@monoes/monograph 1.5.3 → 1.5.5

package/src/analysis/cycles.ts

@@ -1,268 +0,0 @@
-import type { MonographDb } from '../storage/db.js';
-
-export interface DependencyCycle {
-  files: string[];         // file paths forming the cycle, in order
-  length: number;
-  isCrossCommunity: boolean;  // true if files span multiple communities
-  edgeRelations: string[];    // relations used in the cycle edges
-}
-
-export interface CycleDetectionResult {
-  cycles: DependencyCycle[];
-  totalCycles: number;
-  filesInCycles: number;
-  longestCycle: number;
-  crossCommunityCycles: number;
-}
-
-interface NodeRow {
-  id: string;
-  file_path: string | null;
-  community_id: number | null;
-}
-
-interface EdgeRow {
-  source_id: string;
-  target_id: string;
-  relation: string;
-}
-
-/**
- * Iterative Tarjan's SCC algorithm to avoid stack overflow on large graphs.
- * Returns arrays of node IDs, each array is one SCC.
- */
-function tarjanSCC(adjacency: Map<string, string[]>, nodes: string[]): string[][] {
-  const index: Map<string, number> = new Map();
-  const lowlink: Map<string, number> = new Map();
-  const onStack: Set<string> = new Set();
-  const stack: string[] = [];
-  const sccs: string[][] = [];
-  let counter = 0;
-
-  // Iterative DFS using explicit call stack
-  for (const startNode of nodes) {
-    if (index.has(startNode)) continue;
-
-    // Each frame: [nodeId, neighborIndex, parent]
-    type Frame = { node: string; neighborIdx: number };
-    const callStack: Frame[] = [{ node: startNode, neighborIdx: 0 }];
-
-    index.set(startNode, counter);
-    lowlink.set(startNode, counter);
-    counter++;
-    stack.push(startNode);
-    onStack.add(startNode);
-
-    while (callStack.length > 0) {
-      const frame = callStack[callStack.length - 1];
-      const { node } = frame;
-      const neighbors = adjacency.get(node) ?? [];
-
-      if (frame.neighborIdx < neighbors.length) {
-        const neighbor = neighbors[frame.neighborIdx];
-        frame.neighborIdx++;
-
-        if (!index.has(neighbor)) {
-          index.set(neighbor, counter);
-          lowlink.set(neighbor, counter);
-          counter++;
-          stack.push(neighbor);
-          onStack.add(neighbor);
-          callStack.push({ node: neighbor, neighborIdx: 0 });
-        } else if (onStack.has(neighbor)) {
-          const curLow = lowlink.get(node)!;
-          const neighborIdx = index.get(neighbor)!;
-          if (neighborIdx < curLow) {
-            lowlink.set(node, neighborIdx);
-          }
-        }
-      } else {
-        // Done with this node — pop and propagate lowlink to parent
-        callStack.pop();
-        if (callStack.length > 0) {
-          const parent = callStack[callStack.length - 1].node;
-          const parentLow = lowlink.get(parent)!;
-          const nodeLow = lowlink.get(node)!;
-          if (nodeLow < parentLow) {
-            lowlink.set(parent, nodeLow);
-          }
-        }
-
-        // If this is an SCC root, pop the stack
-        if (lowlink.get(node) === index.get(node)) {
-          const scc: string[] = [];
-          let w: string;
-          do {
-            w = stack.pop()!;
-            onStack.delete(w);
-            scc.push(w);
-          } while (w !== node);
-          sccs.push(scc);
-        }
-      }
-    }
-  }
-
-  return sccs;
-}
-
-/**
- * Enumerate elementary cycles within a given SCC using DFS.
- * Caps at maxCycles to avoid exponential blowup.
- */
-function findCyclesInSCC(
-  scc: string[],
-  adjacency: Map<string, string[]>,
-  maxCycles: number
-): string[][] {
-  const sccSet = new Set(scc);
-  const cycles: string[][] = [];
-  const seen = new Set<string>();
-
-  for (const startNode of scc) {
-    if (cycles.length >= maxCycles) break;
-
-    const path: string[] = [startNode];
-    const onPath = new Set<string>([startNode]);
-
-    const dfs = (node: string): void => {
-      if (cycles.length >= maxCycles) return;
-      const neighbors = adjacency.get(node) ?? [];
-      for (const neighbor of neighbors) {
-        if (!sccSet.has(neighbor)) continue;
-        if (neighbor === startNode && path.length > 1) {
-          // Found a cycle — normalize via smallest-index-first rotation
-          const canonical = canonicalRotation([...path]);
-          const key = canonical.join('\0');
-          if (!seen.has(key)) {
-            seen.add(key);
-            cycles.push([...path, startNode]);
-          }
-        } else if (!onPath.has(neighbor)) {
-          path.push(neighbor);
-          onPath.add(neighbor);
-          dfs(neighbor);
-          path.pop();
-          onPath.delete(neighbor);
-        }
-      }
-    };
-
-    dfs(startNode);
-  }
-
-  return cycles;
-}
-
-function canonicalRotation(cycle: string[]): string[] {
-  // Find index of lexicographically smallest element
-  let minIdx = 0;
-  for (let i = 1; i < cycle.length; i++) {
-    if (cycle[i] < cycle[minIdx]) minIdx = i;
-  }
-  return [...cycle.slice(minIdx), ...cycle.slice(0, minIdx)];
-}
-
-export function detectCycles(db: MonographDb): CycleDetectionResult {
-  // Load all File nodes
-  const nodeRows = db.prepare(
-    `SELECT id, file_path, community_id FROM nodes WHERE label = 'File'`
-  ).all() as NodeRow[];
-
-  const nodeMap = new Map<string, NodeRow>();
-  for (const row of nodeRows) {
-    nodeMap.set(row.id, row);
-  }
-
-  // Load all IMPORTS and RE_EXPORTS edges between File nodes
-  const edgeRows = db.prepare(
-    `SELECT e.source_id, e.target_id, e.relation
-     FROM edges e
-     WHERE e.relation IN ('IMPORTS', 'RE_EXPORTS')
-       AND e.source_id IN (SELECT id FROM nodes WHERE label = 'File')
-       AND e.target_id IN (SELECT id FROM nodes WHERE label = 'File')`
-  ).all() as EdgeRow[];
-
-  // Build adjacency list
-  const adjacency = new Map<string, string[]>();
-  const edgeRelationMap = new Map<string, string>(); // "src\0tgt" -> relation
-
-  for (const row of nodeRows) {
-    adjacency.set(row.id, []);
-  }
-
-  for (const edge of edgeRows) {
-    const neighbors = adjacency.get(edge.source_id);
-    if (neighbors) {
-      neighbors.push(edge.target_id);
-    }
-    edgeRelationMap.set(`${edge.source_id}\0${edge.target_id}`, edge.relation);
-  }
-
-  // Run Tarjan's SCC
-  const nodeIds = nodeRows.map(n => n.id);
-  const sccs = tarjanSCC(adjacency, nodeIds);
-
-  // SCCs with size > 1 are multi-node cycles; size-1 SCCs are cycles only if self-referencing
-  const cycleSCCs = sccs.filter(scc =>
-    scc.length > 1 || (scc.length === 1 && adjacency.get(scc[0])?.includes(scc[0])),
-  );
-
-  const cycles: DependencyCycle[] = [];
-  const filesInCyclesSet = new Set<string>();
-
-  for (const scc of cycleSCCs) {
-    const elementaryCycles = scc.length === 1
-      ? [[scc[0], scc[0]]]
-      : findCyclesInSCC(scc, adjacency, 20);
-    for (const cyclePath of elementaryCycles) {
-      // cyclePath is [...nodes, startNode] — last element = first
-      const cycleNodes = cyclePath.slice(0, -1);
-
-      for (const nodeId of cycleNodes) {
-        filesInCyclesSet.add(nodeId);
-      }
-
-      // Collect file paths
-      const files = cycleNodes.map(id => nodeMap.get(id)?.file_path ?? id);
-
-      // isCrossCommunity: any two nodes with different community_id
-      const communityIds = cycleNodes
-        .map(id => nodeMap.get(id)?.community_id)
-        .filter((c): c is number => c !== null && c !== undefined);
-      const uniqueCommunities = new Set(communityIds);
-      const isCrossCommunity = uniqueCommunities.size > 1;
-
-      // Collect edge relations used in this cycle
-      const edgeRelations: string[] = [];
-      for (let i = 0; i < cyclePath.length - 1; i++) {
-        const key = `${cyclePath[i]}\0${cyclePath[i + 1]}`;
-        const rel = edgeRelationMap.get(key);
-        if (rel && !edgeRelations.includes(rel)) {
-          edgeRelations.push(rel);
-        }
-      }
-
-      cycles.push({
-        files,
-        length: cycleNodes.length,
-        isCrossCommunity,
-        edgeRelations,
-      });
-    }
-  }
-
-  // Sort by length ascending
-  cycles.sort((a, b) => a.length - b.length);
-
-  const longestCycle = cycles.length > 0 ? cycles.reduce((a, c) => Math.max(a, c.length), 0) : 0;
-  const crossCommunityCycles = cycles.filter(c => c.isCrossCommunity).length;
-
-  return {
-    cycles,
-    totalCycles: cycles.length,
-    filesInCycles: filesInCyclesSet.size,
-    longestCycle,
-    crossCommunityCycles,
-  };
-}

