Files
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

248 lines
7.4 KiB
Go

package main
import (
"cmp"
"fmt"
"slices"
"strings"
"github.com/yuin/goldmark"
"github.com/yuin/goldmark/ast"
"github.com/yuin/goldmark/extension"
east "github.com/yuin/goldmark/extension/ast"
"github.com/yuin/goldmark/text"
"golang.org/x/net/html"
)
// kindEmptyTableHeader is a table header cell with no text. Screen readers
// announce such a column or row without a name, and axe reports it as
// empty-table-header.
const kindEmptyTableHeader findingKind = "empty-table-header"
// headerCell is one header cell of a table: the line it starts on and its
// text with whitespace collapsed.
type headerCell struct {
line int
text string
}
// checkTables returns a finding for every table header cell with no text, in
// both GFM pipe tables (the header row) and raw HTML tables (any <th>). Text is
// whatever a reader would hear: entities such as &nbsp; are decoded and
// whitespace is trimmed, so <th>&nbsp;</th> and <th><br></th> count as empty,
// while an image's alt text, an autolink, and code count as text. Tables
// inside code blocks and code spans are ignored.
func checkTables(src []byte) []finding {
doc := goldmark.New(goldmark.WithExtensions(extension.Table)).Parser().Parse(text.NewReader(src))
t := &tableChecker{c: checker{src: src, lineStarts: lineStarts(src)}}
preorder(doc, func(n ast.Node) bool {
switch node := n.(type) {
case *east.TableHeader:
t.pipeHeader(node)
return false
case *ast.HTMLBlock:
segs := segmentsOf(node.Lines())
if node.HasClosure() {
segs = append(segs, node.ClosureLine)
}
t.scanHTML(segs)
case *ast.RawHTML:
t.scanHTML(segmentsOf(node.Segments))
case *ast.Text:
// Markdown between the raw-HTML blocks of an open <th>, such as
// <th>\n\n**Feature**\n\n</th>, is that cell's text.
t.addText(textValue(node, src))
case *ast.String:
t.addText(string(node.Value))
case *ast.AutoLink:
t.addText(string(node.Label(src)))
case *ast.FencedCodeBlock, *ast.CodeBlock:
for _, seg := range segmentsOf(n.Lines()) {
t.addText(string(seg.Value(src)))
}
}
return true
})
// A table left unclosed at end of file still reports its empty headers.
for len(t.tables) > 0 {
t.closeTable()
}
slices.SortStableFunc(t.findings, func(a, b finding) int {
return cmp.Compare(a.line, b.line)
})
return t.findings
}
type tableChecker struct {
// c supplies the source and line lookup; its tag-balance state is unused.
c checker
findings []finding
// tables is the stack of open HTML tables (they can nest); each entry
// holds that table's <th> cells so far.
tables [][]headerCell
// inTH reports whether the innermost table has an open <th>, whose text
// accumulates in the last cell of that table.
inTH bool
}
// pipeHeader checks the header row of a GFM pipe table.
func (t *tableChecker) pipeHeader(header *east.TableHeader) {
line := t.c.lineAt(header.Pos())
var cells []headerCell
for cell := header.FirstChild(); cell != nil; cell = cell.NextSibling() {
cells = append(cells, headerCell{line: line, text: collapse(inlineText(cell, t.c.src))})
}
t.report(cells)
}
// inlineText returns the text a reader would hear from a pipe table cell.
func inlineText(n ast.Node, src []byte) string {
var b []byte
preorder(n, func(n ast.Node) bool {
switch node := n.(type) {
case *ast.Text:
b = append(b, textValue(node, src)...)
case *ast.String:
b = append(b, node.Value...)
case *ast.AutoLink:
b = append(b, node.Label(src)...)
case *ast.RawHTML:
tokenizeSegments(src, segmentsOf(node.Segments), func(int) int { return 0 }, func(z *html.Tokenizer, tt html.TokenType, raw []byte, _ int) {
if (tt == html.StartTagToken || tt == html.SelfClosingTagToken) && strings.EqualFold(rawTagName(raw), "img") {
b = append(b, ' ')
b = append(b, imgAlt(z)...)
}
})
}
return true
})
return string(b)
}
// textValue returns the text of a Markdown text node with entities decoded.
// goldmark keeps &nbsp; as literal source text until it renders, so without
// decoding a cell holding only &nbsp; would look non-empty. Text in a code
// span renders literally, so `&nbsp;` there stays six visible characters.
func textValue(n *ast.Text, src []byte) string {
v := string(n.Segment.Value(src))
if _, ok := n.Parent().(*ast.CodeSpan); ok {
return v
}
return html.UnescapeString(v)
}
// imgAlt returns the alt attribute of the img start tag z is on, which a
// screen reader announces as the image's text. It must run after rawTagName
// has read the raw token, because the tokenizer lowercases attribute names
// in place.
func imgAlt(z *html.Tokenizer) string {
for {
key, val, more := z.TagAttr()
if string(key) == "alt" {
return string(val)
}
if !more {
return ""
}
}
}
// preorder visits n and its descendants in document order. visit returns
// false to skip a node's children. Unlike ast.Walk it has no error path,
// because none of these visitors can fail.
func preorder(n ast.Node, visit func(ast.Node) bool) {
if !visit(n) {
return
}
for c := n.FirstChild(); c != nil; c = c.NextSibling() {
preorder(c, visit)
}
}
// scanHTML tracks <table> and <th> through one raw-HTML node. State persists
// across nodes, so a table split over several HTML blocks is checked as one.
func (t *tableChecker) scanHTML(segs []text.Segment) {
tokenizeSegments(t.c.src, segs, t.c.lineAt, func(z *html.Tokenizer, tt html.TokenType, raw []byte, line int) {
switch tt {
case html.TextToken:
// Text decodes entities, so &nbsp; arrives as U+00A0.
t.addText(string(z.Text()))
case html.StartTagToken, html.SelfClosingTagToken:
switch strings.ToLower(rawTagName(raw)) {
case "img":
t.addText(imgAlt(z))
case "table":
t.inTH = false
t.tables = append(t.tables, nil)
case "th":
if len(t.tables) > 0 {
top := len(t.tables) - 1
t.tables[top] = append(t.tables[top], headerCell{line: line})
t.inTH = true
}
case "td", "tr":
t.inTH = false
}
case html.EndTagToken:
switch strings.ToLower(rawTagName(raw)) {
case "table":
t.closeTable()
case "th", "tr", "thead", "tbody", "tfoot":
t.inTH = false
}
}
})
}
// addText appends s to the open <th>, if any.
func (t *tableChecker) addText(s string) {
if !t.inTH || len(t.tables) == 0 {
return
}
cells := t.tables[len(t.tables)-1]
last := &cells[len(cells)-1]
last.text = collapse(last.text + " " + s)
}
// closeTable pops the innermost HTML table and reports its empty headers.
func (t *tableChecker) closeTable() {
t.inTH = false
top := len(t.tables) - 1
cells := t.tables[top]
t.tables = t.tables[:top]
t.report(cells)
}
// report adds a finding for each empty cell, naming the table by its first
// non-empty header so the author can find it on a page with many tables.
func (t *tableChecker) report(cells []headerCell) {
first := "(none)"
for _, c := range cells {
if c.text != "" {
first = fmt.Sprintf("%q", c.text)
break
}
}
for i, c := range cells {
if c.text != "" {
continue
}
t.findings = append(t.findings, finding{
line: c.line,
kind: kindEmptyTableHeader,
tag: "th",
msg: fmt.Sprintf("header cell %d has no text (table's first header %s)", i+1, first),
})
}
}
// collapse trims s and folds internal whitespace into single spaces.
// strings.Fields splits on unicode.IsSpace, which includes the U+00A0 that
// &nbsp; decodes to, so a cell holding only &nbsp; collapses to "".
func collapse(s string) string {
return strings.Join(strings.Fields(s), " ")
}