check_docs.py

#!/usr/bin/env python3
"""Doc-drift gate: every NUMBER the docs claim, re-derived from the tree.

The docs in this repo carry hard numbers — the shipped version, the test
counts a release battery produced, how many RAW/baked extensions the engine
accepts, which crates the stack is built from, which toolchain compiled it.
Those numbers were all true the day they were written, and nothing but a
human re-reading them keeps them true afterwards: `Cargo.toml` bumps, a
const grows an entry, a dependency lands, and the prose silently becomes a
confident lie. This is a GATE, not a report — run it before a release and it
exits non-zero when a doc and the tree disagree.

The core is a CLAIMS registry: each row names ONE claim site (doc + regex
with named capture groups) and ONE truth extractor (the source of record for
that number). Three outcomes per row:

  PASS  every occurrence of the pattern carries the truth's value
  FAIL  a value disagrees -> claim name, doc value, truth value, both sources
  FAIL  the pattern matches NOTHING -> the claim site moved (the doc was
        rewritten, the sentence rephrased). This is deliberately NOT a silent
        skip: a gate that quietly stops looking is worse than no gate, because
        it keeps reporting PASS over prose nobody is checking any more.
        Re-anchor the row on the new wording.
  SKIP  the truth is not derivable from the repo alone — today only the test
        counts, which are only provable by RUNNING the battery (pass its
        transcript with --gates).

A pattern may match several times (the same count is claimed in several
sections); ALL occurrences must agree with the truth, so a half-updated doc
fails.

Pure stdlib, no network, strictly READ-ONLY over the repo — it never rewrites
a file, and it never "fixes" a doc for you. The repo has MIXED line endings by
design (per-file `.gitattributes` + `core.autocrlf`), so every file is read as
utf-8 and normalised to LF *inside* the checker only.

    python scripts/check_docs.py
    python scripts/check_docs.py --gates <release-battery transcript>
    python scripts/check_docs.py --list
"""

from __future__ import annotations

import argparse
import os
import re
import sys
import xml.etree.ElementTree as ET
from pathlib import Path
from typing import Callable, NamedTuple

REPO = Path(__file__).resolve().parents[1]

_CACHE: dict[Path, str] = {}


def text(rel: str) -> str:
    """Repo file as LF-normalised utf-8. Read-only; nothing is written back."""
    p = REPO / rel
    if p not in _CACHE:
        _CACHE[p] = (
            p.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
        )
    return _CACHE[p]


def line_of(src: str, idx: int) -> int:
    return src.count("\n", 0, idx) + 1


class Truth(NamedTuple):
    """A claim's source of record: the value, and where it was read from."""

    value: tuple[str, ...]
    source: str


class Skip(NamedTuple):
    reason: str


# ── Truth extractors ────────────────────────────────────────────────────────


_ARRAY_LEN = re.compile(r"\[\s*&\s*(?:'[A-Za-z_]\w*\s+)?str\s*;\s*(\d+)\s*\]")


def _literals_in_const(src: str, anchor: str) -> list[str]:
    """String literals inside `const <NAME>: [&str; N] = [ ... ];`.

    The bracket scan starts at the `=`, NOT at the anchor: the declaration's
    TYPE carries its own bracket (`[&str; 24]`), so opening on the first `[`
    after the name would measure the type and extract nothing. The span is
    bracket-MATCHED rather than line-matched, so an initialiser that wraps
    across source lines (RAW_EXTS spans three) counts the same as a one-liner.

    Both Rust comment forms are skipped. `//` always was; `/* */` was NOT until
    R28 2c, so a literal commented out with a block comment counted as live and
    the docs were checked against a number the compiler never saw. (Nesting is
    not modelled — Rust's block comments nest, this stops at the first `*/`.
    The residue is then ordinary text to this scanner, so the failure direction
    is a wrong count, which the length cross-check below catches.)

    The count is CROSS-CHECKED against the declared `[&str; N]`, which the
    compiler enforces and this scanner does not: any drift between what the
    lexer sees and what the type says is a broken lexer, and a broken lexer
    that returns a plausible number is exactly what a doc gate must never do.
    """
    at = src.find(anchor)
    if at < 0:
        raise LookupError(f"anchor {anchor!r} not found (const renamed/moved?)")
    i = src.index("[", src.index("=", at))
    declared = _ARRAY_LEN.search(src[at:i])
    if not declared:
        raise LookupError(
            f"{anchor}: no `[&str; N]` type annotation — not a fixed-size array any more"
        )
    depth = 0
    out: list[str] = []
    while i < len(src):
        c = src[i]
        if src.startswith("//", i):
            i = src.index("\n", i)
            continue
        if src.startswith("/*", i):
            shut = src.find("*/", i + 2)
            if shut < 0:
                raise LookupError(f"unterminated block comment in {anchor!r}")
            i = shut + 2
            continue
        if c == '"':
            j = i + 1
            while src[j] != '"':
                j += 2 if src[j] == "\\" else 1
            out.append(src[i + 1 : j])
            i = j + 1
            continue
        if c == "[":
            depth += 1
        elif c == "]":
            depth -= 1
            if depth == 0:
                n = int(declared.group(1))
                if len(out) != n:
                    raise LookupError(
                        f"{anchor}: extracted {len(out)} literal(s) but the type "
                        f"declares [&str; {n}] — the scanner and the compiler "
                        "disagree; fix the scanner, not the doc"
                    )
                return out
        i += 1
    raise LookupError(f"unclosed initialiser for {anchor!r}")


# Self-check (the font gate's notdef idiom): a broken scanner must fail HERE,
# never pass by extracting nothing — "0 extensions" would otherwise sail
# through as a number the docs simply never claim.
_PROBE = (
    'pub const P: [&str; 3] = [\n'
    '    "a", "b\\"x", // "not a literal"\n'
    '    /* "nor is this" */ "c",\n'
    "];"
)
assert _literals_in_const(_PROBE, "const P") == ["a", 'b\\"x', "c"], (
    "const-literal self-check: type bracket / escape / comment handling drifted"
)


