repo-dive 0.4.1 → 0.4.2

package/README.md

@@ -81,6 +81,38 @@ export default defineConfig({
 
 `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). The config is read by `index`. See [docs/specs/07-config.md](docs/specs/07-config.md) for details.
 
+## AI agents (MCP)
+
+`repo-dive mcp` serves the metrics cube over the Model Context Protocol on stdio, so an agent can explore a repository's history by asking SQL questions. Two tools:
+
+- **`schema`** — tables, available metrics with row counts, sample category keys per metric and the commit range; worth calling before writing queries.
+- **`query`** — one read-only statement (`SELECT`/`WITH`/`EXPLAIN`) against the cube, returning `{ columns, rows, truncated }` (up to 200 rows).
+
+Run `scan` and `index` first: the server exits immediately if there is no cube at `.repo-dive/index/metrics.sqlite`. The database is opened read-only, so nothing an agent asks can change the catalog.
+
+For [Claude Code](https://code.claude.com/docs/en/mcp), run this inside the repository you want to ask questions about:
+
+```sh
+claude mcp add repo-dive -- npx -y repo-dive mcp
+```
+
+Or commit a project-scoped `.mcp.json` at the repository root, so everyone on the team gets the same server:
+
+```json
+{
+  "mcpServers": {
+    "repo-dive": {
+      "command": "npx",
+      "args": ["-y", "repo-dive", "mcp"]
+    }
+  }
+}
+```
+
+Then ask things like "which languages grew fastest last year?" or "how has the share of AI-assisted commits changed?".
+
+The same stdio server works with any MCP client — point yours at `npx repo-dive mcp`, adding `--repo /path/to/repo` if the client does not start it inside the repository being analyzed.
+
 ## Development
 
 The project is written in TypeScript with [Effect](https://effect.website) v4 (beta) and its built-in CLI toolkit (`effect/unstable/cli`).

package/dist/cli.js

@@ -5,7 +5,7 @@ import http from "node:http";
 import * as Crypto$1 from "node:crypto";
 import { createHash } from "node:crypto";
 import * as NFS from "node:fs";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, statSync } from "node:fs";
 import * as OS from "node:os";
 import os from "node:os";
 import * as Path from "node:path";
@@ -52170,7 +52170,7 @@ var runWith = (command, config) => {
 };
 var package_default = {
 	name: "repo-dive",
-	version: "0.4.1",
+	version: "0.4.2",
 	description: "Dive into a git repository's history: per-commit snapshots, an indexed metrics catalog and an interactive dashboard",
 	keywords: [
 		"git",
@@ -52240,6 +52240,7 @@ var package_default = {
 	"lint-staged": { "**": ["prettier --ignore-unknown --write"] },
 	prettier: "@kachkaev/prettier-config",
 	devDependencies: {
+		"@changesets/changelog-github": "0.7.0",
 		"@changesets/cli": "2.31.1",
 		"@changesets/config": "3.1.4",
 		"@effect/platform-node": "4.0.0-beta.99",
@@ -52723,12 +52724,12 @@ var writeCollectorOutput = ({ catalog, sha, collector, cacheKey, output, duratio
 var openCaches = /* @__PURE__ */ new Map();
 /** Bump when the table shape changes; a mismatch drops the cache and rebuilds. */
 var schemaVersion = 2;
+var blobCachePath = (repoRoot) => path.join(repoRoot, catalogDirName, "cache", "blob-cache.sqlite");
 var getBlobCache = (repoRoot) => {
 	const existing = openCaches.get(repoRoot);
-	if (existing) return existing;
-	const cacheDir = path.join(repoRoot, catalogDirName, "cache");
-	mkdirSync(cacheDir, { recursive: true });
-	const db = new DatabaseSync(path.join(cacheDir, "blob-cache.sqlite"));
+	if (existing) return existing.cache;
+	mkdirSync(path.join(repoRoot, catalogDirName, "cache"), { recursive: true });
+	const db = new DatabaseSync(blobCachePath(repoRoot));
 	db.exec("PRAGMA journal_mode = WAL");
 	const storedSchema = db.prepare("PRAGMA user_version").get();
 	if (Number(storedSchema?.["user_version"] ?? 0) !== schemaVersion) {
@@ -52768,9 +52769,82 @@ var getBlobCache = (repoRoot) => {
 			}
 		}
 	};
-	openCaches.set(repoRoot, cache);
+	openCaches.set(repoRoot, {
+		db,
+		cache
+	});
 	return cache;
 };
+/** Bytes the cache occupies, counting the write-ahead log SQLite keeps beside it. */
+var blobCacheSizeBytes = (repoRoot) => {
+	const base = blobCachePath(repoRoot);
+	return [
+		"",
+		"-wal",
+		"-shm"
+	].map((suffix) => `${base}${suffix}`).reduce((total, filePath) => total + (existsSync(filePath) ? statSync(filePath).size : 0), 0);
+};
+/** Opens the cache file for maintenance, or `undefined` when there is none. */
+var openForMaintenance = (repoRoot) => {
+	const filePath = blobCachePath(repoRoot);
+	if (!existsSync(filePath)) return;
+	const open = openCaches.get(repoRoot);
+	if (open) {
+		open.db.close();
+		openCaches.delete(repoRoot);
+	}
+	const db = new DatabaseSync(filePath);
+	if (!db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'blob_results'").get()) {
+		db.close();
+		return;
+	}
+	return db;
+};
+/** What the cache currently holds, one row per (collector, fingerprint) pair. */
+var listBlobCacheNamespaces = (repoRoot) => {
+	const db = openForMaintenance(repoRoot);
+	if (!db) return [];
+	try {
+		return db.prepare("SELECT collector, cache_key, count(*) AS entry_count FROM blob_results GROUP BY collector, cache_key").all().flatMap((row) => {
+			const collector = row["collector"];
+			const cacheKey = row["cache_key"];
+			return typeof collector === "string" && typeof cacheKey === "string" ? [{
+				collector,
+				cacheKey,
+				entryCount: Number(row["entry_count"])
+			}] : [];
+		});
+	} finally {
+		db.close();
+	}
+};
+/**
+* Deletes the given namespaces and compacts the file, returning how many bytes
+* that gave back. Entries are content-derived, so removing them costs at most
+* a re-scan of the blobs involved — never any recorded data.
+*/
+var pruneBlobCacheNamespaces = (repoRoot, namespaces) => {
+	if (namespaces.length === 0) return 0;
+	const sizeBefore = blobCacheSizeBytes(repoRoot);
+	const db = openForMaintenance(repoRoot);
+	if (!db) return 0;
+	try {
+		const deleteNamespace = db.prepare("DELETE FROM blob_results WHERE collector = ? AND cache_key = ?");
+		db.exec("BEGIN");
+		try {
+			for (const { collector, cacheKey } of namespaces) deleteNamespace.run(collector, cacheKey);
+			db.exec("COMMIT");
+		} catch (error) {
+			db.exec("ROLLBACK");
+			throw error;
+		}
+		db.exec("VACUUM");
+		db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+	} finally {
+		db.close();
+	}
+	return Math.max(0, sizeBefore - blobCacheSizeBytes(repoRoot));
+};
 //#endregion
 //#region src/lib/collectors/tree-files.ts
 /**
@@ -54459,9 +54533,12 @@ var buildPlan = (repoRoot) => gen(function* () {
 		"rev-list",
 		"HEAD"
 	])).split("\n").filter(Boolean));
+	const firstParentShas = yield* listFirstParentShas(repoRoot);
 	const config = yield* loadConfig(repoRoot);
 	const currentCacheKeys = new Map(builtInCollectors.map((collector) => [collector.name, collectorCacheKey(collector, config)]));
+	const snapshotCollectorNames = new Set(builtInCollectors.filter((collector) => describesTreeState(collector)).map((collector) => collector.name));
 	const unreachableShas = [];
+	const offMainlineOutputs = [];
 	const staleOutputs = [];
 	const countsByCollector = /* @__PURE__ */ new Map();
 	for (const sha of catalogShas) {
@@ -54472,6 +54549,10 @@ var buildPlan = (repoRoot) => gen(function* () {
 		const collectorNames = yield* readdirIfExists(path.join(commitsPath, sha));
 		for (const collectorName of collectorNames) {
 			countsByCollector.set(collectorName, (countsByCollector.get(collectorName) ?? 0) + 1);
+			if (!firstParentShas.has(sha) && snapshotCollectorNames.has(collectorName)) offMainlineOutputs.push({
+				sha,
+				collectorName
+			});
 			const currentCacheKey = currentCacheKeys.get(collectorName);
 			if (currentCacheKey === void 0) {
 				staleOutputs.push({
@@ -54492,12 +54573,18 @@ var buildPlan = (repoRoot) => gen(function* () {
 			});
 		}
 	}
+	const liveNamespaces = new Set([...currentCacheKeys].map(([collectorName, cacheKey]) => `${collectorName}:${cacheKey}`));
 	return {
 		catalogPath,
 		commitsPath,
 		unreachableShas,
+		offMainlineOutputs,
 		staleOutputs,
-		countsByCollector
+		countsByCollector,
+		staleCacheNamespaces: (yield* try_({
+			try: () => listBlobCacheNamespaces(repoRoot),
+			catch: toError$2
+		})).filter((namespace) => !liveNamespaces.has(`${namespace.collector}:${namespace.cacheKey}`))
 	};
 });
 var removePaths = (paths, dryRun) => dryRun ? void_$1 : forEach$1(paths, (target) => tryPromise({
@@ -54528,11 +54615,30 @@ var pruneEmptyCommitDirs = (commitsPath) => gen(function* () {
 	}
 	return pruned;
 });
-var runGc = ({ repoPath, unreachable, stale, collectorNames, dryRun = false, yes = false }) => gen(function* () {
-	const plan = yield* buildPlan(yield* resolveRepoRoot(repoPath));
+var staleCacheEntryCount = (plan) => plan.staleCacheNamespaces.reduce((total, namespace) => total + namespace.entryCount, 0);
+/** Human-readable size, e.g. "3.4 MB". */
+var formatBytes = (bytes) => {
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB"
+	];
+	let value = bytes;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex += 1;
+	}
+	return `${unitIndex === 0 ? value : value.toFixed(1)} ${units[unitIndex]}`;
+};
+var runGc = ({ repoPath, unreachable, offMainline, stale, collectorNames, dryRun = false, yes = false }) => gen(function* () {
+	const repoRoot = yield* resolveRepoRoot(repoPath);
+	const plan = yield* buildPlan(repoRoot);
 	const requestedCollectors = (collectorNames ?? "").split(",").map((name) => name.trim()).filter(Boolean);
-	const anyFlagGiven = unreachable === true || stale === true || requestedCollectors.length > 0;
+	const anyFlagGiven = unreachable === true || offMainline === true || stale === true || requestedCollectors.length > 0;
 	let removeUnreachable = unreachable === true;
+	let removeOffMainline = offMainline === true;
 	let removeStale = stale === true;
 	let collectorsToRemove = requestedCollectors;
 	if (!anyFlagGiven) {
@@ -54541,10 +54647,17 @@ var runGc = ({ repoPath, unreachable, stale, collectorNames, dryRun = false, yes
 			title: `Data for ${plan.unreachableShas.length} commits no longer reachable from HEAD`,
 			value: { kind: "unreachable" }
 		});
-		if (plan.staleOutputs.length > 0) choices.push({
-			title: `${plan.staleOutputs.length} stale collector outputs (old versions or removed collectors)`,
-			value: { kind: "stale" }
+		if (plan.offMainlineOutputs.length > 0) choices.push({
+			title: `${plan.offMainlineOutputs.length} snapshot outputs taken off HEAD's first-parent chain (left out of the cube)`,
+			value: { kind: "offMainline" }
 		});
