check_doc_diagrams.py

Go to the documentation of this file.

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Brighton Sikarskie
"""Gate: authored diagrams render, and the hand-authored figures stay valid.
 
An authored Graphviz block is written as ``@dot`` ... ``@enddot`` inside a
Markdown page or a Doxygen comment.  Doxygen renders each one by shelling out
to ``dot`` and emitting ``<img src="dot_inline_dotgraph_<md5>.svg">`` into the
page.  Nothing in this repository ever checked that the second half happened.
 
That gap is not hypothetical.  Three separate failure modes drop a diagram
while leaving the page HTTP 200, the prose intact and every existing gate
green:
 
* ``HAVE_DOT=NO`` -- ``build_docs.sh`` degrades to text-only output when
  ``dot`` is absent from ``PATH``.  Doxygen then ignores every authored block,
  the published site loses every diagram, and nothing fails.
* ``PLANTUML_JAR_PATH`` unset -- doxygen ignored every ``@startuml`` block and
  emitted one warning per block, which ``scripts/ci.sh`` explicitly filtered
  out.  24 state-machine diagrams rendered nowhere for the entire life of the
  tree while ``CLAUDE.md`` mandated the construct that produced them.
* A block doxygen parses but ``dot`` fails to lay out yields an SVG file with
  no graph content in it -- present, referenced, and empty.
 
So this gate reads the *generated output*, not the configuration.
Configuration is what everyone checked; output is what was broken.
 
Counting model
--------------
Comparing raw embed counts does not work: doxygen renders one comment block on
both the file page and the topic page it belongs to, so a single ``@dot``
legitimately produces several ``<img>`` embeds.  Doxygen also names each
rendered SVG after a hash of the block body, so two byte-identical blocks share
one file.  The invariant that survives both effects is:
 
    distinct authored block bodies  ==  distinct rendered SVGs referenced
 
Both sides are deduplicated by content, which is the identity doxygen itself
uses.
 
The hand-authored figures
-------------------------
``docs/diagrams/*.svg`` are not generated by anything.  They are written by
hand and embedded straight into Markdown pages with ``<img>``, so GitHub and
the published site serve them from the repository as-is.  No build step
touches them and no other gate reads them -- fix-encoding.py's suffix set
does not include ``.svg`` -- so a figure can stop being an SVG while every
check in the tree stays green and the page renders an empty box.
 
That is not hypothetical either: a ``--`` inside an XML comment is illegal,
every renderer refuses the whole document over it, and one shipped as far as
a green docs-gate run.  So this gate also sweeps that directory for
well-formedness, 7-bit ASCII, self-containment, and ``url(#id)`` references
that resolve to a locally-defined id.
 
Usage::
 
    check_doc_diagrams.py --html build/docs-gate/html   # the gate
    check_doc_diagrams.py --selftest                    # both-direction proof
 
Exit 0 when clean, 1 on findings, 2 on a selftest failure or a missing ``dot``.
"""
 
from __future__ import annotations
 
import argparse
import hashlib
import re
import shutil
import sys
import tempfile
from collections.abc import Iterator
from pathlib import Path
from typing import NamedTuple
from xml.parsers import expat
 
sys.path.insert(0, str(Path(__file__).resolve().parent))
 
from lint_targets import is_build_output_path
 
REPO_ROOT = Path(__file__).resolve().parents[2]
 
#: Roots scanned for authored diagram blocks.  Mirrors the CLAUDE.md scope
#: note: every first-party file, not just the firmware.
SCAN_ROOTS = ("docs", "libs", "port", "examples", "tools", "apps", "tests")
 
#: Suffixes that can carry a doxygen comment or a doxygen-rendered page.
SCAN_SUFFIXES = (".md", ".c", ".h", ".cpp", ".hpp", ".dox")
 
#: Path fragments marking vendored or generated trees, which are out of scope.
EXCLUDED = ("third_party", "/generated/", "doxygen_theme")
 
#: Files allowed to name the banned construct while documenting the rule.
#: They describe the policy; they do not carry a renderable block.
STARTUML_DOC_ALLOWLIST = (
    "docs/STYLE_GUIDE.md",
    "docs/DOCS.md",
    "docs/formats/BINARY_FORMATS.md",
)
 
#: Written into the generated HTML tree by build_docs.sh once a build finishes.
#: Its contents are the fingerprint of the authored diagram set that build saw,
#: which is what lets this gate tell "output built from the tree under test"
#: apart from "whatever HTML was lying around".
STAMP_NAME = ".ra8-diagram-stamp"
 
#: Where the hand-authored figures live.  Nothing generates them and nothing
#: else in the tree reads them, so a file that stops being a valid SVG breaks
#: silently: the embedding page renders an empty box and every gate stays
#: green.
DIAGRAM_DIR = "docs/diagrams"
 
