Skip to content

A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.

23.6 KB
Raw Blame
# /// script
# requires-python = ">=3.11"
# dependencies = ["pyyaml==6.0.3"]
# ///
"""Lists the content that no named person has reviewed yet and that an AI agent may have checked (CONTENT_POLICY
section 2, rule 6), so the owner can work through it: docs/review-queue.md.

Read-only on content/ and translations/: it parses the YAML and asks git, and writes only the Markdown page (or prints it).

Two kinds of entry:

1. **Agent-checked Hebrew names**: every `*_review: agent-checked` flag (`name_he_review`, `title_he_review`,
   `title_he_f_review`, `body_he_review`; #564), and every `review: agent-checked` entry of translations/he/content.yaml
   and events.yaml, where the Hebrew moves (#1618), listed with its English record's row and sources. The flag itself
   says no person has read the name.
2. **Reviewed statuses last written by a commit with an AI co-author trailer**: every row whose `status` is
   `fact-checked`, `historian-reviewed` or `sensitivity-reviewed`, where the line that holds that status was last
   written by such a commit.

The heuristic for (2), because content has no reviewer field: `docs/HISTORIAN_REVIEW.md` keeps the reviewer's record in
the pull request, not in the YAML (no `reviewed_by` key), so the only signal in the repository is git history. For each
such status line, `git blame` on the working-tree file (the text this script reads, so a deleted flag or another
uncommitted edit does not shift the lines), with `-w -M`, gives the commit that last wrote it; a file git does not track
yet is read too, and every row in it counts as not committed. A commit counts when its message has an AI co-author trailer or the Claude Code line ("Co-Authored-By:
Claude ...", "Co-Authored-By: ... Codex / Copilot / GPT ...", "Generated with [Claude Code]", "Generated with Codex").
A row that carries a person's whole sign-off beside its status (`reviewed_by`, a GitHub handle, and `reviewed_on`, a day;
owner, 15 October 2026, #375: "Yes, humans only"; tools/review_record.py) leaves the queue and is counted as signed off,
whatever wrote its status line; a malformed sign-off does not count (fail closed). Any other such row is listed with
the commit and its pull request number. A status line not committed yet is listed too, as
"not committed yet": no commit vouches for it, so the queue fails closed. Any other row is counted, not listed.

Limits, said plainly, and on the page too:
- **Over-inclusive.** An agent-co-written commit may only record a person's decision (the owner's sensitivity sign-offs
  are recorded that way), and a person may have reviewed an agent's row and merged it without touching the line. Both
  stay listed: the list is "not shown to be human-reviewed", not "checked by an agent".
- **Blind spots.** An agent whose commits carry none of these trailers (another tool, or an outside contributor who does
  not mark AI use) counts as a person; a person who set a status without checking is not caught.
- **Edits that move the blame.** Blame ignores whitespace (`-w`) and follows lines moved within a file (`-M`), so a
  re-indent or a re-spacing keeps the earlier author. It cannot see through a key reordering that moves too little text
  for `-M` to match (git needs about 20 characters), nor a reflow between flow style (`{ id: x, status: ... }`) and block
  style: the commit that did either becomes the line's author.
- **History.** A shallow clone blames every line on its one commit, so the script refuses one (exit 2). The page names
  the commit it was generated from.

Usage: uv run tools/review_queue.py [--write]   (prints the page; --write writes docs/review-queue.md)
"""
from __future__ import annotations

import argparse
import re
import subprocess
import sys
from dataclasses import dataclass, field
from pathlib import Path

import yaml

sys.path.insert(0, str(Path(__file__).resolve().parent))  # under python -I the script's folder is not on sys.path
import review_record  # noqa: E402
import yaml12  # noqa: E402

ROOT = Path(__file__).resolve().parents[1]
PAGE = ROOT / "docs" / "review-queue.md"
STATUSES = ("fact-checked", "historian-reviewed", "sensitivity-reviewed")
FLAG = "agent-checked"
FLAG_KEY = re.compile(r"^(?P<field>[a-z_]+_he(?:_f)?)_review$")
AI_MARK = re.compile(r"co-authored-by:[^\n]*(claude|codex|copilot|gpt)|generated with \[?(claude code|codex)", re.I)
PR_NUMBER = re.compile(r"\(#(\d+)\)\s*$")


