gitmole 0.16.0__tar.gz → 0.17.0__tar.gz

{gitmole-0.16.0 → gitmole-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.16.0
+Version: 0.17.0
 Summary: Offline git repository analysis with a terminal report: hotspots, coupling, ownership, code age, secrets, repo health.
 License: MIT
 Project-URL: Homepage, https://github.com/antvinni/gitmole

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/__init__.py

@@ -1,3 +1,3 @@
 """gitmole: offline git repository analysis with a terminal report."""
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/cli.py

@@ -369,6 +369,9 @@ def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, p
     from . import maat as _maat
     cut = _maat.months_before(meta["last_date"], 6) if meta["last_date"] else None
     first = meta.get("first_date_all") or meta["first_date"]   # the backtest reads the whole history, window or not
+    year = _maat.months_before(meta["last_date"], 12) if meta["last_date"] else None
+    if year and first and first <= year:
+        meta["duplicates"]["then"] = year   # the rate a year back, when the history reaches it
     if cut and first and first <= _maat.months_before(cut, 6):
         meta["backtest"] = {"status": "planned", "until": cut}
     else:
@@ -427,7 +430,7 @@ def _analyse(repo_dir: str, out_dir: str, args, ui: Console, planner, estimator)
     run.clear_outputs(out_dir)
     steps = planner(repo_dir, out_dir, branch=meta["branch"], age=age_ok, plots=plots_ok, ignore=ignore, types=types_spec, now=args.now,
                     since=args.since_date, lizard=lizard_ok, duplicates=duplicates_ok, backtest=cut, ignore_revs=run.ignore_revs_files(repo_dir),
-                    structure=getattr(args, "structure", False))
+                    structure=getattr(args, "structure", False), duplicates_then=meta["duplicates"].get("then"))
     run.save_meta(meta, out_dir)
     results = _execute(steps, log_path, repo_dir, args.workers, ui, timeout=args.timeout)
     if _control.cancelled.is_set():

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/duplicates.py

@@ -6,8 +6,10 @@ jscpd walks the working tree and reports every pair of matching fragments. This
 whose two sides are both tracked files inside the analysed types, folds the pairs of one fragment into
 a block with all its places, measures the duplicated share over the kept files, and writes
 duplicates.json. jscpd's own report quotes every fragment, so it is written to a temporary directory
-under OUT and removed before this returns: no source text lands in the output directory. Standalone,
-like maat.py and blame.py.
+under OUT and removed before this returns: no source text lands in the output directory. With --then
+DATE the tree at the last commit before that date is exported under OUT, measured the same way and
+removed, so the rate has a direction: GitClear's longitudinal data shows duplication is where the
+change is, and one number without the year before it says little. Standalone, like maat.py and blame.py.
 """
 from __future__ import annotations
 
@@ -118,6 +120,40 @@ def run_jscpd(repo: str, out: str, procs: int, ignore=()) -> tuple:
         shutil.rmtree(tmp, ignore_errors=True)
 
 
+def rev_before(repo: str, date: str):
+    out = subprocess.run(["git", "rev-list", "-1", f"--before={date}T00:00:00", "HEAD"], cwd=repo, capture_output=True, text=True)
+    return out.stdout.strip() or None
+
+
+def files_at(repo: str, rev: str, ignore=(), types_spec: str = None) -> list:
+    """The tracked text files of the tree at `rev`, in the analysed types, as select_files lists HEAD's."""
+    import fnmatch
+    proc = subprocess.run([*filetypes.GIT, "grep", "-I", "--name-only", "-z", "-e", "", rev], cwd=repo, capture_output=True)
+    types = filetypes.parse(types_spec)
+    paths = sorted(p.decode("utf-8", "surrogateescape").split(":", 1)[1] for p in proc.stdout.split(b"\0") if p)
+    return [f for f in paths if filetypes.matches(f, types) and not any(fnmatch.fnmatch(f, g) for g in ignore)]
+
+
+def rate_at(repo: str, out: str, rev: str, procs: int, ignore=(), types_spec: str = None):
+    """The duplicated share of the tree at `rev`: the tree exported through a temporary index under
+    `out` (as the backtest exports its cut-off), jscpd over it, the same fold and rate as HEAD's."""
+    tmp = tempfile.mkdtemp(prefix=".dup-then-", dir=out)
+    try:
+        tree = os.path.join(tmp, "tree")
+        os.makedirs(tree)
+        env = dict(os.environ, GIT_INDEX_FILE=os.path.join(tmp, "index"))
+        subprocess.run(["git", "read-tree", rev], cwd=repo, env=env, check=True, capture_output=True)
+        subprocess.run(["git", "checkout-index", "-a", f"--prefix={tree}/"], cwd=repo, env=env, check=True, capture_output=True)
+        files = files_at(repo, rev, ignore, types_spec)
+        rc, report = run_jscpd(tree, out, procs, ignore)
+        if rc != 0:
+            return None
+        blocks = fold(report.get("duplicates") or [], set(files))
+        return {"files": len(files), "rate": rate(blocks, tree, files)}
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
 def write(result: dict, target: str) -> None:
     fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath(target)), prefix=".duplicates-", suffix=".json")
     try:
@@ -136,6 +172,7 @@ def main(argv=None) -> int:
     p.add_argument("--procs", type=int, default=1)
     p.add_argument("--ignore", action="append", default=[])
     p.add_argument("--types", default=None, help="file types spec as for gitmole --file-types")
+    p.add_argument("--then", metavar="YYYY-MM-DD", help="also measure the tree at the last commit before this date, for the direction")
     args = p.parse_args(argv)
     repo, out = os.path.abspath(args.repo), os.path.abspath(args.out)
     files = select_files(repo, args.ignore, args.types)
@@ -145,6 +182,11 @@ def main(argv=None) -> int:
     blocks = fold(report.get("duplicates") or [], set(files))
     result = {"tool": "jscpd", "files": len(files), "clones": sum(len(b["places"]) - 1 for b in blocks),
               "rate": rate(blocks, repo, files), "blocks": blocks[:BLOCKS_KEPT]}
+    if args.then:
+        rev = rev_before(repo, args.then)
+        measured = rate_at(repo, out, rev, args.procs, args.ignore, args.types) if rev else None
+        if measured:
+            result["then"] = {"date": args.then, "rev": rev[:12], **measured}
     write(result, os.path.join(out, "duplicates.json"))
     return 0
 

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/findings.py

@@ -1022,9 +1022,76 @@ def unreferenced_files(report: dict) -> list:
                rule={"id": "unreferenced_files", "ref": "Romano et al., TSE 2020"}, evidence={"count": n, "files": paths[:10]})]
 
 