package/src/analysis/trace.ts

@@ -1,300 +0,0 @@
-export type TraceReason = 'no_references' | 'only_re_exported' | 'self_import' | 'has_references';
-
-export interface ReferenceLocation {
-  filePath: string;
-  line: number;
-  col: number;
-}
-
-export interface ReExportChain {
-  path: string;
-  exportName: string;
-}
-
-export interface ExportTrace {
-  file: string;
-  exportName: string;
-  isUsed: boolean;
-  directReferences: ReferenceLocation[];
-  reExportChains: ReExportChain[];
-  reason: TraceReason;
-}
-
-export interface FileTrace {
-  file: string;
-  exports: Array<{ name: string; isUsed: boolean; line: number }>;
-  importsFrom: string[];
-  importedBy: string[];
-  reExports: Array<{ name: string; fromFile: string }>;
-}
-
-export interface DependencyTrace {
-  packageName: string;
-  directImporters: string[];
-  transitiveImporters: string[];
-  isUsed: boolean;
-}
-
-export interface CloneInstance {
-  filePath: string;
-  startLine: number;
-  endLine: number;
-  similarity: number;
-}
-
-export interface CloneTrace {
-  sourceFile: string;
-  sourceLine: number;
-  matchingInstances: CloneInstance[];
-  groupId?: number;
-}
-
-export interface GraphNode {
-  id: string;
-  filePath?: string;
-  name: string;
-  isExported: boolean;
-  startLine?: number;
-}
-
-interface GraphEdge {
-  sourceId: string;
-  targetId: string;
-  relation: string;
-}
-
-interface Graph {
-  nodes: GraphNode[];
-  edges: GraphEdge[];
-}
-
-/** Build an O(1) id→node index. Pass to the trace functions when calling multiple times on the same graph. */
-export function buildNodeIndex(graph: Graph): Map<string, GraphNode> {
-  const index = new Map<string, GraphNode>();
-  for (const n of graph.nodes) index.set(n.id, n);
-  return index;
-}
-
-export function traceExport(
-  graph: Graph,
-  file: string,
-  exportName: string,
-  nodeIndex?: Map<string, GraphNode>,
-): ExportTrace {
-  // Build index once if not supplied — O(N) amortised when caller reuses it
-  const idx = nodeIndex ?? buildNodeIndex(graph);
-
-  // Find nodes in the target file matching exportName
-  const targetIds = new Set<string>();
-  for (const n of graph.nodes) {
-    if (n.filePath === file && n.name === exportName) targetIds.add(n.id);
-  }
-
-  // Find CALLS or IMPORTS edges pointing to these nodes from other files
-  const directReferences: ReferenceLocation[] = [];
-  const reExportChains: ReExportChain[] = [];
-
-  for (const edge of graph.edges) {
-    if (!targetIds.has(edge.targetId)) continue;
-
-    const sourceNode = idx.get(edge.sourceId);
-    if (!sourceNode) continue;
-
-    // Skip self-references (same file)
-    if (sourceNode.filePath === file) continue;
-
-    if (edge.relation === 'CALLS' || edge.relation === 'IMPORTS') {
-      directReferences.push({
-        filePath: sourceNode.filePath ?? sourceNode.id,
-        line: sourceNode.startLine ?? 0,
-        col: 0,
-      });
-    } else if (edge.relation === 'RE_EXPORTS') {
-      reExportChains.push({
-        path: sourceNode.filePath ?? sourceNode.id,
-        exportName: sourceNode.name,
-      });
-    }
-  }
-
-  // Determine reason
-  let reason: TraceReason;
-  let isUsed: boolean;
-
-  if (directReferences.length > 0) {
-    reason = 'has_references';
-    isUsed = true;
-  } else if (reExportChains.length > 0) {
-    reason = 'only_re_exported';
-    isUsed = false;
-  } else {
-    reason = 'no_references';
-    isUsed = false;
-  }
-
-  return {
-    file,
-    exportName,
-    isUsed,
-    directReferences,
-    reExportChains,
-    reason,
-  };
-}
-
-export function traceFile(
-  graph: Graph,
-  file: string,
-  nodeIndex?: Map<string, GraphNode>,
-): FileTrace {
-  // Build index once if not supplied
-  const idx = nodeIndex ?? buildNodeIndex(graph);
-
-  // Find all nodes in this file
-  const fileNodes = graph.nodes.filter((n) => n.filePath === file);
-  const fileNodeIds = new Set(fileNodes.map((n) => n.id));
-
-  // Pre-compute which target node ids have external references in one edge pass
-  // to avoid O(exported_nodes * edges) in the map below.
-  const externallyReferenced = new Set<string>();
-  const importsFromSet = new Set<string>();
-  const importedBySet = new Set<string>();
-  const reExports: Array<{ name: string; fromFile: string }> = [];
-
-  for (const edge of graph.edges) {
-    const srcInFile = fileNodeIds.has(edge.sourceId);
-    const tgtInFile = fileNodeIds.has(edge.targetId);
-
-    if (edge.relation === 'IMPORTS') {
-      if (srcInFile) {
-        const targetNode = idx.get(edge.targetId);
-        if (targetNode?.filePath && targetNode.filePath !== file) {
-          importsFromSet.add(targetNode.filePath);
-        }
-      }
-      if (tgtInFile) {
-        const sourceNode = idx.get(edge.sourceId);
-        if (sourceNode?.filePath && sourceNode.filePath !== file) {
-          importedBySet.add(sourceNode.filePath);
-        }
-      }
-      // External IMPORTS into a file node → that node is externally referenced
-      if (tgtInFile && !srcInFile) {
-        externallyReferenced.add(edge.targetId);
-      }
-    }
-
-    if (edge.relation === 'CALLS' && tgtInFile && !srcInFile) {
-      externallyReferenced.add(edge.targetId);
-    }
-
-    if (edge.relation === 'RE_EXPORTS' && srcInFile) {
-      const sourceNode = idx.get(edge.sourceId);
-      const targetNode = idx.get(edge.targetId);
-      if (sourceNode && targetNode?.filePath) {
-        reExports.push({ name: sourceNode.name, fromFile: targetNode.filePath });
-      }
-    }
-  }
-
-  // Build exports list using pre-computed set — O(exported_nodes) not O(exported_nodes * edges)
-  const exports = fileNodes
-    .filter((n) => n.isExported)
-    .map((n) => ({
-      name: n.name,
-      isUsed: externallyReferenced.has(n.id),
-      line: n.startLine ?? 0,
-    }));
-
-  return {
-    file,
-    exports,
-    importsFrom: Array.from(importsFromSet),
-    importedBy: Array.from(importedBySet),
-    reExports,
-  };
-}
-
-export function traceDependency(
-  importEdges: Array<{ sourceFile: string; targetPackage: string }>,
-  packageName: string,
-): DependencyTrace {
-  // Find direct importers
-  const directImporters = importEdges
-    .filter((e) => e.targetPackage === packageName)
-    .map((e) => e.sourceFile);
-
-  const directSet = new Set(directImporters);
-
-  // BFS to find transitive importers via reverse import graph
-  const reverseImportMap = new Map<string, Set<string>>();
-  for (const edge of importEdges) {
-    if (!reverseImportMap.has(edge.targetPackage)) {
-      reverseImportMap.set(edge.targetPackage, new Set());
-    }
-    reverseImportMap.get(edge.targetPackage)!.add(edge.sourceFile);
-  }
-
-  const transitiveSet = new Set<string>();
-  const queue = [...directImporters];
-  const visited = new Set(directImporters);
-
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    const upstream = reverseImportMap.get(current);
-    if (upstream) {
-      for (const file of upstream) {
-        if (!visited.has(file) && !directSet.has(file)) {
-          visited.add(file);
-          transitiveSet.add(file);
-          queue.push(file);
-        }
-      }
-    }
-  }
-
-  return {
-    packageName,
-    directImporters,
-    transitiveImporters: Array.from(transitiveSet),
-    isUsed: directImporters.length > 0 || transitiveSet.size > 0,
-  };
-}
-
-export function traceClone(
-  cloneGroups: Array<{ id: number; instances: CloneInstance[] }>,
-  file: string,
-  line: number,
-): CloneTrace {
-  // Find groups containing an instance at (file, line)
-  const matchingGroups = cloneGroups.filter((group) =>
-    group.instances.some(
-      (inst) =>
-        inst.filePath === file && inst.startLine <= line && inst.endLine >= line,
-    ),
-  );
-
-  if (matchingGroups.length === 0) {
-    return {
-      sourceFile: file,
-      sourceLine: line,
-      matchingInstances: [],
-      groupId: undefined,
-    };
-  }
-
-  // Use the first matching group
-  const group = matchingGroups[0];
-
-  // Return all OTHER instances (not the source one)
-  const matchingInstances = group.instances.filter(
-    (inst) => !(inst.filePath === file && inst.startLine <= line && inst.endLine >= line),
-  );
-
-  return {
-    sourceFile: file,
-    sourceLine: line,
-    matchingInstances,
-    groupId: group.id,
-  };
-}

