Files
coder/scripts/styleclaims
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
..

styleclaims

styleclaims fails CI when the Coder documentation style guide claims a prose rule is enforced by tooling that isn't actually enabled. It runs as make lint/style-claims (part of make lint and make lint-light).

Why it exists

Each rule section in docs/.style/style-guide/ ends with an annotation naming what enforces it. Those annotations drifted from the configuration: 8 cited third-party Google.* rules that the repo-root .vale.ini never loads, and 2 cited Coder.* rules that have no YAML under docs/.style/styles/Coder/. A reader who trusts an annotation believes a rule is checked when it isn't, which is worse than an unenforced rule the guide is honest about.

What it catches

  • A Coder.* rule cited as active with no rule file. The rule doesn't exist; the citation needs (planned).
  • A third-party rule cited as active. .vale.ini sets BasedOnStyles = Coder, and third-party rules return one per PR after their corpus is clean, so any Google.*, alex.*, or write-good.* citation is planned until that happens.
  • A rule with no style guide section. A rule file exists but no annotation cites it as active, so a rule landed without the section the per-rule PR pattern requires.
  • Checks-table drift. A severity that disagrees with the rule file's level:, a row for a rule that doesn't exist, a missing row for a rule that does, or a scope cell that doesn't read the way .vale.ini configures the rule. The scope check compares the rendered text, not the set of paths, so a cell that says "and" where the config says "except" is caught along with a cell that omits or invents a path.
  • A rule cited as enforcement while .vale.ini leaves it off. A rule file can exist and still run nowhere.
  • Coverage-table drift. A per-section or total count that disagrees with the annotations.
  • A rule heading with no footer. A ## or ### heading that states a rule but carries no annotation, so the coverage table can't count it.

The checker verifies a Coder.* citation against the rule files, so a typo is caught. A third-party citation is verified only against the loaded styles: those rule files are vendored rather than kept in this repository, so the guarantee is weaker on that side.

The annotation format it relies on

An annotation starts with one of Enforced, Documentation-only, Adapted, or Vale rule, and runs to the line ending in *.

A citation counts as a claim only when its sentence contains enforc or names a Vale rule. A sentence that mentions a rule without claiming it runs, such as the note explaining why Google.Passive stays out of the package, is ignored.

Mark each planned citation individually. (planned) after the citation, or Planned Vale rule before it, both work:

*Enforced by `Coder.BrandNames`.*
*Enforced by `Coder.LearnMore` (planned).*
*Enforced by `Google.Gender` (planned) and `Google.GenderBias` (planned).*
*Enforced by `scripts/check_emdash.sh` (existing CI script) and `Coder.EmDash` (planned).*
*Documentation-only. No Vale rule.*

A trailing clause such as (both planned) that covers several citations at once isn't understood; mark each one.

A marker that appears before any citation introduces the list that follows, as in "Planned Vale rules" followed by names, and it carries until a later clause re-asserts enforcement. So "Planned A, enforced by B." reads A planned and B active.

Coverage counts

Each annotation is classified once for the coverage table, so the table counts rule sections rather than linter rule names. One annotation footer is one rule section: a heading without a footer, such as an example, a navigation heading, or the out-of-scope Color contrast section, isn't a rule of the guide and isn't counted.

The checker also reports a ## or ### heading that states a rule but carries no footer, so a rule can't drop out of the table by never being annotated. A footer belongs to the nearest heading above it, and a heading that has sub-headings is treated as covered by them, so a parent rule whose footer sits after a scoping sub-heading isn't flagged. A heading is also exempt when it is the Learn more navigation section, or when it carries a note that opens with Out of scope or Not a rule, which is how a section that organizes a page without stating a rule declares itself. Headings deeper than ### are detail inside a section, not rules. A Markdown file that has no footers and no coverage row, such as editor-setup.md, isn't a rule section and isn't scanned.

  • Documentation-only: the annotation declares the section Documentation-only. This wins over everything else, so a section that only cross-references a rule another section owns counts under that other section and no rule is counted twice. The match is case-sensitive; a lowercase "documentation-only" describes part of a section, not the section.
  • Tool-checked: cites as active an enabled Coder rule, a third-party rule whose style .vale.ini loads, markdownlint, an MD### rule, scripts/check_emdash.sh, or scripts/docshtmlcheck. A Coder rule that exists but is disabled everywhere doesn't count: it checks no file.
  • Planned: cites only planned checkers.

Usage

go run ./scripts/styleclaims

It takes no arguments and runs from the repository root. Findings print as file:line: message, or as file: message when the problem is the file as a whole, such as a rule with no style guide section or a missing coverage row. Any finding exits 1.

The set of style guide sections comes from the directory, not from a list in the source. A Markdown file is a rule section when it carries at least one enforcement footer, or when the coverage table gives it a row, so a new subpage is validated as soon as either is true.