repo-dive 0.7.0 → 0.9.0

package/README.md

@@ -1,14 +1,16 @@
 # repo-dive
 
-Dive into a git repository's history: per-commit snapshots, an indexed metrics catalog and an interactive dashboard.
+_Dive into a git repo's history: per-commit snapshots, an indexed metrics catalog and an interactive dashboard_ <!-- markdownlint-disable-line MD036 -- a tagline, not a heading -->
 
-> **Still 0.x.**
-> The pipeline works end to end and has been run against repositories with tens of thousands of commits, but interfaces, the catalog format and the collector roster still move between minor versions — pin the version if you script against it.
-> Renamed from `repo-insighter` in 0.4.0.
+[![npm version](https://img.shields.io/npm/v/repo-dive?logo=npm&color=3c7ef6&labelColor=333)](https://www.npmjs.com/package/repo-dive)
+[![npm downloads](https://img.shields.io/npm/dt/repo-dive?logo=npm&color=3c7ef6&labelColor=333)](https://www.npmjs.com/package/repo-dive)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-3c7ef6?logo=opensourceinitiative&logoColor=white&labelColor=333)](LICENSE.md)
+[![Effect](https://img.shields.io/badge/Effect-v4-3c7ef6?logo=effect&logoColor=white&labelColor=333)](https://effect.website)
+[![MCP](https://img.shields.io/badge/MCP-ready-3c7ef6?logo=modelcontextprotocol&logoColor=white&labelColor=333)](#ai-agents-mcp)
 
 ## What it does
 
-Point it at any git repository and get an explorable catalog of insights derived from its history:
+Point `repo-dive` at any git repository and get an explorable catalog of insights derived from its history:
 
 ```sh
 cd /path/to/your/repo
@@ -19,18 +21,31 @@ One command runs the whole pipeline — scan, index, dashboard — and opens the
 
 - **Map**: walk the repo's commits (all or sampled) and let pluggable collectors capture raw snapshots per commit — language/LOC breakdowns, author stats, lint diagnostics and more.
 - **Reduce**: index those snapshots into a local metrics store shaped like a data cube — numbers at intersections of open-ended categories (author, language, date, lint rule, …).
-- **Explore**: query the cube to draw charts, build presentations and ask AI questions about how the codebase evolved.
+- **Explore**: query the cube to draw charts, export shareable reports and ask AI questions about how the codebase evolved.
 
 Everything is local-first, incremental and resumable: results live in a catalog folder inside the repo being analyzed and are refined over multiple runs.
 
 See [docs/specs](docs/specs/README.md) for the architecture and [docs/research/prior-art.md](docs/research/prior-art.md) for a survey of existing tools and why none of them fills this niche.
 
+## Examples
+
+Live dashboards for a few popular repositories, produced by running the tool on their full history:
+
+- [curl](https://kachkaev.github.io/repo-dive/examples/curl/) (C, since 1999)
+- [ollama](https://kachkaev.github.io/repo-dive/examples/ollama/) (Go, since 2023)
+- [prettier](https://kachkaev.github.io/repo-dive/examples/prettier/) (JavaScript, since 2016)
+- [react](https://kachkaev.github.io/repo-dive/examples/react/) (JavaScript, since 2013)
+- [transformers](https://kachkaev.github.io/repo-dive/examples/transformers/) (Python, since 2018)
+- [vite](https://kachkaev.github.io/repo-dive/examples/vite/) (TypeScript, since 2020)
+
+Each one is a single self-contained HTML file exported with `repo-dive report` and redeployed weekly by [a scheduled workflow](.github/workflows/examples.yaml) — see [examples](examples/README.md) for how they are defined.
+
 ## Usage
 
-Run from inside the repository you want to analyze (or pass `--repo /path/to/repo`):
+Run from inside the repository you want to analyze (or pass `--repo /path/to/repo`).
+Node 22.13 or newer is required.
 
 ```sh
-cd /path/to/your/repo
 npx repo-dive            # the whole pipeline: scan + index + dashboard
 npx repo-dive scan       # collect snapshots into .repo-dive/
 npx repo-dive index      # roll up into the metrics cube + dashboard data
@@ -38,10 +53,10 @@ npx repo-dive dashboard  # serve the interactive dashboard
 npx repo-dive status     # show catalog coverage
 npx repo-dive collectors # list available collectors
 npx repo-dive report     # export one shareable self-contained HTML file
+npx repo-dive mcp        # serve the cube to AI agents (Model Context Protocol)
+npx repo-dive gc         # clean up the catalog interactively
+npx repo-dive ignore     # keep other tools out of the catalog
 npx repo-dive query "SELECT metric, sum(value) FROM facts GROUP BY metric"
-npx repo-dive mcp    # serve the cube to AI agents (Model Context Protocol)
-npx repo-dive gc     # clean up the catalog interactively
-npx repo-dive ignore # keep other tools out of the catalog
 ```
 
 `scan` walks the repository's history and runs collectors against every commit (or a sample, per collector), writing raw snapshots into a `.repo-dive/` catalog inside the analyzed repo.
@@ -53,15 +68,16 @@ Collectors so far:
 - **churn** — lines added/deleted per commit, by file extension
 - **file-types** — file count and bytes per extension at each commit's tree
 - **directives** — eslint-disable comments by rule (block disables tracked as gray areas) and `@ts-ignore`/`@ts-expect-error`/`@ts-nocheck`
-- **dependencies** — total resolved packages from package-manager lockfiles, per package manager (pnpm, npm and yarn — classic and berry; version-aware and monorepo-aware, extensible to more managers), plus direct/dev/optional dependencies and the number of manifests read straight from `package.json` files
+- **dependencies** — resolved package totals from lockfiles, per package manager (pnpm, npm, yarn classic and yarn berry), plus direct/dev/optional dependencies and manifest counts read straight from `package.json` files; version-aware, monorepo-aware and extensible to more managers
 - **todo-comments** — TODO/FIXME/HACK/XXX counts
 - **languages** — lines and file count per language across a commit's source files (lockfiles, minified bundles and generated data excluded)
 - **survival** — `git blame` line survival by extension, author and age cohort (sampled monthly)
 
 The catalog hides itself from git, but other tools that walk the repository (prettier, markdownlint, cspell, docker builds) each read one ignore file at its root.
-`scan` warns when the catalog is missing from those; `repo-dive ignore` adds it to every one of them.
+`scan` warns when the catalog is missing from those; `repo-dive ignore` adds it to every one that needs it, writing the entry in the shape the file is already written in and skipping the files whose tool learns about the catalog elsewhere.
 
-`index` normalizes raw snapshots into `.repo-dive/index/metrics.sqlite` (a facts-by-categories cube, rebuildable at any time) plus `dashboard.json`, and `dashboard` serves a local React app with interactive charts: languages over time, a GitHub-style commit calendar, monthly commits with AI-assisted share, churn, lint-suppression trends, dependency counts over time, code survival by cohort and author, and more.
+`index` normalizes raw snapshots into `.repo-dive/index/metrics.sqlite` — a facts-by-categories cube, rebuildable at any time — plus `dashboard.json`.
+`dashboard` then serves a local React app with interactive charts: languages over time, a GitHub-style commit calendar, monthly commits with AI-assisted share, churn, lint-suppression trends, dependency counts over time, code survival by cohort and author, and more.
 
 ## Configuration
 
@@ -98,7 +114,9 @@ export default defineConfig({
 ```
 
 `charts.weekStartsOn` sets the first day of the week in calendar-shaped charts such as the commit calendar (`"monday"` by default, `"sunday"` also supported).
-`contributors.aliases` merges the multiple identities one person commits under (work + personal email, GitHub noreply, name variants) so attribution, the contributors table and code-survival-by-contributor count them once; a group can also carry a `displayName`, a profile `url` and a `kind` (`human`/`bot`/`ai`, otherwise auto-derived — the dashboard badges bots and AI agents and lists them apart from humans).
+`contributors.aliases` merges the multiple identities one person commits under (work + personal email, GitHub noreply, name variants) so attribution, the contributors table and code-survival-by-contributor count them once.
+A group can also carry a `displayName`, a profile `url` and a `kind` (`human`/`bot`/`ai`, otherwise auto-derived).
+The dashboard badges bots and AI agents, listing them apart from humans.
 `catalog.dir` moves the catalog; point it outside the repository (e.g. `"../repo-dive-catalogs/my-repo"`) to leave the analyzed working tree untouched altogether, ignore files included.
 Apart from `catalog`, which every command needs, the config is read by `index`.
 See [docs/specs/07-config.md](docs/specs/07-config.md) for details.
@@ -148,9 +166,18 @@ pnpm lint
 pnpm fix
 ```
 
+To see how heavy the published package would be:
+
+```sh
+pnpm build && pnpm report-package-size
+```
+
+It prints the tarball and unpacked sizes with a per-file breakdown, comparing them against the previous measurement.
+CI runs the same report on every push and adds it to the job summary, comparing against the latest `main`.
+
 ## Acknowledgements
 
-Thanks to [@WillJack20](https://github.com/WillJack20) for suggesting the name **repo-dive**.
+Thanks to [@WillJack20](https://github.com/WillJack20) for suggesting the name `repo-dive`, formerly [repo-insighter](https://www.npmjs.com/package/repo-insighter).
 
 ## License