@jesdi/skills 0.0.9 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/crap-gate/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: crap-gate
+description: >-
+  Score every function a branch changed with CRAP (cyclomatic complexity ×
+  untested fraction), fail on existing functions > 15 and new functions > 9,
+  and drive a fixer + independent reviewer loop until the gate passes. Use
+  when implementation is done and before pushing, when the user says "run the
+  crap gate", "check CRAP", "is this change tested enough", or when a push
+  gate reports CRAP violations.
+---
+
+# crap-gate — untested complexity is the thing you may not add
+
+`CRAP(f) = CC(f)² · (1 − cov(f))³ + CC(f)`. One number per function: how much
+complexity did this change add that tests do not verify. A CC-2 helper passes
+untested; a CC-9 function needs 100 % coverage; a CC-40 function fails even
+when fully tested (CRAP ≥ CC always). Thresholds come from the project's
+`.crap-gate.json` (defaults: existing changed function > 15 fails, new
+function > 9 fails). There are no pragmas and no allow-lists — the only bypass
+is the human approval gate at push time.
+
+## Running the engine
+
+The engine ships with this skill and is stdlib-only Python (plus `node` and
+the project's own `typescript` package for TS/TSX targets). Run it from
+anywhere inside the repo — it walks up to `.crap-gate.json`:
+
+```bash
+python3 <skill-dir>/crap.py            # human table, exit 1 on violations
+python3 <skill-dir>/crap.py --json     # same data for a subagent prompt
+python3 <skill-dir>/crap.py --no-run   # reuse the last coverage reports
+python3 <skill-dir>/crap.py --all      # whole-repo baseline (exploration only)
+python3 <skill-dir>/crap.py --base main --threshold-new 7   # local what-ifs
+```
+
+`<skill-dir>` is wherever this skill is installed (`.agents/skills/crap-gate`,
+`~/.my-skills/crap-gate`, …). Projects usually
+wrap it (`make crap`); prefer the wrapper when one exists.
+
+By default the engine runs each target's coverage command only when that
+target has changed files, so a backend-only change never runs the frontend
+suite. Coverage command output goes to `.crap/<target>.log`.
+
+Reading a line:
+
+```
+FAIL  backend/routers/stock.py:120  get_pe_history  CC 22  cov 0%  CRAP 506.0  limit 15 (existing)  → split to CC ≤ 3
+```
+
+The hint is the cheapest way out: `cover ≥ N%` when tests alone can fix it,
+`split to CC ≤ k` when the function is too complex to pass at its current
+coverage, both when both work. `Not measured:` lists changed code files that
+no target covers (never a failure, never silent).
+
+## Project setup (once per repository)
+
+Create `.crap-gate.json` at the repo root:
+
+```json
+{
+  "thresholds": { "existing": 15, "new": 9 },
+  "base": "origin/main",
+  "targets": [
+    {
+      "name": "backend",
+      "paths": ["backend/**/*.py"],
+      "exclude": ["backend/tests/**"],
+      "complexity": { "tool": "python" },
+      "coverage": {
+        "format": "coverage.py",
+        "root": "backend",
+        "report": "backend/.crap/coverage.json",
+        "command": "cd backend && pytest --cov=src --cov-report=json:.crap/coverage.json -q"
+      }
+    },
+    {
+      "name": "frontend",
+      "paths": ["frontend/src/**/*.ts", "frontend/src/**/*.tsx"],
+      "exclude": ["frontend/src/**/*.test.*"],
+      "complexity": { "tool": "typescript", "cwd": "frontend" },
+      "coverage": {
+        "format": "istanbul",
+        "report": "frontend/coverage/coverage-final.json",
+        "command": "cd frontend && vitest run --coverage --coverage.reportOnFailure=true"
+      }
+    }
+  ]
+}
+```
+
+- `thresholds` / `base` are optional (defaults shown). Flags override them.
+- `complexity.tool`: `python` (stdlib `ast`) or `typescript` (compiler API,
+  `cwd` = directory whose `node_modules/typescript` to use).
+- `coverage.format`: `coverage.py` (`root` = directory its file paths are
+  relative to, i.e. where pytest ran; run with `branch = true`) or `istanbul`
+  (absolute paths, e.g. vitest/jest `json` reporter).
+- `coverage.command` runs via `sh -c` from the repo root. It must (re)write
+  `coverage.report`. If it exits non-zero but still wrote a report (failing
+  tests), the engine warns and continues; no report → exit 2.
+
+## What counts as a function
+
+- Named functions: `def`s and function declarations, class methods
+  (`Class.method`), nested named functions (`outer.inner`), and
+  functions/arrows that directly initialise a variable or `export default`.
+  At module level, `export const X = memo(forwardRef(() => …))` is `X`.
+- Anonymous callbacks (`.map(() => …)`, `useMemo(() => …)`, handlers,
+  lambdas) **fold into the nearest named function**: a React component's
+  render callbacks are its complexity. The remedy is to extract a named
+  subcomponent, hook or helper — which is then scored on its own.
+- CC counts `if`/`elif`, loops, `except`/`catch`, ternaries, `case`, each
+  `&&`/`||`/`??` (and their assignment forms), comprehension `for`/`if`.
+  Optional chaining is not counted.
+- A function is **new** when its qualified name did not exist in the base
+  version of the file (renames count as new). Everything else that intersects
+  a diff hunk is **existing**. Untouched functions are not reported.
+
+## The loop — when the gate fails
+
+You are the orchestrator. Do not fix violations yourself in the same context
+that wrote the code; a fresh pair of eyes per role is the point.
+
+1. Run the engine with `--json` and keep the output.
+2. **Fixer.** Dispatch a subagent with: the JSON findings, the spec of the
+   change being made (the user's intent), and these rules:
+   - Tests first. Add or extend tests that prove the function's observable
+     behaviour through its public interface. Tests that merely assert the
+     implementation's text, tokens or incidental snapshots are not evidence.
+   - Refactor only when the hint says `split to CC ≤ k` and coverage alone
+     cannot reach the limit (CC > limit), or when the function is genuinely
+     doing two things. Extract named functions; keep behaviour identical.
+   - Touch nothing outside the listed functions and their tests. No drive-by
+     cleanups, no unrelated refactors.
+   - Re-run the engine before finishing and report the before/after lines.
+3. **Reviewer.** Dispatch a *different* subagent with the fixer's diff and the
+   original findings. It answers three questions with evidence: Do the new
+   tests exercise behaviour rather than restate the code? Is every refactor
+   behaviour-preserving (same inputs → same outputs, same side effects)? Did
+   the change stay inside the listed functions? Verdict: approve, or request
+   changes with specifics.
+4. **Adjudicate.** If changes are requested, send the review to the fixer
+   (same subagent if it still has context, otherwise a new one with the
+   review attached) and go back to step 3. If approved, re-run the engine.
+5. Stop after **3 rounds** with violations remaining. Report to the user: the
+   residual findings, what the fixer tried, what the reviewer objected to, and
+   your recommendation (usually: the function needs a design change, not more
+   tests). Do not loosen thresholds and do not add suppressions.
+
+Exit 0 from the engine ends the loop. Only then push.
+
+## Push gate
+
+Projects that gate pushes with `no-mistakes` run the same engine as the lint
+command with auto-fix disabled, so a violation that reaches the push parks for
+a human decision instead of being patched by an unreviewed fix agent:
+
+```yaml
+# .no-mistakes.yaml (must be on the default branch)
+allow_repo_commands: true
+commands:
+  lint: "make crap-gate"
+auto_fix:
+  lint: 0
+```
+
+If a push is parked on a CRAP finding, run the loop above on the branch, then
+`no-mistakes rerun`.

package/skills/crap-gate/crap.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""crap-gate engine: CRAP score for every function a branch changed.
+
+    python3 crap.py [--config PATH] [--base REF] [--threshold-existing N]
+                    [--threshold-new N] [--run | --no-run] [--all] [--json]
+
+Exit 0 = no violations, 1 = violations, 2 = configuration/tool error.
+Stdlib only; the typescript target additionally needs `node` and the
+project's own `typescript` package.
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import crap_git
+import crap_python
+import crap_typescript
+from crap_config import CODE_SUFFIXES, CONFIG_NAME, Config, Target, find_config, load, matches
+from crap_coverage import Report, load_report
+from crap_model import Func, ToolError
+from crap_report import Result, TargetRun, render_json, render_text
+from crap_score import score
+
+BASE_LABEL = "@base"
+
+
+# ── analysis ────────────────────────────────────────────────────────────────
+
+def _analyze(target: Target, root: Path, items: list[tuple[str, str | None]]) -> dict[str, list[Func]]:
+    """items: (label, source_text_or_None-for-working-tree). Returns label → funcs."""
+    if target.complexity_tool == "python":
+        out: dict[str, list[Func]] = {}
+        for label, text in items:
+            source = text if text is not None else (root / label.removesuffix(BASE_LABEL)).read_text()
+            out[label] = crap_python.functions(source, label)
+        return out
+    with tempfile.TemporaryDirectory(prefix="crap-gate-") as tmp:
+        files: list[tuple[Path, str]] = []
+        for index, (label, text) in enumerate(items):
+            if text is None:
+                files.append((root / label, label))
+            else:
+                real = label.removesuffix(BASE_LABEL)
+                p = Path(tmp) / f"{index}{Path(real).suffix}"
+                p.write_text(text)
+                files.append((p, label))
+        return crap_typescript.functions(files, root / target.complexity_cwd)
+
+
+def _intersects(func: Func, ranges: list[tuple[int, int]]) -> bool:
+    return any(func.start <= hi and lo <= func.end for lo, hi in ranges)
+
+
+def _score_target(
+    target: Target,
+    files: list[tuple[str, str | None]],
+    cfg: Config,
+    base: str,
+    report: Report,
+    all_functions: bool,
+) -> list:
+    items: list[tuple[str, str | None]] = []
+    base_sources: dict[str, str | None] = {}
+    for path, old in files:
+        items.append((path, None))
+        if not all_functions and old is not None:
+            base_sources[path] = crap_git.show(cfg.root, base, old)
+            if base_sources[path] is not None:
+                items.append((path + BASE_LABEL, base_sources[path]))
+    analysed = _analyze(target, cfg.root, items)
+
+    scored = []
+    for path, old in files:
+        funcs = analysed[path]
+        if all_functions:
+            touched, base_names = None, {f.name for f in funcs}
+        elif old is None or base_sources.get(path) is None:
+            touched, base_names = None, set()
+        else:
+            touched = crap_git.touched_lines(cfg.root, base, path)
+            base_names = {f.name for f in analysed[path + BASE_LABEL]}
+        for func in funcs:
+            if touched is not None and not _intersects(func, touched):
+                continue
+            kind = "existing" if func.name in base_names else "new"
+            children = [g for g in funcs if func.contains(g)]
+            if report.has_file(path):
+                coverage, note = report.function_coverage(func, children), ""
+            else:
+                coverage, note = 0.0, "file absent from coverage report"
+            scored.append(score(target.name, func, coverage, kind, cfg.thresholds, note))
+    return scored
+
+
+# ── coverage commands ───────────────────────────────────────────────────────
+
+def _maybe_run_coverage(target: Target, root: Path, run_mode: str, needed: bool) -> TargetRun:
+    report = root / target.coverage_report
+    should_run = run_mode == "run" or (run_mode == "auto" and needed)
+    if not should_run:
+        if not report.exists():
+            raise ToolError(f"{target.name}: report {target.coverage_report} is missing; run without --no-run")
+        return TargetRun(target.name, target.coverage_report, ran=False, seconds=0.0)
+    if not target.coverage_command:
+        raise ToolError(f"{target.name}: coverage.command is not configured")
+    log = root / ".crap" / f"{target.name}.log"
+    log.parent.mkdir(exist_ok=True)
+    before = report.stat().st_mtime_ns if report.exists() else None
+    started = time.monotonic()
+    # shell=True is deliberate: the command is the repository's own committed
+    # config (same trust model as a Makefile or no-mistakes' commands.*), never
+    # user input — it needs `cd … && …`, env assignments and pipes.
+    with log.open("w") as fh:
+        proc = subprocess.run(target.coverage_command, shell=True, cwd=root, stdout=fh, stderr=subprocess.STDOUT)
+    seconds = time.monotonic() - started
+    fresh = report.exists() and (before is None or report.stat().st_mtime_ns > before)
+    if not fresh:
+        raise ToolError(
+            f"{target.name}: coverage command exited {proc.returncode} and wrote no report "
+            f"({target.coverage_report}); see {log.relative_to(root)}"
+        )
+    if proc.returncode != 0:
+        print(
+            f"crap: {target.name}: coverage command exited {proc.returncode} (failing tests?) — "
+            f"using the report it wrote; see {log.relative_to(root)}",
+            file=sys.stderr,
+        )
+    return TargetRun(target.name, target.coverage_report, ran=True, seconds=seconds)
+
+
+# ── engine ──────────────────────────────────────────────────────────────────
+
+def run(cfg: Config, run_mode: str = "auto", all_functions: bool = False) -> Result:
+    base = crap_git.merge_base(cfg.root, cfg.base)
+    if all_functions:
+        candidates: list[tuple[str, str | None]] = [(p, p) for p in crap_git.tracked_files(cfg.root)]
+    else:
+        candidates = crap_git.changed_files(cfg.root, base)
+
+    per_target: dict[str, list[tuple[str, str | None]]] = {t.name: [] for t in cfg.targets}
+    not_measured: list[str] = []
+    for path, old in candidates:
+        if Path(path).suffix not in CODE_SUFFIXES:
+            continue
+        owner = next((t for t in cfg.targets if matches(t, path)), None)
+        if owner is None:
+            if not all_functions:
+                not_measured.append(path)
+            continue
+        per_target[owner.name].append((path, old))
+
+    runs: list[TargetRun] = []
+    functions = []
+    for target in cfg.targets:
+        files = per_target[target.name]
+        if not files:
+            continue
+        runs.append(_maybe_run_coverage(target, cfg.root, run_mode, needed=True))
+        report = load_report(target, cfg.root)
+        functions.extend(_score_target(target, files, cfg, base, report, all_functions))
+
+    return Result(base, cfg.base, cfg.thresholds, runs, functions, not_measured)
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="crap", description="CRAP score for every function a branch changed.")
+    p.add_argument("--config", type=Path, help="path to .crap-gate.json (default: walk up from cwd)")
+    p.add_argument("--base", help="git ref to diff against (default from config, else origin/main)")
+    p.add_argument("--threshold-existing", type=float)
+    p.add_argument("--threshold-new", type=float)
+    mode = p.add_mutually_exclusive_group()
+    mode.add_argument("--run", dest="run_mode", action="store_const", const="run", help="always run coverage commands")
+    mode.add_argument("--no-run", dest="run_mode", action="store_const", const="no-run", help="reuse existing reports")
+    p.set_defaults(run_mode="auto")
+    p.add_argument("--all", action="store_true", help="score every function in scope, not only changed ones")
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        config_path = args.config.resolve() if args.config else find_config(Path.cwd())
+        cfg = load(
+            config_path,
+            {"base": args.base, "threshold_existing": args.threshold_existing, "threshold_new": args.threshold_new},
+        )
+        toplevel = crap_git.toplevel(cfg.root).resolve()
+        if toplevel != cfg.root:
+            raise ToolError(
+                f"{CONFIG_NAME} must live at the git repository root; it is in "
+                f"{cfg.root}, but the root is {toplevel}"
+            )
+        result = run(cfg, run_mode=args.run_mode, all_functions=args.all)
+    except ToolError as exc:
+        print(f"crap: {exc}", file=sys.stderr)
+        return 2
+    sys.stdout.write(render_json(result) if args.json else render_text(result))
+    return 1 if result.summary["fail"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/crap-gate/crap_config.py

@@ -0,0 +1,124 @@
+"""Discover, validate and expose .crap-gate.json. Stdlib only."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from crap_model import ToolError
+
+CONFIG_NAME = ".crap-gate.json"
+CODE_SUFFIXES = {".py", ".ts", ".tsx"}
+COMPLEXITY_TOOLS = {"python", "typescript"}
+COVERAGE_FORMATS = {"coverage.py", "istanbul"}
+DEFAULT_THRESHOLDS = {"existing": 15, "new": 9}
+DEFAULT_BASE = "origin/main"
+
+
+@dataclass(frozen=True)
+class Target:
+    name: str
+    paths: list[str]
+    exclude: list[str]
+    complexity_tool: str
+    complexity_cwd: str
+    coverage_format: str
+    coverage_report: str
+    coverage_command: str
+    coverage_root: str
+
+
+@dataclass
+class Config:
+    root: Path
+    thresholds: dict[str, float]
+    base: str
+    targets: list[Target]
+
+
+def find_config(start: Path) -> Path:
+    for directory in [start.resolve(), *start.resolve().parents]:
+        candidate = directory / CONFIG_NAME
+        if candidate.is_file():
+            return candidate
+    raise ToolError(f"no {CONFIG_NAME} found in {start} or any parent directory")
+
+
+def load(path: Path, overrides: dict) -> Config:
+    try:
+        raw = json.loads(path.read_text())
+    except (OSError, ValueError) as exc:
+        raise ToolError(f"cannot read {path}: {exc}") from exc
+
+    thresholds = dict(DEFAULT_THRESHOLDS)
+    thresholds.update(raw.get("thresholds", {}))
+    if overrides.get("threshold_existing") is not None:
+        thresholds["existing"] = overrides["threshold_existing"]
+    if overrides.get("threshold_new") is not None:
+        thresholds["new"] = overrides["threshold_new"]
+    for key in ("existing", "new"):
+        if not isinstance(thresholds.get(key), (int, float)):
+            raise ToolError(f"thresholds.{key} must be a number")
+
+    base = overrides.get("base") or raw.get("base") or DEFAULT_BASE
+
+    targets = [_target(entry, index) for index, entry in enumerate(raw.get("targets", []))]
+    if not targets:
+        raise ToolError("config needs at least one target")
+    names = [t.name for t in targets]
+    if len(set(names)) != len(names):
+        raise ToolError(f"duplicate target name in {names}")
+
+    return Config(root=path.parent.resolve(), thresholds=thresholds, base=base, targets=targets)
+
+
+def _target(entry: dict, index: int) -> Target:
+    name = entry.get("name") or f"target[{index}]"
+    complexity = entry.get("complexity", {})
+    coverage = entry.get("coverage", {})
+    tool = complexity.get("tool")
+    if tool not in COMPLEXITY_TOOLS:
+        raise ToolError(f"{name}: complexity.tool must be one of {sorted(COMPLEXITY_TOOLS)}, got {tool!r}")
+    fmt = coverage.get("format")
+    if fmt not in COVERAGE_FORMATS:
+        raise ToolError(f"{name}: coverage.format must be one of {sorted(COVERAGE_FORMATS)}, got {fmt!r}")
+    if not coverage.get("report"):
+        raise ToolError(f"{name}: coverage.report is required")
+    if not entry.get("paths"):
+        raise ToolError(f"{name}: paths must list at least one glob")
+    return Target(
+        name=name,
+        paths=list(entry["paths"]),
+        exclude=list(entry.get("exclude", [])),
+        complexity_tool=tool,
+        complexity_cwd=complexity.get("cwd", "."),
+        coverage_format=fmt,
+        coverage_report=coverage["report"],
+        coverage_command=coverage.get("command", ""),
+        coverage_root=coverage.get("root", "."),
+    )
+
+
+def _glob_re(pattern: str) -> re.Pattern[str]:
+    """Translate a path glob to a regex: `**/` spans directories, `*` and `?`
+    never cross `/` (same rules as no-mistakes' ignore_patterns)."""
+    out, i = "", 0
+    while i < len(pattern):
+        if pattern.startswith("**/", i):
+            out, i = out + "(?:.*/)?", i + 3
+        elif pattern.startswith("**", i):
+            out, i = out + ".*", i + 2
+        elif pattern[i] == "*":
+            out, i = out + "[^/]*", i + 1
+        elif pattern[i] == "?":
+            out, i = out + "[^/]", i + 1
+        else:
+            out, i = out + re.escape(pattern[i]), i + 1
+    return re.compile(f"^{out}$")
+
+
+def matches(target: Target, file: str) -> bool:
+    if any(_glob_re(p).match(file) for p in target.exclude):
+        return False
+    return any(_glob_re(p).match(file) for p in target.paths)

package/skills/crap-gate/crap_coverage.py

@@ -0,0 +1,85 @@
+"""Per-function coverage from coverage.py JSON and istanbul JSON. Stdlib only."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+from crap_config import Target
+from crap_model import Func, ToolError
+
+
+class Report(Protocol):
+    def has_file(self, file: str) -> bool: ...
+    def function_coverage(self, func: Func, children: list[Func]) -> float: ...
+
+
+class CoveragePyReport:
+    """coverage.py `json` report (7.x): files[path].functions[qualname] with
+    start_line and summary.percent_covered (statements + branches)."""
+
+    def __init__(self, data: dict, root: str) -> None:
+        prefix = "" if root in ("", ".") else root.rstrip("/") + "/"
+        self._files = {prefix + path: entry for path, entry in data.get("files", {}).items()}
+
+    def has_file(self, file: str) -> bool:
+        return file in self._files
+
+    def function_coverage(self, func: Func, children: list[Func]) -> float:
+        entries = [e for e in self._files[func.file].get("functions", {}).values() if "start_line" in e]
+        exact = [e for e in entries if e["start_line"] == func.start]
+        inside = sorted((e for e in entries if func.start <= e["start_line"] <= func.end), key=lambda e: e["start_line"])
+        chosen = exact or inside
+        if not chosen:
+            return 0.0
+        return float(chosen[0]["summary"]["percent_covered"]) / 100.0
+
+
+class IstanbulReport:
+    """istanbul `coverage-final.json`: keys are absolute paths; statementMap/s
+    and branchMap/b give per-location hit counts."""
+
+    def __init__(self, data: dict, repo_root: Path) -> None:
+        self._files: dict[str, dict] = {}
+        root = repo_root.resolve()
+        for key, entry in data.items():
+            p = Path(entry.get("path", key))
+            try:
+                rel = p.resolve().relative_to(root).as_posix() if p.is_absolute() else p.as_posix()
+            except ValueError:
+                rel = p.as_posix()
+            self._files[rel] = entry
+
+    def has_file(self, file: str) -> bool:
+        return file in self._files
+
+    def function_coverage(self, func: Func, children: list[Func]) -> float:
+        entry = self._files[func.file]
+
+        def owned(loc: dict) -> bool:
+            line = loc["start"]["line"]
+            return func.start <= line <= func.end and not any(c.start <= line <= c.end for c in children)
+
+        total = covered = 0
+        for sid, loc in entry.get("statementMap", {}).items():
+            if owned(loc):
+                total += 1
+                covered += 1 if entry.get("s", {}).get(sid, 0) > 0 else 0
+        for bid, branch in entry.get("branchMap", {}).items():
+            loc = branch.get("loc") or (branch.get("locations") or [None])[0]
+            if loc and owned(loc):
+                counts = entry.get("b", {}).get(bid, [])
+                total += len(counts)
+                covered += sum(1 for c in counts if c > 0)
+        return 1.0 if total == 0 else covered / total
+
+
+def load_report(target: Target, repo_root: Path) -> Report:
+    path = repo_root / target.coverage_report
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError) as exc:
+        raise ToolError(f"{target.name}: cannot read coverage report {target.coverage_report}: {exc}") from exc
+    if target.coverage_format == "coverage.py":
+        return CoveragePyReport(data, target.coverage_root)
+    return IstanbulReport(data, repo_root)

package/skills/crap-gate/crap_git.py

@@ -0,0 +1,73 @@
+"""Thin git wrapper: what changed against the base, and base file contents."""
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from crap_model import ToolError
+
+_HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+
+
+def _git(root: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    proc = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+    if check and proc.returncode != 0:
+        raise ToolError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+    return proc
+
+
+def toplevel(cwd: Path) -> Path:
+    return Path(_git(cwd, "rev-parse", "--show-toplevel").stdout.strip())
+
+
+def merge_base(root: Path, ref: str) -> str:
+    proc = _git(root, "merge-base", "HEAD", ref, check=False)
+    if proc.returncode != 0:
+        raise ToolError(f"cannot resolve base {ref!r}: {proc.stderr.strip()} (fetch it or pass --base)")
+    return proc.stdout.strip()
+
+
+def changed_files(root: Path, base: str) -> list[tuple[str, str | None]]:
+    """(path, old_path) for every file that differs between the working tree
+    and `base`, plus untracked files. Deleted files are omitted."""
+    out: dict[str, str | None] = {}
+    for line in _git(root, "diff", "--name-status", "-M", base).stdout.splitlines():
+        parts = line.split("\t")
+        status = parts[0][0]
+        if status == "D":
+            continue
+        if status == "R":
+            out[parts[2]] = parts[1]
+        elif status == "A":
+            out[parts[1]] = None
+        else:
+            out[parts[1]] = parts[1]
+    for path in _git(root, "ls-files", "--others", "--exclude-standard").stdout.splitlines():
+        out[path] = None
+    return sorted(out.items())
+
+
+def touched_lines(root: Path, base: str, path: str) -> list[tuple[int, int]]:
+    """Inclusive line ranges of the working-tree file touched since `base`.
+    A pure deletion at +c touches c and c+1 (the seam)."""
+    ranges: list[tuple[int, int]] = []
+    for line in _git(root, "diff", "-U0", base, "--", path).stdout.splitlines():
+        m = _HUNK.match(line)
+        if not m:
+            continue
+        start = int(m.group(1))
+        count = int(m.group(2)) if m.group(2) is not None else 1
+        ranges.append((start, start + count - 1) if count else (start, start + 1))
+    return ranges
+
+
+def show(root: Path, rev: str, path: str) -> str | None:
+    proc = _git(root, "show", f"{rev}:{path}", check=False)
+    return proc.stdout if proc.returncode == 0 else None
+
+
+def tracked_files(root: Path) -> list[str]:
+    """Tracked + untracked files that exist in the working tree."""
+    listed = _git(root, "ls-files", "--cached", "--others", "--exclude-standard").stdout.splitlines()
+    return sorted(p for p in set(listed) if (root / p).is_file())