def _raises_lookup(fn: Callable[[], object]) -> bool:
    """Did `fn` reject its input? The self-checks below assert the FAILING
    direction of a guard, and a guard only ever exercised on input it accepts
    cannot be told apart from a deleted one (R28 2c). LookupError is caught
    rather than swallowed because it is precisely the verdict under test — any
    other exception is a real defect and propagates.
    """
    try:
        fn()
    except LookupError:
        return True
    return False


assert _raises_lookup(lambda: _literals_in_const('pub const Q: [&str; 4] = ["a", "b"];', "const Q")), (
    "const-literal self-check: a count that disagrees with [&str; N] was accepted"
)


def ext_count(rel: str, anchor: str) -> Callable[[argparse.Namespace], Truth]:
    def extract(_args: argparse.Namespace) -> Truth:
        src = text(rel)
        n = len(_literals_in_const(src, anchor))
        line = line_of(src, src.find(anchor))
        return Truth((str(n),), f"{rel}:{line} ({anchor})")

    return extract


def _set_verdict(
    got: list[str],
    want: list[str],
    got_source: str,
    truth_source: str,
) -> tuple[str, list[str]]:
    """Compare named memberships, with duplicate detection and useful deltas."""
    got_norm = [v.lower().lstrip(".") for v in got]
    want_norm = [v.lower().lstrip(".") for v in want]
    got_set, want_set = set(got_norm), set(want_norm)
    duplicates = sorted({v for v in got_norm if got_norm.count(v) > 1})
    missing = sorted(want_set - got_set)
    extra = sorted(got_set - want_set)
    if duplicates or missing or extra:
        detail = [
            f"        doc      {len(got_norm)} item(s) from {got_source}",
            f"        truth    {len(want_set)} member(s) from {truth_source}",
        ]
        if missing:
            detail.append("        missing  " + ", ".join(missing))
        if extra:
            detail.append("        extra    " + ", ".join(extra))
        if duplicates:
            detail.append("        duplicate " + ", ".join(duplicates))
        return "FAIL", detail
    return "PASS", [f"        exact {len(want_set)}-member set"]


def check_readme_raw_ext_membership(
    _args: argparse.Namespace,
) -> tuple[str, list[str]]:
    """README's fenced RAW list must name exactly `decode::RAW_EXTS`."""
    doc = text("README.md")
    m = re.search(
        r"\*\*Camera RAW — \d+ extensions\*\*.*?```text\n(?P<items>.*?)\n```",
        doc,
        re.S,
    )
    if not m:
        raise LookupError("README Camera RAW fenced list moved; re-anchor the set gate")
    got = [v.strip() for v in m.group("items").replace("\n", " ").split(",") if v.strip()]
    source = text("src/decode.rs")
    want = _literals_in_const(source, "const RAW_EXTS")
    return _set_verdict(
        got,
        want,
        f"README.md:{line_of(doc, m.start('items'))}",
        f"src/decode.rs:{line_of(source, source.find('const RAW_EXTS'))} (const RAW_EXTS)",
    )


def check_readme_no_preview_membership(
    _args: argparse.Namespace,
) -> tuple[str, list[str]]:
    """README's no-preview names must equal decode.rs's no-rendition set."""
    doc = text("README.md")
    m = re.search(
        r"\*\*No embedded\s+preview:\*\*.*?They are (?P<items>.*?); AutoShade",
        doc,
        re.S,
    )
    if not m:
        raise LookupError("README no-preview sentence moved; re-anchor the set gate")
    got = re.findall(r"`([A-Za-z0-9]+)`", m.group("items"))

    source = text("src/decode.rs")
    truth = re.search(
        r"overrides none of the three\s+///\s+rendition methods for (?P<items>.*?)\s+"
        r"\(the trait defaults",
        source,
        re.S,
    )
    if not truth:
        raise LookupError(
            "src/decode.rs no-rendition source comment moved; re-anchor the set gate"
        )
    want = re.findall(r"\b[A-Z0-9]{2,4}\b", truth.group("items"))
    return _set_verdict(
        got,
        want,
        f"README.md:{line_of(doc, m.start('items'))}",
        f"src/decode.rs:{line_of(source, truth.start('items'))} (no-rendition set)",
    )


def cargo_version(_args: argparse.Namespace) -> Truth:
    src = text("Cargo.toml")
    at = src.index("[package]")
    end = src.find("\n[", at)
    m = re.search(r'^version = "(\d+\.\d+\.\d+)"', src[at:end], re.M)
    if not m:
        raise LookupError("Cargo.toml: no [package] version = \"X.Y.Z\"")
    return Truth((m.group(1),), f"Cargo.toml:{line_of(src, at + m.start())}")


def latest_published_version(args: argparse.Namespace) -> Truth:
    """Latest already-published release during a pre-release documentation pass.

    W4 deliberately prepares Cargo/docs for the next version before W5 builds
    and publishes it. While README carries that explicit pre-release sentence,
    the issue template must keep offering the actually published release. Once
    W5 removes the sentence, the package version becomes the truth again.
    """
    src = text("README.md")
    m = re.search(r"v(\d+\.\d+\.\d+) remains the latest published release", src)
    if m:
        return Truth(
            (m.group(1),),
            f"README.md:{line_of(src, m.start())} (pre-release publication status)",
        )
    return cargo_version(args)


# ── Cargo dependency inventory (tech-stack completeness) ────────────────────

_DEP_SECTION = re.compile(
    r"^\[(?:target\.[^\]]+\.)?"
    r"(dependencies|dev-dependencies|build-dependencies)"
    r"(?:\.([A-Za-z0-9_-]+))?\]$"
)