package/src/analysis/worker-pool.ts

@@ -1,81 +0,0 @@
-import { Worker } from 'node:worker_threads';
-import { cpus } from 'node:os';
-
-const DEFAULT_STACK_SIZE_MB = 16;
-
-export interface WorkerPoolOptions {
-  threads?: number;
-  stackSizeMb?: number;
-}
-
-interface QueuedTask {
-  script: string;
-  input: unknown;
-  resolve: (value: unknown) => void;
-  reject: (reason: unknown) => void;
-}
-
-let _globalPool: WorkerPool | null = null;
-
-export class WorkerPool {
-  readonly threads: number;
-  readonly stackSizeMb: number;
-
-  private _active = 0;
-  private readonly _queue: QueuedTask[] = [];
-
-  constructor(opts: WorkerPoolOptions = {}) {
-    this.threads = opts.threads ?? cpus().length;
-    this.stackSizeMb = opts.stackSizeMb ?? DEFAULT_STACK_SIZE_MB;
-  }
-
-  run<T>(workerScript: string, input: unknown): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
-      this._queue.push({ script: workerScript, input, resolve: resolve as (v: unknown) => void, reject });
-      this._drain();
-    });
-  }
-
-  private _drain(): void {
-    while (this._active < this.threads && this._queue.length > 0) {
-      const task = this._queue.shift()!;
-      this._active++;
-      const worker = new Worker(task.script, {
-        workerData: task.input,
-        resourceLimits: { stackSizeMb: this.stackSizeMb },
-      });
-      let settled = false;
-      const settle = (fn: () => void) => {
-        if (settled) return;
-        settled = true;
-        fn();
-        this._active--;
-        this._drain();
-      };
-      worker.on('message', (v: unknown) => {
-        settle(() => task.resolve(v));
-      });
-      worker.on('error', (err: unknown) => {
-        settle(() => task.reject(err));
-      });
-      worker.on('exit', (code: number) => {
-        if (code !== 0) {
-          settle(() => task.reject(new Error(`Worker exited with code ${code}`)));
-        }
-      });
-    }
-  }
-}
-
-export function configureGlobalPool(threads?: number, stackSizeMb?: number): WorkerPool {
-  if (!_globalPool) _globalPool = new WorkerPool({ threads, stackSizeMb });
-  return _globalPool;
-}
-
-export function getGlobalPool(): WorkerPool {
-  return _globalPool ?? configureGlobalPool();
-}
-
-export function resetGlobalPool(): void {
-  _globalPool = null;
-}