@dataclass
class Commit:
    sha: str
    author: str
    subject: str
    agent: bool

    @property
    def pr(self) -> str:
        m = PR_NUMBER.search(self.subject)
        return f"#{m.group(1)}" if m else ""

    def describe(self) -> str:
        """The commit, not a verdict on who checked the row: an agent-co-written commit may only record a person's
        decision (the owner's sensitivity sign-offs are recorded that way)."""
        who = "a commit with an AI co-author trailer" if self.agent else f"a commit by {self.author}"
        where = f"PR {self.pr}" if self.pr else f"commit {self.sha[:8]}"
        subject = PR_NUMBER.sub("", self.subject).rstrip()
        if len(subject) > 80:
            subject = subject[:79].rstrip() + "…"
        return f"{who} ({where}: {subject})"


@dataclass
class Entry:
    kind: str            # "flag" or "status"
    file: str            # path relative to the repository root
    line: int            # 1-based line of the flag or the status
    row: str             # the row's id (or its position)
    field: str           # the field to review
    value: str
    sources: list[str] = field(default_factory=list)
    checked_by: str = ""


def _scalar(node) -> str:
    return node.value if isinstance(node, yaml.ScalarNode) else ""


def _value(node):
    """A scalar's text (None for a YAML null), or the node itself when it is not a scalar (never a valid sign-off)."""
    if not isinstance(node, yaml.ScalarNode):
        return node
    return None if node.tag.endswith(":null") else node.value


def _urls(node) -> list[str]:
    """Every https URL under a node, in order (a `sources` list of strings or of {url, checked} maps)."""
    out: list[str] = []
    if isinstance(node, yaml.ScalarNode):
        if node.value.startswith("https://"):
            out.append(node.value)
    elif isinstance(node, yaml.SequenceNode):
        for n in node.value:
            out += _urls(n)
    elif isinstance(node, yaml.MappingNode):
        for _, v in node.value:
            out += _urls(v)
    return out


def _rows(node, path: str = ""):
    """Every mapping in the document with a label: its id, else its place in the tree."""
    if isinstance(node, yaml.MappingNode):
        keys = {_scalar(k): v for k, v in node.value}
        label = _scalar(keys["id"]) if "id" in keys else path or "(file)"
        yield label, keys
        for k, v in node.value:
            yield from _rows(v, f"{path}.{_scalar(k)}" if path else _scalar(k))
    elif isinstance(node, yaml.SequenceNode):
        for i, v in enumerate(node.value):
            yield from _rows(v, f"{path}[{i}]")


def _mappings(node, path: str = ""):
    """Every mapping node in the document with its label (as _rows)."""
    if isinstance(node, yaml.MappingNode):
        keys = {_scalar(k): v for k, v in node.value}
        yield (_scalar(keys["id"]) if "id" in keys else path or "(file)"), keys, node
        for k, v in node.value:
            yield from _mappings(v, f"{path}.{_scalar(k)}" if path else _scalar(k))
    elif isinstance(node, yaml.SequenceNode):
        for i, v in enumerate(node.value):
            yield from _mappings(v, f"{path}[{i}]")


@dataclass
class SignedRow:
    label: str
    first: int        # 1-based lines the row's mapping spans, inclusive
    last: int
    key_column: int   # 0-based column of its keys (a line inserted at this indent or deeper, right after it, belongs to it)
    flow: bool        # a one-line { ... } row: nothing inserted after it belongs to it
    # 1-based inclusive spans of nodes the row pulls in from elsewhere through an alias or a merge key (`*a`, `<<: *d`):
    # editing the anchor changes the row as surely as editing the row (people.yaml shares source anchors across rows).
    extra: list = field(default_factory=list)


def signed_rows(text: str) -> list[SignedRow]:
    """The rows of a YAML text that carry a person's whole sign-off (#375), with their line spans. Raises yaml.YAMLError on
    text that is not YAML."""
    root = yaml.compose(text)
    if root is None:
        return []
    lines = text.splitlines()

    def last_line(n) -> int:
        end = n.end_mark
        before = lines[end.line][:end.column] if end.line < len(lines) else ""
        return (end.line - 1 if before.strip() == "" else end.line) + 1

    out = []
    for label, keys, node in _mappings(root):
        if "reviewed_by" not in keys or not review_record.signed({k: _value(keys[k]) for k in review_record.FIELDS if k in keys}):
            continue
        first, last = node.start_mark.line + 1, last_line(node)
        extra, seen, todo = [], set(), [node]
        while todo:   # every node the row reaches; one whose text lies outside the row came in through an alias
            n = todo.pop()
            if id(n) in seen:
                continue
            seen.add(id(n))
            a, b = n.start_mark.line + 1, last_line(n)
            if a < first or a > last:
                extra.append((a, max(a, b)))
            if isinstance(n, yaml.MappingNode):
                todo.extend(v for kv in n.value for v in kv)
            elif isinstance(n, yaml.SequenceNode):
                todo.extend(n.value)
        out.append(SignedRow(label, first, last, node.start_mark.column, bool(node.flow_style), sorted(set(extra))))
    return out


