gitmole 0.7.0__tar.gz → 0.7.1__tar.gz

{gitmole-0.7.0 → gitmole-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -26,14 +26,15 @@ A toolkit for digging into any cloned git repository: who works on it,
 where the risk is, how old the code is, whether the repo itself is healthy,
 and whether anything sensitive was ever committed.
 
-Any stack. Free. Offline. No token. No AI. Light.
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/report.svg" width="912" alt="gitmole on react: the summary, and the watch list of files where the next bug is likely, with a backtest">
 
-- **Free.** MIT licence, no paid tier, no account. The tools it runs are open source too.
+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.
-- **Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
-- **No token.** A local clone needs no credentials. The optional `owner/repo` shortcut uses the `gh` login you already have, and you ask for it.
-- **No AI.** Every finding is a plain rule over counts you can recompute by hand. The same clone gives the same report every time.
-- **Light.** A 4,400-commit repository takes under thirty seconds. A few thousand lines of Python plus two libraries.
+- **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. 
+- **Fast.** A 4,400-commit repository takes under thirty seconds.
 
 ## Install
 
@@ -72,47 +73,64 @@ blocks on secrets in source files and still posts the report. Every option:
 
 ## What you get
 
-Running `gitmole .` inside this repository:
+The opening of the report for [react](https://github.com/facebook/react), 35,263 commits
+since 2013, at a pinned commit; the picture above, as text:
 
 ```text
-╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
-│ 185 commits  ·  2026-09-15 → 2026-09-17  ·  1 identity  ·  branch main                           │
-│ 9,475 lines in 52 files  ·  Python, Ruby                                                         │
-│ most commits on Wed at 20:00  ·  4% of commits are fixes  ·  100% of surviving code from 2026    │
-│ 3 warnings, 1 note                                                                               │
-╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-╭─ Findings (4) ───────────────────────────────────────────────────────────────────────────────────╮
-│ ▲ Bus factor of one                                                                              │
-│   vinni wrote 100% of the code that survives today                                               │
-│   ↳ Pair someone with vinni on gitmole/ first; it is 100% theirs.                                │
-│ ▲ Hotspots getting more complex                                                                  │
-│   4 of the 10 top source hotspots grew by 25% or more in a year: gitmole/render.py (+194%),      │
-│   gitmole/findings.py (+360%), gitmole/cli.py (+64%), gitmole/run.py (+34%)                      │
-│   ↳ Split gitmole/render.py before the next change; its complexity grew 194% in a year.          │
-│ ▲ Knowledge islands                                                                              │
-│   1 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
-│   100%). That is 98% of all lines added                                                          │
-│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 7,607 lines.                 │
-│ ● Bug magnets                                                                                    │
-│   5 file(s) were fixed 3+ times in the last six months: gitmole/load.py (4 recent, 4 total);     │
-│   gitmole/cli.py (3 recent, 3 total); gitmole/findings.py (3 recent, 3 total); gitmole/render.py │
-│   (3 recent, 3 total); gitmole/run.py (3 recent, 3 total)                                        │
-│   ↳ Review gitmole/load.py and gitmole/cli.py before the next release; expect the next bug       │
-│   there.                                                                                         │
-│ ✔ No secrets in history                                                                          │
-│   betterleaks scanned every commit on every branch; 28 placeholder-shaped hits left out          │
+╭─ react ──────────────────────────────────────────────────────────────────────────────────────────╮
+│ 35263 commits  ·  2013-05-28 → 2026-09-16  ·  1880 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%  │
+│ of surviving code from 2026                                                                      │
+│ 1 critical, 6 warnings, 8 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 
+  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)                                             
 ```
 
-Below that: a watch list of the five files where the next bug is most
-likely, with the reasons in words and a backtest of how the list would have
-done; then tables for people, the knowledge map, the timeline, hotspots with
-their complexity trend, change coupling, complex functions and repo health.
-The full report is in
-[docs/example.md](https://github.com/antvinni/gitmole/blob/main/docs/example.md),
-and every section is explained in
+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
 [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
+reference date, published as gitmole wrote them; the repo-health numbers
+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.
+
 ## The tool set
 
 One tool per question; together they cover what a single command can tell
@@ -138,7 +156,7 @@ 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.
-- [Full example report](https://github.com/antvinni/gitmole/blob/main/docs/example.md): the whole `gitmole .` output for this repository.
+- [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django, react and kubernetes at pinned commits, regenerated by `bin/render-examples`.
 - [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.

{gitmole-0.7.0 → gitmole-0.7.1}/README.md

@@ -6,14 +6,15 @@ A toolkit for digging into any cloned git repository: who works on it,
 where the risk is, how old the code is, whether the repo itself is healthy,
 and whether anything sensitive was ever committed.
 
-Any stack. Free. Offline. No token. No AI. Light.
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/report.svg" width="912" alt="gitmole on react: the summary, and the watch list of files where the next bug is likely, with a backtest">
 
-- **Free.** MIT licence, no paid tier, no account. The tools it runs are open source too.
+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.
-- **Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
-- **No token.** A local clone needs no credentials. The optional `owner/repo` shortcut uses the `gh` login you already have, and you ask for it.
-- **No AI.** Every finding is a plain rule over counts you can recompute by hand. The same clone gives the same report every time.
-- **Light.** A 4,400-commit repository takes under thirty seconds. A few thousand lines of Python plus two libraries.
+- **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. 
+- **Fast.** A 4,400-commit repository takes under thirty seconds.
 
 ## Install
 
@@ -52,47 +53,64 @@ blocks on secrets in source files and still posts the report. Every option:
 
 ## What you get
 
-Running `gitmole .` inside this repository:
+The opening of the report for [react](https://github.com/facebook/react), 35,263 commits
+since 2013, at a pinned commit; the picture above, as text:
 
 ```text
-╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
-│ 185 commits  ·  2026-09-15 → 2026-09-17  ·  1 identity  ·  branch main                           │
-│ 9,475 lines in 52 files  ·  Python, Ruby                                                         │
-│ most commits on Wed at 20:00  ·  4% of commits are fixes  ·  100% of surviving code from 2026    │
-│ 3 warnings, 1 note                                                                               │
-╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-╭─ Findings (4) ───────────────────────────────────────────────────────────────────────────────────╮
-│ ▲ Bus factor of one                                                                              │
-│   vinni wrote 100% of the code that survives today                                               │
-│   ↳ Pair someone with vinni on gitmole/ first; it is 100% theirs.                                │
-│ ▲ Hotspots getting more complex                                                                  │
-│   4 of the 10 top source hotspots grew by 25% or more in a year: gitmole/render.py (+194%),      │
-│   gitmole/findings.py (+360%), gitmole/cli.py (+64%), gitmole/run.py (+34%)                      │
-│   ↳ Split gitmole/render.py before the next change; its complexity grew 194% in a year.          │
-│ ▲ Knowledge islands                                                                              │
-│   1 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
-│   100%). That is 98% of all lines added                                                          │
-│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 7,607 lines.                 │
-│ ● Bug magnets                                                                                    │
-│   5 file(s) were fixed 3+ times in the last six months: gitmole/load.py (4 recent, 4 total);     │
-│   gitmole/cli.py (3 recent, 3 total); gitmole/findings.py (3 recent, 3 total); gitmole/render.py │
-│   (3 recent, 3 total); gitmole/run.py (3 recent, 3 total)                                        │
-│   ↳ Review gitmole/load.py and gitmole/cli.py before the next release; expect the next bug       │
-│   there.                                                                                         │
-│ ✔ No secrets in history                                                                          │
-│   betterleaks scanned every commit on every branch; 28 placeholder-shaped hits left out          │
+╭─ react ──────────────────────────────────────────────────────────────────────────────────────────╮
+│ 35263 commits  ·  2013-05-28 → 2026-09-16  ·  1880 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%  │
+│ of surviving code from 2026                                                                      │
+│ 1 critical, 6 warnings, 8 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 
+  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)                                             
 ```
 
-Below that: a watch list of the five files where the next bug is most
-likely, with the reasons in words and a backtest of how the list would have
-done; then tables for people, the knowledge map, the timeline, hotspots with
-their complexity trend, change coupling, complex functions and repo health.
-The full report is in
-[docs/example.md](https://github.com/antvinni/gitmole/blob/main/docs/example.md),
-and every section is explained in
+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
 [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
+reference date, published as gitmole wrote them; the repo-health numbers
+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.
+
 ## The tool set
 
 One tool per question; together they cover what a single command can tell
@@ -118,7 +136,7 @@ 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.
-- [Full example report](https://github.com/antvinni/gitmole/blob/main/docs/example.md): the whole `gitmole .` output for this repository.
+- [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django, react and kubernetes at pinned commits, regenerated by `bin/render-examples`.
 - [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.

{gitmole-0.7.0 → gitmole-0.7.1}/gitmole/__init__.py

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

{gitmole-0.7.0 → gitmole-0.7.1}/gitmole/banner.py

@@ -83,8 +83,9 @@ def _sprite_rows(look: int = 0) -> list:
     return rows
 
 
-def neon(offset: int = 0, look: int = 0) -> Text:
-    """The banner with the palette rotated down by `offset` rows, and the mole beside it."""
+def neon(offset: int = 0, look: int = 0, version: str = None) -> Text:
+    """The banner with the palette rotated down by `offset` rows, and the mole beside it.
+    With `version`, a dim `v1.2.3` row underneath: the report's reproducibility stamp."""
     text = Text()
     sprite = _sprite_rows(look)
     for i, row in enumerate(ART.split("\n")):
@@ -93,15 +94,17 @@ def neon(offset: int = 0, look: int = 0) -> Text:
         text.append(" " * GAP)
         text.append_text(sprite[i])
         text.append("\n")
+    if version:
+        text.append(f"v{version}\n", style="dim")
     return text
 
 
 LOOK_EVERY = 5  # frames per glance; at 10 fps the eyes move every half second
 
 
-def frames():
+def frames(version: str = None):
     """Endless generator of banner frames: gradient flowing down, eyes glancing side to side."""
     n = 0
     while True:
-        yield neon(offset=n % len(NEON), look=(n // LOOK_EVERY) % 2)
+        yield neon(offset=n % len(NEON), look=(n // LOOK_EVERY) % 2, version=version)
         n += 1

{gitmole-0.7.0 → gitmole-0.7.1}/gitmole/cli.py

@@ -171,7 +171,7 @@ def _no_run(args, console, ui, err) -> int:
         err.print(f"[red]no gitmole output found in {out_dir}[/red] (expected meta.json)")
         return 2
     if ui.is_terminal:
-        ui.print(banner.neon())
+        ui.print(banner.neon(version=__version__))
     return _render(out_dir, console, ui, args, err)
 
 
@@ -437,7 +437,7 @@ def _execute(steps, log_path, repo_dir, workers, console, timeout=None) -> dict:
     active, lock = set(), threading.Lock()
     started = time.monotonic()
     spinner = Spinner("dots", style="cyan")
-    frame = banner.frames()
+    frame = banner.frames(version=__version__)
 
     def label() -> str:
         with lock:
@@ -466,7 +466,7 @@ def _execute(steps, log_path, repo_dir, workers, console, timeout=None) -> dict:
         while worker.is_alive():
             live.update(view())
             worker.join(0.1)
-        live.update(Group(banner.neon(), Text("")) if console.is_terminal else Text(""))
+        live.update(Group(banner.neon(version=__version__), Text("")) if console.is_terminal else Text(""))
     console.print(f"[dim]{len(steps)} steps in {time.monotonic() - started:.1f}s[/dim]\n")
     return results
 

{gitmole-0.7.0 → gitmole-0.7.1}/gitmole/render.py

@@ -809,6 +809,13 @@ def report(report: dict, findings: list, console: Console, full: bool = False, r
     console.print(Text(f"Full results and plots in {report['out_dir']}", style="dim"), soft_wrap=True)
 
 
+def excerpt(report: dict, findings: list, console: Console, full: bool = False) -> None:
+    """The report's opening on its own: the header, whose tally counts the findings, and the watch
+    list. What the README's picture shows; the findings themselves are in the full report."""
+    console.print(header(report, findings))
+    print_section(console, watch_section(report, full=full, width=console.width))
+
+
 # --- markdown / json -------------------------------------------------------
 
 def _md_cell(cell: str) -> str:

{gitmole-0.7.0 → gitmole-0.7.1}/gitmole.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -26,14 +26,15 @@ A toolkit for digging into any cloned git repository: who works on it,
 where the risk is, how old the code is, whether the repo itself is healthy,
 and whether anything sensitive was ever committed.
 
-Any stack. Free. Offline. No token. No AI. Light.
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/report.svg" width="912" alt="gitmole on react: the summary, and the watch list of files where the next bug is likely, with a backtest">
 
-- **Free.** MIT licence, no paid tier, no account. The tools it runs are open source too.
+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.
-- **Offline.** Everything runs against a clone on your machine. Nothing is uploaded, nothing phones home; the vulnerability database is a copy you download once.
-- **No token.** A local clone needs no credentials. The optional `owner/repo` shortcut uses the `gh` login you already have, and you ask for it.
-- **No AI.** Every finding is a plain rule over counts you can recompute by hand. The same clone gives the same report every time.
-- **Light.** A 4,400-commit repository takes under thirty seconds. A few thousand lines of Python plus two libraries.
+- **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. 
+- **Fast.** A 4,400-commit repository takes under thirty seconds.
 
 ## Install
 
@@ -72,47 +73,64 @@ blocks on secrets in source files and still posts the report. Every option:
 
 ## What you get
 
-Running `gitmole .` inside this repository:
+The opening of the report for [react](https://github.com/facebook/react), 35,263 commits
+since 2013, at a pinned commit; the picture above, as text:
 
 ```text
-╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
-│ 185 commits  ·  2026-09-15 → 2026-09-17  ·  1 identity  ·  branch main                           │
-│ 9,475 lines in 52 files  ·  Python, Ruby                                                         │
-│ most commits on Wed at 20:00  ·  4% of commits are fixes  ·  100% of surviving code from 2026    │
-│ 3 warnings, 1 note                                                                               │
-╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
-╭─ Findings (4) ───────────────────────────────────────────────────────────────────────────────────╮
-│ ▲ Bus factor of one                                                                              │
-│   vinni wrote 100% of the code that survives today                                               │
-│   ↳ Pair someone with vinni on gitmole/ first; it is 100% theirs.                                │
-│ ▲ Hotspots getting more complex                                                                  │
-│   4 of the 10 top source hotspots grew by 25% or more in a year: gitmole/render.py (+194%),      │
-│   gitmole/findings.py (+360%), gitmole/cli.py (+64%), gitmole/run.py (+34%)                      │
-│   ↳ Split gitmole/render.py before the next change; its complexity grew 194% in a year.          │
-│ ▲ Knowledge islands                                                                              │
-│   1 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
-│   100%). That is 98% of all lines added                                                          │
-│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 7,607 lines.                 │
-│ ● Bug magnets                                                                                    │
-│   5 file(s) were fixed 3+ times in the last six months: gitmole/load.py (4 recent, 4 total);     │
-│   gitmole/cli.py (3 recent, 3 total); gitmole/findings.py (3 recent, 3 total); gitmole/render.py │
-│   (3 recent, 3 total); gitmole/run.py (3 recent, 3 total)                                        │
-│   ↳ Review gitmole/load.py and gitmole/cli.py before the next release; expect the next bug       │
-│   there.                                                                                         │
-│ ✔ No secrets in history                                                                          │
-│   betterleaks scanned every commit on every branch; 28 placeholder-shaped hits left out          │
+╭─ react ──────────────────────────────────────────────────────────────────────────────────────────╮
+│ 35263 commits  ·  2013-05-28 → 2026-09-16  ·  1880 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%  │
+│ of surviving code from 2026                                                                      │
+│ 1 critical, 6 warnings, 8 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 
+  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)                                             
 ```
 
-Below that: a watch list of the five files where the next bug is most
-likely, with the reasons in words and a backtest of how the list would have
-done; then tables for people, the knowledge map, the timeline, hotspots with
-their complexity trend, change coupling, complex functions and repo health.
-The full report is in
-[docs/example.md](https://github.com/antvinni/gitmole/blob/main/docs/example.md),
-and every section is explained in
+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
 [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
+reference date, published as gitmole wrote them; the repo-health numbers
+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.
+
 ## The tool set
 
 One tool per question; together they cover what a single command can tell
@@ -138,7 +156,7 @@ 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.
-- [Full example report](https://github.com/antvinni/gitmole/blob/main/docs/example.md): the whole `gitmole .` output for this repository.
+- [Example reports](https://github.com/antvinni/gitmole/tree/main/docs/examples): curl, django, react and kubernetes at pinned commits, regenerated by `bin/render-examples`.
 - [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.

{gitmole-0.7.0 → gitmole-0.7.1}/gitmole.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ tests/test_loss.py
 tests/test_maat.py
 tests/test_packaging.py
 tests/test_render.py
+tests/test_render_examples.py
 tests/test_run.py
 tests/test_textfmt.py
 tests/test_trend.py

{gitmole-0.7.0 → gitmole-0.7.1}/tests/test_banner.py

@@ -122,5 +122,27 @@ class BannerInCli(unittest.TestCase):
         self.assertNotIn("███╗", self._run(terminal=False))
 
 
+class VersionLine(unittest.TestCase):
+    def test_version_row_sits_under_the_letters(self):
+        rows = banner.neon(version="1.2.3").plain.rstrip("\n").split("\n")
+        self.assertEqual(len(rows), 7)
+        self.assertEqual(rows[6], "v1.2.3")
+
+    def test_version_row_is_dim(self):
+        text = banner.neon(version="1.2.3")
+        start = text.plain.index("v1.2.3")
+        style = next(str(sp.style) for sp in text.spans if sp.start == start)
+        self.assertIn("dim", style)
+
+    def test_without_a_version_nothing_changes(self):
+        self.assertEqual(banner.neon().plain, banner.neon(version=None).plain)
+        self.assertNotIn("v", banner.neon().plain.split("\n")[-2])
+
+    def test_every_frame_carries_the_version(self):
+        gen = banner.frames(version="1.2.3")
+        for _ in range(3):
+            self.assertTrue(next(gen).plain.rstrip("\n").endswith("v1.2.3"))
+
+
 if __name__ == "__main__":
     unittest.main()

{gitmole-0.7.0 → gitmole-0.7.1}/tests/test_cli.py

@@ -30,6 +30,18 @@ class NoRun(unittest.TestCase):
         self.assertEqual(rc, 2)
         self.assertIn("/nonexistent/analysis-x", c.export_text())
 
+    def test_terminal_no_run_prints_the_banner_with_the_version(self):
+        from gitmole import __version__
+        with tempfile.TemporaryDirectory() as out:
+            with open(os.path.join(out, "meta.json"), "w") as fh:
+                json.dump({"name": "demo", "commits": 5, "identities": []}, fh)
+            c = Console(file=io.StringIO(), width=100, record=True, force_terminal=True, color_system="truecolor")
+            rc = cli.main([out, "--no-run"], console=c)
+            text = c.export_text()
+        self.assertEqual(rc, 0)
+        self.assertIn("███╗   ███╗", text)
+        self.assertIn(f"v{__version__}", text)
+
 
 class LiveRun(unittest.TestCase):
     def test_full_run_on_a_terminal_console_prints_banner_and_report(self):
@@ -44,6 +56,8 @@ class LiveRun(unittest.TestCase):
             text = c.export_text()
         self.assertEqual(rc, 0)
         self.assertIn("███╗   ███╗", text)
+        from gitmole import __version__
+        self.assertIn(f"v{__version__}", text)
         self.assertIn("1 steps in", text)
         self.assertIn(os.path.basename(d), text)
 

{gitmole-0.7.0 → gitmole-0.7.1}/tests/test_render.py

@@ -1155,5 +1155,31 @@ class ChangeRisk(unittest.TestCase):
         self.assertNotIn("change_risk", render.to_json(sample_report(), []))
 
 
+class Excerpt(unittest.TestCase):
+    def _text(self, findings=()):
+        console = Console(file=io.StringIO(), width=100, record=True, force_terminal=False, color_system=None)
+        render.excerpt(sample_report(), list(findings), console)
+        return console.export_text()
+
+    def test_prints_header_and_watch_list(self):
+        text = self._text()
+        self.assertIn("demo", text)                     # header panel title
+        self.assertIn("363 commits", text)
+        self.assertIn("Watch list", text)
+        self.assertIn("static/apps-metadata.json", text)   # the top watch row: 128 revisions
+
+    def test_prints_nothing_else(self):
+        text = self._text()
+        for heading in ("Findings", "Hotspots", "People", "Knowledge map", "Timeline", "Change coupling", "Repo health", "Full results"):
+            self.assertNotIn(heading, text)
+
+    def test_findings_are_tallied_in_the_header_not_listed(self):
+        found = [{"severity": "warning", "title": "Bus factor of one", "detail": "Ann wrote 80% of the code",
+                  "advice": "Pair someone with Ann."}]
+        text = self._text(found)
+        self.assertIn("1 warning", text)
+        self.assertNotIn("Bus factor of one", text)
+
+
 if __name__ == "__main__":
     unittest.main()

gitmole-0.7.1/tests/test_render_examples.py

@@ -0,0 +1,106 @@
+"""The pure parts of bin/render-examples: the committed document's shape and the pins' shape."""
+import importlib.machinery
+import importlib.util
+import os
+import unittest
+
+PATH = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "bin", "render-examples")
+
+
+def load():
+    loader = importlib.machinery.SourceFileLoader("render_examples", PATH)
+    spec = importlib.util.spec_from_loader("render_examples", loader)
+    module = importlib.util.module_from_spec(spec)
+    loader.exec_module(module)
+    return module
+
+
+MARKDOWN = """# curl
+
+35000 commits · 1999-12-29 → 2026-09-17 · 900 identities · branch master  
+200,000 lines in 1,200 files · C
+
+## Findings
+
+- something
+
+## Watch list
+
+| file | why |
+| --- | --- |
+| lib/url.c | changed 800 times |
+
+betterleaks scanned every commit on every branch
+
+Full results and plots in /private/tmp/x/gitmole-examples/analysis-curl
+"""
+
+
+class Document(unittest.TestCase):
+    def setUp(self):
+        self.mod = load()
+        self.doc = self.mod.document("curl/curl", "a" * 40, MARKDOWN)
+
+    def test_keeps_the_title_first(self):
+        self.assertTrue(self.doc.startswith("# curl\n"))
+
+    def test_provenance_names_version_target_commit_and_date(self):
+        from gitmole import __version__
+        line = self.doc.split("\n")[2]
+        self.assertIn(f"gitmole {__version__}", line)
+        self.assertIn("[curl/curl](https://github.com/curl/curl)", line)
+        self.assertIn("https://github.com/curl/curl/commit/" + "a" * 40, line)
+        self.assertIn("`" + "a" * 12 + "`", line)
+        self.assertIn(self.mod.NOW, line)
+        self.assertIn("bin/render-examples", line)
+        self.assertIn("(https://github.com/antvinni/gitmole#readme)", line)
+
+    def test_drops_the_machine_specific_last_line(self):
+        self.assertNotIn("Full results and plots", self.doc)
+        self.assertNotIn("/private/tmp", self.doc)
+        self.assertTrue(self.doc.endswith("every commit on every branch\n"))
+
+    def test_body_is_otherwise_unchanged(self):
+        self.assertIn("| lib/url.c | changed 800 times |", self.doc)
+        self.assertIn("## Watch list", self.doc)
+
+    def test_strips_the_footer_render_markdown_actually_emits(self):
+        from tests.test_render import sample_report
+        from gitmole import render
+        markdown = render.markdown(sample_report(), [])
+        self.assertIn("Full results and plots in", markdown)          # the fixture copies this sentence
+        doc = self.mod.document("demo/demo", "b" * 40, markdown)
+        self.assertNotIn("Full results and plots in", doc)
+        self.assertNotIn(sample_report()["out_dir"], doc)
+
+
+class Pins(unittest.TestCase):
+    def test_every_example_is_a_github_target_with_a_full_sha(self):
+        mod = load()
+        self.assertGreaterEqual(len(mod.EXAMPLES), 3)
+        for target, sha in mod.EXAMPLES:
+            self.assertRegex(target, r"^[\w.-]+/[\w.-]+$")
+            self.assertRegex(sha, r"^[0-9a-f]{40}$", f"{target} is not pinned to a full commit hash")
+
+    def test_names_are_unique_and_featured_is_one_of_them(self):
+        mod = load()
+        from gitmole import run
+        names = [run.repo_name(t) for t, _ in mod.EXAMPLES]
+        self.assertEqual(len(names), len(set(names)))
+        self.assertIn(mod.FEATURED, names)
+
+    def test_constants(self):
+        mod = load()
+        self.assertRegex(mod.NOW, r"^\d{4}-\d{2}-\d{2}$")
+        self.assertEqual(mod.WIDTH, 100)
+        self.assertGreaterEqual(mod.TIMEOUT, 900)
+
+    def test_unknown_name_exits_2_and_names_the_choices(self):
+        mod = load()
+        import io, contextlib
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            rc = mod.main(["nope"])
+        self.assertEqual(rc, 2)
+        self.assertIn("nope", err.getvalue())
+        self.assertIn("curl", err.getvalue())