@monoes/monograph 1.2.0 → 1.2.2

package/src/graph/loader.ts

@@ -18,24 +18,27 @@ export function loadGraphFromEdges(edges: MonographEdge[]): Graph {
 
 export function loadGraphFromDb(db: import('../storage/db.js').MonographDb): Graph {
   const nodes = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
-  const edges = db.prepare('SELECT * FROM edges').all() as {
+  // Explicitly select only the columns used here — avoids fetching reason/evidence blobs
+  const edges = db.prepare(
+    'SELECT id, source_id, target_id, relation, confidence, confidence_score FROM edges'
+  ).all() as {
     id: string; source_id: string; target_id: string; relation: string;
     confidence: string; confidence_score: number;
   }[];
 
   const graph = new Graph({ multi: true, type: 'directed' });
-  for (const n of nodes) {
-    if (!graph.hasNode(n.id)) graph.addNode(n.id);
-  }
+  // Seed known nodes first; edges below may reference node ids not in the nodes table
+  // (defensive: addNode is a no-op guard here, has-check avoided to reduce overhead)
+  for (const n of nodes) graph.mergeNode(n.id);
   for (const e of edges) {
-    if (!graph.hasNode(e.source_id)) graph.addNode(e.source_id);
-    if (!graph.hasNode(e.target_id)) graph.addNode(e.target_id);
+    graph.mergeNode(e.source_id);
+    graph.mergeNode(e.target_id);
     try {
       graph.addEdge(e.source_id, e.target_id, {
         id: e.id, relation: e.relation,
         confidence: e.confidence, confidenceScore: e.confidence_score,
       });
-    } catch { /* skip */ }
+    } catch { /* skip duplicate edges */ }
   }
   return graph;
 }

package/src/graph/maintainability.ts

@@ -46,35 +46,36 @@ export function computeMaintainabilityIndex(db: MonographDb): MaintainabilityRep
     return { results: [], averageMi: 100, lowMiCount: 0, criticalCount: 0 };
   }
 
+  // ── Batch degree lookup: one query replaces 2×N individual queries ────────
+  // Combine in-degree and out-degree via UNION ALL + GROUP BY in a single pass.
+  const degreeMap = new Map<string, number>();
+  for (const { node_id, deg } of db.prepare(`
+    SELECT node_id, SUM(cnt) as deg FROM (
+      SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
+      UNION ALL
+      SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
+    ) GROUP BY node_id
+  `).all() as { node_id: string; deg: number }[]) {
+    degreeMap.set(node_id, deg);
+  }
+
   const results: MaintainabilityResult[] = [];
+  const propUpdates: Array<{ id: string; props: string }> = [];
 
   for (const node of nodes) {
     const loc = Math.max(1, node.end_line - node.start_line + 1);
-
-    // Count in/out degree from edges table
-    const inDegreeRow = db.prepare(
-      'SELECT COUNT(*) as c FROM edges WHERE target_id = ?'
-    ).get(node.id) as { c: number };
-    const outDegreeRow = db.prepare(
-      'SELECT COUNT(*) as c FROM edges WHERE source_id = ?'
-    ).get(node.id) as { c: number };
-
-    const degree = inDegreeRow.c + outDegreeRow.c;
+    const degree = degreeMap.get(node.id) ?? 0;
     const hvProxy = degree * Math.log2(Math.max(degree, 2));
 
     // Maintainability Index formula
     const rawMi = 171 - 5.2 * Math.log(hvProxy + 1) - 0.23 * (loc / 10) - 16.2 * Math.log(Math.max(1, loc));
     const mi = Math.max(0, Math.min(100, rawMi));
-
     const grade = gradeFromMi(mi);
 
-    // Store maintainabilityIndex back on the node's properties
-    const props = node.properties ? JSON.parse(node.properties) : {};
+    // Stage property update — batched below
+    const props: Record<string, unknown> = node.properties ? JSON.parse(node.properties) : {};
     props.maintainabilityIndex = mi;
-    db.prepare('UPDATE nodes SET properties = ? WHERE id = ?').run(
-      JSON.stringify(props),
-      node.id
-    );
+    propUpdates.push({ id: node.id, props: JSON.stringify(props) });
 
     results.push({
       nodeId: node.id,
@@ -87,6 +88,12 @@ export function computeMaintainabilityIndex(db: MonographDb): MaintainabilityRep
     });
   }
 