def _strip_toml_comment(line: str) -> str:
    """Drop a trailing `# ...` comment. Cargo.toml's comments are prose full of
    brackets (`Vec<[f32;3]>`), which would wreck the depth counter below."""
    out: list[str] = []
    in_str = False
    for ch in line:
        if ch == '"':
            in_str = not in_str
        elif ch == "#" and not in_str:
            break
        out.append(ch)
    return "".join(out)


def _mask_toml_strings(line: str) -> str:
    """Blank the CONTENT of every quoted span, keeping the line's shape.

    The depth counter below is a bracket census, and a `[` inside a string
    value is not structure — `note = "see [x"` used to leave the counter stuck
    at depth 1, after which every remaining dependency AND every section header
    was skipped (the `depth == 0` guard covers both). The empty-list guard in
    `check_tech_stack` only catches a TOTAL loss, so a half-lost inventory
    passed as coverage (R28 2c).

    Line-local, and deliberately so: Cargo.toml's strings are basic ones that
    cannot span lines, and this file has no `\"\"\"` literals.
    """
    out: list[str] = []
    quote: str | None = None
    for ch in line:
        if quote is not None:
            if ch == quote:
                quote = None
            out.append(" ")
        elif ch in "\"'":
            quote = ch
            out.append(" ")
        else:
            out.append(ch)
    return "".join(out)


def _dep_names_from(src: str) -> list[str]:
    """[`cargo_dependency_names`] over any TOML text — split out so the
    self-check below can feed it a synthetic table instead of the repo's own
    (a scanner probed only against the file it already handles proves nothing).
    """
    names: list[str] = []
    section: str | None = None
    depth = 0
    for raw in src.split("\n"):
        line = _strip_toml_comment(raw)
        if depth == 0:
            stripped = line.strip()
            m = _DEP_SECTION.match(stripped)
            if m:
                section = m.group(1)
                if m.group(2):  # [dependencies.foo] sub-table names the dep
                    names.append(m.group(2))
            elif stripped.startswith("["):
                section = None  # [package] / [lib] / [[bin]] / [features]
            elif section:
                k = re.match(r"([A-Za-z0-9_-]+)\s*=", line)
                if k:
                    names.append(k.group(1))
        counted = _mask_toml_strings(line)
        depth = max(0, depth + sum(counted.count(c) for c in "[{")
                    - sum(counted.count(c) for c in "]}"))
    return sorted(set(names))


# A bracket inside a quoted value must not derail the census. Without the mask
# the `"see [x"` line leaves depth at 1 and `beta` is never seen.
_TOML_PROBE = '[dependencies]\nalpha = { version = "1", note = "see [x" }\nbeta = "2"\n'
assert _dep_names_from(_TOML_PROBE) == ["alpha", "beta"], (
    "dependency-census self-check: a bracket inside a quoted value broke the depth counter"
)


def cargo_dependency_names() -> list[str]:
    """Every DIRECT dependency name: [dependencies] (the optional gui crates
    live there behind `optional = true`), the per-target tables, build- and
    dev-dependencies.

    Only column-0 `name =` lines at bracket depth 0 count, so a multi-line
    inline table (`image = { ... features = [\\n "jpeg", ... \\n] }`) yields
    the crate and not its feature strings.
    """
    return _dep_names_from(text("Cargo.toml"))


def check_tech_stack(_args: argparse.Namespace) -> tuple[str, list[str]]:
    """Every direct dependency must be NAMED somewhere in ARCHITECTURE.md.

    Not a value comparison but a coverage one: a crate that entered the tree
    without ever entering the architecture doc is a stack the doc no longer
    describes. Token match (word-ish boundaries over `[A-Za-z0-9_-]`), so
    `serde` inside `serde_json` does not vouch for `serde`.
    """
    names = cargo_dependency_names()
    if not names:
        return "FAIL", ["        Cargo.toml yielded NO dependency names — parser drift"]
    doc = text("docs/ARCHITECTURE.md")
    missing = [
        n
        for n in names
        if not re.search(
            r"(?<![A-Za-z0-9_-])" + re.escape(n) + r"(?![A-Za-z0-9_-])", doc
        )
    ]
    if missing:
        return "FAIL", [
            f"        {len(missing)} of {len(names)} direct deps never named in "
            "docs/ARCHITECTURE.md",
            "        missing  " + ", ".join(missing),
            "        truth    Cargo.toml (dependency tables)",
        ]
    return "PASS", [f"        all {len(names)} direct deps named"]


# ── Release-battery transcript (test counts) ────────────────────────────────

_BLOCK = re.compile(r"^=== (?P<name>.+?) ===\s*$")
_TARGET = re.compile(r"^\s+(?P<kind>Running (?:unittests )?|Doc-tests )(?P<target>\S+)")
_RESULT = re.compile(
    r"^test result: (?P<status>\w+)\. (?P<passed>\d+) passed; "
    r"(?P<failed>\d+) failed; (?P<ignored>\d+) ignored;"
)


def _battery_blocks(path: Path) -> dict[str, list[tuple[str, str, int, int, int]]]:
    """Per block: (target, status, passed, failed, ignored) in cargo's order.

    `target` is the path cargo names in its `Running ...` header, normalised
    to forward slashes (`src/lib.rs`, `src/bin/gui/main.rs`, `tests/x.rs`);
    a Doc-tests suite is named `doc-tests:<crate>` so it can never be mistaken
    for a claimable count.
    """
    blocks: dict[str, list[tuple[str, str, int, int, int]]] = {}
    cur: str | None = None
    target = "?"
    raw = path.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
    for line in raw.split("\n"):
        b = _BLOCK.match(line)
        if b:
            cur = b.group("name")
            blocks.setdefault(cur, [])
            target = "?"
            continue
        t = _TARGET.match(line)
        if t:
            name = t.group("target").replace("\\", "/")
            target = f"doc-tests:{name}" if t.group("kind").startswith("Doc") else name
            continue
        r = _RESULT.match(line)
        if r and cur is not None:
            blocks[cur].append(
                (
                    target,
                    r.group("status"),
                    int(r.group("passed")),
                    int(r.group("failed")),
                    int(r.group("ignored")),
                )
            )
    return blocks


