## 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> </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 incfd29a2160(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), andb807bcbbc7and2871f89bdf(style guide rule section, `make lint/docs-html` in the checks table, coverage counts). Linear: DOCS-1308 --- 🤖 Built with AI assistance.
176 lines
5.6 KiB
Go
176 lines
5.6 KiB
Go
package main
|
|
|
|
import (
|
|
"os"
|
|
"path/filepath"
|
|
"strings"
|
|
"testing"
|
|
)
|
|
|
|
func TestCheckTables(t *testing.T) {
|
|
t.Parallel()
|
|
|
|
type want struct {
|
|
line int
|
|
first string
|
|
}
|
|
cases := []struct {
|
|
name string
|
|
src string
|
|
want []want
|
|
}{
|
|
{
|
|
name: "pipe table with an empty header row",
|
|
src: "Intro.\n\n| | |\n| --- | --- |\n| Type | `string` |\n",
|
|
want: []want{{line: 3}, {line: 3}},
|
|
},
|
|
{
|
|
name: "pipe table with an empty corner cell",
|
|
src: "| | Auditor | Owner |\n| --- | --- | --- |\n| Read | yes | yes |\n",
|
|
want: []want{{line: 1, first: "Auditor"}},
|
|
},
|
|
{
|
|
name: "pipe table with header text in every cell",
|
|
src: "| Property | Value |\n| --- | --- |\n| Type | `string` |\n",
|
|
},
|
|
{
|
|
name: "header text that is only inline code or a link counts",
|
|
src: "| `name` | [Docs](./x.md) |\n| --- | --- |\n| a | b |\n",
|
|
},
|
|
{
|
|
name: "pipe table inside a fenced code block is ignored",
|
|
src: "```md\n| | |\n| --- | --- |\n| a | b |\n```\n",
|
|
},
|
|
{
|
|
name: "html table with an empty th",
|
|
src: "<table>\n<tr><th></th><th>Coder Desktop</th></tr>\n<tr><td>a</td><td>b</td></tr>\n</table>\n",
|
|
want: []want{{line: 2, first: "Coder Desktop"}},
|
|
},
|
|
{
|
|
name: "html th holding only a non-breaking space",
|
|
src: "<table>\n<tr>\n<th> </th>\n<th scope=\"col\">Name</th>\n</tr>\n</table>\n",
|
|
want: []want{{line: 3, first: "Name"}},
|
|
},
|
|
{
|
|
name: "html th holding only a line break",
|
|
src: "<table><tr><th><br></th><th>Name</th></tr></table>\n",
|
|
want: []want{{line: 1, first: "Name"}},
|
|
},
|
|
{
|
|
name: "html th with nested markup and text",
|
|
src: "<table>\n<tr><th scope=\"col\"><strong>Feature</strong></th><th>Name</th></tr>\n</table>\n",
|
|
},
|
|
{
|
|
name: "html th whose text is Markdown between html blocks",
|
|
src: "<table>\n<tr>\n<th>\n\n**Feature**\n\n</th>\n</tr>\n</table>\n",
|
|
},
|
|
{
|
|
name: "html table inside a fenced code block is ignored",
|
|
src: "```html\n<table><tr><th></th></tr></table>\n```\n",
|
|
},
|
|
{
|
|
name: "pipe header holding only a non-breaking space entity",
|
|
src: "| | A |\n| --- | --- |\n| a | b |\n",
|
|
want: []want{{line: 1, first: "A"}},
|
|
},
|
|
{
|
|
name: "pipe header holding only a numeric non-breaking space entity",
|
|
src: "|   | A |\n| --- | --- |\n| a | b |\n",
|
|
want: []want{{line: 1, first: "A"}},
|
|
},
|
|
{
|
|
name: "html th whose Markdown between blocks is only a non-breaking space",
|
|
src: "<table>\n<tr>\n<th>\n\n \n\n</th>\n<th>Name</th>\n</tr>\n</table>\n",
|
|
want: []want{{line: 3, first: "Name"}},
|
|
},
|
|
{
|
|
// A code span renders its content literally, so ` ` is the
|
|
// six visible characters, not a space.
|
|
name: "an entity inside a code span is text",
|
|
src: "| ` ` | A |\n| --- | --- |\n| a | b |\n",
|
|
},
|
|
{
|
|
name: "html th holding only an image with alt text",
|
|
src: "<table><tr><th><img alt=\"Logo\" src=\"x.png\"></th></tr></table>\n",
|
|
},
|
|
{
|
|
name: "html th holding only an image with empty alt text",
|
|
src: "<table><tr><th><img alt=\"\" src=\"x.png\"></th><th>Name</th></tr></table>\n",
|
|
want: []want{{line: 1, first: "Name"}},
|
|
},
|
|
{
|
|
name: "pipe header holding only a raw image with alt text",
|
|
src: "| <img alt=\"Logo\" src=\"x.png\"> | A |\n| --- | --- |\n| a | b |\n",
|
|
},
|
|
{
|
|
name: "pipe header holding only a raw image with empty alt text",
|
|
src: "| <img alt=\"\" src=\"x.png\"> | A |\n| --- | --- |\n| a | b |\n",
|
|
want: []want{{line: 1, first: "A"}},
|
|
},
|
|
{
|
|
name: "html th whose Markdown between blocks is an autolink",
|
|
src: "<table>\n<tr>\n<th>\n\n<https://coder.com>\n\n</th>\n</tr>\n</table>\n",
|
|
},
|
|
{
|
|
name: "html th whose Markdown between blocks is a fenced code block",
|
|
src: "<table>\n<tr>\n<th>\n\n```sh\ncoder login\n```\n\n</th>\n</tr>\n</table>\n",
|
|
},
|
|
{
|
|
name: "every header empty names no first header",
|
|
src: "<table><tr><th></th></tr></table>\n",
|
|
want: []want{{line: 1}},
|
|
},
|
|
}
|
|
|
|
for _, tc := range cases {
|
|
t.Run(tc.name, func(t *testing.T) {
|
|
t.Parallel()
|
|
got := checkTables([]byte(tc.src))
|
|
if len(got) != len(tc.want) {
|
|
t.Fatalf("want %d findings, got %d: %+v", len(tc.want), len(got), got)
|
|
}
|
|
for i, w := range tc.want {
|
|
f := got[i]
|
|
if f.kind != kindEmptyTableHeader {
|
|
t.Errorf("finding %d: want kind %s, got %s", i, kindEmptyTableHeader, f.kind)
|
|
}
|
|
if f.line != w.line {
|
|
t.Errorf("finding %d: want line %d, got %d", i, w.line, f.line)
|
|
}
|
|
firstHeader := "(none)"
|
|
if w.first != "" {
|
|
firstHeader = `"` + w.first + `"`
|
|
}
|
|
if !strings.Contains(f.msg, "first header "+firstHeader) {
|
|
t.Errorf("finding %d: want message naming first header %s, got %q", i, firstHeader, f.msg)
|
|
}
|
|
}
|
|
})
|
|
}
|
|
}
|
|
|
|
func TestRunEmptyTableHeader(t *testing.T) {
|
|
t.Parallel()
|
|
|
|
dir := t.TempDir()
|
|
bad := filepath.Join(dir, "bad.md")
|
|
src := "# Page\n\n| | Auditor |\n| --- | --- |\n| Read | yes |\n"
|
|
if err := os.WriteFile(bad, []byte(src), 0o600); err != nil {
|
|
t.Fatal(err)
|
|
}
|
|
var stdout, stderr strings.Builder
|
|
if code := run([]string{bad}, &stdout, &stderr); code != 1 {
|
|
t.Errorf("want exit 1, got %d", code)
|
|
}
|
|
wantLine := canonicalPath(bad) + `:3: empty-table-header: header cell 1 has no text (table's first header "Auditor")`
|
|
if !strings.Contains(stdout.String(), wantLine) {
|
|
t.Errorf("want %q in output, got:\n%s", wantLine, stdout.String())
|
|
}
|
|
if !strings.Contains(stderr.String(), "empty table header cell(s)") {
|
|
t.Errorf("want the table summary footer, got:\n%s", stderr.String())
|
|
}
|
|
if strings.Contains(stderr.String(), "invalid inline HTML issue(s)") {
|
|
t.Errorf("table findings should not print the inline HTML footer, got:\n%s", stderr.String())
|
|
}
|
|
}
|