#: Non-vacuity floor for that sweep.  The directory holds eight figures today
#: (one system map, seven cluster maps).  A sweep finding fewer has lost its
#: subject -- a rename, a move, an emptied directory -- and a scan of nothing
#: must fail rather than report clean.
DIAGRAM_FLOOR = 8
 
#: What a self-contained figure may point at: a fragment inside itself, or an
#: inline data: payload.  Anything else is a fetch the reader's browser makes
#: against a host that may not answer, which is how a figure renders here and
#: nowhere else.
SVG_LOCAL_REF = ("#", "data:")
 
SVG_HREF = re.compile(r'(?:xlink:href|href|src)\s*=\s*"([^"]*)"')
SVG_URL_REF = re.compile(r"url\‍(\s*#([^)\s]+?)\s*\‍)")
SVG_ID_DEF = re.compile(r'\bid\s*=\s*"([^"]*)"')
 
DOT_OPEN = re.compile(r"^\s*(?:\*\s?)?@dot\s*$")
DOT_CLOSE = re.compile(r"^\s*(?:\*\s?)?@enddot\s*$")
SVG_REF = re.compile(r"dot_inline_dotgraph_[0-9a-f]+\.svg")
SVG_TEXT = re.compile(r"<text[^>]*>([^<]*)</text>")
COMMENT_LEADER = re.compile(r"^\s*\*\s?")
 
 
def in_scope(path: Path) -> bool:
    """Whether a file is scanned for diagram blocks.
 
    Build output is excluded via the shared is_build_output_path predicate
    rather than a local substring test, so this gate and the size gates cannot
    disagree about what counts as generated (#377).
    """
    posix = path.as_posix()
    if is_build_output_path(posix) or any(frag in posix for frag in EXCLUDED):
        return False
    return path.suffix in SCAN_SUFFIXES
 
 
def iter_sources(root: Path) -> Iterator[Path]:
    """Yield every in-scope source file beneath the configured scan roots.
 
    Symlinks are skipped, so a link pointing back into the tree cannot make
    one diagram body appear at two origins and read as a duplicate.
    """
    for top in SCAN_ROOTS:
        base = root / top
        if not base.is_dir():
            continue
        for path in sorted(base.rglob("*")):
            if path.is_file() and not path.is_symlink() and in_scope(path):
                yield path
 
 
def normalise(body_lines: list[str]) -> str:
    """Reduce a block body to the text doxygen hashes.
 
    Strips the Doxygen comment leader (`` * ``) and trailing whitespace, so the
    same diagram written in a ``.h`` comment and in a ``.md`` page normalises
    identically -- which is what makes them collide into one rendered SVG.
    """
    out = [COMMENT_LEADER.sub("", ln).rstrip() for ln in body_lines]
    while out and not out[0]:
        out.pop(0)
    while out and not out[-1]:
        out.pop()
    return "\n".join(out)
 
 
class Finding:
    """One rule violation, rendered as ``where: message``."""
 
    def __init__(self, where: str, message: str) -> None:
        """Record one finding at ``where`` (a ``path:line``) with its message."""
        self.where = where
        self.message = message
 
    def __str__(self) -> str:
        """Render as ``path:line: message`` -- editor-jumpable."""
        return f"{self.where}: {self.message}"
 
 
def _scan_startuml(rel: str, lines: list[str]) -> list[Finding]:
    """Reject the construct that renders nowhere in this tree."""
    if rel in STARTUML_DOC_ALLOWLIST:
        return []
    return [
        Finding(
            f"{rel}:{idx}",
            "@startuml renders nothing (PLANTUML_JAR_PATH is unset and no "
            "JVM is provisioned) -- use @dot",
        )
        for idx, line in enumerate(lines, 1)
        if "@startuml" in line
    ]
 
 
def _scan_dot_blocks(rel: str, lines: list[str], blocks: dict[str, list[str]]) -> list[Finding]:
    """Collect ``@dot`` bodies into ``blocks``; return marker findings."""
    findings: list[Finding] = []
    open_at: int | None = None
    body: list[str] = []
 
    for idx, line in enumerate(lines, 1):
        if DOT_OPEN.match(line):
            if open_at is not None:
                findings.append(Finding(f"{rel}:{idx}", "nested @dot: previous block never closed"))
            open_at, body = idx, []
        elif DOT_CLOSE.match(line):
            if open_at is None:
                findings.append(Finding(f"{rel}:{idx}", "@enddot without @dot"))
                continue
            key = normalise(body)
            if not key:
                findings.append(Finding(f"{rel}:{open_at}", "empty @dot block"))
            blocks.setdefault(key, []).append(f"{rel}:{open_at}")
            open_at = None
        elif open_at is not None:
            body.append(line)
 
    if open_at is not None:
        findings.append(Finding(f"{rel}:{open_at}", "@dot block never closed"))
    return findings
 
 