def battery_test_counts(args: argparse.Namespace) -> Truth | Skip:
    """library / CLI / GUI / contract counts from a release-battery transcript.

    Only the battery can prove these, so without --gates the row SKIPS rather
    than inventing a number. Suites are read BY NAME from cargo's own
    `Running` headers: library = `src/lib.rs`, CLI = `src/main.rs` and the
    contract pair = `tests/*.rs`, all from the default block; GUI = the
    `src/bin/gui/main.rs` bin from the gui block. The `gui` feature only adds
    dependencies (Cargo.toml [features]; no `cfg(feature = "gui")` outside
    src/bin/gui), so the gui trip need not repeat the other suites — and when
    it does, every suite both trips ran must agree, count for count, or the
    transcript is refused: that equality is what licenses the shorter trip.
    """
    if not args.gates:
        return Skip("no --gates transcript: test counts are only provable by "
                    "running the release battery")
    path = Path(args.gates)
    blocks = _battery_blocks(path)
    for want in ("test default", "test gui"):
        if want not in blocks:
            raise LookupError(f"{path.name}: no '=== {want} ===' block")
    # A red battery cannot vouch for anything.
    for name in ("test default", "test gui"):
        bad = [r for r in blocks[name] if r[1] != "ok"]
        if bad:
            raise LookupError(f"{path.name}: '{name}' has a non-ok result: {bad[0]}")

    def counts(name: str) -> dict[str, int]:
        # passed + ignored per named suite; a Doc-tests suite is not a count.
        out: dict[str, int] = {}
        for target, _, passed, _, ignored in blocks[name]:
            if target.startswith("doc-tests:"):
                continue
            if target in out:
                raise LookupError(f"{path.name}: '{name}' ran {target} twice")
            out[target] = passed + ignored
        return out

    default, gui = counts("test default"), counts("test gui")
    for target in sorted(default.keys() & gui.keys()):
        if default[target] != gui[target]:
            raise LookupError(
                f"{path.name}: {target} counts {default[target]} (default) vs "
                f"{gui[target]} (gui) — the gui feature must not change it"
            )
    for target in ("src/lib.rs", "src/main.rs"):
        if target not in default:
            raise LookupError(f"{path.name}: default block never ran {target}")
    if "src/bin/gui/main.rs" not in gui:
        raise LookupError(f"{path.name}: gui block never ran src/bin/gui/main.rs")
    contract = [n for t, n in default.items() if t.startswith("tests/")]
    if len(contract) != 2:
        raise LookupError(
            f"{path.name}: {len(contract)} contract suites, the doc claims a pair"
        )
    value = (
        str(default["src/lib.rs"]), str(default["src/main.rs"]),
        str(gui["src/bin/gui/main.rs"]), str(contract[0]), str(contract[1]),
    )
    return Truth(value, f"{path.name} (=== test default === / === test gui ===, by suite name)")


def _battery_block_text(path: Path, name: str) -> str | None:
    """One `=== name ===` block verbatim, or None when the transcript has none.

    `_battery_blocks` keeps only the result tuples, which is all the count
    claim needs. The calibration lane is claimed on things that are not
    counts — the skip lines a test prints, the summary the script writes — so
    this hands back the block's own text.
    """
    raw = path.read_text(encoding="utf-8").replace("\r\n", "\n").replace("\r", "\n")
    out: list[str] = []
    inside = False
    for line in raw.split("\n"):
        m = _BLOCK.match(line)
        if m:
            inside = m.group("name") == name
            continue
        if inside:
            out.append(line)
    return "\n".join(out) if out else None


_LANE = re.compile(r"^lane (?P<name>[a-z][a-z0-9_]*)", re.M)


def check_release_battery_lanes(args: argparse.Namespace) -> tuple[str, list[str]]:
    """Every lane `scripts/release_battery.sh` runs, named in ARCHITECTURE.

    The script is the source of record: each `lane <name>` invocation in it is
    a lane, and the battery paragraph must name each one in bold, so a lane
    added later cannot stay undocumented while the prose still describes
    three. With a --gates transcript the same names must each own a
    `=== test <name> ===` block, and the calibration lane's library suite must
    report the same test count as the default lane's — the corpus variable
    decides whether a test SKIPS, never whether it exists, so a disagreement
    means the two lanes did not run the same suite.

    A transcript written by hand rather than by the script has no calibration
    block; that is a SKIP with the reason, not a failure, because the claim is
    about the script's lanes and not about how the transcript was produced.
    """
    script = "scripts/release_battery.sh"
    lanes = _LANE.findall(text(script))
    if not lanes:
        raise LookupError(f"{script}: no `lane <name>` invocation — the lane set moved")
    doc = text(ARCH)
    missing = [n for n in lanes if f"**{n}**" not in doc]
    if missing:
        return "FAIL", [
            f"        {script} runs {', '.join(lanes)}",
            f"        {ARCH} names none of: {', '.join(missing)}",
        ]
    detail = [f"        lanes {', '.join(lanes)}   ({script} -> {ARCH})"]
    if not args.gates:
        return "PASS", detail
    path = Path(args.gates)
    blocks = _battery_blocks(path)
    absent = [n for n in lanes if f"test {n}" not in blocks]
    if absent:
        return "SKIP", detail + [
            f"        {path.name} has no '=== test {absent[0]} ===' block — it was "
            "not written by release_battery.sh, so its lanes cannot be checked"
        ]
    calib = {t: p + i for t, _, p, _, i in blocks["test calib"] if not t.startswith("doc-tests:")}
    default = {t: p + i for t, _, p, _, i in blocks["test default"] if not t.startswith("doc-tests:")}
    lib = "src/lib.rs"
    if lib in calib and lib in default and calib[lib] != default[lib]:
        return "FAIL", detail + [
            f"        {path.name}: {lib} is {default[lib]} in the default lane and "
            f"{calib[lib]} in the calibration lane — the corpus variable must not "
            "change which tests exist"
        ]
    body = _battery_block_text(path, "test calib") or ""
    # Counted wherever a skip line lands, as release_battery.sh counts it:
    # under --nocapture it can arrive mid-line, between libtest's `test
    # <name> ... ` and its `ok` (the v1.6.3 battery). A name runs to the first
    # ": ".
    skips = len(re.findall(r"SKIPPED [^:\n]+: ", body))
    detail.append(
        f"        {path.name}: calibration lane ran {calib.get(lib, 0)} library tests, "
        f"{skips} of them skipped for want of a corpus or a sidecar"
    )
    return "PASS", detail


