pr-verify 0.1.0__tar.gz

pr_verify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calas Automations Inc.
+
+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.

pr_verify-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: pr-verify
+Version: 0.1.0
+Summary: Deterministic trust scoring for agent-authored PRs.
+Author: Calas Automations Inc.
+License: MIT
+Project-URL: Homepage, https://github.com/calasdan-sketch/pr-verify
+Project-URL: Issues, https://github.com/calasdan-sketch/pr-verify/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PR Verify
+
+Deterministic trust for agent-authored PRs. Not another AI reviewer —
+**verification, not opinion.** Agents now write more code than seniors can
+review; this tells a senior exactly how deep to review, from observable
+facts: which lines an agent wrote, what could break, and whether policy
+gates pass.
+
+## Install
+
+```bash
+git clone <repo> && cd pr-verify
+pip install .   # provides the `pr-verify` console script
+```
+
+Or run without installing: `python3 -m pr_verify` from the repo root.
+
+## Quick start
+
+```bash
+cd your-repo
+python3 -m pr_verify init        # write an example .pr-verify.yaml
+python3 -m pr_verify check --base main
+```
+
+## What it reports
+
+**Provenance** — every added line labeled agent/human via `git blame` +
+commit-author analysis (configurable markers: claude, codex, cursor,
+copilot, bot…). Per file: `agent` / `mixed` / `human`, with the detected
+agent identities.
+
+**Blast radius** — reverse dependency graph: for each changed file, the
+transitive set of in-repo dependents that could break. Python via AST;
+JS/TS/Go/Rust/Java/Ruby/PHP via heuristic fallback.
+
+**Policy gates** — commands from `.pr-verify.yaml` (tests, typecheck,
+lint), run with timeout, pass/fail captured. The config is read from the
+base ref (never the worktree under review) and gates run **without** a
+shell — `;`, `&&`, `$()`, pipes and the rest are literal arguments, never
+interpreted. A failing gate fails the verification (nonzero exit).
+
+**Risk score** — deterministic 0–100 from six public factors:
+
+| Factor | Max | What it measures |
+|---|---|---|
+| agent_share | 40 | % of added lines agent-authored |
+| blast | 25 | log-scaled transitive dependents |
+| sensitive | 20 | changed files under sensitive globs (auth, crypto, payments, migrations…); deleted files match like touched ones |
+| gates | 10 | any policy gate failed |
+| no_tests | 5 | source changed with no test changes |
+| deletion | 50 | agent-attributed deletions: 45 if any deleted file is sensitive, else 10 for deleting tracked files at all, plus log-scaled points for the deleted files' dependents — pure-deletion PRs can trip the threshold too |
+
+Bands: 0–29 low · 30–69 medium · 70–100 high. The formula is documented so
+teams can argue with it and tune it — a black-box score is just another
+opinion.
+
+## CI
+
+```bash
+python3 -m pr_verify check --base origin/main --format json --fail-on high
+```
+
+`--fail-on high` (default) exits 1 when score ≥ `risk_threshold` (70).
+`--fail-on any-risk` / `--fail-on never` available. A GitHub Action is
+included at `.github/workflows/pr-verify.yml`.
+
+## Example output
+
+```
+════════════════════════════════════════════════════════
+  PR VERIFY  risk 57/100 (MEDIUM)
+════════════════════════════════════════════════════════
+
+  provenance: 9/13 added lines agent-authored
+    agent   app/auth.py (4/4 agent) [claude-bot]
+    mixed   app/core.py (4/8 agent) [claude-bot]
+    agent   app/views.py (1/1 agent) [claude-bot]
+
+  blast radius:
+    app/core.py: 1 downstream dependent(s)
+      direct: app/views.py
+
+  risk factors:
+     28 pts  agent_share  9/13 added lines agent-authored (69%)
+      4 pts  blast        largest blast radius: 1 downstream dependent(s)
+     20 pts  sensitive    sensitive files touched: app/auth.py
+      0 pts  gates        no gates configured
+      5 pts  no_tests     source changed with no test changes
+
+  ✓ score 57 < threshold 70
+════════════════════════════════════════════════════════
+```
+
+## Honest limits
+
+- Provenance depends on commit authorship — squashed or rebased PRs lose
+  per-commit attribution (tune `agent_markers` for your workflow).
+  Uncommitted working-tree changes are included in `check`, but with no
+  commit to blame they are counted as human-written, never agent-written.
+- Non-Python blast-radius extraction is heuristic.
+- The risk formula is a starting point, not a verdict — tune the threshold
+  per team.
+
+## Tests
+
+55/55 pass: `python3 -m unittest discover -s tests`