def scan_sources(
    root: Path, files: list[Path] | None = None
) -> tuple[dict[str, list[str]], list[Finding]]:
    """Return ``(blocks, findings)``; ``blocks`` maps normalised body -> origins."""
    blocks: dict[str, list[str]] = {}
    findings: list[Finding] = []
    sources = files if files is not None else list(iter_sources(root))
 
    for path in sources:
        try:
            text = path.read_text(encoding="utf-8")
        except (UnicodeDecodeError, OSError):
            continue
        rel = path.relative_to(root).as_posix() if path.is_absolute() else path.as_posix()
        lines = text.splitlines()
        findings += _scan_startuml(rel, lines)
        findings += _scan_dot_blocks(rel, lines, blocks)
 
    return blocks, findings
 
 
def scan_html(html_dir: Path) -> tuple[set[str], set[str], list[Finding]]:
    """Return ``(referenced, live, findings)`` for diagrams under ``html_dir``."""
    findings: list[Finding] = []
    referenced: set[str] = set()
 
    for page in sorted(html_dir.rglob("*.html")):
        try:
            text = page.read_text(encoding="utf-8", errors="replace")
        except OSError:
            continue
        referenced.update(SVG_REF.findall(text))
 
    live: set[str] = set()
    for name in sorted(referenced):
        svg = html_dir / name
        if not svg.is_file():
            findings.append(Finding(name, "referenced by a page but not generated"))
            continue
        content = svg.read_text(encoding="utf-8", errors="replace")
        # A laid-out graphviz SVG always carries at least one node group.
        if 'class="node"' not in content:
            findings.append(
                Finding(name, "rendered SVG contains no graph nodes (dot produced an empty layout)")
            )
            continue
        # A diagram can render and still be wrong. `\\n` in a dot label is an
        # escaped backslash followed by 'n', so graphviz draws the characters
        # "\n" instead of breaking the line -- the label reads as one run of
        # text with literal escapes in it. This has shipped twice, so catch it
        # in the rendered text rather than trusting the source spelling.
        literal = [t for t in SVG_TEXT.findall(content) if "\\n" in t]
        if literal:
            findings.append(
                Finding(
                    name,
                    "rendered label contains a literal '\\n' -- the dot source "
                    "double-escaped a line break (use \\n, not \\\\n): "
                    + "; ".join(sorted(literal)[:3]),
                )
            )
            continue
        live.add(name)
 
    return referenced, live, findings
 
 
def source_fingerprint(blocks: dict[str, list[str]]) -> str:
    """Fingerprint the authored diagram set, order-independently."""
    digest = hashlib.sha256()
    for key in sorted(blocks):
        digest.update(key.encode("utf-8"))
        digest.update(b"\0")
    return digest.hexdigest()
 
 
def check_stamp(html_dir: Path, blocks: dict[str, list[str]]) -> list[Finding]:
    """Refuse to judge output that was not built from the tree under test.
 
    Doxygen never deletes what it no longer produces, so a directory can hold a
    mixture of two builds. That is dangerous in both directions: an orphan
    render can mask a diagram the current tree drops, and a diagram added since
    the last build looks dropped. Rather than trusting the caller to have
    rebuilt, compare the authored diagram set against the fingerprint the build
    recorded.
    """
    stamp = html_dir / STAMP_NAME
    if not stamp.is_file():
        return [
            Finding(
                str(html_dir),
                "no build stamp -- this HTML was not produced by scripts/builders/docs.sh, "
                "so it cannot be trusted to reflect the current tree. Rebuild with "
                "'bash scripts/builders/docs.sh --gate'.",
            )
        ]
    recorded = stamp.read_text(encoding="utf-8").strip()
    current = source_fingerprint(blocks)
    if recorded != current:
        return [
            Finding(
                str(html_dir),
                "stale output -- the authored diagram set has changed since this "
                f"HTML was built (stamp {recorded[:12]}, tree {current[:12]}). "
                "Rebuild with 'bash scripts/builders/docs.sh --gate'; do not judge "
                "the diagrams from a mixture of two builds.",
            )
        ]
    return []
 
 
