culprit 0.1.0__py3-none-any.whl

culprit/__init__.py

@@ -0,0 +1,9 @@
+"""culprit — root-cause analysis for a PR or branch.
+
+Repo-agnostic engine: deterministic git/PR analysis that emits structured JSON.
+The only LLM step (the "why it broke" narrative) is isolated behind
+``culprit.reasoning`` so the same engine drives both the Claude Code skill
+(harness reasons) and the standalone CLI (Claude API reasons).
+"""
+
+__version__ = "0.1.0"

culprit/_proc.py

@@ -0,0 +1,46 @@
+"""Thin, read-only subprocess helpers for git and gh.
+
+Every command here is read-only by construction. Nothing in culprit ever
+mutates the target repository or the PR.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import List, Optional
+
+
+class ProcError(RuntimeError):
+    """A subprocess exited non-zero."""
+
+    def __init__(self, cmd: List[str], returncode: int, stderr: str):
+        self.cmd = cmd
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__("`{}` exited {}: {}".format(" ".join(cmd), returncode, stderr.strip()))
+
+
+def run(cmd: List[str], cwd: Optional[str] = None, check: bool = True) -> str:
+    """Run a command and return stdout. Raise ProcError on failure when check."""
+    proc = subprocess.run(
+        cmd,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if check and proc.returncode != 0:
+        raise ProcError(cmd, proc.returncode, proc.stderr)
+    return proc.stdout
+
+
+def git(args: List[str], repo: str, check: bool = True) -> str:
+    return run(["git", "-C", repo] + args, check=check)
+
+
+def have_gh() -> bool:
+    return shutil.which("gh") is not None
+
+
+def gh(args: List[str], repo: str, check: bool = True) -> str:
+    return run(["gh"] + args, cwd=repo, check=check)

culprit/blast_radius.py

@@ -0,0 +1,124 @@
+"""Feature path: what can this change break?
+
+For each changed source file, find who imports it (reverse-import map), which
+tests cover those modules, and which touched files live in shared/core areas
+(high blast radius). Heuristic but grounded — the reasoning layer ranks risk
+and recommends the test surface from this structured map.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+from . import _proc
+
+DEFAULT_SOURCE_GLOBS = [
+    "*.js", "*.jsx", "*.ts", "*.tsx", "*.mjs", "*.cjs", "*.vue", "*.svelte",
+    "*.py", "*.go", "*.rb", "*.java", "*.kt", "*.scala", "*.cs", "*.php",
+    "*.rs", "*.c", "*.h", "*.cc", "*.cpp", "*.hpp", "*.m", "*.swift",
+]
+# Test-file conventions across ecosystems: JS spec/test, Python test_*/*_test,
+# Go *_test.go, Java/Kotlin/C# *Test/*Tests, Ruby *_spec, plus test dirs.
+DEFAULT_TEST_RE = re.compile(
+    r"(\.spec\.|\.test\.|_test\.|_spec\.|/__tests__/|(^|/)cypress/|(^|/)tests?/"
+    r"|(^|/)test_[^/]*\.(py|rb)$|Tests?\.(java|kt|cs|scala|swift)$|_test\.go$)", re.I)
+HIGH_RISK_RE = re.compile(r"(^|/)(shared|common|core|lib|utils?|helpers?|base|hooks|store)(/|$)", re.I)
+
+_INDEX_RE = re.compile(r"(^|/)(index|__init__|mod)\.[^/]+$")
+
+
+def _module_token(path: str) -> str:
+    """The identifier other files most likely import this module by."""
+    if _INDEX_RE.search(path):
+        # package entry files (index.js / __init__.py / mod.go) are imported by dir name
+        return os.path.basename(os.path.dirname(path)) or os.path.basename(path)
+    return os.path.splitext(os.path.basename(path))[0]
+
+
+def _importers(repo: str, token: str, exclude: str, source_globs: List[str]) -> List[str]:
+    if not token:
+        return []
+    tok = re.escape(token)
+    # An import-ish line that references the token as a delimited path segment.
+    # Covers JS/TS (`import x from '…/token'`, `require('…token…')`), Python
+    # (`from a.token import x`, `import a.token`), Java (`import a.b.Token;`),
+    # Go/Ruby/C (`"…/token"`, `<token.h>`). Uses POSIX classes only — git grep -E
+    # has no \w / \b, so token boundaries are spelled [^A-Za-z0-9_].
+    pat = r"(import|require|include|from|use).*[^A-Za-z0-9_]{}([^A-Za-z0-9_]|$)".format(tok)
+    args = ["grep", "-l", "-I", "-E", "-e", pat, "--"] + source_globs
+    out = _proc.git(args, repo, check=False)
+    return [f for f in out.splitlines() if f.strip() and f != exclude]
+
+
+def test_gap(changed_files: List[str], repo: str,
+             source_globs: Optional[List[str]] = None, max_files: int = 60) -> Dict[str, Any]:
+    """For a bugfix: which changed (non-test) files have no covering tests.
+
+    A regression usually slips through because the touched code isn't tested.
+    Reuses the reverse-import map to find test files that import each module.
+    """
+    source_globs = source_globs or DEFAULT_SOURCE_GLOBS
+    files = [f for f in changed_files if f]
+    notes: List[str] = []
+    if len(files) > max_files:
+        notes.append("{} files; checked the first {}".format(len(files), max_files))
+        files = files[:max_files]
+    covering = set()
+    untested: List[str] = []
+    for path in files:
+        if DEFAULT_TEST_RE.search(path):
+            continue  # the changed file is itself a test
+        token = _module_token(path)
+        tests = [i for i in _importers(repo, token, path, source_globs) if DEFAULT_TEST_RE.search(i)]
+        if tests:
+            covering.update(tests)
+        else:
+            untested.append(path)
+    return {"untested": untested, "covering_tests": sorted(covering), "notes": notes}
+
+
+def analyze(ctx: Dict[str, Any], repo: str,
+            source_globs: Optional[List[str]] = None,
+            max_dependents: int = 50, max_files: int = 200) -> Dict[str, Any]:
+    source_globs = source_globs or DEFAULT_SOURCE_GLOBS
+    changed = [f for f in ctx.get("changed_files", []) if f]
+    notes: List[str] = []
+    if len(changed) > max_files:
+        notes.append("changeset has {} files; mapping dependents for the first {} "
+                     "(narrow the base or analyze one commit)".format(len(changed), max_files))
+        changed = changed[:max_files]
+
+    dependents: Dict[str, List[str]] = {}
+    covering_tests = set()
+    high_risk: List[str] = []
+
+    for path in changed:
+        if DEFAULT_TEST_RE.search(path):
+            covering_tests.add(path)  # the change itself touches a test
+        if HIGH_RISK_RE.search(path):
+            high_risk.append(path)
+
+        token = _module_token(path)
+        imps = _importers(repo, token, path, source_globs)[:max_dependents]
+        if imps:
+            dependents[path] = imps
+        for imp in imps:
+            if DEFAULT_TEST_RE.search(imp):
+                covering_tests.add(imp)
+
+    # A changed file with many dependents is also high-risk even outside shared/.
+    for path, imps in dependents.items():
+        if len(imps) >= 10 and path not in high_risk:
+            high_risk.append(path)
+
+    ranked = sorted(dependents.items(), key=lambda kv: len(kv[1]), reverse=True)
+    return {
+        "changed_files": changed,
+        "dependents": dict(ranked),
+        "dependent_counts": {p: len(v) for p, v in ranked},
+        "covering_tests": sorted(covering_tests),
+        "high_risk": high_risk,
+        "total_dependents": sum(len(v) for v in dependents.values()),
+        "notes": notes,
+    }

