@monoes/monograph 1.2.0 → 1.2.2

package/src/graph/complexity.ts

@@ -32,6 +32,12 @@ export function computeCrapScore(cc: number, coverage: number): number {
   return cc * cc * Math.pow(1 - cov, 3) + cc;
 }
 
+function percentile(arr: number[], p: number): number {
+  if (arr.length === 0) return 0;
+  const idx = Math.floor((p / 100) * (arr.length - 1));
+  return arr[idx];
+}
+
 /**
  * Compute cyclomatic and cognitive complexity for all Function/Method nodes
  * in the knowledge graph. Uses graph degree as a proxy for decision points
@@ -41,9 +47,11 @@ export function computeCrapScore(cc: number, coverage: number): number {
  * - Cognitive complexity proxy: (endLine - startLine) / 10, capped at 20
  * - LOC: endLine - startLine + 1 (or 1 if missing)
  * - CRAP: computed with coverage = 0 (worst-case, no test data available)
+ *
+ * Batches all SQL work to avoid N+1 queries (2 GROUP BY queries replace 2×N individual queries).
  */
 export function computeComplexity(db: MonographDb): ComplexityReport {
-  // Query all function/method nodes
+  // Fetch all function/method nodes in one query
   const rows = db.prepare(`
     SELECT id, name, file_path, start_line, end_line, properties
     FROM nodes
@@ -57,52 +65,53 @@ export function computeComplexity(db: MonographDb): ComplexityReport {
     properties: string | null;
   }>;
 
+  if (rows.length === 0) {
+    return { functions: [], p50cc: 0, p90cc: 0, p95cc: 0, highComplexityCount: 0, criticalCount: 0 };
+  }
+
+  // ── Batch edge counts: 2 GROUP BY queries replace 2×N individual queries ─
+  const callsMap = new Map<string, number>();
+  for (const { source_id, c } of db.prepare(`
+    SELECT source_id, COUNT(*) as c FROM edges WHERE relation = 'CALLS' GROUP BY source_id
+  `).all() as { source_id: string; c: number }[]) {
+    callsMap.set(source_id, c);
+  }
+
+  const accessesMap = new Map<string, number>();
+  for (const { source_id, c } of db.prepare(`
+    SELECT source_id, COUNT(*) as c FROM edges WHERE relation = 'ACCESSES' GROUP BY source_id
+  `).all() as { source_id: string; c: number }[]) {
+    accessesMap.set(source_id, c);
+  }
+
+  // ── Compute metrics for each function ────────────────────────────────────
   const functions: FunctionComplexity[] = [];
+  const propUpdates: Array<{ id: string; props: string }> = [];
 
   for (const row of rows) {
     const props = row.properties ? JSON.parse(row.properties) as Record<string, unknown> : {};
 
-    // Outgoing CALLS edges (decision points proxy)
-    const callsCount = (db.prepare(`
-      SELECT COUNT(*) as c FROM edges
-      WHERE source_id = ? AND relation = 'CALLS'
-    `).get(row.id) as { c: number }).c;
-
-    // Outgoing ACCESSES edges
-    const accessesCount = (db.prepare(`
-      SELECT COUNT(*) as c FROM edges
-      WHERE source_id = ? AND relation = 'ACCESSES'
-    `).get(row.id) as { c: number }).c;
+    const callsCount = callsMap.get(row.id) ?? 0;
+    const accessesCount = accessesMap.get(row.id) ?? 0;
 
-    // Cyclomatic complexity proxy: decision points + 1
     const cyclomaticComplexity = Math.round(callsCount * 0.5 + accessesCount * 0.2 + 1);
 
-    // Cognitive complexity proxy: nesting depth approximation capped at 20
     const lineSpan = (row.start_line != null && row.end_line != null)
       ? row.end_line - row.start_line
       : 0;
     const cognitiveComplexity = Math.min(Math.round(lineSpan / 10), 20);
-
-    // LOC
     const linesOfCode = (row.start_line != null && row.end_line != null)
       ? row.end_line - row.start_line + 1
       : 1;
 
-    // Param count from stored properties
     const paramCount = typeof props.paramCount === 'number' ? props.paramCount : 0;
-
-    // CRAP score with no coverage data (worst-case: coverage = 0)
     const crapScore = computeCrapScore(cyclomaticComplexity, 0);
 
-    // Store computed metrics back onto the node properties
-    const updatedProps = {
-      ...props,
-      cyclomaticComplexity,
-      cognitiveComplexity,
-      crapScore,
-    };
-    db.prepare('UPDATE nodes SET properties = ? WHERE id = ?')
-      .run(JSON.stringify(updatedProps), row.id);
+    // Stage property update — batched in a single transaction below
+    propUpdates.push({
+      id: row.id,
+      props: JSON.stringify({ ...props, cyclomaticComplexity, cognitiveComplexity, crapScore }),
+    });
 
     functions.push({
       nodeId: row.id,
@@ -118,28 +127,74 @@ export function computeComplexity(db: MonographDb): ComplexityReport {
     });
   }
 
-  // Compute percentiles for cyclomatic complexity
-  const ccValues = functions.map(f => f.cyclomaticComplexity).sort((a, b) => a - b);
-  const len = ccValues.length;
-
-  function percentile(arr: number[], p: number): number {
-    if (arr.length === 0) return 0;
-    const idx = Math.floor((p / 100) * (arr.length - 1));
-    return arr[idx];
-  }
+  // ── 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);
 
-  const p50cc = percentile(ccValues, 50);
-  const p90cc = percentile(ccValues, 90);
-  const p95cc = percentile(ccValues, 95);
-  const highComplexityCount = functions.filter(f => f.cyclomaticComplexity > 10).length;
-  const criticalCount = functions.filter(f => f.cyclomaticComplexity > 20).length;
+  // ── Compute percentiles ───────────────────────────────────────────────────
+  const ccValues = functions.map(f => f.cyclomaticComplexity).sort((a, b) => a - b);
 
   return {
     functions,
-    p50cc,
-    p90cc,
-    p95cc,
-    highComplexityCount,
-    criticalCount,
+    p50cc: percentile(ccValues, 50),
+    p90cc: percentile(ccValues, 90),
+    p95cc: percentile(ccValues, 95),
+    highComplexityCount: functions.filter(f => f.cyclomaticComplexity > 10).length,
+    criticalCount: functions.filter(f => f.cyclomaticComplexity > 20).length,
   };
 }
+
+/**
+ * Format a ComplexityReport as structured text with file:line hints for LLM navigation.
+ *
+ * @param report - ComplexityReport from computeComplexity()
+ * @param topN - number of worst offenders to list (default 10)
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatComplexity(report: ComplexityReport, topN = 10): string {
+  const { functions, p50cc, p90cc, p95cc, highComplexityCount, criticalCount } = report;
+
+  if (functions.length === 0) {
+    return 'complexity: no Function/Method nodes found in graph\n';
+  }
+
+  const lines: string[] = [
+    `complexity: ${functions.length} functions analysed`,
+    `  p50_cc: ${p50cc}  p90_cc: ${p90cc}  p95_cc: ${p95cc}`,
+    `  high(cc>10): ${highComplexityCount}  critical(cc>20): ${criticalCount}`,
+    '',
+  ];
+
+  // Sort by crapScore descending (worst first)
+  const worst = [...functions]
+    .sort((a, b) => b.crapScore - a.crapScore)
+    .slice(0, topN);
+
+  if (worst.length > 0) {
+    lines.push(`top_${topN}_worst_crap:`);
+    for (const fn of worst) {
+      const loc = fn.filePath
+        ? `${fn.filePath}:${fn.startLine ?? 1}`
+        : `<unknown>:1`;
+      lines.push(`  - ${fn.name}`);
+      lines.push(`    file: ${loc}`);
+      lines.push(`    cc: ${fn.cyclomaticComplexity}  crap: ${fn.crapScore.toFixed(1)}  loc: ${fn.linesOfCode}`);
+    }
+    lines.push('');
+  }
+
+  const critical = functions.filter(f => f.cyclomaticComplexity > 20);
+  if (critical.length > 0) {
+    lines.push(`critical_functions(cc>20): ${critical.length}`);
+    for (const fn of critical.slice(0, 5)) {
+      const loc = fn.filePath ? `${fn.filePath}:${fn.startLine ?? 1}` : `<unknown>:1`;
+      lines.push(`  - ${fn.name}  file: ${loc}  cc: ${fn.cyclomaticComplexity}`);
+    }
+    if (critical.length > 5) lines.push(`  ... and ${critical.length - 5} more`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/graph/cross-reference-findings.ts

@@ -36,6 +36,23 @@ export function crossReference(duplication: CrossRefDuplicationReport, deadCode:
   const findings: CombinedFinding[] = [];
   let clonesInUnusedFiles = 0, clonesWithUnusedExports = 0;
 
+  // Preindex unusedExports and unusedTypes by file path to avoid O(N) Array.find
+  // per clone instance. Each lookup becomes an O(1) Map get + a short in-range scan
+  // over the candidates for that specific file.
+  const exportsByPath = new Map<string, Array<{ exportName: string; line: number }>>();
+  for (const e of deadCode.unusedExports) {
+    const bucket = exportsByPath.get(e.path) ?? [];
+    bucket.push({ exportName: e.exportName, line: e.line });
+    exportsByPath.set(e.path, bucket);
+  }
+
+  const typesByPath = new Map<string, Array<{ typeName: string; line: number }>>();
+  for (const t of deadCode.unusedTypes) {
+    const bucket = typesByPath.get(t.path) ?? [];
+    bucket.push({ typeName: t.typeName, line: t.line });
+    typesByPath.set(t.path, bucket);
+  }
+
   for (let gi = 0; gi < duplication.cloneGroups.length; gi++) {
     for (const inst of duplication.cloneGroups[gi].instances) {
       if (deadCode.unusedFiles.has(inst.file)) {
@@ -43,13 +60,17 @@ export function crossReference(duplication: CrossRefDuplicationReport, deadCode:
         clonesInUnusedFiles++;
         continue;
       }
-      const overlap = deadCode.unusedExports.find(e => e.path === inst.file && e.line >= inst.startLine && e.line <= inst.endLine);
+
+      const exportsForFile = exportsByPath.get(inst.file);
+      const overlap = exportsForFile?.find(e => e.line >= inst.startLine && e.line <= inst.endLine);
       if (overlap) {
         findings.push({ cloneInstance: inst, deadCodeKind: { type: 'unused-export', exportName: overlap.exportName }, groupIndex: gi });
         clonesWithUnusedExports++;
         continue;
       }
-      const typeOverlap = deadCode.unusedTypes.find(t => t.path === inst.file && t.line >= inst.startLine && t.line <= inst.endLine);
+
+      const typesForFile = typesByPath.get(inst.file);
+      const typeOverlap = typesForFile?.find(t => t.line >= inst.startLine && t.line <= inst.endLine);
       if (typeOverlap) {
         findings.push({ cloneInstance: inst, deadCodeKind: { type: 'unused-type', typeName: typeOverlap.typeName }, groupIndex: gi });
         clonesWithUnusedExports++;

package/src/graph/cross-reference.ts

@@ -111,3 +111,29 @@ export function crossReferenceDuplicatesAndDeadCode(db: MonographDb): CrossRefer
     crossCount: crossIds.length,
   };
 }
+
+/**
+ * Format a CrossReferenceReport as structured text for LLM consumption.
+ */
+export function formatCrossReferenceReport(report: CrossReferenceReport): string {
+  const lines: string[] = [
+    `Cross-reference analysis: dead code × structural duplicates`,
+    `  Dead (unreachable) file nodes : ${report.deadCount}`,
+    `  Duplicated file nodes         : ${report.duplicateCount}`,
+    `  Both dead AND duplicated      : ${report.crossCount}  (highest-confidence safe-delete candidates)`,
+  ];
+
+  if (report.crossCount === 0) {
+    lines.push('  No cross-referenced candidates found.');
+    return lines.join('\n');
+  }
+
+  lines.push('');
+  lines.push('Safe-delete candidates:');
+  for (const f of report.findings) {
+    const loc = f.filePath ? `  ${f.filePath}` : `  (no path) ${f.nodeName}`;
+    lines.push(loc);
+    lines.push(`    ${f.description}`);
+  }
+  return lines.join('\n');
+}

package/src/graph/cycle-detection.ts

@@ -25,7 +25,12 @@ function canonicalCycle(cycle: number[], idToPath: Map<number, string>): number[
       minPos = i;
     }
   }
-  return [...cycle.slice(minPos), ...cycle.slice(0, minPos)];
+  if (minPos === 0) return cycle.slice(); // already canonical — single allocation
+  // Single-pass rotation without 3 intermediate arrays (2x slice + spread)
+  const n = cycle.length;
+  const result = new Array<number>(n);
+  for (let i = 0; i < n; i++) result[i] = cycle[(minPos + i) % n];
+  return result;
 }
 
 function tryRecordCycle(
@@ -103,7 +108,8 @@ function enumerateElementaryCycles(
   const cycles: number[][] = [];
   const seen = new Set<string>();
 
-  const sortedNodes = [...sccNodes].sort((a, b) => {
+  // Use slice() rather than spread to avoid the iterator allocation overhead
+  const sortedNodes = sccNodes.slice().sort((a, b) => {
     const pa = idToPath.get(a) ?? '';
     const pb = idToPath.get(b) ?? '';
     return pa < pb ? -1 : pa > pb ? 1 : 0;
@@ -284,9 +290,22 @@ export function findCycles(
   });
 
   return result.map(cycle => ({
-    files: [...cycle]
+    // slice() instead of spread to avoid iterator overhead
+    files: cycle.slice()
       .sort((a, b) => (idToPath.get(a) ?? '').localeCompare(idToPath.get(b) ?? ''))
       .map(id => idToPath.get(id) ?? String(id)),
     length: cycle.length,
   }));
 }
+
+/** Format cycle groups as structured text for LLM consumption. */
+export function formatCycleGroups(groups: CycleGroup[]): string {
+  if (groups.length === 0) return 'No import cycles detected.';
+  const lines: string[] = [`Import Cycles (${groups.length} total):`];
+  for (const g of groups.slice(0, 30)) {
+    lines.push(`\n  Cycle (length ${g.length}):`);
+    for (const f of g.files) lines.push(`    ${f}`);
+  }
+  if (groups.length > 30) lines.push(`\n  ... and ${groups.length - 30} more cycles`);
+  return lines.join('\n');
+}

package/src/graph/cycles.ts

@@ -1,71 +1,127 @@
 import type { MonographDb } from '../storage/db.js';
 
-/**
- * Find ALL strongly connected components (SCCs) using Kosaraju's algorithm.
- *
- * Returns every SCC, including singleton components (single nodes with no self-loop).
- * This is the full SCC decomposition of the graph.
- *
- * @param db - The MonographDb instance
- * @returns Array of SCCs; each SCC is an array of node ids in that component.
- */
-export function findStronglyConnectedComponents(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);
+/** Build adjacency maps from DB rows (shared by both exports). */
+function buildAdjacency(
+  nodes: string[],
+  edgeRows: { source_id: string; target_id: string }[],
+): {
+  adj: Map<string, string[]>;
+  radj: Map<string, string[]>;
+  selfLoops: Set<string>;
+} {
   const nodeSet = new Set(nodes);
-
   const adj = new Map<string, string[]>();
   const radj = new Map<string, string[]>();
   for (const n of nodes) {
     adj.set(n, []);
     radj.set(n, []);
   }
-
+  const selfLoops = new Set<string>();
   for (const { source_id: src, target_id: tgt } of edgeRows) {
     if (!nodeSet.has(src) || !nodeSet.has(tgt)) continue;
-    if (src === tgt) continue;
+    if (src === tgt) {
+      selfLoops.add(src);
+      continue;
+    }
     adj.get(src)!.push(tgt);
     radj.get(tgt)!.push(src);
   }
+  return { adj, radj, selfLoops };
+}
 
-  const visited = new Set<string>();
-  const finishOrder: string[] = [];
-
-  function dfs1(node: string): void {
-    visited.add(node);
-    for (const neighbor of adj.get(node) ?? []) {
-      if (!visited.has(neighbor)) dfs1(neighbor);
+/** Iterative DFS pass 1: populate finish order (replaces recursive dfs1). */
+function iterativeDfs1(
+  roots: string[],
+  adj: Map<string, string[]>,
+  visited: Set<string>,
+  finishOrder: string[],
+): void {
+  for (const root of roots) {
+    if (visited.has(root)) continue;
+    // Stack entries: [node, neighborIndex]
+    const stack: [string, number][] = [[root, 0]];
+    visited.add(root);
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const [node, idx] = frame;
+      const neighbors = adj.get(node) ?? [];
+      if (idx < neighbors.length) {
+        frame[1]++;
+        const neighbor = neighbors[idx];
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          stack.push([neighbor, 0]);
+        }
+      } else {
+        stack.pop();
+        finishOrder.push(node);
+      }
     }
-    finishOrder.push(node);
   }
+}
 
-  for (const node of nodes) {
-    if (!visited.has(node)) dfs1(node);
-  }
-
-  const assigned = new Set<string>();
-  const sccs: string[][] = [];
-
-  function dfs2(node: string, component: string[]): void {
-    assigned.add(node);
+/** Iterative DFS pass 2: collect SCC component (replaces recursive dfs2). */
+function iterativeDfs2(
+  root: string,
+  radj: Map<string, string[]>,
+  assigned: Set<string>,
+  component: string[],
+): void {
+  const stack: string[] = [root];
+  assigned.add(root);
+  while (stack.length > 0) {
+    const node = stack.pop()!;
     component.push(node);
     for (const neighbor of radj.get(node) ?? []) {
-      if (!assigned.has(neighbor)) dfs2(neighbor, component);
+      if (!assigned.has(neighbor)) {
+        assigned.add(neighbor);
+        stack.push(neighbor);
+      }
     }
   }
+}
+
+/**
+ * Fetch nodes and edges once and return raw rows (shared helper).
+ */
+function fetchGraphRows(db: MonographDb): {
+  nodes: string[];
+  edgeRows: { source_id: string; target_id: 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;
+  }[];
+  return { nodes: nodeRows.map(r => r.id), edgeRows };
+}
+
+/**
+ * Find ALL strongly connected components (SCCs) using iterative Kosaraju's algorithm.
+ *
+ * Returns every SCC, including singleton components (single nodes with no self-loop).
+ * This is the full SCC decomposition of the graph.
+ *
+ * @param db - The MonographDb instance
+ * @returns Array of SCCs; each SCC is an array of node ids in that component.
+ */
+export function findStronglyConnectedComponents(db: MonographDb): string[][] {
+  const { nodes, edgeRows } = fetchGraphRows(db);
+  if (nodes.length === 0) return [];
 
+  const { adj, radj } = buildAdjacency(nodes, edgeRows);
+
+  const visited = new Set<string>();
+  const finishOrder: string[] = [];
+  iterativeDfs1(nodes, adj, visited, finishOrder);
+
+  const assigned = new Set<string>();
+  const sccs: string[][] = [];
   for (let i = finishOrder.length - 1; i >= 0; i--) {
     const node = finishOrder[i];
     if (!assigned.has(node)) {
       const component: string[] = [];
-      dfs2(node, component);
+      iterativeDfs2(node, radj, assigned, component);
       sccs.push(component);
     }
   }
@@ -77,77 +133,31 @@ export function findStronglyConnectedComponents(db: MonographDb): string[][] {
  * Find all strongly connected components (SCCs) with more than 1 node,
  * or self-loops, and return them as cycle node lists.
  *
- * Uses Kosaraju's algorithm to find SCCs. Each SCC with size > 1 represents
- * a cycle. Self-loops (node -> itself) are also detected separately.
+ * Uses iterative Kosaraju's algorithm to avoid stack overflow on large graphs.
+ * Each SCC with size > 1 represents a cycle. Self-loops are also detected.
  *
  * @param db - The MonographDb instance
  * @returns Array of cycles; each cycle is an array of node ids participating in it.
  */
 export function findCycles(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 nodeSet = new Set(nodes);
+  const { nodes, edgeRows } = fetchGraphRows(db);
+  if (nodes.length === 0) return [];
 
-  // Build adjacency list and reverse adjacency list
-  const adj = new Map<string, string[]>();
-  const radj = new Map<string, string[]>();
-  for (const n of nodes) {
-    adj.set(n, []);
-    radj.set(n, []);
-  }
-
-  const selfLoops = new Set<string>();
-
-  for (const { source_id: src, target_id: tgt } of edgeRows) {
-    if (!nodeSet.has(src) || !nodeSet.has(tgt)) continue;
-    if (src === tgt) {
-      selfLoops.add(src);
-      continue;
-    }
-    adj.get(src)!.push(tgt);
-    radj.get(tgt)!.push(src);
-  }
+  const { adj, radj, selfLoops } = buildAdjacency(nodes, edgeRows);
 
-  // Kosaraju's algorithm — pass 1: DFS on original graph, build finish order
+  // Pass 1: iterative DFS on original graph, build finish order
   const visited = new Set<string>();
   const finishOrder: string[] = [];
+  iterativeDfs1(nodes, adj, visited, finishOrder);
 
-  function dfs1(node: string): void {
-    visited.add(node);
-    for (const neighbor of adj.get(node) ?? []) {
-      if (!visited.has(neighbor)) dfs1(neighbor);
-    }
-    finishOrder.push(node);
-  }
-
-  for (const node of nodes) {
-    if (!visited.has(node)) dfs1(node);
-  }
-
-  // Kosaraju's algorithm — pass 2: DFS on reverse graph in reverse finish order
+  // Pass 2: iterative DFS on reverse graph in reverse finish order
   const assigned = new Set<string>();
   const sccs: string[][] = [];
-
-  function dfs2(node: string, component: string[]): void {
-    assigned.add(node);
-    component.push(node);
-    for (const neighbor of radj.get(node) ?? []) {
-      if (!assigned.has(neighbor)) dfs2(neighbor, component);
-    }
-  }
-
   for (let i = finishOrder.length - 1; i >= 0; i--) {
     const node = finishOrder[i];
     if (!assigned.has(node)) {
       const component: string[] = [];
-      dfs2(node, component);
+      iterativeDfs2(node, radj, assigned, component);
       if (component.length > 1) {
         sccs.push(component);
       }
@@ -161,3 +171,52 @@ export function findCycles(db: MonographDb): string[][] {
 
   return sccs;
 }
+
+/**
+ * Format cycle results as structured text with file:line hints for LLM navigation.
+ *
+ * @param cycles - Array of cycle arrays (node ids / file paths)
+ * @param nodeToFile - Optional map from node id to file path for resolving paths
+ * @returns Structured text output suitable for LLM consumption
+ */
+export function formatCycles(
+  cycles: string[][],
+  nodeToFile?: Map<string, string>,
+): string {
+  if (cycles.length === 0) {
+    return 'cycles: none\nstatus: no circular dependencies detected\n';
+  }
+
+  const resolve = (id: string): string => nodeToFile?.get(id) ?? id;
+
+  const lines: string[] = [
+    `cycles: ${cycles.length} circular dependency group(s) found`,
+    '',
+  ];
+
+  // Sort by cycle length ascending, then alphabetically
+  const sorted = [...cycles].sort((a, b) => {
+    if (a.length !== b.length) return a.length - b.length;
+    return resolve(a[0]).localeCompare(resolve(b[0]));
+  });
+
+  sorted.forEach((cycle, i) => {
+    const isSelfLoop = cycle.length === 1;
+    const label = isSelfLoop ? 'self-loop' : `cycle(${cycle.length})`;
+    lines.push(`[${i + 1}] ${label}`);
+    for (const node of cycle) {
+      lines.push(`  file: ${resolve(node)}:1`);
+    }
+    if (!isSelfLoop) {
+      // Show the closing edge
+      lines.push(`  closes: ${resolve(cycle[cycle.length - 1])} → ${resolve(cycle[0])}`);
+    }
+    lines.push('');
+  });
+
+  const selfLoopCount = sorted.filter(c => c.length === 1).length;
+  const multiNodeCount = sorted.length - selfLoopCount;
+  lines.push(`summary: ${multiNodeCount} multi-node cycle(s), ${selfLoopCount} self-loop(s)`);
+
+  return lines.join('\n');
+}