# ── Toolchain ───────────────────────────────────────────────────────────────

_TOOLCHAIN_PINS = ("rust-toolchain.toml", "rust-toolchain")


def toolchain_truth(_args: argparse.Namespace) -> Truth:
    """The toolchain the docs must agree with.

    Since v1.2.4 the repo DOES pin one (`rust-toolchain.toml`), so the branch
    below promotes it to the source of record and the doc-internal fallback
    stops being used — exactly as this function was written to do. The fallback
    is kept, not deleted: it is what the check falls back to if the pin is ever
    removed, and a claim that silently stops checking anything is worse than one
    that checks the weaker thing.

    The comparison here stays at major.minor, because the fallback source
    (README's Tech line) carries no patch. `pinned_toolchain` below is the row
    that compares the PATCH, and it is the one the pin made possible.
    """
    for rel in _TOOLCHAIN_PINS:
        p = REPO / rel
        if p.exists():
            src = text(rel)
            m = re.search(r'channel\s*=\s*"([^"]+)"', src) or re.search(
                r"^\s*(\d+\.\d+(?:\.\d+)?)\s*$", src, re.M
            )
            if not m:
                raise LookupError(f"{rel}: no channel/version found")
            return Truth((m.group(1),), f"{rel}:{line_of(src, m.start())}")
    src = text("README.md")
    m = re.search(r"rustc/cargo (?P<toolchain>\d+(?:\.\d+)+)", src)
    if not m:
        raise LookupError("README.md: Tech line no longer states rustc/cargo X.Y")
    return Truth((m.group("toolchain"),), f"README.md:{line_of(src, m.start())} "
                 "(doc-internal: repo pins no toolchain)")


def pinned_toolchain(_args: argparse.Namespace) -> Truth | Skip:
    """The channel `rust-toolchain.toml` pins, exactly — patch included.

    `toolchain_truth` compares at major.minor because its fallback source has no
    patch, so "1.94.1 in ARCHITECTURE, 1.94.2 on every runner" reads as a match.
    The pin closed that: it is what `rustup` hands every `cargo` call, so it is
    what actually built the published binaries, and §5 states the patch. This
    row compares the two verbatim.

    SKIPs rather than fails when the pin is absent, so removing the pin does not
    turn this into a red that says nothing about the docs.
    """
    p = REPO / "rust-toolchain.toml"
    if not p.is_file():
        return Skip("rust-toolchain.toml is absent: there is no pin to compare against")
    src = text("rust-toolchain.toml")
    m = re.search(r'channel\s*=\s*"([^"]+)"', src)
    if not m:
        raise LookupError('rust-toolchain.toml: no channel = "…" to read')
    return Truth((m.group(1),), f"rust-toolchain.toml:{line_of(src, m.start())}")


def major_minor(v: tuple[str, ...]) -> tuple[str, ...]:
    return tuple(".".join(x.split(".")[:2]) for x in v)


def camera_model_count(_args: argparse.Namespace) -> Truth:
    """rawler's camera-model count, from the source-of-record comment in
    decode.rs (a rawler property this tree asserts once in code and quotes in
    five doc places — R28 doc audit added this row so a rawler bump cannot
    leave the doc copies behind)."""
    src = text("src/decode.rs")
    m = re.search(r"carries (?P<models>\d+) camera models", src)
    if not m:
        raise LookupError(
            "src/decode.rs: no 'carries N camera models' comment — the "
            "source-of-record moved; re-anchor this extractor"
        )
    return Truth((m.group("models"),), f"src/decode.rs:{line_of(src, m.start())}")


def readme_battery_numbers(_args: argparse.Namespace) -> Truth:
    """All README battery numbers, reordered to match ARCHITECTURE's sentence."""
    src = text("README.md")
    m = re.search(
        r"current battery is \*\*(?P<lib>\d+) library "
        r"\((?P<passed>\d+) pass \+ (?P<ignored>\d+) `#\[ignore\]`d forensic probes\) / "
        r"(?P<cli>\d+) CLI / (?P<gui>\d+) GUI / "
        r"(?P<c1>\d+)\+(?P<c2>\d+) contract\*\* tests",
        src,
    )
    if not m:
        raise LookupError("README.md: current battery sentence moved; re-anchor the extractor")
    value = tuple(
        m.group(name)
        for name in ("lib", "cli", "gui", "c1", "c2", "passed", "ignored")
    )
    return Truth(value, f"README.md:{line_of(src, m.start())} (doc-internal battery source)")


