Files
coder/scripts/docshtmlcheck/main_test.go
T
Nick Vigilante 6e51c66a97 docs: give every table header cell text and fail lint on empty ones (#30879)
## Summary

axe reports `empty-table-header` on 116 generated CLI reference pages
and several hand-written pages: a header cell with no text is announced
by screen readers as an unnamed column. This PR gives every table header
cell in `docs/` text, and adds a lint check so empty header cells can't
come back.

## How to review this PR

- `docs/reference/cli/`: 116 files, these all generate identically, so I
would only spot check 2-3 of them and skip the rest
- `docs/*` outside of `docs/reference/cli/`: 6 files, normal review of
these
- `scripts`: 5 files, code review of the Bash and Go files to make sure
we're properly inserting headers into each table

## What changed

**Generator.** `scripts/clidocgen` wrote an empty header row (`| | |`)
over each option's metadata table (Type, Environment, YAML, Default). It
now writes `| Property | Value |`. Subcommand tables already had `Name |
Purpose` and are unchanged. Regenerated with `make
docs/reference/cli/index.md`: 116 files under `docs/reference/cli/`
change. The header rows change, and the body rows of each option table
are re-padded to the wider first column; the content is otherwise
identical. Every option on those 116 pages now shows a visible `Property
| Value` header row above Type, Environment, YAML, and Default, so this
is a visual change on the docs site as well as a screen reader one. The
CLI's own `--help` output doesn't use this template, so it's unchanged.

**Audit logs.** `docs/admin/security/audit-logs.md` already has `Field |
Tracked` headers on `main` (the generator writes them), so there was
nothing to change there; the live-site finding predates that.

**Hand-written tables.**
- `docs/admin/networking/port-forwarding.md`: the CORS matrix had three
empty spanning corner cells. The corner now reads `From user` and `From
workspace` (spanning the three row-header columns, beside the Alice/Bob
and Workspace rows) and `To user`, `To workspace`, `To app` (over the
three row-header columns). The grid is still 3 header rows by 7 columns.
The From cells have `scope="row"` and the other header-row cells
`scope="col"`, so the From labels don't become column headers for the
body's label columns; the body's user, workspace, and app labels are
`<th scope="row">`; and a `<caption>` says columns are the origin and
rows the destination.
- `groups-roles.md`, `airgap.md`, `scale-testing.md`,
`workspace-tags.md`: these four corner cells are already filled by
#30873. The new check would fail CI without them, so this PR carries the
same four lines, byte-identical to #30873 (`Permission`, `Component`,
`Scenario`, `Input`), so whichever PR merges second rebases without
conflict. If #30873 merges first, these hunks drop out.

**New check.** `scripts/docshtmlcheck` (`make lint/docs-html`, part of
`make lint`) now also reports `empty-table-header`. I put it there
because that checker already parses every Markdown file under `docs/`,
generated pages included, with goldmark and tokenizes raw HTML with
`golang.org/x/net/html`, and it already runs in CI. A markdownlint
custom rule would have needed a new JS rule and HTML parsing there.
- Markdown pipe tables: the header row, via goldmark's GFM table
extension.
- Raw HTML tables: every `<th>`, tracked across HTML blocks, with
entities decoded and whitespace trimmed, so `<th></th>`,
`<th>&nbsp;</th>`, and `<th><br></th>` are all reported. Markdown
between the HTML blocks of an open `<th>` counts as its text. Tables in
code blocks are ignored.
- Output: `docs/x.md:29: empty-table-header: header cell 1 has no text
(table's first header "Auditor")`, plus a summary footer.
- The tokenizer loop moved out of `scanNode` into a shared
`tokenizeSegments` helper so both checks use it; `scanNode`'s behavior
is unchanged.
- The style guide's checks table gets one row; the README for the
checker describes the rule.

## Testing

