@monoes/monograph 1.5.6 → 1.5.7

package/src/graph/cycle-detection.ts

@@ -1,311 +0,0 @@
-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

@@ -1,222 +0,0 @@
-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

@@ -1,128 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-/**
- * Detect dead code: exported top-level functions with zero inbound references.
- *
- * Limited to Function nodes only — the graph tracks CALLS edges for functions
- * but has near-zero coverage for Interface/TypeAlias/Class usage.
- *
- * Filters:
- * - Only top-level functions (File CONTAINS node) — skips nested closures
- * - Only exported — private locals are internal by design
- * - Skips entry-point, test, dist, and node_modules paths
- * - Requires zero inbound CALLS, IMPORTS, REFERENCES, and RE_EXPORTS edges
- * - Not re-exported through any index.ts barrel file, via an actual RE_EXPORTS
- *   edge from that barrel's File node (not merely sharing a name with something
- *   an index.ts happens to also define)
- *
- * Known gap: files consumed only via a dynamic `import()` call won't have a static
- * edge in the graph, so they can still surface as false positives here — this
- * detector only tracks statically-resolved edges.
- */
-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;
-}
-
-export function detectDeadCodeNodes(db: MonographDb): DeadCodeNode[] {
-  // monolean: only Function — graph lacks edges for Interface/TypeAlias/Class usage
-  const rows = db
-    .prepare(
-      `SELECT n.id, n.name, n.file_path, n.start_line, n.label
-       FROM nodes n
-       WHERE n.is_exported = 1
-         AND n.label = 'Function'
-         AND n.file_path IS NOT NULL
-         AND n.file_path NOT LIKE '%/dist/%'
-         AND n.file_path NOT LIKE '%node_modules%'
-         AND n.file_path NOT LIKE '%__tests__%'
-         AND n.file_path NOT LIKE '%.test.%'
-         AND n.file_path NOT LIKE '%.spec.%'
-         AND n.file_path NOT LIKE '%/index.%'
-         AND n.file_path NOT LIKE 'bin/%'
-         AND n.file_path NOT LIKE '%/cli.ts'
-         AND n.file_path NOT LIKE '%/main.ts'
-         -- top-level only: parent is a File node
-         AND EXISTS (
-           SELECT 1 FROM edges e
-           JOIN nodes p ON e.source_id = p.id
-           WHERE e.target_id = n.id AND e.relation = 'CONTAINS' AND p.label = 'File'
-         )
-         -- no inbound usage edges of any kind
-         AND NOT EXISTS (
-           SELECT 1 FROM edges e
-           WHERE e.target_id = n.id
-             AND e.relation IN ('CALLS', 'IMPORTS', 'REFERENCES', 'RE_EXPORTS')
-         )
-         -- not re-exported through a barrel (index.ts/index.js) — checked via an
-         -- ACTUAL RE_EXPORTS edge from the barrel's File node to this candidate's
-         -- File node, not a same-NAME coincidence with an unrelated symbol that
-         -- happens to also live in some index.ts elsewhere in the repo.
-         AND NOT EXISTS (
-           SELECT 1 FROM edges e
-           JOIN nodes fn ON fn.id = e.target_id AND fn.label = 'File'
-           JOIN nodes bn ON bn.id = e.source_id AND bn.label = 'File'
-           WHERE e.relation = 'RE_EXPORTS'
-             AND fn.file_path = n.file_path
-             AND bn.file_path LIKE '%/index.%'
-             AND bn.file_path NOT LIKE '%/dist/%'
-             AND bn.file_path NOT LIKE '%node_modules%'
-         )
-       ORDER BY n.file_path, n.start_line`,
-    )
-    .all() as {
-    id: string;
-    name: string;
-    file_path: string | null;
-    start_line: number | null;
-    label: string;
-  }[];
-
-  return rows.map(r => ({
-    id: r.id,
-    name: r.name,
-    filePath: r.file_path,
-    startLine: r.start_line,
-    label: r.label,
-  }));
-}
-
-/**
- * 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 candidates: ${nodes.length} exported function${nodes.length === 1 ? '' : 's'} with no graph references`,
-    '(Candidates only — verify with grep before removing)',
-    '',
-  ];
-
-  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');
-}