def _compose(text: str, rel: str):
    """The YAML node tree of a file's text; text that is not YAML is a QueueError naming the file and line (#2532)."""
    try:
        return yaml.compose(text)
    except yaml.YAMLError as e:
        raise QueueError(yaml12.not_yaml(rel, e)) from e


def scan(text: str, rel: str) -> list[Entry]:
    """The flags and the reviewed statuses in one YAML file, with their lines; no git. Raises QueueError on text that is
    not YAML."""
    root = _compose(text, rel)
    entries: list[Entry] = []
    if root is None:
        return entries
    for label, keys in _rows(root):
        for key, node in keys.items():
            m = FLAG_KEY.match(key)
            if m and _scalar(node) == FLAG:
                name = m.group("field")
                entries.append(Entry("flag", rel, node.start_mark.line + 1, label, name, _scalar(keys.get(name)) if name in keys else "",
                                     _field_sources(keys, name)))
        status = keys.get("status")
        if status is not None and _scalar(status) in STATUSES:
            # A whole sign-off by a person (#375) takes the row out of the queue; a malformed one does not (fail closed).
            signoff = {k: _value(keys[k]) for k in review_record.FIELDS if k in keys}
            entries.append(Entry("signed" if review_record.signed(signoff) else "status", rel, status.start_mark.line + 1, label,
                                 "status", _scalar(status), _urls(keys["sources"]) if "sources" in keys else []))
    return entries


def _field_sources(keys: dict, name: str) -> list[str]:
    """The source URLs of a Hebrew field (name_he ...), kept on its English record: <field>_sources, or, for people,
    biography_sources.<field> (content/people.yaml)."""
    source_node = keys.get(name + "_sources")
    if source_node is None and isinstance(keys.get("biography_sources"), yaml.MappingNode):
        source_node = {_scalar(k): v for k, v in keys["biography_sources"].value}.get(name)
    return _urls(source_node) if source_node is not None else []


def _records(node, ids: tuple = ()):
    """Every mapping under node with its key path, as tools/translate.py keys content: a list item by its id, else its
    index."""
    if isinstance(node, yaml.MappingNode):
        yield ids, node
        for k, v in node.value:
            yield from _records(v, ids + (_scalar(k),))
    elif isinstance(node, yaml.SequenceNode):
        for i, item in enumerate(node.value):
            ident = next((v.value for k, v in item.value if _scalar(k) == "id" and isinstance(v, yaml.ScalarNode)), None) \
                if isinstance(item, yaml.MappingNode) else None
            yield from _records(item, ids + (ident if ident is not None else str(i),))


HE_TRANSLATIONS = ("translations/he/content.yaml", "translations/he/events.yaml")


def scan_translations(repo: Path, rel: str) -> list[Entry]:
    """The agent-checked flags of a translations/he/ file (#1618; docs/translations.md): each entry whose `review` is
    agent-checked, listed as the inline flag it replaces, with the row and sources of its English record (the sources stay
    there): a content entry's record by its key; an event's by its id, with its text_he_sources, else the event's own
    sources."""
    root = _compose((repo / rel).read_text(encoding="utf-8"), rel)
    entries: list[Entry] = []
    parsed: dict[str, dict] = {}
    events: dict[str, dict] | None = None
    for k, v in root.value if isinstance(root, yaml.MappingNode) else []:
        keys = {_scalar(a): b for a, b in v.value} if isinstance(v, yaml.MappingNode) else {}
        if _scalar(keys.get("review")) != FLAG:
            continue
        key, line = _scalar(k), keys["review"].start_mark.line + 1
        if rel.endswith("events.yaml"):
            if events is None:
                events = {}
                for path in sorted((repo / "content" / "events").glob("*.yaml")):
                    tree = _compose(path.read_text(encoding="utf-8"), path.relative_to(repo).as_posix())
                    top = {_scalar(a): b for a, b in tree.value} if isinstance(tree, yaml.MappingNode) else {}
                    if "id" in top:
                        events[_scalar(top["id"])] = top
            event = events.get(key, {})
            sources = _field_sources(event, "text_he") or (_urls(event["sources"]) if "sources" in event else [])
            entries.append(Entry("flag", rel, line, key, "text_he", _scalar(keys.get("text")), sources))
            continue
        file, _, rest = key.partition("#")
        where, _, name = rest.rpartition(".")
        if file not in parsed:
            path = repo / "content" / file
            tree = _compose(path.read_text(encoding="utf-8"), path.relative_to(repo).as_posix()) if path.is_file() else None
            parsed[file] = {".".join(ids): n for ids, n in _records(tree)}
        record = parsed[file].get(where)
        fields = {_scalar(a): b for a, b in record.value} if record is not None else {}
        he = name.removesuffix("_f") + "_he" + ("_f" if name.endswith("_f") else "")
        label = _scalar(fields["id"]) if "id" in fields else where
        entries.append(Entry("flag", rel, line, label, he, _scalar(keys.get("text")), _field_sources(fields, he)))
    return entries


