Files
coder/scripts/docshtmlcheck/main.go
T
Nick Vigilante 6e51c66a97 docs: give every table header cell text and fail lint on empty ones (#30879)
## 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>&nbsp;</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 in cfd29a2160 (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), and b807bcbbc7 and 2871f89bdf (style guide rule
section, `make lint/docs-html` in the checks table, coverage counts).

Linear: DOCS-1308

---

🤖 Built with AI assistance.
2026-10-21 10:58:04 -07:00

697 lines
25 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).
//
// 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.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.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, stale int
}
func (c issueCounts) add(o issueCounts) issueCounts {
return issueCounts{html: c.html + o.html, table: c.table + o.table, 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, 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++
default:
counts.html++
}
}
if counts.html+counts.table > 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(_ *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
}
// 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
}