gate_scripts.py

#!/usr/bin/env python3
"""Gate Scripts Starter, from Claude Code Pipeline Patterns (NerdyChefs).

Three runnable gate checks, python3 standard library only, no installs.
Every command exits 0 when clean and 1 on any failure, so an orchestrator
(or a Claude Code hook) can branch on the exit code and nothing else.

    python3 gate-scripts-starter-v1.py ledger STATUS.md
        Validate every gate line in a STATUS-style ledger against the
        book's grammar (section 03), including HUMAN decision lines
        (pattern 12). Reports file:line for every bad line.

    python3 gate-scripts-starter-v1.py manifest MANIFEST.md
        Check a Self-Verifying Generator manifest (pattern 9). Grammar,
        one claim per line:  <file path> | <check> | <expected value>
        Checks: exists, min-bytes:N, contains:<string>. Paths resolve
        relative to the manifest's own directory.

    python3 gate-scripts-starter-v1.py textcheck draft.md --max-words 40
        One example structural prose check, shipped as a template: flag
        every sentence over the word cap. Swap the rule for your own;
        keep the shape (deterministic scan, file:line report, exit code).

    python3 gate-scripts-starter-v1.py --selftest
        The script gates itself: it writes clean and failing fixtures to
        a temporary directory, runs all three checkers against them, and
        asserts each exit code. Prints one line per case plus a summary,
        exits 0 only when every case behaves. Run it after you edit this
        file; a gate you changed is a gate you re-check.

Edit freely. The one rule that must survive your edits: the check prints
what it measured and exits 0 or 1. A gate that returns an adjective is
not a gate.
"""

from __future__ import annotations

import argparse
import contextlib
import io
import re
import sys
import tempfile
from pathlib import Path

# ----------------------------------------------------------------- ledger
# The gate-line grammar, exactly as section 03 defines it:
#   - YYYY-MM-DD | stage=<n>-<NAME> | PASS/FAIL | evidence: <...>
GATE_LINE_RE = re.compile(
    r"^- \d{4}-\d{2}-\d{2} \| stage=\d+-[A-Z][A-Z-]* \| (?:PASS|FAIL) \| evidence: .+$"
)

# The HUMAN decision-line grammar from pattern 12 (Stop-the-Line). Only a
# human-authored line restarts a stopped line, and it has a grammar too,
# so the resume rule stays machine-checkable:
#   - YYYY-MM-DD | HUMAN | PROCEED|REVISE|ABORT | instruction: <text>
HUMAN_LINE_RE = re.compile(
    r"^- \d{4}-\d{2}-\d{2} \| HUMAN \| (?:PROCEED|REVISE|ABORT) \| instruction: .+$"
)

# Anything that opens like a ledger line must finish like one. Prose,
# headings, and ordinary list items are ignored; a line that starts with
# a dated pipe-separated stub and then breaks the grammar is a defect.
LEDGER_SHAPE_RE = re.compile(r"^- \d{4}-\d{2}-\d{2} \|")

# Pulls the stage number and verdict out of a valid gate line, so the
# checker can also answer "where are we?" from the log alone.
STAGE_VERDICT_RE = re.compile(r"^- \d{4}-\d{2}-\d{2} \| stage=(\d+)-[A-Z][A-Z-]* \| (PASS|FAIL) ")