+def _agents(report: dict) -> dict:
+    return ((report.get("provenance") or {}).get("agents")) or {}
+
+
+def agent_approval_disabled(report: dict) -> list:
+    """A committed agent configuration that turns approval prompts off: every clone that picks the
+    settings up runs the agent's tools without asking."""
+    rows = _agents(report).get("approval_disabled") or []
+    if not rows:
+        return []
+    listed = "; ".join(f"{r['file']} sets {r['setting']}" for r in rows)
+    return [_f("warning", "Agent approval prompts turned off in the repository", f"{listed}. Anyone who opens the clone with that agent runs its tools unasked.",
+               "Move the setting to your personal settings file, which is not committed, and keep the shared one to what everyone should get.",
+               rule={"id": "agent_approval_disabled", "by": "tracked agent settings"}, evidence={"settings": rows})]
+
+
+def agent_local_settings(report: dict) -> list:
+    rows = _agents(report).get("local_settings") or []
+    if not rows:
+        return []
+    return [_f("warning", "Personal agent settings tracked", f"{_files_list(rows)} {'is' if len(rows) == 1 else 'are'} tracked; the file is meant for one machine and to stay out of git.",
+               f"git rm --cached {rows[0]} and add it to .gitignore.",
+               rule={"id": "agent_local_settings", "by": "path convention"}, evidence={"files": rows})]
+
+
+def mcp_literal_env(report: dict) -> list:
+    """An MCP server declaration whose environment holds a literal value long enough to be a
+    credential rather than a ${VAR} reference. The key is named, the value never."""
+    rows = [(m["file"], x) for m in _agents(report).get("mcp") or [] for x in m.get("literal_env") or []]
+    if not rows:
+        return []
+    listed = "; ".join(f"{x['server']} sets {x['key']} in {f} to a literal value" for f, x in rows[:5])
+    f0, x0 = rows[0]
+    return [_f("warning", "Literal values in MCP server declarations", f"{listed}. A committed declaration shares whatever it holds.",
+               f"Replace the value of {x0['key']} with ${{{x0['key']}}} and set it in the environment; rotate it if it was a live credential.",
+               rule={"id": "mcp_literal_env", "min_length": 16, "placeholders": "left out"},
+               evidence={"entries": [{"file": f, "server": x["server"], "key": x["key"]} for f, x in rows[:10]]})]
+
+
+def agent_instructions_drift(report: dict, min_months: int = 6, min_commits: int = 100) -> list:
+    """Agent instruction files (AGENTS.md and the like) far behind the code they describe."""
+    last = (report.get("meta") or {}).get("last_date") or ""
+    stale = [r for r in _agents(report).get("instructions") or []
+             if last and _months_apart(r["last"], last) >= min_months and r["commits_behind"] >= min_commits]
+    if not stale:
+        return []
+    listed = "; ".join(f"{r['file']} last changed on {r['last']}, {_months_apart(r['last'], last)} months and {r['commits_behind']:,} commits before the last commit" for r in stale)
+    return [_f("info", "Agent instructions behind the code", f"{listed}.",
+               f"Read {stale[0]['file']} against the tree and update what moved; an agent follows it literally.",
+               rule={"id": "agent_instructions_drift", "min_months": min_months, "min_commits": min_commits},
+               evidence={"files": stale})]
+
+
+def signoff_by_co_author(report: dict, min_commits: int = 2) -> list:
+    """An identity that signs off commits it co-authors but never authors one: the Linux kernel's policy
+    on coding assistants forbids an agent to add Signed-off-by, since the DCO is a human's statement."""
+    rows = [r for r in ((report.get("provenance") or {}).get("trailers") or {}).get("signoff_by_co_author") or [] if r["commits"] >= min_commits]
+    if not rows:
+        return []
+    listed = "; ".join(f"{r['name']} <{r['email']}> signs off {_plural(r['commits'], 'commit')} but never authors one" for r in rows[:3])
+    return [_f("info", "Sign-offs by identities that only co-author", f"{listed}.",
+               "A Signed-off-by line certifies the Developer Certificate of Origin; have a person who authors commits add it.",
+               rule={"id": "signoff_by_co_author", "min_commits": min_commits, "ref": "Linux kernel, Documentation/process/coding-assistants.rst"},
+               evidence={"identities": rows[:10]})]
+
+
 RULES = [dormant, secrets_found, credential_files, vulnerable_dependencies, placeholder_identity, bus_factor, sizer_concerns, hotspot_dominance, bug_magnets,
          minor_contributors, reverts, brain_methods, complexity_growth, tight_coupling, duplication, stale_files, knowledge_islands, knowledge_loss,
-         sweeping_commits, tangled_commits, hygiene_findings, debt_in_hotspots, deep_nesting, hidden_coupling, unreferenced_files]
+         sweeping_commits, tangled_commits, hygiene_findings, debt_in_hotspots, deep_nesting, hidden_coupling, unreferenced_files,
+         agent_approval_disabled, agent_local_settings, mcp_literal_env, agent_instructions_drift, signoff_by_co_author]
 
 
 def evaluate(report: dict) -> list:

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/load.py

@@ -197,7 +197,10 @@ def parse_duplicates_json(data) -> dict | None:
     blocks = [{"lines": _num(b.get("lines")), "places": sorted(tuple(p[:3]) for p in b.get("places") or [] if len(p) >= 3)}
               for b in data.get("blocks") or []]
     rate = data.get("rate")
-    return {"rate": float(rate) if rate is not None else None, "blocks": blocks, "files": _num(data.get("files"))}
+    out = {"rate": float(rate) if rate is not None else None, "blocks": blocks, "files": _num(data.get("files"))}
+    if isinstance(data.get("then"), dict):
+        out["then"] = data["then"]   # the rate at the last commit a year before: the direction
+    return out
 
 
 def parse_duplicates(text: str) -> dict:
@@ -331,6 +334,7 @@ def load_report(out_dir: str, nested: bool = True) -> dict:
         "signing": _read_json(out_dir, "signing.json", {}) or {},   # commit signing coverage; {} before the step or after a killed one
         "hygiene": _read_json(out_dir, "hygiene.json", {}) or {},   # the hygiene checks (hygiene.py); {} before 0.15
         "unreachable": _read_json(out_dir, "unreachable.json", {}) or {},
-        "structure": _read_json(out_dir, "structure.json", {}) or {},   # tree-sitter metrics (structure.py); {} without gitmole[structure]   # what the secrets step found outside reachable history
+        "structure": _read_json(out_dir, "structure.json", {}) or {},
+        "provenance": _read_json(out_dir, "provenance.json", {}) or {},   # trailers, cohorts, commit shape, agent files; {} before 0.17   # tree-sitter metrics (structure.py); {} without gitmole[structure]   # what the secrets step found outside reachable history
         "backtest": _nested(out_dir) if nested else None,
     }

