gitmole 0.6.15__tar.gz → 0.7.1__tar.gz

gitmole-0.7.1/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: gitmole
+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
+Keywords: git,analysis,hotspots,code-age,repository,metrics
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13
+Requires-Dist: lizard>=1.24
+Provides-Extra: plots
+Requires-Dist: git-of-theseus; extra == "plots"
+Dynamic: license-file
+
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/banner.svg" width="912" alt="gitmole">
+
+# gitmole
+
+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.
+
+<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. 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. 
+- **Fast.** A 4,400-commit repository takes under thirty seconds.
+
+## Install
+
+```bash
+# macOS, or Linux with Homebrew: gitmole and the five tools it runs
+brew tap antvinni/gitmole https://github.com/antvinni/gitmole
+brew trust antvinni/gitmole
+brew install gitmole
+
+# anywhere else: scc, git-sizer, betterleaks, jscpd and osv-scanner on your PATH, then
+pipx install gitmole
+```
+
+Linux package names, the release binaries, `--plots` and the pip caveats:
+[docs/install.md](https://github.com/antvinni/gitmole/blob/main/docs/install.md).
+
+## Usage
+
+```bash
+gitmole .                              # the clone you are in
+gitmole /path/to/clone                 # any local clone
+gitmole owner/repo                     # clones into a temp dir first, with gh or plain git
+gitmole 'owner/*'                      # every non-archived repo of a user or org, one summary table
+
+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 . --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:
+[docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
+
+## What you get
+
+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
+╭─ 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)                                             
+```
+
+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
+you about a clone.
+
+| Question | Tool | Install |
+|---|---|---|
+| What is this repo, at a glance; who commits, when, how much churn | gitmole itself, from the git log | built in |
+| How big is the codebase, per language | [scc](https://github.com/boyter/scc) | brew |
+| Is the repo itself healthy (huge blobs, deep trees) | [git-sizer](https://github.com/github/git-sizer) | brew |
+| Where is the risk: hotspots, coupling, ownership | gitmole's own change analysis over `git log --numstat` | built in |
+| How old is the surviving code, per year and author | gitmole's own blame pass (one `git blame` per file at HEAD) | built in |
+| Code-age and survival plots over time | [git-of-theseus](https://github.com/erikbern/git-of-theseus) | pip, opt-in with `--plots` |
+| Per-function complexity, length, parameters | [lizard](https://github.com/terryyin/lizard) | pip, installed with gitmole; tracked code files only |
+| 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 |
+
+Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
+
+## Docs
+
+- [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`.
+- [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.
+
+## Safety
+
+- Everything is offline except the optional clone step, which uses your
+  existing gh auth. None of the tools send data anywhere; osv-scanner runs
+  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.
+- 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
+  for that one report and never saved.
+
+## License
+
+[MIT](https://github.com/antvinni/gitmole/blob/main/LICENSE). gitmole runs
+the tools it wraps as separate processes and bundles none of them; their
+licences are listed in
+[docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md#licences).

gitmole-0.7.1/README.md

@@ -0,0 +1,164 @@
+<img src="https://raw.githubusercontent.com/antvinni/gitmole/main/docs/banner.svg" width="912" alt="gitmole">
+
+# gitmole
+
+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.
+
+<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. 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. 
+- **Fast.** A 4,400-commit repository takes under thirty seconds.
+
+## Install
+
+```bash
+# macOS, or Linux with Homebrew: gitmole and the five tools it runs
+brew tap antvinni/gitmole https://github.com/antvinni/gitmole
+brew trust antvinni/gitmole
+brew install gitmole
+
+# anywhere else: scc, git-sizer, betterleaks, jscpd and osv-scanner on your PATH, then
+pipx install gitmole
+```
+
+Linux package names, the release binaries, `--plots` and the pip caveats:
+[docs/install.md](https://github.com/antvinni/gitmole/blob/main/docs/install.md).
+
+## Usage
+
+```bash
+gitmole .                              # the clone you are in
+gitmole /path/to/clone                 # any local clone
+gitmole owner/repo                     # clones into a temp dir first, with gh or plain git
+gitmole 'owner/*'                      # every non-archived repo of a user or org, one summary table
+
+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 . --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:
+[docs/cli.md](https://github.com/antvinni/gitmole/blob/main/docs/cli.md).
+
+## What you get
+
+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
+╭─ 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)                                             
+```
+
+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
+you about a clone.
+
+| Question | Tool | Install |
+|---|---|---|
+| What is this repo, at a glance; who commits, when, how much churn | gitmole itself, from the git log | built in |
+| How big is the codebase, per language | [scc](https://github.com/boyter/scc) | brew |
+| Is the repo itself healthy (huge blobs, deep trees) | [git-sizer](https://github.com/github/git-sizer) | brew |
+| Where is the risk: hotspots, coupling, ownership | gitmole's own change analysis over `git log --numstat` | built in |
+| How old is the surviving code, per year and author | gitmole's own blame pass (one `git blame` per file at HEAD) | built in |
+| Code-age and survival plots over time | [git-of-theseus](https://github.com/erikbern/git-of-theseus) | pip, opt-in with `--plots` |
+| Per-function complexity, length, parameters | [lizard](https://github.com/terryyin/lizard) | pip, installed with gitmole; tracked code files only |
+| 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 |
+
+Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md).
+
+## Docs
+
+- [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`.
+- [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.
+
+## Safety
+
+- Everything is offline except the optional clone step, which uses your
+  existing gh auth. None of the tools send data anywhere; osv-scanner runs
+  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.
+- 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
+  for that one report and never saved.
+
+## License
+
+[MIT](https://github.com/antvinni/gitmole/blob/main/LICENSE). gitmole runs
+the tools it wraps as separate processes and bundles none of them; their
+licences are listed in
+[docs/tools.md](https://github.com/antvinni/gitmole/blob/main/docs/tools.md#licences).

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

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

{gitmole-0.6.15 → 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.6.15 → gitmole-0.7.1}/gitmole/cli.py

@@ -37,7 +37,7 @@ def parse_args(argv):
     p.add_argument("--list-file-types", action="store_true", help="list the file types in the repository, with counts and whether they count as code, then exit")
     p.add_argument("--clean", action="store_true", help="list the directories gitmole created (temp clones, analysis-* under the target) and delete them after a y/N question, then exit")
     p.add_argument("--yes", action="store_true", help="with --clean: delete without asking")
-    p.add_argument("--duplicates", action="store_true", help="also look for duplicated code blocks (minutes and gigabytes on a large repo; function metrics alone take seconds)")
+    p.add_argument("--duplicates", action="store_true", help=argparse.SUPPRESS)   # duplicates always run now; kept so older scripts still parse
     p.add_argument("--full", action="store_true", help="every column and every row in the terminal report, and the test files the default tables hide (the default is the tighter, readable one)")
     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")
@@ -100,7 +100,7 @@ def main(argv=None, console: Console = None, tool_check=run.missing_tools, plann
     missing = tool_check(plots=args.plots)
     if missing:
         err.print("[red]missing tools:[/red] " + ", ".join(missing))
-        err.print("brew install scc git-sizer betterleaks; see README.md for other ways")
+        err.print(f"brew install {' '.join(run.REQUIRED_TOOLS)}; see README.md for other ways")
         return 2
     args.lizard = lizard_check()   # decided once, for every repository this run analyses
 
@@ -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)
 
 
@@ -269,12 +269,17 @@ def _list_file_types(repo_dir: str, args, console: Console) -> int:
     return 0
 
 
-def _budgets(args, estimate, ui) -> tuple[bool, bool, float]:
-    """Decide whether code age and plots fit their time/size budgets, printing a skip notice for each
-    one cut. The projected blame time comes back with them: meta.json records it."""
+def _budgets(args, estimate, ui) -> tuple[bool, bool, float, bool]:
+    """Decide whether code age, plots and the duplicates step fit their time/size budgets, printing a
+    skip notice for each one cut. The projected blame time comes back with them: meta.json records it."""
     projected = float(estimate.get("seconds", 0.0))
     age_ok = args.deep or projected <= args.time_budget
     plots_ok = args.plots and (args.deep or estimate["blames"] <= args.budget)
+    text_mb = estimate.get("text_bytes", 0) / 1e6
+    duplicates_ok = args.deep or text_mb <= run.DUPLICATES_BUDGET_MB
+    if not duplicates_ok:
+        ui.print(f"[yellow]duplicates skipped:[/yellow] {text_mb:,.0f} MB of tracked text is over the {run.DUPLICATES_BUDGET_MB} MB budget; "
+                 f"jscpd would need about {text_mb / 25:,.0f} GB of memory. Rerun with --deep to force it, or --ignore-data to shrink it.")
     if not age_ok:
         ui.print(f"[yellow]code age skipped:[/yellow] a blame pass over {estimate.get('code_files', estimate['files']):,} files is projected "
                  f"to take about {projected:,.0f}s, over the {args.time_budget:,.0f}s time budget. "
@@ -283,10 +288,10 @@ def _budgets(args, estimate, ui) -> tuple[bool, bool, float]:
         ui.print(f"[yellow]plots skipped:[/yellow] about {estimate['blames']:,} git blames "
                  f"({estimate['files']:,} files × {estimate['samples']} samples) exceeds the budget of {args.budget:,}. "
                  f"Rerun with --deep to force them, or --ignore-data to shrink them.")
-    return age_ok, plots_ok, projected
+    return age_ok, plots_ok, projected, duplicates_ok
 
 
-def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, projected: float) -> tuple[dict, str | None]:
+def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, projected: float, duplicates_ok: bool = True) -> tuple[dict, str | None]:
     """Collect this run's meta.json: repo facts plus a planned status record for every optional step.
     Raises NoCommits when --since leaves no commits to analyse."""
     types_spec = _types_spec(args.file_types)
@@ -308,6 +313,8 @@ def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, p
         meta["plots"] = {"status": "run" if plots_ok else "skipped", "blames": estimate["blames"], "samples": estimate["samples"], "budget": args.budget}
     lizard_ok = args.lizard
     meta["functions"] = {"status": "planned" if lizard_ok else "skipped"}   # "run" only once the step has finished
+    meta["duplicates"] = {"status": "planned" if duplicates_ok else "skipped", "text_mb": round(estimate.get("text_bytes", 0) / 1e6, 1),
+                          "budget_mb": run.DUPLICATES_BUDGET_MB}
     meta["trend"] = {"status": "planned"}
     from . import maat as _maat
     cut = _maat.months_before(meta["last_date"], 6) if meta["last_date"] else None
@@ -320,7 +327,7 @@ def _meta_for_run(repo_dir: str, args, estimate, age_ok: bool, plots_ok: bool, p
     return meta, cut
 
 
-def _record_statuses(meta, results, age_ok: bool, plots_ok: bool, lizard_ok: bool, cut) -> None:
+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."""
     def status(step, default="run"):
         rc = results.get(step, 0)
@@ -331,6 +338,8 @@ def _record_statuses(meta, results, age_ok: bool, plots_ok: bool, lizard_ok: boo
         meta["plots"]["status"] = status("git-of-theseus")
     if lizard_ok:
         meta["functions"]["status"] = status("functions")
+    if duplicates_ok and "duplicates" in results:
+        meta["duplicates"]["status"] = status("duplicates")
     if "trend" in results:
         meta["trend"]["status"] = status("trend")
     if cut and "backtest" in results:
@@ -345,14 +354,14 @@ def _analyse(repo_dir: str, out_dir: str, args, ui: Console, planner, estimator)
 
     ignore = list(run.DATA_IGNORES if args.ignore_data else []) + list(args.ignore)
     estimate = estimator(repo_dir, run.MONTH, ignore=ignore, types=filetypes.parse(args.file_types))
-    age_ok, plots_ok, projected = _budgets(args, estimate, ui)
+    age_ok, plots_ok, projected, duplicates_ok = _budgets(args, estimate, ui)
 
-    meta, cut = _meta_for_run(repo_dir, args, estimate, age_ok, plots_ok, projected)
+    meta, cut = _meta_for_run(repo_dir, args, estimate, age_ok, plots_ok, projected, duplicates_ok)
     types_spec = meta["file_types"]
     lizard_ok = args.lizard
     run.clear_outputs(out_dir)
     steps = planner(repo_dir, out_dir, branch=meta["branch"], age=age_ok, plots=plots_ok, ignore=ignore, types=types_spec, now=args.now,
-                    since=args.since_date, lizard=lizard_ok, duplicates=args.duplicates, backtest=cut)
+                    since=args.since_date, lizard=lizard_ok, duplicates=duplicates_ok, backtest=cut)
     run.save_meta(meta, out_dir)
     results = _execute(steps, log_path, repo_dir, args.workers, ui, timeout=args.timeout)
     if _control.cancelled.is_set():
@@ -360,7 +369,7 @@ def _analyse(repo_dir: str, out_dir: str, args, ui: Console, planner, estimator)
         ui.print(f"[red]interrupted:[/red] killed {len(killed)} step(s)")
         raise Interrupted()
 
-    _record_statuses(meta, results, age_ok, plots_ok, lizard_ok, cut)
+    _record_statuses(meta, results, age_ok, plots_ok, lizard_ok, cut, duplicates_ok)
     run.save_meta(meta, out_dir)
 
     failed = [n for n, rc in results.items() if rc != 0]
@@ -428,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:
@@ -457,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