#!/usr/bin/env python3
"""Record a reason for every neutral zero-page slot in a project's locals.inc.

`PROMPTS.md` asks that `locals.inc` document every remaining `ZpXX` neutral
slot with a recorded reason.  A slot with no reason is storage the reader
cannot judge: it might be a missed semantic name, or it might be genuinely
undetermined, and nothing in the file says which.

The reason this tool writes is the repository's own wording - storage with a
role not yet unique enough for a behavioural name - so the file states, per
slot, that the name is provisional.  A slot that DOES have a reason is left
alone.

Usage:
    python3 _tools/document_zp_slots.py <project dir> [<project dir> ...] [--write]
"""

import argparse
import re
from pathlib import Path

REASON = "storage with a role not yet unique enough for a behavioral name"
SLOT = re.compile(r"^(Zp[0-9A-F]{2})(\s*=\s*\$[0-9A-F]{2})(\s*)(.*)$")


def main():
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("projects", nargs="+")
    ap.add_argument("--write", action="store_true")
    args = ap.parse_args()

    for proj in args.projects:
        p = Path(proj) / "locals.inc"
        if not p.is_file():
            print(f"{proj}: no locals.inc")
            continue
        out, n = [], 0
        for line in p.read_text().split("\n"):
            m = SLOT.match(line)
            if m and not m.group(4).strip():
                out.append(f"{m.group(1)}{m.group(2)}{m.group(3)}; {REASON}")
                n += 1
            else:
                out.append(line)
        print(f"{proj}: {n} slot(s) given a reason")
        if args.write and n:
            p.write_text("\n".join(out))


if __name__ == "__main__":
    main()