def cmd_ledger(args: argparse.Namespace) -> int:
    """Validate a STATUS-style ledger file line by line."""
    path = Path(args.file)
    if not path.is_file():
        print(f"error: {path} is not a file", file=sys.stderr)
        return 2

    gate_lines = 0
    human_lines = 0
    bad = 0
    passed: set[int] = set()
    seen: set[int] = set()
    in_fence = False

    for lineno, line in enumerate(
        path.read_text(encoding="utf-8", errors="replace").splitlines(), start=1
    ):
        # Ledgers quote script output verbatim inside fenced blocks as
        # evidence. Quoted material is exempt; only live lines are gated.
        if line.lstrip().startswith("```"):
            in_fence = not in_fence
            continue
        if in_fence:
            continue
        if not LEDGER_SHAPE_RE.match(line):
            continue  # not shaped like a ledger line; none of our business
        if GATE_LINE_RE.match(line):
            gate_lines += 1
            m = STAGE_VERDICT_RE.match(line)
            if m:
                stage = int(m.group(1))
                seen.add(stage)
                if m.group(2) == "PASS":
                    passed.add(stage)
        elif HUMAN_LINE_RE.match(line):
            human_lines += 1
        else:
            bad += 1
            print(f"{path}:{lineno}: bad ledger line (dated stub that fails the grammar): {line.strip()}")

    if bad:
        print(f"LEDGER: {bad} bad line(s), {gate_lines} valid gate line(s) in {path.name}")
        return 1

    # The book's resume rule: the current stage is the lowest stage
    # without a PASS line.
    if seen:
        open_stages = [n for n in range(1, max(seen) + 1) if n not in passed]
        where = f"current stage: {min(open_stages)}" if open_stages else \
            f"stages 1-{max(seen)} all have a PASS"
    else:
        where = "no gate lines yet"
    print(
        f"LEDGER: clean, {gate_lines} gate line(s), {human_lines} HUMAN decision line(s); {where}"
    )
    return 0


# --------------------------------------------------------------- manifest


def cmd_manifest(args: argparse.Namespace) -> int:
    """Check every claim line in a pattern-9 manifest against the files."""
    manifest = Path(args.file)
    if not manifest.is_file():
        print(f"error: {manifest} is not a file", file=sys.stderr)
        return 2
    base = manifest.parent  # claim paths resolve next to the manifest

    checked = 0
    failed = 0
    for lineno, raw in enumerate(
        manifest.read_text(encoding="utf-8", errors="replace").splitlines(), start=1
    ):
        line = raw.strip()
        if not line or line.startswith("#"):
            continue  # blank lines and comments carry no claims
        parts = [p.strip() for p in line.split("|", 2)]
        if len(parts) != 3 or not all(parts):
            failed += 1
            print(f"[line {lineno:02d}] FAIL malformed claim, need '<file path> | <check> | <expected value>': {line}")
            continue
        rel, check, expected = parts
        target = base / rel
        checked += 1

        if check == "exists":
            ok = target.exists()
            actual = "present" if ok else "missing"
        elif check.startswith("min-bytes:"):
            try:
                floor = int(check[len("min-bytes:"):])
            except ValueError:
                failed += 1
                print(f"[line {lineno:02d}] FAIL {rel} | {check} | the byte floor is not an integer")
                continue
            if not target.is_file():
                ok, actual = False, "missing"
            else:
                size = target.stat().st_size
                ok = size >= floor
                actual = f"{size} bytes"
        elif check.startswith("contains:"):
            needle = check[len("contains:"):]
            if not target.is_file():
                ok, actual = False, "missing"
            else:
                ok = needle in target.read_text(encoding="utf-8", errors="replace")
                actual = "string found" if ok else "string not found"
        else:
            failed += 1
            print(f"[line {lineno:02d}] FAIL {rel} | unknown check '{check}' (use exists, min-bytes:N, contains:<string>)")
            continue

        verdict = "PASS" if ok else "FAIL"
        if not ok:
            failed += 1
        print(f"[line {lineno:02d}] {verdict} {rel} | {check} | expected: {expected} | actual: {actual}")

    if failed:
        print(f"MANIFEST: {failed} failed of {checked} claim(s) checked")
        return 1
    if not checked:
        print("MANIFEST: no claim lines found, which is its own kind of FAIL")
        return 1
    print(f"MANIFEST: clean, {checked}/{checked} claim(s) hold")
    return 0


# -------------------------------------------------------------- textcheck

WORD_RE = re.compile(r"[\w'-]+")
SENTENCE_SPLIT_RE = re.compile(r"(?<=[.!?])\s+")