def check(root: Path, html_dir: Path) -> list[Finding]:
    """Run every rule and return the accumulated findings."""
    blocks, findings = scan_sources(root)
 
    # Freshness first: every count below is meaningless against stale output,
    # and reporting a bogus count mismatch is how a gate teaches people to
    # `rm -rf` and re-run until green.
    stale = check_stamp(html_dir, blocks)
    if stale:
        return findings + stale
 
    _referenced, live, html_findings = scan_html(html_dir)
    findings += html_findings
 
    n_src, n_live = len(blocks), len(live)
    if n_src != n_live:
        detail = [
            "",
            f"  distinct authored @dot blocks : {n_src}",
            f"  distinct rendered  SVGs       : {n_live}",
            "",
        ]
        if n_src > n_live:
            # Report SOURCE files, never rendered-SVG filenames. Doxygen names
            # each SVG after a hash of its own normalised copy of the block, and
            # that normalisation is not reproducible from the source text, so an
            # SVG name cannot be attributed back to the block that produced it.
            # Printing one anyway names a file the author never touched, which
            # is exactly what made this hard to read the first time it fired.
            per_file: dict[str, int] = {}
            for origins in blocks.values():
                for origin in origins:
                    per_file[origin.rsplit(":", 1)[0]] = (
                        per_file.get(origin.rsplit(":", 1)[0], 0) + 1
                    )
            detail.append(f"  {n_src - n_live} authored diagram(s) did not reach the HTML.")
            detail.append("  Authored @dot blocks by source file:")
            detail.extend(f"    {count:3d}  {path}" for path, count in sorted(per_file.items()))
            detail.append("")
            detail.append("  The build is fresh (stamp matched), so a block in one of these")
            detail.append("  files was parsed but not rendered. Check it for a dot syntax")
            detail.append("  error, or a node count over DOT_GRAPH_MAX_NODES.")
        else:
            detail.append(
                "  More rendered diagrams than authored blocks -- a scan root "
                "or suffix is missing from this gate."
            )
        findings.append(
            Finding(
                "diagram-count", "authored and rendered diagram counts disagree" + "\n".join(detail)
            )
        )
    return findings
 
 
# ---------------------------------------------------------------------------
# The hand-authored figures under docs/diagrams/
# ---------------------------------------------------------------------------
 
 
def _svg_wellformed(rel: str, data: bytes) -> list[Finding]:
    """Reject a figure that is not parseable XML, at the parser's own position.
 
    expat rather than ElementTree or minidom on purpose: it is the engine
    underneath both, it hands back the failing line and column directly, and it
    is the one spelling ruff's flake8-bandit family does not require a
    suppression for.
    """
    parser = expat.ParserCreate()
    try:
        # expat takes isfinal POSITIONALLY: Parse() rejects the keyword form
        # outright, so this boolean has no more readable spelling.
        parser.Parse(data, True)  # noqa: FBT003 -- keyword form unsupported
    except expat.ExpatError as exc:
        return [
            Finding(
                f"{rel}:{parser.ErrorLineNumber}",
                f"not well-formed XML at column {parser.ErrorColumnNumber}: "
                f"{expat.ErrorString(exc.code)} -- every renderer refuses the "
                "whole document, so the page shows an empty box",
            )
        ]
    return []
 
 
def _svg_ascii(rel: str, data: bytes) -> list[Finding]:
    """Reject any byte outside 7-bit ASCII, naming the first one.
 
    The repository-wide ASCII policy is enforced by fix-encoding.py, whose
    suffix set has never included ``.svg``; these figures have therefore never
    been covered by it. Asserted here rather than by widening that gate's scope,
    because fix-encoding.py REWRITES what it finds and transliterating inside a
    coordinate or path stream is not obviously safe.
    """
    try:
        data.decode("ascii")
    except UnicodeDecodeError as exc:
        line = data[: exc.start].count(b"\n") + 1
        return [
            Finding(
                f"{rel}:{line}",
                f"non-ASCII byte 0x{data[exc.start]:02x} at offset {exc.start} "
                "-- figures are held to the same 7-bit rule as every other "
                "first-party file",
            )
        ]
    return []
 
 
def _svg_self_contained(rel: str, text: str) -> list[Finding]:
    """Reject an off-page fetch, and any ``url(#id)`` with no local definition.
 
    Two failure modes, one symptom: a figure that renders here and not there.
    An external href is a request to a host outside this repository, which a
    reader behind a proxy or an offline copy of the docs never gets. A
    ``url(#id)`` naming an id no element defines -- a renamed marker, a
    fragment copied between figures -- leaves the arrowhead or gradient
    silently missing from a document that is otherwise perfectly valid.
    """
    findings = [
        Finding(
            rel,
            f"external reference {value!r} -- a figure must carry everything it draws",
        )
        for value in SVG_HREF.findall(text)
        if not value.startswith(SVG_LOCAL_REF)
    ]
    ids = set(SVG_ID_DEF.findall(text))
    findings += [
        Finding(rel, f"url(#{ref}) names an id no element in this file defines")
        for ref in sorted(set(SVG_URL_REF.findall(text)) - ids)
    ]
    return findings
 
 
