gitfence 0.1.0__py3-none-any.whl

fence/render.py

@@ -0,0 +1,287 @@
+"""Human and JSON output. Verdict first, one-sentence reason, evidence, then detail.
+
+Meaning never depends on colour: every coloured word is also a text label, so
+output reads the same in plain terminals, CI logs and screen readers.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import asdict
+from datetime import UTC, datetime
+
+import typer
+
+from fence.check.engine import CLEAR, KEEP, SAFE, VERIFY, CheckResult, Finding
+from fence.decisions.build import WhyResult
+from fence.decisions.model import SCHEMA, SCORE_NOTE, DecisionRecord, Evidence, Score
+from fence.text import quoted
+
+_COLORS = {KEEP: "red", VERIFY: "yellow", CLEAR: "green", SAFE: "cyan",
+           "critical": "red", "high": "red", "medium": "yellow", "low": "green"}
+
+
+class Out:
+    def __init__(self, color: str = "auto", *, max_items: int = 10, verbose: bool = False) -> None:
+        if color == "auto":
+            self.color = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+        else:
+            self.color = color == "always"
+        self.max_items = max_items
+        self.verbose = verbose
+
+    def c(self, text: str, key: str | None = None, *, bold: bool = False) -> str:
+        if not self.color:
+            return text
+        return typer.style(text, fg=_COLORS.get(key or text), bold=bold)
+
+
+def _date(ts: int | None) -> str:
+    return datetime.fromtimestamp(ts, UTC).strftime("%Y-%m-%d") if ts else "unknown date"
+
+
+def _ev_line(e: Evidence) -> str:
+    status = "" if e.retrieval_status == "ok" else f" ({e.retrieval_status.replace('_', ' ')})"
+    ref = e.ref[:12] if e.type in ("commit", "revert") else e.ref
+    link = f"  {e.url}" if e.url else ""
+    return f"{e.id} {e.type} {ref}{status}{link}"
+
+
+def _factors(s: Score, n: int = 3) -> str:
+    return "; ".join(f"{f.points:+g} {f.reason}" for f in s.top(n))
+
+
+def _reason(d: DecisionRecord) -> str:
+    if d.stated_reason:
+        src = next((e for e in d.evidence if e.id == d.stated_reason_evidence), None)
+        where = f"{src.type} {src.ref[:12] if src.type == 'commit' else src.ref}" if src else "?"
+        return f"{quoted(d.stated_reason)} (quoted from {where})"
+    return d.reason_text
+
+
+def decision_text(d: DecisionRecord, o: Out, *, full: bool = False) -> list[str]:
+    s = d.strength
+    commit = d.evidence[0]
+    head = (f"{o.c(f'[{s.band.upper()} {s.value}]', s.band, bold=True)} {d.type} | grade {d.grade}"
+            f" | confidence {s.confidence:.2f} | {d.id}")
+    lines = [head, f"  Why: {_reason(d)}"]
+    subject = (commit.quote or "").split("\n", 1)[0]
+    lines.append(f"  Introduced {_date(d.introduced_at)} by {commit.author or 'unknown'} in "
+                 f"{d.introduced_sha[:12]} \"{subject}\"")
+    spans = ", ".join(f"{a.start_line}" + (f"-{a.end_line}" if a.end_line != a.start_line else "")
+                      + (f" ({a.symbol})" if a.symbol else "") for a in d.anchors)
+    lines.append(f"  Lines: {spans}" + (f" | status {d.status}" if d.status != "active" else ""))
+    if d.constraints:
+        lines.append("  Constraint: " + " | ".join(f'"{c}"' for c in d.constraints[:2]))
+    lines.append(f"  Top factors: {_factors(s, 99 if full else 3)}")
+    ev = d.evidence if full else d.evidence[:4]
+    lines.append("  Evidence:" + ("" if ev else " none"))
+    lines += [f"    {_ev_line(e)}" for e in ev]
+    if len(d.evidence) > len(ev):
+        lines.append(f"    ... {len(d.evidence) - len(ev)} more (use --verbose)")
+    if s.what_would_change:
+        lines.append("  Would change this: " + "; ".join(s.what_would_change))
+    return lines
+
+
+def why_text(r: WhyResult, o: Out, *, full: bool = False) -> str:
+    t = r.target
+    span = f"{t.start}" if t.start == t.end else f"{t.start}-{t.end}"
+    sym = f" ({t.symbol})" if t.symbol else ""
+    n = len(r.decisions)
+    out = [f"{t.path}:{span}{sym} @ {t.rev[:12]} | {n} decision{'s' if n != 1 else ''}"]
+    if r.unexplained_lines:
+        out.append(f"{r.unexplained_lines} line(s) have no recoverable reason (grade D).")
+    for d in r.decisions[: o.max_items]:
+        out.append("")
+        out += decision_text(d, o, full=full or o.verbose)
+    if n > o.max_items:
+        out.append(f"\n... {n - o.max_items} more decisions (raise --max-items)")
+    if r.notes or r.decisions:
+        out.append("")
+        out += [f"Note: {x}" for x in r.notes]
+    if r.decisions:
+        out.append(f"Note: {SCORE_NOTE}")
+    return "\n".join(out)
+
+
+def ack_command(f: Finding, base: str, head_is_base: bool) -> str:
+    rev = "" if head_is_base else f" --rev {base[:12]}"
+    span = f"{f.start}" if f.start == f.end else f"{f.start}-{f.end}"
+    return (f'fence ack {f.decision.id} --at {f.path}:{span}{rev} '
+            f'--reason "<why it is safe to change>"')
+
+
+def finding_text(f: Finding, o: Out, base: str, head_is_base: bool) -> list[str]:
+    d, r = f.decision, f.risk
+    span = f"{f.start}" if f.start == f.end else f"{f.start}-{f.end}"
+    label = o.c(f"{f.verdict:<6}", f.verdict, bold=True)
+    acked = " | ACKNOWLEDGED" if f.ack else ""
+    lines = [f"{label} {f.path}:{span}  {f.kind}  risk {r.value} ({r.band}) | "
+             f"evidence confidence {r.confidence:.2f} | grade {d.grade}{acked}"]
+    preview = f.removed_preview.split("\n")
+    lines.append(f"  Change: {f.kind_reason}: " + preview[0].strip()
+                 + (f" (+{len(preview) - 1} lines)" if len(preview) > 1 else ""))
+    lines.append(f"  Why it matters: {_reason(d)}")
+    lines.append(f"  Decision {d.id}: {d.type}, introduced {_date(d.introduced_at)} in "
+                 f"{d.introduced_sha[:12]}")
+    lines.append("  Evidence: " + ", ".join(
+        f"{e.type} {e.ref[:12] if e.type in ('commit', 'revert') else e.ref}"
+        + ("" if e.retrieval_status == "ok" else f" ({e.retrieval_status.replace('_', ' ')})")
+        for e in d.evidence[:5]))
+    lines.append(f"  Factors: {_factors(r)}")
+    if f.ack:
+        lines.append(f'  Acknowledged by {f.ack.who} on {f.ack.when[:10]}: "{f.ack.reason}"')
+    elif f.verdict == KEEP:
+        lines.append("  Next: check with the decision's author or reviewers, or acknowledge:")
+        lines.append(f"    {ack_command(f, base, head_is_base)}")
+    elif f.verdict == VERIFY:
+        lines.append("  Next: confirm the reason no longer applies before merging.")
+    elif f.verdict == SAFE:
+        lines.append("  Next: possibly obsolete; verify the evidence, then remove.")
+    return lines
+
+
+def check_text(r: CheckResult, o: Out) -> str:
+    head_is_base = r.head is None
+    counts = {v: sum(1 for f in r.findings if f.verdict == v) for v in (KEEP, VERIFY, SAFE)}
+    out = [f"{o.c(r.verdict, r.verdict, bold=True)}: "
+           + (_summary_sentence(r, counts) if r.findings else "no meaningful decision affected.")]
+    shown = r.findings[: o.max_items]
+    for f in shown:
+        out.append("")
+        out += finding_text(f, o, r.base, head_is_base)
+    if len(r.findings) > len(shown):
+        out.append(f"\n... {len(r.findings) - len(shown)} more findings (raise --max-items)")
+    out.append("")
+    out.append(f"Checked {r.blocks_checked} change block(s) in {r.files_checked} file(s) "
+               f"against {r.base[:12]} in {r.seconds:.2f}s | exit {r.exit_code}"
+               + (" (bypassed by env)" if r.bypassed else ""))
+    for path, g in r.ghosts:
+        out.append(f"Ghost fence: {path} re-adds code (similarity {g.similarity}) that was "
+                   f"removed in {g.removed_in[:12]} \"{g.subject}\" from {g.path}.")
+    out += [f"Note: {x}" for x in r.notes]
+    if r.findings:
+        out.append(f"Note: {SCORE_NOTE}")
+    return "\n".join(out)
+
+
+def _summary_sentence(r: CheckResult, counts: dict[str, int]) -> str:
+    parts = [f"{n} {v}" for v, n in counts.items() if n]
+    top = r.findings[0]
+    return (f"{', '.join(parts)}. Top: {top.path}:{top.start} touches a {top.decision.type} "
+            f"decision ({top.decision.grade}).")
+
+
+COMMENT_MARKER = "<!-- fence:sticky -->"
+
+
+def check_markdown(r: CheckResult, ctx) -> str:
+    """PR comment / job summary. Only meaningful findings; links where we have them."""
+    out = [COMMENT_MARKER, f"### Fence check: **{r.verdict}**", ""]
+    if not r.findings:
+        out.append("No meaningful decision affected by this change.")
+    for f in r.findings[:15]:
+        d = f.decision
+        commit = d.introduced_sha[:12]
+        url = ctx.commit_url(d.introduced_sha) if ctx else None
+        commit_md = f"[{commit}]({url})" if url else f"`{commit}`"
+        acked = " (acknowledged)" if f.ack else ""
+        out.append(f"**{f.verdict}**{acked} `{f.path}:{f.start}` | {f.kind} | risk {f.risk.value} "
+                   f"({f.risk.band}) | grade {d.grade} | confidence {f.risk.confidence:.2f}")
+        out += ["", f"> {_reason(d).replace(chr(10), ' ')}", ""]
+        out.append(f"- Decision `{d.id}` ({d.type}) from {commit_md}")
+        out.append(f"- Evidence: {_md_evidence(d, 4)}")
+        out.append(f"- Factors: {_factors(f.risk)}")
+        if not f.ack and f.verdict == KEEP:
+            out.append(f"<sub>To proceed: `{ack_command(f, r.base, r.head is None)}`</sub>")
+        out.append("")
+    if len(r.findings) > 15:
+        out.append(f"... and {len(r.findings) - 15} more.")
+    out.append(f"<sub>{r.blocks_checked} change blocks in {r.files_checked} files against "
+               f"`{r.base[:12]}`. Repository text above is quoted evidence. "
+               f"{SCORE_NOTE}</sub>")
+    return "\n".join(out)
+
+
+def _md_evidence(d: DecisionRecord, n: int) -> str:
+    def one(e: Evidence) -> str:
+        label = f"{e.type} {e.ref[:12] if e.type in ('commit', 'revert') else e.ref}"
+        status = "" if e.retrieval_status == "ok" else f" ({e.retrieval_status.replace('_', ' ')})"
+        return (f"[{label}]({e.url})" if e.url else label) + status
+    return ", ".join(one(e) for e in d.evidence[:n]) or "none"
+
+
+def why_markdown(r: WhyResult, ctx) -> str:
+    """The same fields as the text output, for PR descriptions, issues and docs."""
+    t = r.target
+    span = f"{t.start}" if t.start == t.end else f"{t.start}-{t.end}"
+    sym = f" ({t.symbol})" if t.symbol else ""
+    out = [f"### Fence why: `{t.path}:{span}`{sym} @ `{t.rev[:12]}`", ""]
+    if r.unexplained_lines:
+        out += [f"{r.unexplained_lines} line(s) have no recoverable reason (grade D).", ""]
+    for d in r.decisions:
+        s = d.strength
+        url = ctx.commit_url(d.introduced_sha) if ctx else None
+        commit = d.introduced_sha[:12]
+        commit_md = f"[{commit}]({url})" if url else f"`{commit}`"
+        lines = ", ".join(f"{a.start_line}" + (f"-{a.end_line}" if a.end_line != a.start_line
+                                               else "") + (f" ({a.symbol})" if a.symbol else "")
+                          for a in d.anchors)
+        out.append(f"**{s.band.upper()} {s.value}** {d.type} | grade {d.grade} | "
+                   f"confidence {s.confidence:.2f} | `{d.id}`")
+        out += ["", f"> {_reason(d).replace(chr(10), ' ')}", ""]
+        out.append(f"- Introduced {_date(d.introduced_at)} by "
+                   f"{d.evidence[0].author or 'unknown'} in {commit_md}")
+        out.append(f"- Lines: {lines}" + (f" | status {d.status}" if d.status != "active" else ""))
+        if d.constraints:
+            out.append("- Constraint: " + " | ".join(f'"{c}"' for c in d.constraints[:2]))
+        out.append(f"- Factors: {_factors(s)}")
+        out.append(f"- Evidence: {_md_evidence(d, 6)}")
+        if s.what_would_change:
+            out.append("- Would change this: " + "; ".join(s.what_would_change))
+        out.append("")
+    out += [f"Note: {x}" for x in r.notes]
+    out.append(f"<sub>Repository text above is quoted evidence. {SCORE_NOTE}</sub>")
+    return "\n".join(out)
+
+
+# JSON ---------------------------------------------------------------------------
+
+def why_json(r: WhyResult) -> dict:
+    return {
+        "schema": SCHEMA, "kind": "why",
+        "target": asdict(r.target),
+        "decisions": [d.to_dict() for d in r.decisions],
+        "unexplained_lines": r.unexplained_lines,
+        "notes": r.notes, "score_note": SCORE_NOTE,
+    }
+
+
+def finding_dict(f: Finding, base: str, head_is_base: bool) -> dict:
+    return {
+        "verdict": f.verdict, "path": f.path, "start": f.start, "end": f.end, "kind": f.kind,
+        "kind_reason": f.kind_reason, "risk": {**asdict(f.risk),
+                                               "top_factors": [asdict(x) for x in f.risk.top()]},
+        "decision": f.decision.to_dict(), "decision_fingerprint": f.decision_fingerprint,
+        "removed_preview": f.removed_preview, "lost_signals": list(f.lost_signals),
+        "ack": asdict(f.ack) if f.ack else None,
+        "ack_command": None if f.ack else ack_command(f, base, head_is_base),
+    }
+
+
+def check_json(r: CheckResult) -> dict:
+    return {
+        "schema": SCHEMA, "kind": "check", "verdict": r.verdict, "exit_code": r.exit_code,
+        "base": r.base, "head": r.head, "bypassed": r.bypassed,
+        "files_checked": r.files_checked, "blocks_checked": r.blocks_checked,
+        "seconds": r.seconds, "notes": r.notes, "score_note": SCORE_NOTE,
+        "findings": [finding_dict(f, r.base, r.head is None) for f in r.findings],
+        "ghosts": [{"path": p, **asdict(g)} for p, g in r.ghosts],
+    }
+
+
+def dumps(obj: object) -> str:
+    return json.dumps(obj, indent=2, sort_keys=False, ensure_ascii=False, default=str)

fence/report.py

@@ -0,0 +1,103 @@
+"""`fence report`: where the load-bearing code is, for a tech lead (F6)."""
+
+from __future__ import annotations
+
+import html
+from collections import Counter
+
+from fence.context import Context
+from fence.scan import scan
+
+
+def build(ctx: Context, path: str = ".", *, limit: int = 15, max_files: int = 300) -> dict:
+    res = scan(ctx, path, max_files=max_files)
+    churn: Counter[str] = Counter()
+    owners: dict[str, Counter[str]] = {}
+    for row in ctx.store.conn.execute(
+        "SELECT f.path, c.author_email FROM file_changes f JOIN commits c ON c.sha = f.sha "
+        "WHERE c.orphaned = 0 AND c.format_only = 0"
+    ):
+        churn[row["path"]] += 1
+        owners.setdefault(row["path"], Counter())[row["author_email"]] += 1
+
+    def item(f: str, d) -> dict:
+        return {"file": f, "lines": [[a.start_line, a.end_line] for a in d.anchors],
+                "strength": d.strength.value, "band": d.strength.band, "grade": d.grade,
+                "type": d.type, "decision": d.id, "reason": d.reason_text,
+                "commits_to_file": churn.get(f, 0)}
+
+    ranked = [item(f, d) for f, d in res.decisions]
+    fragile = [x for x in ranked if x["grade"] in ("C", "D")
+               and x["strength"] >= ctx.cfg.scoring.verify_min_risk]
+    hot = sorted((x for x in ranked if x["strength"] >= ctx.cfg.scoring.bands.medium),
+                 key=lambda x: (-x["strength"] * x["commits_to_file"], x["file"]))
+    files = sorted({f for f, _ in res.decisions})
+    concentration = []
+    for f in files:
+        c = owners.get(f)
+        if not c or sum(c.values()) < 5:
+            continue
+        top, n = c.most_common(1)[0]
+        share = n / sum(c.values())
+        if share >= 0.8:
+            concentration.append({"file": f, "top_author_share": round(share, 2),
+                                  "commits": sum(c.values()), "authors": len(c)})
+    return {
+        "schema": "fence/v1", "kind": "report", "path": res.path,
+        "files_scanned": res.files_scanned, "decisions": len(ranked), "notes": res.notes,
+        "load_bearing": ranked[:limit], "fragile_undocumented": fragile[:limit],
+        "hot_and_strong": hot[:limit], "ownership_concentration": concentration[:limit],
+    }
+
+
+def to_markdown(r: dict) -> str:
+    out = [f"# Fence report: `{r['path']}`", "",
+           f"{r['decisions']} decisions in {r['files_scanned']} files.", ""]
+
+    def table(title: str, rows: list[dict], cols: list[str]) -> None:
+        out.append(f"## {title}")
+        if not rows:
+            out.extend(["", "None.", ""])
+            return
+        out.extend(["", "| " + " | ".join(cols) + " |", "|" + "---|" * len(cols)])
+        for x in rows:
+            vals = []
+            for c in cols:
+                v = x.get(c)
+                if c == "lines":
+                    v = ",".join(f"{a}-{b}" for a, b in v[:3])
+                vals.append(str(v).replace("|", "\\|").replace("\n", " ")[:120])
+            out.append("| " + " | ".join(vals) + " |")
+        out.append("")
+
+    main = ["file", "lines", "strength", "grade", "type", "reason"]
+    table("Load-bearing code (do not simply delete)", r["load_bearing"], main)
+    table("Fragile and undocumented (strong, but reason only inferred or unknown)",
+          r["fragile_undocumented"], main)
+    table("Strong and frequently changed", r["hot_and_strong"], [*main[:4], "commits_to_file"])
+    table("Ownership concentration (>= 80% of commits by one person)",
+          r["ownership_concentration"], ["file", "top_author_share", "commits", "authors"])
+    out += [f"Note: {n}" for n in r["notes"]]
+    return "\n".join(out)
+
+
+def to_html(r: dict) -> str:
+    md = to_markdown(r)
+    body = []
+    for line in md.splitlines():
+        e = html.escape(line)
+        if line.startswith("# "):
+            body.append(f"<h1>{e[2:]}</h1>")
+        elif line.startswith("## "):
+            body.append(f"<h2>{e[3:]}</h2>")
+        elif line.startswith("|---"):
+            continue
+        elif line.startswith("| "):
+            cells = [html.escape(c.strip()) for c in line.strip("|").split(" | ")]
+            body.append("<tr>" + "".join(f"<td>{c}</td>" for c in cells) + "</tr>")
+        elif line:
+            body.append(f"<p>{e}</p>")
+    return ("<!doctype html><meta charset=utf-8><title>Fence report</title>"
+            "<style>body{font:14px system-ui;margin:2em;max-width:1100px}"
+            "td{border-bottom:1px solid #ddd;padding:4px 8px;vertical-align:top}</style>"
+            + "\n".join(body))

fence/scan.py

@@ -0,0 +1,50 @@
+"""`fence scan DIR`: every decision in a directory, ranked by "do not simply delete"."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from fence.context import Context
+from fence.decisions.build import WhyError, why
+from fence.decisions.model import DecisionRecord
+from fence.git.runner import GitError
+from fence.globs import match_any
+from fence.lang import plugin_for
+
+MAX_FILES = 300
+
+
+@dataclass
+class ScanResult:
+    path: str
+    decisions: list[tuple[str, DecisionRecord]] = field(default_factory=list)  # (file, record)
+    files_scanned: int = 0
+    files_skipped: int = 0
+    notes: list[str] = field(default_factory=list)
+
+
+def scan(ctx: Context, path: str = ".", *, rev: str = "HEAD", max_files: int = MAX_FILES,
+         deep: bool = False) -> ScanResult:
+    rev_sha = ctx.repo.verify_ref(rev)
+    rel = "." if path in (".", "") else ctx.repo.safe_relpath(path)
+    out = ctx.repo.run(["ls-tree", "-r", "--name-only", "-z", rev_sha, "--", rel])
+    files = [f for f in out.split("\x00") if f]
+    files = [f for f in files if not match_any(f, ctx.cfg.index.exclude)
+             and not match_any(f, ctx.cfg.policy.ignore_paths)]
+    # Source files first; then others. Stable order.
+    files.sort(key=lambda f: (plugin_for(f) is None, f))
+    res = ScanResult(rel)
+    if len(files) > max_files:
+        res.notes.append(f"{len(files)} files; scanned the first {max_files} (source files first)")
+        res.files_skipped = len(files) - max_files
+        files = files[:max_files]
+    for f in files:
+        try:
+            w = why(ctx, f, rev=rev_sha, deep=deep)
+        except (WhyError, GitError):
+            res.files_skipped += 1
+            continue
+        res.files_scanned += 1
+        res.decisions += [(f, d) for d in w.decisions if d.type != "cleanup"]
+    res.decisions.sort(key=lambda fd: (-fd[1].strength.value, fd[0], fd[1].id))
+    return res