def cmd_textcheck(args: argparse.Namespace) -> int:
    """Template structural check: flag sentences over the word cap.

    The rule here is deliberately small. The shape is the point: read the
    file, skip quoted code, measure something countable, report file:line,
    exit 0 or 1. Replace the sentence rule with whatever structural rule
    your artifact needs and the gate wiring stays identical.
    """
    path = Path(args.file)
    if not path.is_file():
        print(f"error: {path} is not a file", file=sys.stderr)
        return 2
    cap = args.max_words

    # Gather prose paragraphs: fenced code is exempt, and heading, table,
    # and quote lines are structure rather than sentences.
    paragraphs: list[tuple[int, str]] = []  # (starting line, text)
    buf: list[str] = []
    buf_start = 0
    in_fence = False
    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
    for lineno, line in enumerate(lines + [""], start=1):
        stripped = line.strip()
        if stripped.startswith("```"):
            in_fence = not in_fence
            stripped = ""
        if in_fence or not stripped or stripped.startswith(("#", "|", ">")):
            if buf:
                paragraphs.append((buf_start, " ".join(buf)))
                buf = []
            continue
        if not buf:
            buf_start = lineno
        buf.append(stripped)

    flagged = 0
    total = 0
    for start, text in paragraphs:
        for sentence in SENTENCE_SPLIT_RE.split(text):
            words = WORD_RE.findall(sentence)
            if not words:
                continue
            total += 1
            if len(words) > cap:
                flagged += 1
                head = " ".join(words[:12])
                print(f"{path}:{start}: {len(words)} words (cap {cap}): {head} ...")

    if flagged:
        print(f"TEXTCHECK: {flagged} of {total} sentence(s) over {cap} words")
        return 1
    print(f"TEXTCHECK: clean, {total} sentence(s), none over {cap} words")
    return 0


# --------------------------------------------------------------- selftest


