Files
skillshare/internal/audit/markdown.go
T
Willie 9dbcd925d8 feat(audit): honor findings accepted with --force via --respect-accepted (#872)
* feat(audit): honor findings accepted with --force via --respect-accepted

install and update --force record the findings a user accepted in
audit_accepted, but audit ignored that record. A skill installed with
--force therefore kept failing `skillshare audit` in CI with no way to
let the accepted findings pass (#869).

audit --respect-accepted marks those findings as acknowledged. They stay
in every output (JSON acknowledged: true, a text/TUI note, "(accepted
earlier)" in Markdown, SARIF external suppressions), but they are counted
in summary.accepted instead of their severity and no longer fail the
audit. Without the flag nothing changes, so existing CI gates keep their
behavior. A changed file or snippet produces a new key and blocks again.

Tracked repositories record acceptances at the repo root with paths
relative to it, so ApplyAcceptedFindings walks up from each skill to
match them. The install, update and edit gates use the same function and
now honor repo-wide acceptances for skills inside tracked repos too.

The dashboard always honors accepted findings: the Audit page mutes them
and counts them apart, the skill Audit tab collapses them, and the
Dashboard attention card no longer lists a skill whose only blocking
findings were accepted. The CLI JSON summary and the server summary share
Result.CountOpenBySeverity so both count accepted findings the same way.
The oplog records the accepted count and the log views show it.

* fix(audit): match acceptances when a single file is scanned

A single-file scan names its findings by the file's base name, but the
ancestor lookup used the file's whole path as the prefix, so it hashed
SKILL.md/SKILL.md instead of the recorded SKILL.md. Auditing a skill file
directly with --respect-accepted, and auditing agents inside a tracked
repository in the CLI or the dashboard, still failed on unchanged
accepted findings. For a file target the prefix is now the file's own
directory.
2026-11-12 11:15:44 +08:00

316 lines
9.2 KiB
Go

package audit
import (
"fmt"
"sort"
"strings"
)
// MarkdownOptions carries summary statistics for the Markdown report header.
type MarkdownOptions struct {
Scanned int
Passed int
Warning int
Failed int
Critical int
High int
Medium int
Low int
Info int
Accepted int // accepted earlier with --force; left out of the severity counts
BinaryFiles int
SkippedFiles int
OversizedFiles int
ScanErrors int
RiskScore int
RiskLabel string
Threshold string
Mode string
MinSeverity string // display-only, normalized severity; empty shows all
SourceWarnings []string // source links the scan did not follow
Incomplete bool // a source link could not be read, so its skills went unscanned
AvgAnalyzability float64
Profile string
ByCategory map[string]int
}
// ToMarkdown converts audit results into a Markdown report suitable for
// GitHub Issues, PRs, or documentation.
func ToMarkdown(results []*Result, opts MarkdownOptions) string {
var b strings.Builder
writeHeader(&b, opts)
writeSummaryTable(&b, opts)
writeCoverageTable(&b, results)
writeSourceLinkWarnings(&b, opts)
if opts.MinSeverity != "" {
visible, hidden := DisplayCounts(results, opts.MinSeverity)
fmt.Fprintf(&b, "\nFindings: %d visible, %d hidden (minimum %s).\n", visible, hidden, opts.MinSeverity)
}
// Partition results into failed, warning, and clean.
var failed, warned, clean []*Result
for _, r := range results {
switch {
case r.IsBlocked:
failed = append(failed, r)
case len(DisplayFindings(r.Findings, opts.MinSeverity)) > 0:
warned = append(warned, r)
case len(r.Findings) == 0:
clean = append(clean, r)
}
}
// Sort each group alphabetically by skill name.
sortResults := func(rs []*Result) {
sort.Slice(rs, func(i, j int) bool {
return rs[i].SkillName < rs[j].SkillName
})
}
sortResults(failed)
sortResults(warned)
sortResults(clean)
// Findings section: failed first, then warned.
hasFindings := len(failed)+len(warned) > 0
if hasFindings {
b.WriteString("\n## Findings\n")
for _, r := range failed {
writeSkillSection(&b, r, true, opts.MinSeverity)
}
for _, r := range warned {
writeSkillSection(&b, r, false, opts.MinSeverity)
}
}
// Clean skills section.
if len(clean) > 0 {
fmt.Fprintf(&b, "\n## Clean Skills (%d)\n\n", len(clean))
names := make([]string, len(clean))
for i, r := range clean {
names[i] = "`" + r.SkillName + "`"
}
b.WriteString(strings.Join(names, ", "))
b.WriteString("\n")
}
return b.String()
}
func writeHeader(b *strings.Builder, opts MarkdownOptions) {
b.WriteString("# Skillshare Audit Report\n\n")
fmt.Fprintf(b, "- **Scanned**: %d skill(s)\n", opts.Scanned)
fmt.Fprintf(b, "- **Mode**: %s\n", opts.Mode)
fmt.Fprintf(b, "- **Threshold**: %s\n", opts.Threshold)
if opts.Profile != "" && opts.Profile != "default" {
fmt.Fprintf(b, "- **Profile**: %s\n", opts.Profile)
}
}
func writeSummaryTable(b *strings.Builder, opts MarkdownOptions) {
b.WriteString("\n## Summary\n\n")
b.WriteString("| Metric | Value |\n")
b.WriteString("|--------|-------|\n")
fmt.Fprintf(b, "| Passed | %d |\n", opts.Passed)
fmt.Fprintf(b, "| Warning | %d |\n", opts.Warning)
fmt.Fprintf(b, "| Failed | %d |\n", opts.Failed)
fmt.Fprintf(b, "| Severity | C:%d H:%d M:%d L:%d I:%d |\n",
opts.Critical, opts.High, opts.Medium, opts.Low, opts.Info)
if opts.Accepted > 0 {
fmt.Fprintf(b, "| Accepted | %d |\n", opts.Accepted)
}
if threatsLine := formatCategoryBreakdownPlain(opts.ByCategory); threatsLine != "" {
fmt.Fprintf(b, "| Threats | %s |\n", threatsLine)
}
fmt.Fprintf(b, "| Risk | %s (%d/100) |\n",
strings.ToUpper(opts.RiskLabel), opts.RiskScore)
fmt.Fprintf(b, "| Analyzability | %.0f%% avg |\n",
opts.AvgAnalyzability*100)
if opts.SkippedFiles > 0 {
fmt.Fprintf(b, "| Skipped files | %d (%d binary, %d oversized) |\n", opts.SkippedFiles, opts.BinaryFiles, opts.OversizedFiles)
}
if opts.ScanErrors > 0 {
fmt.Fprintf(b, "| Scan Errors | %d |\n", opts.ScanErrors)
}
}
// writeCoverageTable keeps partial coverage visible even for clean resources.
func writeCoverageTable(b *strings.Builder, results []*Result) {
var rows []*Result
for _, r := range results {
if r.SkippedFiles > 0 {
rows = append(rows, r)
}
}
if len(rows) == 0 {
return
}
sort.Slice(rows, func(i, j int) bool { return rows[i].SkillName < rows[j].SkillName })
b.WriteString("\n## File coverage by resource\n\n| Resource | Skipped | Binary | Oversized |\n|---|---:|---:|---:|\n")
for _, r := range rows {
fmt.Fprintf(b, "| %s | %d | %d | %d |\n", escapeMarkdownTable(r.SkillName), r.SkippedFiles, r.BinaryFiles, r.OversizedFiles)
}
}
// writeSourceLinkWarnings keeps an incomplete scan visible: the tables and the
// display floor describe only what was scanned.
func writeSourceLinkWarnings(b *strings.Builder, opts MarkdownOptions) {
if len(opts.SourceWarnings) == 0 {
return
}
b.WriteString("\n## Source links not followed\n\n")
if opts.Incomplete {
b.WriteString("**Incomplete scan:** a source link could not be read, so the skills behind it were not scanned.\n\n")
}
for _, w := range opts.SourceWarnings {
fmt.Fprintf(b, "- %s\n", w)
}
}
// findingLocation formats a file:line location string for a finding.
func findingLocation(f Finding) string {
if f.File == "" {
return ""
}
if f.Line > 0 {
return fmt.Sprintf("%s:%d", f.File, f.Line)
}
return f.File
}
func writeSkillSection(b *strings.Builder, r *Result, blocked bool, minSeverity string) {
symbol := "!"
if blocked {
symbol = "✗"
}
fmt.Fprintf(b, "\n### %s %s\n\n", symbol, r.SkillName)
// Block decision line.
maxSev := r.MaxSeverity()
if maxSev == "" {
maxSev = "NONE"
}
threshold := r.Threshold
if threshold == "" {
threshold = DefaultThreshold()
}
if blocked {
fmt.Fprintf(b, "> **BLOCKED** — max severity %s >= threshold %s\n\n", maxSev, threshold)
} else {
fmt.Fprintf(b, "> **ALLOWED** — max severity %s < threshold %s\n\n", maxSev, threshold)
}
findings := DisplayFindings(r.Findings, minSeverity)
if minSeverity != "" {
fmt.Fprintf(b, "Findings: %d visible, %d hidden.\n\n", len(findings), len(r.Findings)-len(findings))
}
// Findings table — also track whether any snippets exist.
if len(findings) > 0 {
b.WriteString("| # | Rule ID | Severity | Pattern | Analyzer | Category | Message | Location |\n")
b.WriteString("|---|---------|----------|---------|----------|----------|---------|----------|\n")
}
hasSnippets := false
for i, f := range findings {
if f.Snippet != "" {
hasSnippets = true
}
ruleID := f.RuleID
if ruleID == "" {
ruleID = "-"
}
analyzer := f.Analyzer
if analyzer == "" {
analyzer = "-"
}
category := f.Category
if category == "" {
category = "-"
}
fmt.Fprintf(b, "| %d | %s | %s | %s | %s | %s | %s | %s |\n",
i+1,
escapeMarkdownTable(ruleID),
escapeMarkdownTable(f.Severity),
escapeMarkdownTable(f.Pattern),
escapeMarkdownTable(analyzer),
escapeMarkdownTable(category),
escapeMarkdownTable(markdownMessage(f)),
escapeMarkdownTable(findingLocation(f)),
)
}
// Snippets in collapsible details.
if hasSnippets {
b.WriteString("\n<details>\n<summary>Snippets</summary>\n\n")
for _, f := range findings {
if f.Snippet == "" {
continue
}
fmt.Fprintf(b, "**%s** — `%s`\n\n", findingLocation(f), f.Pattern)
// Use 4-space indented code block to avoid backtick conflicts.
b.WriteString(" " + escapeSnippetLine(f.Snippet) + "\n\n")
}
b.WriteString("</details>\n")
}
// Metadata bullets.
fmt.Fprintf(b, "\n- Risk: %s (%d/100)\n",
strings.ToUpper(r.RiskLabel), r.RiskScore)
fmt.Fprintf(b, "- Analyzability: %.0f%%\n", r.Analyzability*100)
if !r.TierProfile.IsEmpty() {
fmt.Fprintf(b, "- Commands: %s\n", r.TierProfile.String())
}
b.WriteString("\n---\n")
}
// markdownMessage is a finding's message, marked when it was accepted earlier.
func markdownMessage(f Finding) string {
if f.Acknowledged {
return f.ExplainedMessage() + " (accepted earlier)"
}
return f.ExplainedMessage()
}
// escapeSnippetLine replaces newlines so that indented code blocks stay single-line.
func escapeSnippetLine(s string) string {
s = strings.ReplaceAll(s, "\n", " ")
s = strings.ReplaceAll(s, "\r", "")
return s
}
// escapeMarkdownTable replaces characters that would break a Markdown table cell.
func escapeMarkdownTable(s string) string {
return strings.ReplaceAll(escapeSnippetLine(s), "|", "\\|")
}
// formatCategoryBreakdownPlain formats a category count map as "cat:N cat:N ..."
// sorted by count descending, using full names. Returns "" if map is empty.
func formatCategoryBreakdownPlain(cats map[string]int) string {
if len(cats) == 0 {
return ""
}
type catCount struct {
name string
count int
}
sorted := make([]catCount, 0, len(cats))
for name, count := range cats {
sorted = append(sorted, catCount{name, count})
}
sort.Slice(sorted, func(i, j int) bool {
if sorted[i].count != sorted[j].count {
return sorted[i].count > sorted[j].count
}
return sorted[i].name < sorted[j].name
})
parts := make([]string, len(sorted))
for i, cc := range sorted {
parts[i] = fmt.Sprintf("%s:%d", cc.name, cc.count)
}
return strings.Join(parts, " ")
}