How this guide stays true

def snippet(keys: dict, bare: list) -> Piece:
    rel = keys.get("path") or (bare[0] if bare else "")
    code, first, last = extract(rel, keys.get("symbol", ""), keys.get("marker", ""))
    lang = keys.get("lang") or LANGS.get(Path(rel).suffix, "text")
    what = keys.get("symbol") or keys.get("marker") or ""
    where = f"line {first}" if first == last else f"lines {first}–{last}"
    # (a long path or name may break after a slash or a dot, so a phone's narrow caption wraps it rather than cutting it off)
    path = html.escape(rel).replace("/", "/<wbr>")
    name = html.escape(what).replace(".", ".<wbr>")
    caption = (
        f'<figcaption><code class="g-path">{path}</code>'
        f'<span class="g-where">{name + " · " if what else ""}{where}</span></figcaption>'
    )
    note = f'<p class="g-code-note">{html.escape(keys["note"])}</p>' if keys.get("note") else ""
    body = f'<pre tabindex="0"><code class="hl language-{html.escape(lang)}">{highlight(code, lang)}</code></pre>'
    return Piece(html=f'<figure class="g-code" data-source="{html.escape(rel)}">{caption}{body}{note}</figure>', block=True)

def py_symbol(text: str, symbol: str, rel: str) -> tuple[int, int]:
    """(first line, last line), 1-based, of a Python name."""
    try:
        tree = ast.parse(text)
    except SyntaxError as e:
        raise DirectiveError(f"{rel} doesn't parse: {e}") from None
    body, node = tree.body, None
    for part in symbol.split("."):
        node = None
        for n in body:
            if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)) and n.name == part:
                node = n
            elif isinstance(n, ast.Assign) and any(isinstance(t, ast.Name) and t.id == part for t in n.targets):
                node = n
            elif isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name) and n.target.id == part:
                node = n
        if node is None:
            raise DirectiveError(f"{rel} has no {symbol!r}")
        body = getattr(node, "body", [])
    first = min([node.lineno] + [d.lineno for d in getattr(node, "decorator_list", [])])
    lines = text.split("\n")
    first = _leading_comments(lines, first - 1, js=False) + 1
    return first, node.end_lineno

def css_tokens(text: str) -> list[tuple[str, str, str, str]]:
    """Every custom property a stylesheet declares, in order: (the @media
    it's under, "" for none; its rule's selector; its name; its value)."""
    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
    out: list[tuple[str, str, str, str]] = []
    stack: list[str] = []
    buf: list[str] = []
    quote, depth = "", 0

    def declare(chunk: str, selector: str):
        media = " and ".join(p[len("@media"):].strip() for p in stack if p.startswith("@media"))
        for d in _split(chunk, ";"):
            name, colon, val = d.partition(":")
            if colon and name.strip().startswith("--"):
                out.append((media, selector, name.strip(), " ".join(val.split())))

    for ch in text:
        if quote:
            buf.append(ch)
            if ch == quote:
                quote = ""
            continue
        if ch in "\"'":
            quote = ch
        elif ch == "(":
            depth += 1
        elif ch == ")":
            depth -= 1
        elif ch == "{" and not depth:
            *before, prelude = _split("".join(buf), ";") or [""]
            if before and stack:
                declare(";".join(before), stack[-1])
            stack.append(" ".join(prelude.split()))
            buf = []
            continue
        elif ch == "}" and not depth:
            declare("".join(buf), stack.pop() if stack else "")
            buf = []
            continue
        buf.append(ch)
    return out

def fingerprint(paths: list[str]) -> str:
    h = hashlib.sha256()
    for p in paths:
        h.update(f"{blob(p)} {p}\n".encode())
    return h.hexdigest()[:12]

def changed_since(chapter: Chapter, fresh: Freshness) -> tuple[str | None, list[tuple[str, str]]]:
    """(the commit to diff from, [(path, how)]): what changed in the covered
    files since the stamp was committed. Without a commit (a stamp not yet
    committed, a shallow clone, no git), every covered file is listed."""
    commit = stamped_at(chapter)
    if commit:
        then = _git("ls-tree", "-r", "--name-only", commit) or ""
        then_files = [f for f in then.split("\n") if f]
        before = set(covered(chapter, then_files)[0])
        now = set(fresh.files)
        out = []
        diff = _git("diff", "--name-only", commit, "--", *sorted(before & now)) if before & now else ""
        for f in sorted(x for x in (diff or "").split("\n") if x):
            out.append((f, "changed"))
        out += [(f, "new") for f in sorted(now - before)]
        out += [(f, "removed") for f in sorted(before - now)]
        if out:
            return commit, out
    return commit, [(f, "covered") for f in fresh.files]

