## 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.
708 lines
26 KiB
Go
708 lines
26 KiB
Go
// Command docshtmlcheck fails when Markdown files under docs/ contain invalid
|
|
// inline HTML that the documentation site's HTML renderer silently drops or
|
|
// mangles.
|
|
//
|
|
// It exists to prevent regressions of two classes of bug that were fixed by a
|
|
// manual audit of the docs:
|
|
//
|
|
// - Swallowed angle-bracket placeholders. An unwrapped placeholder such as
|
|
// <region> or <server>__ is parsed as an unknown HTML tag and stripped
|
|
// from the rendered page, so readers see broken text. Placeholders must be
|
|
// wrapped in backticks (see contributing/documentation.md).
|
|
// This also covers CLI --help strings and Swagger annotations, whose text
|
|
// is generated into docs/reference/**.
|
|
// - Structurally invalid or unregistered HTML: end tags for void elements
|
|
// (</br>); tag names outside the standard HTML5 element set; capitalized
|
|
// tags such as <Image> or <Table>, which the docs renderer reads as
|
|
// component references and drops when unregistered (only <children> is
|
|
// registered); and unclosed container tags (a <div class="tabs"> that is
|
|
// never closed and leaks its wrapper over the rest of the page).
|
|
//
|
|
// It also fails on table header cells with no text, in Markdown pipe tables and
|
|
// raw HTML tables alike, because screen readers announce them as unnamed
|
|
// columns (see tables.go), and on elements and attributes that docs pages have
|
|
// no use for: ARIA, role, tabindex, and lang attributes, and iframe, object,
|
|
// area, form control, and meta elements (see guard.go).
|
|
//
|
|
// Detection is Markdown-aware: the file is parsed with goldmark and only raw
|
|
// HTML nodes are inspected, so angle brackets inside fenced code blocks, inline
|
|
// code spans, HTML comments, and <https://...> or <user@host> autolinks are
|
|
// ignored.
|
|
//
|
|
// Known limitations (accepted; no docs page hits either today): a placeholder
|
|
// whose name is itself a real element (<input>, <time>) is indistinguishable
|
|
// from intended markup and passes; and the interior of a raw-text element
|
|
// (<script>, <style>) is one opaque text token to the tokenizer, so a tag
|
|
// nested inside is not scanned, though an unclosed <script>/<style> is still
|
|
// caught.
|
|
//
|
|
// Usage:
|
|
//
|
|
// docshtmlcheck [path ...]
|
|
//
|
|
// With no arguments it scans docs/. Arguments may be files or directories.
|
|
package main
|
|
|
|
import (
|
|
"bytes"
|
|
"cmp"
|
|
"fmt"
|
|
"io"
|
|
"io/fs"
|
|
"maps"
|
|
"os"
|
|
"path/filepath"
|
|
"regexp"
|
|
"slices"
|
|
"sort"
|
|
"strings"
|
|
|
|
"github.com/yuin/goldmark"
|
|
"github.com/yuin/goldmark/ast"
|
|
"github.com/yuin/goldmark/text"
|
|
"golang.org/x/net/html"
|
|
)
|
|
|
|
// voidElements are HTML elements that never have an end tag. An end tag for any
|
|
// of these (e.g. </br>) is invalid.
|
|
var voidElements = map[string]bool{
|
|
"area": true, "base": true, "br": true, "col": true, "embed": true,
|
|
"hr": true, "img": true, "input": true, "link": true, "meta": true,
|
|
"param": true, "source": true, "track": true, "wbr": true,
|
|
}
|
|
|
|
// allowedElements is the set of tag names permitted in docs Markdown: the
|
|
// standard HTML5 element set plus "children", the one intentional renderer
|
|
// component (a child-page card grid with no HTML equivalent). Lookups are
|
|
// lowercase; a tag whose raw name is capitalized is treated as a component
|
|
// reference and reported by scanNode before this set is consulted, so only
|
|
// lowercase element names belong here. Any name outside the set is treated as
|
|
// a swallowed placeholder or an unregistered component and is reported. Inline
|
|
// SVG and MathML are intentionally out of scope (no docs page uses them); add
|
|
// the element here if that changes.
|
|
//
|
|
// Maintenance: this set is hand-maintained to mirror the tags the docs
|
|
// renderer actually accepts. It is not generated from the renderer, so a
|
|
// renderer change that adds or removes an accepted tag is not reflected here
|
|
// automatically and the two can drift until this map is updated by hand. Keep
|
|
// them in sync whenever the renderer's accepted set changes.
|
|
//
|
|
// Known gap: a placeholder whose name is itself a real element (<input>,
|
|
// <output>, <time>) is indistinguishable from intended markup and passes.
|
|
// Such placeholders almost always live in fenced code blocks, which are
|
|
// ignored, so the gap is narrow in practice.
|
|
var allowedElements = map[string]bool{
|
|
// Standard HTML5 elements.
|
|
"a": true, "abbr": true, "address": true, "area": true, "article": true,
|
|
"aside": true, "audio": true, "b": true, "base": true, "bdi": true,
|
|
"bdo": true, "blockquote": true, "body": true, "br": true, "button": true,
|
|
"canvas": true, "caption": true, "cite": true, "code": true, "col": true,
|
|
"colgroup": true, "data": true, "datalist": true, "dd": true, "del": true,
|
|
"details": true, "dfn": true, "dialog": true, "div": true, "dl": true,
|
|
"dt": true, "em": true, "embed": true, "fieldset": true, "figcaption": true,
|
|
"figure": true, "footer": true, "form": true, "h1": true, "h2": true,
|
|
"h3": true, "h4": true, "h5": true, "h6": true, "head": true, "header": true,
|
|
"hgroup": true, "hr": true, "html": true, "i": true, "iframe": true,
|
|
"img": true, "input": true, "ins": true, "kbd": true, "label": true,
|
|
"legend": true, "li": true, "link": true, "main": true, "map": true,
|
|
"mark": true, "menu": true, "meta": true, "meter": true, "nav": true,
|
|
"noscript": true, "object": true, "ol": true, "optgroup": true,
|
|
"option": true, "output": true, "p": true, "param": true, "picture": true,
|
|
"pre": true, "progress": true, "q": true, "rp": true, "rt": true,
|
|
"ruby": true, "s": true, "samp": true, "script": true, "search": true,
|
|
"section": true, "select": true, "slot": true, "small": true,
|
|
"source": true, "span": true, "strong": true, "style": true, "sub": true,
|
|
"summary": true, "sup": true, "table": true, "tbody": true, "td": true,
|
|
"template": true, "textarea": true, "tfoot": true, "th": true,
|
|
"thead": true, "time": true, "title": true, "tr": true, "track": true,
|
|
"u": true, "ul": true, "var": true, "video": true, "wbr": true,
|
|
|
|
// Intentional docs renderer component. Also listed in rendererComponents,
|
|
// which drives the self-closing balance rule in scanNode.
|
|
"children": true,
|
|
}
|
|
|
|
// rendererComponents are the non-HTML tags the docs renderer accepts as MDX
|
|
// components rather than standard HTML elements; they also appear in
|
|
// allowedElements. MDX honors the self-closing form on a component, so
|
|
// <children /> is complete and is not balance-tracked. A self-closing HTML
|
|
// container such as <div/> is different: the HTML5 parser ignores the flag and
|
|
// leaves it open, so it stays tracked and is still caught as an unclosed
|
|
// wrapper.
|
|
var rendererComponents = map[string]bool{
|
|
"children": true,
|
|
}
|
|
|
|
// optionalEndTags are elements whose end tag is optional in the HTML5 parsing
|
|
// algorithm (a following sibling or the parent's end implicitly closes them).
|
|
// Requiring them to be explicitly balanced would produce false positives on
|
|
// valid HTML, so they are excluded from the unclosed/mismatch balance check.
|
|
// They are still subject to the void-end-tag and unknown-element checks.
|
|
var optionalEndTags = map[string]bool{
|
|
"li": true, "dd": true, "dt": true, "p": true, "option": true,
|
|
"optgroup": true, "td": true, "th": true, "tr": true, "thead": true,
|
|
"tbody": true, "tfoot": true, "caption": true, "colgroup": true,
|
|
"rt": true, "rp": true,
|
|
}
|
|
|
|
// allowedUnknownTags suppresses specific unknown-element findings on specific
|
|
// files. This is a deliberately narrow escape hatch for placeholders whose
|
|
// source is outside this repository and therefore cannot be fixed by a source
|
|
// edit here.
|
|
//
|
|
// The escape hatch is self-clearing: filterAllowed emits a stale-allowlist-entry
|
|
// finding (failing the build) if an allowlisted tag no longer appears in its
|
|
// file, so a dead entry cannot silently mask a future regression of the same
|
|
// tag on that page. The guard is per-tag on a scanned file; an entry whose
|
|
// file is deleted outright is never rescanned and lingers as harmless dead
|
|
// config (a missing file yields no findings, so nothing hides behind it).
|
|
//
|
|
// Keys are canonical file paths; values are the set of allowed tag names.
|
|
var allowedUnknownTags = map[string]map[string]bool{}
|
|
|
|
// docshtmlcheckSource is where allowlist-maintenance findings are reported: the
|
|
// fix for a stale entry lives in this file's allowedUnknownTags, not in the
|
|
// scanned doc, so pointing at the doc would send the reader to the wrong file.
|
|
const docshtmlcheckSource = "scripts/docshtmlcheck/main.go"
|
|
|
|
type findingKind string
|
|
|
|
const (
|
|
kindUnknownElement findingKind = "unknown-element"
|
|
kindVoidEndTag findingKind = "void-end-tag"
|
|
kindUnclosedTag findingKind = "unclosed-tag"
|
|
kindStrayEndTag findingKind = "stray-end-tag"
|
|
kindStaleAllowlist findingKind = "stale-allowlist-entry"
|
|
)
|
|
|
|
type finding struct {
|
|
line int
|
|
kind findingKind
|
|
tag string
|
|
msg string
|
|
}
|
|
|
|
func main() {
|
|
roots := os.Args[1:]
|
|
if len(roots) == 0 {
|
|
roots = []string{"docs"}
|
|
}
|
|
os.Exit(run(roots, os.Stdout, os.Stderr))
|
|
}
|
|
|
|
// run scans roots, writes per-finding lines to stdout and the summary and
|
|
// errors to stderr, and returns the process exit code (0 clean, 1 findings,
|
|
// 2 I/O error). It is separated from main so tests can drive it with buffers
|
|
// and assert the reported locations, the generator-source note routing, and
|
|
// the summary footers.
|
|
func run(roots []string, stdout, stderr io.Writer) int {
|
|
files, err := collectMarkdown(roots)
|
|
if err != nil {
|
|
_, _ = fmt.Fprintf(stderr, "docshtmlcheck: %v\n", err)
|
|
return 2
|
|
}
|
|
|
|
var total issueCounts
|
|
for _, path := range files {
|
|
src, err := os.ReadFile(path)
|
|
if err != nil {
|
|
_, _ = fmt.Fprintf(stderr, "docshtmlcheck: %v\n", err)
|
|
return 2
|
|
}
|
|
findings := append(filterAllowed(path, checkSource(src), allowedUnknownTags), checkTables(src)...)
|
|
sortFindings(findings)
|
|
total = total.add(reportFindings(path, findings, allowedUnknownTags, stdout))
|
|
}
|
|
|
|
if total.html > 0 {
|
|
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d invalid inline HTML issue(s).\n"+
|
|
"Wrap angle-bracket placeholders in backticks so they render as inline code\n"+
|
|
"(see contributing/documentation.md), fix void-element end tags\n"+
|
|
"like </br>, use registered components for custom tags, and close container tags.\n", total.html)
|
|
}
|
|
if total.table > 0 {
|
|
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d empty table header cell(s).\n"+
|
|
"Give every header cell text that names its column or row, including the\n"+
|
|
"top-left corner cell of a matrix; screen readers announce an empty one\n"+
|
|
"with no name.\n", total.table)
|
|
}
|
|
if total.guard > 0 {
|
|
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d disallowed element(s) or attribute(s).\n"+
|
|
"Docs pages don't use ARIA, role, tabindex, or lang attributes, or iframe, object,\n"+
|
|
"area, form control, or meta elements. Each brings accessibility requirements\n"+
|
|
"that no docs check verifies; write the content in Markdown instead.\n", total.guard)
|
|
}
|
|
if total.stale > 0 {
|
|
_, _ = fmt.Fprintf(stderr, "\ndocshtmlcheck: found %d stale allowlist entry(ies); "+
|
|
"remove them from allowedUnknownTags in %s.\n", total.stale, docshtmlcheckSource)
|
|
}
|
|
if total.html+total.table+total.guard+total.stale > 0 {
|
|
return 1
|
|
}
|
|
return 0
|
|
}
|
|
|
|
// issueCounts holds the number of findings of each class, which run reports
|
|
// under separate summary footers.
|
|
type issueCounts struct {
|
|
html, table, guard, stale int
|
|
}
|
|
|
|
func (c issueCounts) add(o issueCounts) issueCounts {
|
|
return issueCounts{html: c.html + o.html, table: c.table + o.table, guard: c.guard + o.guard, stale: c.stale + o.stale}
|
|
}
|
|
|
|
// sortFindings orders findings by line. A finding with no line belongs to the
|
|
// linter's allowlist rather than to the scanned doc, so it sorts after every
|
|
// content finding.
|
|
func sortFindings(findings []finding) {
|
|
slices.SortStableFunc(findings, func(a, b finding) int {
|
|
if (a.line == 0) != (b.line == 0) {
|
|
if a.line == 0 {
|
|
return 1
|
|
}
|
|
return -1
|
|
}
|
|
return cmp.Compare(a.line, b.line)
|
|
})
|
|
}
|
|
|
|
// reportFindings writes one file's findings to out and returns how many it
|
|
// wrote of each class: invalid HTML, empty table headers, disallowed elements
|
|
// and attributes, and stale allowlist entries. A stale-allowlist finding is reported against the linter source
|
|
// (its fix lives in allowedUnknownTags, not the scanned doc) and with no line.
|
|
// When the file has a content finding, is generated, and is not allowlisted, a
|
|
// trailing note points the author at the generator source instead of the
|
|
// throwaway output.
|
|
//
|
|
// The allowlist skip is file-scoped: a genuinely new invalid tag on an
|
|
// allowlisted generated page is still reported, but without the
|
|
// generator-source hint, because that page's source is external.
|
|
func reportFindings(path string, findings []finding, allowlist map[string]map[string]bool, out io.Writer) issueCounts {
|
|
var counts issueCounts
|
|
for _, f := range findings {
|
|
loc := path
|
|
if f.kind == kindStaleAllowlist {
|
|
// The fix is in this tool's allowlist, not the scanned doc, so
|
|
// report the linter source rather than a misleading docs:1.
|
|
loc = docshtmlcheckSource
|
|
}
|
|
if f.line > 0 {
|
|
_, _ = fmt.Fprintf(out, "%s:%d: %s: %s\n", loc, f.line, f.kind, f.msg)
|
|
} else {
|
|
_, _ = fmt.Fprintf(out, "%s: %s: %s\n", loc, f.kind, f.msg)
|
|
}
|
|
switch f.kind {
|
|
case kindStaleAllowlist:
|
|
counts.stale++
|
|
case kindEmptyTableHeader:
|
|
counts.table++
|
|
case kindDisallowedElement, kindDisallowedAttribute:
|
|
counts.guard++
|
|
default:
|
|
counts.html++
|
|
}
|
|
}
|
|
if counts.html+counts.table+counts.guard > 0 && isGeneratedDoc(path) && allowlist[canonicalPath(path)] == nil {
|
|
_, _ = fmt.Fprintf(out, "%s: note: this page is generated by `make gen`; fix the source "+
|
|
"(%s) and regenerate; edits to this file will not persist\n", path, generatorSource(path))
|
|
}
|
|
return counts
|
|
}
|
|
|
|
// generatorSource names where a generated page's content comes from. A CLI
|
|
// page is rendered from the command's --help text through a page template, so
|
|
// a structural problem such as an empty option-table header lives in the
|
|
// template.
|
|
func generatorSource(path string) string {
|
|
if strings.HasPrefix(canonicalPath(path), "docs/reference/cli/") {
|
|
return "CLI --help text, or the page template scripts/clidocgen/command.tpl"
|
|
}
|
|
return "codersdk/*.go doc comments, CLI --help text, or swagger annotations"
|
|
}
|
|
|
|
// collectMarkdown expands the given roots (files or directories) into a sorted
|
|
// list of unique .md files in canonical (repo-relative, slash) form.
|
|
func collectMarkdown(roots []string) ([]string, error) {
|
|
seen := map[string]bool{}
|
|
for _, root := range roots {
|
|
info, err := os.Stat(root)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if !info.IsDir() {
|
|
if strings.HasSuffix(root, ".md") {
|
|
seen[canonicalPath(root)] = true
|
|
}
|
|
continue
|
|
}
|
|
err = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
|
|
if err != nil {
|
|
return err
|
|
}
|
|
if !d.IsDir() && strings.HasSuffix(path, ".md") {
|
|
seen[canonicalPath(path)] = true
|
|
}
|
|
return nil
|
|
})
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
return slices.Sorted(maps.Keys(seen)), nil
|
|
}
|
|
|
|
// canonicalPath normalizes a path to a clean, slash-separated form, made
|
|
// relative to the working directory when absolute. Running the linter from the
|
|
// repo root (as CI and `make lint/docs-html` do) yields repo-relative keys such
|
|
// as docs/reference/cli/agent-firewall.md regardless of whether the caller
|
|
// passed a relative, ./-prefixed, or absolute path, so allowlist lookups and
|
|
// reported locations stay consistent.
|
|
func canonicalPath(p string) string {
|
|
p = filepath.Clean(p)
|
|
if filepath.IsAbs(p) {
|
|
if wd, err := os.Getwd(); err == nil {
|
|
if rel, err := filepath.Rel(wd, p); err == nil {
|
|
p = rel
|
|
}
|
|
}
|
|
}
|
|
return filepath.ToSlash(p)
|
|
}
|
|
|
|
// isGeneratedDoc reports whether a docs path is produced by `make gen` rather
|
|
// than hand-written, so findings can route the author to the generator source.
|
|
func isGeneratedDoc(path string) bool {
|
|
return strings.HasPrefix(canonicalPath(path), "docs/reference/")
|
|
}
|
|
|
|
// filterAllowed drops unknown-element findings suppressed by allowlist (see
|
|
// allowedUnknownTags) for the file. It also reports any allowlist entry that
|
|
// suppressed nothing, so a stale escape hatch fails the build instead of
|
|
// silently masking a future regression of the same tag on that page.
|
|
func filterAllowed(path string, findings []finding, allowlist map[string]map[string]bool) []finding {
|
|
allowed := allowlist[canonicalPath(path)]
|
|
if allowed == nil {
|
|
return findings
|
|
}
|
|
out := make([]finding, 0, len(findings))
|
|
used := make(map[string]bool, len(allowed))
|
|
for _, f := range findings {
|
|
if f.kind == kindUnknownElement && allowed[f.tag] {
|
|
used[f.tag] = true
|
|
continue
|
|
}
|
|
out = append(out, f)
|
|
}
|
|
stale := make([]string, 0, len(allowed))
|
|
for tag := range allowed {
|
|
if !used[tag] {
|
|
stale = append(stale, tag)
|
|
}
|
|
}
|
|
slices.Sort(stale)
|
|
for _, tag := range stale {
|
|
// No line: the fix is in allowedUnknownTags, not at any line of the
|
|
// scanned doc. main reports these against the linter source.
|
|
out = append(out, finding{
|
|
kind: kindStaleAllowlist,
|
|
tag: tag,
|
|
msg: fmt.Sprintf("allowlist entry <%s> for %s no longer suppresses anything; "+
|
|
"remove it from allowedUnknownTags", tag, canonicalPath(path)),
|
|
})
|
|
}
|
|
return out
|
|
}
|
|
|
|
// checkSource parses Markdown and returns findings for invalid inline HTML. It
|
|
// inspects only raw HTML nodes, so angle brackets inside code spans, fenced
|
|
// code blocks, HTML comments, and autolinks are ignored.
|
|
func checkSource(src []byte) []finding {
|
|
doc := goldmark.New().Parser().Parse(text.NewReader(src))
|
|
|
|
c := &checker{src: src, lineStarts: lineStarts(src)}
|
|
|
|
_ = ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
|
|
if !entering {
|
|
return ast.WalkContinue, nil
|
|
}
|
|
switch node := n.(type) {
|
|
case *ast.RawHTML:
|
|
c.scanNode(segmentsOf(node.Segments))
|
|
case *ast.HTMLBlock:
|
|
segs := segmentsOf(node.Lines())
|
|
if node.HasClosure() {
|
|
segs = append(segs, node.ClosureLine)
|
|
}
|
|
c.scanNode(segs)
|
|
}
|
|
return ast.WalkContinue, nil
|
|
})
|
|
|
|
// Anything left open at end of file is unclosed.
|
|
for _, open := range c.stack {
|
|
c.findings = append(c.findings, unclosedFinding(open))
|
|
}
|
|
|
|
slices.SortStableFunc(c.findings, func(a, b finding) int {
|
|
return cmp.Compare(a.line, b.line)
|
|
})
|
|
return c.findings
|
|
}
|
|
|
|
// segmentsOf materializes a *text.Segments into a slice.
|
|
func segmentsOf(s *text.Segments) []text.Segment {
|
|
out := make([]text.Segment, 0, s.Len())
|
|
for i := range s.Len() {
|
|
out = append(out, s.At(i))
|
|
}
|
|
return out
|
|
}
|
|
|
|
// rawTagName extracts the original-case tag name from a raw token. The
|
|
// tokenizer's TagName lowercases, which hides whether a tag was capitalized, so
|
|
// scanNode reads the name straight from the raw bytes: skip the leading < and
|
|
// the / of an end tag, then take everything up to the first whitespace, / or >.
|
|
func rawTagName(raw []byte) string {
|
|
i := 0
|
|
for i < len(raw) && (raw[i] == '<' || raw[i] == '/') {
|
|
i++
|
|
}
|
|
start := i
|
|
for i < len(raw) {
|
|
switch raw[i] {
|
|
case ' ', '\t', '\n', '\r', '\f', '/', '>':
|
|
return string(raw[start:i])
|
|
}
|
|
i++
|
|
}
|
|
return string(raw[start:i])
|
|
}
|
|
|
|
type openTag struct {
|
|
tag string
|
|
line int
|
|
}
|
|
|
|
// unclosedFinding builds the finding for a container tag left open. It is the
|
|
// single source for the unclosed-tag message, shared by the end-of-file drain
|
|
// in checkSource and the dangling-inner-tag loop in matchEndTag.
|
|
func unclosedFinding(o openTag) finding {
|
|
return finding{
|
|
line: o.line,
|
|
kind: kindUnclosedTag,
|
|
tag: o.tag,
|
|
msg: fmt.Sprintf("unclosed <%s> tag", o.tag),
|
|
}
|
|
}
|
|
|
|
type checker struct {
|
|
src []byte
|
|
lineStarts []int
|
|
stack []openTag
|
|
findings []finding
|
|
}
|
|
|
|
// scanNode checks the tags in one raw-HTML node. The balance stack persists
|
|
// across nodes, so a container opened in one block and closed in another still
|
|
// balances.
|
|
func (c *checker) scanNode(segs []text.Segment) {
|
|
tokenizeSegments(c.src, segs, c.lineAt, func(z *html.Tokenizer, tt html.TokenType, raw []byte, line int) {
|
|
switch tt {
|
|
case html.StartTagToken, html.SelfClosingTagToken:
|
|
rawName := rawTagName(raw)
|
|
name := strings.ToLower(rawName)
|
|
if autolinkShaped(name) {
|
|
// e.g. <https://coder.com> or <user@coder.com>: valid Markdown
|
|
// autolink syntax, never a real HTML element. goldmark only
|
|
// classifies these as autolinks in inline context, not inside a
|
|
// raw HTML block, so skip them explicitly to avoid false
|
|
// positives.
|
|
return
|
|
}
|
|
if rawName != name {
|
|
// A capitalized tag is an MDX/JSX component reference, not an
|
|
// HTML element (element names are case-insensitive but
|
|
// conventionally lowercase; the docs renderer treats a
|
|
// capitalized tag as a component). Report it regardless of
|
|
// whether the lowercased name collides with a real element, so
|
|
// <Table>, <Section>, and <Image> are all caught.
|
|
c.findings = append(c.findings, finding{
|
|
line: line,
|
|
kind: kindUnknownElement,
|
|
tag: name,
|
|
msg: fmt.Sprintf("<%s> is a capitalized tag; the docs renderer reads it as a "+
|
|
"component reference and drops it unless registered. Use a lowercase HTML "+
|
|
"element or a registered component", rawName),
|
|
})
|
|
return
|
|
}
|
|
if !allowedElements[name] {
|
|
c.findings = append(c.findings, finding{
|
|
line: line,
|
|
kind: kindUnknownElement,
|
|
tag: name,
|
|
msg: fmt.Sprintf("<%s> is not a recognized HTML element or component; wrap a "+
|
|
"placeholder in backticks, add a standard HTML element to allowedElements, "+
|
|
"or use a registered component", name),
|
|
})
|
|
return
|
|
}
|
|
c.findings = append(c.findings, guardTag(z, name, line)...)
|
|
// Track balance for container elements that need an explicit end
|
|
// tag. A self-closing flag on a non-void HTML element (<div/>) is
|
|
// ignored by the HTML5 parser and the docs renderer, so it opens a
|
|
// container that leaks exactly like <div>; keep tracking it. A
|
|
// self-closing renderer component (<children/>) is the exception:
|
|
// MDX honors the self-closing form, so it is complete and must not
|
|
// be tracked. Void and optional-end-tag elements are never pushed.
|
|
if !voidElements[name] && !optionalEndTags[name] {
|
|
if tt != html.SelfClosingTagToken || !rendererComponents[name] {
|
|
c.stack = append(c.stack, openTag{tag: name, line: line})
|
|
}
|
|
}
|
|
case html.EndTagToken:
|
|
rawName := rawTagName(raw)
|
|
name := strings.ToLower(rawName)
|
|
if autolinkShaped(name) {
|
|
return
|
|
}
|
|
if rawName != name {
|
|
// Closing tag of a capitalized component; its opening tag was
|
|
// already reported, and component tags are not balance-tracked.
|
|
return
|
|
}
|
|
if voidElements[name] {
|
|
c.findings = append(c.findings, finding{
|
|
line: line,
|
|
kind: kindVoidEndTag,
|
|
tag: name,
|
|
msg: fmt.Sprintf("</%s> is invalid: <%s> is a void element with no end tag", name, name),
|
|
})
|
|
return
|
|
}
|
|
if !allowedElements[name] || optionalEndTags[name] {
|
|
// Unknown end tags are reported via their start tag; optional
|
|
// end tags are not balance-tracked.
|
|
return
|
|
}
|
|
c.matchEndTag(name, line)
|
|
}
|
|
})
|
|
}
|
|
|
|
// tokenizeSegments tokenizes an entire raw-HTML node at once and calls visit
|
|
// for each token with its source line. It concatenates the node's source
|
|
// segments into a single buffer, so a tag whose text wraps across lines is
|
|
// tokenized whole instead of being torn in half.
|
|
func tokenizeSegments(src []byte, segs []text.Segment, lineAt func(int) int, visit func(z *html.Tokenizer, tt html.TokenType, raw []byte, line int)) {
|
|
if len(segs) == 0 {
|
|
return
|
|
}
|
|
|
|
// Concatenate the segment text into one buffer, recording where each
|
|
// segment lands so a buffer offset can be translated back to a source byte
|
|
// offset. Segments are individually contiguous in the source but may be
|
|
// separated by gaps (such as the line breaks a block spans).
|
|
type span struct {
|
|
bufStart, srcStart, length int
|
|
}
|
|
var buf []byte
|
|
spans := make([]span, 0, len(segs))
|
|
for _, seg := range segs {
|
|
v := seg.Value(src)
|
|
spans = append(spans, span{bufStart: len(buf), srcStart: seg.Start, length: len(v)})
|
|
buf = append(buf, v...)
|
|
}
|
|
srcOffset := func(bufPos int) int {
|
|
for i := len(spans) - 1; i >= 0; i-- {
|
|
if bufPos >= spans[i].bufStart {
|
|
return spans[i].srcStart + min(bufPos-spans[i].bufStart, spans[i].length)
|
|
}
|
|
}
|
|
return spans[0].srcStart
|
|
}
|
|
|
|
z := html.NewTokenizer(bytes.NewReader(buf))
|
|
pos := 0
|
|
for {
|
|
tt := z.Next()
|
|
if tt == html.ErrorToken {
|
|
return
|
|
}
|
|
raw := z.Raw()
|
|
line := lineAt(srcOffset(pos))
|
|
pos += len(raw)
|
|
visit(z, tt, raw, line)
|
|
}
|
|
}
|
|
|
|
// matchEndTag resolves an end tag against the balance stack: it pops to the
|
|
// matching open tag, emits kindUnclosedTag for any tags left dangling above the
|
|
// match, and emits kindStrayEndTag when nothing matches.
|
|
func (c *checker) matchEndTag(name string, line int) {
|
|
for i := len(c.stack) - 1; i >= 0; i-- {
|
|
if c.stack[i].tag == name {
|
|
// Tags above the match were left unclosed inside this element.
|
|
for j := len(c.stack) - 1; j > i; j-- {
|
|
c.findings = append(c.findings, unclosedFinding(c.stack[j]))
|
|
}
|
|
c.stack = c.stack[:i]
|
|
return
|
|
}
|
|
}
|
|
c.findings = append(c.findings, finding{
|
|
line: line,
|
|
kind: kindStrayEndTag,
|
|
tag: name,
|
|
msg: fmt.Sprintf("</%s> has no matching opening tag", name),
|
|
})
|
|
}
|
|
|
|
// schemeRe matches a URI scheme ending in a colon (e.g. "https:", "mailto:").
|
|
// A Markdown autolink inside a raw-HTML block tokenizes with such a name.
|
|
var schemeRe = regexp.MustCompile(`^[a-z][a-z0-9+.-]*:$`)
|
|
|
|
// autolinkShaped reports whether a tokenized tag name is a real Markdown
|
|
// autolink rather than an HTML element or a placeholder. goldmark only
|
|
// classifies autolinks as such in inline context; inside a raw-HTML block one
|
|
// tokenizes as a tag whose name is either a URI scheme ending in a colon
|
|
// (<https://coder.com> tokenizes as "https:") or a mail-shaped local@domain
|
|
// with a real, dotted domain (<user@coder.com>). A bare colon or at sign is
|
|
// not enough, so placeholders the linter targets (<region:id>, <user@host>)
|
|
// stay checked.
|
|
func autolinkShaped(name string) bool {
|
|
if schemeRe.MatchString(name) {
|
|
return true
|
|
}
|
|
at := strings.IndexByte(name, '@')
|
|
if at <= 0 || at >= len(name)-1 {
|
|
return false
|
|
}
|
|
domain := name[at+1:]
|
|
return !strings.Contains(domain, "@") && strings.Contains(domain, ".")
|
|
}
|
|
|
|
// lineStarts returns the byte offset of the start of each line.
|
|
func lineStarts(src []byte) []int {
|
|
starts := []int{0}
|
|
for i, b := range src {
|
|
if b == '\n' {
|
|
starts = append(starts, i+1)
|
|
}
|
|
}
|
|
return starts
|
|
}
|
|
|
|
// lineAt returns the 1-based line number for a byte offset.
|
|
func (c *checker) lineAt(offset int) int {
|
|
// Largest index i such that lineStarts[i] <= offset.
|
|
i := sort.Search(len(c.lineStarts), func(i int) bool {
|
|
return c.lineStarts[i] > offset
|
|
})
|
|
if i < 1 {
|
|
return 1
|
|
}
|
|
return i
|
|
}
|