pr_verify-0.1.0/README.md

@@ -0,0 +1,107 @@
+# PR Verify
+
+Deterministic trust for agent-authored PRs. Not another AI reviewer —
+**verification, not opinion.** Agents now write more code than seniors can
+review; this tells a senior exactly how deep to review, from observable
+facts: which lines an agent wrote, what could break, and whether policy
+gates pass.
+
+## Install
+
+```bash
+git clone <repo> && cd pr-verify
+pip install .   # provides the `pr-verify` console script
+```
+
+Or run without installing: `python3 -m pr_verify` from the repo root.
+
+## Quick start
+
+```bash
+cd your-repo
+python3 -m pr_verify init        # write an example .pr-verify.yaml
+python3 -m pr_verify check --base main
+```
+
+## What it reports
+
+**Provenance** — every added line labeled agent/human via `git blame` +
+commit-author analysis (configurable markers: claude, codex, cursor,
+copilot, bot…). Per file: `agent` / `mixed` / `human`, with the detected
+agent identities.
+
+**Blast radius** — reverse dependency graph: for each changed file, the
+transitive set of in-repo dependents that could break. Python via AST;
+JS/TS/Go/Rust/Java/Ruby/PHP via heuristic fallback.
+
+**Policy gates** — commands from `.pr-verify.yaml` (tests, typecheck,
+lint), run with timeout, pass/fail captured. The config is read from the
+base ref (never the worktree under review) and gates run **without** a
+shell — `;`, `&&`, `$()`, pipes and the rest are literal arguments, never
+interpreted. A failing gate fails the verification (nonzero exit).
+
+**Risk score** — deterministic 0–100 from six public factors:
+
+| Factor | Max | What it measures |
+|---|---|---|
+| agent_share | 40 | % of added lines agent-authored |
+| blast | 25 | log-scaled transitive dependents |
+| sensitive | 20 | changed files under sensitive globs (auth, crypto, payments, migrations…); deleted files match like touched ones |
+| gates | 10 | any policy gate failed |
+| no_tests | 5 | source changed with no test changes |
+| deletion | 50 | agent-attributed deletions: 45 if any deleted file is sensitive, else 10 for deleting tracked files at all, plus log-scaled points for the deleted files' dependents — pure-deletion PRs can trip the threshold too |
+
+Bands: 0–29 low · 30–69 medium · 70–100 high. The formula is documented so
+teams can argue with it and tune it — a black-box score is just another
+opinion.
+
+## CI
+
+```bash
+python3 -m pr_verify check --base origin/main --format json --fail-on high
+```
+
+`--fail-on high` (default) exits 1 when score ≥ `risk_threshold` (70).
+`--fail-on any-risk` / `--fail-on never` available. A GitHub Action is
+included at `.github/workflows/pr-verify.yml`.
+
+## Example output
+
+```
+════════════════════════════════════════════════════════
+  PR VERIFY  risk 57/100 (MEDIUM)
+════════════════════════════════════════════════════════
+
+  provenance: 9/13 added lines agent-authored
+    agent   app/auth.py (4/4 agent) [claude-bot]
+    mixed   app/core.py (4/8 agent) [claude-bot]
+    agent   app/views.py (1/1 agent) [claude-bot]
+
+  blast radius:
+    app/core.py: 1 downstream dependent(s)
+      direct: app/views.py
+
+  risk factors:
+     28 pts  agent_share  9/13 added lines agent-authored (69%)
+      4 pts  blast        largest blast radius: 1 downstream dependent(s)
+     20 pts  sensitive    sensitive files touched: app/auth.py
+      0 pts  gates        no gates configured
+      5 pts  no_tests     source changed with no test changes
+
+  ✓ score 57 < threshold 70
+════════════════════════════════════════════════════════
+```
+
+## Honest limits
+
+- Provenance depends on commit authorship — squashed or rebased PRs lose
+  per-commit attribution (tune `agent_markers` for your workflow).
+  Uncommitted working-tree changes are included in `check`, but with no
+  commit to blame they are counted as human-written, never agent-written.
+- Non-Python blast-radius extraction is heuristic.
+- The risk formula is a starting point, not a verdict — tune the threshold
+  per team.
+
+## Tests
+
+55/55 pass: `python3 -m unittest discover -s tests`