def _git(args: list[str], cwd: Path) -> str:
    return subprocess.run(["git", *args], cwd=cwd, check=True, capture_output=True, text=True).stdout


UNCOMMITTED = "0" * 40


def blame(repo: Path, rel: str) -> dict[int, str]:
    """Line number of the working-tree file (the text scan() reads) to the sha of the commit that last wrote it; a line
    not committed yet maps to UNCOMMITTED. Blaming HEAD instead would misplace every line after an uncommitted edit, such
    as a reviewer's deleted flag (second review of #611)."""
    # -w: a whitespace-only change (re-spacing, re-indenting) is not a review, so it keeps the earlier author; -M: a line
    # moved within the file keeps its author too (independent re-review of #611).
    out, lines, sha = _git(["blame", "-w", "-M", "--line-porcelain", "--", rel], repo), {}, ""
    for row in out.splitlines():
        m = re.match(r"^([0-9a-f]{40}) \d+ (\d+)", row)
        if m:
            sha = m.group(1)
            lines[int(m.group(2))] = sha
    return lines


def commit(repo: Path, sha: str, cache: dict[str, Commit]) -> Commit:
    if sha == UNCOMMITTED:
        return Commit(sha, "nobody yet", "not committed yet", False)
    if sha not in cache:
        author, subject, body = _git(["log", "-1", "--format=%an%x00%s%x00%B", sha], repo).split("\x00", 2)
        cache[sha] = Commit(sha, author, subject, bool(AI_MARK.search(body)))
    return cache[sha]


class QueueError(Exception):
    """The working tree cannot be read as the page needs (run() prints it and exits 2)."""


def content_files(repo: Path) -> tuple[list[str], set[str]]:
    """Every YAML file under content/, in ordinal order: the tracked ones and the untracked ones git does not ignore (a new
    file is content too; independent re-review of #611); and the set of untracked ones. A tracked file missing from the
    working tree (a plain mv not yet committed) is an error, not a silent gap."""
    tracked = [f for f in _git(["ls-files", "content"], repo).splitlines() if f.endswith(".yaml")]
    missing = [f for f in tracked if not (repo / f).exists()]
    if missing:
        raise QueueError(f"{', '.join(missing)}: tracked but missing from the working tree (moved or deleted?); commit the "
                         "move or restore the file, then rerun")
    untracked = {f for f in _git(["ls-files", "--others", "--exclude-standard", "content"], repo).splitlines() if f.endswith(".yaml")}
    return sorted(set(tracked) | untracked), untracked


def queue(repo: Path) -> tuple[list[Entry], int, int]:
    """The entries to review; how many reviewed statuses were last written by a commit with no agent marker (not listed);
    and how many rows a person signed off (reviewed_by and reviewed_on, #375; not listed)."""
    cache: dict[str, Commit] = {}
    entries: list[Entry] = []
    human = signed = 0
    files, untracked = content_files(repo)
    for rel in files:
        found = scan((repo / rel).read_text(encoding="utf-8"), rel)
        if not found:
            continue
        lines = {e.line: UNCOMMITTED for e in found} if rel in untracked else blame(repo, rel)
        for e in found:
            if e.kind == "signed":
                signed += 1
                continue
            c = commit(repo, lines[e.line], cache)
            if e.kind == "flag":
                e.checked_by = f"an AI agent (the `{FLAG}` flag)"
                entries.append(e)
            elif c.sha == UNCOMMITTED:   # no commit vouches for it yet: list it, never hide it (fail closed)
                e.checked_by = "not committed yet"
                entries.append(e)
            elif c.agent:
                e.checked_by = c.describe()
                entries.append(e)
            else:
                human += 1
    for rel in HE_TRANSLATIONS:
        if (repo / rel).is_file():
            for e in scan_translations(repo, rel):
                e.checked_by = f"an AI agent (the `{FLAG}` flag)"
                entries.append(e)
    return entries, human, signed


def _cell(text: str) -> str:
    return text.replace("|", "\\|").replace("\n", " ")


