@monoes/monograph 1.2.0 → 1.2.2

package/src/graph/statistics.ts

@@ -1,14 +1,47 @@
 import { bfsFromNode } from 'graphology-traversal/bfs.js';
+import type Graph from 'graphology';
 import { loadGraphFromDb } from './loader.js';
 import type { MonographDb } from '../storage/db.js';
 
+// ---------------------------------------------------------------------------
+// Module-level graph cache — avoids reloading the full graph on every call
+// when multiple statistics functions are invoked in the same request cycle.
+// TTL: 5 seconds; keyed by DB file path (better-sqlite3 exposes .name).
+// ---------------------------------------------------------------------------
+const GRAPH_CACHE_TTL_MS = 5_000;
+
+interface GraphCacheEntry {
+  graph: Graph;
+  expiresAt: number;
+}
+
+const _graphCache = new Map<string, GraphCacheEntry>();
+
+function getGraph(db: MonographDb): Graph {
+  const key = (db as unknown as { name: string }).name ?? '__default__';
+  const now = Date.now();
+  const cached = _graphCache.get(key);
+  if (cached && now < cached.expiresAt) return cached.graph;
+  const graph = loadGraphFromDb(db);
+  _graphCache.set(key, { graph, expiresAt: now + GRAPH_CACHE_TTL_MS });
+  return graph;
+}
+
+/**
+ * Evict the cached graph for a given DB instance (call after writes).
+ */
+export function invalidateGraphCache(db: MonographDb): void {
+  const key = (db as unknown as { name: string }).name ?? '__default__';
+  _graphCache.delete(key);
+}
+
 /**
  * Graph density: ratio of actual edges to maximum possible directed edges.
  * For a directed graph with n nodes: max = n * (n - 1).
  * Ignores self-loops.
  */
 export function graphDensity(db: MonographDb): number {
-  const graph = loadGraphFromDb(db);
+  const graph = getGraph(db);
   const n = graph.order;
   if (n < 2) return 0;
   const maxEdges = n * (n - 1);
@@ -28,7 +61,7 @@ export function graphDensity(db: MonographDb): number {
  * We use the undirected approximation: treat edges as undirected, count triangles.
  */
 export function clusteringCoefficient(db: MonographDb): number {
-  const graph = loadGraphFromDb(db);
+  const graph = getGraph(db);
   if (graph.order === 0) return 0;
 
   // Build undirected adjacency sets
@@ -67,67 +100,62 @@ export function clusteringCoefficient(db: MonographDb): number {
   return totalCoeff / countWithNeighbors;
 }
 
+// ---------------------------------------------------------------------------
+// Shared BFS result for path-length metrics
+// ---------------------------------------------------------------------------
+
+export interface PathStats {
+  /** Average shortest path length across all reachable pairs (i ≠ j). */
+  averagePathLength: number;
+  /** Maximum shortest path length (diameter) across all reachable pairs. */
+  diameter: number;
+}
+
 /**
- * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
- * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ * Compute both average path length and graph diameter in a single BFS pass.
+ * Unreachable pairs are excluded from averagePathLength.
  */
-export function averagePathLength(db: MonographDb): number {
-  const graph = loadGraphFromDb(db);
+export function pathStats(db: MonographDb): PathStats {
+  const graph = getGraph(db);
   const nodes = graph.nodes();
-  if (nodes.length < 2) return 0;
+  if (nodes.length < 2) return { averagePathLength: 0, diameter: 0 };
 
   let totalLength = 0;
   let reachablePairs = 0;
+  let maxDist = 0;
 
   for (const source of nodes) {
-    const distances = new Map<string, number>();
-    distances.set(source, 0);
-
     bfsFromNode(graph, source, (node, _attr, depth) => {
-      if (node !== source) {
-        distances.set(node, depth);
-      }
-    });
-
-    for (const [target, dist] of distances) {
-      if (target !== source && dist > 0) {
-        totalLength += dist;
+      if (node !== source && depth > 0) {
+        totalLength += depth;
         reachablePairs++;
+        if (depth > maxDist) maxDist = depth;
       }
-    }
+    });
   }
 
-  if (reachablePairs === 0) return 0;
-  return totalLength / reachablePairs;
+  return {
+    averagePathLength: reachablePairs === 0 ? 0 : totalLength / reachablePairs,
+    diameter: maxDist,
+  };
+}
+
+/**
+ * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
+ * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ *
+ * @deprecated Prefer `pathStats(db).averagePathLength` to share BFS with `graphDiameter`.
+ */
+export function averagePathLength(db: MonographDb): number {
+  return pathStats(db).averagePathLength;
 }
 
 /**
  * Graph diameter: the maximum shortest path length across all reachable node pairs.
  * Returns 0 for empty or single-node graphs.
+ *
+ * @deprecated Prefer `pathStats(db).diameter` to share BFS with `averagePathLength`.
  */
 export function graphDiameter(db: MonographDb): number {
-  const graph = loadGraphFromDb(db);
-  const nodes = graph.nodes();
-  if (nodes.length < 2) return 0;
-
-  let maxDist = 0;
-
-  for (const source of nodes) {
-    const distances = new Map<string, number>();
-    distances.set(source, 0);
-
-    bfsFromNode(graph, source, (node, _attr, depth) => {
-      if (node !== source) {
-        distances.set(node, depth);
-      }
-    });
-
-    for (const [target, dist] of distances) {
-      if (target !== source && dist > maxDist) {
-        maxDist = dist;
-      }
-    }
-  }
-
-  return maxDist;
+  return pathStats(db).diameter;
 }

package/src/graph/stats.ts

@@ -1,5 +1,27 @@
 import type Database from 'better-sqlite3';
 
+// Per-DB prepared statement cache to avoid re-parsing SQL on repeated calls
+const stmtCache = new WeakMap<Database.Database, Map<string, Database.Statement>>();
+
+function stmt(db: Database.Database, sql: string): Database.Statement {
+  let dbCache = stmtCache.get(db);
+  if (!dbCache) { dbCache = new Map(); stmtCache.set(db, dbCache); }
+  let s = dbCache.get(sql);
+  if (!s) { s = db.prepare(sql); dbCache.set(sql, s); }
+  return s;
+}
+
+/** Binary search: returns index of first element > value in a sorted ascending array. */
+function upperBound(sorted: number[], value: number): number {
+  let lo = 0, hi = sorted.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (sorted[mid] <= value) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
 export type RiskBin = 'low' | 'medium' | 'high' | 'critical';
 
 export interface RiskProfile {
@@ -64,23 +86,21 @@ function buildRiskProfile(values: number[]): RiskProfile {
  * Compute full coupling profile from SQLite.
  */
 export function computeCouplingProfile(db: Database.Database): CouplingProfile {
-  const fanInRows = db.prepare(
-    'SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id'
-  ).all() as { target_id: string; c: number }[];
+  const fanInRows = stmt(db, 'SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id')
+    .all() as { target_id: string; c: number }[];
 
-  const fanOutRows = db.prepare(
-    'SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id'
-  ).all() as { source_id: string; c: number }[];
+  const fanOutRows = stmt(db, 'SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id')
+    .all() as { source_id: string; c: number }[];
 
-  const totalFiles = (db.prepare(
-    "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'"
-  ).get() as { n: number }).n;
+  const totalFiles = (stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+    .get() as { n: number }).n;
 
   const fanInValues = fanInRows.map(r => r.c).sort((a, b) => a - b);
   const fanOutValues = fanOutRows.map(r => r.c).sort((a, b) => a - b);
 
   const p95FanIn = percentile(fanInValues, 95);
-  const couplingHighCount = fanInValues.filter(v => v > p95FanIn).length;
+  // Use binary search instead of O(N) filter to count elements above p95 threshold
+  const couplingHighCount = fanInValues.length - upperBound(fanInValues, p95FanIn);
   const couplingHighPct = fanInValues.length > 0
     ? Math.round((couplingHighCount / fanInValues.length) * 100)
     : 0;
@@ -101,14 +121,13 @@ export function computeCouplingProfile(db: Database.Database): CouplingProfile {
  * Quick stats summary (extends existing stats from monograph_stats MCP tool).
  */
 export function computeGraphStats(db: Database.Database): GraphStatsSummary {
-  const nodeCount = (db.prepare('SELECT COUNT(*) as n FROM nodes').get() as { n: number }).n;
-  const edgeCount = (db.prepare('SELECT COUNT(*) as n FROM edges').get() as { n: number }).n;
-  const communityCount = (db.prepare(
+  const nodeCount = (stmt(db, 'SELECT COUNT(*) as n FROM nodes').get() as { n: number }).n;
+  const edgeCount = (stmt(db, 'SELECT COUNT(*) as n FROM edges').get() as { n: number }).n;
+  const communityCount = (stmt(db,
     "SELECT COUNT(DISTINCT community_id) as n FROM nodes WHERE community_id IS NOT NULL"
   ).get() as { n: number }).n;
-  const fileCount = (db.prepare(
-    "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'"
-  ).get() as { n: number }).n;
+  const fileCount = (stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+    .get() as { n: number }).n;
 
   const couplingProfile = computeCouplingProfile(db);
 
@@ -120,3 +139,18 @@ export function computeGraphStats(db: Database.Database): GraphStatsSummary {
     couplingProfile,
   };
 }
+
+/** Format a GraphStatsSummary as structured text for LLM consumption. */
+export function formatGraphStats(s: GraphStatsSummary): string {
+  const cp = s.couplingProfile;
+  const lines: string[] = [
+    `Graph Stats`,
+    `  Nodes: ${s.nodeCount}  Edges: ${s.edgeCount}  Communities: ${s.communityCount}  Files: ${s.fileCount}`,
+    `Coupling Profile (${cp.totalFiles} files)`,
+    `  Fan-in p50/p75/p90/p95: ${cp.p50FanIn}/${cp.p75FanIn}/${cp.p90FanIn}/${cp.p95FanIn}`,
+    `  High-coupling (>p95): ${cp.couplingHighPct}%`,
+    `Fan-in Risk: low=${cp.fanInProfile.low}(${cp.fanInProfile.lowPct}%) med=${cp.fanInProfile.medium}(${cp.fanInProfile.mediumPct}%) high=${cp.fanInProfile.high}(${cp.fanInProfile.highPct}%) crit=${cp.fanInProfile.critical}(${cp.fanInProfile.criticalPct}%)`,
+    `Fan-out Risk: low=${cp.fanOutProfile.low}(${cp.fanOutProfile.lowPct}%) med=${cp.fanOutProfile.medium}(${cp.fanOutProfile.mediumPct}%) high=${cp.fanOutProfile.high}(${cp.fanOutProfile.highPct}%) crit=${cp.fanOutProfile.critical}(${cp.fanOutProfile.criticalPct}%)`,
+  ];
+  return lines.join('\n');
+}

package/src/graph/subgraph.ts

@@ -1,3 +1,4 @@
+import Database from 'better-sqlite3';
 import type { MonographNode, MonographEdge } from '../types.js';
 import type { MonographDb } from '../storage/db.js';
 
@@ -21,46 +22,80 @@ export interface InducedSubgraph {
 // (source_id IN chunk), then filters target in-memory — full limit available per chunk.
 const SQLITE_VAR_LIMIT = 32766;
 
+/** Cache of placeholder strings keyed by count: 1 → "?", 2 → "?,?", etc. */
+const placeholderCache = new Map<number, string>();
+function placeholders(n: number): string {
+  let ph = placeholderCache.get(n);
+  if (!ph) {
+    ph = Array(n).fill('?').join(',');
+    placeholderCache.set(n, ph);
+  }
+  return ph;
+}
+
+type RawNode = {
+  id: string; label: string; name: string; norm_label?: string | null; file_path: string | null;
+  start_line: number | null; end_line: number | null; community_id: number | null;
+  is_exported: number; language: string | null; properties: string | null;
+};
+type RawEdge = {
+  id: string; source_id: string; target_id: string; relation: string;
+  confidence: string; confidence_score: number; reason: string | null;
+  // evidence column omitted — not surfaced in InducedSubgraph
+};
+
+/**
+ * Prepared-statement caches per db instance — stored on the db object to avoid
+ * cross-db pollution while ensuring each unique chunk size is prepared at most once.
+ */
+function getStmtCaches(db: MonographDb): {
+  nodes: Map<number, ReturnType<MonographDb['prepare']>>;
+  edges: Map<number, ReturnType<MonographDb['prepare']>>;
+} {
+  const key = '__subgraphStmtCache__';
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const dbAny = db as any;
+  if (!dbAny[key]) {
+    dbAny[key] = { nodes: new Map(), edges: new Map() };
+  }
+  return dbAny[key] as { nodes: Map<number, ReturnType<MonographDb['prepare']>>; edges: Map<number, ReturnType<MonographDb['prepare']>> };
+}
+
 export function extractInducedSubgraph(db: MonographDb, nodeIds: string[]): InducedSubgraph {
   if (nodeIds.length === 0) return { nodes: [], edges: [] };
 
-  // Chunk helper to stay within SQLITE_MAX_VARIABLE_NUMBER
-  function queryChunked<T>(ids: string[], chunkSize: number, query: (ph: string, chunk: string[]) => T[]): T[] {
+  const stmts = getStmtCaches(db);
+
+  // Chunk helper — caches prepared statements by chunk size to avoid re-prepare per call.
+  function queryChunked<T>(ids: string[], chunkSize: number, stmtCache: Map<number, Database.Statement>, sql: (ph: string) => string): T[] {
     const results: T[] = [];
     for (let i = 0; i < ids.length; i += chunkSize) {
       const chunk = ids.slice(i, i + chunkSize);
-      const ph = chunk.map(() => '?').join(',');
-      results.push(...query(ph, chunk));
+      const ph = placeholders(chunk.length);
+      let stmt = stmtCache.get(chunk.length);
+      if (!stmt) { stmt = db.prepare(sql(ph)); stmtCache.set(chunk.length, stmt); }
+      results.push(...(stmt.all(...chunk) as T[]));
     }
     return results;
   }
 
-  type RawNode = {
-    id: string; label: string; name: string; norm_label?: string | null; file_path: string | null;
-    start_line: number | null; end_line: number | null; community_id: number | null;
-    is_exported: number; language: string | null; properties: string | null;
-  };
-  type RawEdge = {
-    id: string; source_id: string; target_id: string; relation: string;
-    confidence: string; confidence_score: number; reason: string | null; evidence: string | null;
-  };
-
-  const rawNodes = queryChunked<RawNode>(nodeIds, SQLITE_VAR_LIMIT, (ph, chunk) =>
-    db.prepare(
-      `SELECT id, label, name, file_path, start_line, end_line, community_id, is_exported, language, properties
-       FROM nodes WHERE id IN (${ph})`
-    ).all(...chunk) as RawNode[]
+  const rawNodes = queryChunked<RawNode>(
+    nodeIds,
+    SQLITE_VAR_LIMIT,
+    stmts.nodes,
+    ph => `SELECT id, label, name, file_path, start_line, end_line, community_id, is_exported, language, properties FROM nodes WHERE id IN (${ph})`,
   );
 
   // For edges: query by source_id chunks (1 bind per row), then filter target in-memory.
-  // Querying by both source+target would miss cross-chunk edges and requires 2× bind slots.
   const nodeSet = new Set(nodeIds);
-  const rawEdges = queryChunked<RawEdge>(nodeIds, SQLITE_VAR_LIMIT, (ph, chunk) =>
-    (db.prepare(
-      `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason, evidence
-       FROM edges WHERE source_id IN (${ph})`
-    ).all(...chunk) as RawEdge[]).filter(e => nodeSet.has(e.target_id))
+  const allSourceEdges = queryChunked<RawEdge>(
+    nodeIds,
+    SQLITE_VAR_LIMIT,
+    stmts.edges,
+    // Drop unused 'evidence' column to reduce row data transfer
+    ph => `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason FROM edges WHERE source_id IN (${ph})`,
   );
+  const rawEdges = allSourceEdges.filter(e => nodeSet.has(e.target_id));
 
   const nodes: MonographNode[] = rawNodes.map(n => ({
     id: n.id,
@@ -88,3 +123,40 @@ export function extractInducedSubgraph(db: MonographDb, nodeIds: string[]): Indu
 
   return { nodes, edges };
 }
+
+/**
+ * Format an InducedSubgraph as structured text for LLM consumption.
+ * Groups nodes by file path and lists edges with relation + file:line hints.
+ */
+export function formatInducedSubgraph(sg: InducedSubgraph): string {
+  if (sg.nodes.length === 0) return 'Subgraph is empty.';
+
+  const lines: string[] = [`Subgraph: ${sg.nodes.length} nodes, ${sg.edges.length} edges`];
+
+  // Group nodes by file
+  const byFile = new Map<string, MonographNode[]>();
+  for (const n of sg.nodes) {
+    const file = n.filePath ?? '(unknown)';
+    let list = byFile.get(file);
+    if (!list) { list = []; byFile.set(file, list); }
+    list.push(n);
+  }
+
+  lines.push('\nNodes:');
+  for (const [file, nodes] of byFile) {
+    lines.push(`  ${file}`);
+    for (const n of nodes) {
+      const loc = n.startLine ? `:${n.startLine}` : '';
+      lines.push(`    ${n.label} ${n.name}${loc}`);
+    }
+  }
+
+  if (sg.edges.length > 0) {
+    lines.push('\nEdges:');
+    for (const e of sg.edges) {
+      lines.push(`  ${e.sourceId} --[${e.relation}]--> ${e.targetId}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/graph/topo-sort.ts

@@ -16,35 +16,49 @@ export interface TopoSortResult {
  * Files with no incoming edges on the reverse graph (i.e., no one imports them)
  * are leaves and appear in level 0.
  *
+ * The in-degree computation is pushed into SQL (GROUP BY aggregation) to avoid
+ * materialising the full edge table into JavaScript memory.
+ *
  * @param db - The MonographDb instance
  * @returns Object with `levels` (array of independent groups, leaf-first) and `cycleCount`.
  */
 export function topologicalLevelSort(db: MonographDb): TopoSortResult {
   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 {
-    source_id: string;
-    target_id: string;
-  }[];
-
   if (nodeRows.length === 0) return { levels: [], cycleCount: 0 };
 
   const nodes = nodeRows.map(r => r.id);
 
-  // Build reverse graph: original edge src→tgt becomes tgt→src in reverse
-  // In-degree in the reverse graph = number of nodes that tgt imports (out-degree in original)
-  const reverseAdj = new Map<string, string[]>();
-  const inDegree = new Map<string, number>();
+  // Compute in-degree (on the reverse graph) via SQL aggregation.
+  // In the original graph each edge src→tgt means "src imports tgt".
+  // In the reverse graph the edge becomes tgt→src, so src gains in-degree +1.
+  // We aggregate target_id counts grouped by source_id to get reverse-in-degree per node.
+  const inDegreeRows = db
+    .prepare(
+      `SELECT source_id AS node_id, COUNT(*) AS cnt
+       FROM edges
+       WHERE source_id != target_id
+       GROUP BY source_id`,
+    )
+    .all() as { node_id: string; cnt: number }[];
 
-  for (const n of nodes) {
-    reverseAdj.set(n, []);
-    inDegree.set(n, 0);
+  const inDegree = new Map<string, number>();
+  for (const n of nodes) inDegree.set(n, 0);
+  for (const { node_id, cnt } of inDegreeRows) {
+    if (inDegree.has(node_id)) inDegree.set(node_id, cnt);
   }
 
+  // Build reverse adjacency list — still needed for Kahn's BFS relaxation step.
+  // Fetch only what Kahn needs: target_id → [source_id, ...] (reverse direction).
+  const reverseAdj = new Map<string, string[]>();
+  for (const n of nodes) reverseAdj.set(n, []);
+
+  const edgeRows = db
+    .prepare('SELECT source_id, target_id FROM edges WHERE source_id != target_id')
+    .all() as { source_id: string; target_id: string }[];
+
   for (const { source_id: src, target_id: tgt } of edgeRows) {
-    if (src === tgt) continue; // skip self-loops
     if (!reverseAdj.has(tgt) || !reverseAdj.has(src)) continue;
     reverseAdj.get(tgt)!.push(src);
-    inDegree.set(src, (inDegree.get(src) ?? 0) + 1);
   }
 
   // Kahn's BFS on the reverse graph
@@ -57,7 +71,6 @@ export function topologicalLevelSort(db: MonographDb): TopoSortResult {
   const visited = new Set<string>();
 
   while (queue.length > 0) {
-    // All nodes currently at in-degree 0 form one level
     const level = [...queue];
     queue.length = 0;
     levels.push(level);
@@ -76,7 +89,6 @@ export function topologicalLevelSort(db: MonographDb): TopoSortResult {
   // Remaining unvisited nodes are in cycles
   const cycleNodes = nodes.filter(n => !visited.has(n));
   let cycleCount = 0;
-
   if (cycleNodes.length > 0) {
     cycleCount = cycleNodes.length;
     levels.push(cycleNodes);
@@ -84,3 +96,76 @@ export function topologicalLevelSort(db: MonographDb): TopoSortResult {
 
   return { levels, cycleCount };
 }
+
+// ---------------------------------------------------------------------------
+// Structured text formatter for LLM consumption
+// ---------------------------------------------------------------------------
+
+/**
+ * Format topological sort levels as structured text.
+ *
+ * Resolves node IDs to names and file paths so LLMs can navigate directly
+ * to the source. Cycle nodes (if any) are clearly labelled.
+ *
+ * @param db - The MonographDb instance (for name resolution)
+ * @param result - Result from topologicalLevelSort()
+ * @param maxLevels - Max levels to include in output (default: all)
+ * @returns Structured text suitable for injection into LLM context
+ */
+export function formatTopoSort(
+  db: MonographDb,
+  result: TopoSortResult,
+  maxLevels?: number,
+): string {
+  if (result.levels.length === 0) {
+    return 'Topological sort: no nodes found.';
+  }
+
+  // Batch-resolve all node IDs
+  const allIds = result.levels.flat();
+  const CHUNK = 200;
+  const nodeInfo = new Map<string, { name: string; filePath: string | null }>();
+
+  for (let i = 0; i < allIds.length; i += CHUNK) {
+    const chunk = allIds.slice(i, i + CHUNK);
+    const ph = chunk.map(() => '?').join(',');
+    const rows = db
+      .prepare(`SELECT id, name, file_path FROM nodes WHERE id IN (${ph})`)
+      .all(...chunk) as { id: string; name: string; file_path: string | null }[];
+    for (const row of rows) {
+      nodeInfo.set(row.id, { name: row.name ?? row.id, filePath: row.file_path });
+    }
+  }
+
+  const isCycleLevelIdx =
+    result.cycleCount > 0 && result.levels.length > 0
+      ? result.levels.length - 1
+      : -1;
+
+  const displayLevels = maxLevels !== undefined ? result.levels.slice(0, maxLevels) : result.levels;
+
+  const lines: string[] = [
+    `Topological sort: ${result.levels.length - (result.cycleCount > 0 ? 1 : 0)} level${result.levels.length === 1 ? '' : 's'}` +
+      (result.cycleCount > 0 ? `, ${result.cycleCount} node${result.cycleCount === 1 ? '' : 's'} in cycles` : ''),
+    '',
+  ];
+
+  for (let li = 0; li < displayLevels.length; li++) {
+    const level = displayLevels[li];
+    const label = li === isCycleLevelIdx ? 'Cycle nodes (unresolvable order)' : `Level ${li}`;
+    lines.push(`${label} (${level.length} node${level.length === 1 ? '' : 's'}):`);
+    for (const id of level) {
+      const info = nodeInfo.get(id);
+      const name = info?.name ?? id;
+      const fp = info?.filePath;
+      lines.push(`  ${name}${fp ? ` — ${fp}` : ''}`);
+    }
+    lines.push('');
+  }
+
+  if (maxLevels !== undefined && result.levels.length > maxLevels) {
+    lines.push(`... (${result.levels.length - maxLevels} more level${result.levels.length - maxLevels === 1 ? '' : 's'} omitted)`);
+  }
+
+  return lines.join('\n').trimEnd();
+}