gitmole 0.17.0__tar.gz → 0.18.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.17.0
+Version: 0.18.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
@@ -44,7 +44,7 @@ Free. Any Stack. Local. Offline. Deterministic. Fast.
 - **Free.** MIT licence, no paid tier, no account, no token. A local clone needs no credentials, and a public `owner/repo` is cloned with plain git. Your `gh` login is only used for private repositories and for `owner/*`, and only when you ask for them. The tools it runs are open source too.
 - **Any stack.** It reads what every repository has: the git log, git blame and the files themselves.
 - **Local & Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
-- **Deterministic.** No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule and the numbers it fired on. The same clone gives the same report every time. 
+- **Deterministic.** No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule, the numbers it fired on and, where a rule rests on a paper, the citation. The same commit gives the same bytes: gitmole's own CI runs it twice on every commit, compares the exports and attests the report.
 
 ## Install
 
@@ -73,12 +73,17 @@ gitmole . --markdown report.md         # the same report as a Markdown document
 gitmole . --json report.json           # every table, the watch list and the findings
 gitmole . --fail-on warning            # exit 3 if any finding is a warning or worse
 gitmole . --risk main --risk-threshold 10  # exit 3 if the files changed since main hold over 10% of the risk
+gitmole . --sarif gitmole.sarif        # the findings for GitHub code scanning or GitLab
+gitmole . --compare last.json          # what changed since an earlier --json export
+gitmole analysis-repo --no-run --hook  # a coding agent's edit hook: history's view of the files it just touched
 gitmole . --since 2y --full            # the current team, every row and column
 gitmole --clean                        # list what gitmole left behind, delete on a yes
 ```
 
 A CI job that runs `gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY"`