+		if (plan.staleOutputs.length > 0 || plan.staleCacheNamespaces.length > 0) {
+			const parts = [...plan.staleOutputs.length > 0 ? [`${plan.staleOutputs.length} collector outputs`] : [], ...plan.staleCacheNamespaces.length > 0 ? [`${staleCacheEntryCount(plan)} blob-cache entries`] : []];
+			choices.push({
+				title: `Stale ${parts.join(" and ")} (old versions or removed collectors)`,
+				value: { kind: "stale" }
+			});
+		}
 		for (const [name, count] of [...plan.countsByCollector.entries()].toSorted(([left], [right]) => left.localeCompare(right))) choices.push({
 			title: `All ${count} outputs of collector "${name}"`,
 			value: {
@@ -54565,19 +54678,26 @@ var runGc = ({ repoPath, unreachable, stale, collectorNames, dryRun = false, yes
 			return;
 		}
 		removeUnreachable = selected.some((action) => action.kind === "unreachable");
+		removeOffMainline = selected.some((action) => action.kind === "offMainline");
 		removeStale = selected.some((action) => action.kind === "stale");
 		collectorsToRemove = selected.flatMap((action) => action.kind === "collector" ? [action.name] : []);
 	}
-	const targets = [];
+	const targets = /* @__PURE__ */ new Set();
 	const reportLines = [];
 	if (removeUnreachable && plan.unreachableShas.length > 0) {
-		targets.push(...plan.unreachableShas.map((sha) => path.join(plan.commitsPath, sha)));
+		for (const sha of plan.unreachableShas) targets.add(path.join(plan.commitsPath, sha));
 		reportLines.push(`${plan.unreachableShas.length} unreachable commit folders`);
 	}
+	if (removeOffMainline && plan.offMainlineOutputs.length > 0) {
+		for (const output of plan.offMainlineOutputs) targets.add(path.join(plan.commitsPath, output.sha, output.collectorName));
+		reportLines.push(`${plan.offMainlineOutputs.length} off-mainline snapshot outputs`);
+	}
 	if (removeStale && plan.staleOutputs.length > 0) {
-		targets.push(...plan.staleOutputs.map((output) => path.join(plan.commitsPath, output.sha, output.collectorName)));
+		for (const output of plan.staleOutputs) targets.add(path.join(plan.commitsPath, output.sha, output.collectorName));
 		reportLines.push(`${plan.staleOutputs.length} stale collector outputs`);
 	}
+	const pruneCacheNamespaces = removeStale && plan.staleCacheNamespaces.length > 0;
+	if (pruneCacheNamespaces) reportLines.push(`${staleCacheEntryCount(plan)} stale blob-cache entries`);
 	for (const name of collectorsToRemove) {
 		const count = plan.countsByCollector.get(name) ?? 0;
 		if (count === 0) {
@@ -54585,10 +54705,10 @@ var runGc = ({ repoPath, unreachable, stale, collectorNames, dryRun = false, yes
 			continue;
 		}
 		const shas = yield* readdirIfExists(plan.commitsPath);
-		for (const sha of shas) targets.push(path.join(plan.commitsPath, sha, name));
+		for (const sha of shas) targets.add(path.join(plan.commitsPath, sha, name));
 		reportLines.push(`${count} outputs of collector "${name}"`);
 	}
-	if (targets.length === 0) {
+	if (targets.size === 0 && !pruneCacheNamespaces) {
 		yield* log("Nothing to garbage-collect.");
 		return;
 	}
@@ -54603,22 +54723,28 @@ var runGc = ({ repoPath, unreachable, stale, collectorNames, dryRun = false, yes
 			return;
 		}
 	}
-	yield* removePaths(targets, false);
+	yield* removePaths([...targets], false);
 	const pruned = yield* pruneEmptyCommitDirs(plan.commitsPath);
-	yield* log(`${summary}${pruned > 0 ? ` Pruned ${pruned} empty commit folders.` : ""} Run \`repo-dive index\` to refresh rollups.`);
+	const cacheBytesReclaimed = pruneCacheNamespaces ? yield* try_({
+		try: () => pruneBlobCacheNamespaces(repoRoot, plan.staleCacheNamespaces),
+		catch: toError$2
+	}) : 0;
+	yield* log(`${summary}${pruned > 0 ? ` Pruned ${pruned} empty commit folders.` : ""}${cacheBytesReclaimed > 0 ? ` Blob cache shrank by ${formatBytes(cacheBytesReclaimed)}.` : ""} Run \`repo-dive index\` to refresh rollups.`);
 }).pipe(provide(layer$1));
 //#endregion
 //#region src/commands/gc.ts
 var gcCommand = make$3("gc", {
 	repoPath: string("repo").pipe(withDefault("."), withDescription$1("Path to the git repository whose catalog to clean (defaults to the current directory)")),
 	unreachable: boolean("unreachable").pipe(withDescription$1("Remove data for commits no longer reachable from HEAD")),
-	stale: boolean("stale").pipe(withDescription$1("Remove outputs written by old collector versions or by collectors that no longer exist")),
+	offMainline: boolean("off-mainline").pipe(withDescription$1("Remove tree snapshots stored under commits that are not on HEAD's first-parent chain")),
+	stale: boolean("stale").pipe(withDescription$1("Remove catalog outputs and blob-cache entries written by old collector versions or by collectors that no longer exist")),
 	collectorNames: optional$1(string("collectors").pipe(withDescription$1("Comma-separated collector names whose outputs should be removed entirely"))),
 	dryRun: boolean("dry-run").pipe(withDescription$1("Report what would be removed without removing it")),
 	yes: boolean("yes").pipe(withAlias("y"), withDescription$1("Skip the confirmation prompt"))
-}).pipe(withDescription("Garbage-collect the catalog: unreachable commits, stale versions or whole collectors (interactive without flags)"), withHandler((config) => runGc({
+}).pipe(withDescription("Garbage-collect the catalog: unreachable commits, off-mainline snapshots, stale versions or whole collectors (interactive without flags)"), withHandler((config) => runGc({
 	repoPath: config.repoPath,
 	unreachable: config.unreachable,
+	offMainline: config.offMainline,
 	stale: config.stale,
 	collectorNames: getOrUndefined$1(config.collectorNames),
 	dryRun: config.dryRun,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-dive",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Dive into a git repository's history: per-commit snapshots, an indexed metrics catalog and an interactive dashboard",
   "keywords": [
     "git",
@@ -52,6 +52,7 @@
   },
   "prettier": "@kachkaev/prettier-config",
   "devDependencies": {
+    "@changesets/changelog-github": "0.7.0",
     "@changesets/cli": "2.31.1",
     "@changesets/config": "3.1.4",
     "@effect/platform-node": "4.0.0-beta.99",