breakproof 0.1.1__py3-none-any.whl

breakproof/__init__.py

@@ -0,0 +1,3 @@
+"""Breakproof: fail the PR only when you actually broke something."""
+
+__version__ = "0.1.1"

breakproof/cli.py

@@ -0,0 +1,167 @@
+"""breakproof CLI. Reads a lot, writes only what you point it at.
+
+Exit codes: 0 pass, 1 fail (something broke), 2 you broke the invocation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from breakproof import __version__
+from breakproof.extract import scan_path
+from breakproof.prgate import build_gate, render_gate_markdown
+from breakproof.radar import build_api_diff, render_radar_markdown
+
+MAX_CONTRACT_BYTES = 50_000_000
+
+
+def _force_utf8() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if hasattr(stream, "reconfigure"):
+                stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
+_force_utf8()
+
+
+def _load_contract(source: str) -> dict:
+    if not isinstance(source, str) or not source:
+        raise ValueError("empty contract source")
+    if os.path.isdir(source):
+        return scan_path(source)
+    try:
+        if os.path.getsize(source) > MAX_CONTRACT_BYTES:
+            raise ValueError(f"contract file too large: {source}")
+    except OSError as exc:
+        raise ValueError(f"cannot read contract: {exc}") from exc
+    try:
+        with open(source, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError) as exc:
+        raise ValueError(f"bad contract JSON: {exc}") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("endpoints"), list):
+        return {"endpoints": [], "edges": []}
+    edges = data.get("edges") if isinstance(data.get("edges"), list) else []
+    return {"endpoints": data["endpoints"], "edges": edges}
+
+
+def _write_file(path: str, content: str) -> None:
+    """Write exactly one file the user named. Nothing else. Ever."""
+    parent = os.path.dirname(os.path.abspath(path))
+    os.makedirs(parent, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(content)
+
+
+def _cmd_scan(args) -> int:
+    try:
+        contract = scan_path(args.path, service=args.service or "")
+    except ValueError as exc:
+        print(f"breakproof: {exc}", file=sys.stderr)
+        return 2
+    payload = json.dumps(contract, indent=2, sort_keys=True) + "\n"
+    if args.out:
+        try:
+            _write_file(args.out, payload)
+        except OSError as exc:
+            print(f"breakproof: cannot write {args.out}: {exc}", file=sys.stderr)
+            return 2
+    else:
+        try:
+            print(payload, end="")
+        except BrokenPipeError:
+            return 0
+    print(f"endpoints={len(contract['endpoints'])}", file=sys.stderr)
+    return 0
+
+
+def _cmd_diff(args) -> int:
+    base_src = args.base or args.base_dir
+    head_src = args.head or args.head_dir
+    if not base_src or not head_src:
+        print("breakproof diff: need --base/--base-dir and --head/--head-dir",
+              file=sys.stderr)
+        return 2
+    try:
+        base = _load_contract(base_src)
+        head = _load_contract(head_src)
+    except ValueError as exc:
+        print(f"breakproof: {exc}", file=sys.stderr)
+        return 2
+    gate = build_gate(base, head, base_ref=args.base_ref or "",
+                      head_ref=args.head_ref or "")
+    md = render_gate_markdown(gate)
+    try:
+        if args.markdown:
+            _write_file(args.markdown, md + "\n")
+        else:
+            print(md)
+    except (OSError, BrokenPipeError) as exc:
+        if isinstance(exc, BrokenPipeError):
+            return 0
+        print(f"breakproof: cannot write {args.markdown}: {exc}", file=sys.stderr)
+        return 2
+    if args.out_gate:
+        try:
+            _write_file(args.out_gate,
+                        json.dumps(gate, indent=2, sort_keys=True) + "\n")
+        except OSError as exc:
+            print(f"breakproof: cannot write {args.out_gate}: {exc}", file=sys.stderr)
+            return 2
+    if args.radar_markdown:
+        try:
+            _write_file(args.radar_markdown,
+                        render_radar_markdown(gate.get("diff", {}),
+                                              args.head_ref or "") + "\n")
+        except OSError as exc:
+            print(f"breakproof: cannot write {args.radar_markdown}: {exc}",
+                  file=sys.stderr)
+            return 2
+    verdict = gate.get("verdict", "pass")
+    print(f"verdict={verdict}", file=sys.stderr)
+    return 1 if verdict == "fail" else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="breakproof",
+        description="Fail the PR only when an API contract vanished. No spec needed.")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="Read a directory, print its contracts.")
+    s.add_argument("path", help="Directory to read. Only read, promise.")
+    s.add_argument("--out", default="", help="Write contract JSON here, else stdout.")
+    s.add_argument("--service", default="", help="Label every endpoint with this service.")
+    s.set_defaults(func=_cmd_scan)
+
+    d = sub.add_parser("diff", help="Base vs head. Removals fail, additions don't.")
+    d.add_argument("--base", default="", help="Base contract JSON, or nothing.")
+    d.add_argument("--head", default="", help="Head contract JSON, or nothing.")
+    d.add_argument("--base-dir", default="", help="Scan this dir as base instead.")
+    d.add_argument("--head-dir", default="", help="Scan this dir as head instead.")
+    d.add_argument("--base-ref", default="")
+    d.add_argument("--head-ref", default="")
+    d.add_argument("--out-gate", default="")
+    d.add_argument("--markdown", default="")
+    d.add_argument("--radar-markdown", default="")
+    d.set_defaults(func=_cmd_diff)
+    return p
+
+
+def main(argv=None) -> int:
+    try:
+        args = build_parser().parse_args(argv)
+        return int(args.func(args) or 0)
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

breakproof/evidence.py

@@ -0,0 +1,94 @@
+"""Finding types. Dumb data, no opinions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional
+
+
+class Verdict(str, Enum):
+    REQUIRED = "REQUIRED"
+    NECESSARY = "NECESSARY"
+    UNNECESSARY = "UNNECESSARY"
+    DEAD = "DEAD"
+    UNREACHABLE = "UNREACHABLE"
+    MISSING = "MISSING"
+    INCORRECT = "INCORRECT"
+    REDUNDANT = "REDUNDANT"
+    RISKY = "RISKY"
+    EXPENSIVE = "EXPENSIVE"
+    REGRESSION = "REGRESSION"
+    UNPROVEN = "UNPROVEN"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass
+class Evidence:
+    kind: str
+    summary: str
+    detail: Dict = field(default_factory=dict)
+
+    def as_dict(self) -> Dict:
+        return {"kind": self.kind, "summary": self.summary, "detail": self.detail}
+
+
+@dataclass
+class Finding:
+    id: str
+    title: str
+    verdict: Verdict
+    severity: str
+    location: Optional[Dict] = None
+    requirement_id: Optional[str] = None
+    claim: str = ""
+    static_evidence: List[Evidence] = field(default_factory=list)
+    runtime_evidence: List[Evidence] = field(default_factory=list)
+    counterfactual: Optional[Evidence] = None
+    confidence: float = 0.0
+
+    def add(self, ev: Evidence) -> None:
+        if ev.kind == "runtime":
+            self.runtime_evidence.append(ev)
+        elif ev.kind == "counterfactual":
+            self.counterfactual = ev
+        else:
+            self.static_evidence.append(ev)
+        self._recompute_confidence()
+
+    def _recompute_confidence(self) -> None:
+        score = 0.0
+        if self.static_evidence:
+            score += 0.4
+        if self.runtime_evidence:
+            score += 0.3
+        if self.counterfactual is not None:
+            score += 0.3
+        self.confidence = min(1.0, score)
+
+    def as_dict(self) -> Dict:
+        return {
+            "id": self.id, "title": self.title, "verdict": self.verdict.value,
+            "severity": self.severity, "location": self.location,
+            "requirement_id": self.requirement_id, "claim": self.claim,
+            "static_evidence": [e.as_dict() for e in self.static_evidence],
+            "runtime_evidence": [e.as_dict() for e in self.runtime_evidence],
+            "counterfactual": self.counterfactual.as_dict() if self.counterfactual else None,
+            "confidence": round(self.confidence, 3),
+        }
+
+
+class EvidenceEngine:
+    """Mints findings. That's it."""
+
+    def new(self, *, id: str, title: str, verdict: Verdict, severity: str,
+            location: Optional[Dict] = None, requirement_id: Optional[str] = None,
+            claim: str = "") -> Finding:
+        return Finding(id=id, title=title, verdict=verdict, severity=severity,
+                       location=location, requirement_id=requirement_id, claim=claim)
+
+    def finalize(self, f: Finding) -> Finding:
+        strong = f.verdict in (Verdict.NECESSARY, Verdict.REGRESSION)
+        if strong and f.confidence < 0.6:
+            f.verdict = Verdict.UNPROVEN
+        return f

