## Merge order This PR was stacked on #30879, which has merged. It now targets `main` and has no remaining dependency. ## Summary The axe Linter checks only one rule in Markdown, `heading-order`, and markdownlint `MD001` already covers it for Markdown headings. This PR adds owned checks for the raw HTML in docs Markdown that neither tool sees, so the coverage stays when the licence ends. - `Coder.HeadingOrder` (Vale) flags heading-level skips and counts raw `<hN>` headings, such as the `<h3>` headings `scripts/apidocgen` emits, which `MD001` ignores. - `Coder.EmptyHeading` (Vale) flags headings with no text, in Markdown and raw HTML. - `Coder.LinkName` (Vale) flags links with no text: `[](url)`, links whose only content is an image with empty alt text, and empty `<a href>`. - `docshtmlcheck` now rejects `aria-*`, `role`, `tabindex`, and `lang` attributes, and `iframe`, `object`, `area`, `form`, `input`, `select`, `textarea`, `button`, and `meta` elements. No docs page uses any of them, so the 32 axe HTML rules that check them have nothing to check, and this keeps it that way. - The style guide's decorative-image example changes from ``, which `MD045` rejects, to `<img src="…" alt="">`. No docs page used the old form. - The style guide's checks table gains a row per new check, and the coverage counts move the descriptive-link-text section from planned to tool-checked (22 of 90 rules tool-checked, up from 21 on `main`). ## Design All three Vale rules are `script` rules on `raw` scope, because heading levels, empty headings, and links with no text only show up in the raw source. Raw scope also reaches YAML front matter, fenced code, HTML comments, and inline code, so the scripts skip those themselves. Fence tracking matches the opening marker's character and length, so a four-backtick fence holding a three-backtick one stays closed correctly. The patterns use only capture groups that always participate, because Tengo's `text.re_find` panics on a group that didn't match. `Coder.HeadingOrder` is built to agree with `MD001` without reporting the same skip twice. It tracks the previous heading of any kind and the previous Markdown heading. It stays quiet on a Markdown heading that `MD001` already reports (a skip measured against the previous Markdown heading) and reports the skips `MD001` can't see: a raw HTML heading that skips, and a Markdown heading that skips only because a raw HTML heading sits before it. On a probe file covering each case, the two tools reported disjoint lines. The one remaining divergence is by design: after `## A`, `<h3>B</h3>`, `#### C`, `MD001` reports C (it sees H2 to H4) while this rule sees a clean H2, H3, H4 sequence and stays quiet, so the author still gets exactly one finding. The `docshtmlcheck` guard is a separate `guard.go` that runs on each start tag the existing tokenizer already walks. The elements stay in `allowedElements`, so authors get a message explaining why the element doesn't belong rather than the generic unknown-element one, and a closed `<button>` still balances. Guard findings get their own kinds (`disallowed-element`, `disallowed-attribute`) and their own summary footer. I included `form` alongside the form controls the issue lists, since a form with no controls has no use either. Known gaps, documented in each rule's header and none hit by the current corpus: setext headings, headings inside block quotes or list items, raw HTML headings or links split across lines, reference-style links, and inline code delimited by more than one backtick. There is no Vale rule test harness in the repository, so the hit and non-hit probe files used below live outside the tree. ## QA I ran each Vale rule against a probe file with hits and non-hits, with the repository `.vale.ini` and the pinned Vale 3.7.1. - `Coder.HeadingOrder`: reported the raw `<h4>` after an `##` and the `###` that follows a raw `<h1>` after a `###`. It stayed quiet on the two skips `MD001` reports, on `#` lines in front matter, fenced code, and an HTML comment, and on a clean sequence. markdownlint on the same file reported only the two `MD001` lines, so no line got both. - `Coder.EmptyHeading`: reported `##`, `### ###`, `<h2></h2>`, `<h3> </h3>`, and `<h4> <br/> </h4>`. It stayed quiet on text headings, seven `#` marks, an empty `<h2>` in inline code, and lone `#` lines in front matter, fences, and comments. - `Coder.LinkName`: reported all 7 hit cases (empty, whitespace, `![]()` inside a link, raw empty-alt `<img>` inside a link, empty `<a href>`, `<a href>` around an empty-alt image, `<a href>` holding only ` `). It stayed quiet on all 9 non-hit cases, including a bare decorative image, `<a id>` anchors, inline code, comments, and fenced code. Findings on the current corpus (`docs/`, excluding the exempt style guide): `Coder.HeadingOrder` 0, `Coder.EmptyHeading` 0, `Coder.LinkName` 0, `docshtmlcheck` guard 0. The other Vale findings are unchanged from before the PR. No corpus pages changed. ## Testing - `go test ./scripts/docshtmlcheck/ ./scripts/styleclaims/`: 140 passed. The guard tests were written first and failed before `guard.go` existed. They cover each element, each attribute (including case-insensitive names and attributes wrapped across lines), lookalike names such as `data-role`, code and comment exclusion, the reported line and message, and the `run` exit code and footer. - `make lint/docs-html`: clean. - `make lint/style-claims`: clean, so the checks table, the coverage counts, and the annotations agree with `.vale.ini` and the rule files. - `make lint/emdash`: clean. - `pnpm check-docs` (markdownlint and table formatting): 0 errors across 515 files. - Vale 3.7.1 over `docs/` with `--no-exit`, run directly rather than through `make lint/prose` because the worktree's mise config isn't trusted: no findings from the new rules. ## Upstream Not applicable. These checks are specific to the Coder docs corpus and its style guide, so there's nothing to send to Vale, markdownlint, or goldmark. ## Linear https://linear.app/codercom/issue/DOCS-1318 --- 🤖 Built with AI assistance.
547 lines
18 KiB
Go
547 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"},
|
|
{line: 6, kind: kindDisallowedElement, tag: "iframe", msg: "disallowed"},
|
|
{line: 7, kind: kindDisallowedAttribute, tag: "div", msg: "disallowed"},
|
|
},
|
|
want: issueCounts{html: 1, table: 2, guard: 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)
|
|
}
|
|
}
|
|
}
|