+  // ── Batch UPDATE all property writes in one transaction ───────────────────
+  const updateStmt = db.prepare('UPDATE nodes SET properties = ? WHERE id = ?');
+  db.transaction((updates: typeof propUpdates) => {
+    for (const { id, props } of updates) updateStmt.run(props, id);
+  })(propUpdates);
+
   // Sort by MI ascending (worst first)
   results.sort((a, b) => a.mi - b.mi);
 
@@ -94,13 +101,56 @@ export function computeMaintainabilityIndex(db: MonographDb): MaintainabilityRep
     ? results.reduce((sum, r) => sum + r.mi, 0) / results.length
     : 100;
 
-  const lowMiCount = results.filter(r => r.mi < 65).length;
-  const criticalCount = results.filter(r => r.mi < 25).length;
-
   return {
     results,
     averageMi: Math.round(averageMi * 100) / 100,
-    lowMiCount,
-    criticalCount,
+    lowMiCount: results.filter(r => r.mi < 65).length,
+    criticalCount: results.filter(r => r.mi < 25).length,
   };
 }
+
+/**
+ * Format a MaintainabilityReport as structured text with file:line hints for LLM navigation.
+ *
+ * @param report - MaintainabilityReport from computeMaintainabilityIndex()
+ * @param topN - number of worst files to list (default 10)
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatMaintainability(report: MaintainabilityReport, topN = 10): string {
+  const { results, averageMi, lowMiCount, criticalCount } = report;
+
+  if (results.length === 0) {
+    return 'maintainability: no Function/Method/Symbol nodes with line info found\n';
+  }
+
+  const lines: string[] = [
+    `maintainability: ${results.length} nodes analysed`,
+    `  avg_mi: ${averageMi}  low(mi<65): ${lowMiCount}  critical(mi<25): ${criticalCount}`,
+    '',
+  ];
+
+  // results already sorted by MI ascending (worst first)
+  const worst = results.slice(0, topN);
+  if (worst.length > 0) {
+    lines.push(`top_${topN}_worst_mi:`);
+    for (const r of worst) {
+      const loc = r.filePath ? `${r.filePath}:1` : `<unknown>:1`;
+      lines.push(`  - ${r.name}  grade:${r.grade}  mi:${r.mi}`);
+      lines.push(`    file: ${loc}`);
+      lines.push(`    loc: ${r.linesOfCode}  halstead_vol: ${r.halsteadVolume}`);
+    }
+    lines.push('');
+  }
+
+  const critical = results.filter(r => r.mi < 25);
+  if (critical.length > 0) {
+    lines.push(`critical_nodes(mi<25): ${critical.length}`);
+    for (const r of critical.slice(0, 5)) {
+      const loc = r.filePath ? `${r.filePath}:1` : `<unknown>:1`;
+      lines.push(`  - ${r.name}  file: ${loc}  mi:${r.mi}  grade:${r.grade}`);
+    }
+    if (critical.length > 5) lines.push(`  ... and ${critical.length - 5} more`);
+  }
+
+  return lines.join('\n');
+}

package/src/graph/mirrored-dirs.ts

@@ -126,18 +126,30 @@ export function detectMirroredFamilies(
       const fa = families[i];
       const fb = families[j];
 
-      const dirsA = new Set(fa.files.map(dirOf));
-      const dirsB = new Set(fb.files.map(dirOf));
-
-      if (dirsA.size !== 1 || dirsB.size !== 1) continue;
-
-      const [dirA] = dirsA;
-      const [dirB] = dirsB;
+      // Single pass: extract dir and basename together to avoid two separate .map() iterations
+      let firstDirA: string | undefined;
+      let singleDirA = true;
+      let firstDirB: string | undefined;
+      let singleDirB = true;
+      const namesA = new Set<string>();
+      const namesB = new Set<string>();
+      for (const f of fa.files) {
+        const d = dirOf(f);
+        if (firstDirA === undefined) firstDirA = d;
+        else if (d !== firstDirA) { singleDirA = false; }
+        namesA.add(baseName(f));
+      }
+      for (const f of fb.files) {
+        const d = dirOf(f);
+        if (firstDirB === undefined) firstDirB = d;
+        else if (d !== firstDirB) { singleDirB = false; }
+        namesB.add(baseName(f));
+      }
 
-      if (dirA === dirB) continue;
+      if (!singleDirA || !singleDirB) continue;
 
-      const namesA = new Set(fa.files.map(baseName));
-      const namesB = new Set(fb.files.map(baseName));
+      const dirA = firstDirA!;
+      const dirB = firstDirB!;
 
       const shared: string[] = [];
       for (const n of namesA) {
@@ -164,8 +176,27 @@ export function detectMirroredFamilies(
 
   mirrored.sort((a, b) => b.similarity - a.similarity);
 
-  return {
-    mirrored,
-    remaining: [...remainingIndices].map(i => families[i]),
-  };
+  const remaining: CloneFamily[] = [];
+  for (const i of remainingIndices) remaining.push(families[i]);
+
+  return { mirrored, remaining };
+}
+
+/**
+ * Format a MirroredDirsReport as structured text for LLM consumption.
+ */
+export function formatMirroredDirs(report: MirroredDirsReport): string {
+  if (report.pairs.length === 0) {
+    return `No mirrored directories found (${report.totalDirsAnalyzed} dirs analyzed).`;
+  }
+  const lines: string[] = [
+    `Mirrored directories: ${report.pairs.length} pair(s) of ${report.totalDirsAnalyzed} analyzed`,
+    '',
+  ];
+  for (const p of report.pairs) {
+    lines.push(
+      `  ${p.dirA} <-> ${p.dirB}  similarity=${(p.similarity * 100).toFixed(0)}%  shared=${p.sharedFileNames.length}  uniqueA=${p.uniqueToA}  uniqueB=${p.uniqueToB}`,
+    );
+  }
+  return lines.join('\n');
 }

