gitmole 0.6.15__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitmole
-Version: 0.6.15
+Version: 0.7.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
@@ -30,7 +30,7 @@ Any stack. Free. Offline. No token. No AI. Light.
 
 - **Free.** MIT licence, no paid tier, no account. 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.
+- **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.
@@ -38,12 +38,12 @@ Any stack. Free. Offline. No token. No AI. Light.
 ## Install
 
 ```bash
-# macOS, or Linux with Homebrew: gitmole and the three tools it runs
+# 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 and betterleaks on your PATH, then
+# anywhere else: scc, git-sizer, betterleaks, jscpd and osv-scanner on your PATH, then
 pipx install gitmole
 ```
 
@@ -76,31 +76,31 @@ Running `gitmole .` inside this repository:
 
 ```text
 ╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
-│ 135 commits  ·  2026-09-15 → 2026-09-16  ·  1 identity  ·  branch main                           │
-│ 7,002 lines in 44 files  ·  Python, Ruby                                                         │
+│ 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/ and build/ first; they are 100% and 100% theirs.         │
+│   ↳ 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 (+160%),      │
-│   gitmole/cli.py (+32%), gitmole/findings.py (+266%), gitmole/run.py (+26%)                      │
-│   ↳ Split gitmole/render.py before the next change; its complexity grew 160% in a year.          │
+│   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                                                                              │
-│   2 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
-│   100%); build/ (vinni 100%). That is 97% of all lines added                                     │
-│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 5,371 lines.                 │
+│   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                                                                                    │
-│   4 file(s) were fixed 3+ times in the last six months: 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/cli.py and gitmole/findings.py before the next release; expect the next bug   │
+│   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                                               │
+│   betterleaks scanned every commit on every branch; 28 placeholder-shaped hits left out          │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -126,8 +126,10 @@ you about a clone.
 | 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; duplicated blocks with `--duplicates` | [lizard](https://github.com/terryyin/lizard) | pip, installed with gitmole; tracked code files only |
+| 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).
 
@@ -144,7 +146,9 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 ## Safety
 
 - Everything is offline except the optional clone step, which uses your
-  existing gh auth. None of the tools send data anywhere.
+  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-0.6.15 → gitmole-0.7.0}/README.md

@@ -10,7 +10,7 @@ Any stack. Free. Offline. No token. No AI. Light.
 
 - **Free.** MIT licence, no paid tier, no account. 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.
+- **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.
@@ -18,12 +18,12 @@ Any stack. Free. Offline. No token. No AI. Light.
 ## Install
 
 ```bash
-# macOS, or Linux with Homebrew: gitmole and the three tools it runs
+# 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 and betterleaks on your PATH, then
+# anywhere else: scc, git-sizer, betterleaks, jscpd and osv-scanner on your PATH, then
 pipx install gitmole
 ```
 
@@ -56,31 +56,31 @@ Running `gitmole .` inside this repository:
 
 ```text
 ╭─ gitmole ────────────────────────────────────────────────────────────────────────────────────────╮
-│ 135 commits  ·  2026-09-15 → 2026-09-16  ·  1 identity  ·  branch main                           │
-│ 7,002 lines in 44 files  ·  Python, Ruby                                                         │
+│ 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/ and build/ first; they are 100% and 100% theirs.         │
+│   ↳ 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 (+160%),      │
-│   gitmole/cli.py (+32%), gitmole/findings.py (+266%), gitmole/run.py (+26%)                      │
-│   ↳ Split gitmole/render.py before the next change; its complexity grew 160% in a year.          │
+│   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                                                                              │
-│   2 area(s) with at least 200 lines were written almost entirely by one person: gitmole/ (vinni  │
-│   100%); build/ (vinni 100%). That is 97% of all lines added                                     │
-│   ↳ Pair someone with vinni on gitmole/ first; it is the largest at 5,371 lines.                 │
+│   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                                                                                    │
-│   4 file(s) were fixed 3+ times in the last six months: 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/cli.py and gitmole/findings.py before the next release; expect the next bug   │
+│   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                                               │
+│   betterleaks scanned every commit on every branch; 28 placeholder-shaped hits left out          │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -106,8 +106,10 @@ you about a clone.
 | 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; duplicated blocks with `--duplicates` | [lizard](https://github.com/terryyin/lizard) | pip, installed with gitmole; tracked code files only |
+| 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).
 
