@monoes/monograph 1.2.0 → 1.2.2

package/src/graph/dead-code.ts

@@ -11,35 +11,94 @@ import type { MonographDb } from '../storage/db.js';
  * @returns Array of node ids that are considered dead code.
  */
 export function detectDeadCode(db: MonographDb): string[] {
-  const nodeRows = db.prepare('SELECT id, is_exported FROM nodes').all() as {
+  return detectDeadCodeNodes(db).map(n => n.id);
+}
+
+// ---------------------------------------------------------------------------
+
+export interface DeadCodeNode {
+  id: string;
+  name: string;
+  filePath: string | null;
+  startLine: number | null;
+  label: string;
+}
+
+/**
+ * Like detectDeadCode() but returns rich node objects with filePath and
+ * startLine so callers can render file:line navigation hints.
+ *
+ * @param db - The MonographDb instance
+ * @returns Array of dead-code nodes with location metadata.
+ */
+export function detectDeadCodeNodes(db: MonographDb): DeadCodeNode[] {
+  const nodeRows = db
+    .prepare('SELECT id, name, file_path, start_line, label, is_exported FROM nodes')
+    .all() as {
     id: string;
+    name: string;
+    file_path: string | null;
+    start_line: number | null;
+    label: string;
     is_exported: number;
   }[];
 
   if (nodeRows.length === 0) return [];
 
-  // Count in-degrees
+  // Count in-degrees via a single SQL aggregation — avoids loading all edges into JS
+  const inDegreeRows = db
+    .prepare(
+      'SELECT target_id, COUNT(*) AS cnt FROM edges WHERE source_id != target_id GROUP BY target_id',
+    )
+    .all() as { target_id: string; cnt: number }[];
+
   const inDegree = new Map<string, number>();
-  for (const { id } of nodeRows) {
-    inDegree.set(id, 0);
+  for (const { target_id, cnt } of inDegreeRows) {
+    inDegree.set(target_id, cnt);
   }
 
-  const edgeRows = db.prepare('SELECT target_id FROM edges WHERE source_id != target_id').all() as {
-    target_id: string;
-  }[];
-
-  for (const { target_id } of edgeRows) {
-    if (inDegree.has(target_id)) {
-      inDegree.set(target_id, (inDegree.get(target_id) ?? 0) + 1);
+  const dead: DeadCodeNode[] = [];
+  for (const row of nodeRows) {
+    if ((inDegree.get(row.id) ?? 0) === 0 && row.is_exported !== 1) {
+      dead.push({
+        id: row.id,
+        name: row.name,
+        filePath: row.file_path,
+        startLine: row.start_line,
+        label: row.label,
+      });
     }
   }
 
-  const dead: string[] = [];
-  for (const { id, is_exported } of nodeRows) {
-    if ((inDegree.get(id) ?? 0) === 0 && is_exported !== 1) {
-      dead.push(id);
-    }
+  return dead;
+}
+
+/**
+ * Format dead-code nodes as structured text for LLM consumption.
+ * Each entry includes a file:line navigation hint where available.
+ *
+ * @param nodes - Result from detectDeadCodeNodes()
+ * @returns Multi-line string suitable for injection into LLM context
+ */
+export function formatDeadCode(nodes: DeadCodeNode[]): string {
+  if (nodes.length === 0) {
+    return 'Dead code: none detected.';
   }
 
-  return dead;
+  const lines: string[] = [
+    `Dead code: ${nodes.length} unreachable node${nodes.length === 1 ? '' : 's'} detected`,
+    '',
+  ];
+
+  for (const node of nodes) {
+    const loc =
+      node.filePath != null
+        ? node.startLine != null
+          ? `${node.filePath}:${node.startLine}`
+          : node.filePath
+        : '(unknown location)';
+    lines.push(`  [${node.label}] ${node.name} — ${loc}`);
+  }
+
+  return lines.join('\n');
 }

package/src/graph/dependency-closure.ts

@@ -17,6 +17,8 @@ export interface DepClosureReport {
   deepDependencyFiles: DepClosureResult[];   // files with depDepth > 5
 }
 
+const SQLITE_VAR_LIMIT = 200; // safe batch size for IN clauses
+
 export function computeDependencyClosure(db: MonographDb, maxNodes = 100): DepClosureReport {
   // Get File nodes sorted by degree (most connected first)
   const fileNodes = (db.prepare(`
@@ -38,6 +40,12 @@ export function computeDependencyClosure(db: MonographDb, maxNodes = 100): DepCl
     `).all() as Array<{ file_path: string }>).map(r => r.file_path)
   );
 
+  // Hoist prepared statement outside the per-node BFS loop to avoid recompiling
+  // on every iteration (N×maxNodes calls previously).
+  const edgeStmt = db.prepare(
+    `SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`,
+  );
+
   const results: DepClosureResult[] = [];
 
   for (const fileNode of fileNodes) {
@@ -53,10 +61,7 @@ export function computeDependencyClosure(db: MonographDb, maxNodes = 100): DepCl
       depth++;
       const next: string[] = [];
       for (const id of frontier) {
-        const edges = db.prepare(
-          `SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`
-        ).all(id) as Array<{ target_id: string }>;
-
+        const edges = edgeStmt.all(id) as Array<{ target_id: string }>;
         for (const e of edges) {
           if (!visited.has(e.target_id)) {
             visited.add(e.target_id);
@@ -73,11 +78,23 @@ export function computeDependencyClosure(db: MonographDb, maxNodes = 100): DepCl
       frontier = next;
     }
 
+    // Batch-resolve file_paths for all transitive deps in one chunked SQL query
+    // instead of one SELECT per dep (N+1 → O(deps/CHUNK) queries).
+    const depFilePathMap = new Map<string, string | null>();
+    for (let i = 0; i < transitiveDeps.length; i += SQLITE_VAR_LIMIT) {
+      const chunk = transitiveDeps.slice(i, i + SQLITE_VAR_LIMIT);
+      const ph = chunk.map(() => '?').join(',');
+      const rows = db
+        .prepare(`SELECT id, file_path FROM nodes WHERE id IN (${ph})`)
+        .all(...chunk) as Array<{ id: string; file_path: string | null }>;
+      for (const row of rows) depFilePathMap.set(row.id, row.file_path);
+    }
+
     // unusedTransitiveDeps: transitive deps whose file_path is NOT in importedFilePaths
     const unusedTransitiveDeps = transitiveDeps.filter(depId => {
-      const depNode = db.prepare('SELECT file_path FROM nodes WHERE id = ?').get(depId) as { file_path: string | null } | undefined;
-      if (!depNode?.file_path) return false;
-      return !importedFilePaths.has(depNode.file_path);
+      const fp = depFilePathMap.get(depId);
+      if (!fp) return false;
+      return !importedFilePaths.has(fp);
     });
 
     results.push({

package/src/graph/dfs.ts

@@ -7,6 +7,12 @@ export interface DfsOptions {
   maxDepth?: number;
 }
 
+export interface DfsResult {
+  visited: DfsNode[];
+  maxDepth: number;
+  nodeCount: number;
+}
+
 export function dfsTraversal(
   startId: string,
   adjacency: Map<string, string[]>,
@@ -38,3 +44,75 @@ export function dfsTraversal(
     }
   }
 }
+
+/** Collect all reachable nodes from startId via DFS, returning structured result. */
+export function dfsCollect(
+  startId: string,
+  adjacency: Map<string, string[]>,
+  options: DfsOptions = {},
+): DfsResult {
+  const visited: DfsNode[] = [];
+  let maxReachedDepth = 0;
+  dfsTraversal(startId, adjacency, (node) => {
+    visited.push(node);
+    if (node.depth > maxReachedDepth) maxReachedDepth = node.depth;
+  }, options);
+  return { visited, maxDepth: maxReachedDepth, nodeCount: visited.length };
+}
+
+/** BFS level-order traversal — useful when shortest-path distance matters more than DFS order. */
+export function bfsTraversal(
+  startId: string,
+  adjacency: Map<string, string[]>,
+  visitor: (node: DfsNode) => void,
+  options: DfsOptions = {},
+): void {
+  if (!adjacency.has(startId)) return;
+
+  const { maxDepth = Infinity } = options;
+  const visited = new Set<string>([startId]);
+  const queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { id, depth } = queue.shift()!;
+    visitor({ id, depth });
+
+    if (depth < maxDepth) {
+      const neighbors = adjacency.get(id) ?? [];
+      for (let i = 0; i < neighbors.length; i++) {
+        const neighbor = neighbors[i]!;
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          queue.push({ id: neighbor, depth: depth + 1 });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Format a DfsResult as structured text for LLM consumption.
+ * Groups nodes by depth level for easy reading.
+ */
+export function formatDfsResult(result: DfsResult, startId: string): string {
+  if (result.nodeCount === 0) return `No nodes reachable from "${startId}".`;
+
+  const byDepth = new Map<number, string[]>();
+  for (const node of result.visited) {
+    let bucket = byDepth.get(node.depth);
+    if (!bucket) { bucket = []; byDepth.set(node.depth, bucket); }
+    bucket.push(node.id);
+  }
+
+  const lines: string[] = [
+    `DFS from "${startId}": ${result.nodeCount} nodes, max depth ${result.maxDepth}`,
+    '',
+  ];
+  // Iterate in depth order
+  const depths = Array.from(byDepth.keys()).sort((a, b) => a - b);
+  for (const depth of depths) {
+    const ids = byDepth.get(depth)!;
+    lines.push(`  depth ${depth}: ${ids.join(', ')}`);
+  }
+  return lines.join('\n');
+}

package/src/graph/duplication-stats.ts

@@ -39,11 +39,15 @@ export function computeDuplicationStats(
   }
 
   const filesWithClones = fileLines.size;
-  const duplicatedLines = [...fileLines.values()].reduce((s, set) => s + set.size, 0);
-  const duplicatedTokens = Math.min(
-    totalTokens,
-    groups.reduce((s, g) => s + g.instances.reduce((t, i) => t + (i.tokenCount ?? 0), 0), 0),
-  );
+  // Single-pass line count — avoids spread allocation over all file Sets
+  let duplicatedLines = 0;
+  for (const set of fileLines.values()) duplicatedLines += set.size;
+  // Single-pass token sum — avoids nested reduce and intermediate arrays
+  let rawTokens = 0;
+  for (const group of groups) {
+    for (const inst of group.instances) rawTokens += inst.tokenCount ?? 0;
+  }
+  const duplicatedTokens = Math.min(totalTokens, rawTokens);
 
   return {
     totalFiles: allFilePaths.length,
@@ -59,10 +63,17 @@ export function computeDuplicationStats(
 }
 
 export function formatDuplicationStats(stats: DuplicationStats): string {
+  const pct = stats.duplicationPct;
+  const grade = pct < 5 ? 'A' : pct < 10 ? 'B' : pct < 20 ? 'C' : pct < 30 ? 'D' : 'F';
+  const tokenPct = stats.totalTokens > 0
+    ? ((stats.duplicatedTokens / stats.totalTokens) * 100).toFixed(1)
+    : '0.0';
   return [
+    `Duplication grade: ${grade} (${pct.toFixed(1)}% duplicated lines)`,
     `Clone groups:      ${stats.cloneGroups}`,
     `Clone instances:   ${stats.cloneInstances}`,
     `Files with clones: ${stats.filesWithClones} / ${stats.totalFiles}`,
-    `Duplicated lines:  ${stats.duplicatedLines} / ${stats.totalLines} (${stats.duplicationPct.toFixed(1)}%)`,
+    `Duplicated lines:  ${stats.duplicatedLines} / ${stats.totalLines} (${pct.toFixed(1)}%)`,
+    `Duplicated tokens: ${stats.duplicatedTokens} / ${stats.totalTokens} (${tokenPct}%)`,
   ].join('\n');
 }

package/src/graph/edge-filter.ts

@@ -85,19 +85,33 @@ export function filterEdgesInMemory(
   edges: MonographEdge[],
   options: EdgeFilterOptions = {},
 ): MonographEdge[] {
+  // Convert arrays to Sets once before the loop for O(1) membership checks
+  const relationSet = options.relations && options.relations.length > 0
+    ? new Set(options.relations) : null;
+  const confidenceSet = options.confidences && options.confidences.length > 0
+    ? new Set(options.confidences) : null;
+  const minScore = options.minConfidenceScore;
+  const maxScore = options.maxConfidenceScore;
+
   return edges.filter(e => {
-    if (options.relations && options.relations.length > 0) {
-      if (!options.relations.includes(e.relation)) return false;
-    }
-    if (options.confidences && options.confidences.length > 0) {
-      if (!options.confidences.includes(e.confidence)) return false;
-    }
-    if (options.minConfidenceScore !== undefined && e.confidenceScore < options.minConfidenceScore) {
-      return false;
-    }
-    if (options.maxConfidenceScore !== undefined && e.confidenceScore > options.maxConfidenceScore) {
-      return false;
-    }
+    if (relationSet && !relationSet.has(e.relation)) return false;
+    if (confidenceSet && !confidenceSet.has(e.confidence)) return false;
+    if (minScore !== undefined && e.confidenceScore < minScore) return false;
+    if (maxScore !== undefined && e.confidenceScore > maxScore) return false;
     return true;
   });
 }
+
+// ── Formatting ─────────────────────────────────────────────────────────────────
+
+/** Format a list of filtered edges as structured text for LLM consumption. */
+export function formatFilteredEdges(edges: MonographEdge[]): string {
+  if (edges.length === 0) return 'No edges match the filter.';
+  const lines: string[] = [`Filtered edges (${edges.length}):`];
+  for (const e of edges) {
+    const score = e.confidenceScore !== undefined ? ` [${e.confidenceScore.toFixed(2)}]` : '';
+    const reason = e.reason ? ` — ${e.reason}` : '';
+    lines.push(`  ${e.sourceId} -[${e.relation}/${e.confidence}${score}]-> ${e.targetId}${reason}`);
+  }
+  return lines.join('\n');
+}

package/src/graph/health-score.ts

@@ -75,23 +75,13 @@ export function computeHealthScore(db: Database.Database): HealthScoreResult {
   const circularEdges = circularRow.c * 2;
 
   // ── Hotspot files (churnScore > 0.5 in properties) ───────────────────────
-  // Files where properties contain a churnScore > 0.5
-  // We detect presence of churnScore via LIKE and then evaluate in JS
-  const hotspotCandidates = db.prepare(
-    "SELECT properties FROM nodes WHERE label = 'File' AND properties LIKE '%churnScore%'"
-  ).all() as { properties: string | null }[];
-
-  let hotspotCount = 0;
-  for (const row of hotspotCandidates) {
-    if (!row.properties) continue;
-    try {
-      const props = JSON.parse(row.properties) as Record<string, unknown>;
-      const churn = props['churnScore'];
-      if (typeof churn === 'number' && churn > 0.5) hotspotCount++;
-    } catch {
-      // ignore malformed JSON
-    }
-  }
+  // Push the numeric filter into SQLite via json_extract() — avoids O(N) JS JSON.parse loop
+  const hotspotRow = db.prepare(`
+    SELECT COUNT(*) as c FROM nodes
+    WHERE label = 'File'
+      AND CAST(json_extract(properties, '$.churnScore') AS REAL) > 0.5
+  `).get() as { c: number };
+  const hotspotCount = hotspotRow.c;
 
   // ── Isolated nodes (degree = 0) ───────────────────────────────────────────
   const isolatedRow = db.prepare(`
@@ -150,3 +140,43 @@ export function computeHealthScore(db: Database.Database): HealthScoreResult {
 
   return { score, grade, penalties, summary };
 }
+
+/**
+ * Format a HealthScoreResult as structured text for LLM navigation.
+ * Provides a concise grade breakdown that an LLM can parse and act on.
+ *
+ * @param result - HealthScoreResult from computeHealthScore()
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatHealthScore(result: HealthScoreResult): string {
+  const { score, grade, penalties } = result;
+
+  const fmt = (val: number): string => val.toFixed(1);
+
+  const lines: string[] = [
+    `health_score: ${score}/100  grade: ${grade}`,
+    '',
+    'penalties:',
+    `  unreachable_files:     ${fmt(penalties.unreachableFilePct)}%  (max -25)`,
+    `  god_nodes:             ${fmt(penalties.godNodePct)}%  (max -20)`,
+    `  circular_edges:        ${fmt(penalties.circularEdgePct)}%  (max -20)`,
+    `  hotspot_files:         ${fmt(penalties.hotspotPct)}%  (max -15)`,
+    `  isolated_nodes:        ${fmt(penalties.isolatedNodePct)}%  (max -10)`,
+    `  cross_community_edges: ${fmt(penalties.crossCommunityEdgePct)}%  (max -10)`,
+    '',
+  ];
+
+  // Actionable guidance for grades below B
+  if (grade === 'F' || grade === 'D') {
+    lines.push('action_required: yes');
+    if (penalties.circularEdgePct > 5) lines.push('  - break circular import cycles (monograph_context for file dependencies)');
+    if (penalties.godNodePct > 5) lines.push('  - split god nodes (monograph_god_nodes for candidates)');
+    if (penalties.unreachableFilePct > 10) lines.push('  - investigate unreachable files (monograph_detect_changes to surface dead paths)');
+  } else if (grade === 'C') {
+    lines.push('action_suggested: yes');
+    if (penalties.hotspotPct > 10) lines.push('  - reduce churn on hotspot files');
+    if (penalties.isolatedNodePct > 10) lines.push('  - connect or remove isolated nodes');
+  }
+
+  return lines.join('\n');
+}

package/src/graph/hotspots.ts

@@ -1,6 +1,11 @@
 import { execSync } from 'child_process';
 import type Database from 'better-sqlite3';
 
+// ── Process-scoped TTL cache for expensive git log calls ─────────────────────
+// Key: `${projectDir}:${windowDays}` → { output, ts }
+const GIT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const gitLogCache = new Map<string, { output: string; ts: number }>();
+
 export interface HotspotResult {
   nodeId: string;
   nodeName: string;
@@ -47,16 +52,23 @@ export function computeHotspots(
   const now = Date.now();
   const HALF_LIFE_DAYS = 90;
 
-  // ── Step 1: Get git log with dates ────────────────────────────────────────
+  // ── Step 1: Get git log with dates (TTL-cached per projectDir+window) ────
   // Format: ISO-date\tfile-path (one per changed file per commit)
   let gitOutput = '';
-  try {
-    gitOutput = execSync(
-      `git log --since="${windowDays} days ago" --name-only --pretty=format:"%ci" -- .`,
-      { cwd: projectDir, maxBuffer: 10 * 1024 * 1024 },
-    ).toString();
-  } catch {
-    return []; // not a git repo or git not available
+  const cacheKey = `${projectDir}:${windowDays}`;
+  const cached = gitLogCache.get(cacheKey);
+  if (cached && now - cached.ts < GIT_CACHE_TTL_MS) {
+    gitOutput = cached.output;
+  } else {
+    try {
+      gitOutput = execSync(
+        `git log --since="${windowDays} days ago" --name-only --pretty=format:"%ci" -- .`,
+        { cwd: projectDir, maxBuffer: 10 * 1024 * 1024 },
+      ).toString();
+      gitLogCache.set(cacheKey, { output: gitOutput, ts: now });
+    } catch {
+      return []; // not a git repo or git not available
+    }
   }
 
   // ── Step 2: Parse git log and compute churn scores ────────────────────────
@@ -164,3 +176,40 @@ export function computeHotspots(
     .sort((a, b) => b.hotspotScore - a.hotspotScore)
     .slice(0, limit);
 }
+
+/**
+ * Format hotspot results as structured text with file:line hints for LLM navigation.
+ *
+ * @param hotspots - Results from computeHotspots()
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatHotspots(hotspots: HotspotResult[]): string {
+  if (hotspots.length === 0) {
+    return 'hotspots: none found (insufficient git history or no matching file nodes)\n';
+  }
+
+  const trendMark = (t: HotspotResult['trend']): string => {
+    if (t === 'accelerating') return '+';
+    if (t === 'cooling') return '-';
+    return '~';
+  };
+
+  const lines: string[] = [
+    `hotspots: ${hotspots.length} high-risk files (churn x centrality)`,
+    '',
+  ];
+
+  hotspots.forEach((h, i) => {
+    lines.push(`[${i + 1}] ${h.nodeName}  trend:${trendMark(h.trend)}`);
+    lines.push(`  file: ${h.filePath}:1`);
+    lines.push(`  score: ${h.hotspotScore.toFixed(2)}  churn: ${h.churnScore.toFixed(2)}  centrality: ${h.centralityScore.toFixed(2)}`);
+    lines.push(`  commits: ${h.rawCommitCount}  last: ${h.lastCommitDate ?? 'unknown'}`);
+    lines.push('');
+  });
+
+  const accelerating = hotspots.filter(h => h.trend === 'accelerating').length;
+  const cooling = hotspots.filter(h => h.trend === 'cooling').length;
+  lines.push(`summary: ${accelerating} accelerating, ${cooling} cooling, ${hotspots.length - accelerating - cooling} stable`);
+
+  return lines.join('\n');
+}

package/src/graph/import-chain.ts

@@ -10,7 +10,9 @@ export interface ImportChainOptions {
 /**
  * Trace all import chains (paths) from `sourceId` to `targetId`.
  *
- * Uses BFS/DFS with cycle detection. Returns all simple paths up to `maxDepth`.
+ * Uses frontier-based BFS with lazy edge loading: only fetches outgoing edges
+ * for nodes as they are visited, avoiding loading the full edge table when
+ * the graph is large.  Returns all simple paths up to `maxDepth`.
  *
  * @param db - The MonographDb instance
  * @param sourceId - Starting node id
@@ -26,28 +28,27 @@ export function traceImportChain(
 ): string[][] {
   const { maxDepth = 10, maxPaths = 100 } = options;
 
-  const nodeRows = db.prepare('SELECT id FROM nodes').all() as { id: string }[];
-  if (nodeRows.length === 0) return [];
-
-  const nodeSet = new Set(nodeRows.map(r => r.id));
-  if (!nodeSet.has(sourceId) || !nodeSet.has(targetId)) return [];
+  // Quick existence check — avoids loading any edge data for invalid IDs
+  const exists = db.prepare('SELECT 1 FROM nodes WHERE id = ? LIMIT 1');
+  if (!exists.get(sourceId) || !exists.get(targetId)) return [];
   if (sourceId === targetId) return [[sourceId]];
 
-  const edgeRows = db.prepare('SELECT source_id, target_id FROM edges').all() as {
-    source_id: string;
-    target_id: string;
-  }[];
+  // Lazy adjacency cache: only loaded for nodes we actually visit
+  const adjCache = new Map<string, string[]>();
+  const edgeStmt = db.prepare(
+    'SELECT target_id FROM edges WHERE source_id = ? AND source_id != target_id',
+  );
 
-  // Build adjacency
-  const adj = new Map<string, string[]>();
-  for (const n of nodeSet) adj.set(n, []);
-  for (const { source_id: src, target_id: tgt } of edgeRows) {
-    if (src === tgt) continue;
-    if (!adj.has(src) || !adj.has(tgt)) continue;
-    adj.get(src)!.push(tgt);
+  function getNeighbors(nodeId: string): string[] {
+    let neighbors = adjCache.get(nodeId);
+    if (neighbors === undefined) {
+      neighbors = (edgeStmt.all(nodeId) as { target_id: string }[]).map(r => r.target_id);
+      adjCache.set(nodeId, neighbors);
+    }
+    return neighbors;
   }
 
-  // DFS with path tracking
+  // DFS with path tracking (iterative to avoid stack overflow on deep graphs)
   const results: string[][] = [];
   const stack: Array<{ node: string; path: string[]; visited: Set<string> }> = [
     { node: sourceId, path: [sourceId], visited: new Set([sourceId]) },
@@ -59,7 +60,7 @@ export function traceImportChain(
     // the target would require one more edge which would exceed maxDepth.
     if (path.length - 1 >= maxDepth) continue;
 
-    for (const neighbor of adj.get(node) ?? []) {
+    for (const neighbor of getNeighbors(node)) {
       if (visited.has(neighbor)) continue;
       if (neighbor === targetId) {
         results.push([...path, neighbor]);
@@ -76,3 +77,72 @@ export function traceImportChain(
 
   return results;
 }
+
+// ---------------------------------------------------------------------------
+// Structured text formatter for LLM consumption
+// ---------------------------------------------------------------------------
+
+/**
+ * Format import-chain paths as structured text.
+ *
+ * Resolves node IDs to human-readable names (name + file_path) for LLM
+ * context injection.  Each path is printed as an arrow chain with file:line
+ * hints where available.
+ *
+ * @param db - The MonographDb instance (used for name resolution)
+ * @param paths - Result of traceImportChain()
+ * @param sourceId - Source node id (for summary line)
+ * @param targetId - Target node id (for summary line)
+ * @returns Structured text string
+ */
+export function formatImportChain(
+  db: MonographDb,
+  paths: string[][],
+  sourceId: string,
+  targetId: string,
+): string {
+  if (paths.length === 0) {
+    return `Import chain: no path found from ${sourceId} to ${targetId}.`;
+  }
+
+  // Batch-resolve all node IDs in the result set
+  const allIds = [...new Set(paths.flat())];
+  const placeholders = allIds.map(() => '?').join(',');
+  const nodeRows = db
+    .prepare(
+      `SELECT id, name, file_path, start_line FROM nodes WHERE id IN (${placeholders})`,
+    )
+    .all(...allIds) as {
+    id: string;
+    name: string;
+    file_path: string | null;
+    start_line: number | null;
+  }[];
+
+  const nodeInfo = new Map<string, { name: string; loc: string }>();
+  for (const row of nodeRows) {
+    const loc =
+      row.file_path != null
+        ? row.start_line != null
+          ? `${row.file_path}:${row.start_line}`
+          : row.file_path
+        : row.id;
+    nodeInfo.set(row.id, { name: row.name ?? row.id, loc });
+  }
+
+  const lines: string[] = [
+    `Import chain: ${paths.length} path${paths.length === 1 ? '' : 's'} from ${nodeInfo.get(sourceId)?.name ?? sourceId} to ${nodeInfo.get(targetId)?.name ?? targetId}`,
+    '',
+  ];
+
+  for (let i = 0; i < paths.length; i++) {
+    lines.push(`Path ${i + 1} (${paths[i].length} node${paths[i].length === 1 ? '' : 's'}):`);
+    for (const id of paths[i]) {
+      const info = nodeInfo.get(id);
+      lines.push(`  ${info?.name ?? id} — ${info?.loc ?? id}`);
+    }
+    if (i < paths.length - 1) lines.push('');
+  }
+
+  return lines.join('\n');
+}