package/src/graph/narrowing.ts

@@ -46,3 +46,47 @@ export function markMemberExportsReferenced(
   }
   return result;
 }
+
+export interface NarrowingReport {
+  filePath: string;
+  totalExports: number;
+  referencedExports: string[];
+  unusedExports: string[];
+}
+
+/**
+ * Given a file's exports and the accessed members from all import sites,
+ * return a report of which exports are unused.
+ */
+export function filterUnusedExports(
+  filePath: string,
+  exports: string[],
+  accessed: AccessedMembers,
+): NarrowingReport {
+  const referenced = markMemberExportsReferenced(exports, accessed);
+  const unusedExports: string[] = [];
+  for (const exp of exports) {
+    if (!referenced.has(exp)) unusedExports.push(exp);
+  }
+  return {
+    filePath,
+    totalExports: exports.length,
+    referencedExports: Array.from(referenced),
+    unusedExports,
+  };
+}
+
+/**
+ * Format narrowing reports as structured text for LLM dead-import diagnostics.
+ */
+export function formatNarrowingReport(reports: NarrowingReport[]): string {
+  const withUnused = reports.filter(r => r.unusedExports.length > 0);
+  if (withUnused.length === 0) return 'No unused exports found.';
+
+  const lines: string[] = [`Unused exports in ${withUnused.length} file(s):`, ''];
+  for (const r of withUnused) {
+    lines.push(`  ${r.filePath} (${r.unusedExports.length}/${r.totalExports} unused)`);
+    for (const exp of r.unusedExports) lines.push(`    - ${exp}`);
+  }
+  return lines.join('\n');
+}

package/src/graph/node-search.ts

@@ -1,3 +1,4 @@
+import Database from 'better-sqlite3';
 import type { MonographNode, NodeLabel } from '../types.js';
 import type { MonographDb } from '../storage/db.js';
 
@@ -50,11 +51,39 @@ function rowToNode(r: {
   };
 }
 
