repo-dive 0.4.0 → 0.4.2

package/README.md

@@ -68,8 +68,8 @@ export default defineConfig({
       ["alice@work.example", "alice@personal.example"],
       // Rich form: a display name, a profile link and an explicit kind.
       {
-        emails: ["bob@work.example", "12345+bob@users.noreply.github.com"],
         displayName: "Bob",
+        emails: ["bob@work.example", "12345+bob@users.noreply.github.com"],
         url: "https://github.com/bob",
       },
     ],
@@ -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.0",
+	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",
@@ -52364,6 +52365,15 @@ var recordAt = (value, key) => asRecord$1(asRecord$1(value)?.[key]) ?? {};
 var arrayAt = (value, key) => asArray(asRecord$1(value)?.[key]);
 //#endregion
 //#region src/lib/collectors/types.ts
+/**
+* Whether a collector describes the *state of the tree* at a commit rather than
+* facts about the commit itself. Such snapshots are only meaningful on the
+* first-parent chain: a commit that lives on a side branch — or that arrived
+* with a foreign history absorbed by an unrelated-histories merge — carries a
+* tree that was never the repository's state, so charting it puts a cliff into
+* every timeline.
+*/
+var describesTreeState = (collector) => collector.strategy !== "log";
 /** File extension used as a category key, e.g. ".ts"; files without one map to "(none)". */
 var extensionOf = (filePath) => {
 	const basename = filePath.split("/").at(-1) ?? "";
@@ -52714,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) {
@@ -52759,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
 /**
@@ -53546,12 +53629,57 @@ var resolveCollectors = (names) => {
 	return resolved;
 };
 //#endregion
+//#region src/lib/sampling.ts
+var parseSamplingPolicy = (input) => {
+	if (input === "all" || input === "weekly" || input === "monthly" || input === "quarterly") return input;
+	const everyNthMatch = /^every-nth:(\d+)$/.exec(input);
+	if (everyNthMatch?.[1]) {
+		const everyNth = Number(everyNthMatch[1]);
+		if (everyNth >= 1) return { everyNth };
+	}
+	return /* @__PURE__ */ new Error(`Unknown sampling policy: ${input}. Expected all, weekly, monthly, quarterly or every-nth:<n>.`);
+};
+/** How a policy is spelled in CLI output (`collectors`, `scan`, `status`). */
+var samplingLabel = (policy) => typeof policy === "object" ? `every-nth:${policy.everyNth}` : policy;
+var isoWeekOf = (date) => {
+	const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+	const dayOfWeek = utc.getUTCDay() || 7;
+	utc.setUTCDate(utc.getUTCDate() + 4 - dayOfWeek);
+	const yearStart = Date.UTC(utc.getUTCFullYear(), 0, 1);
+	const week = Math.ceil(((utc.getTime() - yearStart) / 864e5 + 1) / 7);
+	return `${utc.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+};
+var bucketOf = (policy, authorDate) => {
+	const date = new Date(authorDate);
+	if (policy === "weekly") return isoWeekOf(date);
+	const month = date.getUTCMonth();
+	return policy === "monthly" ? `${date.getUTCFullYear()}-${String(month + 1).padStart(2, "0")}` : `${date.getUTCFullYear()}-Q${Math.floor(month / 3) + 1}`;
+};
+/**
+* Picks the sampled subset of commits for a policy. `commits` must be ordered
+* newest first (as `git log` emits them); period policies keep the newest
+* commit of each period, so HEAD is always included.
+*/
+var sampleCommits = (commits, policy) => {
+	if (policy === "all") return [...commits];
+	if (typeof policy === "object") return commits.filter((_, index) => index % policy.everyNth === 0);
+	const seenBuckets = /* @__PURE__ */ new Set();
+	const sampled = [];
+	for (const commit of commits) {
+		const bucket = bucketOf(policy, commit.authorDate);
+		if (!seenBuckets.has(bucket)) {
+			seenBuckets.add(bucket);
+			sampled.push(commit);
+		}
+	}
+	return sampled;
+};
+//#endregion
 //#region src/commands/collectors.ts
-var samplingLabel$1 = (policy) => typeof policy === "object" ? `every-nth:${policy.everyNth}` : policy;
 var collectorsCommand = make$3("collectors").pipe(withDescription("List available collectors, their versions, strategies and default sampling"), withHandler(() => gen(function* () {
 	for (const collector of builtInCollectors) yield* log([
 		`${collector.name} (v${collector.version})`,
-		`  strategy: ${collector.strategy}, sampling: ${samplingLabel$1(collector.defaultSampling)}`,
+		`  strategy: ${collector.strategy}, sampling: ${samplingLabel(collector.defaultSampling)}`,
 		`  ${collector.description}`
 	].join("\n"));
 })));
@@ -53817,6 +53945,7 @@ var runIndex = ({ repoPath }) => gen(function* () {
 	const commitsPath = path.join(catalogPath, "commits");
 	const registry = new Map(builtInCollectors.map((collector) => [collector.name, collector]));
 	const gitCommits = yield* listCommits(repoRoot);
+	const firstParentShas = yield* listFirstParentShas(repoRoot);
 	const catalogShas = new Set(yield* tryPromise({
 		try: async () => {
 			try {
@@ -53830,10 +53959,12 @@ var runIndex = ({ repoPath }) => gen(function* () {
 	const orderedCommits = gitCommits.toReversed().filter((commit) => catalogShas.has(commit.hash));
 	if (orderedCommits.length === 0) return yield* fail$3(/* @__PURE__ */ new Error(`No collected commits found in ${commitsPath} — run \`repo-dive scan\` first.`));
 	let unknownCollectorDirs = 0;