def census_counts(_args: argparse.Namespace) -> Truth | Skip:
    """Re-derive the active XMP census when its corpus root is supplied.

    The corpus is user data, not a repository fixture, so the default gate
    reports SKIP rather than pretending the machine-local count is universal.
    CI/release runs that have the corpus set `AUTOSHADE_CENSUS_ROOT` and get a
    first-party count check against the source-of-truth comment.

    The pre-rename `AUTOSHOP_CENSUS_ROOT` no longer answers: v1.2.4 closed the
    app's own `AUTOSHOP_*` door (the alias prefix and the four functions that
    rebuilt names out of it are gone from `config.rs`), and a gate that kept a
    second spelling the app itself refuses would be checking a configuration
    nothing else honours.
    """
    name = "AUTOSHADE_CENSUS_ROOT"
    raw = os.environ.get(name)
    if not raw:
        return Skip("AUTOSHADE_CENSUS_ROOT is unset: the census corpus is outside the repo")
    root = Path(raw)
    if not root.is_dir():
        raise LookupError(f"{name} is not a directory: {root}")
    files = list(root.rglob("*.xmp"))
    counts = {"Mask/Aggregate": 0, "Mask/Image": 0, "Mask/Paint": 0, "Mask/*": 0, "Gesture": 0}
    for path in files:
        try:
            document = ET.parse(path)
        except ET.ParseError as exc:
            raise LookupError(f"{path}: XML parse failed: {exc}") from exc
        for element in document.iter():
            for name, value in element.attrib.items():
                if name.rsplit("}", 1)[-1] != "What" or not value.startswith("Mask/"):
                    continue
                counts["Mask/*"] += 1
                counts[value] = counts.get(value, 0) + 1
            if element.tag.rsplit("}", 1)[-1] == "Gesture":
                counts["Gesture"] += 1
    values = (
        str(len(files)),
        str(counts["Mask/Aggregate"]),
        str(counts["Mask/Image"]),
        str(counts["Mask/Paint"]),
        str(counts["Mask/*"]),
        str(counts["Gesture"]),
    )
    return Truth(values, f"{root} (recursive *.xmp census, XML parser)")


# ── The one file we publish ourselves ───────────────────────────────────────

_OWN_PIN = re.compile(
    r'"(?P<key>[^"]+)":\s*\{\s*'
    r'"url":\s*f"\{_AUTOSHADE_RELEASE\}/(?P<file>[^"]+)",\s*'
    r'"sha256":\s*"(?P<sha>[0-9a-f]{64})",\s*'
    r'"bytes":\s*(?P<bytes>\d+),'
)


def _own_release_pins(src: str) -> list[re.Match[str]]:
    """The `PINS` entries served from OUR release, not from an upstream host.

    Split out so the self-check below can feed it a synthetic table: a scanner
    only ever run against the file it already handles proves nothing.
    """
    return list(_OWN_PIN.finditer(src))


# It must pick our own release and leave upstream pins alone — a scanner that
# matched everything, or nothing, would make the claim below vacuous.
_PIN_PROBE = (
    '_AUTOSHADE_RELEASE = "https://example.invalid/releases/download/v9.8.7"\n'
    "PINS = {\n"
    '    "w.pth": {\n'
    '        "url": f"{_AUTOSHADE_RELEASE}/w.pth",\n'
    f'        "sha256": "{"a" * 64}",\n'
    '        "bytes": 1234567,\n'
    "    },\n"
    '    "upstream.py": {\n'
    '        "url": f"{_KAIR_RAW}/deadbeef/upstream.py",\n'
    f'        "sha256": "{"b" * 64}",\n'
    '        "bytes": 10,\n'
    "    },\n"
    "}\n"
)
assert [m.group("file") for m in _own_release_pins(_PIN_PROBE)] == ["w.pth"], (
    "own-release pin self-check: the scanner no longer separates our release from upstream"
)


def weight_pin(_args: argparse.Namespace) -> Truth:
    """The RAW denoiser weights: which release holds them, their size and hash.

    Every other entry in `PINS` is somebody else's file at somebody else's
    revision. This is the one we publish, and it is NOT a build product: no CI
    job re-cuts it, a human uploads it by hand. v1.5.0 shipped with that upload
    forgotten and every gate stayed green, because nothing compared README's
    asset table against the pin the sidecar actually enforces — so a cold-cache
    machine got a 404 where its denoiser should have been.

    The filename is read FROM the pin rather than written here, so renaming the
    weights (a v2 fine-tune would) moves the truth with them instead of leaving
    this extractor hunting a file that no longer exists.
    """
    src = text("python/denoise_raw.py")
    base = re.search(
        r'_AUTOSHADE_RELEASE = "[^"]+/v(?P<version>\d+\.\d+\.\d+)"', src
    )
    if not base:
        raise LookupError(
            'python/denoise_raw.py: no `_AUTOSHADE_RELEASE = "…/vX.Y.Z"` — the '
            "release the weights live in is no longer stated there"
        )
    own = _own_release_pins(src)
    if len(own) != 1:
        raise LookupError(
            f"python/denoise_raw.py: {len(own)} pin(s) served from our own release; "
            "this claim describes exactly one. Extend the row when a second lands "
            "(a v1 kept beside a v2 would be the obvious case)."
        )
    m = own[0]
    return Truth(
        (base.group("version"), f"{int(m.group('bytes')):,}", m.group("sha")),
        f"python/denoise_raw.py:{line_of(src, m.start())} (PINS[{m.group('key')!r}])",
    )


def release_version_only(v: tuple[str, ...]) -> tuple[str, ...]:
    """The prose link names the release and nothing else; compare just that."""
    return v[:1]


# ── The CLAIMS registry ─────────────────────────────────────────────────────


class Claim(NamedTuple):
    doc: str
    name: str
    pattern: str
    truth: Callable[[argparse.Namespace], Truth | Skip]
    norm: Callable[[tuple[str, ...]], tuple[str, ...]] = lambda v: v


class SetClaim(NamedTuple):
    """A coverage claim (a SET must be fully named), not a value claim."""

    doc: str
    name: str
    check: Callable[[argparse.Namespace], tuple[str, list[str]]]

    @property
    def pattern(self) -> str:
        return "(set-coverage check, no pattern)"


ARCH = "docs/ARCHITECTURE.md"
README = "README.md"
TECH = "docs/TECH_STACK.md"

