repo-dive 0.8.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 _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 -->
 
 [![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/dm/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)
@@ -21,12 +21,26 @@ 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)
+- [effect](https://kachkaev.github.io/repo-dive/examples/effect/) (TypeScript, since 2020)
+- [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`).
@@ -55,13 +69,13 @@ 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** — resolved package totals from lockfiles, per package manager (pnpm, npm and yarn classic and berry), plus direct/dev/optional dependencies and manifest counts read straight from `package.json` files; version-aware, monorepo-aware and extensible to more managers
+- **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`.
 `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.
@@ -102,7 +116,8 @@ 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, with the dashboard badging bots and AI agents and listing them apart from humans.
+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.
@@ -163,8 +178,7 @@ CI runs the same report on every push and adds it to the job summary, comparing
 
 ## Acknowledgements
 
-Thanks to [@WillJack20](https://github.com/WillJack20) for suggesting the name **repo-dive**.
-The project was published as [repo-insighter](https://www.npmjs.com/package/repo-insighter) before 0.4.0.
+Thanks to [@WillJack20](https://github.com/WillJack20) for suggesting the name `repo-dive`, formerly [repo-insighter](https://www.npmjs.com/package/repo-insighter).
 
 ## License