gitmole 0.7.2__tar.gz → 0.8.0__tar.gz

{gitmole-0.7.2 → gitmole-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.7.2
+Version: 0.8.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
@@ -31,7 +31,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 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 and the numbers it fired on. The same clone gives the same report every time. 
 - **Fast.** A 4,400-commit repository takes under thirty seconds.
 
 ## Install
@@ -60,7 +60,7 @@ gitmole 'owner/*'                      # every non-archived repo of a user or or
 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 5   # exit 3 if the files changed since main are too risky
+gitmole . --risk main --risk-threshold 10  # exit 3 if the files changed since main hold over 10% of the risk
 gitmole . --since 2y --full            # the current team, every row and column
 gitmole --clean                        # list what gitmole left behind, delete on a yes
 ```
@@ -71,47 +71,48 @@ blocks on secrets in source files and still posts the report. Every option:
 
 ## What you get
 
-The opening of the report for [react](https://github.com/facebook/react), 35,263 commits
+The opening of the report for [react](https://github.com/facebook/react), 21,703 commits
 since 2013, at a pinned commit:
 
 ```text
 ╭─ react ──────────────────────────────────────────────────────────────────────────────────────────╮
-│ 35263 commits  ·  2013-05-28 → 2026-09-16  ·  1880 identities  ·  branch main                    │
+│ 21703 commits  ·  2013-05-28 → 2026-09-16  ·  1843 identities  ·  branch main                    │
 │ 681,078 lines in 4781 files  ·  JavaScript, TypeScript, Rust, CSS                                │
-│ most commits on Wed at 16:00  ·  13% of commits are fixes  ·  1% of commits are reverts  ·  19%  │
+│ most commits on Wed at 15:00  ·  14% of commits are fixes  ·  1% of commits are reverts  ·  19%  │
 │ of surviving code from 2026                                                                      │
-│ 1 critical, 6 warnings, 8 notes                                                                  │
+│ 1 critical, 6 warnings, 9 notes                                                                  │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 
 ◎ Watch list
   file                                              why                                             
   ──────────────────────────────────────────────────────────────────────────────────────────────────
-  compiler/packages/babel-plugin-react-compiler/s   changed 331 times · fixed twice in six months · 
-  rc/Inference/InferMutationAliasingEffects.ts      Joe Savona wrote 98% of it ·                    
-                                                    findNonMutatedDestructureSpreads() complexity 39
-  packages/react-server/src/ReactFlightServer.js    changed 377 times · fixed once in six months ·  
-                                                    renderModelDestructive() complexity 544         
-  packages/shared/forks/ReactFeatureFlags.www.js    changed 583 times · fixed once in six months ·  
-                                                    changes with                                    
-                                                    packages/shared/forks/ReactFeatureFlags.test-ren
-                                                    derer.www.js (77%) and 5 others                 
-  packages/shared/ReactFeatureFlags.js              changed 575 times · fixed 6 times · changes with
-                                                    packages/shared/forks/ReactFeatureFlags.test-ren
-                                                    derer.js (80%) and 4 others                     
-  packages/react-reconciler/src/ReactFiberWorkLoo   changed 342 times · fixed 4 times in six months 
+  packages/react-server/src/ReactFlightServer.js    changed 319 times · fixed once in six months ·  
+                                                    visitAsyncNodeImpl() complexity 46              
+  packages/react-server/src/ReactFizzServer.js      changed 297 times · fixed twice in six months · 
+                                                    retryNode() complexity 41                       
+  packages/react-reconciler/src/ReactFiberWorkLoo   changed 312 times · fixed 4 times in six months 
   p.js                                              · flushSpawnedWork() complexity 48              
-  ranked by churn × recent fixes × complexity × single ownership                                    
-  6 months ago this list would have named 6 of the 211 files fixed since (a random 15 of the 1979   
-  files that had changed more than once would name 0.3)                                             
+  packages/react-reconciler/src/ReactFiberCommitW   changed 284 times · fixed 28 times ·            
+  ork.js                                            commitLayoutEffectOnFiber() complexity 72       
+  packages/react-reconciler/src/ReactFiberBeginWo   changed 361 times · fixed once in six months ·  
+  rk.js                                             beginWork() complexity 52                       
+  ranked by revisions × lines of code; the reasons say what else counts against each file           
+  6 months ago this list would have named 11 of the 46 files fixed since (a random 15 of the 1802   
+  files that had changed more than once would name 0.3; the 15 most changed would name 7)           
 ```
 
-The watch list is the point: the five files where the next bug is most
-likely, the reasons in words, and a backtest that says how the same list,
-drawn six months earlier, would have done against the fixes that followed.
-Between the header and that list the full report puts its findings, 15 for
-react (1 critical, 6 warnings, 8 notes); below it, tables for people, the
-knowledge map, the timeline, hotspots with their complexity trend, change
-coupling, complex functions and repo health. Every section is explained in
+The watch list is the point: the five source files most likely to need a fix
+next, the reasons in words, and a backtest that says how the same list, drawn
+six months earlier, would have done against the fixes that followed. The list
+ranks by revisions × lines of code: measured at six cut-offs on three
+repositories
+([validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md)),
+that named more of the files fixed next than churn alone, size alone or a
+weighted product of fixes, complexity and ownership. Between the header and
+that list the full report puts its findings, 16 for react (1 critical, 6
+warnings, 9 notes); below it, tables for people, the knowledge map, the
+timeline, hotspots with their complexity trend, change coupling, complex
+functions and repo health. Every section is explained in
 [docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
 
 Reports on repositories you know, each at a pinned commit with a fixed
@@ -120,14 +121,9 @@ come from git-sizer over the whole clone, so a fresh clone can differ there:
 
 | Repository | Commits | Lines | Watch list backtest |
 |---|---:|---:|---|
-| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | 39,894 | 247,179 | named 15 of the 239 files fixed in the next six months; a random pick would name 5.0 |
-| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | 52,832 | 431,749 | named 13 of the 213 files fixed in the next six months; a random pick would name 2.8 |
-| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | 35,263 | 681,078 | named 6 of the 211 files fixed in the next six months; a random pick would name 0.3 |
-| [kubernetes](https://github.com/antvinni/gitmole/blob/main/docs/examples/kubernetes.md) | 161,803 | 4,180,715 | named 7 of the 338 files fixed in the next six months; a random pick would name 0.4 |
-
-kubernetes's code-age step was skipped on gitmole's default time budget and
-its report says so; the duplicates step was skipped on the memory budget too
-and produced no section.
+| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | 39,758 | 247,179 | named 15 of the 238 files fixed in the next six months; a random pick would name 4.9, the 15 most changed 15 |
+| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | 34,933 | 431,749 | named 15 of the 213 files fixed in the next six months; a random pick would name 3.1, the 15 most changed 13 |
+| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | 21,703 | 681,078 | named 11 of the 46 files fixed in the next six months; a random pick would name 0.3, the 15 most changed 7 |
 
 ## The tool set
 
@@ -154,7 +150,8 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 - [Install](https://github.com/antvinni/gitmole/blob/main/docs/install.md): macOS, Linux, pipx, the check, pinned releases.
 - [Command line](https://github.com/antvinni/gitmole/blob/main/docs/cli.md): every option, portfolio mode, exports and CI gates, big repositories.
 - [The report and the output files](https://github.com/antvinni/gitmole/blob/main/docs/output.md): what each section and each file means.
-- [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django, react and kubernetes at pinned commits, regenerated by `bin/render-examples`.
+- [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.
 - [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.
@@ -166,9 +163,10 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
   against a local copy of its database that you download once, and gitmole
   never downloads it for you.
 - Remote targets are cloned into a fresh temp directory that is removed when
-  the run ends. Local clones are only read, but the log export and the
-  secrets scan touch all branches. `gitmole --clean` lists every directory
-  gitmole created and deletes them after a y/N question.
+  the run ends. Local clones are only read. The secrets scan reads every
+  branch; everything else describes the branch that is checked out.
+  `gitmole --clean` lists every directory gitmole created and deletes them
+  after a y/N question.
 - Secret values never reach the output directory. betterleaks reports to
   gitmole in memory, and gitmole stores a short keyed hash in place of the
   value, the matched text and the commit message. The key is random, made

{gitmole-0.7.2 → gitmole-0.8.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 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 and the numbers it fired on. The same clone gives the same report every time. 
 - **Fast.** A 4,400-commit repository takes under thirty seconds.
 
 ## Install
@@ -40,7 +40,7 @@ gitmole 'owner/*'                      # every non-archived repo of a user or or
 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 5   # exit 3 if the files changed since main are too risky
+gitmole . --risk main --risk-threshold 10  # exit 3 if the files changed since main hold over 10% of the risk
 gitmole . --since 2y --full            # the current team, every row and column
 gitmole --clean                        # list what gitmole left behind, delete on a yes
 ```
@@ -51,47 +51,48 @@ blocks on secrets in source files and still posts the report. Every option:
 
 ## What you get
 
-The opening of the report for [react](https://github.com/facebook/react), 35,263 commits
+The opening of the report for [react](https://github.com/facebook/react), 21,703 commits
 since 2013, at a pinned commit:
 
 ```text
 ╭─ react ──────────────────────────────────────────────────────────────────────────────────────────╮
-│ 35263 commits  ·  2013-05-28 → 2026-09-16  ·  1880 identities  ·  branch main                    │
+│ 21703 commits  ·  2013-05-28 → 2026-09-16  ·  1843 identities  ·  branch main                    │
 │ 681,078 lines in 4781 files  ·  JavaScript, TypeScript, Rust, CSS                                │
-│ most commits on Wed at 16:00  ·  13% of commits are fixes  ·  1% of commits are reverts  ·  19%  │
+│ most commits on Wed at 15:00  ·  14% of commits are fixes  ·  1% of commits are reverts  ·  19%  │
 │ of surviving code from 2026                                                                      │
-│ 1 critical, 6 warnings, 8 notes                                                                  │
+│ 1 critical, 6 warnings, 9 notes                                                                  │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 
 ◎ Watch list
   file                                              why                                             
   ──────────────────────────────────────────────────────────────────────────────────────────────────
-  compiler/packages/babel-plugin-react-compiler/s   changed 331 times · fixed twice in six months · 
-  rc/Inference/InferMutationAliasingEffects.ts      Joe Savona wrote 98% of it ·                    
-                                                    findNonMutatedDestructureSpreads() complexity 39
-  packages/react-server/src/ReactFlightServer.js    changed 377 times · fixed once in six months ·  
-                                                    renderModelDestructive() complexity 544         
-  packages/shared/forks/ReactFeatureFlags.www.js    changed 583 times · fixed once in six months ·  
-                                                    changes with                                    
-                                                    packages/shared/forks/ReactFeatureFlags.test-ren
-                                                    derer.www.js (77%) and 5 others                 
-  packages/shared/ReactFeatureFlags.js              changed 575 times · fixed 6 times · changes with
-                                                    packages/shared/forks/ReactFeatureFlags.test-ren
-                                                    derer.js (80%) and 4 others                     
-  packages/react-reconciler/src/ReactFiberWorkLoo   changed 342 times · fixed 4 times in six months 
+  packages/react-server/src/ReactFlightServer.js    changed 319 times · fixed once in six months ·  
+                                                    visitAsyncNodeImpl() complexity 46              
+  packages/react-server/src/ReactFizzServer.js      changed 297 times · fixed twice in six months · 
+                                                    retryNode() complexity 41                       
+  packages/react-reconciler/src/ReactFiberWorkLoo   changed 312 times · fixed 4 times in six months 
   p.js                                              · flushSpawnedWork() complexity 48              
-  ranked by churn × recent fixes × complexity × single ownership                                    
-  6 months ago this list would have named 6 of the 211 files fixed since (a random 15 of the 1979   
-  files that had changed more than once would name 0.3)                                             
+  packages/react-reconciler/src/ReactFiberCommitW   changed 284 times · fixed 28 times ·            
+  ork.js                                            commitLayoutEffectOnFiber() complexity 72       
+  packages/react-reconciler/src/ReactFiberBeginWo   changed 361 times · fixed once in six months ·  
+  rk.js                                             beginWork() complexity 52                       
+  ranked by revisions × lines of code; the reasons say what else counts against each file           
+  6 months ago this list would have named 11 of the 46 files fixed since (a random 15 of the 1802   
+  files that had changed more than once would name 0.3; the 15 most changed would name 7)           
 ```
 
-The watch list is the point: the five files where the next bug is most
-likely, the reasons in words, and a backtest that says how the same list,
-drawn six months earlier, would have done against the fixes that followed.
-Between the header and that list the full report puts its findings, 15 for
-react (1 critical, 6 warnings, 8 notes); below it, tables for people, the
-knowledge map, the timeline, hotspots with their complexity trend, change
-coupling, complex functions and repo health. Every section is explained in
+The watch list is the point: the five source files most likely to need a fix
+next, the reasons in words, and a backtest that says how the same list, drawn
+six months earlier, would have done against the fixes that followed. The list
+ranks by revisions × lines of code: measured at six cut-offs on three
+repositories
+([validation](https://github.com/antvinni/gitmole/blob/main/docs/validation.md)),
+that named more of the files fixed next than churn alone, size alone or a
+weighted product of fixes, complexity and ownership. Between the header and
+that list the full report puts its findings, 16 for react (1 critical, 6
+warnings, 9 notes); below it, tables for people, the knowledge map, the
+timeline, hotspots with their complexity trend, change coupling, complex
+functions and repo health. Every section is explained in
 [docs/output.md](https://github.com/antvinni/gitmole/blob/main/docs/output.md).
 
 Reports on repositories you know, each at a pinned commit with a fixed
@@ -100,14 +101,9 @@ come from git-sizer over the whole clone, so a fresh clone can differ there:
 
 | Repository | Commits | Lines | Watch list backtest |
 |---|---:|---:|---|
-| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | 39,894 | 247,179 | named 15 of the 239 files fixed in the next six months; a random pick would name 5.0 |
-| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | 52,832 | 431,749 | named 13 of the 213 files fixed in the next six months; a random pick would name 2.8 |
-| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | 35,263 | 681,078 | named 6 of the 211 files fixed in the next six months; a random pick would name 0.3 |
-| [kubernetes](https://github.com/antvinni/gitmole/blob/main/docs/examples/kubernetes.md) | 161,803 | 4,180,715 | named 7 of the 338 files fixed in the next six months; a random pick would name 0.4 |
-
-kubernetes's code-age step was skipped on gitmole's default time budget and
-its report says so; the duplicates step was skipped on the memory budget too
-and produced no section.
+| [curl](https://github.com/antvinni/gitmole/blob/main/docs/examples/curl.md) | 39,758 | 247,179 | named 15 of the 238 files fixed in the next six months; a random pick would name 4.9, the 15 most changed 15 |
+| [django](https://github.com/antvinni/gitmole/blob/main/docs/examples/django.md) | 34,933 | 431,749 | named 15 of the 213 files fixed in the next six months; a random pick would name 3.1, the 15 most changed 13 |
+| [react](https://github.com/antvinni/gitmole/blob/main/docs/examples/react.md) | 21,703 | 681,078 | named 11 of the 46 files fixed in the next six months; a random pick would name 0.3, the 15 most changed 7 |
 
 ## The tool set
 
@@ -134,7 +130,8 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 - [Install](https://github.com/antvinni/gitmole/blob/main/docs/install.md): macOS, Linux, pipx, the check, pinned releases.
 - [Command line](https://github.com/antvinni/gitmole/blob/main/docs/cli.md): every option, portfolio mode, exports and CI gates, big repositories.
 - [The report and the output files](https://github.com/antvinni/gitmole/blob/main/docs/output.md): what each section and each file means.
-- [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django, react and kubernetes at pinned commits, regenerated by `bin/render-examples`.
+- [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.
 - [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.
@@ -146,9 +143,10 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
   against a local copy of its database that you download once, and gitmole
   never downloads it for you.
 - Remote targets are cloned into a fresh temp directory that is removed when
-  the run ends. Local clones are only read, but the log export and the
-  secrets scan touch all branches. `gitmole --clean` lists every directory
-  gitmole created and deletes them after a y/N question.
+  the run ends. Local clones are only read. The secrets scan reads every
+  branch; everything else describes the branch that is checked out.
+  `gitmole --clean` lists every directory gitmole created and deletes them
+  after a y/N question.
 - Secret values never reach the output directory. betterleaks reports to
   gitmole in memory, and gitmole stores a short keyed hash in place of the
   value, the matched text and the commit message. The key is random, made

{gitmole-0.7.2 → gitmole-0.8.0}/gitmole/__init__.py

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

{gitmole-0.7.2 → gitmole-0.8.0}/gitmole/cli.py

@@ -42,8 +42,8 @@ def parse_args(argv):
     p.add_argument("--json", metavar="PATH", help="write the report and findings as JSON to PATH, or - for stdout")
     p.add_argument("--markdown", metavar="PATH", help="write the report as Markdown to PATH, or - for stdout")
     p.add_argument("--fail-on", choices=findings.SEVERITIES, help="exit 3 if any finding is at this severity or worse")
-    p.add_argument("--risk", metavar="BASE", help="score the files changed since BASE (merge base with HEAD) with the watch list's score; needs a local path")
-    p.add_argument("--risk-threshold", type=float, metavar="N", help="with --risk: exit 3 when the change-risk total exceeds N")
+    p.add_argument("--risk", metavar="BASE", help="score the files changed since BASE (merge base with HEAD) by their share of the repository's revisions × lines of code; needs a local path")
+    p.add_argument("--risk-threshold", type=float, metavar="N", help="with --risk: exit 3 when the changed files hold more than N percent of the repository's revisions × lines of code")
     p.add_argument("--version", action="version", version=f"gitmole {__version__}")
     return p.parse_args(argv)
 
@@ -328,7 +328,7 @@ def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, p
 
 
 def _record_statuses(meta, results, age_ok: bool, plots_ok: bool, lizard_ok: bool, cut, duplicates_ok: bool = True) -> None:
-    """Turn each planned step's exit code into its final status: run, timeout or failed."""
+    """Turn each step's exit code into its final status: run, skipped, timeout or failed."""
     def status(step, default="run"):
         rc = results.get(step, 0)
         return default if rc == 0 else ("timeout" if rc == "timeout" else "failed")
@@ -344,6 +344,8 @@ def _record_statuses(meta, results, age_ok: bool, plots_ok: bool, lizard_ok: boo
         meta["trend"]["status"] = status("trend")
     if cut and "backtest" in results:
         meta["backtest"]["status"] = status("backtest")
+    # every step, not only the optional ones above: a killed scc is otherwise a report of "0 lines" with no reason
+    meta["steps"] = {name: "run" if rc == 0 else (rc if isinstance(rc, str) else "failed") for name, rc in results.items()}
 
 
 def _analyse(repo_dir: str, out_dir: str, args, ui: Console, planner, estimator) -> None:
@@ -411,7 +413,11 @@ def _portfolio(owner: str, args, console: Console, ui: Console, planner, estimat
             except NoCommits as e:
                 ui.print(f"[yellow]{name}:[/yellow] {e}; skipped")
                 continue
-            report = load.load_report(out_dir)
+            try:
+                report = load.load_report(out_dir)
+            except load.Unreadable as e:
+                ui.print(f"[yellow]{name}:[/yellow] {e}; skipped", soft_wrap=True)
+                continue
             reports.append((name, report, findings.evaluate(report)))
     finally:
         shutil.rmtree(parent, ignore_errors=True)   # the temp clones; nothing reads them after the run
@@ -484,7 +490,11 @@ def _render(out_dir: str, console: Console, ui: Console, args, err: Console) ->
 
     from . import render
 
-    report = load.load_report(out_dir)
+    try:
+        report = load.load_report(out_dir)
+    except load.Unreadable as e:
+        err.print(f"[red]{e}[/red]", soft_wrap=True)
+        return 2
     found = findings.evaluate(report)
     risk = None
     if args.risk:

gitmole-0.8.0/gitmole/evaluate.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""How the watch list would have done at several cut-off dates, next to the factor products it
+replaced and the simpler baselines.
+
+A development tool, not a pipeline step: `python -m gitmole.evaluate REPO OUT_DIR [--windows 6]
+[--horizon 6] [--top 15]`, where OUT_DIR is a finished gitmole output directory for REPO (its log.txt
+and meta.json are read). For each cut-off T, counted back from the last commit in steps of `horizon`
+months, the change analysis is rebuilt from the commits before T, scc measures the tree at T, every
+variant names its `top` files, and the source files a fix commit touched in [T, T + horizon) are the
+outcome. A fix is a commit whose subject says so (maat.is_fix): a proxy, not a bug tracker, and the
+table is only as good as the repository's commit subjects. Prints Markdown: one row per variant, one
+column per cut-off, and the total; then how many commits `--all` adds to HEAD's."""
+from __future__ import annotations
+
+import argparse
+import calendar
+import datetime as dt
+import os
+import subprocess
+import sys
+
+from . import backtest, filetypes, identity, load, maat, trend, watch
+
+
+def cutoffs(last_date: str, windows: int, horizon: int) -> list:
+    """The cut-off dates, oldest first: the last commit's date less one, two, ... horizons."""
+    return sorted(maat.months_before(last_date, horizon * k) for k in range(1, windows + 1))
+
+
+def months_after(date: str, months: int) -> str:
+    """The ISO date `months` whole months after `date`, day clamped to the month's length."""
+    d = dt.date.fromisoformat(date)
+    years, month = divmod(d.month - 1 + months, 12)
+    y, m = d.year + years, month + 1
+    return dt.date(y, m, min(d.day, calendar.monthrange(y, m)[1])).isoformat()
+
+
+def fixed_between(commits: list, start: str, end: str) -> set:
+    """Source files a fix commit touched on or after `start` and before `end`. Test files change with every fix."""
+    return {p for c in maat.in_window(commits, start, end) if maat.is_fix(c.get("subject", ""))
+            for p, _, _ in c["files"] if not filetypes.is_test_path(p)}
+
+
+def report_at(commits: list, t: str, size: dict, meta: dict) -> dict:
+    """The report watch.risks reads, from the commits before `t` and scc's listing of the tree at `t`.
+    No coupling and no functions: neither enters the score, and the pipeline's own backtest has no functions either."""
+    past = maat.in_window(commits, until=t)
+    bots = {b["name"] for b in meta.get("bots") or []}
+    ownership = [r for r in maat.entity_ownership(past) if r["author"] not in bots and not identity.is_bot(r["author"])]
+    return {"meta": {"now": t, "generated": meta.get("generated") or []}, "size": size, "revisions": maat.revisions(past),
+            "plumbing": maat.plumbing(past), "authors": maat.authors(past), "ownership": ownership,
+            "fixes": maat.fixes(past, now=t), "coupling": [], "functions": []}
+
+
+def variants(report: dict) -> dict:
+    """variant -> file names, best first, every one drawn from the pool the watch list draws from."""
+    rows = watch.risks(report)
+    out = {"watch list (hotspot)": [r["file"] for r in rows],
+           "factor product (max-scaled)": [r["file"] for r in watch.risks(report, scoring="max")],
+           "factor product (rank-scaled)": [r["file"] for r in watch.risks(report, scoring="rank")]}
+    for name, key in watch.BASELINES.items():
+        out[name] = watch.ranked_by(rows, key)
+    out["recent fixes"] = watch.ranked_by(rows, lambda r: (r["recent_fixes"], r["revs"]))
+    return out
+
+
+def score(report: dict, fixed: set, top: int) -> dict:
+    """variant -> how many of its first `top` files were fixed, plus what a random `top` of the pool would name."""
+    lists = variants(report)
+    pool = lists["churn"]
+    out = {name: len(fixed.intersection(files[:top])) for name, files in lists.items()}
+    out["random (expected)"] = round(min(top, len(pool)) * len(fixed.intersection(pool)) / len(pool), 1) if pool else 0.0
+    return out
+
+
+def table(results: list) -> str:
+    """results: [(t, files fixed that were in the pool, pool size, {variant: hits})], oldest first -> Markdown."""
+    names = list(results[0][3]) if results else []
+    head = "| variant | " + " | ".join(f"{t} ({fixed} of {pool} fixed)" for t, fixed, pool, _ in results) + " | total |"
+    rule = "|---|" + "---:|" * (len(results) + 1)
+    rows = []
+    for name in names:
+        cells = [hits[name] for _, _, _, hits in results]
+        total = round(sum(cells), 1) if any(isinstance(c, float) for c in cells) else sum(cells)
+        rows.append(f"| {name} | " + " | ".join(str(c) for c in cells) + f" | {total} |")
+    return "\n".join([head, rule, *rows])
+
+
+def ref_spread(repo: str) -> dict:
+    """Commits and fix commits reachable from every ref (what `git log --all` exports: remote release
+    branches with their backports, unmerged work, the stash) against those reachable from HEAD."""
+    def subjects(*revs):
+        out = subprocess.run([*filetypes.GIT, "log", *revs, "--format=%s"], cwd=repo, check=True, capture_output=True).stdout
+        return out.decode("utf-8", "replace").split("\n")[:-1]
+    everything, head = subjects("--all"), subjects("HEAD")
+    return {"all": len(everything), "head": len(head), "fix_all": sum(map(maat.is_fix, everything)), "fix_head": sum(map(maat.is_fix, head))}
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("repo")
+    p.add_argument("out")
+    p.add_argument("--windows", type=int, default=6)
+    p.add_argument("--horizon", type=int, default=6, metavar="MONTHS")
+    p.add_argument("--top", type=int, default=watch.WATCH_TOP)
+    args = p.parse_args(argv)
+    meta = load._read_json(args.out, "meta.json", {})
+    log_path = os.path.join(args.out, "log.txt")
+    if not meta.get("last_date") or not os.path.exists(log_path):
+        print("evaluate: a finished output directory is needed (meta.json with last_date, and log.txt)", file=sys.stderr)
+        return 2
+    types = filetypes.parse(meta.get("file_types"))
+    aliases = maat.aliases_from_meta(os.path.join(args.out, "meta.json")) if "aliases" in meta else None
+    with open(log_path, encoding="utf-8", errors="replace", newline="") as fh:
+        commits = maat.parse_log(fh.read(), aliases, types)
+    results = []
+    for t in cutoffs(meta["last_date"], args.windows, args.horizon):
+        rev = trend.rev_before(args.repo, t, end_of_day=False)
+        if not rev:
+            continue                      # the history does not reach back this far
+        size = load.parse_scc(backtest.size_at(args.repo, rev, args.out), types)
+        report = report_at(commits, t, size, meta)
+        fixed = fixed_between(commits, t, months_after(t, args.horizon))
+        pool = set(variants(report)["churn"])
+        results.append((t, len(fixed & pool), len(pool), score(report, fixed, args.top)))
+        print(f"evaluate: {t} done", file=sys.stderr)
+    if not results:
+        print("evaluate: no cut-off falls inside the history", file=sys.stderr)
+        return 2
+    spread = ref_spread(args.repo)
+    print(f"### {meta.get('name', args.repo)}, top {args.top}, {args.horizon}-month horizon\n")
+    print(table(results))
+    print(f"\n`--all` exports {spread['all']:,} commits ({spread['fix_all']:,} fixes); HEAD reaches {spread['head']:,} ({spread['fix_head']:,} fixes).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())