+// ── Prepared statement cache ───────────────────────────────────────────────────
+// Keyed by a fingerprint of which conditions are active (not by param values),
+// so the same query shape reuses the compiled statement across calls.
+
+// WeakMap ensures the cache is garbage-collected when the DB object is released.
+const stmtCache = new WeakMap<object, Map<string, Database.Statement>>();
+
+function getCachedStmt(
+  db: MonographDb,
+  key: string,
+  buildSql: () => string,
+): Database.Statement {
+  let dbCache = stmtCache.get(db);
+  if (!dbCache) {
+    dbCache = new Map();
+    stmtCache.set(db, dbCache);
+  }
+  let stmt = dbCache.get(key);
+  if (!stmt) {
+    stmt = db.prepare(buildSql());
+    dbCache.set(key, stmt);
+  }
+  return stmt;
+}
+
 // ── DB-backed search ───────────────────────────────────────────────────────────
 
 /**
  * Search nodes by structured property criteria.
  * All supplied criteria are combined with AND.
+ *
+ * Prepared statements are cached per-DB keyed by the active condition set so
+ * repeated calls with the same filter shape reuse the compiled statement.
  */
 export function searchNodesByProperty(
   db: MonographDb,
@@ -62,15 +91,19 @@ export function searchNodesByProperty(
 ): MonographNode[] {
   const conditions: string[] = [];
   const params: unknown[] = [];
+  // fingerprint encodes which conditions are active (not their values)
+  const fingerprint: string[] = [];
 
   if (options.label) {
     conditions.push('label = ?');
     params.push(options.label);
+    fingerprint.push('lbl');
   }
 
   if (options.language) {
     conditions.push('LOWER(language) = LOWER(?)');
     params.push(options.language);
+    fingerprint.push('lang');
   }
 
   if (options.fileExtension !== undefined) {
@@ -80,30 +113,43 @@ export function searchNodesByProperty(
       : `.${options.fileExtension}`;
     conditions.push("file_path LIKE ?");
     params.push(`%${ext}`);
+    fingerprint.push('ext');
   }
 
   if (options.filePath !== undefined) {
     conditions.push("LOWER(file_path) LIKE LOWER(?)");
     params.push(`%${options.filePath}%`);
+    fingerprint.push('fp');
   }
 
   if (options.isExported !== undefined) {
     conditions.push('is_exported = ?');
     params.push(options.isExported ? 1 : 0);
+    fingerprint.push('exp');
   }
 
   if (options.communityId !== undefined) {
     conditions.push('community_id = ?');
     params.push(options.communityId);
+    fingerprint.push('com');
   }
 
+  const hasLimit = options.limit !== undefined;
+  if (hasLimit) fingerprint.push('lim');
+
   const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
-  const limitClause = options.limit !== undefined ? `LIMIT ${Number(options.limit)}` : '';
-  const sql = `SELECT id, label, name, norm_label, file_path, start_line, end_line,
+  const limitClause = hasLimit ? `LIMIT ${Number(options.limit)}` : '';
+  const cacheKey = fingerprint.join(':') || 'all';
+
+  const stmt = getCachedStmt(
+    db,
+    cacheKey,
+    () => `SELECT id, label, name, norm_label, file_path, start_line, end_line,
                       community_id, is_exported, language, properties
-               FROM nodes ${where} ${limitClause}`;
+               FROM nodes ${where} ${limitClause}`,
+  );
 
-  const rows = db.prepare(sql).all(...params) as Parameters<typeof rowToNode>[0][];
+  const rows = stmt.all(...params) as Parameters<typeof rowToNode>[0][];
   return rows.map(rowToNode);
 }
 

package/src/graph/normalize-id.ts

@@ -87,8 +87,9 @@ export function reconcileEdges(
     let remapped = false;
 
     if (!nodeIds.has(src)) {
+      // Cache normalizeId result to avoid calling it twice for the same string
       const canonical = normToId.get(normalizeId(src));
-      if (canonical) {
+      if (canonical !== undefined) {
         src = canonical;
         remapped = true;
       }
@@ -96,7 +97,7 @@ export function reconcileEdges(
 
     if (!nodeIds.has(tgt)) {
       const canonical = normToId.get(normalizeId(tgt));
-      if (canonical) {
+      if (canonical !== undefined) {
         tgt = canonical;
         remapped = true;
       }
@@ -112,3 +113,26 @@ export function reconcileEdges(
 
   return { resolved, dangling, remappedCount };
 }
+
+/**
+ * Format a ReconciliationResult as structured text for LLM consumption.
+ */
+export function formatReconciliationResult(result: ReconciliationResult): string {
+  const total = result.resolved.length + result.dangling.length;
+  const lines: string[] = [
+    `Edge reconciliation: ${result.resolved.length}/${total} resolved, ${result.remappedCount} remapped, ${result.dangling.length} dangling`,
+  ];
+  if (result.dangling.length > 0) {
+    lines.push('');
+    lines.push('Dangling edges (unresolvable endpoints):');
+    const limit = Math.min(result.dangling.length, 20);
+    for (let i = 0; i < limit; i++) {
+      const e = result.dangling[i]!;
+      lines.push(`  ${e.source} -> ${e.target}`);
+    }
+    if (result.dangling.length > limit) {
+      lines.push(`  ... and ${result.dangling.length - limit} more`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/graph/pagerank.ts

@@ -1,3 +1,4 @@
+import Database from 'better-sqlite3';
 import type { MonographDb } from '../storage/db.js';
 
 export interface PageRankOptions {
@@ -9,6 +10,59 @@ export interface PageRankOptions {
   tolerance?: number;
 }
 
+// ---------------------------------------------------------------------------
+// Per-DB statement cache — avoids recompiling SQL on every pageRank() call.
+// ---------------------------------------------------------------------------
+interface StmtCache {
+  selectNodes: Database.Statement;
+  selectEdges: Database.Statement;
+}
+
+const _stmtCache = new Map<string, StmtCache>();
+
+function getStmts(db: MonographDb): StmtCache {
+  const key = (db as unknown as { name: string }).name ?? '__default__';
+  let cache = _stmtCache.get(key);
+  if (!cache) {
+    cache = {
+      selectNodes: db.prepare('SELECT id FROM nodes'),
+      selectEdges: db.prepare('SELECT source_id, target_id FROM edges'),
+    };
+    _stmtCache.set(key, cache);
+  }
+  return cache;
+}
+
+// ---------------------------------------------------------------------------
+// Result cache — avoids re-running power iteration when the graph hasn't
+// changed. Keyed by (dbName, nodeCount, edgeCount) with a 5-second TTL.
+// ---------------------------------------------------------------------------
+const PAGERANK_CACHE_TTL_MS = 5_000;
+
+interface PageRankCacheEntry {
+  result: Map<string, number>;
+  expiresAt: number;
+}
+
+const _resultCache = new Map<string, PageRankCacheEntry>();
+
+function resultCacheKey(db: MonographDb, nodeCount: number, edgeCount: number): string {
+  const name = (db as unknown as { name: string }).name ?? '__default__';
+  return `${name}:${nodeCount}:${edgeCount}`;
+}
+
+/**
+ * Evict cached statements and results for a given DB instance (call after writes).
+ */
+export function invalidatePageRankCache(db: MonographDb): void {
+  const key = (db as unknown as { name: string }).name ?? '__default__';
+  _stmtCache.delete(key);
+  // Purge all result-cache entries for this DB (they have the name as prefix)
+  for (const k of _resultCache.keys()) {
+    if (k.startsWith(`${key}:`)) _resultCache.delete(k);
+  }
+}
+
 /**
  * Compute PageRank scores for all nodes using power iteration.
  *
@@ -16,6 +70,9 @@ export interface PageRankOptions {
  * After convergence the scores still sum to ~1 (standard normalized PageRank).
  * Dangling nodes (out-degree 0) distribute their rank equally to all nodes.
  *
+ * Results are cached for 5 seconds when the graph's node+edge counts are
+ * unchanged, making repeated calls (e.g. during context preloading) free.
+ *
  * @param db - The MonographDb instance
  * @param options - Optional tuning parameters
  * @returns Map of nodeId → PageRank score
@@ -23,14 +80,21 @@ export interface PageRankOptions {
 export function pageRank(db: MonographDb, options: PageRankOptions = {}): Map<string, number> {
   const { dampingFactor = 0.85, maxIterations = 100, tolerance = 1e-6 } = options;
 
-  const nodeRows = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
-  const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
+  const stmts = getStmts(db);
+  const nodeRows = stmts.selectNodes.all() as { id: string }[];
+  const edgeRows = stmts.selectEdges.all() as {
     source_id: string;
     target_id: string;
   }[];
 
   if (nodeRows.length === 0) return new Map();
 
+  // Check result cache before running power iteration
+  const cacheKey = resultCacheKey(db, nodeRows.length, edgeRows.length);
+  const now = Date.now();
+  const cached = _resultCache.get(cacheKey);
+  if (cached && now < cached.expiresAt) return cached.result;
+
   const nodes = nodeRows.map(r => r.id);
   const n = nodes.length;
   const nodeIndex = new Map<string, number>();
@@ -84,5 +148,9 @@ export function pageRank(db: MonographDb, options: PageRankOptions = {}): Map<st
   for (let i = 0; i < n; i++) {
     result.set(nodes[i], scores[i]);
   }
+
+  // Store in result cache
+  _resultCache.set(cacheKey, { result, expiresAt: now + PAGERANK_CACHE_TTL_MS });
+
   return result;
 }

package/src/graph/prune.ts

@@ -1,5 +1,11 @@
 import type { MonographDb } from '../storage/db.js';
 
+export interface PruneResult {
+  danglingEdgesRemoved: number;
+  orphanNodesRemoved: number;
+  staleFileNodesRemoved: number;
+}
+
 /**
  * Remove edges whose source or target node does not exist in the nodes table.
  *
@@ -17,3 +23,73 @@ export function pruneDanglingEdges(db: MonographDb): number {
 
   return result.changes;
 }
+
+/**
+ * Remove non-File nodes that have no incoming or outgoing edges.
+ * Leaves File nodes in place so they can still be queried even if isolated.
+ *
+ * @param db - The MonographDb instance
+ * @returns Number of orphan nodes removed
+ */
+export function pruneOrphanNodes(db: MonographDb): number {
+  const result = db.prepare(`
+    DELETE FROM nodes
+    WHERE label != 'File'
+      AND NOT EXISTS (SELECT 1 FROM edges WHERE source_id = nodes.id OR target_id = nodes.id)
+  `).run();
+  return result.changes;
+}
+
+/**
+ * Remove File nodes whose file_path no longer exists on disk.
+ * Also cascades to remove any edges connected to those nodes (via pruneDanglingEdges).
+ *
+ * @param db - The MonographDb instance
+ * @param existingPaths - Set of file paths that currently exist on disk
+ * @returns Number of stale File nodes removed (call pruneDanglingEdges after to clean edges)
+ */
+export function pruneStaleFileNodes(db: MonographDb, existingPaths: Set<string>): number {
+  const staleRows = db.prepare(
+    `SELECT id, file_path FROM nodes WHERE label = 'File' AND file_path IS NOT NULL`,
+  ).all() as { id: string; file_path: string }[];
+
+  let removed = 0;
+  const deleteStmt = db.prepare(`DELETE FROM nodes WHERE id = ?`);
+  const tx = db.transaction(() => {
+    for (const row of staleRows) {
+      if (!existingPaths.has(row.file_path)) {
+        deleteStmt.run(row.id);
+        removed++;
+      }
+    }
+  });
+  tx();
+  return removed;
+}
+
+/**
+ * Run a full prune pass: dangling edges → orphan nodes → stale file nodes.
+ * Optionally pass existingPaths to also remove deleted-file nodes.
+ */
+export function pruneAll(db: MonographDb, existingPaths?: Set<string>): PruneResult {
+  const danglingEdgesRemoved = pruneDanglingEdges(db);
+  const orphanNodesRemoved = pruneOrphanNodes(db);
+  const staleFileNodesRemoved = existingPaths ? pruneStaleFileNodes(db, existingPaths) : 0;
+  // A second dangling-edge pass cleans up any edges left by stale file node removal
+  if (staleFileNodesRemoved > 0) pruneDanglingEdges(db);
+  return { danglingEdgesRemoved, orphanNodesRemoved, staleFileNodesRemoved };
+}
+
+/**
+ * Format a PruneResult as structured text for LLM consumption.
+ */
+export function formatPruneResult(result: PruneResult): string {
+  const total = result.danglingEdgesRemoved + result.orphanNodesRemoved + result.staleFileNodesRemoved;
+  if (total === 0) return 'Prune pass: nothing to remove — graph is clean.';
+  return [
+    `Prune pass removed ${total} artifact(s):`,
+    `  dangling edges:    ${result.danglingEdgesRemoved}`,
+    `  orphan nodes:      ${result.orphanNodesRemoved}`,
+    `  stale file nodes:  ${result.staleFileNodesRemoved}`,
+  ].join('\n');
+}