@monoes/monograph 1.1.0 → 1.2.1

package/src/graph/stats.ts

@@ -0,0 +1,156 @@
+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 {
+  low: number;
+  medium: number;
+  high: number;
+  critical: number;
+  lowPct: number;
+  mediumPct: number;
+  highPct: number;
+  criticalPct: number;
+}
+
+export interface CouplingProfile {
+  p50FanIn: number;
+  p75FanIn: number;
+  p90FanIn: number;
+  p95FanIn: number;
+  couplingHighPct: number;
+  fanInProfile: RiskProfile;
+  fanOutProfile: RiskProfile;
+  totalFiles: number;
+}
+
+export interface GraphStatsSummary {
+  nodeCount: number;
+  edgeCount: number;
+  communityCount: number;
+  fileCount: number;
+  couplingProfile: CouplingProfile;
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.floor((p / 100) * sorted.length);
+  return sorted[Math.min(idx, sorted.length - 1)];
+}
+
+function buildRiskProfile(values: number[]): RiskProfile {
+  const total = values.length;
+  let low = 0, medium = 0, high = 0, critical = 0;
+  for (const v of values) {
+    if (v < 5) low++;
+    else if (v <= 15) medium++;
+    else if (v <= 30) high++;
+    else critical++;
+  }
+  const pct = (n: number) => total > 0 ? Math.round((n / total) * 100) : 0;
+  return {
+    low,
+    medium,
+    high,
+    critical,
+    lowPct: pct(low),
+    mediumPct: pct(medium),
+    highPct: pct(high),
+    criticalPct: pct(critical),
+  };
+}
+
+/**
+ * Compute full coupling profile from SQLite.
+ */
+export function computeCouplingProfile(db: Database.Database): CouplingProfile {
+  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 = stmt(db, 'SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id')
+    .all() as { source_id: string; c: number }[];
+
+  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);
+  // 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;
+
+  return {
+    p50FanIn: percentile(fanInValues, 50),
+    p75FanIn: percentile(fanInValues, 75),
+    p90FanIn: percentile(fanInValues, 90),
+    p95FanIn,
+    couplingHighPct,
+    fanInProfile: buildRiskProfile(fanInValues),
+    fanOutProfile: buildRiskProfile(fanOutValues),
+    totalFiles,
+  };
+}
+
+/**
+ * Quick stats summary (extends existing stats from monograph_stats MCP tool).
+ */
+export function computeGraphStats(db: Database.Database): GraphStatsSummary {
+  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 = (stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+    .get() as { n: number }).n;
+
+  const couplingProfile = computeCouplingProfile(db);
+
+  return {
+    nodeCount,
+    edgeCount,
+    communityCount,
+    fileCount,
+    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

@@ -0,0 +1,161 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+export interface InducedSubgraph {
+  nodes: MonographNode[];
+  edges: MonographEdge[];
+}
+
+/**
+ * Extract the induced subgraph for the given set of node ids.
+ *
+ * The induced subgraph contains:
+ * - Only the nodes whose ids are in `nodeIds` (and exist in the DB)
+ * - Only the edges where both source and target are in `nodeIds`
+ *
+ * @param db - The MonographDb instance
+ * @param nodeIds - The subset of node ids to include
+ * @returns An object with `nodes` and `edges` arrays
+ */
+// SQLite SQLITE_MAX_VARIABLE_NUMBER limit (32766). Edge query binds nodeIds once
+// (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: [] };
+
+  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, ReturnType<MonographDb['prepare']>>, 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 = 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;
+  }
+
+  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.
+  const nodeSet = new Set(nodeIds);
+  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,
+    label: n.label as MonographNode['label'],
+    name: n.name,
+    normLabel: (n.norm_label ?? n.name ?? '').toLowerCase(),
+    filePath: n.file_path ?? undefined,
+    startLine: n.start_line ?? undefined,
+    endLine: n.end_line ?? undefined,
+    communityId: n.community_id ?? undefined,
+    isExported: n.is_exported === 1,
+    language: n.language ?? undefined,
+    properties: n.properties ? (JSON.parse(n.properties) as Record<string, unknown>) : undefined,
+  }));
+
+  const edges: MonographEdge[] = rawEdges.map(e => ({
+    id: e.id,
+    sourceId: e.source_id,
+    targetId: e.target_id,
+    relation: e.relation as MonographEdge['relation'],
+    confidence: e.confidence as MonographEdge['confidence'],
+    confidenceScore: e.confidence_score,
+    reason: e.reason ?? undefined,
+  }));
+
+  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

