@monoes/monograph 1.1.0 → 1.2.1

package/src/graph/cycle-detection.ts

@@ -0,0 +1,311 @@
+export interface CycleGroup {
+  files: string[];
+  length: number;
+}
+
+interface TarjanFrame {
+  node: number;
+  succPos: number;
+  succEnd: number;
+}
+
+interface CycleFrame {
+  succPos: number;
+  succEnd: number;
+}
+
+function canonicalCycle(cycle: number[], idToPath: Map<number, string>): number[] {
+  if (cycle.length === 0) return [];
+  let minPos = 0;
+  let minPath = idToPath.get(cycle[0]) ?? '';
+  for (let i = 1; i < cycle.length; i++) {
+    const p = idToPath.get(cycle[i]) ?? '';
+    if (p < minPath) {
+      minPath = p;
+      minPos = i;
+    }
+  }
+  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(
+  path: number[],
+  idToPath: Map<number, string>,
+  seen: Set<string>,
+  cycles: number[][],
+): void {
+  const canonical = canonicalCycle(path, idToPath);
+  const key = canonical.join(',');
+  if (seen.has(key)) return;
+  seen.add(key);
+  cycles.push(canonical);
+}
+
+function dfsFindCyclesFrom(
+  start: number,
+  depthLimit: number,
+  sccSet: Set<number>,
+  allSuccs: number[],
+  succRanges: Map<number, [number, number]>,
+  maxCycles: number,
+  seen: Set<string>,
+  cycles: number[][],
+  idToPath: Map<number, string>,
+): void {
+  const path: number[] = [start];
+  const pathSet = new Set<number>([start]);
+  const range = succRanges.get(start) ?? [0, 0];
+  const dfs: CycleFrame[] = [{ succPos: range[0], succEnd: range[1] }];
+
+  while (dfs.length > 0) {
+    if (cycles.length >= maxCycles) return;
+
+    const frame = dfs[dfs.length - 1];
+    if (frame.succPos >= frame.succEnd) {
+      dfs.pop();
+      if (path.length > 1) {
+        const removed = path.pop()!;
+        pathSet.delete(removed);
+      }
+      continue;
+    }
+
+    const w = allSuccs[frame.succPos];
+    frame.succPos++;
+
+    if (!sccSet.has(w)) continue;
+
+    if (w === start && path.length >= 2 && path.length === depthLimit) {
+      tryRecordCycle(path, idToPath, seen, cycles);
+      continue;
+    }
+
+    if (pathSet.has(w) || path.length >= depthLimit) continue;
+
+    path.push(w);
+    pathSet.add(w);
+
+    const wRange = succRanges.get(w) ?? [0, 0];
+    dfs.push({ succPos: wRange[0], succEnd: wRange[1] });
+  }
+}
+
+function enumerateElementaryCycles(
+  sccNodes: number[],
+  allSuccs: number[],
+  succRanges: Map<number, [number, number]>,
+  maxCycles: number,
+  idToPath: Map<number, string>,
+  skipTypeOnly: boolean,
+  typeOnlyEdges: Set<string>,
+): number[][] {
+  const sccSet = new Set(sccNodes);
+  const cycles: number[][] = [];
+  const seen = new Set<string>();
+
+  // 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;
+  });
+
+  const maxDepth = Math.min(sccNodes.length, 12);
+  for (let depthLimit = 2; depthLimit <= maxDepth; depthLimit++) {
+    if (cycles.length >= maxCycles) break;
+    for (const start of sortedNodes) {
+      if (cycles.length >= maxCycles) break;
+      dfsFindCyclesFrom(
+        start,
+        depthLimit,
+        sccSet,
+        allSuccs,
+        succRanges,
+        maxCycles,
+        seen,
+        cycles,
+        idToPath,
+      );
+    }
+  }
+
+  return cycles;
+}
+
+export function findCycles(
+  fileIds: number[],
+  edges: Map<number, number[]>,
+  idToPath: Map<number, string>,
+  skipTypeOnly = false,
+  typeOnlyEdges: Set<string> = new Set(),
+): CycleGroup[] {
+  const n = fileIds.length;
+  if (n === 0) return [];
+
+  const idIndex = new Map<number, number>();
+  for (let i = 0; i < fileIds.length; i++) {
+    idIndex.set(fileIds[i], i);
+  }
+
+  const allSuccs: number[] = [];
+  const succRanges = new Map<number, [number, number]>();
+
+  for (const id of fileIds) {
+    const start = allSuccs.length;
+    const seen = new Set<number>();
+    const neighbors = edges.get(id) ?? [];
+    for (const neighbor of neighbors) {
+      if (skipTypeOnly && typeOnlyEdges.has(`${id}→${neighbor}`)) continue;
+      if (idIndex.has(neighbor) && !seen.has(neighbor)) {
+        seen.add(neighbor);
+        allSuccs.push(neighbor);
+      }
+    }
+    succRanges.set(id, [start, allSuccs.length]);
+  }
+
+  const UNDEF = 0xffffffff;
+  const indices: number[] = new Array(n).fill(UNDEF);
+  const lowlinks: number[] = new Array(n).fill(0);
+  const onStack: boolean[] = new Array(n).fill(false);
+  const stack: number[] = [];
+  const sccs: number[][] = [];
+  let indexCounter = 0;
+
+  const dfsStack: TarjanFrame[] = [];
+
+  for (let startI = 0; startI < n; startI++) {
+    if (indices[startI] !== UNDEF) continue;
+
+    const startId = fileIds[startI];
+    indices[startI] = indexCounter;
+    lowlinks[startI] = indexCounter;
+    indexCounter++;
+    onStack[startI] = true;
+    stack.push(startI);
+
+    const startRange = succRanges.get(startId) ?? [0, 0];
+    dfsStack.push({ node: startI, succPos: startRange[0], succEnd: startRange[1] });
+
+    while (dfsStack.length > 0) {
+      const frame = dfsStack[dfsStack.length - 1];
+      if (frame.succPos < frame.succEnd) {
+        const wId = allSuccs[frame.succPos];
+        frame.succPos++;
+
+        const wI = idIndex.get(wId);
+        if (wI === undefined) continue;
+
+        if (indices[wI] === UNDEF) {
+          indices[wI] = indexCounter;
+          lowlinks[wI] = indexCounter;
+          indexCounter++;
+          onStack[wI] = true;
+          stack.push(wI);
+
+          const wId2 = fileIds[wI];
+          const wRange = succRanges.get(wId2) ?? [0, 0];
+          dfsStack.push({ node: wI, succPos: wRange[0], succEnd: wRange[1] });
+        } else if (onStack[wI]) {
+          const v = frame.node;
+          if (indices[wI] < lowlinks[v]) {
+            lowlinks[v] = indices[wI];
+          }
+        }
+      } else {
+        const v = frame.node;
+        const vLowlink = lowlinks[v];
+        const vIndex = indices[v];
+        dfsStack.pop();
+
+        if (dfsStack.length > 0) {
+          const parent = dfsStack[dfsStack.length - 1];
+          if (vLowlink < lowlinks[parent.node]) {
+            lowlinks[parent.node] = vLowlink;
+          }
+        }
+
+        if (vLowlink === vIndex) {
+          const scc: number[] = [];
+          while (true) {
+            const w = stack.pop()!;
+            onStack[w] = false;
+            scc.push(fileIds[w]);
+            if (w === v) break;
+          }
+          if (scc.length >= 2) {
+            sccs.push(scc);
+          }
+        }
+      }
+    }
+  }
+
+  const MAX_CYCLES_PER_SCC = 20;
+  const result: number[][] = [];
+  const seenCycles = new Set<string>();
+
+  for (const scc of sccs) {
+    if (scc.length === 2) {
+      const pathA = idToPath.get(scc[0]) ?? '';
+      const pathB = idToPath.get(scc[1]) ?? '';
+      const cycle = pathA <= pathB ? [scc[0], scc[1]] : [scc[1], scc[0]];
+      const key = cycle.join(',');
+      if (!seenCycles.has(key)) {
+        seenCycles.add(key);
+        result.push(cycle);
+      }
+      continue;
+    }
+
+    const elementary = enumerateElementaryCycles(
+      scc,
+      allSuccs,
+      succRanges,
+      MAX_CYCLES_PER_SCC,
+      idToPath,
+      skipTypeOnly,
+      typeOnlyEdges,
+    );
+
+    for (const cycle of elementary) {
+      const key = cycle.join(',');
+      if (!seenCycles.has(key)) {
+        seenCycles.add(key);
+        result.push(cycle);
+      }
+    }
+  }
+
+  result.sort((a, b) => {
+    if (a.length !== b.length) return a.length - b.length;
+    const pa = idToPath.get(a[0]) ?? '';
+    const pb = idToPath.get(b[0]) ?? '';
+    return pa < pb ? -1 : pa > pb ? 1 : 0;
+  });
+
+  return result.map(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

@@ -0,0 +1,222 @@
+import type { MonographDb } from '../storage/db.js';
+
+/** 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) {
+      selfLoops.add(src);
+      continue;
+    }
+    adj.get(src)!.push(tgt);
+    radj.get(tgt)!.push(src);
+  }
+  return { adj, radj, selfLoops };
+}
+
+/** 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);
+      }
+    }
+  }
+}
+
+/** 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)) {
+        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[] = [];
+      iterativeDfs2(node, radj, assigned, component);
+      sccs.push(component);
+    }
+  }
+
+  return sccs;
+}
+
+/**
+ * Find all strongly connected components (SCCs) with more than 1 node,
+ * or self-loops, and return them as cycle node lists.
+ *
+ * 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 { nodes, edgeRows } = fetchGraphRows(db);
+  if (nodes.length === 0) return [];
+
+  const { adj, radj, selfLoops } = buildAdjacency(nodes, edgeRows);
+
+  // Pass 1: iterative DFS on original graph, build finish order
+  const visited = new Set<string>();
+  const finishOrder: string[] = [];
+  iterativeDfs1(nodes, adj, visited, finishOrder);
+
+  // Pass 2: iterative DFS on reverse graph in reverse finish order
+  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[] = [];
+      iterativeDfs2(node, radj, assigned, component);
+      if (component.length > 1) {
+        sccs.push(component);
+      }
+    }
+  }
+
+  // Add self-loops as single-element cycles
+  for (const node of selfLoops) {
+    sccs.push([node]);
+  }
+
+  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');
+}

package/src/graph/dead-code.ts

@@ -0,0 +1,104 @@
+import type { MonographDb } from '../storage/db.js';
+
+/**
+ * Detect dead code: nodes that have in-degree 0 AND are not marked as exported.
+ *
+ * In a module dependency graph, a node with in-degree 0 is never imported by
+ * any other module. If it is also not explicitly exported (i.e., not an entry-point),
+ * it is considered dead code — unreachable and unused.
+ *
+ * @param db - The MonographDb instance
+ * @returns Array of node ids that are considered dead code.
+ */
+export function detectDeadCode(db: MonographDb): string[] {
+  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 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 { target_id, cnt } of inDegreeRows) {
+    inDegree.set(target_id, cnt);
+  }
+
+  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,
+      });
+    }
+  }
+
+  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.';
+  }
+
+  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');
+}