culprit/classify.py

@@ -0,0 +1,87 @@
+"""Classify a change as a bugfix or a feature, with evidence.
+
+Deterministic scoring over branch name, PR labels, and commit/title prefixes.
+The verdict is advisory: the Claude Code harness (or the API reasoning layer)
+makes the final call, but the score + evidence give it grounded signal instead
+of guessing.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Tuple
+
+_BUG_BRANCH = re.compile(r"^(bug|bugfix|fix|hotfix|patch)[/\-_]", re.I)
+_FEAT_BRANCH = re.compile(r"^(feat|feature|enhancement|chore|refactor)[/\-_]", re.I)
+
+# Leading [\W_]* tolerates real-world prefixes like "- fix:", "🚀 feat:", ": fixes".
+_BUG_PREFIX = re.compile(r"^[\W_]*(bug\s*)?fix(es|ed)?\b|^[\W_]*hotfix\b|^[\W_]*patch\b", re.I)
+_FEAT_PREFIX = re.compile(r"^[\W_]*(feat|feature|add|implement|introduce|chore|refactor)\b", re.I)
+
+_BUG_LABELS = {"bug", "bugfix", "regression", "defect", "hotfix"}
+_FEAT_LABELS = {"feature", "enhancement", "feat", "improvement"}
+
+
+def _add(evidence: List[str], score: int, delta: int, msg: str) -> int:
+    evidence.append(msg)
+    return score + delta
+
+
+def classify(ctx: Dict[str, Any]) -> Dict[str, Any]:
+    """Return {verdict, confidence, evidence, score} from a pr_context dict."""
+    score = 0  # positive → bugfix, negative → feature
+    evidence: List[str] = []
+
+    branch = ctx.get("head_ref") or ""
+    if _BUG_BRANCH.match(branch):
+        score = _add(evidence, score, 2, "branch '{}' uses a fix/bug prefix".format(branch))
+    elif _FEAT_BRANCH.match(branch):
+        score = _add(evidence, score, -2, "branch '{}' uses a feat/feature prefix".format(branch))
+
+    labels = [str(l).lower() for l in (ctx.get("labels") or [])]
+    for lab in labels:
+        if lab in _BUG_LABELS:
+            score = _add(evidence, score, 3, "PR label '{}' indicates a bug".format(lab))
+        elif lab in _FEAT_LABELS:
+            score = _add(evidence, score, -3, "PR label '{}' indicates a feature".format(lab))
+
+    title = ctx.get("title") or ""
+    if title:
+        if _BUG_PREFIX.search(title):
+            score = _add(evidence, score, 2, "PR title '{}' reads like a fix".format(title))
+        elif _FEAT_PREFIX.search(title):
+            score = _add(evidence, score, -2, "PR title '{}' reads like a feature".format(title))
+
+    bug_commits = 0
+    feat_commits = 0
+    for c in ctx.get("commits", []):
+        subj = c.get("subject") or ""
+        if _BUG_PREFIX.search(subj):
+            bug_commits += 1
+        elif _FEAT_PREFIX.search(subj):
+            feat_commits += 1
+    if bug_commits or feat_commits:
+        if bug_commits > feat_commits:
+            score = _add(evidence, score, 1,
+                         "{} of {} commit subjects look like fixes".format(
+                             bug_commits, len(ctx.get("commits", []))))
+        elif feat_commits > bug_commits:
+            score = _add(evidence, score, -1,
+                         "{} of {} commit subjects look like features".format(
+                             feat_commits, len(ctx.get("commits", []))))
+
+    if score > 0:
+        verdict = "bugfix"
+    elif score < 0:
+        verdict = "feature"
+    else:
+        verdict = "unknown"
+
+    # Confidence scales with the margin; capped at a readable 0.95.
+    confidence = min(0.95, 0.5 + 0.1 * abs(score)) if verdict != "unknown" else 0.0
+
+    return {
+        "verdict": verdict,
+        "confidence": round(confidence, 2),
+        "score": score,
+        "evidence": evidence,
+    }

culprit/cli.py

@@ -0,0 +1,152 @@
+"""culprit CLI — orchestrate the engine and emit a report.
+
+    rca                      # analyze the current branch (local git or its PR)
+    rca --pr 16786           # analyze a specific GitHub PR
+    rca --repo /path --base main
+    rca --mode api --fast    # use the Claude API reasoning layer (standalone)
+    rca --json               # print the structured result only
+
+In Claude Code the default --mode harness emits the skeleton and the harness
+writes the narrative. --mode api calls Claude directly for terminal/CI use.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import os
+import sys
+from typing import Any, Dict, Optional
+
+from . import blast_radius, classify, config, evolution, pr_context, reasoning, report, suspect
+
+
+def analyze(repo: str, pr: Optional[int], base: str, head: Optional[str],
+            force: Optional[str] = None) -> Dict[str, Any]:
+    """Run the full deterministic pipeline; return the structured result."""
+    ctx = pr_context.resolve(repo, pr=pr, base=base, head=head)
+    cls = classify.classify(ctx)
+    if force:
+        # Reflect the override in the displayed classification, not just the path.
+        cls = dict(cls)
+        cls["verdict"] = force
+        cls["evidence"] = ["forced to '{}' via --force".format(force)] + list(cls.get("evidence", []))
+    verdict = force or cls["verdict"]
+
+    bugfix = feature = None
+    if verdict == "feature":
+        feature = blast_radius.analyze(ctx, repo)
+    else:
+        # bugfix or unknown → run RCA (the more actionable default)
+        bugfix = suspect.find_suspects(ctx, repo)
+        # Attach the line-evolution timeline (origin → … → suspect → fix).
+        bugfix["timeline"] = evolution.build_timeline(ctx, repo, bugfix.get("suspects", []))
+        # Did the touched files have any tests? (why the bug slipped through)
+        bugfix["test_gap"] = blast_radius.test_gap(ctx.get("changed_files", []), repo)
+
+    return report.build(ctx, cls, bugfix, feature)
+
+
+def _save(result: Dict[str, Any], narrative: str) -> str:
+    run = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+    out_dir = os.path.join(os.path.expanduser("~/culprit/output"), run)
+    os.makedirs(out_dir, exist_ok=True)
+    with open(os.path.join(out_dir, "result.json"), "w") as fh:
+        json.dump(result, fh, indent=2, default=str)
+    with open(os.path.join(out_dir, "report.md"), "w") as fh:
+        fh.write(narrative)
+    return out_dir
+
+
+def _serve_cmd(argv: list) -> int:
+    from . import serve
+    sp = argparse.ArgumentParser(prog="rca serve",
+                                 description="Interactive local web UI with a base-branch picker.")
+    sp.add_argument("--repo", default=".", help="repo path (default: cwd)")
+    sp.add_argument("--host", default="127.0.0.1", help="bind host (default: 127.0.0.1)")
+    sp.add_argument("--port", type=int, default=8722, help="port (default: 8722)")
+    sp.add_argument("--no-open", action="store_true", help="don't open a browser")
+    a = sp.parse_args(argv)
+    return serve.run(repo=a.repo, host=a.host, port=a.port, open_browser=not a.no_open)
+
+
+def main(argv: Optional[list] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "serve":
+        return _serve_cmd(argv[1:])
+
+    p = argparse.ArgumentParser(prog="rca", description="Root-cause analysis for a PR or branch.")
+    p.add_argument("pr", nargs="?", type=int, help="PR number (optional)")
+    p.add_argument("--pr", dest="pr_flag", type=int, help="PR number")
+    p.add_argument("--repo", default=".", help="repo path (default: cwd)")
+    p.add_argument("--base", default=None,
+                   help="base ref for the diff. Default (local, no PR): the latest commit "
+                        "(HEAD~1) — 'the change I just made'. Pass a branch (e.g. develop) "
+                        "to analyze a whole branch.")
+    p.add_argument("--head", default=None, help="head ref (default: current branch)")
+    p.add_argument("--last", action="store_true",
+                   help="analyze only the latest commit (HEAD~1), ignoring the configured base")
+    p.add_argument("--force", choices=["bugfix", "feature"], help="override classification")
+    p.add_argument("--mode", choices=["harness", "api"], default="harness",
+                   help="reasoning layer (default: harness)")
+    p.add_argument("--fast", action="store_true", help="api mode: use the faster/cheaper model")
+    p.add_argument("--json", action="store_true", help="print structured result only")
+    p.add_argument("--html", metavar="PATH", help="write a self-contained HTML report to PATH")
+    p.add_argument("--open", dest="open_", action="store_true", help="open the HTML report in a browser")
+    p.add_argument("--narrative-file", metavar="PATH",
+                   help="embed a pre-written markdown narrative in the HTML report")
+    p.add_argument("--no-save", action="store_true", help="don't write to ~/culprit/output")
+    args = p.parse_args(argv)
+
+    repo = os.path.abspath(os.path.expanduser(args.repo))
+    pr = args.pr_flag if args.pr_flag is not None else args.pr
+
+    # Base resolution (local mode): --last forces latest commit; else explicit
+    # --base; else the repo's configured base (CULPRIT_BASE / .culprit.toml);
+    # else None → latest commit.
+    if args.last:
+        base = None
+    elif args.base is not None:
+        base = args.base
+    else:
+        base = config.repo_base(repo)
+
+    result = analyze(repo, pr=pr, base=base, head=args.head, force=args.force)
+
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+        return 0
+
+    # Resolve the "why" narrative for the report: an explicit file wins, else
+    # the API adapter generates one; harness mode leaves it empty (the visual
+    # timeline stands on its own with no API key).
+    narrative_md = ""
+    if args.narrative_file:
+        with open(os.path.expanduser(args.narrative_file), encoding="utf-8") as fh:
+            narrative_md = fh.read()
+    elif args.mode == "api":
+        narrative_md = reasoning.get_adapter(mode="api", fast=args.fast).explain(result)
+
+    if args.html:
+        from . import htmlreport
+        out_path = os.path.abspath(os.path.expanduser(args.html))
+        with open(out_path, "w", encoding="utf-8") as fh:
+            fh.write(htmlreport.render(result, narrative_md))
+        sys.stderr.write("Wrote HTML report to {}\n".format(out_path))
+        if args.open_:
+            import webbrowser
+            webbrowser.open("file://" + out_path)
+        return 0
+
+    # Default: markdown to stdout.
+    narrative = narrative_md or reasoning.get_adapter(mode=args.mode, fast=args.fast).explain(result)
+    print(narrative)
+
+    if not args.no_save:
+        out_dir = _save(result, narrative)
+        sys.stderr.write("\nSaved to {}\n".format(out_dir))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

culprit/config.py

@@ -0,0 +1,43 @@
+"""Per-repo configuration so culprit can track a repo's real base branch (and host).
+
+Resolution order for the default base (local mode only — a PR always carries
+its own base):
+  1. ``--base`` on the CLI (handled by the caller)
+  2. ``CULPRIT_BASE`` environment variable
+  3. ``base = "..."`` in a ``.culprit.toml`` at the repo root
+  4. None → fall back to the latest commit (HEAD~1)
+
+``host`` (``CULPRIT_HOST`` / ``host = "gitlab"``) overrides host auto-detection
+for self-hosted forges where the URL alone can't tell GitHub from GitLab/Gitea.
+
+The ``.culprit.toml`` parse is intentionally tiny (one regex, no TOML dep) so
+the package stays dependency-free on Python 3.9.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+
+def _get(repo: str, key: str, env: str) -> Optional[str]:
+    val = os.environ.get(env)
+    if val:
+        return val.strip()
+    path = os.path.join(repo, ".culprit.toml")
+    try:
+        with open(path) as fh:
+            text = fh.read()
+    except (IOError, OSError):
+        return None
+    m = re.search(r"""^\s*{}\s*=\s*['"]?([^'"\n#]+?)['"]?\s*(?:#.*)?$""".format(re.escape(key)),
+                  text, re.M)
+    return m.group(1).strip() if m else None
+
+
+def repo_base(repo: str) -> Optional[str]:
+    return _get(repo, "base", "CULPRIT_BASE")
+
+
+def repo_host(repo: str) -> Optional[str]:
+    return _get(repo, "host", "CULPRIT_HOST")

culprit/evolution.py

@@ -0,0 +1,171 @@
+"""Line-evolution timeline: how the buggy lines became a bug, commit by commit.
+
+For each line range the fix touched, ``git log -L<start>,<end>:<file>`` over the
+base history gives every commit that ever modified those exact lines, oldest
+first. We tag the earliest as ``origin``, the prime-suspect commit as
+``suspect``, the rest as ``modified``, and append a synthetic ``fix`` step from
+the fix diff. That ordered list is what the HTML report visualizes as a vertical
+timeline (origin → … → the commit that broke it → the fix).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import _proc
+from .suspect import _parse_hunks, _iso, _pr_for_commit
+
+# Field/record delimiters that won't appear in commit metadata.
+_SOH, _US, _STX = "\x01", "\x1f", "\x02"
+_FMT = _SOH + "%H" + _US + "%an" + _US + "%aI" + _US + "%s" + _STX
+
+_MAX_PR_LOOKUPS = 12  # _pr_for_commit is costly; bound total lookups per run
+
+
+def _hunk_text(body: str) -> str:
+    """Keep the unified-diff from the first @@ hunk header onward (drop the
+    `diff --git` / `index` / `---` / `+++` preamble)."""
+    lines = body.splitlines()
+    out: List[str] = []
+    started = False
+    for ln in lines:
+        if not started and ln.startswith("@@"):
+            started = True
+        if started:
+            out.append(ln)
+    return "\n".join(out).strip("\n")
+
+
+def _file_block(diff: str, path: str) -> str:
+    """Extract the fix's diff block for `path` from the full unified diff."""
+    lines = (diff or "").splitlines()
+    block: List[str] = []
+    capturing = False
+    for ln in lines:
+        if ln.startswith("diff --git "):
+            if capturing:
+                break
+            capturing = ("a/" + path in ln) or ("b/" + path in ln) or (path in ln)
+            if capturing:
+                block = []
+            continue
+        if capturing:
+            block.append(ln)
+    return _hunk_text("\n".join(block))
+
+
+def _log_L(repo: str, start: int, end: int, path: str, base: str) -> List[Dict[str, Any]]:
+    """Parse `git log -L<start>,<end>:<file> --reverse <base>` into ordered steps."""
+    spec = "-L{},{}:{}".format(start, end, path)
+    try:
+        out = _proc.git(
+            ["log", "--reverse", spec, "--format=" + _FMT, str(base)],
+            repo, check=False,
+        )
+    except _proc.ProcError:
+        return []
+    steps: List[Dict[str, Any]] = []
+    # Each commit block starts at _SOH; split and drop the empty leading chunk.
+    for chunk in out.split(_SOH)[1:]:
+        if _STX not in chunk:
+            continue
+        header, body = chunk.split(_STX, 1)
+        fields = header.split(_US)
+        if len(fields) < 4:
+            continue
+        sha, author, date_iso, subject = fields[0], fields[1], fields[2], fields[3]
+        steps.append({
+            "hash": sha.strip(),
+            "short": sha.strip()[:10],
+            "author": author,
+            "date": date_iso,
+            "subject": subject,
+            "diff": _hunk_text(body),
+        })
+    return steps
+
+
+def build_timeline(ctx: Dict[str, Any], repo: str, suspects: List[Dict[str, Any]],
+                   max_ranges: int = 10, max_steps: int = 25) -> Dict[str, Any]:
+    """Build per-range line-evolution timelines. Returns {ranges:[...], notes:[...]}."""
+    base = ctx.get("base_sha") or ctx.get("base_ref")
+    head_diff = ctx.get("diff") or ""
+    notes: List[str] = []
+    if not base:
+        return {"ranges": [], "notes": ["no base revision; timeline unavailable"]}
+
+    suspect_hashes = {s["hash"] for s in suspects} if suspects else set()
+    prime = suspects[0]["hash"] if suspects else None
+
+    parsed = _parse_hunks(head_diff)
+    pairs: List[Tuple[str, int, int]] = []
+    for f in parsed:
+        path = f["old_path"]
+        for (start, end) in (f["removed_ranges"] or f["context_ranges"]):
+            pairs.append((path, start, end))
+    if len(pairs) > max_ranges:
+        notes.append("{} buggy ranges; showing the first {}".format(len(pairs), max_ranges))
+        pairs = pairs[:max_ranges]
+
+    pr_cache: Dict[str, Optional[int]] = {}
+    pr_budget = [_MAX_PR_LOOKUPS]
+    head = ctx.get("head_sha") or ctx.get("head_ref") or "HEAD"
+
+    def pr_for(sha: str) -> Optional[int]:
+        if sha in pr_cache:
+            return pr_cache[sha]
+        if pr_budget[0] <= 0:
+            return None
+        pr_budget[0] -= 1
+        pr_cache[sha] = _pr_for_commit(repo, sha, str(head))
+        return pr_cache[sha]
+
+    ranges_out: List[Dict[str, Any]] = []
+    for (path, start, end) in pairs:
+        steps = _log_L(repo, start, end, path, str(base))
+        if not steps:
+            continue
+        truncated = False
+        if len(steps) > max_steps:
+            steps = [steps[0]] + steps[-(max_steps - 1):]
+            truncated = True
+
+        # Only the PRIME suspect is the red "broke" node — one clear culprit.
+        # The earliest commit is the origin; everything else is a modification.
+        # (Other ranked suspects still appear in the suspect-set section.)
+        has_prime = any(st["hash"] == prime for st in steps)
+        for i, st in enumerate(steps):
+            if st["hash"] == prime:
+                st["role"] = "suspect"
+            elif i == 0:
+                st["role"] = "origin"
+            else:
+                st["role"] = "modified"
+            # PR attribution: only spend the budget on the interesting steps.
+            st["pr_number"] = pr_for(st["hash"]) if st["role"] in ("origin", "suspect") else None
+        # If the prime suspect didn't touch this range, mark the latest pre-fix
+        # commit as the suspect so every range still shows where it last changed.
+        if not has_prime and len(steps) > 1:
+            steps[-1]["role"] = "suspect"
+            steps[-1]["pr_number"] = pr_for(steps[-1]["hash"])
+
+        # Synthetic fix step from the head diff for this file.
+        fix_diff = _file_block(head_diff, path)
+        steps.append({
+            "hash": ctx.get("head_sha") or "",
+            "short": (ctx.get("head_sha") or "")[:10] or (ctx.get("head_ref") or "HEAD"),
+            "author": None,
+            "subject": ctx.get("title") or "THE FIX",
+            "date": ctx.get("head_date"),
+            "pr_number": ctx.get("pr_number"),
+            "role": "fix",
+            "diff": fix_diff,
+        })
+
+        ranges_out.append({
+            "file": path,
+            "range": [start, end],
+            "truncated": truncated,
+            "steps": steps,
+        })
+
+    return {"ranges": ranges_out, "notes": notes}

culprit/htmlreport.py

@@ -0,0 +1,37 @@
+"""Render a self-contained HTML RCA report from a structured result.
+
+One file, no external CDN, no build step: the template ships as package data,
+the result JSON and an optional narrative are injected as text nodes. Open the
+output in any browser — works offline.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+try:  # Python 3.9+: importlib.resources.files
+    from importlib.resources import files as _res_files
+
+    def _template() -> str:
+        return _res_files("culprit").joinpath("templates/report.html").read_text(encoding="utf-8")
+except Exception:  # pragma: no cover - very old runtimes
+    import os
+
+    def _template() -> str:
+        here = os.path.dirname(__file__)
+        with open(os.path.join(here, "templates", "report.html"), encoding="utf-8") as fh:
+            return fh.read()
+
+
+def _safe_json(obj: Any) -> str:
+    # Embedded in a <script type="application/json"> node read via JSON.parse;
+    # the only sequence that can break out of the node is "</".
+    return json.dumps(obj, default=str).replace("</", "<\\/")
+
+
+def render(result: Dict[str, Any], narrative_md: str = "") -> str:
+    tpl = _template()
+    data = _safe_json(result)
+    narrative = (narrative_md or "").replace("</script", "<\\/script")
+    # Placeholders are unique literals in the template.
+    return tpl.replace("__CULPRIT_DATA__", data).replace("__NARRATIVE__", narrative)