@@ -0,0 +1,171 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface TopoSortResult {
+  /** Groups of nodes that can be processed independently at each level.
+   *  Level 0 = leaves (nodes with no outgoing IMPORTS edges on the reverse graph).
+   *  Higher levels depend on previous levels. Cycle nodes are appended last. */
+  levels: string[][];
+  /** Number of nodes that are part of a cycle and could not be sorted. */
+  cycleCount: number;
+}
+
+/**
+ * Topological level sort using Kahn's algorithm on the *reverse* import graph.
+ *
+ * In the reverse graph, an edge A→B in the original (A imports B) becomes B→A.
+ * 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 }[];
+  if (nodeRows.length === 0) return { levels: [], cycleCount: 0 };
+
+  const nodes = nodeRows.map(r => r.id);
+
+  // 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 }[];
+
+  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 (!reverseAdj.has(tgt) || !reverseAdj.has(src)) continue;
+    reverseAdj.get(tgt)!.push(src);
+  }
+
+  // Kahn's BFS on the reverse graph
+  const queue: string[] = [];
+  for (const [node, deg] of inDegree) {
+    if (deg === 0) queue.push(node);
+  }
+
+  const levels: string[][] = [];
+  const visited = new Set<string>();
+
+  while (queue.length > 0) {
+    const level = [...queue];
+    queue.length = 0;
+    levels.push(level);
+
+    for (const node of level) {
+      visited.add(node);
+      for (const neighbor of reverseAdj.get(node) ?? []) {
+        if (visited.has(neighbor)) continue;
+        const newDeg = (inDegree.get(neighbor) ?? 0) - 1;
+        inDegree.set(neighbor, newDeg);
+        if (newDeg === 0) queue.push(neighbor);
+      }
+    }
+  }
+
+  // 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);
+  }
+
+  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();
+}

package/src/graph/wcc.ts

@@ -0,0 +1,187 @@
+import type { MonographDb } from '../storage/db.js';
+
+/**
+ * Find all weakly connected components (WCCs) of the graph.
+ *
+ * Treats the directed graph as undirected: an edge A→B connects A and B
+ * regardless of direction. Uses union-find (disjoint-set) for O(α·n) performance.
+ *
+ * @param db - The MonographDb instance
+ * @returns Array of components; each component is an array of node ids.
+ *          Sorted so the largest component comes first.
+ */
+export function weaklyConnectedComponents(db: MonographDb): string[][] {
+  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 [];
+
+  const nodes = nodeRows.map(r => r.id);
+  const { parent, rank } = buildUnionFind(nodes);
+
+  for (const { source_id: src, target_id: tgt } of edgeRows) {
+    if (src === tgt) continue;
+    if (!parent.has(src) || !parent.has(tgt)) continue;
+    ufUnion(parent, rank, src, tgt);
+  }
+
+  return groupByRoot(nodes, parent);
+}
+
+// ---------------------------------------------------------------------------
+// Summary stats — avoids name resolution and component array materialisation
+// ---------------------------------------------------------------------------
+
+export interface WccStats {
+  /** Total number of weakly connected components */
+  componentCount: number;
+  /** Size of the largest component */
+  largestSize: number;
+  /** Size of the smallest component */
+  smallestSize: number;
+  /** Mean component size */
+  meanSize: number;
+  /** Number of isolated nodes (component size = 1) */
+  isolatedNodeCount: number;
+}
+
+/**
+ * Lightweight summary statistics for all WCCs.
+ * Does not materialise component arrays — returns aggregate numbers only.
+ */
+export function wccStats(db: MonographDb): WccStats {
+  const components = weaklyConnectedComponents(db);
+  if (components.length === 0) {
+    return { componentCount: 0, largestSize: 0, smallestSize: 0, meanSize: 0, isolatedNodeCount: 0 };
+  }
+
+  const sizes = components.map(c => c.length);
+  const total = sizes.reduce((a, b) => a + b, 0);
+  return {
+    componentCount: sizes.length,
+    largestSize: sizes[0], // already sorted descending
+    smallestSize: sizes[sizes.length - 1],
+    meanSize: Math.round((total / sizes.length) * 100) / 100,
+    isolatedNodeCount: sizes.filter(s => s === 1).length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Structured text formatter for LLM consumption
+// ---------------------------------------------------------------------------
+
+/**
+ * Format WCC results as structured text for LLM consumption.
+ *
+ * Resolves node IDs to names and file paths for the top-N largest components.
+ * Small/isolated components are summarised in aggregate to avoid token waste.
+ *
+ * @param db - The MonographDb instance (for name resolution)
+ * @param components - Result of weaklyConnectedComponents()
+ * @param topN - Number of largest components to detail (default: 5)
+ * @returns Structured text string suitable for LLM context injection
+ */
+export function formatWcc(db: MonographDb, components: string[][], topN = 5): string {
+  if (components.length === 0) {
+    return 'Weakly connected components: no nodes found.';
+  }
+
+  const isolatedCount = components.filter(c => c.length === 1).length;
+  const nonTrivial = components.filter(c => c.length > 1);
+  const display = nonTrivial.slice(0, topN);
+
+  // Batch-resolve all node IDs in the displayed components
+  const allIds = display.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 lines: string[] = [
+    `Weakly connected components: ${components.length} total` +
+      (isolatedCount > 0 ? ` (${isolatedCount} isolated node${isolatedCount === 1 ? '' : 's'})` : ''),
+    '',
+  ];
+
+  for (let ci = 0; ci < display.length; ci++) {
+    const comp = display[ci];
+    lines.push(`Component ${ci + 1} (${comp.length} nodes):`);
+    for (const id of comp) {
+      const info = nodeInfo.get(id);
+      const name = info?.name ?? id;
+      const fp = info?.filePath;
+      lines.push(`  ${name}${fp ? ` — ${fp}` : ''}`);
+    }
+    if (ci < display.length - 1) lines.push('');
+  }
+
+  if (nonTrivial.length > topN) {
+    lines.push('');
+    lines.push(`... (${nonTrivial.length - topN} more non-trivial component${nonTrivial.length - topN === 1 ? '' : 's'} omitted)`);
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internal union-find helpers
+// ---------------------------------------------------------------------------
+
+function buildUnionFind(nodes: string[]): { parent: Map<string, string>; rank: Map<string, number> } {
+  const parent = new Map<string, string>();
+  const rank = new Map<string, number>();
+  for (const n of nodes) {
+    parent.set(n, n);
+    rank.set(n, 0);
+  }
+  return { parent, rank };
+}
+
+function ufFind(parent: Map<string, string>, x: string): string {
+  let root = x;
+  while (parent.get(root) !== root) root = parent.get(root)!;
+  // Path compression
+  let cur = x;
+  while (cur !== root) {
+    const next = parent.get(cur)!;
+    parent.set(cur, root);
+    cur = next;
+  }
+  return root;
+}
+
+function ufUnion(parent: Map<string, string>, rank: Map<string, number>, a: string, b: string): void {
+  const ra = ufFind(parent, a);
+  const rb = ufFind(parent, b);
+  if (ra === rb) return;
+  const rankA = rank.get(ra) ?? 0;
+  const rankB = rank.get(rb) ?? 0;
+  if (rankA < rankB) {
+    parent.set(ra, rb);
+  } else if (rankA > rankB) {
+    parent.set(rb, ra);
+  } else {
+    parent.set(rb, ra);
+    rank.set(ra, rankA + 1);
+  }
+}
+
+function groupByRoot(nodes: string[], parent: Map<string, string>): string[][] {
+  const components = new Map<string, string[]>();
+  for (const n of nodes) {
+    const root = ufFind(parent, n);
+    if (!components.has(root)) components.set(root, []);
+    components.get(root)!.push(n);
+  }
+  return [...components.values()].sort((a, b) => b.length - a.length);
+}