def run(today: date | None = None, freshness: bool = True) -> Report:
    from games.catalog import GAMES

    today = today or date.today()
    report = Report()
    for path in chapter_files():
        try:
            report.chapters.append(load(path))
        except FrontMatterError as e:
            report.problems.append(f"✖ {path.relative_to(ROOT)}: {e}")
    chapters = sorted(report.chapters, key=lambda c: (c.order, c.slug))
    by_slug = {c.slug: c for c in chapters}
    anchors, rendered = {}, {}
    for ch in chapters:
        r = render(ch, debug=True)
        rendered[ch.slug] = r
        anchors[ch.slug] = {s.id for s in r.sections if s.id}
        report.directives += len(re.findall(r"(?<!\\)\{\{[a-z]+", ch.body))
        for p in r.problems:
            report.problems.append(f"✖ {ch.rel}, {p}")

    # Links between chapters land somewhere.
    for ch in chapters:
        for href in rendered[ch.slug].links:
            if href.startswith("#"):
                target, anchor = ch.slug, href[1:]
            elif href.startswith("/guide/"):
                rest = href[len("/guide/"):]
                target, _, anchor = rest.partition("#")
                target = target.strip("/")
                if not target:
                    continue
            else:
                continue
            if target not in by_slug:
                report.problems.append(f"✖ {ch.rel} links to {href}, but there's no chapter {target!r}")
            elif anchor and anchor not in anchors[target]:
                report.problems.append(f"✖ {ch.rel} links to {href}, but {target} has no heading #{anchor}")

    # Every game has a chapter.
    games = {c.game: c for c in chapters if c.game}
    for c in chapters:
        if c.game and c.slug != f"games/{c.game}":
            report.problems.append(f"✖ {c.rel}: a game's chapter is docs/guide/games/{c.game}.md")
        if c.slug.startswith("games/") and not c.game:
            report.problems.append(f"✖ {c.rel}: a chapter under games/ says which game it is (`game: <slug>`)")
    for game in GAMES:
        if game.slug not in games:
            report.problems.append(
                f"✖ {game.title} ({game.slug}) has no chapter: write docs/guide/games/{game.slug}.md "
                f"(docs/guide/README.md, \"A game's chapter\")"
            )
    known = {g.slug for g in GAMES}
    for slug, c in games.items():
        if slug not in known:
            report.problems.append(f"✖ {c.rel}: there's no game {slug!r} in games/catalog.py")

    # Stubs, and every written chapter true to its code.
    files = coverage.repo_files() if freshness else []
    for ch in chapters:
        if ch.status not in ("written", "stub"):
            report.problems.append(f"✖ {ch.rel}: status is `written` (the default) or `stub`, not {ch.status!r}")
            continue
        if ch.stub:
            report.stubs += 1
            if not ch.game:
                report.problems.append(f"✖ {ch.rel}: only a game's chapter may be a stub")
            elif today > STUBS_UNTIL:
                report.problems.append(f"✖ {ch.rel} is still a stub, and stubs were allowed until {STUBS_UNTIL}: write it")
            continue
        if not ch.covers:
            report.problems.append(f"✖ {ch.rel}: a written chapter says what code it covers (`covers:`)")
            continue
        if not freshness:
            continue
        fresh = coverage.freshness(ch, files)
        if fresh.empty:
            report.problems.append(f"✖ {ch.rel}: covers {', '.join(fresh.empty)}, which match no files")
        if ch.reviewed and not re.fullmatch(r"\d{4}-\d{2}-\d{2} [0-9a-f]{12}", ch.reviewed):
            report.problems.append(f"✖ {ch.rel}: `reviewed:` is a date and a hash, set by npm run guide:stamp {ch.slug}")
        elif not fresh.fresh:
            report.stale.append(ch.slug)
            report.problems.append(_stale_message(ch, fresh))
    return report

/** The last line of every game's How to play: a quiet link to how it works,
 * for the curious ("Technical guide: how Hashi works"). Null where the
 * game has no chapter to link to. */
export function guideLink(title, path) {
  const href = guideHref(path);
  return href ? h('p.house-guide', h('a', { href }, `Technical guide: how ${title} works`)) : null;
}

/** Where a game's chapter of the technical guide is (docs/adr/0035): its
 * slug from this page's address, /games/<slug>/…, so a game served
 * anywhere else (The Register outside the hub) has none. */
export function guideHref(path = globalThis.location?.pathname || '') {
  const slug = /^\/games\/([a-z0-9-]+)\//.exec(path)?.[1];
  return slug ? `/guide/games/${slug}/` : null;
}