def run_selftest() -> int:
    """Check the three checkers against generated fixtures; exit 0 when all behave."""
    with tempfile.TemporaryDirectory(prefix="gate-scripts-selftest-") as tmp:
        base = Path(tmp)

        # Ledger fixtures. The clean one exercises gate lines, a HUMAN
        # decision line, a fenced quote (exempt), and a plain list item
        # (ignored). The bad one holds four dated stubs that each break
        # the grammar a different way, plus one valid line.
        clean_ledger = base / "clean-ledger.md"
        clean_ledger.write_text(
            "# STATUS, selftest fixture\n"
            "\n"
            "## Gate log\n"
            "\n"
            "- 2026-07-03 | stage=1-PLAN | PASS | evidence: 3 stages named, contract written\n"
            "- 2026-07-03 | stage=2-WRITE | FAIL | evidence: 2 of 9 sections missing\n"
            "- 2026-07-03 | stage=2-WRITE | PASS | evidence: 9/9 sections present, 4102 words\n"
            "- 2026-07-03 | HUMAN | PROCEED | instruction: counts verified by hand, continue\n"
            "- a plain list item without a date, none of the checker's business\n"
            "\n"
            "```\n"
            "- 2026-07-03 | stage=9 | PASSED | quoted inside a fence, exempt\n"
            "```\n",
            encoding="utf-8",
        )
        bad_ledger = base / "bad-ledger.md"
        bad_ledger.write_text(
            "## Gate log\n"
            "\n"
            "- 2026-07-03 | stage=2-writer | PASS | evidence: lowercase stage name\n"
            "- 2026-07-03 | stage=2-WRITER | PASSED | evidence: wrong verdict token\n"
            "- 2026-07-03 | stage=2-WRITER | PASS | the evidence field is missing\n"
            "- 2026-07-03 | HUMAN | MAYBE | instruction: not one of the three decisions\n"
            "- 2026-07-03 | stage=3-EDITOR | PASS | evidence: the one valid line here\n",
            encoding="utf-8",
        )

        # Manifest fixtures. One real file on disk; the clean manifest
        # makes three claims that hold, the failing one breaks a claim
        # per supported check plus an unknown check and a malformed line.
        made = base / "made"
        made.mkdir()
        (made / "note.md").write_text(
            "## Prompt\n\nA small real file for the manifest checks to measure.\n",
            encoding="utf-8",
        )
        clean_manifest = base / "clean-manifest.md"
        clean_manifest.write_text(
            "# selftest manifest: every claim below holds\n"
            "made/note.md | exists | file present\n"
            "made/note.md | min-bytes:10 | no stub\n"
            "made/note.md | contains:## Prompt | heading present\n",
            encoding="utf-8",
        )
        bad_manifest = base / "bad-manifest.md"
        bad_manifest.write_text(
            "made/absent.md | exists | file present\n"
            "made/note.md | min-bytes:100000 | a floor no fixture meets\n"
            "made/note.md | contains:a string that is not there | heading present\n"
            "made/note.md | checksum:abc | a check this script does not know\n"
            "a line with no pipes at all\n",
            encoding="utf-8",
        )

        # Textcheck fixtures. The clean file keeps every sentence short
        # and hides a long line inside a fence to prove the exemption.
        # The failing file carries one sentence far over the cap.
        clean_prose = base / "clean-prose.md"
        clean_prose.write_text(
            "# Fixture\n"
            "\n"
            "Short sentences pass. The cap stays out of reach.\n"
            "\n"
            "```\n"
            + " ".join(["fenced"] * 60)
            + ".\n"
            "```\n",
            encoding="utf-8",
        )
        long_prose = base / "long-prose.md"
        long_prose.write_text(
            "One sentence runs long on purpose "
            + " ".join(["and keeps going"] * 15)
            + " until it lands far past the cap.\n",
            encoding="utf-8",
        )

        cases = [
            ("ledger accepts the clean ledger", cmd_ledger,
             argparse.Namespace(file=str(clean_ledger)), 0),
            ("ledger rejects the bad ledger", cmd_ledger,
             argparse.Namespace(file=str(bad_ledger)), 1),
            ("manifest passes when every claim holds", cmd_manifest,
             argparse.Namespace(file=str(clean_manifest)), 0),
            ("manifest fails on broken claims", cmd_manifest,
             argparse.Namespace(file=str(bad_manifest)), 1),
            ("textcheck passes short sentences, fence exempt", cmd_textcheck,
             argparse.Namespace(file=str(clean_prose), max_words=40), 0),
            ("textcheck flags the long sentence", cmd_textcheck,
             argparse.Namespace(file=str(long_prose), max_words=40), 1),
        ]

        passed = 0
        for i, (name, func, ns, want) in enumerate(cases, start=1):
            buf = io.StringIO()
            with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
                got = func(ns)
            if got == want:
                passed += 1
                print(f"[case {i}] PASS {name} (exit {got} as expected)")
            else:
                print(f"[case {i}] FAIL {name} (exit {got}, expected {want})")
                for line in buf.getvalue().splitlines():
                    print(f"    {line}")

    print(f"SELFTEST: {passed}/{len(cases)} case(s) behaved as expected")
    return 0 if passed == len(cases) else 1


# ------------------------------------------------------------------- main


def main() -> int:
    if "--selftest" in sys.argv[1:]:
        return run_selftest()
    parser = argparse.ArgumentParser(
        prog="gate-scripts-starter-v1.py",
        description="Three deterministic gate checks: ledger, manifest, textcheck.",
        epilog="Run with --selftest (no other arguments) to check all three "
               "commands against generated fixtures.",
    )
    sub = parser.add_subparsers(dest="command", required=True)

    p_ledger = sub.add_parser("ledger", help="validate a STATUS-style gate log")
    p_ledger.add_argument("file", help="path to the ledger, usually STATUS.md")
    p_ledger.set_defaults(func=cmd_ledger)

    p_manifest = sub.add_parser("manifest", help="check a pattern-9 manifest")
    p_manifest.add_argument("file", help="path to the manifest, usually MANIFEST.md")
    p_manifest.set_defaults(func=cmd_manifest)

    p_text = sub.add_parser("textcheck", help="flag sentences over a word cap")
    p_text.add_argument("file", help="path to the prose file to scan")
    p_text.add_argument(
        "--max-words",
        type=int,
        default=40,
        help="word cap per sentence (default 40)",
    )
    p_text.set_defaults(func=cmd_textcheck)

    args = parser.parse_args()
    return args.func(args)


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