## 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.
162 lines
4.8 KiB
Go
162 lines
4.8 KiB
Go
package main
|
|
|
|
import (
|
|
"os"
|
|
"path/filepath"
|
|
"strings"
|
|
"testing"
|
|
)
|
|
|
|
func TestCheckSourceDisallowed(t *testing.T) {
|
|
t.Parallel()
|
|
|
|
cases := []struct {
|
|
name string
|
|
src string
|
|
want []finding
|
|
}{
|
|
{
|
|
name: "iframe embed",
|
|
src: "<iframe src=\"https://www.youtube.com/embed/x\"></iframe>\n",
|
|
want: []finding{{kind: kindDisallowedElement, tag: "iframe"}},
|
|
},
|
|
{
|
|
name: "object embed",
|
|
src: "<object data=\"diagram.svg\"></object>\n",
|
|
want: []finding{{kind: kindDisallowedElement, tag: "object"}},
|
|
},
|
|
{
|
|
name: "image map area",
|
|
src: "<map name=\"m\"><area href=\"#a\" coords=\"0,0,1,1\"></map>\n",
|
|
want: []finding{{kind: kindDisallowedElement, tag: "area"}},
|
|
},
|
|
{
|
|
name: "form and its controls",
|
|
src: "<form>\n<input type=\"text\">\n<select><option>a</option></select>\n<textarea></textarea>\n<button>Go</button>\n</form>\n",
|
|
want: []finding{
|
|
{kind: kindDisallowedElement, tag: "form"},
|
|
{kind: kindDisallowedElement, tag: "input"},
|
|
{kind: kindDisallowedElement, tag: "select"},
|
|
{kind: kindDisallowedElement, tag: "textarea"},
|
|
{kind: kindDisallowedElement, tag: "button"},
|
|
},
|
|
},
|
|
{
|
|
name: "meta refresh",
|
|
src: "<meta http-equiv=\"refresh\" content=\"0; url=/docs\">\n",
|
|
want: []finding{{kind: kindDisallowedElement, tag: "meta"}},
|
|
},
|
|
{
|
|
// The element is reported, and its end tag still balances, so a
|
|
// closed <button> adds no stray-end-tag or unclosed-tag finding.
|
|
name: "inline button reports once",
|
|
src: "Select <button>Save</button> to finish.\n",
|
|
want: []finding{{kind: kindDisallowedElement, tag: "button"}},
|
|
},
|
|
{
|
|
name: "aria attribute",
|
|
src: "<span aria-label=\"Close\">x</span>\n",
|
|
want: []finding{{kind: kindDisallowedAttribute, tag: "span"}},
|
|
},
|
|
{
|
|
name: "role attribute",
|
|
src: "<div role=\"button\">\n\ncontent\n\n</div>\n",
|
|
want: []finding{{kind: kindDisallowedAttribute, tag: "div"}},
|
|
},
|
|
{
|
|
name: "tabindex attribute",
|
|
src: "<a href=\"#x\" tabindex=\"1\">jump</a>\n",
|
|
want: []finding{{kind: kindDisallowedAttribute, tag: "a"}},
|
|
},
|
|
{
|
|
name: "lang attribute",
|
|
src: "<span lang=\"fr\">bonjour</span>\n",
|
|
want: []finding{{kind: kindDisallowedAttribute, tag: "span"}},
|
|
},
|
|
{
|
|
name: "attribute names are case-insensitive",
|
|
src: "<span ARIA-HIDDEN=\"true\" Role=\"img\">x</span>\n",
|
|
want: []finding{
|
|
{kind: kindDisallowedAttribute, tag: "span"},
|
|
{kind: kindDisallowedAttribute, tag: "span"},
|
|
},
|
|
},
|
|
{
|
|
name: "attribute wrapped across lines",
|
|
src: "<div\n class=\"tabs\"\n role=\"tablist\">\n\ncontent\n\n</div>\n",
|
|
want: []finding{{kind: kindDisallowedAttribute, tag: "div"}},
|
|
},
|
|
{
|
|
name: "allowed attributes pass",
|
|
src: "<a href=\"x\" id=\"y\" class=\"z\" title=\"t\" target=\"_blank\">x</a> <img src=\"a.png\" alt=\"\" width=\"10\">\n",
|
|
want: nil,
|
|
},
|
|
{
|
|
// data-role, data-aria-label, and language only resemble guarded names.
|
|
name: "lookalike attribute names pass",
|
|
src: "<span data-role=\"x\" data-aria-label=\"y\" language=\"z\">x</span>\n",
|
|
want: nil,
|
|
},
|
|
{
|
|
name: "elements in fenced code are ignored",
|
|
src: "```html\n<iframe src=\"x\"></iframe>\n<div role=\"button\"></div>\n```\n",
|
|
want: nil,
|
|
},
|
|
{
|
|
name: "elements in inline code are ignored",
|
|
src: "Avoid `<button aria-label=\"x\">` in docs.\n",
|
|
want: nil,
|
|
},
|
|
{
|
|
name: "elements in html comments are ignored",
|
|
src: "<!-- <iframe src=\"x\" role=\"y\"></iframe> -->\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)
|
|
})
|
|
}
|
|
}
|
|
|
|
func TestDisallowedFindingMessage(t *testing.T) {
|
|
t.Parallel()
|
|
|
|
got := checkSource([]byte("# Page\n\n<span aria-label=\"x\">y</span>\n"))
|
|
if len(got) != 1 {
|
|
t.Fatalf("want 1 finding, got %+v", got)
|
|
}
|
|
if got[0].line != 3 {
|
|
t.Errorf("want line 3, got %d", got[0].line)
|
|
}
|
|
if !strings.Contains(got[0].msg, "aria-label") {
|
|
t.Errorf("message should name the attribute, got %q", got[0].msg)
|
|
}
|
|
}
|
|
|
|
func TestRunDisallowed(t *testing.T) {
|
|
t.Parallel()
|
|
|
|
bad := filepath.Join(t.TempDir(), "bad.md")
|
|
if err := os.WriteFile(bad, []byte("# Page\n\n<iframe src=\"x\" title=\"Demo\"></iframe>\n"), 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)
|
|
}
|
|
if !strings.Contains(stdout.String(), canonicalPath(bad)+":3: disallowed-element:") {
|
|
t.Errorf("want a disallowed-element line, got:\n%s", stdout.String())
|
|
}
|
|
if !strings.Contains(stderr.String(), "disallowed element(s) or attribute(s)") {
|
|
t.Errorf("want the guard summary footer, got:\n%s", stderr.String())
|
|
}
|
|
if strings.Contains(stderr.String(), "invalid inline HTML issue(s)") {
|
|
t.Errorf("guard findings should not print the inline HTML footer, got:\n%s", stderr.String())
|
|
}
|
|
}
|