def page(entries: list[Entry], human: int, head: str, signed: int = 0) -> str:
    flags = [e for e in entries if e.kind == "flag"]
    statuses = [e for e in entries if e.kind == "status"]
    out = [
        "# Human-review queue",
        "",
        f"Generated by `uv run tools/review_queue.py --write` at commit `{head[:8]}`. Do not edit by hand: rerun the tool.",
        "It changes no status. Clearing an entry is a content change in its own pull request: a native speaker deletes a",
        "name's `*_review: agent-checked` line once they have read it against its source (#564); a person who has checked",
        "every claim of a listed row signs it off beside its status with `reviewed_by` (their GitHub handle) and",
        "`reviewed_on` (the day), as `docs/HISTORIAN_REVIEW.md` describes; only a person writes those (#375). An AI-assisted",
        "contributor may do either when the pull request discloses the AI help and names the check, and never removes a",
        "sign-off (owner, 4 November 2026; CONTENT_POLICY.md, section 2, rules 6 and 7).",
        "",
        "**This list is over-inclusive, and it is not a verdict on who checked anything.** The second table lists every",
        "reviewed status whose line was last written by a commit with an AI co-author trailer. Some of those record a",
        "person's decision that an agent only typed in, such as the owner's sensitivity sign-offs; they are listed",
        "anyway until a person signs them off with `reviewed_by` and `reviewed_on`, the only reviewer record the queue",
        "reads. It also misses things: an agent whose commits carry no such trailer (another tool, or an",
        "outside contributor who does not mark AI use) is counted as a person, and a person who set a status without",
        "checking is not caught. Blame ignores whitespace and follows moved lines, but a key reordering too small for git",
        "to match, or a reflow between flow and block style, makes that commit the line's author. The heuristic in full:",
        "[tools/review_queue.py](../tools/review_queue.py)",
        "([CONTENT_POLICY.md](CONTENT_POLICY.md), section 2, rule 6).",
        "",
        f"- Hebrew names flagged `{FLAG}`: **{len(flags)}**",
        f"- `fact-checked`, `historian-reviewed` or `sensitivity-reviewed` statuses last written by a commit with an AI "
        f"co-author trailer, or not committed yet: **{len(statuses)}**",
        f"- the same statuses last written by a commit without one (not listed): {human}",
        f"- signed off by a person (`reviewed_by` and `reviewed_on`; not listed): {signed}",
        "",
    ]
    for title, items, cols in (
        ("Hebrew names to review (#564)", flags, ("Line", "Row", "Field", "Value", "Sources", "Checked by")),
        ("Reviewed statuses last written by a commit with an AI co-author trailer, or not committed yet", statuses,
         ("Line", "Row", "Status", "Sources", "Last written by")),
    ):
        out += [f"## {title}", ""]
        if not items:
            out += ["None.", ""]
            continue
        for rel in sorted({e.file for e in items}):
            rows = [e for e in items if e.file == rel]
            out += [f"### [{rel}](../{rel}) ({len(rows)})", "", "| " + " | ".join(cols) + " |", "|" + "---|" * len(cols)]
            for e in rows:
                src = "<br>".join(f"<{u}>" for u in e.sources) or "(none in the row)"
                link = f"[{e.line}](../{e.file}#L{e.line})"
                cells = [link, e.row, e.field, e.value, src, e.checked_by] if e.kind == "flag" else [link, e.row, e.value, src, e.checked_by]
                out.append("| " + " | ".join(_cell(c) for c in cells) + " |")
            out.append("")
    return "\n".join(out).rstrip("\n") + "\n"


def run(repo: Path, write: bool) -> int:
    """Prints the page for <repo>, or writes it to its docs/review-queue.md; 2 on a shallow clone."""
    if _git(["rev-parse", "--is-shallow-repository"], repo).strip() == "true":
        print("review_queue: a shallow clone blames every line on one commit; run it on a full clone", file=sys.stderr)
        return 2
    try:
        entries, human, signed = queue(repo)
    except QueueError as e:
        print(f"review_queue: {e}", file=sys.stderr)
        return 2
    text = page(entries, human, _git(["rev-parse", "HEAD"], repo).strip(), signed)
    if write:
        target = repo / PAGE.relative_to(ROOT)
        target.write_text(text, encoding="utf-8", newline="\n")
        print(f"wrote {target.relative_to(repo)}: {len(entries)} entries")
    else:
        sys.stdout.write(text)
    return 0


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("--write", action="store_true", help=f"write {PAGE.relative_to(ROOT)} instead of printing it")
    args = ap.parse_args(argv)
    return run(ROOT, args.write)


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