def check_diagram_svgs(root: Path) -> list[Finding]:
    """Validate every hand-authored figure under ``docs/diagrams/``.
 
    Independent of the docs build: these files ship verbatim, so what matters
    is a property of the file rather than of any generated output. A malformed
    figure is reported on its own -- the pattern rules would only add noise
    about a document the parser has already rejected.
    """
    base = root / DIAGRAM_DIR
    svgs = sorted(base.glob("*.svg")) if base.is_dir() else []
    if len(svgs) < DIAGRAM_FLOOR:
        return [
            Finding(
                DIAGRAM_DIR,
                f"only {len(svgs)} SVG(s) found, floor is {DIAGRAM_FLOOR} -- the "
                "sweep has lost its subject, and a scan of nothing must not "
                "report clean",
            )
        ]
    findings: list[Finding] = []
    for path in svgs:
        rel = path.relative_to(root).as_posix()
        data = path.read_bytes()
        findings += _svg_ascii(rel, data)
        malformed = _svg_wellformed(rel, data)
        findings += malformed
        if not malformed:
            findings += _svg_self_contained(rel, data.decode("ascii", errors="replace"))
    return findings
 
 
# ---------------------------------------------------------------------------
# Selftest
# ---------------------------------------------------------------------------
 
 
def _svg(*, nodes: bool, label: str = "Idle") -> str:
    body = f'<g class="node"><title>A</title><text x="0" y="0">{label}</text></g>' if nodes else ""
    return f'<?xml version="1.0"?><svg xmlns="http://www.w3.org/2000/svg">{body}</svg>'
 
 
def _md(*bodies: str) -> str:
    return "Prose paragraph.\n\n" + "\n".join("@dot\n" + b + "\n@enddot\n" for b in bodies)
 
 
def _page(*svgs: str) -> str:
    imgs = "".join(f'<div class="dotgraph"><img src="{s}"/></div>' for s in svgs)
    return f"<html><body>{imgs}</body></html>"
 
 
def _hashed(body: str) -> str:
    """Synthesise a doxygen-style SVG filename for a selftest fixture.
 
    Not a security primitive: this only has to be a stable, unique-per-body
    name so the fixtures can wire a page to its SVG the way doxygen does.
    """
    digest = hashlib.md5(body.encode(), usedforsecurity=False).hexdigest()
    return f"dot_inline_dotgraph_{digest}.svg"
 
 
# --- selftest fixtures ------------------------------------------------------
# The cases below are DATA, not logic, and they live at module scope for that
# reason: wrapping a 100-line table in a function only moves the length, since
# the size gate measures a function body whether it holds statements or a list
# literal. Splitting the table itself into arbitrary chunks would scatter one
# cohesive spec across several names for no reader's benefit.
 
_G1 = "digraph a { x -> y; }"
_G2 = "digraph b { p -> q; }"
_S1, _S2 = _hashed(_G1), _hashed(_G2)
 
_DUP_HEADER = (
    "/**\n * @dot\n" + "\n".join(" * " + ln for ln in _G1.splitlines()) + "\n * @enddot\n */\n"
)
 
 
class _DiagramCase(NamedTuple):
    """One selftest scenario: a fixture tree and the verdict the gate must reach.
 
    Replaces the positional tuples this table used to hold, where the optional
    fifth field was read as ``case[STAMP_MODE_FIELD] if len(case) > ...``. The
    named default says the same thing without an index constant.
    """
 
    name: str
    """Human-readable scenario name, printed in the per-case verdict line."""
    sources: dict[str, str]
    """Repo-relative source path -> file text, materialised under ``repo/``."""
    html: dict[str, str]
    """Doxygen-output-relative path -> file text, materialised under ``html/``."""
    expect_fire: bool
    """True when the gate MUST report a finding for this tree."""
    stamp_mode: str = "good"
    """How the build stamp is seeded: ``good`` / ``wrong`` / ``missing``."""
 
 