pr_verify-0.1.0/pr_verify/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pr_verify-0.1.0/pr_verify/blastradius.py

@@ -0,0 +1,179 @@
+"""Blast radius: who depends on the changed files?
+
+Builds a module import graph for the repo (Python via AST, other languages
+via heuristic regex), inverts it, and for each changed file reports the
+transitive set of dependents — the code that could break if the change is
+wrong. Standalone: no dependency on sibling packages.
+"""
+
+from __future__ import annotations
+
+import ast
+import dataclasses
+import os
+import re
+
+PY_EXTS = {".py"}
+OTHER_EXTS = {".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+              ".go", ".rs", ".java", ".rb", ".php"}
+
+_GENERIC_IMPORT_RES = [
+    re.compile(r'^\s*import\s+(?:type\s+)?[{*]?[^"\']*?from\s+["\']([^"\']+)["\']'),
+    re.compile(r'^\s*import\s+["\']([^"\']+)["\']'),
+    re.compile(r'require\(\s*["\']([^"\']+)["\']\s*\)'),
+    re.compile(r'^\s*use\s+([a-zA-Z0-9_:]+)(?:::|\s*[{;])'),
+]
+
+
+def _imports_of(path: str, content: str) -> list[str]:
+    ext = os.path.splitext(path)[1].lower()
+    if ext in PY_EXTS:
+        try:
+            tree = ast.parse(content)
+        except SyntaxError:
+            return []
+        mods = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                mods.extend(a.name for a in node.names)
+            elif isinstance(node, ast.ImportFrom):
+                if node.level:
+                    mods.append("<local>")
+                elif node.module:
+                    mods.append(node.module)
+        return mods
+    if ext in OTHER_EXTS:
+        mods = []
+        for line in content.splitlines():
+            for rx in _GENERIC_IMPORT_RES:
+                m = rx.search(line)
+                if m:
+                    mods.append(m.group(1))
+                    break
+        return mods
+    return []
+
+
+def _module_candidates(rel: str) -> list[str]:
+    """Dotted forms a file might be imported as: a/b.py -> a.b, b."""
+    base = rel.replace(os.sep, "/")
+    if base.endswith("/__init__.py"):
+        dotted = base[: -len("/__init__.py")].replace("/", ".")
+    elif base.endswith(".py"):
+        dotted = base[: -len(".py")].replace("/", ".")
+    else:
+        stem = base.rsplit(".", 1)[0].replace("/", ".")
+        return [stem, stem.split(".")[-1]]
+    parts = dotted.split(".")
+    return [dotted, parts[-1]] if len(parts) > 1 else [dotted]
+
+
+@dataclasses.dataclass
+class BlastRadius:
+    file: str
+    direct: list[str]          # files directly importing it
+    transitive: list[str]      # all downstream dependents
+    external_only: bool = False  # changed file imported by nothing in-repo
+
+    @property
+    def size(self) -> int:
+        return len(self.transitive)
+
+
+def _iter_files(root: str) -> list[str]:
+    skip = {".git", "node_modules", "__pycache__", ".venv", "venv",
+            "dist", "build", ".tox", "vendor"}
+    out = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in skip]
+        for fn in filenames:
+            if os.path.splitext(fn)[1].lower() in (PY_EXTS | OTHER_EXTS):
+                out.append(os.path.join(dirpath, fn))
+    return sorted(out)
+
+
+def build_graph(root: str) -> dict[str, set[str]]:
+    """rel path -> set of rel paths it imports (in-repo only)."""
+    files = _iter_files(root)
+    rels = [os.path.relpath(p, root).replace(os.sep, "/") for p in files]
+    # index: dotted name -> rel
+    index: dict[str, str] = {}
+    for rel in rels:
+        for cand in _module_candidates(rel):
+            index.setdefault(cand, rel)
+    graph: dict[str, set[str]] = {rel: set() for rel in rels}
+    for path, rel in zip(files, rels):
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        except OSError:
+            continue
+        for mod in _imports_of(path, content):
+            target = index.get(mod)
+            if target and target != rel:
+                graph[rel].add(target)
+    return graph
+
+
+def dependents_of_modules(root: str, module_names: set[str]) -> list[str]:
+    """rel paths in the current worktree importing any of module_names.
+
+    Used for changed files absent from the worktree (e.g. deleted files):
+    the normal graph can't resolve them, so match the raw imported module
+    strings instead. Over-approximates on bare-name matches (e.g. "core");
+    for a trust tool, flagging a possibly-broken dependent beats silence.
+    """
+    if not module_names:
+        return []
+    out = []
+    for path in _iter_files(root):
+        rel = os.path.relpath(path, root).replace(os.sep, "/")
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        except OSError:
+            continue
+        if set(_imports_of(path, content)) & module_names:
+            out.append(rel)
+    return sorted(out)
+
+
+def _transitive_dependents(reverse: dict[str, set[str]],
+                           direct: list[str], rel: str) -> list[str]:
+    seen = set(direct)
+    stack = list(direct)
+    while stack:
+        cur = stack.pop()
+        for nxt in reverse.get(cur, ()):
+            if nxt not in seen:
+                seen.add(nxt)
+                stack.append(nxt)
+    seen.discard(rel)
+    return sorted(seen)
+
+
+def analyze(root: str, changed: list[str]) -> dict[str, BlastRadius]:
+    graph = build_graph(root)
+    # invert
+    reverse: dict[str, set[str]] = {rel: set() for rel in graph}
+    for src, deps in graph.items():
+        for dep in deps:
+            reverse[dep].add(src)
+    result: dict[str, BlastRadius] = {}
+    for rel in changed:
+        if rel in reverse:
+            direct = sorted(reverse[rel])
+            transitive = _transitive_dependents(reverse, direct, rel)
+            result[rel] = BlastRadius(file=rel, direct=direct,
+                                      transitive=transitive)
+            continue
+        # Not in the worktree graph (deleted or unknown file): fall back
+        # to matching the file's module names against the raw imports of
+        # every file still in the worktree, so deleted imports still show
+        # their (now broken) dependents.
+        direct = dependents_of_modules(root, set(_module_candidates(rel)))
+        transitive = _transitive_dependents(reverse, direct, rel)
+        result[rel] = BlastRadius(file=rel, direct=direct,
+                                  transitive=transitive,
+                                  external_only=not direct)
+    return result