breakproof/extract.py

@@ -0,0 +1,171 @@
+"""Find HTTP routes in a directory. Read-only; wouldn't delete your files if you paid it.
+
+Covers common Flask/FastAPI/Express/Go patterns. Anything exotic is reported
+as nothing rather than guessed at — a missed route is an honest gap, a fake
+route is a lie.
+"""
+
+from __future__ import annotations
+
+import bisect
+import os
+import re
+
+MAX_FILE_BYTES = 1_000_000
+MAX_FILES = 50_000
+MAX_ENDPOINTS = 20_000
+MAX_PATH_LEN = 2048
+
+SCAN_EXTS = (".py", ".js", ".jsx", ".ts", ".tsx", ".go")
+SKIP_DIRS = frozenset({
+    ".git", "node_modules", "dist", "build", "__pycache__",
+    ".venv", "venv", ".tox", "vendor",
+})
+
+_METHODS = ("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS")
+
+_PY_DECORATOR = re.compile(
+    r"""@(?:[\w.]+\.)?(get|post|put|delete|patch|head|options)\s*\(\s*["']([^"']+)["']""",
+    re.IGNORECASE,
+)
+_PY_ROUTE = re.compile(
+    r"""@(?:[\w.]+\.)?route\s*\(\s*["']([^"']+)["']\s*(?:,\s*methods\s*=\s*\[([^\]]{0,512})\])?""",
+    re.IGNORECASE,
+)
+_PY_METHOD = re.compile(r"""["'](\w{3,7})["']""")
+_JS_ROUTE = re.compile(
+    r"""(?:app|router|server|api)\s*\.\s*(get|post|put|delete|patch|head|options)\s*\(\s*["'`]([^"'`]+)["'`]""",
+    re.IGNORECASE,
+)
+_GO_HANDLE = re.compile(r"""HandleFunc\s*\(\s*["']([^"']+)["']""")
+_GO_GIN = re.compile(
+    r"""\.\s*(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\s*\(\s*["']([^"']+)["']""",
+)
+
+
+def _service_for(relpath: str) -> str:
+    head = (relpath or "").replace("\\", "/").split("/", 1)[0]
+    return head or "app"
+
+
+def _line_offsets(text: str) -> list:
+    offsets, total = [0], 0
+    for line in text.splitlines(keepends=True):
+        total += len(line)
+        offsets.append(total)
+    return offsets
+
+
+def _line_of(offsets: list, pos: int) -> int:
+    return bisect.bisect_right(offsets, pos)
+
+
+def _valid_route(path: str) -> bool:
+    return bool(path) and path.startswith("/") and len(path) <= MAX_PATH_LEN and " " not in path
+
+
+def extract_endpoints_from_text(text, lang: str) -> list:
+    """Pull (method, path, line) triples out of one file's text."""
+    if not isinstance(text, str) or not text or not isinstance(lang, str):
+        return []
+    offsets = _line_offsets(text)
+    found = []
+
+    def line_at(pos: int) -> int:
+        return _line_of(offsets, pos)
+
+    if lang == "py":
+        for m in _PY_DECORATOR.finditer(text):
+            if _valid_route(m.group(2)):
+                found.append((m.group(1).upper(), m.group(2), line_at(m.start())))
+        for m in _PY_ROUTE.finditer(text):
+            if not _valid_route(m.group(1)):
+                continue
+            methods = _PY_METHOD.findall(m.group(2) or "GET")
+            methods = [x.upper() for x in methods if x.upper() in _METHODS] or ["GET"]
+            for meth in methods:
+                found.append((meth, m.group(1), line_at(m.start())))
+    elif lang in ("js", "ts"):
+        for m in _JS_ROUTE.finditer(text):
+            if _valid_route(m.group(2)):
+                found.append((m.group(1).upper(), m.group(2), line_at(m.start())))
+    elif lang == "go":
+        for m in _GO_HANDLE.finditer(text):
+            if _valid_route(m.group(1)):
+                found.append(("GET", m.group(1), line_at(m.start())))
+        for m in _GO_GIN.finditer(text):
+            if _valid_route(m.group(2)):
+                found.append((m.group(1).upper(), m.group(2), line_at(m.start())))
+    return found
+
+
+def _lang_of(filename: str) -> str:
+    ext = os.path.splitext(filename.lower())[1]
+    if ext == ".py":
+        return "py"
+    if ext == ".go":
+        return "go"
+    if ext in (".js", ".jsx"):
+        return "js"
+    return "ts"
+
+
+def _iter_files(root: str) -> list:
+    """Collect candidate files. Skips symlinks — cute trick, not today."""
+    out = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames[:] = sorted(
+            d for d in dirnames
+            if d not in SKIP_DIRS and not d.startswith(".")
+            and not os.path.islink(os.path.join(dirpath, d))
+        )
+        for fn in sorted(filenames):
+            if not fn.endswith(SCAN_EXTS):
+                continue
+            full = os.path.join(dirpath, fn)
+            if os.path.islink(full):
+                continue
+            out.append(full)
+            if len(out) >= MAX_FILES:
+                return out
+    return out
+
+
+def scan_path(root: str, service: str = "") -> dict:
+    """Scan a directory into a contract. Never writes, never deletes, never executes."""
+    if not isinstance(root, str) or not root:
+        raise ValueError("scan root must be a non-empty path")
+    if not os.path.isdir(root):
+        raise ValueError(f"not a directory: {root}")
+    endpoints, seen = [], set()
+    for path in _iter_files(root):
+        try:
+            if os.path.getsize(path) > MAX_FILE_BYTES:
+                continue
+        except OSError:
+            continue
+        try:
+            with open(path, "r", encoding="utf-8", errors="ignore") as fh:
+                text = fh.read()
+        except (OSError, ValueError):
+            continue
+        try:
+            rel = os.path.relpath(path, root).replace("\\", "/")
+        except ValueError:
+            continue
+        if rel.startswith(".."):
+            continue
+        svc = service or _service_for(rel)
+        for method, route, line in extract_endpoints_from_text(text, _lang_of(path)):
+            key = (method, route, rel, line)
+            if key in seen:
+                continue
+            seen.add(key)
+            endpoints.append({"method": method, "path": route, "protocol": "http",
+                              "service": svc, "handler": "", "file": rel, "line": line})
+            if len(endpoints) >= MAX_ENDPOINTS:
+                break
+        if len(endpoints) >= MAX_ENDPOINTS:
+            break
+    endpoints.sort(key=lambda e: (e["method"], e["path"], e["file"], str(e["line"])))
+    return {"endpoints": endpoints, "edges": []}