_SELFTEST_CASES: tuple[_DiagramCase, ...] = (
    # --- the gate must STAY SILENT on correct output ------------------
    _DiagramCase(
        "correct: 2 authored, 2 rendered",
        {"docs/x.md": _md(_G1, _G2)},
        {"p.html": _page(_S1, _S2), _S1: _svg(nodes=True), _S2: _svg(nodes=True)},
        expect_fire=False,
    ),
    _DiagramCase(
        "correct: one block embedded on two pages",
        {"docs/x.md": _md(_G1)},
        {"a.html": _page(_S1), "b.html": _page(_S1), _S1: _svg(nodes=True)},
        expect_fire=False,
    ),
    _DiagramCase(
        "correct: identical blocks share one SVG",
        {"docs/x.md": _md(_G1), "libs/y.h": _DUP_HEADER},
        {"p.html": _page(_S1), _S1: _svg(nodes=True)},
        expect_fire=False,
    ),
    # --- the gate must FIRE when a diagram is dropped -----------------
    _DiagramCase(
        "dropped: 2 authored, 1 rendered",
        {"docs/x.md": _md(_G1, _G2)},
        {"p.html": _page(_S1), _S1: _svg(nodes=True)},
        expect_fire=True,
    ),
    _DiagramCase(
        "dropped: every diagram missing (HAVE_DOT=NO)",
        {"docs/x.md": _md(_G1, _G2)},
        {"p.html": "<html><body>no diagrams</body></html>"},
        expect_fire=True,
    ),
    _DiagramCase(
        "empty: rendered SVG has no nodes",
        {"docs/x.md": _md(_G1)},
        {"p.html": _page(_S1), _S1: _svg(nodes=False)},
        expect_fire=True,
    ),
    _DiagramCase(
        "double-escaped: label renders a literal backslash-n",
        {"docs/x.md": _md(_G1)},
        {"p.html": _page(_S1), _S1: _svg(nodes=True, label="ra8_init\\nstep two")},
        expect_fire=True,
    ),
    _DiagramCase(
        "missing: referenced SVG absent from disk",
        {"docs/x.md": _md(_G1)},
        {"p.html": _page(_S1)},
        expect_fire=True,
    ),
    _DiagramCase(
        "startuml: banned construct present",
        {"docs/x.md": "@startuml\n[*] --> A\n@enduml\n"},
        {"p.html": "<html></html>"},
        expect_fire=True,
    ),
    _DiagramCase(
        "unbalanced: @dot never closed",
        {"docs/x.md": "@dot\ndigraph z { a -> b; }\n"},
        {"p.html": "<html></html>"},
        expect_fire=True,
    ),
    # --- the gate must REFUSE output it cannot attribute to this tree ----
    # Stale output is dangerous in both directions, and the dangerous one
    # is a leftover render MASKING a diagram the current tree drops. Both
    # of these would otherwise "pass" on the counts alone.
    _DiagramCase(
        "stale: leftover render masks a dropped diagram",
        # Two blocks authored; only one is rendered, but a leftover SVG
        # from an older build makes the count add up.
        {"docs/x.md": _md(_G1, _G2)},
        {"p.html": _page(_S1), _S1: _svg(nodes=True), _S2: _svg(nodes=True)},
        expect_fire=True,
        stamp_mode="wrong",
    ),
    _DiagramCase(
        "stale: output predates a newly added diagram",
        {"docs/x.md": _md(_G1, _G2)},
        {"p.html": _page(_S1, _S2), _S1: _svg(nodes=True), _S2: _svg(nodes=True)},
        expect_fire=True,
        stamp_mode="wrong",
    ),
    _DiagramCase(
        "unknown provenance: no build stamp at all",
        {"docs/x.md": _md(_G1)},
        {"p.html": _page(_S1), _S1: _svg(nodes=True)},
        expect_fire=True,
        stamp_mode="missing",
    ),
)
 
 
def _materialise_case(case: _DiagramCase, td: str) -> tuple[Path, Path]:
    """Write one case's fixture tree under ``td`` and seed its build stamp.
 
    Returns ``(repo_root, html_dir)``. The stamp is what lets the gate tell
    output built from the tree under test from output that was not: "good"
    models a directory build_docs.sh has just written, "wrong" a stale render,
    "missing" output of unknown provenance.
    """
    root = Path(td) / "repo"
    hdir = Path(td) / "html"
    hdir.mkdir(parents=True)
    for rel, text in case.sources.items():
        path = root / rel
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(text, encoding="utf-8")
    for rel, text in case.html.items():
        (hdir / rel).write_text(text, encoding="utf-8")
 
    if case.stamp_mode == "good":
        seen, _ = scan_sources(root)
        (hdir / STAMP_NAME).write_text(source_fingerprint(seen), encoding="utf-8")
    elif case.stamp_mode == "wrong":
        (hdir / STAMP_NAME).write_text("0" * 64, encoding="utf-8")
    # "missing" writes nothing at all.
    return root, hdir
 
 
def _verdict(name: str, *, fired: bool, expect_fire: bool) -> bool:
    """Print one case's verdict line; True when the gate behaved as specified."""
    if fired == expect_fire:
        verdict = "fires" if expect_fire else "silent"
        sys.stdout.write(f"  ok ({verdict:6s}) {name}\n")
        return True
    want = "FIRE" if expect_fire else "stay silent"
    got = "fired" if fired else "stayed silent"
    sys.stderr.write(f"  selftest FAIL [{name}]: expected the gate to {want}, it {got}\n")
    return False
 
 
