refactor(scripts/docshtmlcheck): count findings per kind and route CLI notes to the template

run derived the HTML count as reportFindings' total minus the table
findings, which only worked because reportFindings lumped table findings in
with HTML ones, and its doc comment no longer said what it returned.
reportFindings now returns a count per kind.

Sorting the merged findings by line also moved line-0 stale-allowlist
findings ahead of the content findings, where they used to come last; they
sort last again.

On a CLI reference page the generated-page note sent authors to codersdk
and swagger, but a CLI page comes from --help text and
scripts/clidocgen/command.tpl, where an empty option-table header would be
fixed. The note now names those for CLI pages.

Assisted-by: AI
This commit is contained in:
Nick Vigilante committed 2026-10-16 15:25:43 -04:00
1 parent cfd29a2160
commit 709a58f603
2 files changed
+119 -45

No files matched your search

+66 -34
View File
@@ -200,58 +200,78 @@ func run(roots []string, stdout, stderr io.Writer) int {
return 2
}
var htmlIssues, tableIssues, staleIssues int
var total issueCounts
for _, path := range files {
src, err := os.ReadFile(path)
if err != nil {
_, _ = fmt.Fprintf(stderr, "docshtmlcheck: %v\n", err)
return 2
}
tables := checkTables(src)
findings := append(filterAllowed(path, checkSource(src), allowedUnknownTags), tables...)
slices.SortStableFunc(findings, func(a, b finding) int {
return cmp.Compare(a.line, b.line)
})
h, s := reportFindings(path, findings, allowedUnknownTags, stdout)
htmlIssues += h - len(tables)
tableIssues += len(tables)
staleIssues += s
findings := append(filterAllowed(path, checkSource(src), allowedUnknownTags), checkTables(src)...)
sortFindings(findings)
total = total.add(reportFindings(path, findings, allowedUnknownTags, stdout))
}
if htmlIssues > 0 {
if total.html > 0 {
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d invalid inline HTML issue(s).\n"+
"Wrap angle-bracket placeholders in backticks so they render as inline code\n"+
"(see contributing/documentation.md), fix void-element end tags\n"+
"like </br>, use registered components for custom tags, and close container tags.\n", htmlIssues)
"like </br>, use registered components for custom tags, and close container tags.\n", total.html)
}
if tableIssues > 0 {
if total.table > 0 {
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d empty table header cell(s).\n"+
"Give every header cell text that names its column or row, including the\n"+
"top-left corner cell of a matrix; screen readers announce an empty one\n"+
"with no name.\n", tableIssues)
"with no name.\n", total.table)
}
if staleIssues > 0 {
if total.stale > 0 {
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d stale allowlist entry(ies); "+
"remove them from allowedUnknownTags in %s.\n", staleIssues, docshtmlcheckSource)
"remove them from allowedUnknownTags in %s.\n", total.stale, docshtmlcheckSource)
}
if htmlIssues+tableIssues+staleIssues > 0 {
if total.html+total.table+total.stale > 0 {
return 1
}
return 0
}
// reportFindings writes one file's findings to out and returns the count of
// invalid-HTML findings and stale-allowlist findings. A stale-allowlist finding
// is reported against the linter source (its fix lives in allowedUnknownTags,
// not the scanned doc) and with no line. When the file has a real content
// finding, is generated, and is not allowlisted, a trailing note points the
// author at the generator source instead of the throwaway output.
// issueCounts holds the number of findings of each class, which run reports
// under separate summary footers.
type issueCounts struct {
html, table, stale int
}
func (c issueCounts) add(o issueCounts) issueCounts {
return issueCounts{html: c.html + o.html, table: c.table + o.table, stale: c.stale + o.stale}
}
// sortFindings orders findings by line. A finding with no line belongs to the
// linter's allowlist rather than to the scanned doc, so it sorts after every
// content finding.
func sortFindings(findings []finding) {
slices.SortStableFunc(findings, func(a, b finding) int {
if (a.line == 0) != (b.line == 0) {
if a.line == 0 {
return 1
}
return -1
}
return cmp.Compare(a.line, b.line)
})
}
// reportFindings writes one file's findings to out and returns how many it
// wrote of each class: invalid HTML, empty table headers, and stale allowlist
// entries. A stale-allowlist finding is reported against the linter source
// (its fix lives in allowedUnknownTags, not the scanned doc) and with no line.
// When the file has a content finding, is generated, and is not allowlisted, a
// trailing note points the author at the generator source instead of the
// throwaway output.
//
// The allowlist skip is file-scoped: a genuinely new invalid tag on an
// allowlisted generated page is still reported, but without the
// generator-source hint, because that page's source is external.
func reportFindings(path string, findings []finding, allowlist map[string]map[string]bool, out io.Writer) (htmlIssues, staleIssues int) {
realFinding := false
func reportFindings(path string, findings []finding, allowlist map[string]map[string]bool, out io.Writer) issueCounts {
var counts issueCounts
for _, f := range findings {
loc := path
if f.kind == kindStaleAllowlist {
@@ -264,19 +284,31 @@ func reportFindings(path string, findings []finding, allowlist map[string]map[st
} else {
_, _ = fmt.Fprintf(out, "%s: %s: %s\n", loc, f.kind, f.msg)
}
if f.kind == kindStaleAllowlist {
staleIssues++
} else {
htmlIssues++
realFinding = true
switch f.kind {
case kindStaleAllowlist:
counts.stale++
case kindEmptyTableHeader:
counts.table++
default:
counts.html++
}
}
if realFinding && isGeneratedDoc(path) && allowlist[canonicalPath(path)] == nil {
if counts.html+counts.table > 0 && isGeneratedDoc(path) && allowlist[canonicalPath(path)] == nil {
_, _ = fmt.Fprintf(out, "%s: note: this page is generated by `make gen`; fix the source "+
"(codersdk/*.go doc comments, CLI --help text, or swagger annotations) and "+
"regenerate; edits to this file will not persist\n", path)
"(%s) and regenerate; edits to this file will not persist\n", path, generatorSource(path))
}
return htmlIssues, staleIssues
return counts
}
// generatorSource names where a generated page's content comes from. A CLI
// page is rendered from the command's --help text through a page template, so
// a structural problem such as an empty option-table header lives in the
// template.
func generatorSource(path string) string {
if strings.HasPrefix(canonicalPath(path), "docs/reference/cli/") {
return "CLI --help text, or the page template scripts/clidocgen/command.tpl"
}
return "codersdk/*.go doc comments, CLI --help text, or swagger annotations"
}
// collectMarkdown expands the given roots (files or directories) into a sorted
+53 -11
View File
@@ -369,15 +369,25 @@ func TestReportFindings(t *testing.T) {
findings []finding
wantContains []string
wantAbsent []string
wantHTML int
wantStale int
want issueCounts
}{
{
name: "generated page routes to the generator source",
path: "docs/reference/cli/server.md",
path: "docs/reference/api/users.md",
findings: []finding{{line: 3, kind: kindUnknownElement, tag: "region", msg: "swallowed"}},
wantContains: []string{"docs/reference/cli/server.md:3: unknown-element: swallowed", "generated by `make gen`"},
wantHTML: 1,
wantContains: []string{"docs/reference/api/users.md:3: unknown-element: swallowed", "generated by `make gen`", "swagger annotations"},
want: issueCounts{html: 1},
},
{
// CLI pages come from --help text and the page template, not
// codersdk or swagger; an empty option-table header comes from the
// template.
name: "generated CLI page routes to the CLI page template",
path: "docs/reference/cli/server.md",
findings: []finding{{line: 3, kind: kindEmptyTableHeader, tag: "th", msg: "empty"}},
wantContains: []string{"docs/reference/cli/server.md:3: empty-table-header: empty", "scripts/clidocgen/command.tpl"},
wantAbsent: []string{"swagger"},
want: issueCounts{table: 1},
},
{
// An allowlisted external page is generated, but its placeholders
@@ -387,14 +397,24 @@ func TestReportFindings(t *testing.T) {
findings: []finding{{line: 5, kind: kindUnknownElement, tag: "foo", msg: "swallowed"}},
wantContains: []string{"docs/reference/cli/external.md:5: unknown-element: swallowed"},
wantAbsent: []string{"generated by `make gen`"},
wantHTML: 1,
want: issueCounts{html: 1},
},
{
name: "hand-written page omits the generator note",
path: "docs/admin/security/audit-logs.md",
findings: []finding{{line: 2, kind: kindUnknownElement, tag: "foo", msg: "swallowed"}},
wantAbsent: []string{"generated by `make gen`"},
wantHTML: 1,
want: issueCounts{html: 1},
},
{
name: "each kind is counted on its own",
path: "docs/admin/security/audit-logs.md",
findings: []finding{
{line: 2, kind: kindUnknownElement, tag: "foo", msg: "swallowed"},
{line: 4, kind: kindEmptyTableHeader, tag: "th", msg: "empty"},
{line: 5, kind: kindEmptyTableHeader, tag: "th", msg: "empty"},
},
want: issueCounts{html: 1, table: 2},
},
{
// A stale-allowlist finding is reported against the linter source
@@ -404,7 +424,7 @@ func TestReportFindings(t *testing.T) {
findings: []finding{{kind: kindStaleAllowlist, tag: "glob", msg: "remove it from allowedUnknownTags"}},
wantContains: []string{docshtmlcheckSource + ": stale-allowlist-entry: remove it from allowedUnknownTags"},
wantAbsent: []string{"generated by `make gen`", "external.md:"},
wantStale: 1,
want: issueCounts{stale: 1},
},
}
@@ -412,7 +432,7 @@ func TestReportFindings(t *testing.T) {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
var out strings.Builder
html, stale := reportFindings(tc.path, tc.findings, testAllowlist, &out)
counts := reportFindings(tc.path, tc.findings, testAllowlist, &out)
got := out.String()
for _, want := range tc.wantContains {
if !strings.Contains(got, want) {
@@ -424,13 +444,35 @@ func TestReportFindings(t *testing.T) {
t.Errorf("output should not contain %q\ngot:\n%s", absent, got)
}
}
if html != tc.wantHTML || stale != tc.wantStale {
t.Errorf("want (html=%d stale=%d), got (html=%d stale=%d)", tc.wantHTML, tc.wantStale, html, stale)
if counts != tc.want {
t.Errorf("want %+v, got %+v", tc.want, counts)
}
})
}
}
// TestSortFindings checks that findings sort by line and that line-0
// findings, which belong to the linter's allowlist rather than to a line of
// the scanned doc, stay after the content findings.
func TestSortFindings(t *testing.T) {
t.Parallel()
findings := []finding{
{line: 0, tag: "stale"},
{line: 9, tag: "b"},
{line: 3, tag: "a"},
{line: 9, tag: "c"},
}
sortFindings(findings)
var got []string
for _, f := range findings {
got = append(got, f.tag)
}
if want := []string{"a", "b", "c", "stale"}; !slices.Equal(got, want) {
t.Errorf("want order %v, got %v", want, got)
}
}
// TestRun drives run end to end through temp files and asserts the exit-code
// contract: 0 clean, 1 findings, 2 unreadable root.
func TestRun(t *testing.T) {