pr_verify-0.1.0/pr_verify/cli.py

@@ -0,0 +1,178 @@
+"""PR Verify: deterministic trust for agent-authored PRs.
+
+Not another AI reviewer — verification, not opinion. For a diff range it
+reports: which lines an agent wrote (provenance), what could break
+(blast radius), whether policy gates pass, and a deterministic risk score
+that tells a senior how deep to review.
+
+  pr-verify check --base main
+  pr-verify check --base origin/main --format json --fail-on high
+  pr-verify init   # write an example .pr-verify.yaml
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+from . import blastradius as br_mod
+from . import config as config_mod
+from . import gates as gates_mod
+from . import provenance as prov_mod
+from . import risk as risk_mod
+
+VERSION = "0.1.0"
+
+
+def _ensure_repo(root: str) -> None:
+    p = subprocess.run(["git", "-C", root, "rev-parse", "--git-dir"],
+                       capture_output=True, timeout=15)
+    if p.returncode != 0:
+        print("error: not a git repo", file=sys.stderr)
+        sys.exit(2)
+
+
+def cmd_init(args) -> int:
+    path = os.path.join(args.root, config_mod.CONFIG_FILE)
+    if os.path.exists(path) and not args.force:
+        print(f"{config_mod.CONFIG_FILE} exists (use --force).")
+        return 2
+    with open(path, "w") as f:
+        f.write(config_mod.example_config())
+    print(f"wrote {config_mod.CONFIG_FILE} — tune markers, paths, gates.")
+    return 0
+
+
+def _report_human(prov, blast, gate_results, breakdown, threshold) -> None:
+    total_added = sum(f.added for f in prov.values())
+    agent_added = sum(f.agent_added for f in prov.values())
+    print("═" * 56)
+    print(f"  PR VERIFY  risk {breakdown.score}/100 "
+          f"({breakdown.band.upper()})")
+    print("═" * 56)
+    print(f"\n  provenance: {agent_added}/{total_added} added lines "
+          f"agent-authored")
+    for rel in sorted(prov):
+        f = prov[rel]
+        if f.deleted:
+            who = ", ".join(f.deleted_by) or "unknown"
+            print(f"    deleted  {rel} (deleted by {who})")
+        elif f.added:
+            who = ",".join(sorted(f.agents)) if f.agents else "human"
+            print(f"    {f.label():6}  {rel} "
+                  f"({f.agent_added}/{f.added} agent) [{who}]")
+    print("\n  blast radius:")
+    ranked = sorted(blast.values(), key=lambda b: b.size, reverse=True)[:8]
+    if not ranked:
+        print("    no files changed")
+    for b in ranked:
+        print(f"    {b.file}: {b.size} downstream dependent(s)")
+        if b.direct:
+            print(f"      direct: {', '.join(b.direct[:5])}"
+                  + (" …" if len(b.direct) > 5 else ""))
+    print("\n  gates:")
+    if not gate_results:
+        print("    none configured")
+    for g in gate_results:
+        mark = "PASS" if g.passed else ("TIMEOUT" if g.timed_out else "FAIL")
+        print(f"    [{mark}] {g.command}")
+    print("\n  risk factors:")
+    for name, fac in breakdown.factors.items():
+        print(f"    {fac['points']:>3} pts  {name:12} {fac['detail']}")
+    print()
+    if breakdown.requires_review:
+        print(f"  ✗ score {breakdown.score} >= threshold {threshold}: "
+              "needs senior review")
+    else:
+        print(f"  ✓ score {breakdown.score} < threshold {threshold}")
+    print("═" * 56)
+
+
+def cmd_check(args) -> int:
+    root = args.root
+    _ensure_repo(root)
+    cfg = config_mod.load(root, args.base)
+
+    # Default head (HEAD) also verifies uncommitted working-tree changes:
+    # snapshot them into a synthetic commit so diff/blame see everything.
+    # An explicit --head means "committed range only".
+    head = args.head
+    if head == "HEAD":
+        snap = prov_mod.snapshot_worktree(root)
+        if snap:
+            head = snap
+    prov = prov_mod.analyze(root, args.base, head,
+                            cfg["agent_markers"])
+    if not prov:
+        print(f"no added lines in {args.base}..{args.head} — nothing to verify")
+        return 0
+    blast = br_mod.analyze(root, list(prov.keys()))
+    gate_results = (gates_mod.run_gates(root, cfg["gates"], cfg["timeout"])
+                    if not args.skip_gates else [])
+    breakdown = risk_mod.score(prov, blast, gate_results,
+                               cfg["sensitive_paths"],
+                               cfg["risk_threshold"])
+
+    if args.format == "json":
+        out = {
+            "tool": "pr-verify", "version": VERSION,
+            "base": args.base, "head": args.head,
+            "risk": breakdown.as_dict(),
+            "files": {
+                rel: {"added": f.added, "agent_added": f.agent_added,
+                      "label": f.label(), "agents": sorted(f.agents),
+                      "deleted": f.deleted, "deleted_by": f.deleted_by}
+                for rel, f in prov.items()},
+            "blast_radius": {
+                rel: {"direct": b.direct, "transitive": b.transitive}
+                for rel, b in blast.items()},
+            "gates": [g.as_dict() for g in gate_results],
+        }
+        print(json.dumps(out, indent=2))
+    else:
+        _report_human(prov, blast, gate_results, breakdown,
+                      cfg["risk_threshold"])
+
+    if any(not g.passed for g in gate_results):
+        # A failing policy gate is a failed verification, independent of
+        # --fail-on: the tool cannot vouch for this diff.
+        return 1
+    if args.fail_on == "high" and breakdown.requires_review:
+        return 1
+    if args.fail_on == "any-risk" and breakdown.score > 0:
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="pr-verify", description=__doc__)
+    p.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
+    p.add_argument("--root", default=os.getcwd())
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    i = sub.add_parser("init", help="Write example .pr-verify.yaml.")
+    i.add_argument("--force", action="store_true")
+
+    c = sub.add_parser("check", help="Verify a diff range.")
+    c.add_argument("--base", default="main",
+                   help="Base ref (default: main).")
+    c.add_argument("--head", default="HEAD",
+                   help="Head ref (default: HEAD, uncommitted "
+                        "working-tree changes included).")
+    c.add_argument("--format", choices=["human", "json"], default="human")
+    c.add_argument("--fail-on", choices=["high", "any-risk", "never"],
+                   default="high")
+    c.add_argument("--skip-gates", action="store_true")
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return {"init": cmd_init, "check": cmd_check}[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())