def _run_case(case: _DiagramCase) -> bool:
    """Run one case in a throwaway tree; True when the gate behaved as specified."""
    with tempfile.TemporaryDirectory() as td:
        root, hdir = _materialise_case(case, td)
        fired = bool(check(root, hdir))
    return _verdict(case.name, fired=fired, expect_fire=case.expect_fire)
 
 
class _SvgCase(NamedTuple):
    """One docs/diagrams scenario: a fixture directory and the verdict required."""
 
    name: str
    """Human-readable scenario name, printed in the per-case verdict line."""
    files: dict[str, str]
    """Repo-relative path -> file text, materialised under ``repo/``."""
    expect_fire: bool
    """True when the sweep MUST report a finding for this tree."""
 
 
def _fig(marker: str, extra: str = "") -> str:
    """One figure in the house style: a marker reached through ``url(#id)``."""
    return (
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 20" width="40">'
        f'<defs><marker id="{marker}"><path d="M0,0 L4,2 L0,4 z"/></marker></defs>'
        f'<line x1="0" y1="10" x2="30" y2="10" marker-end="url(#{marker})"/>{extra}'
        "</svg>\n"
    )
 
 
def _figs(count: int = DIAGRAM_FLOOR, **replace: str) -> dict[str, str]:
    """``count`` clean figures keyed by path, with named entries replaced.
 
    ``_figs(f0=...)`` swaps one figure for a broken one, so each case below
    differs from the clean case in exactly the defect it is asserting.
    """
    tree = {f"{DIAGRAM_DIR}/f{i}.svg": _fig(f"a{i}") for i in range(count)}
    tree.update({f"{DIAGRAM_DIR}/{name}.svg": text for name, text in replace.items()})
    return tree
 
 
_SVG_CASES: tuple[_SvgCase, ...] = (
    # --- the sweep must STAY SILENT on a sound directory ------------------
    _SvgCase("figures: a clean directory", _figs(), expect_fire=False),
    # --- ...and FIRE on each way a figure breaks --------------------------
    # The first case is the exact defect that motivated this sweep: a double
    # hyphen inside an XML comment. The file still looks like an SVG to every
    # text-level check in the tree, and renders as nothing.
    _SvgCase(
        "figures: double hyphen inside an XML comment",
        _figs(f0=_fig("a0", "<!-- drawn -- badly -->")),
        expect_fire=True,
    ),
    _SvgCase(
        "figures: external image reference",
        _figs(f0=_fig("a0", '<image href="https://example.invalid/x.png" width="4"/>')),
        expect_fire=True,
    ),
    _SvgCase(
        "figures: url(#id) naming an id nothing defines",
        _figs(f0=_fig("a0", '<line x1="0" y1="1" x2="9" y2="1" marker-end="url(#gone)"/>')),
        expect_fire=True,
    ),
    _SvgCase(
        "figures: a non-ASCII byte",
        _figs(f0=_fig("a0", '<text x="1" y="1">\u00b5s</text>')),
        expect_fire=True,
    ),
    _SvgCase(
        "figures: directory below the non-vacuity floor",
        _figs(DIAGRAM_FLOOR - 1),
        expect_fire=True,
    ),
)
 
 
def _run_svg_case(case: _SvgCase) -> bool:
    """Run one docs/diagrams case in a throwaway tree; True when it behaved."""
    with tempfile.TemporaryDirectory() as td:
        root = Path(td) / "repo"
        for rel, text in case.files.items():
            path = root / rel
            path.parent.mkdir(parents=True, exist_ok=True)
            path.write_text(text, encoding="utf-8")
        fired = bool(check_diagram_svgs(root))
    return _verdict(case.name, fired=fired, expect_fire=case.expect_fire)
 
 
def selftest() -> int:
    """Prove both halves fire on a broken tree and stay silent on a sound one."""
    failures = sum(1 for case in _SELFTEST_CASES if not _run_case(case))
    failures += sum(1 for case in _SVG_CASES if not _run_svg_case(case))
    expected = [c.expect_fire for c in _SELFTEST_CASES] + [c.expect_fire for c in _SVG_CASES]
    total = len(expected)
    if failures:
        sys.stderr.write(f"check_doc_diagrams.py: selftest FAILED ({failures}/{total} cases).\n")
        return 2
    fires = sum(expected)
    sys.stdout.write(
        f"check_doc_diagrams.py: selftest PASSED ({total} cases -- "
        f"{fires} assert the gate fires, {total - fires} assert it does not).\n"
    )
    return 0
 
 
def _build_parser() -> argparse.ArgumentParser:
    """Build the command-line parser for this gate."""
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument(
        "--html", default="build/docs-gate/html", help="generated HTML directory to inspect"
    )
    parser.add_argument(
        "--selftest", action="store_true", help="run synthetic both-direction fixtures and exit"
    )
    parser.add_argument(
        "--write-stamp",
        action="store_true",
        help="record the authored diagram fingerprint into the HTML tree "
        "(called by scripts/builders/docs.sh once a build finishes)",
    )
    return parser
 
 
