## 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.
545 lines
18 KiB
Go
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)
|
|
}
|
|
}
|
|
}
|