fence/scoring/calibration.py

@@ -0,0 +1,133 @@
+"""Outcome calibration: Change Risk -> observed regret rate, from backtest data.
+
+The table is fitted offline with isotonic regression (pool-adjacent-violators) on
+backtest outcomes and shipped as static data (calibration.json). Nothing is
+computed at check time, so results stay deterministic. Bins are merged until each
+holds at least MIN_BIN blocks and MIN_POSITIVE regrets (except a trailing all-zero
+bin), so no rate rests on a handful of cases. Equal neighbouring rates are merged,
+which makes rates strictly increasing with risk.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+TABLE = Path(__file__).with_name("calibration.json")
+MIN_BIN = 30
+MIN_POSITIVE = 2
+
+
+@dataclass(frozen=True)
+class Bin:
+    risk_min: int
+    risk_max: int
+    n: int
+    regretted: int
+
+    @property
+    def rate(self) -> float:
+        return self.regretted / self.n if self.n else 0.0
+
+
+def _merge(a: Bin, b: Bin) -> Bin:
+    return Bin(a.risk_min, b.risk_max, a.n + b.n, a.regretted + b.regretted)
+
+
+def _pool(bins: list[Bin]) -> list[Bin]:
+    """Pool adjacent violators: merge until rates strictly increase."""
+    out: list[Bin] = []
+    for b in bins:
+        out.append(b)
+        while len(out) >= 2 and out[-2].rate >= out[-1].rate:
+            hi, lo = out.pop(), out.pop()
+            out.append(_merge(lo, hi))
+    return out
+
+
+def fit(points: Iterable[tuple[int, bool]]) -> list[Bin]:
+    """Isotonic fit of P(regret) over integer Change Risk, as merged bins."""
+    by_risk: dict[int, list[int]] = {}
+    for risk, regretted in points:
+        c = by_risk.setdefault(int(risk), [0, 0])
+        c[0] += 1
+        c[1] += int(bool(regretted))
+    bins = _pool([Bin(r, r, n, k) for r, (n, k) in sorted(by_risk.items())])
+    # Minimum support: grow each bin until it has MIN_BIN blocks and MIN_POSITIVE regrets.
+    supported: list[Bin] = []
+    cur: Bin | None = None
+    for b in bins:
+        cur = b if cur is None else _merge(cur, b)
+        if cur.n >= MIN_BIN and cur.regretted >= MIN_POSITIVE:
+            supported.append(cur)
+            cur = None
+    if cur is not None:
+        if supported:
+            supported[-1] = _merge(supported[-1], cur)
+        else:
+            supported.append(cur)
+    out = _pool(supported)
+    # Cover 0-100 with no gaps: each bin runs up to the next bin's start.
+    for i, b in enumerate(out):
+        lo = 0 if i == 0 else b.risk_min
+        hi = 100 if i == len(out) - 1 else out[i + 1].risk_min - 1
+        out[i] = Bin(lo, hi, b.n, b.regretted)
+    return out
+
+
+def write(bins: list[Bin], path: Path, provenance: dict) -> None:
+    data = {"provenance": provenance,
+            "bins": [{"risk_min": b.risk_min, "risk_max": b.risk_max, "n": b.n,
+                      "regretted": b.regretted, "rate": round(b.rate, 4)} for b in bins]}
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+@lru_cache(maxsize=4)
+def load(path: str = str(TABLE)) -> tuple[tuple[Bin, ...], dict]:
+    p = Path(path)
+    if not p.is_file():
+        return (), {}
+    data = json.loads(p.read_text(encoding="utf-8"))
+    bins = tuple(Bin(b["risk_min"], b["risk_max"], b["n"], b["regretted"])
+                 for b in data.get("bins", []))
+    return bins, data.get("provenance", {})
+
+
+def lookup(risk: int) -> Bin | None:
+    """The calibration bin for a Change Risk value, or None if no table is shipped."""
+    bins, _ = load()
+    for b in bins:
+        if b.risk_min <= risk <= b.risk_max:
+            return b
+    return None
+
+
+def main(argv: list[str] | None = None) -> None:
+    """python -m fence.scoring.calibration OUT.json DUMP.jsonl... (backtest --dump files)."""
+    import sys
+    from datetime import date
+
+    from fence import __version__
+
+    args = argv if argv is not None else sys.argv[1:]
+    out, dumps = Path(args[0]), [Path(a) for a in args[1:]]
+    points = []
+    for d in dumps:
+        for line in d.read_text(encoding="utf-8").splitlines():
+            r = json.loads(line)
+            points.append((r["risk"], r["regretted"]))
+    bins = fit(points)
+    write(bins, out, {"fitted_on": [d.stem for d in dumps], "blocks": len(points),
+                      "regretted": sum(k for _, k in points), "date": date.today().isoformat(),
+                      "fence_version": __version__, "method": "isotonic (PAV), min support "
+                      f"{MIN_BIN} blocks / {MIN_POSITIVE} regrets per bin"})
+    for b in bins:
+        print(f"risk {b.risk_min:>3}-{b.risk_max:<3} n={b.n:<5} regretted={b.regretted:<3} "
+              f"rate={b.rate:.3f}")
+
+
+if __name__ == "__main__":
+    main()