def _graphviz_present() -> bool:
    """True when graphviz ``dot`` is on PATH; writes the FATAL message when not.
 
    A gate whose dependency is absent must FAIL, never silently pass: without
    ``dot`` every authored diagram is dropped, and this gate cannot tell that
    apart from a build that was never run.
    """
    if shutil.which("dot") is not None:
        return True
    sys.stderr.write(
        "check_doc_diagrams.py: FATAL -- graphviz 'dot' is not on PATH.\n"
        "Every authored diagram is dropped without it, and this gate "
        "cannot tell that apart from a build that was never run.\n"
    )
    return False
 
 
def _resolve_html_dir(raw: str) -> Path | None:
    """Resolve ``raw`` against the repo root; None (with a message) if absent."""
    html_dir = Path(raw)
    if not html_dir.is_absolute():
        html_dir = REPO_ROOT / html_dir
    if html_dir.is_dir():
        return html_dir
    sys.stderr.write(
        f"check_doc_diagrams.py: FATAL -- no generated HTML at {html_dir}.\n"
        "Build the docs first (scripts/builders/docs.sh --gate).\n"
    )
    return None
 
 
def _report_findings(findings: list[Finding]) -> None:
    """Print every finding, then advice matched to what actually went wrong.
 
    Kept separate from the decision to fail because the closing advice must
    stay truthful: a provenance failure means "this measurement is not valid
    yet", not "a diagram is missing". Telling someone their diagrams are gone
    when the real answer is "rebuild" is how a gate earns a reputation for
    crying wolf.
    """
    sys.stderr.write("check_doc_diagrams.py: FAILED\n\n")
    for finding in findings:
        sys.stderr.write(f"  {finding}\n")
    figures = [f for f in findings if f.where.startswith(DIAGRAM_DIR)]
    if figures:
        sys.stderr.write(
            f"\nA figure under {DIAGRAM_DIR} ships verbatim: no build step would "
            "notice, and the page that embeds it renders an empty box.\n"
        )
    if any("stale output" in f.message or "no build stamp" in f.message for f in findings):
        sys.stderr.write(
            "\nNothing was measured: the generated HTML does not correspond "
            "to the current tree.\nRebuild and re-run before drawing any "
            "conclusion about the diagrams.\n"
        )
    elif len(figures) != len(findings):
        sys.stderr.write(
            "\nAn authored diagram that does not reach the HTML is invisible "
            "to every reader of the published site.\n"
        )
 
 
def main() -> int:
    """Verify every authored diagram actually reached the generated HTML.
 
    The gate this replaces was the cautionary case: 24 mandated state diagrams
    used ``@startuml``, doxygen ignored every one of them for want of a
    PlantUML jar, and the docs gate filtered the resulting warning away -- so
    the diagrams rendered nowhere for the life of the tree while the style
    rules demanded them. Hence two rules here rather than one: reject
    ``@startuml`` outright, and prove each authored ``@dot`` body appears in
    the output.
 
    ``--write-stamp`` records the authored fingerprint after a docs build and
    checks nothing; the build script calls it, and CI must not, or the stamp
    is written from the same run it is supposed to validate.
 
    Returns 0 when every authored diagram is present, 1 on any finding.
    """
    args = _build_parser().parse_args()
 
    if args.selftest:
        return selftest()
 
    if not _graphviz_present():
        return 2
    html_dir = _resolve_html_dir(args.html)
    if html_dir is None:
        return 2
 
    if args.write_stamp:
        blocks, _ = scan_sources(REPO_ROOT)
        (html_dir / STAMP_NAME).write_text(source_fingerprint(blocks), encoding="utf-8")
        sys.stdout.write(
            f"check_doc_diagrams.py: stamped {len(blocks)} authored diagram(s) "
            f"into {html_dir.relative_to(REPO_ROOT)}.\n"
        )
        return 0
 
    findings = check_diagram_svgs(REPO_ROOT) + check(REPO_ROOT, html_dir)
    if findings:
        _report_findings(findings)
        return 1
 
    blocks, _ = scan_sources(REPO_ROOT)
    figures = len(list((REPO_ROOT / DIAGRAM_DIR).glob("*.svg")))
    sys.stdout.write(
        f"check_doc_diagrams.py: OK -- {len(blocks)} authored diagram(s) all "
        f"render in {html_dir.relative_to(REPO_ROOT)}, and {figures} figure(s) "
        f"under {DIAGRAM_DIR} are well-formed, ASCII and self-contained.\n"
    )
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())