gitmole-0.17.0/gitmole/provenance.py

@@ -0,0 +1,241 @@
+"""Provenance: what the history declares about how its commits were made, and the agent configuration
+the tree declares, read and never inferred.
+
+Runs as a pipeline step, `python -m gitmole.provenance OUT_DIR`, from inside the repository, and
+writes provenance.json:
+
+- trailers: every trailer key and how many commits carry it; the co-authors who never author a commit
+  here (a structural fact about the repository, no list of products); sign-offs by such identities,
+  which the Linux kernel's policy on coding assistants forbids an agent to add.
+- cohort: commits with an `Assisted-by` trailer or a never-authoring co-author, against the rest: how
+  many were reverted (by git's own `Revert "subject"`), how many are fixes, and how many had a file
+  changed again by another commit within two weeks. This repository against itself, with the share
+  of commits the cohort covers beside it; no prior from elsewhere, since the best-controlled study
+  found the spread between agents larger than the pooled difference.
+- shape: neutral descriptors (commits landing in bursts, conventional-commit subjects, how many hours
+  of the day commits come in). Every one has a benign cause, and none is labelled.
+- agents: the agent instruction files by path convention (AGENTS.md, CLAUDE.md, GEMINI.md,
+  .github/copilot-instructions.md) and how far behind HEAD each is, the hook files that declare
+  guardrails, tracked personal settings, settings that turn approval prompts off, and MCP server
+  declarations whose environment carries literal values rather than references. Values are never
+  written."""
+from __future__ import annotations
+
+import bisect
+import datetime as dt
+import json
+import os
+import re
+import subprocess
+import sys
+from collections import Counter
+
+try:
+    from . import filetypes, leaks
+except ImportError:  # run as a script: the package directory is sys.path[0]
+    import filetypes
+    import leaks
+
+SEP, END = "\x1f", "\x1e"
+# a trailer key is hyphenated by convention (Co-authored-by, Signed-off-by, Change-Id); git's parser also
+# accepts a URL or a line of prose that happens to end the message, and those are not trailers
+_TRAILER_LINE = re.compile(r"^([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+):\s*(?!//)(.+)$")
+_IDENT = re.compile(r"^\s*(?P<name>[^<]*?)\s*<(?P<email>[^>]*)>\s*$")
+_CONVENTIONAL = re.compile(r"^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]*\))?!?: \S")
+BURST_SIZE, BURST_SECONDS = 5, 600
+RETOUCH_DAYS = 14
+
+
+def read_commits(repo: str) -> list:
+    """[{hash, time, author, email, subject, trailers: [(key, value)], files}] of HEAD's history, oldest
+    first, through one git log: trailers by git's own parser, files from --name-only."""
+    fmt = f"{END}%H{SEP}%at{SEP}%aN{SEP}%aE{SEP}%s{SEP}%(trailers:unfold,only){SEP}"
+    out = subprocess.run([*filetypes.GIT, "log", "HEAD", "--use-mailmap", "--name-only", f"--format={fmt}"], cwd=repo,
+                         capture_output=True, check=True).stdout.decode("utf-8", "replace")
+    commits = []
+    for chunk in out.split(END)[1:]:
+        parts = chunk.split(SEP)
+        if len(parts) < 7:
+            continue
+        h, at, name, email, subject, trailer_text, files = parts[:7]
+        trailers = [(m.group(1), m.group(2).strip()) for m in (_TRAILER_LINE.match(l) for l in trailer_text.split("\n")) if m]
+        commits.append({"hash": h, "time": int(at), "author": name, "email": email.lower(), "subject": subject,
+                        "trailers": trailers, "files": [f for f in files.split("\n") if f.strip()]})
+    commits.reverse()
+    return commits
+
+
+def _ident(value: str):
+    m = _IDENT.match(value)
+    return (m.group("name"), m.group("email").lower()) if m else None
+
+
+def trailers(commits: list) -> dict:
+    keys = Counter()
+    authors = {c["email"] for c in commits} | {c["author"] for c in commits}
+    co, signed = Counter(), Counter()
+    names = {}
+    for c in commits:
+        for k in {k for k, _ in c["trailers"]}:
+            keys[k] += 1
+        for k, v in c["trailers"]:
+            ident = _ident(v)
+            if not ident:
+                continue
+            names.setdefault(ident[1], ident[0])
+            if k.lower() == "co-authored-by":
+                co[ident[1]] += 1
+            elif k.lower() == "signed-off-by":
+                signed[ident[1]] += 1
+    never = {e for e in co if e not in authors and names[e] not in authors}
+    listing = sorted(({"name": names[e], "email": e, "commits": co[e]} for e in never), key=lambda x: (-x["commits"], x["name"]))
+    signoff = sorted(({"name": names[e], "email": e, "commits": signed[e]} for e in never if signed.get(e)), key=lambda x: (-x["commits"], x["name"]))
+    return {"commits": len(commits), "keys": dict(sorted(keys.items(), key=lambda kv: (-kv[1], kv[0]))[:25]),
+            "with_any": sum(1 for c in commits if c["trailers"]), "never_author": listing[:50], "signoff_by_co_author": signoff[:50]}
+
+
+def cohort(commits: list, inventory: dict) -> dict:
+    """The commits an `Assisted-by` trailer or a never-authoring co-author marks, against the rest."""
+    marked_emails = {x["email"] for x in inventory["never_author"]}
+
+    def marked(c):
+        for k, v in c["trailers"]:
+            if k.lower() == "assisted-by":
+                return True
+            ident = _ident(v)
+            if k.lower() == "co-authored-by" and ident and ident[1] in marked_emails:
+                return True
+        return False
+
+    reverted = {c["subject"][len('Revert "'):-1] for c in commits if c["subject"].startswith('Revert "') and c["subject"].endswith('"')}
+    by_file = {}
+    for i, c in enumerate(commits):
+        for f in c["files"]:
+            by_file.setdefault(f, []).append(i)
+    stats = {True: Counter(), False: Counter()}
+    for i, c in enumerate(commits):
+        s = stats[marked(c)]
+        s["commits"] += 1
+        s["reverted"] += c["subject"] in reverted
+        s["fixes"] += bool(re.match(r"^(fix|hotfix|bugfix)(\([^)]*\))?!?:", c["subject"], re.I) or re.search(r"\b(fix|fixes|fixed|bug)\b", c["subject"], re.I))
+        again = False
+        for f in c["files"]:   # the next commit to touch each file, by position: the list is in commit order
+            k = bisect.bisect_right(by_file[f], i)
+            if k < len(by_file[f]) and commits[by_file[f][k]]["time"] - c["time"] <= RETOUCH_DAYS * 86400:
+                again = True
+                break
+        s["retouched"] += again
+    total = len(commits)
+    return {"definition": "an Assisted-by trailer, or a co-author who never authors a commit here",
+            "share": round(stats[True]["commits"] / total, 3) if total else 0.0,
+            "cohort": dict(stats[True]) or {"commits": 0}, "rest": dict(stats[False]) or {"commits": 0}}
+
+
+def shape(commits: list) -> dict:
+    """How commits arrive, as neutral numbers: the share landing in runs of five or more by one author
+    within ten minutes of each other, the share with conventional-commit subjects, and how many hours
+    of the day (in UTC) see commits."""
+    burst = set()
+    by_author = {}
+    for i, c in enumerate(commits):
+        by_author.setdefault(c["email"], []).append(i)
+    for idx in by_author.values():
+        run = [idx[0]]
+        for a, b in zip(idx, idx[1:]):
+            if commits[b]["time"] - commits[a]["time"] <= BURST_SECONDS:
+                run.append(b)
+            else:
+                if len(run) >= BURST_SIZE:
+                    burst.update(run)
+                run = [b]
+        if len(run) >= BURST_SIZE:
+            burst.update(run)
+    n = len(commits)
+    hours = {dt.datetime.fromtimestamp(c["time"], dt.timezone.utc).hour for c in commits}
+    return {"burst_share": round(len(burst) / n, 3) if n else 0.0,
+            "conventional_share": round(sum(bool(_CONVENTIONAL.match(c["subject"])) for c in commits) / n, 3) if n else 0.0,
+            "hours_used": len(hours)}
+
+
+INSTRUCTIONS = ("AGENTS.md", "CLAUDE.md", "GEMINI.md", ".github/copilot-instructions.md")
+GUARDRAILS = (".claude/settings.json", ".cursor/hooks.json")
+MCP = (".mcp.json", ".cursor/mcp.json", ".vscode/mcp.json")
+LOCAL = (".claude/settings.local.json",)
+_REFERENCE = re.compile(r"^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$|^\$\{[^}]+\}$|^\{\{.*\}\}$")
+
+
+def _json(repo: str, path: str):
+    try:
+        with open(os.path.join(repo, path), encoding="utf-8", errors="replace") as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return None
+
+
+def _literal_secret(value) -> bool:
+    """A literal environment value that could be a credential: a string, not a ${VAR} reference, not a
+    placeholder shape, and long enough to be a key (a short word is configuration)."""
+    if not isinstance(value, str):
+        return False
+    v = value.strip()
+    return len(v) >= 16 and not _REFERENCE.match(v) and not leaks.is_placeholder(v)
+
+
+def agents(repo: str) -> dict:
+    tracked = set(filetypes.git_paths(repo, "ls-files"))
+    head_count = int(subprocess.run(["git", "rev-list", "--count", "HEAD"], cwd=repo, capture_output=True, text=True).stdout.strip() or 0)
+    instructions = []
+    for path in sorted(p for p in tracked if p.rsplit("/", 1)[-1] in ("AGENTS.md", "CLAUDE.md", "GEMINI.md") or p in INSTRUCTIONS):
+        last = subprocess.run(["git", "log", "-1", "--format=%H%x1f%cs", "--", path], cwd=repo, capture_output=True, text=True).stdout.strip()
+        if not last:
+            continue
+        sha, day = last.split("\x1f")
+        behind = int(subprocess.run(["git", "rev-list", "--count", f"{sha}..HEAD"], cwd=repo, capture_output=True, text=True).stdout.strip() or 0)
+        instructions.append({"file": path, "last": day, "commits_behind": behind})
+    guard, disabled = [], []
+    for path in GUARDRAILS:
+        data = _json(repo, path) if path in tracked else None
+        if not isinstance(data, dict):
+            continue
+        if data.get("hooks"):
+            guard.append(path)
+        perms = data.get("permissions") if isinstance(data.get("permissions"), dict) else {}
+        if perms.get("defaultMode") == "bypassPermissions":
+            disabled.append({"file": path, "setting": "permissions.defaultMode=bypassPermissions"})
+        if data.get("skipDangerousModePermissionPrompt") is True:
+            disabled.append({"file": path, "setting": "skipDangerousModePermissionPrompt=true"})
+    mcp = []
+    for path in MCP:
+        data = _json(repo, path) if path in tracked else None
+        if not isinstance(data, dict):
+            continue
+        servers = data.get("mcpServers") or data.get("servers") or {}
+        if not isinstance(servers, dict):
+            continue
+        literal = [{"server": name, "key": key} for name, spec in sorted(servers.items()) if isinstance(spec, dict)
+                   for key, value in sorted((spec.get("env") or {}).items()) if _literal_secret(value)]
+        mcp.append({"file": path, "servers": len(servers), "literal_env": literal})
+    return {"instructions": instructions, "head_commits": head_count, "guardrails": guard, "approval_disabled": disabled,
+            "local_settings": sorted(p for p in tracked if p in LOCAL or p.endswith("/.claude/settings.local.json")), "mcp": mcp}
+
+
+def main(argv=None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1:
+        print("usage: provenance.py OUT_DIR", file=sys.stderr)
+        return 2
+    repo = os.getcwd()
+    try:
+        commits = read_commits(repo)
+    except subprocess.CalledProcessError as e:
+        print(f"provenance.py: {(e.stderr or b'').decode('utf-8', 'replace').strip() or e}", file=sys.stderr)
+        return 1
+    inventory = trailers(commits)
+    result = {"trailers": inventory, "cohort": cohort(commits, inventory), "shape": shape(commits), "agents": agents(repo)}
+    with open(os.path.join(args[0], "provenance.json"), "w", encoding="utf-8") as fh:
+        json.dump(result, fh)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/render.py

@@ -289,6 +289,12 @@ def pulse(report: dict) -> list:
     signed = signing_phrase(report)
     if signed:
         out.append(signed)
+    dup = report.get("duplicates") or {}
+    then = dup.get("then") or {}
+    if dup.get("rate") is not None and then.get("rate") is not None and max(dup["rate"], then["rate"]) >= 0.5:
+        now, before = dup["rate"], then["rate"]
+        way = "as a year before" if round(now, 1) == round(before, 1) else f"{'up' if now > before else 'down'} from {before:.1f}% a year before"
+        out.append(f"{now:.1f}% of lines duplicated, {way}")
     return out
 
 
@@ -517,6 +523,27 @@ def signing_section(report: dict, full: bool = True, width=None) -> dict:
     return _section("Signing by year", columns, rows, caption="; ".join(parts))
 
 
+def trailers_section(report: dict, full: bool = True, width=None) -> dict:
+    """The trailer keys the history carries, with the cohort comparison and the neutral commit-shape
+    descriptors below: --full and Markdown only. Read, never inferred; nothing is labelled."""
+    prov = report.get("provenance") or {}
+    tr, co, sh = prov.get("trailers") or {}, prov.get("cohort") or {}, prov.get("shape") or {}
+    columns = [("trailer", {}), ("commits", RIGHT), ("share", RIGHT)]
+    total = tr.get("commits") or 0
+    rows = [(k, n, _pct(n, total)) for k, n in (tr.get("keys") or {}).items()]
+    notes = []
+    marked, rest = co.get("cohort") or {}, co.get("rest") or {}
+    if marked.get("commits"):
+        def pair(key):
+            return f"{_pct(marked.get(key, 0), marked['commits'])} against {_pct(rest.get(key, 0), rest.get('commits') or 0)}"
+        notes.append(f"marked commits ({co.get('definition')}): {marked['commits']:,}, {round(100 * co.get('share', 0))}% of the history; "
+                     f"reverted {pair('reverted')} for the rest, fixes {pair('fixes')}, a file changed again within two weeks {pair('retouched')}")
+    if sh:
+        notes.append(f"{round(100 * sh.get('burst_share', 0))}% of commits land in bursts of five or more within ten minutes; "
+                     f"{round(100 * sh.get('conventional_share', 0))}% have conventional-commit subjects; commits come in {sh.get('hours_used', 0)} hours of the day")
+    return _section("Trailers", columns, rows, note=None if rows else "no trailers", caption="\n".join(notes) or None)
+
+
 def hotspots_section(report: dict, full: bool = True, width=None) -> dict:
     """Change frequency times size, Tornhill-style. Files no longer in the tree sort last. Drawn
     under `--full` and in the Markdown export only; the default terminal report leaves it to the
@@ -740,10 +767,10 @@ def compare_section(result: dict) -> dict:
 
 
 BUILDERS = [watch_section, size_section, people_section, knowledge_section, activity_section, timeline_section,
-            hotspots_section, coupling_section, signing_section, age_section, functions_section, health_section]
+            hotspots_section, coupling_section, signing_section, trailers_section, age_section, functions_section, health_section]
 # `--full` and Markdown only: Size, Activity and Code age are interesting once and rarely change what you
 # do next; Hotspots ranks the files the watch list already leads with, by the same product.
-FULL_ONLY = {"size", "activity", "age", "hotspots", "signing"}
+FULL_ONLY = {"size", "activity", "age", "hotspots", "signing", "trailers"}
 
 
 def sections(report: dict, full: bool = True, width=None) -> list:

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole/run.py

@@ -195,7 +195,7 @@ def manifest(repo_dir: str, args, version_of=tool_version) -> dict:
 # Everything a run writes besides meta.json and run.log. Removed before each run so a reused
 # --out directory never shows a previous run's data as this run's (a step skipped or killed
 # this time would otherwise leave last time's file in place).
-OUTPUTS = ["size.json", "repo-health.txt", "secrets.json", "dependencies.json", "log.txt", "activity.json", "functions.csv", "signing.json", "hygiene.json", "unreachable.json", "structure.json",
+OUTPUTS = ["size.json", "repo-health.txt", "secrets.json", "dependencies.json", "log.txt", "activity.json", "functions.csv", "signing.json", "hygiene.json", "unreachable.json", "structure.json", "provenance.json",
            "duplicates.json", "duplicates.txt",   # duplicates.txt: what lizard's finder wrote before jscpd
            "theseus/cohorts.json", "theseus/authors.json", "theseus/survival.json", "code-age.png", "survival.png", "trend.json"]
 OUTPUT_GLOBS = ["maat-*.csv"]
@@ -242,7 +242,7 @@ def ignore_revs_files(repo_dir: str) -> list:
 def plan(repo_dir: str, out_dir: str, branch: str = "HEAD", age: bool = True, plots: bool = False,
          procs: int = None, interval: int = MONTH, ignore=(), types: str = None, now: str = None, since: str = None,
          lizard: bool = False, duplicates: bool = True, trend: bool = True, samples: int = 12, backtest: str = None,
-         ignore_revs=(), structure: bool = False) -> list:
+         ignore_revs=(), structure: bool = False, duplicates_then: str = None) -> list:
     o = lambda name: os.path.join(out_dir, name)  # noqa: E731
     log = o("log.txt")
     ignores = [x for pattern in ignore for x in ("--ignore", pattern)]
@@ -263,6 +263,7 @@ def plan(repo_dir: str, out_dir: str, branch: str = "HEAD", age: bool = True, pl
         {"name": "change analysis", "argv": [sys.executable, MAAT_SCRIPT, log, out_dir, *type_args, *(["--now", now] if now else []), *(["--since", since] if since else []), "--aliases", o("meta.json"), *revs_args], "stdout": None, "deps": ["git-log"]},
         {"name": "signing", "argv": [sys.executable, "-m", "gitmole.signing", out_dir], "stdout": None, "deps": []},   # the gpgsig headers, no keyring
         {"name": "hygiene", "argv": [sys.executable, "-m", "gitmole.hygiene", out_dir], "stdout": None, "deps": []},   # the Scorecard checks, from the clone
+        {"name": "provenance", "argv": [sys.executable, "-m", "gitmole.provenance", out_dir], "stdout": None, "deps": []},   # trailers, cohorts, agent files
     ]
     workers = procs or blame.default_procs()
     if lizard:
@@ -271,7 +272,8 @@ def plan(repo_dir: str, out_dir: str, branch: str = "HEAD", age: bool = True, pl
     if structure:   # tree-sitter: nesting, cognitive complexity, debt markers, the import graph; gitmole[structure] only
         steps.append({"name": "structure", "argv": [sys.executable, "-m", "gitmole.structure", out_dir, "--procs", str(workers)], "stdout": None, "deps": []})
     if duplicates:
-        steps.append({"name": "duplicates", "argv": [sys.executable, DUPLICATES_SCRIPT, repo_dir, out_dir, "--procs", str(workers), *ignores, *type_args],
+        steps.append({"name": "duplicates", "argv": [sys.executable, DUPLICATES_SCRIPT, repo_dir, out_dir, "--procs", str(workers), *ignores, *type_args,
+                                                    *(["--then", duplicates_then] if duplicates_then else [])],   # the rate a year back: a direction
                       "stdout": None, "deps": []})
     if trend:
         steps.append({"name": "trend", "argv": [sys.executable, "-m", "gitmole.trend", out_dir, "--samples", str(samples)],

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.16.0
+Version: 0.17.0
 Summary: Offline git repository analysis with a terminal report: hotspots, coupling, ownership, code age, secrets, repo health.
 License: MIT
 Project-URL: Homepage, https://github.com/antvinni/gitmole

{gitmole-0.16.0 → gitmole-0.17.0}/gitmole.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ gitmole/leaks.py
 gitmole/load.py
 gitmole/loss.py
 gitmole/maat.py
+gitmole/provenance.py
 gitmole/render.py
 gitmole/run.py
 gitmole/sarif.py
@@ -66,6 +67,7 @@ tests/test_load.py
 tests/test_loss.py
 tests/test_maat.py
 tests/test_packaging.py
+tests/test_provenance.py
 tests/test_render.py
 tests/test_render_examples.py
 tests/test_run.py

{gitmole-0.16.0 → gitmole-0.17.0}/tests/test_duplicates.py

@@ -103,6 +103,19 @@ class Script(unittest.TestCase):
                              pair("src/a.py", "untracked.py", fragment="def f(x): secret sauce")],
               "statistics": {"total": {"percentage": 50.0}}}
 
+    def test_then_measures_the_tree_as_it_stood_at_a_date_as_well(self):
+        p, argv, cwd, written, leftovers, repo = self._run(self.REPORT, extra=["--then", "2099-01-01"])
+        self.assertEqual(p.returncode, 0, p.stderr)
+        then = written["then"]
+        self.assertEqual(then["date"], "2099-01-01")
+        self.assertEqual(len(then["rev"]), 12)
+        self.assertEqual(then["files"], written["files"], "the code files tracked at that commit: here the same as HEAD's")
+        self.assertEqual(then["rate"], written["rate"], "the same tree, the same rate")
+        self.assertEqual(leftovers, ["duplicates.json"], "the exported tree is removed again")
+        p, _, _, written, _, _ = self._run(self.REPORT, extra=["--then", "1990-01-01"])
+        self.assertEqual(p.returncode, 0, p.stderr)
+        self.assertNotIn("then", written, "no commit before that date: nothing to compare")
+
     def test_runs_jscpd_in_the_repo_and_writes_the_folded_blocks_without_the_fragments(self):
         p, argv, cwd, written, leftovers, repo = self._run(self.REPORT, extra=["--ignore", "vendor/**"])
         self.assertEqual(p.returncode, 0, p.stderr)

{gitmole-0.16.0 → gitmole-0.17.0}/tests/test_findings.py

@@ -1207,3 +1207,43 @@ class Structure(unittest.TestCase):
         r = self.base()
         r["structure"] = {"status": "not-installed"}
         self.assertFalse({"debt_in_hotspots", "deep_nesting", "hidden_coupling", "unreferenced_files"} & set(self.by_id(r)))
+
+
+class AgentSurface(unittest.TestCase):
+    def rep(self, agents=None, trailers=None):
+        return report(provenance={"agents": agents or {}, "trailers": trailers or {"never_author": [], "signoff_by_co_author": []}},
+                      meta={"name": "r", "commits": 1000, "identities": [], "last_date": "2026-09-01"})
+
+    def by_id(self, r):
+        return {f["rule"]["id"]: f for f in findings.evaluate(r)}
+
+    def test_approval_prompts_turned_off_and_personal_settings_tracked_are_warnings(self):
+        found = self.by_id(self.rep(agents={"approval_disabled": [{"file": ".claude/settings.json", "setting": "permissions.defaultMode=bypassPermissions"}],
+                                            "local_settings": [".claude/settings.local.json"]}))
+        f = found["agent_approval_disabled"]
+        self.assertEqual(f["severity"], "warning")
+        self.assertIn(".claude/settings.json sets permissions.defaultMode=bypassPermissions", f["detail"])
+        self.assertEqual(found["agent_local_settings"]["severity"], "warning")
+        self.assertIn(".claude/settings.local.json is tracked", found["agent_local_settings"]["detail"])
+
+    def test_literal_values_in_an_mcp_declaration_name_the_key_never_the_value(self):
+        f = self.by_id(self.rep(agents={"mcp": [{"file": ".mcp.json", "servers": 2, "literal_env": [{"server": "db", "key": "DB_URL"}]}]}))["mcp_literal_env"]
+        self.assertEqual(f["severity"], "warning")
+        self.assertIn("db sets DB_URL in .mcp.json to a literal value", f["detail"])
+        self.assertIn("${DB_URL}", f["advice"])
+
+    def test_stale_instructions(self):
+        found = self.by_id(self.rep(agents={"instructions": [{"file": "AGENTS.md", "last": "2025-01-01", "commits_behind": 640},
+                                                             {"file": "CLAUDE.md", "last": "2026-08-20", "commits_behind": 12}]}))
+        f = found["agent_instructions_drift"]
+        self.assertEqual(f["severity"], "info")
+        self.assertIn("AGENTS.md last changed on 2025-01-01, 20 months and 640 commits before the last commit", f["detail"])
+        self.assertNotIn("CLAUDE.md", f["detail"])
+
+    def test_a_sign_off_by_an_identity_that_only_co_authors(self):
+        f = self.by_id(self.rep(trailers={"never_author": [], "signoff_by_co_author": [{"name": "Ghost", "email": "ghost@x.com", "commits": 3}]}))["signoff_by_co_author"]
+        self.assertEqual(f["severity"], "info")
+        self.assertIn("Ghost <ghost@x.com> signs off 3 commits but never authors one", f["detail"])
+        self.assertEqual(self.by_id(self.rep()).get("signoff_by_co_author"), None)
+        one = self.rep(trailers={"never_author": [], "signoff_by_co_author": [{"name": "Ghost", "email": "ghost@x.com", "commits": 1}]})
+        self.assertIsNone(self.by_id(one).get("signoff_by_co_author"), "one commit is not a habit")

{gitmole-0.16.0 → gitmole-0.17.0}/tests/test_load.py

@@ -367,6 +367,11 @@ class LoadReport(unittest.TestCase):
             r = load.load_report(out)
         self.assertEqual(r["theseus_authors"], {"Bob": 90, "Ann": 10})
 
+    def test_the_duplication_rate_a_year_back_is_kept(self):
+        d = load.parse_duplicates_json({"rate": 6.1, "files": 10, "blocks": [], "then": {"date": "2025-09-17", "rev": "abc", "files": 9, "rate": 4.2}})
+        self.assertEqual(d["then"], {"date": "2025-09-17", "rev": "abc", "files": 9, "rate": 4.2})
+        self.assertNotIn("then", load.parse_duplicates_json({"rate": 6.1, "blocks": []}))
+
     def test_no_signing_file_is_an_empty_record(self):
         import os, tempfile
         with tempfile.TemporaryDirectory() as out:
@@ -376,6 +381,7 @@ class LoadReport(unittest.TestCase):
             self.assertEqual(load.load_report(out)["hygiene"], {})
             self.assertEqual(load.load_report(out)["unreachable"], {})
             self.assertEqual(load.load_report(out)["structure"], {})
+            self.assertEqual(load.load_report(out)["provenance"], {})
 
     def test_missing_optional_file_gives_empty_value(self):
         import tempfile

gitmole-0.17.0/tests/test_provenance.py

@@ -0,0 +1,128 @@
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+from gitmole import provenance
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+class Repo:
+    def __init__(self, d):
+        self.d = d
+        self.git("init", "-q", "-b", "main")
+
+    def git(self, *args, name="Ann", email="ann@x.com", date="2026-01-05T10:00:00"):
+        date = date + "+00:00"   # explicit: the hour count must not depend on the machine's time zone
+        env = dict(os.environ, GIT_CONFIG_GLOBAL="/dev/null", GIT_CONFIG_SYSTEM="/dev/null", GIT_AUTHOR_NAME=name, GIT_AUTHOR_EMAIL=email,
+                   GIT_COMMITTER_NAME=name, GIT_COMMITTER_EMAIL=email, GIT_AUTHOR_DATE=date, GIT_COMMITTER_DATE=date)
+        return subprocess.run(["git", *args], cwd=self.d, check=True, capture_output=True, env=env, text=True).stdout
+
+    def commit(self, path, text, message, **who):
+        full = os.path.join(self.d, path)
+        os.makedirs(os.path.dirname(full) or self.d, exist_ok=True)
+        with open(full, "a") as fh:
+            fh.write(text)
+        self.git("add", "-A", "-f", path, **who)   # -f: a personal excludes file may ignore .claude/settings.local.json
+        self.git("commit", "-q", "-m", message, **who)
+
+
+def history(d):
+    r = Repo(d)
+    r.commit("a.py", "1\n", "feat: start", date="2026-01-05T10:00:00")
+    r.commit("a.py", "2\n", "feat: helper\n\nCo-authored-by: Helper Agent <agent-bot@tools.example>", date="2026-01-05T10:02:00")
+    r.commit("b.py", "3\n", "feat: more\n\nAssisted-by: SomeModel v2\nSigned-off-by: Ann <ann@x.com>", date="2026-01-05T10:04:00")
+    r.commit("a.py", "4\n", "fix: a bug", date="2026-01-05T10:06:00")
+    r.commit("c.py", "5\n", "pair work\n\nCo-authored-by: Bob <bob@x.com>", date="2026-01-05T10:08:00")
+    r.commit("c.py", "6\n", "Bob's own", name="Bob", email="bob@x.com", date="2026-03-01T12:00:00")
+    r.commit("d.py", "7\n", "Revert \"feat: helper\"", date="2026-03-02T09:00:00")
+    r.commit("e.py", "8\n", "odd\n\nCo-authored-by: Ghost <ghost@x.com>\nSigned-off-by: Ghost <ghost@x.com>", date="2026-04-01T09:00:00")
+    r.commit("f.py", "9\n", "see the docs\n\nhttps://example.com/x\nNOTE: prose that ends a message", date="2026-04-02T09:00:00")
+    return r
+
+
+class Trailers(unittest.TestCase):
+    def test_inventory_and_the_co_author_who_never_authors(self):
+        with tempfile.TemporaryDirectory() as d:
+            history(d)
+            commits = provenance.read_commits(d)
+            out = provenance.trailers(commits)
+        self.assertEqual(out["commits"], 9)
+        self.assertEqual(out["keys"], {"Co-authored-by": 3, "Signed-off-by": 2, "Assisted-by": 1}, "a URL and a line of prose are not trailers")
+        self.assertEqual(out["with_any"], 4)
+        self.assertEqual(out["never_author"], [{"name": "Ghost", "email": "ghost@x.com", "commits": 1},
+                                               {"name": "Helper Agent", "email": "agent-bot@tools.example", "commits": 1}],
+                         "Bob co-authors and also authors, so he is not listed")
+        self.assertEqual(out["signoff_by_co_author"], [{"name": "Ghost", "email": "ghost@x.com", "commits": 1}],
+                         "a sign-off by an identity that only ever co-authors: what the kernel's policy forbids agents")
+
+
+class Cohorts(unittest.TestCase):
+    def test_trailer_cohort_against_the_rest(self):
+        with tempfile.TemporaryDirectory() as d:
+            history(d)
+            commits = provenance.read_commits(d)
+            out = provenance.cohort(commits, provenance.trailers(commits))
+        self.assertEqual(out["definition"], "an Assisted-by trailer, or a co-author who never authors a commit here")
+        self.assertEqual((out["cohort"]["commits"], out["rest"]["commits"]), (3, 6))
+        self.assertEqual(out["cohort"]["reverted"], 1, "the helper commit was reverted by subject")
+        self.assertEqual(out["rest"]["reverted"], 0)
+        self.assertEqual(out["cohort"]["fixes"], 0)
+        self.assertEqual(out["rest"]["fixes"], 1)
+        self.assertEqual(out["cohort"]["retouched"], 1, "a.py changed again two minutes after the helper commit")
+        self.assertEqual(out["share"], 0.333)
+
+
+class Shape(unittest.TestCase):
+    def test_neutral_descriptors_of_how_commits_arrive(self):
+        with tempfile.TemporaryDirectory() as d:
+            history(d)
+            out = provenance.shape(provenance.read_commits(d))
+        self.assertEqual(out["burst_share"], 0.556, "five of nine commits land in a run of five or more within ten minutes of each other")
+        self.assertEqual(out["conventional_share"], 0.444, "feat: x3 and fix: x1")
+        self.assertEqual(out["hours_used"], 3)
+        self.assertNotIn("ai", json.dumps(out).lower().replace("assisted", ""), "a descriptor is never labelled")
+
+
+class Agents(unittest.TestCase):
+    def test_agent_configuration_as_a_declared_surface(self):
+        with tempfile.TemporaryDirectory() as d:
+            r = Repo(d)
+            r.commit("AGENTS.md", "rules\n", "agents", date="2025-01-01T10:00:00")
+            r.commit(".claude/settings.json", json.dumps({"hooks": {"PostToolUse": []}, "permissions": {"defaultMode": "bypassPermissions"}}), "settings",
+                     date="2025-01-02T10:00:00")
+            r.commit(".claude/settings.local.json", "{}", "oops", date="2025-01-03T10:00:00")
+            r.commit(".mcp.json", json.dumps({"mcpServers": {"db": {"command": "x", "env": {"DB_URL": "postgres://u:" + "p4ss" * 4 + "@h/db",
+                                                                                            "TOKEN": "${TOKEN}", "MODE": "readonly"}},
+                                                             "web": {"command": "y"}}}), "mcp", date="2025-01-04T10:00:00")
+            for i in range(5):
+                r.commit("src.py", f"{i}\n", f"work {i}", date=f"2026-0{i + 1}-01T10:00:00")
+            out = provenance.agents(d)
+        self.assertEqual(out["instructions"], [{"file": "AGENTS.md", "last": "2025-01-01", "commits_behind": 8}])
+        self.assertEqual(out["guardrails"], [".claude/settings.json"])
+        self.assertEqual(out["approval_disabled"], [{"file": ".claude/settings.json", "setting": "permissions.defaultMode=bypassPermissions"}])
+        self.assertEqual(out["local_settings"], [".claude/settings.local.json"])
+        self.assertEqual(out["mcp"], [{"file": ".mcp.json", "servers": 2, "literal_env": [{"server": "db", "key": "DB_URL"}]}],
+                         "a ${VAR} reference is where a secret is read from; a short word is configuration; the values themselves are never written")
+        self.assertNotIn("p4ss", json.dumps(out))
+
+
+class Step(unittest.TestCase):
+    def test_the_step_writes_provenance_json(self):
+        with tempfile.TemporaryDirectory() as d:
+            history(d)
+            out = os.path.join(d, "out")
+            os.makedirs(out)
+            p = subprocess.run([sys.executable, "-m", "gitmole.provenance", out], cwd=d, capture_output=True, text=True,
+                               env=dict(os.environ, PYTHONPATH=ROOT, GIT_CONFIG_GLOBAL="/dev/null", GIT_CONFIG_SYSTEM="/dev/null"))
+            self.assertEqual(p.returncode, 0, p.stderr)
+            with open(os.path.join(out, "provenance.json")) as fh:
+                data = json.load(fh)
+        self.assertEqual(set(data), {"trailers", "cohort", "shape", "agents"})
+
+
+if __name__ == "__main__":
+    unittest.main()

{gitmole-0.16.0 → gitmole-0.17.0}/tests/test_render.py

@@ -257,6 +257,32 @@ class Report(unittest.TestCase):
         self.assertEqual(short, " · ".join(many[:6]) + " · 3 more")
         self.assertEqual(full, " · ".join(many))
 
+    def test_the_duplication_direction_is_a_header_phrase(self):
+        r = sample_report()
+        r["duplicates"] = {"rate": 6.1, "blocks": [], "then": {"date": "2025-09-10", "rate": 4.2, "files": 30}}
+        self.assertIn("6.1% of lines duplicated, up from 4.2% a year before", render.pulse(r))
+        r["duplicates"]["then"]["rate"] = 6.1
+        self.assertIn("6.1% of lines duplicated, as a year before", render.pulse(r))
+        del r["duplicates"]["then"]
+        self.assertFalse([x for x in render.pulse(r) if "duplicated" in x])
+
+    def test_provenance_is_a_full_only_section_of_trailers_with_the_cohort_and_shape_below(self):
+        r = sample_report()
+        r["provenance"] = {"trailers": {"commits": 363, "keys": {"Co-authored-by": 40, "Signed-off-by": 12, "Assisted-by": 5}, "with_any": 50,
+                                        "never_author": [{"name": "Helper", "email": "h@x", "commits": 30}], "signoff_by_co_author": []},
+                           "cohort": {"definition": "an Assisted-by trailer, or a co-author who never authors a commit here", "share": 0.096,
+                                      "cohort": {"commits": 35, "reverted": 2, "fixes": 4, "retouched": 20},
+                                      "rest": {"commits": 328, "reverted": 3, "fixes": 60, "retouched": 150}},
+                           "shape": {"burst_share": 0.12, "conventional_share": 0.8, "hours_used": 20}, "agents": {}}
+        self.assertNotIn("Trailers", rendered(r, [], width=200))
+        block = _section_text(rendered(r, [], width=200, full=True), "Trailers")
+        self.assertRegex(block, r"Co-authored-by\s+40\s+11%")
+        caption = render.trailers_section(r)["caption"]
+        self.assertIn("marked commits (an Assisted-by trailer, or a co-author who never authors a commit here): 35, 10% of the history; "
+                      "reverted 6% against 1% for the rest, fixes 11% against 18%, a file changed again within two weeks 57% against 46%", caption)
+        self.assertIn("12% of commits land in bursts of five or more within ten minutes; 80% have conventional-commit subjects; commits come in 20 hours of the day", caption)
+        self.assertIn("## Trailers", render.markdown(r, []))
+
     def test_the_secrets_line_says_what_lay_outside_reachable_history(self):
         r = sample_report()
         r["unreachable"] = {"objects": 0, "blobs": 0, "scanned": 0, "findings": 0}

{gitmole-0.16.0 → gitmole-0.17.0}/tests/test_run.py

@@ -226,7 +226,7 @@ class Plan(unittest.TestCase):
     def test_lists_every_tool_and_theseus_plots_depend_on_analyze(self):
         steps = run.plan("/r", "/o")
         names = [s["name"] for s in steps]
-        for expected in ["scc", "git-sizer", "betterleaks", "git-log", "change analysis", "code age", "signing", "hygiene"]:
+        for expected in ["scc", "git-sizer", "betterleaks", "git-log", "change analysis", "code age", "signing", "hygiene", "provenance"]:
             self.assertIn(expected, names)
         self.assertEqual(by_name(steps)["signing"]["argv"][1:], ["-m", "gitmole.signing", "/o"], "commit signing coverage, read from the objects, no keyring")
         self.assertEqual(by_name(steps)["signing"]["deps"], [], "it reads meta.json for the bot names, written before the steps start")
@@ -250,6 +250,14 @@ class Plan(unittest.TestCase):
         self.assertNotIn("--no-renames", by["git-log"]["argv"])
         self.assertEqual(by["git-log"]["argv"][:4], ["git", "-c", "core.quotePath=false", "log"], "non-ASCII paths must not be octal-escaped and quoted")
 
+    def test_provenance_runs_as_a_module_and_duplicates_measure_a_year_back(self):
+        steps = by_name(run.plan("/r", "/o", duplicates_then="2025-09-17"))
+        self.assertEqual(steps["provenance"]["argv"][1:], ["-m", "gitmole.provenance", "/o"])
+        argv = steps["duplicates"]["argv"]
+        self.assertEqual(argv[argv.index("--then") + 1], "2025-09-17")
+        self.assertNotIn("--then", by_name(run.plan("/r", "/o"))["duplicates"]["argv"])
+        self.assertIn("provenance.json", run.OUTPUTS)
+
     def test_the_structure_step_is_optional_and_runs_the_module(self):
         self.assertNotIn("structure", by_name(run.plan("/r", "/o")))
         step = by_name(run.plan("/r", "/o", structure=True, procs=3))["structure"]