"""Two rows of CLAUDE.md's canonical-patterns table, held in code rather than prose.

A rule stated only in a comment drifts: this one had — 63 mutation responses without `ok`, and
twelve route helpers that committed on their own, among them an approval whose decision, activation
and token landed in three separate transactions. The debt burn of 2026-09 fixed the drift; these keep
it fixed.
"""

import ast
from pathlib import Path

ROUTES = Path(__file__).parent.parent / "app" / "routes"
MUTATING = {"post", "put", "patch", "delete"}

# A route helper that commits where it stands, and why the commit has to be there rather than in
# the handler. Anything else flushes and leaves the commit to its handler.
COMMITTING_HELPERS = {
    "auth.py:_issue_token": "the token must be durable before the link that carries it is mailed",
    "auth.py:_consume_token": "burning a single-use token is its own unit: a later failure must "
    "not hand the token back",
    "auth.py:_complete_link": "the tail of the Google callback route, which answers with its result",
    "auth.py:_register_account": "a background task with its own session, i.e. a job wrapper",
    "search.py:_ingest_candidates": "stages around YouTube calls: the stubs must survive an enrich "
    "that fails",
    "search.py:_classify_shorts": "the last stage of that ingest, after its probes",
}


def _modules():
    for path in sorted(ROUTES.rglob("*.py")):
        yield path.relative_to(ROUTES).as_posix(), ast.parse(path.read_text(encoding="utf-8"))


def _is_mutation_route(fn: ast.FunctionDef) -> bool:
    return any(
        isinstance(d, ast.Call) and getattr(d.func, "attr", "") in MUTATING
        for d in fn.decorator_list
    )


def test_every_mutation_answers_ok():
    """`{"ok": true, …}` (or `{"deleted": id}`) for every mutation that answers with a literal —
    one field a client can read the same way everywhere. A serializer's return is exempt: it
    describes a resource, not an acknowledgement."""
    missing = []
    for name, tree in _modules():
        for fn in ast.walk(tree):
            if not (isinstance(fn, ast.FunctionDef) and _is_mutation_route(fn)):
                continue
            for node in ast.walk(fn):
                if isinstance(node, ast.Return) and isinstance(node.value, ast.Dict):
                    keys = {k.value for k in node.value.keys if isinstance(k, ast.Constant)}
                    if not keys & {"ok", "deleted"}:
                        missing.append(f"{name}:{node.lineno} {fn.name}")
    assert missing == []


def test_route_helpers_flush_and_leave_the_commit_to_the_handler():
    committing = set()
    for name, tree in _modules():
        for fn in ast.walk(tree):
            if isinstance(fn, ast.FunctionDef) and fn.name.startswith("_"):
                if any(
                    isinstance(n, ast.Call) and getattr(n.func, "attr", "") == "commit"
                    for n in ast.walk(fn)
                ):
                    committing.add(f"{name}:{fn.name}")
    assert committing == set(COMMITTING_HELPERS)