+	let offMainlineSnapshots = 0;
 	const commitFacts = [];
 	yield* forEach$1(orderedCommits, (commit) => tryPromise({
 		try: async () => {
 			const commitDir = path.join(commitsPath, commit.hash);
+			const onMainline = firstParentShas.has(commit.hash);
 			const factsByCollector = /* @__PURE__ */ new Map();
 			for (const collectorName of await readdir(commitDir)) {
 				const collector = registry.get(collectorName);
@@ -53841,6 +53972,10 @@ var runIndex = ({ repoPath }) => gen(function* () {
 					unknownCollectorDirs += 1;
 					continue;
 				}
+				if (!onMainline && describesTreeState(collector)) {
+					offMainlineSnapshots += 1;
+					continue;
+				}
 				const raw = JSON.parse(await readFile(path.join(commitDir, collectorName, "output.json"), "utf8"));
 				factsByCollector.set(collectorName, collector.normalize(raw));
 			}
@@ -53882,7 +54017,8 @@ var runIndex = ({ repoPath }) => gen(function* () {
 		`Indexed ${commitFacts.length} commits into ${factCount} facts.`,
 		`Cube: ${dbPath}`,
 		`Dashboard data: ${dashboardPath}`,
-		...unknownCollectorDirs > 0 ? [`Skipped ${unknownCollectorDirs} outputs from unknown collectors (see \`gc --stale\`).`] : []
+		...unknownCollectorDirs > 0 ? [`Skipped ${unknownCollectorDirs} outputs from unknown collectors (see \`gc --stale\`).`] : [],
+		...offMainlineSnapshots > 0 ? [`Skipped ${offMainlineSnapshots} tree snapshots taken off HEAD's first-parent chain.`] : []
 	].join("\n"));
 });
 //#endregion
@@ -54035,50 +54171,6 @@ var loadConfig = (repoRoot) => gen(function* () {
 	});
 });
 //#endregion
-//#region src/lib/sampling.ts
-var parseSamplingPolicy = (input) => {
-	if (input === "all" || input === "weekly" || input === "monthly" || input === "quarterly") return input;
-	const everyNthMatch = /^every-nth:(\d+)$/.exec(input);
-	if (everyNthMatch?.[1]) {
-		const everyNth = Number(everyNthMatch[1]);
-		if (everyNth >= 1) return { everyNth };
-	}
-	return /* @__PURE__ */ new Error(`Unknown sampling policy: ${input}. Expected all, weekly, monthly, quarterly or every-nth:<n>.`);
-};
-var isoWeekOf = (date) => {
-	const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
-	const dayOfWeek = utc.getUTCDay() || 7;
-	utc.setUTCDate(utc.getUTCDate() + 4 - dayOfWeek);
-	const yearStart = Date.UTC(utc.getUTCFullYear(), 0, 1);
-	const week = Math.ceil(((utc.getTime() - yearStart) / 864e5 + 1) / 7);
-	return `${utc.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
-};
-var bucketOf = (policy, authorDate) => {
-	const date = new Date(authorDate);
-	if (policy === "weekly") return isoWeekOf(date);
-	const month = date.getUTCMonth();
-	return policy === "monthly" ? `${date.getUTCFullYear()}-${String(month + 1).padStart(2, "0")}` : `${date.getUTCFullYear()}-Q${Math.floor(month / 3) + 1}`;
-};
-/**
-* Picks the sampled subset of commits for a policy. `commits` must be ordered
-* newest first (as `git log` emits them); period policies keep the newest
-* commit of each period, so HEAD is always included.
-*/
-var sampleCommits = (commits, policy) => {
-	if (policy === "all") return [...commits];
-	if (typeof policy === "object") return commits.filter((_, index) => index % policy.everyNth === 0);
-	const seenBuckets = /* @__PURE__ */ new Set();
-	const sampled = [];
-	for (const commit of commits) {
-		const bucket = bucketOf(policy, commit.authorDate);
-		if (!seenBuckets.has(bucket)) {
-			seenBuckets.add(bucket);
-			sampled.push(commit);
-		}
-	}
-	return sampled;
-};
-//#endregion
 //#region src/lib/worktree.ts
 var toError$4 = (error) => error instanceof Error ? error : new Error(String(error));
 /**
@@ -54157,6 +54249,18 @@ var listCommits = (repoRoot) => runGit([
 	"log",
 	`--format=${gitLogFormat}`
 ]).pipe(catch_$2((error) => error instanceof GitCommandError && error.stderr.includes("does not have any commits yet") ? succeed$3("") : fail$3(error)), map$7(parseGitLog));
+/**
+* Shas on HEAD's first-parent chain, i.e. the states the repository actually
+* passed through. See {@link describesTreeState} for why snapshot collectors
+* are restricted to them.
+*/
+var listFirstParentShas = (repoRoot) => runGit([
+	"-C",
+	repoRoot,
+	"log",
+	"--first-parent",
+	"--format=%H"
+]).pipe(catch_$2((error) => error instanceof GitCommandError && error.stderr.includes("does not have any commits yet") ? succeed$3("") : fail$3(error)), map$7((stdout) => new Set(stdout.split("\n").filter(Boolean))));
 var summarizeCommits = (commits) => {
 	const authorEmails = new Set(commits.map((commit) => commit.authorEmail));
 	const dates = commits.map((commit) => commit.authorDate).filter(Boolean).toSorted();
@@ -54220,7 +54324,6 @@ var collectCommit = ({ catalog, sha, collectors, cacheKeyOf, force, failures })
 		skipped
 	};
 });
-var samplingLabel = (policy) => typeof policy === "object" ? `every-nth:${policy.everyNth}` : policy;
 var runScan = ({ repoPath, collectorNames, maxCommits, sample, force = false }) => gen(function* () {
 	const collectors = resolveCollectors(collectorNames);
 	if (collectors instanceof Error) return yield* fail$3(collectors);
@@ -54238,12 +54341,14 @@ var runScan = ({ repoPath, collectorNames, maxCommits, sample, force = false })
 	const config = yield* loadConfig(repoRoot);
 	const cacheKeys = new Map(collectors.map((collector) => [collector.name, collectorCacheKey(collector, config)]));
 	const cacheKeyOf = (collector) => cacheKeys.get(collector.name) ?? collectorCacheKey(collector, config);
+	const firstParentShas = yield* listFirstParentShas(repoRoot);
 	const plans = collectors.map((collector) => {
 		const policy = sampleOverride ?? collector.defaultSampling;
+		const candidates = describesTreeState(collector) ? selected.filter((commit) => firstParentShas.has(commit.hash)) : selected;
 		return {
 			collector,
 			policy,
-			shas: new Set(sampleCommits(selected, policy).map((commit) => commit.hash))
+			shas: new Set(sampleCommits(candidates, policy).map((commit) => commit.hash))
 		};
 	});
 	yield* log(`Plan: ${plans.map((plan) => `${plan.collector.name} → ${plan.shas.size} commits (${samplingLabel(plan.policy)})`).join(", ")}`);
@@ -54428,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) {
@@ -54441,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({
@@ -54461,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({
@@ -54497,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) {
@@ -54510,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: {
@@ -54534,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) {
@@ -54554,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;
 	}
@@ -54572,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,
@@ -59199,6 +59356,7 @@ var exists = (filePath) => promise(() => access(filePath).then(() => true, () =>
 var runStatus = ({ repoPath }) => gen(function* () {
 	const repoRoot = yield* resolveRepoRoot(repoPath);
 	const commits = yield* listCommits(repoRoot);
+	const firstParentShas = yield* listFirstParentShas(repoRoot);
 	const config = yield* loadConfig(repoRoot);
 	const catalogPath = path.join(repoRoot, catalogDirName);
 	if (!(yield* exists(path.join(catalogPath, "catalog.json")))) {
@@ -59220,15 +59378,16 @@ var runStatus = ({ repoPath }) => gen(function* () {
 		`Catalog: ${catalogPath}`
 	];
 	for (const collector of builtInCollectors) {
+		const target = sampleCommits(describesTreeState(collector) ? commits.filter((commit) => firstParentShas.has(commit.hash)) : commits, collector.defaultSampling);
 		let collected = 0;
 		const cacheKey = collectorCacheKey(collector, config);
-		yield* forEach$1(commits, (commit) => isCollected(catalog, commit.hash, collector, cacheKey).pipe(map$7((done) => {
+		yield* forEach$1(target, (commit) => isCollected(catalog, commit.hash, collector, cacheKey).pipe(map$7((done) => {
 			if (done) collected += 1;
 		})), {
 			concurrency: 16,
 			discard: true
 		});
-		lines.push(`  ${collector.name}: ${collected}/${commits.length} commits collected`);
+		lines.push(collector.defaultSampling === "all" ? `  ${collector.name}: ${collected}/${target.length} commits collected` : `  ${collector.name}: ${collected}/${target.length} commits collected (${samplingLabel(collector.defaultSampling)} sample of ${commits.length})`);
 	}
 	yield* log(lines.join("\n"));
 });

package/dist/config.d.ts

@@ -15,8 +15,8 @@
  *       ["alice@work.example", "alice@personal.example"],
  *       // Rich form: a display name, a profile link and a kind.
  *       {
- *         emails: ["bob@work.example", "bob@personal.example"],
  *         displayName: "Bob",
+ *         emails: ["bob@work.example", "bob@personal.example"],
  *         url: "https://github.com/bob",
  *       },
  *     ],

package/dist/config.js

@@ -15,8 +15,8 @@
  *       ["alice@work.example", "alice@personal.example"],
  *       // Rich form: a display name, a profile link and a kind.
  *       {
- *         emails: ["bob@work.example", "bob@personal.example"],
  *         displayName: "Bob",
+ *         emails: ["bob@work.example", "bob@personal.example"],
  *         url: "https://github.com/bob",
  *       },
  *     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-dive",
-  "version": "0.4.0",
+  "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",