breakproof/prgate.py

@@ -0,0 +1,90 @@
+"""Gate a PR: fail on removals, new CVEs, new secrets. Everything else passes.
+
+Additions never fail. Yes, really.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from breakproof.radar import build_api_diff
+
+
+def affected_cves(statements) -> set:
+    return {str(s.get("cve") or "").upper()
+            for s in (statements or []) if isinstance(s, dict)
+            and (s.get("state") or "") == "affected" and s.get("cve")}
+
+
+def secret_sites(compliance_controls) -> set:
+    out = set()
+    for c in compliance_controls or []:
+        if not isinstance(c, dict) or c.get("status") != "fail":
+            continue
+        if c.get("id") not in ("C-SECRETS", "C-CFG-SECRETS"):
+            continue
+        for e in c.get("evidence") or []:
+            if isinstance(e, dict) and e.get("file"):
+                out.add((str(e.get("file")), str(e.get("line", ""))))
+    return out
+
+
+def build_gate(base_contract=None, head_contract=None, base_affected=None,
+               head_affected=None, base_secrets=None, head_secrets=None,
+               base_ref: str = "", head_ref: str = "") -> Dict:
+    """PR verdict from frozen contracts + advisory/secret sets. Deterministic."""
+    diff = build_api_diff(
+        base_contract if isinstance(base_contract, dict) else {},
+        head_contract if isinstance(head_contract, dict) else {})
+    new_cves = sorted(set(head_affected or ()) - set(base_affected or ()))
+    new_secrets = sorted(set(head_secrets or ()) - set(base_secrets or ()))
+    breaking = (diff.get("summary") or {}).get("breaking", 0)
+    failed = bool(breaking or new_cves or new_secrets)
+    return {
+        "verdict": "fail" if failed else "pass",
+        "base_ref": base_ref or "",
+        "head_ref": head_ref or "",
+        "diff": diff,
+        "new_cves": [{"cve": c} for c in new_cves],
+        "new_secrets": [{"file": f, "line": ln} for f, ln in new_secrets],
+        "summary": {"breaking": breaking,
+                    "removed": (diff.get("summary") or {}).get("removed", 0),
+                    "new_cves": len(new_cves),
+                    "new_secrets": len(new_secrets)},
+    }
+
+
+def render_gate_markdown(gate: Dict | None) -> str:
+    """CI-readable verdict rendering."""
+    g = gate if isinstance(gate, dict) else {}
+    s = g.get("summary", {}) or {}
+    verdict = str(g.get("verdict", "pass")).upper()
+    lines = [
+        f"# PR Merge Gate: {verdict}",
+        "",
+        f"Base: `{g.get('base_ref', '')}` → Head: `{g.get('head_ref', '')}`",
+        f"Breaking contracts: {s.get('breaking', 0)} · "
+        f"New CVEs: {s.get('new_cves', 0)} · "
+        f"New secret sites: {s.get('new_secrets', 0)}",
+        "",
+        "## Removed contracts (breaking)",
+    ]
+    for rec in (g.get("diff") or {}).get("removed", []) or []:
+        callers = ", ".join(c.get("service", "") for c in rec.get("callers", [])[:6])
+        lines.append(f"- **{rec.get('method')} {rec.get('path')}** "
+                     f"(was: {rec.get('service', '?')}; callers: {callers or 'none observed'})")
+    if not ((g.get("diff") or {}).get("removed", []) or []):
+        lines.append("- None.")
+    lines.append("")
+    lines.append("## New reachable CVEs")
+    for item in g.get("new_cves", []) or []:
+        lines.append(f"- {item.get('cve')}")
+    if not (g.get("new_cves", []) or []):
+        lines.append("- None.")
+    lines.append("")
+    lines.append("## New secret sites")
+    for item in g.get("new_secrets", []) or []:
+        lines.append(f"- {item.get('file')}:{item.get('line')}")
+    if not (g.get("new_secrets", []) or []):
+        lines.append("- None.")
+    return "\n".join(lines)

breakproof/radar.py

@@ -0,0 +1,223 @@
+"""Diff two frozen endpoint contracts. Removed routes break; added ones don't.
+
+That's the whole philosophy. Everything else is bookkeeping.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from breakproof.evidence import Evidence, EvidenceEngine, Finding, Verdict
+
+# "X consumes Y's API" edges. Deploy wiring and imports don't count —
+# refactors aren't breakages, no matter how scary the diff looks.
+CALLER_KINDS = ("calls", "publish", "subscribe", "event")
+
+MAX_BREAK_FINDINGS = 25
+MAX_WATCH_ROWS = 50
+
+
+def normalize_path(path: str) -> str:
+    path = (path or "").strip() or "/"
+    if not path.startswith("/"):
+        path = "/" + path
+    if len(path) > 1:
+        path = path.rstrip("/")
+    return path
+
+
+def break_key(method: str, path: str) -> str:
+    """Stable cross-scan identity for one contract (also the finding id)."""
+    return f"API-{(method or 'GET').upper()}-{normalize_path(path)}"
+
+
+def normalize_endpoints(endpoints) -> Dict[str, Dict]:
+    """Index endpoint records by contract identity (deterministic)."""
+    out: Dict[str, Dict] = {}
+    for ep in endpoints or []:
+        if not isinstance(ep, dict):
+            continue
+        method = str(ep.get("method", "GET") or "GET").upper()
+        proto = str(ep.get("protocol", "http") or "http").lower()
+        path = normalize_path(ep.get("path", ""))
+        key = break_key(method, path)
+        if key not in out:
+            out[key] = {"key": key, "protocol": proto, "method": method,
+                        "path": path,
+                        "service": str(ep.get("service", "") or ""),
+                        "handler": str(ep.get("handler", "") or ""),
+                        "file": str(ep.get("file", "") or ""),
+                        "line": ep.get("line", "") or ""}
+    return out
+
+
+def api_contract(svc_summary) -> Dict:
+    """Trimmed contract snapshot (endpoints + call edges)."""
+    summary = svc_summary if isinstance(svc_summary, dict) else {}
+    indexed = normalize_endpoints(summary.get("endpoints"))
+    endpoints = [indexed[key] for key in sorted(indexed)]
+    edges = []
+    for e in summary.get("edges", []) or []:
+        if not isinstance(e, dict):
+            continue
+        edges.append({"src": str(e.get("src") or e.get("from") or ""),
+                      "dst": str(e.get("dst") or e.get("to") or ""),
+                      "kind": str(e.get("kind") or e.get("type") or ""),
+                      "file": str(e.get("file", "") or ""),
+                      "line": e.get("line", "") or ""})
+    return {"endpoints": endpoints, "edges": edges}
+
+
+def _callers(prev_edges, owner: str) -> List[Dict]:
+    if not owner:
+        return []
+    out = []
+    for e in prev_edges or []:
+        if e.get("kind") not in CALLER_KINDS or e.get("dst") != owner:
+            continue
+        out.append({"service": e.get("src", ""),
+                    "file": e.get("file", ""), "line": e.get("line", ""),
+                    "via": e.get("kind", "calls")})
+    out.sort(key=lambda c: (c["service"], str(c["file"]), str(c["line"])))
+    return out
+
+
+def build_api_diff(prev_contract=None, curr_contract=None) -> Dict:
+    """Diff two frozen contracts. Pure, deterministic, sorted."""
+    prev = prev_contract if isinstance(prev_contract, dict) else {}
+    curr = curr_contract if isinstance(curr_contract, dict) else {}
+    prev_eps = normalize_endpoints(prev.get("endpoints"))
+    curr_eps = normalize_endpoints(curr.get("endpoints"))
+    prev_edges = [e for e in (prev.get("edges") or []) if isinstance(e, dict)]
+    curr_triples = {(e.get("src"), e.get("dst"), e.get("kind"))
+                    for e in (curr.get("edges") or []) if isinstance(e, dict)}
+
+    removed, added = [], []
+    for key in sorted(set(prev_eps) - set(curr_eps)):
+        rec = dict(prev_eps[key])
+        rec["callers"] = _callers(prev_edges, rec["service"])
+        removed.append(rec)
+    for key in sorted(set(curr_eps) - set(prev_eps)):
+        added.append(dict(curr_eps[key]))
+
+    changed = []
+    for proto, path in sorted({(r["protocol"], r["path"]) for r in
+                               list(prev_eps.values()) + list(curr_eps.values())}):
+        before = sorted(v["method"] for v in prev_eps.values()
+                        if v["protocol"] == proto and v["path"] == path)
+        after = sorted(v["method"] for v in curr_eps.values()
+                       if v["protocol"] == proto and v["path"] == path)
+        dropped = [m for m in before if m not in after]
+        gained = [m for m in after if m not in before]
+        if dropped or gained:
+            still = [m for m in before if m in after]
+            if still:
+                owner = next((v["service"] for v in curr_eps.values()
+                              if v["protocol"] == proto and v["path"] == path), "")
+                changed.append({"protocol": proto, "path": path,
+                                "removed_methods": dropped,
+                                "added_methods": gained,
+                                "breaking": bool(dropped),
+                                "service": owner,
+                                "callers": _callers(prev_edges, owner)})
+
+    watch = []
+    for e in prev_edges:
+        if e.get("kind") not in CALLER_KINDS:
+            continue
+        if (e.get("src"), e.get("dst"), e.get("kind")) not in curr_triples:
+            watch.append({"src": e.get("src", ""), "dst": e.get("dst", ""),
+                          "kind": e.get("kind", ""), "file": e.get("file", ""),
+                          "line": e.get("line", "")})
+    watch.sort(key=lambda w: (w["src"], w["dst"], w["kind"]))
+    watch = watch[:MAX_WATCH_ROWS]
+
+    return {"removed": removed, "added": added, "changed": changed,
+            "watch": watch,
+            "summary": {"removed": len(removed), "added": len(added),
+                        "changed": len(changed), "watch": len(watch),
+                        "breaking": len(removed)}}
+
+
+def api_break_findings(diff: Dict | None, prev_job_id: str,
+                       ev: EvidenceEngine) -> List[Finding]:
+    """One RISKY/high finding per removed endpoint (never double-filed)."""
+    diff = diff if isinstance(diff, dict) else {}
+    prev_job = (prev_job_id or "")[:12]
+    targets = []
+    for rec in diff.get("removed", []) or []:
+        if isinstance(rec, dict):
+            targets.append((rec.get("key") or break_key(rec.get("method"), rec.get("path")),
+                            rec))
+    targets.sort(key=lambda t: t[0])
+    findings: List[Finding] = []
+    for key, rec in targets[:MAX_BREAK_FINDINGS]:
+        callers = rec.get("callers") or []
+        first = next((c for c in callers if c.get("file")), None)
+        location = ({"file": first["file"], "line": first.get("line") or 0,
+                     "col": 0, "end_line": 0, "end_col": 0}
+                    if first else {})
+        caller_note = (f"Affected callers: "
+                       + ", ".join(f"{c['service']} ({c.get('file', '?')}"
+                                   f"{':' + str(c['line']) if c.get('line') else ''})"
+                                   for c in callers[:8]) if callers
+                       else "No in-repo callers observed — external consumers may still break.")
+        f = ev.new(
+            id=key,
+            title=f"Breaking API change: {rec.get('method')} {rec.get('path')} vanished",
+            verdict=Verdict.RISKY, severity="high", location=location,
+            claim=(f"Contract {rec.get('method')} {rec.get('path')} served by "
+                   f"'{rec.get('service') or 'unknown service'}' in scan {prev_job} "
+                   f"is gone. {caller_note}"))
+        f.add(Evidence("static", "Route present in previous frozen scan, absent now.",
+                       {"contract": key, "previous_job": prev_job_id,
+                        "owner": rec.get("service", ""),
+                        "callers": callers[:20]}))
+        f.add(Evidence("counterfactual", "Restore the route or migrate every caller, then re-scan.",
+                       {"fix": f"restore {rec.get('method')} {rec.get('path')}"}))
+        findings.append(ev.finalize(f))
+    return findings
+
+
+def render_radar_markdown(diff: Dict | None, job_id: str = "") -> str:
+    """Shareable contract-diff rendering (findings only for breakage)."""
+    d = diff if isinstance(diff, dict) else {}
+    s = d.get("summary", {}) or {}
+    lines = [
+        "# API Change Radar",
+        "",
+        f"Scan: `{(job_id or '')[:12]}` — breaking changes: {s.get('breaking', 0)} "
+        f"(removed {s.get('removed', 0)}, method-breaks "
+        f"{sum(1 for c in d.get('changed', []) or [] if c.get('breaking'))}, "
+        f"added {s.get('added', 0)})",
+        "",
+        "## Removed contracts (breaking)",
+    ]
+    for rec in d.get("removed", []) or []:
+        callers = ", ".join(c["service"] for c in rec.get("callers", [])[:6]) or "none observed"
+        lines.append(f"- **{rec.get('method')} {rec.get('path')}** "
+                     f"(was: {rec.get('service', '?')}; callers: {callers})")
+    if not (d.get("removed", []) or []):
+        lines.append("- None.")
+    lines.append("")
+    lines.append("## Changed method-sets")
+    for ch in d.get("changed", []) or []:
+        mark = "BREAKING" if ch.get("breaking") else "compatible"
+        lines.append(f"- {ch.get('path')} [{mark}]: "
+                     f"dropped {', '.join(ch.get('removed_methods', [])) or '—'}; "
+                     f"gained {', '.join(ch.get('added_methods', [])) or '—'}")
+    if not (d.get("changed", []) or []):
+        lines.append("- None.")
+    lines.append("")
+    lines.append("## Added contracts (informational)")
+    for rec in (d.get("added", []) or [])[:20]:
+        lines.append(f"- {rec.get('method')} {rec.get('path')} ({rec.get('service', '?')})")
+    if not (d.get("added", []) or []):
+        lines.append("- None.")
+    lines.append("")
+    lines.append("## Watch: vanished consumption (informational, not flagged)")
+    for w in (d.get("watch", []) or [])[:20]:
+        lines.append(f"- {w.get('src')} no longer {w.get('kind')} {w.get('dst')}")
+    if not (d.get("watch", []) or []):
+        lines.append("- None.")
+    return "\n".join(lines)