@@ -124,7 +126,9 @@ Why these and not others: [docs/tools.md](https://github.com/antvinni/gitmole/bl
 ## Safety
 
 - Everything is offline except the optional clone step, which uses your
-  existing gh auth. None of the tools send data anywhere.
+  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-0.6.15 → gitmole-0.7.0}/gitmole/__init__.py

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

{gitmole-0.6.15 → gitmole-0.7.0}/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
 
@@ -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]

gitmole-0.7.0/gitmole/deps.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Known vulnerabilities in the dependencies, from osv-scanner over the lock files, offline.
+
+gitmole runs this as the osv-scanner step: `python3 deps.py OUT_JSON`, from inside the repository.
+osv-scanner reads every lock file it knows (package-lock.json, yarn.lock, uv.lock, poetry.lock, go.sum,
+Cargo.lock, Gemfile.lock and the rest) and matches the packages against a copy of the OSV database on
+this machine; with --offline nothing leaves the machine, and the copy is downloaded once by the user, never
+by gitmole. Its report repeats every advisory in full; this wrapper keeps one row per vulnerable package
+(ids, the CVE aliases, the worst score, the version that fixes it) and the lock files with their package
+counts, and writes only that. Standalone, like leaks.py and duplicates.py.
+
+The same module reads the status back for the report footer.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+
+ARGV = ["osv-scanner", "scan", "source", "-r", "--offline", "--format", "json", "--all-packages", "."]
+NO_SOURCES = 128           # osv-scanner: no lock file found
+NO_DATABASE = "no offline version of the OSV database"   # its message when the local copy is missing
+DOWNLOAD = "osv-scanner scan source -r --offline-vulnerabilities --download-offline-databases ."
+CACHE_DIRS = ("osv-scalibr", "osv-scanner")   # where the local copy lives under the cache directory, by version
+
+_NUMBER = re.compile(r"\d+")
+
+
+def cache_dir() -> str:
+    """The directory osv-scanner keeps its local database in: its own variable, else the platform cache."""
+    explicit = os.environ.get("OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY")
+    if explicit:
+        return explicit
+    if sys.platform == "darwin":
+        return os.path.expanduser("~/Library/Caches")
+    if sys.platform.startswith("win"):
+        return os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+    return os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache")
+
+
+def database_date(base: str = None) -> str | None:
+    """The day the local database was last refreshed (the newest file under it), or None when none."""
+    base = cache_dir() if base is None else base
+    newest = None
+    for name in CACHE_DIRS:
+        root = os.path.join(base, name)
+        for dirpath, _, files in os.walk(root):
+            for f in files:
+                try:
+                    mtime = os.path.getmtime(os.path.join(dirpath, f))
+                except OSError:
+                    continue
+                newest = mtime if newest is None else max(newest, mtime)
+    return dt.datetime.fromtimestamp(newest).date().isoformat() if newest else None
+
+
+def _key(version: str) -> tuple:
+    return tuple(int(n) for n in _NUMBER.findall(version or ""))
+
+
+def fixed_version(vulns: list, name: str, version: str) -> str | None:
+    """The smallest fixed version above the installed one across the advisories' ranges, else the
+    highest named; None when no advisory names a fix."""
+    fixes = set()
+    for v in vulns:
+        for a in v.get("affected") or []:
+            if (a.get("package") or {}).get("name", "").lower() != (name or "").lower():
+                continue
+            for r in a.get("ranges") or []:
+                for e in r.get("events") or []:
+                    if e.get("fixed"):
+                        fixes.add(e["fixed"])
+    if not fixes:
+        return None
+    current = _key(version)
+    above = [f for f in fixes if _key(f) > current]
+    return min(above, key=_key) if above else max(fixes, key=_key)
+
+
+def _score(groups: list, vulns: list) -> float | None:
+    scores = []
+    for g in groups:
+        try:
+            scores.append(float(g.get("max_severity") or ""))
+        except ValueError:
+            pass
+    if scores:
+        return max(scores)
+    return None
+
+
+_WORDS = {"CRITICAL": 9.5, "HIGH": 8.0, "MODERATE": 5.5, "MEDIUM": 5.5, "LOW": 2.0}
+
+
+def _label(score, vulns: list) -> str:
+    """critical / high / medium / low from the CVSS score, or from the advisory's own word when it has
+    no score, else unknown."""
+    if score is None:
+        words = [(v.get("database_specific") or {}).get("severity", "").upper() for v in vulns]
+        known = [w for w in words if w in _WORDS]
+        score = max(_WORDS[w] for w in known) if known else None
+    if score is None:
+        return "unknown"
+    return "critical" if score >= 9 else "high" if score >= 7 else "medium" if score >= 4 else "low"
+
+
+def _relative(path: str, cwd: str) -> str:
+    if os.path.isabs(path):
+        try:
+            rel = os.path.relpath(path, cwd)
+        except ValueError:
+            return path
+        return path if rel.startswith("..") else rel
+    return path[2:] if path.startswith("./") else path
+
+
+def summarise(data: dict, cwd: str) -> dict:
+    sources, vulnerable, packages = [], [], 0
+    for r in data.get("results") or []:
+        path = _relative((r.get("source") or {}).get("path") or "", cwd)
+        pkgs = r.get("packages") or []
+        sources.append({"path": path, "packages": len(pkgs)})
+        packages += len(pkgs)
+        for p in pkgs:
+            vulns = p.get("vulnerabilities") or []
+            if not vulns:
+                continue
+            info = p.get("package") or {}
+            groups = p.get("groups") or []
+            score = _score(groups, vulns)
+            aliases = sorted({a for v in vulns for a in v.get("aliases") or [] if a.startswith("CVE-")})
+            vulnerable.append({"name": info.get("name", ""), "version": info.get("version", ""), "ecosystem": info.get("ecosystem", ""),
+                               "source": path, "ids": [v.get("id", "") for v in vulns], "aliases": aliases,
+                               "advisories": len(groups) or len(vulns), "score": score, "severity": _label(score, vulns),
+                               "summary": next((v.get("summary") for v in vulns if v.get("summary")), ""),
+                               "fixed": fixed_version(vulns, info.get("name", ""), info.get("version", ""))})
+    vulnerable.sort(key=lambda r: (-(r["score"] if r["score"] is not None else -1), r["name"], r["source"]))
+    return {"status": "scanned", "sources": sources, "packages": packages, "vulnerable": vulnerable}
+
+
+def write(result: dict, target: str) -> None:
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath(target)), prefix=".dependencies-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(result, fh, indent=1)
+        os.replace(tmp, target)
+    finally:
+        if os.path.exists(tmp):
+            os.remove(tmp)
+
+
+def main(argv=None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1:
+        print("usage: deps.py OUT_JSON", file=sys.stderr)
+        return 2
+    target = args[0]
+    proc = subprocess.run(ARGV, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    err = proc.stderr.decode("utf-8", "replace")
+    sys.stderr.write(err)   # osv-scanner's own log lands in run.log
+    if proc.returncode == NO_SOURCES:
+        result = {"status": "no-sources"}
+    elif NO_DATABASE in err:
+        result = {"status": "no-database", "download": DOWNLOAD}
+    elif proc.returncode in (0, 1):   # 1: packages with vulnerabilities were found
+        text = proc.stdout.decode("utf-8", "replace").strip()
+        try:
+            data = json.loads(text) if text else {}
+        except json.JSONDecodeError:
+            print("deps.py: osv-scanner printed no JSON report; nothing written", file=sys.stderr)
+            return 1
+        result = summarise(data, os.getcwd())
+        result["database_date"] = database_date()
+    else:
+        print(f"deps.py: osv-scanner exited {proc.returncode}; no report written", file=sys.stderr)
+        return proc.returncode
+    write(result, target)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())