gitvow 0.13.2__tar.gz → 0.14.0__tar.gz

{gitvow-0.13.2/src/gitvow.egg-info → gitvow-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.13.2
+Version: 0.14.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.13.2 → gitvow-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.13.2"
+version = "0.14.0"
 description = "Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{gitvow-0.13.2 → gitvow-0.14.0}/src/gitvow/cli.py

@@ -178,6 +178,19 @@ def cmd_check(a: argparse.Namespace) -> int:
     return 2 if d.blocks else 0
 
 
+def cmd_scan(a: argparse.Namespace) -> int:
+    """Read an existing repository's history: how much an agent wrote, and how much of it records who agreed."""
+    from .scan import build, render
+
+    try:
+        d = build(os.path.abspath(a.repo), a.since)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    print(json.dumps(d, indent=1) if a.json else render(d), end="" if not a.json else "\n")
+    return 0
+
+
 def cmd_status(a: argparse.Namespace) -> int:
     """Is the record actually being written here? Reports what is missing and the line that fixes it."""
     from .status import build, render
@@ -545,6 +558,13 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--target", help="branch the change is going to; scoped decisions not covering it are reopened")
     s.add_argument("--decisions-summary", action="store_true", help="print only the trailer block for a PR description")
     s.set_defaults(f=cmd_report)
+    s = sub.add_parser(
+        "scan", help="read an existing repository's history: how much an agent wrote, and who agreed to it"
+    )
+    s.add_argument("repo", nargs="?", default=".")
+    s.add_argument("--since", default="90d", help="90d, 6m, 1y or a date; default 90d")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(f=cmd_scan)
     s = sub.add_parser("status", help="check the install is live: hooks reachable, policy loads, git hooks in place")
     s.add_argument("--json", action="store_true")
     s.set_defaults(f=cmd_status)

gitvow-0.14.0/src/gitvow/scan.py

@@ -0,0 +1,228 @@
+"""What an existing repository already shows, before gitvow is installed anywhere.
+
+`gitvow scan` reads `git log` and nothing else: how much of the recent history an agent wrote, how much of
+that touched files the policy calls consequential, and how much of it records who agreed. It writes nothing,
+needs no configuration and works on a repository that has never heard of gitvow.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from typing import Any
+
+from .decisions import parse_trailers
+from .policy import DEFAULT_POLICY_PATH, PolicyError, load_policy
+from .state import git, toplevel
+
+# How an agent signs its own work. Trailers first, then the phrases agents put in a message body.
+AGENT_MARKS: tuple[tuple[str, str], ...] = (
+    ("Claude", r"Co-?authored-?by:[^\n]*(claude|anthropic)"),
+    ("Claude", r"Generated with \[Claude Code\]"),
+    ("Cursor", r"Co-?authored-?by:[^\n]*cursor"),
+    ("Copilot", r"Co-?authored-?by:[^\n]*copilot"),
+    ("Codex", r"Co-?authored-?by:[^\n]*(codex|chatgpt)"),
+    ("Gemini", r"Co-?authored-?by:[^\n]*(gemini|google-labs-jules)"),
+    ("Devin", r"Co-?authored-?by:[^\n]*devin"),
+    ("Aider", r"Co-?authored-?by:[^\n]*aider"),
+    ("Factory", r"Co-?authored-?by:[^\n]*(factory|droid)"),
+    ("Windsurf", r"Co-?authored-?by:[^\n]*(windsurf|codeium)"),
+)
+COMPILED = tuple((name, re.compile(pat, re.I)) for name, pat in AGENT_MARKS)
+SESSION_RE = re.compile(r"^Gitvow-Session:\s*\S+", re.M)
+MAX_COMMITS = 5000
+
+
+def _since_date(since: str) -> str:
+    m = re.fullmatch(r"(\d+)([dwmy])", since or "")
+    if not m:
+        return since
+    n, unit = int(m.group(1)), m.group(2)
+    days = n * {"d": 1, "w": 7, "m": 30, "y": 365}[unit]
+    return time.strftime("%Y-%m-%d", time.localtime(time.time() - days * 86400))
+
+
+def _policy_source(cwd: str, home: str | None = None) -> tuple[dict[str, Any], str]:
+    """The policy load_policy would use, and where it came from, so the scan can say whose rules it applied."""
+    home = home or os.path.expanduser("~")
+    for path, label in (
+        (os.path.join(cwd, ".gitvow", "policy.json"), "this repository's policy"),
+        (os.path.join(home, ".gitvow", "policy.json"), "your policy"),
+    ):
+        if os.path.exists(path):
+            try:
+                return load_policy(cwd, home), label
+            except PolicyError:
+                break
+    with open(DEFAULT_POLICY_PATH) as fh:
+        return json.load(fh), "the default policy"
+
+
+def _patterns(cwd: str) -> tuple[list[tuple[re.Pattern[str], str]], str]:
+    """The policy's own path rules decide what counts as consequential, so the scan reflects your policy."""
+    pol, source = _policy_source(cwd)
+    if not (pol.get("path_confirm") or []):
+        with open(DEFAULT_POLICY_PATH) as fh:
+            pol, source = json.load(fh), "the default policy"
+    out: list[tuple[re.Pattern[str], str]] = []
+    for r in pol.get("path_confirm") or []:
+        try:
+            out.append((re.compile(r["pattern"]), r.get("reason", "consequential path")))
+        except (re.error, KeyError, TypeError):
+            continue
+    return out, source
+
+
+def build(cwd: str, since: str = "90d") -> dict[str, Any]:
+    if not os.path.isdir(cwd):
+        raise ValueError(f"not a git repository: {cwd}")
+    try:
+        top = toplevel(cwd) or cwd
+    except OSError as e:
+        raise ValueError(f"not a git repository: {cwd}") from e
+    since_date = _since_date(since)
+    pats, policy_source = _patterns(top)
+    args = [
+        "log",
+        f"-{MAX_COMMITS}",
+        f"--since={since_date}",
+        "--no-merges",
+        "--name-only",
+        "--date=short",
+        "--format=%x01%H%x00%ad%x00%s%x00%B%x02",
+    ]
+    try:
+        rc, out, err = git(args, top)
+    except OSError as e:
+        raise ValueError(f"not a git repository: {cwd}") from e
+    if rc != 0:
+        raise ValueError(err or f"not a git repository: {cwd}")
+    commits = 0
+    agent_commits = 0
+    agents: dict[str, int] = {}
+    consequential: list[dict[str, Any]] = []
+    decided = opened = 0
+    files: dict[str, int] = {}
+    for rec in out.split("\x01"):
+        if not rec.strip():
+            continue
+        head, _, tail = rec.partition("\x02")
+        parts = head.split("\x00")
+        if len(parts) < 4:
+            continue
+        sha, date, subject, body = parts[0], parts[1], parts[2], parts[3]
+        commits += 1
+        seen = {name for name, rx in COMPILED if rx.search(body)}
+        if SESSION_RE.search(body):
+            seen.add("recorded by gitvow")
+        if not seen:
+            continue
+        agent_commits += 1
+        for name in seen:
+            agents[name] = agents.get(name, 0) + 1
+        changed = [ln.strip() for ln in tail.splitlines() if ln.strip()]
+        hits = []
+        for f in changed:
+            for rx, reason in pats:
+                if rx.search(f):
+                    hits.append((f, reason))
+                    files[f] = files.get(f, 0) + 1
+                    break
+        if not hits:
+            continue
+        trailers = parse_trailers(body)
+        answered = [t for t in trailers if t["answer"] in ("accepted", "declined")]
+        still_open = [t for t in trailers if t["answer"] == "open"]
+        if answered:
+            decided += 1
+        if still_open:
+            opened += 1
+        consequential.append(
+            {
+                "sha": sha[:7],
+                "date": date,
+                "subject": subject[:70],
+                "files": [f for f, _ in hits][:6],
+                "reasons": sorted({r for _, r in hits}),
+                "recorded": bool(answered),
+                "open": bool(still_open),
+                "by": sorted({t["by"] for t in answered if t.get("by")}),
+            }
+        )
+    return {
+        "repo": os.path.basename(top),
+        "since": since_date,
+        "until": time.strftime("%Y-%m-%d"),
+        "window": since,
+        "commits": commits,
+        "agent_commits": agent_commits,
+        "agent_share": round(agent_commits / commits, 2) if commits else None,
+        "agents": dict(sorted(agents.items(), key=lambda kv: -kv[1])),
+        "consequential": consequential,
+        "recorded": decided,
+        "open": opened,
+        "unrecorded": len(consequential) - decided,
+        "files": [{"path": p, "commits": n} for p, n in sorted(files.items(), key=lambda kv: -kv[1])[:8]],
+        "policy": policy_source,
+    }
+
+
+def _plural(n: int, one: str, many: str) -> str:
+    return one if n == 1 else many
+
+
+def render(d: dict[str, Any]) -> str:
+    lines: list[str] = []
+    win = d["window"] if re.fullmatch(r"\d+[dwmy]", d["window"] or "") else f"since {d['since']}"
+    human = {"d": "days", "w": "weeks", "m": "months", "y": "years"}
+    if re.fullmatch(r"\d+[dwmy]", win):
+        win = f"the last {win[:-1]} {human[win[-1]]}"
+    lines.append(f"{d['repo']} · {d['commits']} commits in {win}, merges excluded")
+    lines.append("")
+    if not d["commits"]:
+        lines.append("  no commits in this window. Try a longer one: gitvow scan --since 1y")
+        return "\n".join(lines) + "\n"
+    if not d["agent_commits"]:
+        lines.append("  no commits carry an agent's signature in this window.")
+        lines.append("")
+        lines.append("  Either agents are not writing here yet, or they leave no trailer. gitvow records")
+        lines.append("  every session from the moment it is installed, whether the agent signs or not.")
+        lines.append("")
+        lines.append("  Next: pipx install gitvow && gitvow install --user --check")
+        return "\n".join(lines) + "\n"
+    pct = round(100 * d["agent_commits"] / d["commits"])
+    who = ", ".join(d["agents"]) or "unknown"
+    lines.append(f"  {pct:>3}%  agent-assisted{'':11}{d['agent_commits']} of {d['commits']} · {who}")
+    n = len(d["consequential"])
+    if n:
+        shown = ", ".join(d["consequential"][0]["files"][:2]) if d["consequential"] else ""
+        more = f", +{len(d['files']) - 2} more" if len(d["files"]) > 2 else ""
+        lines.append(f"  {n:>4}  touched a gated file{'':6}{shown}{more}")
+        lines.append(f"  {d['recorded']:>4}  recorded who agreed")
+    lines.append("")
+    if not n:
+        lines.append("  None of them touched a file your policy calls consequential, on this history.")
+    elif d["recorded"] == 0:
+        lines.append("  Nothing is wrong with these commits. Nobody can tell you who agreed to them.")
+    elif d["unrecorded"]:
+        lines.append(
+            f"  {d['recorded']} of {n} record who agreed. The other {d['unrecorded']} "
+            f"{_plural(d['unrecorded'], 'does', 'do')} not."
+        )
+    else:
+        lines.append(f"  All {n} record who agreed, with evidence. This is what it looks like when it works.")
+    if d["open"]:
+        lines.append(f"  {d['open']} {_plural(d['open'], 'carries', 'carry')} an open finding nobody has answered.")
+    if n:
+        lines.append("")
+        lines.append("  Gated files in this window, by the rules in " + d["policy"] + ":")
+        for f in d["files"][:5]:
+            lines.append(f"    {f['path']}  ({f['commits']} {_plural(f['commits'], 'commit', 'commits')})")
+    lines.append("")
+    lines.append("  This reads git history and nothing else. It is a floor, not a total: an agent that")
+    lines.append("  leaves no trailer is invisible to it, and gitvow does not rely on trailers once installed.")
+    lines.append("")
+    lines.append("  Next: pipx install gitvow && gitvow install --user --check")
+    return "\n".join(lines) + "\n"

{gitvow-0.13.2 → gitvow-0.14.0/src/gitvow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.13.2
+Version: 0.14.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.13.2 → gitvow-0.14.0}/src/gitvow.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ src/gitvow/recall.py
 src/gitvow/redact.py
 src/gitvow/report.py
 src/gitvow/rules.py
+src/gitvow/scan.py
 src/gitvow/selftest.py
 src/gitvow/snapshots.py
 src/gitvow/state.py
@@ -44,6 +45,7 @@ tests/test_recall.py
 tests/test_redact.py
 tests/test_report.py
 tests/test_rules.py
+tests/test_scan.py
 tests/test_snapshots.py
 tests/test_status.py
 tests/test_transcript_formats.py

gitvow-0.14.0/tests/test_scan.py

@@ -0,0 +1,97 @@
+import json
+import subprocess
+
+from gitvow import cli
+from gitvow.scan import _since_date, build, render
+
+
+def _commit(repo, path, body, content="x\n"):
+    (repo / path).parent.mkdir(parents=True, exist_ok=True)
+    (repo / path).write_text(content)
+    subprocess.run(["git", "add", "-A"], cwd=repo, check=True, capture_output=True)
+    subprocess.run(["git", "commit", "-qm", body], cwd=repo, check=True, capture_output=True)
+
+
+def test_since_shorthand():
+    assert _since_date("2026-01-01") == "2026-01-01"
+    assert len(_since_date("90d")) == 10 and _since_date("90d") < _since_date("1d")
+    assert _since_date("6m") < _since_date("30d") and _since_date("1y") < _since_date("6m")
+
+
+def test_a_repository_with_nothing_recorded(repo, home):
+    _commit(repo, "core/auth_rules.go", "expose export\n\nCo-authored-by: Claude <noreply@anthropic.com>")
+    _commit(repo, "src/util.py", "tidy\n\nCo-authored-by: Cursor <cursoragent@cursor.com>")
+    _commit(repo, ".github/workflows/ci.yml", "ci: add a job\n\nGenerated with [Claude Code]")
+    _commit(repo, "docs/readme.md", "a human wrote this one")
+    d = build(str(repo))
+    assert d["commits"] == 5 and d["agent_commits"] == 3  # the fixture's own initial commit is the fifth
+    assert d["agent_share"] == 0.6
+    assert set(d["agents"]) == {"Claude", "Cursor"}
+    # only the two that touched a path the policy calls consequential
+    assert len(d["consequential"]) == 2
+    assert {f for c in d["consequential"] for f in c["files"]} == {"core/auth_rules.go", ".github/workflows/ci.yml"}
+    assert d["recorded"] == 0 and d["unrecorded"] == 2 and d["open"] == 0
+    text = render(d)
+    assert "agent-assisted" in text and "touched a gated file" in text
+    assert "Nobody can tell you who agreed to them." in text
+    assert "the default policy" in text  # no policy installed in this fixture
+    assert "a floor, not a total" in text
+
+
+def test_a_repository_where_it_is_recorded(repo, home):
+    _commit(
+        repo,
+        "core/auth_rules.go",
+        "expose export\n\nCo-authored-by: Claude <noreply@anthropic.com>\n"
+        "Gitvow-Session: s1\nGitvow-Accepted: edit core/auth_rules.go by nikhil scope=staging: reviewed",
+    )
+    _commit(
+        repo,
+        "core/authz.py",
+        "second one\n\nCo-authored-by: Claude <noreply@anthropic.com>\nGitvow-Open: edit core/authz.py",
+    )
+    d = build(str(repo))
+    assert d["agent_commits"] == 2 and len(d["consequential"]) == 2
+    assert d["recorded"] == 1 and d["unrecorded"] == 1 and d["open"] == 1
+    assert d["consequential"][1]["by"] == ["nikhil"] and d["consequential"][1]["recorded"] is True
+    text = render(d)
+    assert "1 of 2 record who agreed. The other 1 does not." in text
+    assert "1 carries an open finding nobody has answered." in text
+
+
+def test_everything_recorded_says_so(repo, home):
+    _commit(
+        repo,
+        "core/auth_rules.go",
+        "one\n\nCo-authored-by: Claude <x@y>\nGitvow-Accepted: edit core/auth_rules.go by nikhil",
+    )
+    text = render(build(str(repo)))
+    assert "All 1 record who agreed, with evidence." in text
+
+
+def test_no_agent_signatures_is_not_a_failure(repo, home):
+    _commit(repo, "src/util.py", "a person wrote this")
+    d = build(str(repo))
+    assert d["agent_commits"] == 0 and d["agent_share"] == 0.0
+    text = render(d)
+    assert "no commits carry an agent's signature" in text
+    assert "whether the agent signs or not" in text
+    assert "pipx install gitvow" in text
+
+
+def test_an_empty_window_suggests_a_longer_one(repo, home):
+    d = build(str(repo), since="2099-01-01")
+    assert d["commits"] == 0 and d["agent_share"] is None
+    assert "gitvow scan --since 1y" in render(d)
+
+
+def test_cli_scan_text_and_json(repo, home, monkeypatch, capsys):
+    _commit(repo, "core/auth_rules.go", "x\n\nCo-authored-by: Claude <x@y>")
+    monkeypatch.chdir(repo)
+    assert cli.main(["scan"]) == 0
+    assert "agent-assisted" in capsys.readouterr().out
+    assert cli.main(["scan", "--json", "--since", "1y"]) == 0
+    d = json.loads(capsys.readouterr().out)
+    assert d["repo"] == "repo" and d["agent_commits"] == 1 and d["window"] == "1y"
+    assert cli.main(["scan", "/nonexistent-path-for-scan"]) == 1
+    assert "not a git repository" in capsys.readouterr().err