breakproof-0.1.1.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: breakproof
+Version: 0.1.1
+Summary: No-spec API break gate: FAIL only on removed contracts with caller proof
+Author-email: AuditScan <team@auditscan.sh>
+License-Expression: MIT
+Project-URL: Homepage, https://auditscan.sh
+Project-URL: Repository, https://github.com/auditscan-sh/breakproof
+Project-URL: Issues, https://github.com/auditscan-sh/breakproof/issues
+Keywords: api,breaking-changes,contract-testing,ci,merge-gate
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Dynamic: license-file
+
+# Breakproof — merge without fear.
+
+Your PR deleted an endpoint someone still calls. Breakproof tells you before your users do. No OpenAPI spec, no config novel, no noise. Removed contracts fail. Everything else passes.
+
+```bash
+pipx install breakproof
+breakproof scan ./app --out base.json
+breakproof diff --base base.json --head-dir ./pr-branch
+# verdict=fail, exit 1, and a Markdown receipt of exactly what vanished
+```
+
+## Install
+
+```bash
+pipx install breakproof   # CLI, isolated. The good default.
+pip install breakproof    # library + CLI in your venv.
+uvx breakproof --help     # no install at all, just vibes.
+```
+
+Python 3.10+. Zero dependencies. No network, no telemetry, no account. It works on a plane.
+
+## CLI
+
+```bash
+# Freeze a directory into a contract
+breakproof scan ./app --out contract.json
+breakproof scan ./app --service payments --out contract.json
+
+# Diff two frozen contracts
+breakproof diff --base base.json --head head.json
+
+# Diff two directories directly (the 10-second demo)
+breakproof diff --base-dir ./main --head-dir ./pr
+
+# Save the receipts instead of printing them
+breakproof diff --base base.json --head head.json \
+  --out-gate gate.json --markdown gate.md --radar-markdown radar.md
+```
+
+Exit codes: `0` pass, `1` fail (something vanished), `2` you invoked it wrong.
+
+Contract JSON looks like this. You can hand-write it, generate it, or freeze it in CI — Breakproof doesn't care where it came from:
+
+```json
+{
+  "endpoints": [
+    {"method": "GET", "path": "/users", "protocol": "http",
+     "service": "api", "handler": "", "file": "app.py", "line": 12}
+  ],
+  "edges": []
+}
+```
+
+## Library (yes, it's importable)
+
+Same gate your CI runs, inside your own Python:
+
+```python
+from breakproof.extract import scan_path
+from breakproof.prgate import build_gate, render_gate_markdown
+
+base = scan_path("./main")
+head = scan_path("./pr")
+gate = build_gate(base, head, base_ref="main", head_ref="pr")
+
+print(gate["verdict"])  # "pass" | "fail"
+print(render_gate_markdown(gate))  # paste it into a PR comment
+```
+
+Lower level, if you already have contracts:
+
+```python
+from breakproof.radar import build_api_diff
+
+diff = build_api_diff(base, head)
+print(diff["summary"])  # {"removed": 1, "added": 0, ..., "breaking": 1}
+```
+
+## CI
+
+```yaml
+- uses: auditscan-sh/breakproof@v1
+  with:
+    base-dir: ./base
+    head-dir: .
+```
+
+Posts the verdict to the run summary. Set `fail-on-breaking: "false"` for advisory mode (comments, never red).
+
+## Why not a spec diff?
+
+Spec tools need an `openapi.yaml` you have to write and keep honest, then flag everything including stuff nobody calls. Breakproof reads your code, freezes what it serves, and fails only on removals — plus new CVEs or secret sites if you hand it those lists as JSON. Nothing to maintain, nothing to triage, nothing to argue about in review.
+
+## Honest limits
+
+v0.1 recognizes common Flask, FastAPI, Express, Fiber, Go `net/http`, and Gin route patterns. Anything exotic reports zero endpoints instead of inventing some — run `breakproof scan` and eyeball the count before you gate on it. Standalone caller lists read `none observed`; pair it with a scanner that knows your consumers to name names.
+
+## Safety
+
+Read-only by design. It never deletes, moves, edits, or executes your code — it reads the directories you point it at and writes exactly the files you name with `--out` / `--markdown`. Symlinks skipped, files over 1 MB skipped, scans cap at 50k files / 20k endpoints.
+
+## License
+
+MIT. Break things responsibly.
+
+Built by [AuditScan](https://auditscan.sh).

breakproof-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+breakproof/__init__.py,sha256=spb2RNi-CVmM4d_eFz_zF2AQESjqd83ZhUMORlZ9WJo,93
+breakproof/cli.py,sha256=tpJkrHDSeVFpex-G4nYrPj4VmrN1OMCb6ZT9dlS0s7M,5988
+breakproof/evidence.py,sha256=uFHDi093nfP1t0bwQN9MRChbPedPnVfltFc4zcXsmZQ,2986
+breakproof/extract.py,sha256=ciZLr89ufnwCljHidLOiZCaFPu9SDNxtQTTcQ5XaeeA,5905
+breakproof/prgate.py,sha256=FVKd1jRQyCv11gJfPhYWDuH89ITAzzpk58BeUycE4Kw,3641
+breakproof/radar.py,sha256=v2IBqQwy7PIo_Vp7ZHsFCpYppAxWQfZfTr8E098pzRg,10217
+breakproof-0.1.1.dist-info/licenses/LICENSE,sha256=r0pBrXvK5C-IVj5haUtL2SbIycn4SwPT-1128FOB0cw,1066
+breakproof-0.1.1.dist-info/METADATA,sha256=1uI8b5QzkVpYUhdXBl4EyFrMVz4OQjtQvAa0mav0cQ8,4489
+breakproof-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+breakproof-0.1.1.dist-info/entry_points.txt,sha256=GKA5t3_Vxf-yMX61Q0SVNDnVCmhiXKRiP0cHrd80iXo,51
+breakproof-0.1.1.dist-info/top_level.txt,sha256=ggAr7geCjJNnmc30ixrjFpoVUsHSyLj8mam-Lh6192Q,11
+breakproof-0.1.1.dist-info/RECORD,,

breakproof-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

breakproof-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+breakproof = breakproof.cli:main

breakproof-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AuditScan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breakproof-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+breakproof