-blocks on secrets in source files and still posts the report. Every option:
+blocks on secrets in source files and still posts the report. The same
+scoring wires into Claude Code, Cursor, Gemini CLI and pre-commit as a hook
+that exits 2 over a threshold. Every option:
 [docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
 
 ## What you get
@@ -87,9 +92,9 @@ Reports on repositories you know, each at a pinned commit, published as gitmole
 
 | Repository | Commit | Commits | Lines | gitmole run |
 |---|---|---:|---:|---:|
-| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | [`540ee5b5`](https://github.com/curl/curl/commit/540ee5b560cc6e775e11317048a13cc7e355bf91) | 39,758 | 247,179 | 61 s |
-| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | [`8cbdd4a8`](https://github.com/django/django/commit/8cbdd4a814397f81adf0129288f32b615bd1f94f) | 34,933 | 431,749 | 153 s |
-| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | [`2b19aecd`](https://github.com/facebook/react/commit/2b19aecd0e9111b774fad0fad9862e50bcb5bc8a) | 21,703 | 681,078 | 138 s |
+| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | [`540ee5b5`](https://github.com/curl/curl/commit/540ee5b560cc6e775e11317048a13cc7e355bf91) | 39,758 | 247,179 | 57 s |
+| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | [`8cbdd4a8`](https://github.com/django/django/commit/8cbdd4a814397f81adf0129288f32b615bd1f94f) | 34,933 | 431,749 | 132 s |
+| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | [`2b19aecd`](https://github.com/facebook/react/commit/2b19aecd0e9111b774fad0fad9862e50bcb5bc8a) | 21,703 | 681,078 | 151 s |
 
 Run times are one `gitmole CLONE` with every default step, on a MacBook Pro (M4, 16 GB).
 
@@ -110,6 +115,7 @@ you about a clone.
 | Which blocks of code appear more than once | [jscpd](https://github.com/kucherenko/jscpd) | brew |
 | Have secrets ever been committed | [betterleaks](https://github.com/betterleaks/betterleaks) | brew |
 | Do the dependencies have known vulnerabilities | [osv-scanner](https://github.com/google/osv-scanner), offline against a local copy of the OSV database | brew, plus a one-time database download |
+| How deeply nested is the code, what did the authors flag, what imports what | [tree-sitter](https://github.com/tree-sitter/py-tree-sitter) grammars for eleven languages | pip, opt-in with `gitmole[structure]` |
 
 Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
 
@@ -121,6 +127,7 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 - [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django and react at pinned commits, regenerated by `bin/render-examples`.
 - [Validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md): the watch list against other ways of ranking the same files at six cut-offs on three repositories.
 - [Why these tools](https://github.com/antvinni/gitmole/blob/main/docs/tools.md): the rationale, what was left out, licences.
+- [References](https://github.com/antvinni/gitmole/blob/main/docs/references.md): the research and tools gitmole's rules are built on.
 - [Development](https://github.com/antvinni/gitmole/blob/main/docs/development.md): setup, tests, releases, code layout.
 - [Contributing](https://github.com/antvinni/gitmole/blob/main/CONTRIBUTING.md): bugs, ideas, pull requests, security reports.
 

{gitmole-0.17.0 → gitmole-0.18.0}/README.md

@@ -11,7 +11,7 @@ Free. Any Stack. Local. Offline. Deterministic. Fast.
 - **Free.** MIT licence, no paid tier, no account, no token. A local clone needs no credentials, and a public `owner/repo` is cloned with plain git. Your `gh` login is only used for private repositories and for `owner/*`, and only when you ask for them. The tools it runs are open source too.
 - **Any stack.** It reads what every repository has: the git log, git blame and the files themselves.
 - **Local & Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
-- **Deterministic.** No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule and the numbers it fired on. The same clone gives the same report every time. 
+- **Deterministic.** No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule, the numbers it fired on and, where a rule rests on a paper, the citation. The same commit gives the same bytes: gitmole's own CI runs it twice on every commit, compares the exports and attests the report.
 
 ## Install
 
@@ -40,12 +40,17 @@ gitmole . --markdown report.md         # the same report as a Markdown document
 gitmole . --json report.json           # every table, the watch list and the findings
 gitmole . --fail-on warning            # exit 3 if any finding is a warning or worse
 gitmole . --risk main --risk-threshold 10  # exit 3 if the files changed since main hold over 10% of the risk
+gitmole . --sarif gitmole.sarif        # the findings for GitHub code scanning or GitLab
+gitmole . --compare last.json          # what changed since an earlier --json export
+gitmole analysis-repo --no-run --hook  # a coding agent's edit hook: history's view of the files it just touched
 gitmole . --since 2y --full            # the current team, every row and column
 gitmole --clean                        # list what gitmole left behind, delete on a yes
 ```
 
 A CI job that runs `gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY"`
-blocks on secrets in source files and still posts the report. Every option:
+blocks on secrets in source files and still posts the report. The same
+scoring wires into Claude Code, Cursor, Gemini CLI and pre-commit as a hook
+that exits 2 over a threshold. Every option:
 [docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
 
 ## What you get
@@ -54,9 +59,9 @@ Reports on repositories you know, each at a pinned commit, published as gitmole
 
 | Repository | Commit | Commits | Lines | gitmole run |
 |---|---|---:|---:|---:|
-| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | [`540ee5b5`](https://github.com/curl/curl/commit/540ee5b560cc6e775e11317048a13cc7e355bf91) | 39,758 | 247,179 | 61 s |
-| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | [`8cbdd4a8`](https://github.com/django/django/commit/8cbdd4a814397f81adf0129288f32b615bd1f94f) | 34,933 | 431,749 | 153 s |
-| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | [`2b19aecd`](https://github.com/facebook/react/commit/2b19aecd0e9111b774fad0fad9862e50bcb5bc8a) | 21,703 | 681,078 | 138 s |
+| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | [`540ee5b5`](https://github.com/curl/curl/commit/540ee5b560cc6e775e11317048a13cc7e355bf91) | 39,758 | 247,179 | 57 s |
+| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | [`8cbdd4a8`](https://github.com/django/django/commit/8cbdd4a814397f81adf0129288f32b615bd1f94f) | 34,933 | 431,749 | 132 s |
+| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | [`2b19aecd`](https://github.com/facebook/react/commit/2b19aecd0e9111b774fad0fad9862e50bcb5bc8a) | 21,703 | 681,078 | 151 s |
 
 Run times are one `gitmole CLONE` with every default step, on a MacBook Pro (M4, 16 GB).
 
@@ -77,6 +82,7 @@ you about a clone.
 | Which blocks of code appear more than once | [jscpd](https://github.com/kucherenko/jscpd) | brew |
 | Have secrets ever been committed | [betterleaks](https://github.com/betterleaks/betterleaks) | brew |
 | Do the dependencies have known vulnerabilities | [osv-scanner](https://github.com/google/osv-scanner), offline against a local copy of the OSV database | brew, plus a one-time database download |
+| How deeply nested is the code, what did the authors flag, what imports what | [tree-sitter](https://github.com/tree-sitter/py-tree-sitter) grammars for eleven languages | pip, opt-in with `gitmole[structure]` |
 
 Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
 
@@ -88,6 +94,7 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 - [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django and react at pinned commits, regenerated by `bin/render-examples`.
 - [Validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md): the watch list against other ways of ranking the same files at six cut-offs on three repositories.
 - [Why these tools](https://github.com/antvinni/gitmole/blob/main/docs/tools.md): the rationale, what was left out, licences.
+- [References](https://github.com/antvinni/gitmole/blob/main/docs/references.md): the research and tools gitmole's rules are built on.
 - [Development](https://github.com/antvinni/gitmole/blob/main/docs/development.md): setup, tests, releases, code layout.
 - [Contributing](https://github.com/antvinni/gitmole/blob/main/CONTRIBUTING.md): bugs, ideas, pull requests, security reports.
 

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

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

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

@@ -592,7 +592,7 @@ def _render(out_dir: str, console: Console, ui: Console, args, err: Console) ->
             return 2
         comparison = _compare.compare(before, report, found)
     if args.json:
-        _write(json.dumps(render.to_json(report, found, risk=risk, compare=comparison), indent=2) + "\n", args.json, console)
+        _write(render.dumps_json(report, found, risk=risk, compare=comparison), args.json, console)
     if args.markdown:
         _write(render.markdown(report, found, full=args.full, risk=risk, base=args.risk, compare=comparison), args.markdown, console)
     if args.sarif:

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/compare.py

@@ -65,4 +65,13 @@ def compare(before: dict, report: dict, found: list, top: int = watch.WATCH_TOP)
             "watch_entered": [f for f in after_watch if f not in before_watch], "watch_left": [f for f in before_watch if f not in after_watch],
             "tally": {"before": _tally(before.get("findings") or []), "after": _tally(found)},
             "before": {"commit": (meta_b.get("run") or {}).get("commit"), "date": meta_b.get("last_date"),
-                       "options_differ": _options_differ(meta_b, meta_a)}}
+                       "options_differ": _options_differ(meta_b, meta_a), "database": _database_changed(before, report)}}
+
+
+def _database_changed(before: dict, report: dict):
+    """{before, after} dates when the two runs scanned against different snapshots of the OSV database,
+    else None: a new advisory changes the vulnerable-dependency finding without any change to the code."""
+    b, a = before.get("dependencies") or {}, report.get("dependencies") or {}
+    if b.get("database_digest") and a.get("database_digest") and b["database_digest"] != a["database_digest"]:
+        return {"before": b.get("database_date"), "after": a.get("database_date")}
+    return None

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/deps.py

@@ -58,6 +58,28 @@ def database_date(base: str = None) -> str | None:
     return dt.datetime.fromtimestamp(newest).date().isoformat() if newest else None
 
 
+def database_digest(base: str = None) -> str | None:
+    """A digest of the local database snapshot: every file under the cache directories, by path, size
+    and modification time. Two runs against the same snapshot agree; a refresh changes it, which is how
+    --compare can say a dependency finding moved because the database did. None when there is none."""
+    import hashlib
+    base = cache_dir() if base is None else base
+    entries = []
+    for name in CACHE_DIRS:
+        root = os.path.join(base, name)
+        for dirpath, _, files in os.walk(root):
+            for f in files:
+                full = os.path.join(dirpath, f)
+                try:
+                    st = os.stat(full)
+                except OSError:
+                    continue
+                entries.append(f"{os.path.relpath(full, base)}\0{st.st_size}\0{int(st.st_mtime)}")
+    if not entries:
+        return None
+    return hashlib.sha256("\n".join(sorted(entries)).encode("utf-8", "surrogateescape")).hexdigest()[:16]
+
+
 def _key(version: str) -> tuple:
     return tuple(int(n) for n in _NUMBER.findall(version or ""))
 
@@ -94,7 +116,7 @@ def _score(groups: list, vulns: list) -> float | None:
 
 
 _WORDS = {"CRITICAL": 9.5, "HIGH": 8.0, "MODERATE": 5.5, "MEDIUM": 5.5, "LOW": 2.0}
-MALICIOUS_PREFIX = "MAL-"   # OpenSSF malicious-packages records, in the same OSV database; they carry no CVSS
+MALICIOUS_PREFIX = "MAL-"   # OpenSSF malicious-packages records (ossf/malicious-packages), in the same OSV database; they carry no CVSS
 
 
 def is_malicious(vulns: list) -> bool:
@@ -185,6 +207,7 @@ def main(argv=None) -> int:
             return 1
         result = summarise(data, os.getcwd())
         result["database_date"] = database_date()
+        result["database_digest"] = database_digest()
     else:
         print(f"deps.py: osv-scanner exited {proc.returncode}; no report written", file=sys.stderr)
         return proc.returncode

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

@@ -1,4 +1,5 @@
-"""Heuristics that turn a loaded report into a short list of flagged findings."""
+"""Heuristics that turn a loaded report into a short list of flagged findings. A rule that rests on a paper
+carries the short citation in its rule dict's `ref` (see REFS); docs/references.md has the full entries."""
 from __future__ import annotations
 
 import re
@@ -11,11 +12,23 @@ PLACEHOLDER_NAMES = {"your name", "unknown", "root", "user"}
 PLACEHOLDER_EMAIL = re.compile(r"(@example\.(com|org|net)$|^you@|^user@|^root@|@localhost$)")
 
 
+# The paper a rule rests on, as the short citation the rule dict carries in `ref`; the full entries are in
+# docs/references.md. A rule that is gitmole's own heuristic has none.
+REFS = {"minor_contributors": "Bird et al., FSE 2011", "tangled_commits": "Herzig and Zeller, MSR 2013",
+        "brain_methods": "Lanza and Marinescu, 2006", "tight_coupling": "Gall, Hajek and Jazayeri, ICSM 1998",
+        "hotspot_dominance": "Tornhill, Your Code as a Crime Scene, 2024", "trojan_source": "Boucher and Anderson, USENIX Security 2023",
+        "debt_in_hotspots": "Maldonado and Shihab, MTD 2015", "hidden_coupling": "Ajienka and Capiluppi, JSS 2017",
+        "unreferenced_files": "Romano et al., TSE 2020", "signoff_by_co_author": "Linux kernel, Documentation/process/coding-assistants.rst",
+        "deep_nesting": "SonarSource cognitive complexity; CodeScene code health"}
+
+
 def _f(severity: str, title: str, statement: str, advice: str, rule: dict, evidence: dict) -> dict:
     """A finding: the facts, then the next step. `detail` is the two joined for anyone reading the
     JSON; `advice` says which part is the step so the report can show it on its own line. `rule` is
     the rule's id and the thresholds it fired on, `evidence` the numbers they were compared with:
     between them a reader of the JSON can check the finding without reading this file."""
+    if rule.get("id") in REFS and "ref" not in rule:
+        rule = {**rule, "ref": REFS[rule["id"]]}
     return {"severity": severity, "title": title, "detail": f"{statement.rstrip()} {advice}", "advice": advice,
             "rule": rule, "evidence": evidence}
 

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/hook.py

@@ -1,4 +1,5 @@
-"""The agent-hook gate: `gitmole OUT_DIR --no-run --hook [--risk-threshold N] [-- FILE...]`.
+"""The agent-hook gate: `gitmole OUT_DIR --no-run --hook [--risk-threshold N] [-- FILE...]`, after Codacy's
+argument for deterministic findings before inference and Zimmermann et al.'s co-change recommendations.
 
 Deterministic findings should run before inference, so the model reasons over a short list rather
 than rediscovering known issues. A linter says what is wrong in the diff; gitmole says what history

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/hygiene.py

@@ -1,5 +1,6 @@
 """Repository hygiene from the clone alone: the checks OpenSSF Scorecard and the OSPS Baseline make
-through the GitHub API, done with file and git reads.
+through the GitHub API, done with file and git reads; Trojan Source after Boucher and Anderson (USENIX
+Security 2023).
 
 Runs as a pipeline step, `python -m gitmole.hygiene OUT_DIR`, from inside the repository, and writes
 hygiene.json; findings.py turns it into findings. Each check keys on a convention of the ecosystem (a

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/leaks.py

@@ -228,6 +228,9 @@ def scan_unreachable(repo: str, out_dir: str, found: dict) -> list:
         sha = os.path.basename(r.get("File") or "")
         r["File"] = f"(unreachable blob {sha[:12]})"
         r["Commit"] = ""
+        # betterleaks' own fingerprint names the scratch path the blob was written to; this one names the blob,
+        # so it is the same in every run and can go into .betterleaksignore
+        r["Fingerprint"] = f"unreachable:{sha}:{r.get('RuleID', '')}:{r.get('StartLine', '')}"
     return rows
 
 

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

@@ -182,6 +182,7 @@ def parse_functions(text: str) -> list:
         anonymous = name in ("", "(anonymous)")
         rows.append({"file": _rel(r[6]), "function": textfmt.cut(label if anonymous and label else name, NAME_CAP) or "(anonymous)", "anonymous": anonymous,
                      "ccn": _num(r[1]), "nloc": _num(r[0]), "params": _num(r[3]), "start": _num(r[9]), "end": _num(r[10]), "suspect": suspect})
+    rows.sort(key=lambda f: (f["file"], f["start"], f["end"], f["function"]))   # the function step works in parallel; the order is this one
     return rows
 
 
@@ -239,6 +240,8 @@ def parse_secrets(text: str) -> list:
             value, placeholder = None, False
         out.append({"rule": r.get("RuleID", ""), "file": r.get("File", ""), "commit": r.get("Commit", "")[:7], "line": r.get("StartLine"),
                     "fingerprint": r.get("Fingerprint", ""), "value": value, "placeholder": placeholder})
+    # betterleaks scans in parallel and does not promise an order; everything downstream reads the rows in this one
+    out.sort(key=lambda r: (r["file"], r["commit"], r["line"] or 0, r["rule"], r["fingerprint"]))
     return out
 
 
@@ -251,6 +254,8 @@ def parse_dependencies(data) -> dict:
     if data["status"] == "scanned":
         out.update({"sources": data.get("sources") or [], "packages": _num(data.get("packages")),
                     "vulnerable": data.get("vulnerable") or [], "database_date": data.get("database_date")})
+        if data.get("database_digest"):
+            out["database_digest"] = data["database_digest"]
     elif data["status"] == "no-database":
         out["download"] = data.get("download") or ""
     return out

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/maat.py

@@ -1,5 +1,7 @@
 #!/usr/bin/env python3
-"""Change analysis over a git log export, in the layout code-maat produced.
+"""Change analysis over a git log export, in the layout code-maat produced: revisions, coupling and sum of
+coupling after Adam Tornhill's code-maat, minor contributors after Bird et al. (FSE 2011), change entropy
+after Hassan (ICSE 2009), oversized fixes after Herzig and Zeller (MSR 2013); see docs/references.md.
 
 Standalone on purpose: gitmole runs it as a pipeline step with
 `python3 maat.py LOG OUT_DIR [--aliases META_JSON]` and it must not need the

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

@@ -4,6 +4,8 @@ The default report is the tighter one: the columns you actually read, capped row
 paths. `full` restores every column and row (Markdown export is always full)."""
 from __future__ import annotations
 
+import json
+
 from rich import box
 from rich.columns import Columns
 from rich.console import Console, Group
@@ -758,6 +760,10 @@ def compare_section(result: dict) -> dict:
     lines = []
     if before.get("options_differ"):
         lines.append(f"options differ: {', '.join(before['options_differ'])}; the changes partly reflect them")
+    db = before.get("database")
+    if db:
+        lines.append(f"the vulnerability database changed between the runs ({db.get('before') or '?'} to {db.get('after') or '?'}), "
+                     "so a dependency finding can move with no change to the code")
     lines.append(f"{against}, {before.get('date') or '?'} · {_tally_words(result['tally']['before'])} → {_tally_words(result['tally']['after'])}")
     columns = [("change", {}), ("what", {"overflow": "fold", "ratio": 3})]
     # an empty section prints heading + note and drops the caption (section_block, _md_section), so when
@@ -1093,6 +1099,35 @@ def markdown(report: dict, findings: list, full: bool = False, risk: dict = None
     return "\n".join(out)
 
 
+def _envelope(out: dict) -> dict:
+    """Move what differs between two runs of the same clone into `envelope`: the blame pass's measured
+    projection, the machine-local output directory, the structure cache's hits. Everything outside
+    it is the same bytes for the same commit and options, which the CI determinism job checks."""
+    import copy
+    out = copy.deepcopy(out)
+    env = {"out_dir": out.pop("out_dir", None)}
+    age = (out.get("meta") or {}).get("age")
+    if isinstance(age, dict) and "projected_seconds" in age:
+        env["projected_seconds"] = age.pop("projected_seconds")
+    struct = out.get("structure")
+    if isinstance(struct, dict) and "cached" in struct:
+        env["structure_cached"] = struct.pop("cached")
+    # the value hashes use a key made for each run; the same value gets the same label within an export
+    labels = {}
+    if isinstance(out.get("secrets"), list):
+        out["secrets"].sort(key=lambda r: (r.get("file") or "", r.get("commit") or "", r.get("line") or 0, r.get("rule") or "", r.get("fingerprint") or ""))
+    for row in out.get("secrets") or []:
+        if row.get("value"):
+            row["value"] = labels.setdefault(row["value"], f"v{len(labels) + 1}")
+    out["envelope"] = env
+    return out
+
+
+def dumps_json(report: dict, findings: list, risk: dict = None, compare: dict = None) -> str:
+    """The --json export as text: keys sorted, the run-specific values in `envelope`."""
+    return json.dumps(_envelope(to_json(report, findings, risk=risk, compare=compare)), indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
 def to_json(report: dict, findings: list, risk: dict = None, compare: dict = None) -> dict:
     out = {**{k: v for k, v in report.items() if k != "backtest"}, "findings": findings,   # the sub-report is a report of its own
            "watch": [{k: v for k, v in r.items() if k != "function"} | {"function": r["function"]["function"] if r["function"] else None}

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/sarif.py

@@ -1,4 +1,4 @@
-"""The findings as SARIF 2.1.0, for GitHub code scanning and GitLab.
+"""The findings as SARIF 2.1.0, for GitHub code scanning and GitLab, as their SARIF documentation describes.
 
 `--json` already carries a rule id, thresholds and evidence per finding, which is most of a SARIF
 result. What the uploaders need on top: `version "2.1.0"`, `tool.driver` with `rules[]` (id,

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/signing.py

@@ -1,4 +1,5 @@
-"""Commit signing coverage, read from the commit objects, with no keyring and no network.
+"""Commit signing coverage, read from the commit objects, with no keyring and no network (the measure the
+EASE 2025 study of commit signing on GitHub reports).
 
 `%G?` depends on the local keyring: on a fresh clone nearly every signed commit comes back E, cannot
 check. The keyring-independent reading is the `gpgsig` (or `gpgsig-sha256`) header in the commit

{gitmole-0.17.0 → gitmole-0.18.0}/gitmole/watch.py

@@ -1,4 +1,6 @@
-"""The watch list: the source files most likely to be fixed next, and what to look at in each.
+"""The watch list: the source files most likely to be fixed next, and what to look at in each. Hotspots by
+revisions × lines of code, after Tornhill (Your Code as a Crime Scene); the change factors on --risk after
+Kamei et al. (TSE 2013), the coupling gaps after Zimmermann et al. (TSE 2005).
 
 Each source file that is still in the tree and changed more than once is ranked by revisions × lines
 of code, the product the Hotspots table uses: measured at six cut-offs on three repositories

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.17.0
+Version: 0.18.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
@@ -44,7 +44,7 @@ Free. Any Stack. Local. Offline. Deterministic. Fast.
 - **Free.** MIT licence, no paid tier, no account, no token. A local clone needs no credentials, and a public `owner/repo` is cloned with plain git. Your `gh` login is only used for private repositories and for `owner/*`, and only when you ask for them. The tools it runs are open source too.
 - **Any stack.** It reads what every repository has: the git log, git blame and the files themselves.
 - **Local & Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
-- **Deterministic.** No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule and the numbers it fired on. The same clone gives the same report every time. 
+- **Deterministic.** No AI at runtime. Every finding is a plain rule over counts you can recompute by hand. The JSON export carries each finding's rule, the numbers it fired on and, where a rule rests on a paper, the citation. The same commit gives the same bytes: gitmole's own CI runs it twice on every commit, compares the exports and attests the report.
 
 ## Install
 
@@ -73,12 +73,17 @@ gitmole . --markdown report.md         # the same report as a Markdown document
 gitmole . --json report.json           # every table, the watch list and the findings
 gitmole . --fail-on warning            # exit 3 if any finding is a warning or worse
 gitmole . --risk main --risk-threshold 10  # exit 3 if the files changed since main hold over 10% of the risk
+gitmole . --sarif gitmole.sarif        # the findings for GitHub code scanning or GitLab
+gitmole . --compare last.json          # what changed since an earlier --json export
+gitmole analysis-repo --no-run --hook  # a coding agent's edit hook: history's view of the files it just touched
 gitmole . --since 2y --full            # the current team, every row and column
 gitmole --clean                        # list what gitmole left behind, delete on a yes
 ```
 
 A CI job that runs `gitmole . --fail-on critical --markdown - >> "$GITHUB_STEP_SUMMARY"`
-blocks on secrets in source files and still posts the report. Every option:
+blocks on secrets in source files and still posts the report. The same
+scoring wires into Claude Code, Cursor, Gemini CLI and pre-commit as a hook
+that exits 2 over a threshold. Every option:
 [docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
 
 ## What you get
@@ -87,9 +92,9 @@ Reports on repositories you know, each at a pinned commit, published as gitmole
 
 | Repository | Commit | Commits | Lines | gitmole run |
 |---|---|---:|---:|---:|
-| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | [`540ee5b5`](https://github.com/curl/curl/commit/540ee5b560cc6e775e11317048a13cc7e355bf91) | 39,758 | 247,179 | 61 s |
-| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | [`8cbdd4a8`](https://github.com/django/django/commit/8cbdd4a814397f81adf0129288f32b615bd1f94f) | 34,933 | 431,749 | 153 s |
-| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | [`2b19aecd`](https://github.com/facebook/react/commit/2b19aecd0e9111b774fad0fad9862e50bcb5bc8a) | 21,703 | 681,078 | 138 s |
+| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | [`540ee5b5`](https://github.com/curl/curl/commit/540ee5b560cc6e775e11317048a13cc7e355bf91) | 39,758 | 247,179 | 57 s |
+| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | [`8cbdd4a8`](https://github.com/django/django/commit/8cbdd4a814397f81adf0129288f32b615bd1f94f) | 34,933 | 431,749 | 132 s |
+| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | [`2b19aecd`](https://github.com/facebook/react/commit/2b19aecd0e9111b774fad0fad9862e50bcb5bc8a) | 21,703 | 681,078 | 151 s |
 
 Run times are one `gitmole CLONE` with every default step, on a MacBook Pro (M4, 16 GB).
 
@@ -110,6 +115,7 @@ you about a clone.
 | Which blocks of code appear more than once | [jscpd](https://github.com/kucherenko/jscpd) | brew |
 | Have secrets ever been committed | [betterleaks](https://github.com/betterleaks/betterleaks) | brew |
 | Do the dependencies have known vulnerabilities | [osv-scanner](https://github.com/google/osv-scanner), offline against a local copy of the OSV database | brew, plus a one-time database download |
+| How deeply nested is the code, what did the authors flag, what imports what | [tree-sitter](https://github.com/tree-sitter/py-tree-sitter) grammars for eleven languages | pip, opt-in with `gitmole[structure]` |
 
 Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
 
@@ -121,6 +127,7 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 - [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django and react at pinned commits, regenerated by `bin/render-examples`.
 - [Validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md): the watch list against other ways of ranking the same files at six cut-offs on three repositories.
 - [Why these tools](https://github.com/antvinni/gitmole/blob/main/docs/tools.md): the rationale, what was left out, licences.
+- [References](https://github.com/antvinni/gitmole/blob/main/docs/references.md): the research and tools gitmole's rules are built on.
 - [Development](https://github.com/antvinni/gitmole/blob/main/docs/development.md): setup, tests, releases, code layout.
 - [Contributing](https://github.com/antvinni/gitmole/blob/main/CONTRIBUTING.md): bugs, ideas, pull requests, security reports.
 

{gitmole-0.17.0 → gitmole-0.18.0}/tests/test_compare.py

@@ -36,7 +36,7 @@ class Compare(unittest.TestCase):
                          [("Repo health", "warning", "warning"), ("Bug magnets", "info", "warning")], "the after copy, with the severity it had")
         self.assertEqual((out["watch_entered"], out["watch_left"]), (["c.py"], ["b.py"]))
         self.assertEqual(out["tally"], {"before": {"critical": 0, "warning": 2, "info": 2}, "after": {"critical": 0, "warning": 2, "info": 1}})
-        self.assertEqual(out["before"], {"commit": "540ee5b560cc6e775e11317048a13cc7e355bf91", "date": "2026-09-10", "options_differ": ["ignore_data"]})
+        self.assertEqual(out["before"], {"commit": "540ee5b560cc6e775e11317048a13cc7e355bf91", "date": "2026-09-10", "options_differ": ["ignore_data"], "database": None})
 
     def test_compare_skips_watch_rows_without_a_file(self):
         self.before["watch"] = [{"file": "a.py"}, {"note": "no file field"}, {"file": "b.py"}]
@@ -46,7 +46,7 @@ class Compare(unittest.TestCase):
     def test_an_export_without_a_manifest_compares_findings_only(self):
         self.before["meta"].pop("run")
         out = compare.compare(self.before, self.after, self.after_findings)
-        self.assertEqual(out["before"], {"commit": None, "date": "2026-09-10", "options_differ": []})
+        self.assertEqual(out["before"], {"commit": None, "date": "2026-09-10", "options_differ": [], "database": None})
 
     def test_is_export(self):
         self.assertTrue(compare.is_export(self.before))

{gitmole-0.17.0 → gitmole-0.18.0}/tests/test_deps.py

@@ -101,6 +101,20 @@ class DatabaseDate(unittest.TestCase):
             os.utime(path, (1_600_000_000, 1_600_000_000))
             self.assertEqual(deps.database_date(d), "2020-09-13")
 
+    def test_the_digest_names_the_snapshot_and_changes_when_it_does(self):
+        with tempfile.TemporaryDirectory() as d:
+            self.assertIsNone(deps.database_digest(d))
+            os.makedirs(os.path.join(d, "osv-scalibr", "npm"))
+            path = os.path.join(d, "osv-scalibr", "npm", "all.zip")
+            with open(path, "w") as fh:
+                fh.write("a")
+            os.utime(path, (1_600_000_000, 1_600_000_000))
+            first = deps.database_digest(d)
+            self.assertRegex(first, r"^[0-9a-f]{16}$")
+            self.assertEqual(deps.database_digest(d), first)
+            os.utime(path, (1_600_000_100, 1_600_000_100))
+            self.assertNotEqual(deps.database_digest(d), first, "a refreshed copy is another snapshot")
+
     def test_the_explicit_variable_wins_over_the_platform_cache(self):
         from unittest.mock import patch
         with patch.dict(os.environ, {"OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY": "/x/y"}):

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

@@ -271,7 +271,7 @@ class MinorContributors(unittest.TestCase):
         self.assertNotIn("src/f10.py", f["detail"], "outside the top ten")
         self.assertEqual(f["advice"], "Have Ann, who wrote most of src/f0.py, review changes to it from anyone else; "
                                       "Bird et al. found the count of minor contributors the strongest ownership predictor of defects.")
-        self.assertEqual(f["rule"], {"id": "minor_contributors", "min_minor": 5, "warn_at": 10, "minor_share": 0.05, "top_n": 10})
+        self.assertEqual(f["rule"], {"id": "minor_contributors", "min_minor": 5, "warn_at": 10, "minor_share": 0.05, "top_n": 10, "ref": "Bird et al., FSE 2011"})
         self.assertEqual(f["evidence"]["files"][0], {"file": "src/f0.py", "minor": 12, "authors": 15, "owner": "Ann"})
 
     def test_info_below_ten_and_nothing_below_five(self):
@@ -302,7 +302,8 @@ class TangledCommits(unittest.TestCase):
                       "t1 (34 files, 9 directories, Fix the parser, add a cache and rename the helpers); t2 (12 files, 4 directories, Add x; fix y). "
                       "A fix among them credits every file it touched, so 3 fixes over the repository's 99th percentile of lines changed are already left out of the fix counts.", f["detail"])
         self.assertEqual(f["advice"], "Split a change that does several things before merge; the fix history stays readable and the coupling stays real.")
-        self.assertEqual(f["rule"], {"id": "tangled_commits", "min_files": 10, "min_dirs": 4, "min_clauses": 2, "min_share": 0.02, "min_count": 5})
+        self.assertEqual(f["rule"], {"id": "tangled_commits", "min_files": 10, "min_dirs": 4, "min_clauses": 2, "min_share": 0.02, "min_count": 5,
+                                     "ref": "Herzig and Zeller, MSR 2013"})
         self.assertEqual(f["evidence"]["count"], 12)
         self.assertEqual(f["evidence"]["oversized_fixes"], 3)
 
@@ -1247,3 +1248,23 @@ class AgentSurface(unittest.TestCase):
         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")
+
+
+class References(unittest.TestCase):
+    def test_every_rule_resting_on_a_paper_names_it_where_the_numbers_are(self):
+        expected = {"minor_contributors": "Bird et al., FSE 2011", "tangled_commits": "Herzig and Zeller, MSR 2013",
+                    "brain_methods": "Lanza and Marinescu, 2006", "tight_coupling": "Gall, Hajek and Jazayeri, ICSM 1998",
+                    "hotspot_dominance": "Tornhill, Your Code as a Crime Scene, 2024", "trojan_source": "Boucher and Anderson, USENIX Security 2023",
+                    "debt_in_hotspots": "Maldonado and Shihab, MTD 2015", "hidden_coupling": "Ajienka and Capiluppi, JSS 2017",
+                    "unreferenced_files": "Romano et al., TSE 2020"}
+        for rule, ref in expected.items():
+            self.assertEqual(findings.REFS[rule], ref, rule)
+        import os
+        page = open(os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "docs", "references.md")).read()
+        for ref in expected.values():
+            surname = ref.split(",")[0].split(" and ")[0].split(" et al.")[0]
+            self.assertIn(surname, page, f"{ref} is on the references page")
+
+    def test_the_ref_reaches_the_rule_dict(self):
+        found = findings.tight_coupling(report(coupling=[{"entity": "a.py", "coupled": "b.py", "degree": 90, "average-revs": 10}]))
+        self.assertEqual(found[0]["rule"]["ref"], "Gall, Hajek and Jazayeri, ICSM 1998")

{gitmole-0.17.0 → gitmole-0.18.0}/tests/test_golden.py

@@ -96,5 +96,25 @@ class Golden(unittest.TestCase):
             self.fail("report differs from tests/golden/report.txt (UPDATE_GOLDEN=1 to accept):\n" + diff)
 
 
+    def test_two_runs_of_the_same_commit_export_the_same_json_outside_the_envelope(self):
+        import json
+        with tempfile.TemporaryDirectory() as work:
+            repo = os.path.join(work, "demo")
+            os.makedirs(repo)
+            build_repo(repo)
+            exports = []
+            for i in range(2):
+                out = os.path.join(work, "out")   # the same output directory, as a CI job reruns into
+                c = Console(file=io.StringIO(), width=100, record=True, force_terminal=False, color_system=None)
+                target = os.path.join(work, f"report{i}.json")
+                with patch.dict(os.environ, HERMETIC_ENV):
+                    self.assertEqual(cli.main([repo, "--out", out, "--json", target], console=c), 0)
+                with open(target) as fh:
+                    data = json.load(fh)
+                del data["envelope"]
+                exports.append(json.dumps(data, sort_keys=True))
+        self.assertEqual(exports[0], exports[1], "same commit, same options, same bytes: the claim no inference-based reviewer can make")
+
+
 if __name__ == "__main__":
     unittest.main()

{gitmole-0.17.0 → gitmole-0.18.0}/tests/test_leaks.py

@@ -297,6 +297,7 @@ fi
         [row] = rows
         self.assertRegex(row["File"], r"^\(unreachable blob [0-9a-f]{12}\)$")
         self.assertEqual(row["Commit"], "")
+        self.assertRegex(row["Fingerprint"], r"^unreachable:[0-9a-f]{40}:generic-api-key:1$", "no scratch path, the same in every run")
         self.assertNotIn(FAKE, json.dumps(rows))
         self.assertEqual((record["blobs"], record["scanned"], record["findings"]), (2, 2, 1))
         self.assertEqual(leftovers, ["secrets.json", "unreachable.json"], "the blobs written for the scan are gone")

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

@@ -167,8 +167,8 @@ class ParseFunctions(unittest.TestCase):
         rows = load.parse_functions('136,47,926,1,270,"@316-585@completions.go","completions.go",""," c * Command",316,585,"Run: func(c *Command) {",""\n'
                                     '4,2,36,0,4,"(anonymous)@1-4@routes.js","routes.js","(anonymous)","(anonymous)",1,4,"app.post(""/api/x"", async (req, res) => {",""\n'
                                     '4,2,14,2,4,"tracked@1-4@app.py","app.py","tracked","tracked( a , b )",1,4,"",""\n')
-        self.assertEqual([(r["function"], r["anonymous"]) for r in rows],
-                         [("Run: func(c *Command) {", True), ('app.post("/api/x", async (req, res) => {', True), ("tracked", False)])
+        self.assertEqual(sorted((r["function"], r["anonymous"]) for r in rows),
+                         sorted([("Run: func(c *Command) {", True), ('app.post("/api/x", async (req, res) => {', True), ("tracked", False)]))
 
     def test_a_suspect_span_carries_its_reason(self):
         rows = load.parse_functions('9,1,21,1,9,"tpl@1-9@tpl.js","tpl.js","tpl","tpl ( name )",1,9,"","opens a block at line 8 no deeper than its own start"\n')
@@ -177,7 +177,8 @@ class ParseFunctions(unittest.TestCase):
     def test_a_row_cut_short_by_a_killed_step_does_not_abort_the_report(self):
         rows = load.parse_functions(self.CSV + '5,3,40,1,5,"g@1-5@a.py","a.py","g","g( )",1,\n')
         self.assertEqual(len(rows), 3)
-        self.assertEqual((rows[2]["function"], rows[2]["end"]), ("g", 0))
+        g = next(r for r in rows if r["function"] == "g")
+        self.assertEqual(g["end"], 0)
 
 
 class ParseDuplicates(unittest.TestCase):
@@ -372,6 +373,12 @@ class LoadReport(unittest.TestCase):
         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_function_rows_come_back_in_file_and_line_order_whatever_the_step_wrote(self):
+        text = ('3,2,20,1,3,"g@9-11@b.py","b.py","g","g( x )",9,11\n'
+                '3,2,20,1,3,"f@1-3@b.py","b.py","f","f( x )",1,3\n'
+                '3,2,20,1,3,"h@5-7@a.py","a.py","h","h( x )",5,7\n')
+        self.assertEqual([(f["file"], f["function"]) for f in load.parse_functions(text)], [("a.py", "h"), ("b.py", "f"), ("b.py", "g")])
+
     def test_no_signing_file_is_an_empty_record(self):
         import os, tempfile
         with tempfile.TemporaryDirectory() as out:

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

@@ -1,3 +1,4 @@
+import json
 import io
 import unittest
 
@@ -283,6 +284,38 @@ class Report(unittest.TestCase):
         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_comparison_says_when_the_vulnerability_database_changed(self):
+        result = {"new": [], "resolved": [], "persisting": [], "watch_entered": [], "watch_left": [],
+                  "tally": {"before": {"critical": 0, "warning": 0, "info": 0}, "after": {"critical": 0, "warning": 0, "info": 0}},
+                  "before": {"commit": "abc12345", "date": "2026-09-01", "options_differ": [], "database": {"before": "2026-09-01", "after": "2026-09-17"}}}
+        sec = render.compare_section(result)
+        text = (sec.get("caption") or "") + (sec.get("note") or "")
+        self.assertIn("the vulnerability database changed between the runs (2026-09-01 to 2026-09-17), so a dependency finding can move with no change to the code", text)
+
+    def test_the_json_is_the_same_bytes_for_the_same_clone_whatever_the_run(self):
+        import copy
+        a = sample_report()
+        a["secrets"] = [{"rule": "k", "file": "b.py", "commit": "c2", "line": 3, "fingerprint": "f2", "value": "9f00aa11bb22", "placeholder": False},
+                        {"rule": "k", "file": "a.py", "commit": "c1", "line": 1, "fingerprint": "f1", "value": "12ab34cd56ef", "placeholder": False},
+                        {"rule": "k", "file": "c.py", "commit": "c3", "line": 2, "fingerprint": "f3", "value": "12ab34cd56ef", "placeholder": False}]
+        a["meta"]["age"] = {"status": "run", "projected_seconds": 3.14159, "files": 10}
+        a["structure"] = {"status": "run", "cached": 0, "files": {}}
+        b = copy.deepcopy(a)
+        for row, other in zip(b["secrets"], ("0000ffff1111", "aaaabbbbcccc", "aaaabbbbcccc")):
+            row["value"] = other                     # another run: another random key, the same grouping
+        b["secrets"].reverse()                       # and betterleaks free to report in another order
+        b["meta"]["age"]["projected_seconds"] = 2.71828
+        b["structure"]["cached"] = 40
+        b["out_dir"] = "/somewhere/else"
+        first, second = json.loads(render.dumps_json(a, [])), json.loads(render.dumps_json(b, []))
+        self.assertNotEqual(first["envelope"], second["envelope"], "timings, the output path and cache hits vary, and live in the envelope")
+        del first["envelope"], second["envelope"]
+        self.assertEqual(json.dumps(first, sort_keys=True), json.dumps(second, sort_keys=True))
+        self.assertEqual([r["value"] for r in first["secrets"]], ["v1", "v2", "v1"], "the same value, the same label, by the rows' sorted order")
+        text = render.dumps_json(a, [])
+        self.assertTrue(text.endswith("}\n"))
+        self.assertEqual(text, render.dumps_json(a, []))
+
     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}