CLAIMS: list[Claim | SetClaim] = [
    Claim(
        ARCH,
        "shipped version",
        r"Status: \*\*implemented\*\* \(v(?P<version>\d+\.\d+\.\d+)",
        cargo_version,
    ),
    Claim(
        ARCH,
        "test counts (lib/CLI/GUI/contract)",
        r"(?P<lib>\d+) library \+ (?P<cli>\d+) CLI \+ (?P<gui>\d+) GUI "
        r"\+ (?P<c1>\d+)\+(?P<c2>\d+) contract tests",
        battery_test_counts,
    ),
    Claim(
        ARCH,
        "battery numbers — ARCHITECTURE vs README",
        r"(?P<lib>\d+) library \+ (?P<cli>\d+) CLI \+ (?P<gui>\d+) GUI "
        r"\+ (?P<c1>\d+)\+(?P<c2>\d+) contract tests[\s\S]*?"
        r"library result is (?P<passed>\d+) pass \+ (?P<ignored>\d+) `#\[ignore\]`d",
        readme_battery_numbers,
    ),
    SetClaim(ARCH, "release-battery lanes", check_release_battery_lanes),
    Claim(
        ARCH,
        "RAW ext count — §4 milestone table",
        r"RAW decode \+ features \((?P<formats>\d+) formats",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        ARCH,
        "RAW ext count — §4.1 two-lists note",
        r"`decode::RAW_EXTS` \((?P<formats>\d+)\)",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        ARCH,
        "RAW ext count — §4.1 no-preview row",
        r"of the (?P<formats>\d+) formats",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        ARCH,
        "RAW ext count — §6 open question 2",
        r"(?P<formats>\d+) RAW extensions \(`decode::RAW_EXTS`\)",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        README,
        "RAW ext count — Tech line",
        r"RAW decode, (?P<formats>\d+) formats",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        ARCH,
        "baked ext count — §4.1 two-lists note",
        r"`pipeline::BAKED_EXTS` \((?P<baked>\d+)\)",
        ext_count("src/pipeline.rs", "const BAKED_EXTS"),
    ),
    Claim(
        ARCH,
        "baked ext count — §6 open question 2",
        r"\+ (?P<baked>\d+) baked \(`pipeline::BAKED_EXTS`\)",
        ext_count("src/pipeline.rs", "const BAKED_EXTS"),
    ),
    SetClaim(ARCH, "tech stack names every direct dependency", check_tech_stack),
    Claim(
        ARCH,
        "toolchain — §5 vs README Tech line",
        r"rustc/cargo \*\*(?P<toolchain>\d+(?:\.\d+)+)\*\*",
        toolchain_truth,
        major_minor,
    ),
    Claim(
        ARCH,
        "toolchain — §5 vs the rust-toolchain.toml pin (patch included)",
        r"rustc/cargo \*\*(?P<toolchain>\d+(?:\.\d+)+)\*\*",
        pinned_toolchain,
    ),
    # ── R28 doc-audit additions (2026-08-20): pin the maintained COPIES the
    # original 11 rows could not see — the audit found the bug template's
    # version dropdown had already drifted a whole release behind, which is
    # exactly the failure mode these rows exist to end. ────────────────────
    Claim(
        README,
        "shipped version — download link text",
        r"\[Download v(?P<version>\d+\.\d+\.\d+)\]",
        cargo_version,
    ),
    # The `9/9 at v<version>` alternative was dropped 2026-08-21. It pinned the
    # RAW zoo's COUNT to the shipped version, and those are two different kinds
    # of fact: the version is a doc copy of `Cargo.toml`, while the zoo count is
    # a MEASUREMENT of an environment-gated suite the release chain runs against
    # a corpus that does not ship with the source. Coupling them forced the
    # version bump to assert a result nobody had measured yet — the gate demands
    # the string, the string reads as a finding — which is the exact failure this
    # file exists to prevent, pointed the wrong way. The zoo count now stands
    # unversioned in README and is re-recorded per release (ROADMAP
    # 「发版链 + 环境门套件」: 数字每版实录, 勿抄上一版). The version copies that
    # ARE copies stay pinned below.
    Claim(
        README,
        "shipped version — download link URL + release-gates line",
        r"(?:releases/tag/v|Release gates at v)(?P<version>\d+\.\d+\.\d+)",
        cargo_version,
    ),
    Claim(
        ".github/ISSUE_TEMPLATE/bug_report.yml",
        "latest published version — bug template dropdown",
        r"- v(?P<version>\d+\.\d+\.\d+) \(latest release\)",
        latest_published_version,
    ),
    Claim(
        TECH,
        "test counts - Tech Stack release battery",
        r"(?P<lib>\d+) library \((?:\d+ pass \+ )?\d+ `#\[ignore\]`d forensic\s+probes\) / "
        r"(?P<cli>\d+) CLI / (?P<gui>\d+) GUI / (?P<c1>\d+)\+(?P<c2>\d+) contract",
        battery_test_counts,
    ),
    Claim(
        README,
        "test counts — Release gates list",
        r"(?P<lib>\d+) library \((?:\d+ pass \+ )?\d+ `#\[ignore\]`d forensic probes\) / "
        r"(?P<cli>\d+) CLI / (?P<gui>\d+) GUI / (?P<c1>\d+)\+(?P<c2>\d+) contract",
        battery_test_counts,
    ),
    # The headline evidence table states the same counts in a SHORTER shape,
    # with no "(N pass + N ignored)" clause, so neither regex above could ever
    # match it -- and it silently drifted to 1191/22/151 while every other
    # mention moved. A claim of its own is the only thing that stops that
    # happening again.
    Claim(
        README,
        "test counts — headline evidence table",
        r"Automated test battery \| (?P<lib>\d+) library / (?P<cli>\d+) CLI / "
        r"(?P<gui>\d+) GUI / (?P<c1>\d+)\+(?P<c2>\d+) contract tests",
        battery_test_counts,
    ),
    Claim(
        ARCH,
        "camera models — §4 + §5 (all mentions must agree)",
        r"(?P<models>\d+) camera models",
        camera_model_count,
    ),
    Claim(
        README,
        "camera models — Decoding line",
        r"carries \*\*(?P<models>\d+) camera models\*\*",
        camera_model_count,
    ),
    Claim(
        README,
        "camera models — Tech line (bodies)",
        r"(?P<models>\d+) bodies",
        camera_model_count,
    ),
    Claim(
        ".github/ISSUE_TEMPLATE/bug_report.yml",
        "camera models — bug template",
        r"rawler carries (?P<models>\d+) camera models",
        camera_model_count,
    ),
    Claim(
        README,
        "RAW ext count — formats header",
        r"Camera RAW — (?P<formats>\d+) extensions",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        README,
        "RAW ext count — no-preview sentence",
        r"of the (?P<formats>\d+) formats store none",
        ext_count("src/decode.rs", "const RAW_EXTS"),
    ),
    Claim(
        README,
        "baked ext count — formats header",
        r"Baked rasters — (?P<baked>\d+) extensions",
        ext_count("src/pipeline.rs", "const BAKED_EXTS"),
    ),
    SetClaim(README, "RAW extension membership", check_readme_raw_ext_membership),
    SetClaim(README, "no-preview format membership", check_readme_no_preview_membership),
    Claim(
        "src/xmp/mask_xml.rs",
        "active XMP census",
        r"Current corpus re-derivation: (?P<sidecars>\d+) sidecars; "
        r"(?P<aggregate>\d+) Mask/Aggregate;\s*"
        r"(?P<mask_image>\d+)\s*///\s*Mask/Image; (?P<mask_paint>\d+) Mask/Paint; "
        r"(?P<mask_any>\d+) Mask/\*; (?P<gesture>\d+) crs:Gesture",
        census_counts,
    ),
    # The weights are the only asset a human uploads by hand, and until now the
    # only published number no gate re-derived. v1.5.0 is the precedent: the
    # upload was missed, AI denoise was broken on every cold cache, and the whole
    # battery was green. These two rows read the pin the sidecar enforces.
    Claim(
        README,
        "RAW denoiser weights — asset table (release, size, SHA-256)",
        r"\| `[^`]+\.pth` \(RAW denoiser weights, fetched on demand from the "
        r"v(?P<version>\d+\.\d+\.\d+) release\) \| (?P<size>[\d,]+) bytes \| "
        r"`(?P<sha>[0-9a-f]{64})` \|",
        weight_pin,
    ),
    Claim(
        README,
        "RAW denoiser weights — the release the prose sends you to",
        r"releases/download/v(?P<version>\d+\.\d+\.\d+)/[^`)\s]+\.pth",
        weight_pin,
        release_version_only,
    ),
]