- Tests first: `TestCheckTables` (now 22 cases) and
`TestRunEmptyTableHeader` failed against a stub, then pass. The existing
`docshtmlcheck` tests pass unchanged.
- `go run ./scripts/docshtmlcheck` on `main` reports 1,561 empty header
cells (116 CLI pages, port-forwarding, and the four #30873 tables); on
this branch it reports none.
- `go test ./scripts/docshtmlcheck/ ./scripts/clidocgen/
./scripts/docgenenv/`, golangci-lint on the changed packages, `make
lint/docs-html lint/docs-manifest lint/docs-gen-filter lint/emdash`,
`pnpm run check-docs`, and Vale on the changed hand-written pages all
pass.
- `make gen` couldn't run to completion locally (no `protoc-gen-go`);
CI's gen check covers it. The CLI pages were regenerated with the repo's
own target.

Review feedback applied in cfd29a2160 (entities decoded in Markdown
text, image alt text and autolinks count as text), 709a58f603 (per-kind
counts, finding order, CLI generator note), 8e61ff3afa (CORS matrix
scopes and caption), and b807bcbbc7 and 2871f89bdf (style guide rule
section, `make lint/docs-html` in the checks table, coverage counts).

Linear: DOCS-1308

---

🤖 Built with AI assistance.
2026-10-21 10:58:04 -07:00

545 lines
18 KiB
Go

package main
import (
"io"
"os"
"path/filepath"
"slices"
"strings"
"testing"
)
func TestCheckSource(t *testing.T) {
t.Parallel()
cases := []struct {
name string
src string
// want maps each expected finding kind to the tag it concerns. Order
// independent; the test asserts the multiset of (kind, tag) pairs.
want []finding
}{
{
name: "swallowed placeholder in prose",
src: "Use `--region` set to <region> for the endpoint.\n",
want: []finding{{kind: kindUnknownElement, tag: "region"}},
},
{
name: "placeholder inside inline code is ignored",
src: "Constructs `https://bedrock-runtime.<region>.amazonaws.com`.\n",
want: nil,
},
{
name: "placeholder inside fenced code block is ignored",
src: "```\nendpoint: https://host.<region>.example.com\n```\n",
want: nil,
},
{
name: "placeholder inside indented code block is ignored",
src: " literal <region> here\n",
want: nil,
},
{
name: "double-underscore placeholder in prose",
src: "The tool name has the <server>__ prefix stripped.\n",
want: []finding{{kind: kindUnknownElement, tag: "server"}},
},
{
name: "void element end tag",
src: "First line.</br>\nSecond line.\n",
want: []finding{{kind: kindVoidEndTag, tag: "br"}},
},
{
name: "void element self and start tags are fine",
src: "A<br>B<br/>C <img src=\"x.png\"> D\n",
want: nil,
},
{
name: "capitalized component tag",
src: "<Image src=\"x.png\">\n",
want: []finding{{kind: kindUnknownElement, tag: "image"}},
},
{
name: "balanced kbd inline",
src: "Press <kbd>Ctrl</kbd> to continue.\n",
want: nil,
},
{
name: "balanced children component",
src: "<children></children>\n",
want: nil,
},
{
name: "unbalanced children component",
src: "<children>\n\nsome text\n",
want: []finding{{kind: kindUnclosedTag, tag: "children"}},
},
{
name: "unclosed div leaks wrapper",
src: "<div class=\"tabs\">\n\n## Heading\n\ncontent\n",
want: []finding{{kind: kindUnclosedTag, tag: "div"}},
},
{
name: "balanced div block",
src: "<div class=\"tabs\">\n\n## Heading\n\n</div>\n",
want: nil,
},
{
name: "stray end tag",
src: "text</div>\n",
want: []finding{{kind: kindStrayEndTag, tag: "div"}},
},
{
// Regression guard: a start tag whose attributes wrap across lines
// must be tokenized whole, not torn in half. A per-line tokenizer
// silently dropped this unclosed <div> (exit 0), the exact leaked
// wrapper the linter exists to catch.
name: "unclosed div with attributes wrapped across lines",
src: "<div\n class=\"tabs\">\n\n## Heading\n\ncontent\n",
want: []finding{{kind: kindUnclosedTag, tag: "div"}},
},
{
name: "unknown element with attributes wrapped across lines",
src: "See <Image\n src=\"x.png\"> here.\n",
want: []finding{{kind: kindUnknownElement, tag: "image"}},
},
{
// A valid inline tag wrapped across lines must NOT produce a
// spurious stray-end-tag on the closing tag.
name: "balanced kbd wrapped across lines",
src: "Press <kbd\n class=\"key\">Ctrl</kbd> now.\n",
want: nil,
},
{
// Interleaved nesting: the inner tag is left dangling when the outer
// tag closes, exercising matchEndTag's unclosed-reporting loop.
name: "inner tag unclosed when outer closes",
src: "<div>\n\n<span>\n\n</div>\n",
want: []finding{{kind: kindUnclosedTag, tag: "span"}},
},
{
name: "autolink is not raw html",
src: "See <https://coder.com/docs> for details.\n",
want: nil,
},
{
name: "autolink inside a children raw-html block is ignored",
src: "<children>\n This page is rendered on <https://coder.com/docs/tutorials>.\n</children>\n",
want: nil,
},
{
name: "email autolink is not raw html",
src: "Contact <support@coder.com> for help.\n",
want: nil,
},
{
name: "placeholder inside html comment is ignored",
src: "<!-- TODO: document <region> here -->\n",
want: nil,
},
{
name: "optional end tag li is not flagged as unclosed",
src: "<ul>\n<li>one\n<li>two\n</ul>\n",
want: nil,
},
{
name: "table cells with optional end tags are fine",
src: "<table><tr><td>a<td>b</tr></table>\n",
want: nil,
},
{
name: "clean prose with angle-bracket math is not html",
src: "If a < b and b > c then done.\n",
want: nil,
},
{
// A self-closing flag on a non-void HTML container is ignored by
// the HTML5 parser, so <div class="tabs"/> leaks its wrapper
// exactly like the open spelling and must still be caught.
name: "self-closing div still leaks wrapper",
src: "<div class=\"tabs\"/>\n\n## Heading\n\ncontent\n",
want: []finding{{kind: kindUnclosedTag, tag: "div"}},
},
{
// A renderer component is not an HTML element: MDX honors the
// self-closing form, so <children/> is complete and must not be
// flagged as unclosed, even though <div/> above is.
name: "self-closing children component is balanced",
src: "<children/>\n",
want: nil,
},
{
name: "self-closing children component with space is balanced",
src: "<children />\n",
want: nil,
},
{
// A capitalized tag whose lowercase name is a real element
// (<Table>, <Section>) is a component reference, not that element,
// and is reported rather than passing on the accidental lookup.
name: "capitalized real-element name is a component",
src: "<Table>\n",
want: []finding{{kind: kindUnknownElement, tag: "table"}},
},
{
name: "another capitalized real-element name is a component",
src: "<Section>\n\ncontent\n",
want: []finding{{kind: kindUnknownElement, tag: "section"}},
},
{
// The capitalized closing tag must not add a spurious stray-end-tag;
// the opening tag already produced the finding.
name: "capitalized component with close tag reports once",
src: "<Table>\n\ncontent\n\n</Table>\n",
want: []finding{{kind: kindUnknownElement, tag: "table"}},
},
{
// A colon-shaped placeholder is not a real autolink, so it is
// checked (and reported) inside a raw-HTML block.
name: "colon-shaped placeholder in raw block is caught",
src: "<div>\n<region:id>\n</div>\n",
want: []finding{{kind: kindUnknownElement, tag: "region:id"}},
},
{
name: "at-shaped placeholder without a domain dot is caught",
src: "<div>\n<user@host>\n</div>\n",
want: []finding{{kind: kindUnknownElement, tag: "user@host"}},
},
{
// A real dotted email is a genuine autolink and stays ignored, even
// inside a raw-HTML block.
name: "email autolink inside raw block is ignored",
src: "<div>\n<ops@coder.com>\n</div>\n",
want: nil,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
got := checkSource([]byte(tc.src))
assertFindings(t, tc.want, got)
})
}
}
// TestFindingLine pins the reported line number so the line-tracking machinery
// (lineStarts, lineAt, offset mapping) cannot silently regress to a constant.
func TestFindingLine(t *testing.T) {
t.Parallel()
// 1: "intro", 2: blank, 3: the unclosed <div>.
src := "intro\n\n<div class=\"tabs\">\n\n## Heading\n\ncontent\n"
got := checkSource([]byte(src))
if len(got) != 1 {
t.Fatalf("want exactly 1 finding, got %d: %+v", len(got), got)
}
if got[0].kind != kindUnclosedTag || got[0].tag != "div" {
t.Fatalf("want unclosed <div>, got %+v", got[0])
}
if got[0].line != 3 {
t.Errorf("want unclosed <div> reported on line 3, got line %d", got[0].line)
}
}
// TestFindingLineWrapped pins the source line of a finding that is not the
// first token in its raw-HTML block, so the buffer-offset -> source-line
// mapping (srcOffset/spans) is actually exercised. A mapping that collapsed
// every token to the block start would report line 1 here instead of line 2.
func TestFindingLineWrapped(t *testing.T) {
t.Parallel()
// 1: <section> opens, 2: <Foo> is the finding, 3: </section> closes.
src := "<section>\n<Foo>\n</section>\n"
got := checkSource([]byte(src))
if len(got) != 1 {
t.Fatalf("want exactly 1 finding, got %d: %+v", len(got), got)
}
if got[0].kind != kindUnknownElement || got[0].tag != "foo" {
t.Fatalf("want unknown-element <Foo>, got %+v", got[0])
}
if got[0].line != 2 {
t.Errorf("want <Foo> reported on line 2, got line %d", got[0].line)
}
}
// TestIsGeneratedDoc covers the generated-doc routing branch, which no current
// docs page triggers (every placeholder was fixed at its source), so only a
// test exercises it.
func TestIsGeneratedDoc(t *testing.T) {
t.Parallel()
if !isGeneratedDoc("docs/reference/cli/server.md") {
t.Error("want docs/reference/** treated as generated")
}
if isGeneratedDoc("docs/admin/security/audit-logs.md") {
t.Error("want a hand-written docs path treated as not generated")
}
}
// testAllowlist stands in for allowedUnknownTags so these tests do not depend
// on which pages the real allowlist currently holds.
var testAllowlist = map[string]map[string]bool{
"docs/reference/cli/external.md": {"host": true, "glob": true},
}
func TestFilterAllowed(t *testing.T) {
t.Parallel()
// Allowlisted tags are suppressed on that specific path only.
src := "Format: \"domain=<host> [path=<glob>]\".\n"
raw := checkSource([]byte(src))
if len(raw) != 2 {
t.Fatalf("expected 2 raw findings, got %d: %+v", len(raw), raw)
}
filtered := filterAllowed("docs/reference/cli/external.md", checkSource([]byte(src)), testAllowlist)
if len(filtered) != 0 {
t.Fatalf("expected allowlisted host/glob to be suppressed, got %+v", filtered)
}
// The same tokens are NOT suppressed on any other path.
other := filterAllowed("docs/reference/cli/other.md", checkSource([]byte(src)), testAllowlist)
if len(other) != 2 {
t.Fatalf("expected 2 findings on non-allowlisted path, got %d: %+v", len(other), other)
}
}
// TestFilterAllowedStaleEntry verifies the self-clearing guard: when an
// allowlisted tag no longer appears in its file, the unused entry surfaces as a
// stale-allowlist-entry finding so the dead escape hatch fails the build.
func TestFilterAllowedStaleEntry(t *testing.T) {
t.Parallel()
// Only <host> remains; the <glob> allowlist entry now suppresses nothing.
src := "Format: \"domain=<host>\".\n"
got := filterAllowed("docs/reference/cli/external.md", checkSource([]byte(src)), testAllowlist)
if len(got) != 1 {
t.Fatalf("want exactly 1 stale finding, got %d: %+v", len(got), got)
}
if got[0].kind != kindStaleAllowlist || got[0].tag != "glob" {
t.Fatalf("want stale-allowlist-entry for <glob>, got %+v", got[0])
}
// The fix lives in the linter's allowlist, not at any doc line, so the
// finding carries no line (main reports it against the linter source).
if got[0].line != 0 {
t.Errorf("want stale finding to carry no doc line, got line %d", got[0].line)
}
if !strings.Contains(got[0].msg, "allowedUnknownTags") {
t.Errorf("want stale message to name allowedUnknownTags, got %q", got[0].msg)
}
}
func TestCollectMarkdown(t *testing.T) {
t.Parallel()
dir := t.TempDir()
writeTestFile(t, filepath.Join(dir, "b.md"))
writeTestFile(t, filepath.Join(dir, "a.md"))
writeTestFile(t, filepath.Join(dir, "sub", "c.md"))
writeTestFile(t, filepath.Join(dir, "ignore.txt"))
got, err := collectMarkdown([]string{dir})
if err != nil {
t.Fatalf("collectMarkdown: %v", err)
}
// Expected keys go through canonicalPath just like collectMarkdown's, so
// the assertion holds regardless of the temp dir's absolute location.
want := []string{
canonicalPath(filepath.Join(dir, "a.md")),
canonicalPath(filepath.Join(dir, "b.md")),
canonicalPath(filepath.Join(dir, "sub", "c.md")),
}
slices.Sort(want)
if !slices.Equal(got, want) {
t.Fatalf("want %v (sorted, deduped, .md only), got %v", want, got)
}
}
// TestReportFindings covers the per-file reporting in run: the reported
// location (linter source vs. scanned doc), the generator-source note routing
// per file class, and the returned counts. No current docs page triggers these
// branches, so only a test exercises them.
func TestReportFindings(t *testing.T) {
t.Parallel()
cases := []struct {
name string
path string
findings []finding
wantContains []string
wantAbsent []string
want issueCounts
}{
{
name: "generated page routes to the generator source",
path: "docs/reference/api/users.md",
findings: []finding{{line: 3, kind: kindUnknownElement, tag: "region", msg: "swallowed"}},
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
// come from an external CLI, so the generator-source note is skipped.
name: "allowlisted external page omits the generator note",
path: "docs/reference/cli/external.md",
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`"},
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`"},
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
// with no line, counts as stale (not HTML), and never draws the note.
name: "stale entry reports against the linter source",
path: "docs/reference/cli/external.md",
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:"},
want: issueCounts{stale: 1},
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
var out strings.Builder
counts := reportFindings(tc.path, tc.findings, testAllowlist, &out)
got := out.String()
for _, want := range tc.wantContains {
if !strings.Contains(got, want) {
t.Errorf("output missing %q\ngot:\n%s", want, got)
}
}
for _, absent := range tc.wantAbsent {
if strings.Contains(got, absent) {
t.Errorf("output should not contain %q\ngot:\n%s", absent, got)
}
}
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) {
t.Parallel()
dir := t.TempDir()
clean := filepath.Join(dir, "clean.md")
if err := os.WriteFile(clean, []byte("# ok\n\nPress <kbd>Ctrl</kbd>.\n"), 0o600); err != nil {
t.Fatal(err)
}
if code := run([]string{clean}, io.Discard, io.Discard); code != 0 {
t.Errorf("clean file: want exit 0, got %d", code)
}
bad := filepath.Join(dir, "bad.md")
if err := os.WriteFile(bad, []byte("A <region> placeholder.\n"), 0o600); err != nil {
t.Fatal(err)
}
var stdout, stderr strings.Builder
if code := run([]string{bad}, &stdout, &stderr); code != 1 {
t.Errorf("file with a finding: want exit 1, got %d", code)
}
if !strings.Contains(stdout.String(), "unknown-element") {
t.Errorf("want an unknown-element line, got:\n%s", stdout.String())
}
if !strings.Contains(stderr.String(), "invalid inline HTML issue(s)") {
t.Errorf("want the summary footer, got:\n%s", stderr.String())
}
if code := run([]string{filepath.Join(dir, "does-not-exist")}, io.Discard, io.Discard); code != 2 {
t.Errorf("missing root: want exit 2, got %d", code)
}
}
func writeTestFile(t *testing.T, path string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte("# doc\n"), 0o600); err != nil {
t.Fatal(err)
}
}
func assertFindings(t *testing.T, want, got []finding) {
t.Helper()
type key struct {
kind findingKind
tag string
}
counts := map[key]int{}
for _, f := range got {
counts[key{f.kind, f.tag}]++
}
wantCounts := map[key]int{}
for _, f := range want {
wantCounts[key{f.kind, f.tag}]++
}
for k, n := range wantCounts {
if counts[k] != n {
t.Errorf("want %d finding(s) of {%s %s}, got %d\nall findings: %+v", n, k.kind, k.tag, counts[k], got)
}
}
for k, n := range counts {
if wantCounts[k] == 0 {
t.Errorf("unexpected %d finding(s) of {%s %s}\nall findings: %+v", n, k.kind, k.tag, got)
}
}
}