# ── Runner ──────────────────────────────────────────────────────────────────


def show(v: tuple[str, ...]) -> str:
    return " + ".join(v)


def run_claim(row: Claim, args: argparse.Namespace) -> tuple[str, list[str]]:
    doc = text(row.doc)
    hits = list(re.finditer(row.pattern, doc))
    if not hits:
        # NOT a skip: see the module docstring. A pattern that stopped matching
        # is a claim site that moved, and the gate must be re-anchored on the
        # new wording before it can vouch for anything again.
        return "FAIL", [
            f"        pattern matches NOTHING in {row.doc} — claim site moved;"
            " re-anchor the gate",
            f"        pattern  {row.pattern}",
        ]
    try:
        t = row.truth(args)
    except LookupError as e:
        return "FAIL", [f"        truth extractor failed: {e}"]
    if isinstance(t, Skip):
        return "SKIP", [f"        {t.reason}"]
    want = row.norm(t.value)
    bad = [(m, row.norm(tuple(m.groups()))) for m in hits]
    bad = [(m, got) for m, got in bad if got != want]
    if bad:
        out = [f"        truth    {show(t.value)}   ({t.source})"]
        for m, got in bad:
            out.append(
                f"        doc      {show(tuple(m.groups()))}   "
                f"({row.doc}:{line_of(doc, m.start())})"
            )
        return "FAIL", out
    where = ", ".join(f"{row.doc}:{line_of(doc, m.start())}" for m in hits)
    return "PASS", [f"        {show(t.value)}   ({where})"]


def main() -> int:
    # Windows consoles default to the ANSI codepage; doc values quoted back can
    # carry the section signs and CJK these docs mix in.
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    ap.add_argument(
        "--gates",
        metavar="FILE",
        help="release-battery transcript (=== test default === / === test gui "
             "=== blocks). Without it the test-count row SKIPS.",
    )
    ap.add_argument(
        "--list", action="store_true", help="print the claims registry and exit"
    )
    ap.add_argument(
        "-v", "--verbose", action="store_true",
        help="print the detail line for PASS rows too",
    )
    args = ap.parse_args()

    if args.list:
        print(f"{len(CLAIMS)} claims:")
        for row in CLAIMS:
            print(f"  {row.doc:<22} {row.name}")
            print(f"  {'':<22} {row.pattern}")
        return 0

    print(f"doc-drift gate over {REPO.name}/ — "
          f"gates transcript: {args.gates or '(none, test counts will SKIP)'}\n")
    tally = {"PASS": 0, "FAIL": 0, "SKIP": 0}
    for row in CLAIMS:
        if isinstance(row, SetClaim):
            try:
                status, detail = row.check(args)
            except LookupError as e:
                status, detail = "FAIL", [f"        check failed: {e}"]
        else:
            status, detail = run_claim(row, args)
        tally[status] += 1
        print(f"{status}  {row.name}")
        if status != "PASS" or args.verbose:
            for line in detail:
                print(line)
    print(f"\n{len(CLAIMS)} claims: {tally['PASS']} PASS, {tally['FAIL']} FAIL, "
          f"{tally['SKIP']} SKIP")
    return 1 if tally["FAIL"] else 0


if __name__ == "__main__":
    sys.exit(main())