@monoes/monograph 1.1.0 → 1.2.0

package/src/graph/cycles.ts

@@ -0,0 +1,163 @@
+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);
+  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, []);
+  }
+
+  for (const { source_id: src, target_id: tgt } of edgeRows) {
+    if (!nodeSet.has(src) || !nodeSet.has(tgt)) continue;
+    if (src === tgt) continue;
+    adj.get(src)!.push(tgt);
+    radj.get(tgt)!.push(src);
+  }
+
+  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);
+    }
+    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);
+    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);
+      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 Kosaraju's algorithm to find SCCs. Each SCC with size > 1 represents
+ * a cycle. Self-loops (node -> itself) are also detected separately.
+ *
+ * @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);
+
+  // 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);
+  }
+
+  // Kosaraju's algorithm — pass 1: DFS on original graph, build finish order
+  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);
+    }
+    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
+  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);
+      if (component.length > 1) {
+        sccs.push(component);
+      }
+    }
+  }
+
+  // Add self-loops as single-element cycles
+  for (const node of selfLoops) {
+    sccs.push([node]);
+  }
+
+  return sccs;
+}

package/src/graph/dead-code.ts

@@ -0,0 +1,45 @@
+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[] {
+  const nodeRows = db.prepare('SELECT id, is_exported FROM nodes').all() as {
+    id: string;
+    is_exported: number;
+  }[];
+
+  if (nodeRows.length === 0) return [];
+
+  // Count in-degrees
+  const inDegree = new Map<string, number>();
+  for (const { id } of nodeRows) {
+    inDegree.set(id, 0);
+  }
+
+  const edgeRows = db.prepare('SELECT target_id FROM edges WHERE source_id != target_id').all() as {
+    target_id: string;
+  }[];
+
+  for (const { target_id } of edgeRows) {
+    if (inDegree.has(target_id)) {
+      inDegree.set(target_id, (inDegree.get(target_id) ?? 0) + 1);
+    }
+  }
+
+  const dead: string[] = [];
+  for (const { id, is_exported } of nodeRows) {
+    if ((inDegree.get(id) ?? 0) === 0 && is_exported !== 1) {
+      dead.push(id);
+    }
+  }
+
+  return dead;
+}

package/src/graph/dependency-closure.ts

@@ -0,0 +1,109 @@
+import type { MonographDb } from '../storage/db.js';
+
+export interface DepClosureResult {
+  nodeId: string;
+  name: string;
+  filePath: string | null;
+  directDeps: string[];           // IDs of directly imported nodes
+  transitiveDeps: string[];       // IDs of all transitively imported nodes
+  depDepth: number;               // max dependency chain depth
+  unusedTransitiveDeps: string[]; // transitive deps that are never directly referenced by any file in the project
+}
+
+export interface DepClosureReport {
+  nodes: DepClosureResult[];
+  avgDepDepth: number;
+  maxDepDepth: number;
+  deepDependencyFiles: DepClosureResult[];   // files with depDepth > 5
+}
+
+export function computeDependencyClosure(db: MonographDb, maxNodes = 100): DepClosureReport {
+  // Get File nodes sorted by degree (most connected first)
+  const fileNodes = (db.prepare(`
+    SELECT n.id, n.name, n.file_path,
+      (SELECT COUNT(*) FROM edges e WHERE e.source_id = n.id OR e.target_id = n.id) AS degree
+    FROM nodes n
+    WHERE n.label = 'File'
+    ORDER BY degree DESC
+    LIMIT ?
+  `).all(maxNodes) as Array<{ id: string; name: string; file_path: string | null; degree: number }>);
+
+  // Build a set of all file_paths that have any IMPORTS edge pointing to them (are imported by someone)
+  const importedFilePaths = new Set<string>(
+    (db.prepare(`
+      SELECT DISTINCT n.file_path
+      FROM edges e
+      JOIN nodes n ON n.id = e.target_id
+      WHERE e.relation = 'IMPORTS' AND n.file_path IS NOT NULL
+    `).all() as Array<{ file_path: string }>).map(r => r.file_path)
+  );
+
+  const results: DepClosureResult[] = [];
+
+  for (const fileNode of fileNodes) {
+    // BFS forward (following IMPORTS edges from this node)
+    const directDeps: string[] = [];
+    const transitiveDeps: string[] = [];
+    const visited = new Set<string>([fileNode.id]);
+    let frontier = [fileNode.id];
+    let depth = 0;
+    let maxDepth = 0;
+
+    while (frontier.length > 0) {
+      depth++;
+      const next: string[] = [];
+      for (const id of frontier) {
+        const edges = db.prepare(
+          `SELECT target_id FROM edges WHERE source_id = ? AND relation = 'IMPORTS'`
+        ).all(id) as Array<{ target_id: string }>;
+
+        for (const e of edges) {
+          if (!visited.has(e.target_id)) {
+            visited.add(e.target_id);
+            next.push(e.target_id);
+            if (depth === 1) {
+              directDeps.push(e.target_id);
+            } else {
+              transitiveDeps.push(e.target_id);
+            }
+            maxDepth = depth;
+          }
+        }
+      }
+      frontier = next;
+    }
+
+    // unusedTransitiveDeps: transitive deps whose file_path is NOT in importedFilePaths
+    const unusedTransitiveDeps = transitiveDeps.filter(depId => {
+      const depNode = db.prepare('SELECT file_path FROM nodes WHERE id = ?').get(depId) as { file_path: string | null } | undefined;
+      if (!depNode?.file_path) return false;
+      return !importedFilePaths.has(depNode.file_path);
+    });
+
+    results.push({
+      nodeId: fileNode.id,
+      name: fileNode.name,
+      filePath: fileNode.file_path,
+      directDeps,
+      transitiveDeps,
+      depDepth: maxDepth,
+      unusedTransitiveDeps,
+    });
+  }
+
+  // Sort by depDepth descending
+  results.sort((a, b) => b.depDepth - a.depDepth);
+
+  const avgDepDepth = results.length > 0
+    ? results.reduce((sum, r) => sum + r.depDepth, 0) / results.length
+    : 0;
+  const maxDepDepth = results.length > 0 ? results[0].depDepth : 0;
+  const deepDependencyFiles = results.filter(r => r.depDepth > 5);
+
+  return {
+    nodes: results,
+    avgDepDepth: Math.round(avgDepDepth * 100) / 100,
+    maxDepDepth,
+    deepDependencyFiles,
+  };
+}

package/src/graph/dfs.ts

@@ -0,0 +1,40 @@
+export interface DfsNode {
+  id: string;
+  depth: number;
+}
+
+export interface DfsOptions {
+  maxDepth?: number;
+}
+
+export function dfsTraversal(
+  startId: string,
+  adjacency: Map<string, string[]>,
+  visitor: (node: DfsNode) => void,
+  options: DfsOptions = {},
+): void {
+  if (!adjacency.has(startId)) return;
+
+  const { maxDepth = Infinity } = options;
+  const visited = new Set<string>();
+  const stack: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+
+  while (stack.length > 0) {
+    const { id, depth } = stack.pop()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+
+    visitor({ id, depth });
+
+    if (depth < maxDepth) {
+      const neighbors = adjacency.get(id) ?? [];
+      // Push in reverse order so left-most neighbor is processed first (DFS left-to-right order)
+      for (let i = neighbors.length - 1; i >= 0; i--) {
+        const neighbor = neighbors[i]!;
+        if (!visited.has(neighbor)) {
+          stack.push({ id: neighbor, depth: depth + 1 });
+        }
+      }
+    }
+  }
+}

package/src/graph/diff.ts

@@ -12,23 +12,50 @@ export interface GraphDiff {
   newEdges: MonographEdge[];
   removedEdges: MonographEdge[];
   modifiedNodes: Array<{ before: MonographNode; after: MonographNode }>;
+  /** Human-readable summary, e.g. "3 new nodes, 5 new edges, 1 node removed". */
+  summary: string;
+}
+
+function buildDiffSummary(
+  newNodes: MonographNode[],
+  removedNodes: MonographNode[],
+  newEdges: MonographEdge[],
+  removedEdges: MonographEdge[],
+  modifiedNodes: Array<{ before: MonographNode; after: MonographNode }>,
+): string {
+  const parts: string[] = [];
+  if (newNodes.length > 0) parts.push(`${newNodes.length} new node${newNodes.length !== 1 ? 's' : ''}`);
+  if (newEdges.length > 0) parts.push(`${newEdges.length} new edge${newEdges.length !== 1 ? 's' : ''}`);
+  if (removedNodes.length > 0) parts.push(`${removedNodes.length} node${removedNodes.length !== 1 ? 's' : ''} removed`);
+  if (removedEdges.length > 0) parts.push(`${removedEdges.length} edge${removedEdges.length !== 1 ? 's' : ''} removed`);
+  if (modifiedNodes.length > 0) parts.push(`${modifiedNodes.length} node${modifiedNodes.length !== 1 ? 's' : ''} modified`);
+  return parts.length > 0 ? parts.join(', ') : 'no changes';
 }
 
 export function diffSnapshots(before: GraphSnapshot, after: GraphSnapshot): GraphDiff {
   const beforeNodeIds = new Map(before.nodes.map(n => [n.id, n]));
   const afterNodeIds = new Map(after.nodes.map(n => [n.id, n]));
-  const beforeEdgeIds = new Set(before.edges.map(e => e.id));
-  const afterEdgeIds = new Set(after.edges.map(e => e.id));
+  // Key edges by sourceId+relation+targetId — stable across snapshots regardless of synthetic id
+  const edgeKey = (e: MonographEdge) => `${e.sourceId}|${e.relation}|${e.targetId}`;
+  const beforeEdgeKeys = new Set(before.edges.map(edgeKey));
+  const afterEdgeKeys = new Set(after.edges.map(edgeKey));
+
+  const newNodes = after.nodes.filter(n => !beforeNodeIds.has(n.id));
+  const removedNodes = before.nodes.filter(n => !afterNodeIds.has(n.id));
+  const newEdges = after.edges.filter(e => !beforeEdgeKeys.has(edgeKey(e)));
+  const removedEdges = before.edges.filter(e => !afterEdgeKeys.has(edgeKey(e)));
+  const modifiedNodes = after.nodes
+    .filter(n => beforeNodeIds.has(n.id))
+    .filter(n => JSON.stringify(n) !== JSON.stringify(beforeNodeIds.get(n.id)))
+    .map(n => ({ before: beforeNodeIds.get(n.id)!, after: n }));
 
   return {
-    newNodes: after.nodes.filter(n => !beforeNodeIds.has(n.id)),
-    removedNodes: before.nodes.filter(n => !afterNodeIds.has(n.id)),
-    newEdges: after.edges.filter(e => !beforeEdgeIds.has(e.id)),
-    removedEdges: before.edges.filter(e => !afterEdgeIds.has(e.id)),
-    modifiedNodes: after.nodes
-      .filter(n => beforeNodeIds.has(n.id))
-      .filter(n => JSON.stringify(n) !== JSON.stringify(beforeNodeIds.get(n.id)))
-      .map(n => ({ before: beforeNodeIds.get(n.id)!, after: n })),
+    newNodes,
+    removedNodes,
+    newEdges,
+    removedEdges,
+    modifiedNodes,
+    summary: buildDiffSummary(newNodes, removedNodes, newEdges, removedEdges, modifiedNodes),
   };
 }
 

package/src/graph/duplication-stats.ts

@@ -0,0 +1,68 @@
+export interface DuplicationStats {
+  totalFiles: number;
+  filesWithClones: number;
+  totalLines: number;
+  duplicatedLines: number;
+  totalTokens: number;
+  duplicatedTokens: number;
+  cloneGroups: number;
+  cloneInstances: number;
+  duplicationPct: number;
+}
+
+export interface CloneGroupInput {
+  instances: Array<{
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    tokenCount?: number;
+  }>;
+}
+
+export function computeDuplicationStats(
+  groups: CloneGroupInput[],
+  allFilePaths: string[],
+  totalLines: number,
+  totalTokens: number,
+): DuplicationStats {
+  // Per-file deduplicated line sets to avoid double-counting
+  const fileLines = new Map<string, Set<number>>();
+  let cloneInstances = 0;
+
+  for (const group of groups) {
+    for (const inst of group.instances) {
+      cloneInstances++;
+      if (!fileLines.has(inst.filePath)) fileLines.set(inst.filePath, new Set());
+      const set = fileLines.get(inst.filePath)!;
+      for (let l = inst.startLine; l <= inst.endLine; l++) set.add(l);
+    }
+  }
+
+  const filesWithClones = fileLines.size;
+  const duplicatedLines = [...fileLines.values()].reduce((s, set) => s + set.size, 0);
+  const duplicatedTokens = Math.min(
+    totalTokens,
+    groups.reduce((s, g) => s + g.instances.reduce((t, i) => t + (i.tokenCount ?? 0), 0), 0),
+  );
+
+  return {
+    totalFiles: allFilePaths.length,
+    filesWithClones,
+    totalLines,
+    duplicatedLines,
+    totalTokens,
+    duplicatedTokens,
+    cloneGroups: groups.length,
+    cloneInstances,
+    duplicationPct: totalLines > 0 ? (duplicatedLines / totalLines) * 100 : 0,
+  };
+}
+
+export function formatDuplicationStats(stats: DuplicationStats): string {
+  return [
+    `Clone groups:      ${stats.cloneGroups}`,
+    `Clone instances:   ${stats.cloneInstances}`,
+    `Files with clones: ${stats.filesWithClones} / ${stats.totalFiles}`,
+    `Duplicated lines:  ${stats.duplicatedLines} / ${stats.totalLines} (${stats.duplicationPct.toFixed(1)}%)`,
+  ].join('\n');
+}

package/src/graph/edge-filter.ts

@@ -0,0 +1,103 @@
+import type { MonographEdge, EdgeRelation, EdgeConfidence } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+
+// ── Filter options ─────────────────────────────────────────────────────────────
+
+export interface EdgeFilterOptions {
+  /** Only return edges whose relation matches one of these values. */
+  relations?: EdgeRelation[];
+  /** Only return edges whose confidence label matches one of these values. */
+  confidences?: EdgeConfidence[];
+  /** Only return edges with a confidence_score >= this value (0–1). */
+  minConfidenceScore?: number;
+  /** Only return edges with a confidence_score <= this value (0–1). */
+  maxConfidenceScore?: number;
+}
+
+// ── DB-backed filter ───────────────────────────────────────────────────────────
+
+/**
+ * Query edges from a MonographDb with optional relation / confidence filters.
+ * All filters are combined with AND.
+ */
+export function filterEdges(
+  db: MonographDb,
+  options: EdgeFilterOptions = {},
+): MonographEdge[] {
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (options.relations && options.relations.length > 0) {
+    const ph = options.relations.map(() => '?').join(',');
+    conditions.push(`relation IN (${ph})`);
+    params.push(...options.relations);
+  }
+
+  if (options.confidences && options.confidences.length > 0) {
+    const ph = options.confidences.map(() => '?').join(',');
+    conditions.push(`confidence IN (${ph})`);
+    params.push(...options.confidences);
+  }
+
+  if (options.minConfidenceScore !== undefined) {
+    conditions.push('confidence_score >= ?');
+    params.push(options.minConfidenceScore);
+  }
+
+  if (options.maxConfidenceScore !== undefined) {
+    conditions.push('confidence_score <= ?');
+    params.push(options.maxConfidenceScore);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+  const sql = `SELECT id, source_id, target_id, relation, confidence, confidence_score, reason, evidence
+               FROM edges ${where}`;
+
+  const rows = db.prepare(sql).all(...params) as {
+    id: string;
+    source_id: string;
+    target_id: string;
+    relation: string;
+    confidence: string;
+    confidence_score: number;
+    reason: string | null;
+    evidence: string | null;
+  }[];
+
+  return rows.map(r => ({
+    id: r.id,
+    sourceId: r.source_id,
+    targetId: r.target_id,
+    relation: r.relation as EdgeRelation,
+    confidence: r.confidence as EdgeConfidence,
+    confidenceScore: r.confidence_score,
+    reason: r.reason ?? undefined,
+  }));
+}
+
+// ── In-memory filter ───────────────────────────────────────────────────────────
+
+/**
+ * Filter an already-loaded array of edges in memory.
+ * Useful when the caller already has edges and does not need a DB round-trip.
+ */
+export function filterEdgesInMemory(
+  edges: MonographEdge[],
+  options: EdgeFilterOptions = {},
+): MonographEdge[] {
+  return edges.filter(e => {
+    if (options.relations && options.relations.length > 0) {
+      if (!options.relations.includes(e.relation)) return false;
+    }
+    if (options.confidences && options.confidences.length > 0) {
+      if (!options.confidences.includes(e.confidence)) return false;
+    }
+    if (options.minConfidenceScore !== undefined && e.confidenceScore < options.minConfidenceScore) {
+      return false;
+    }
+    if (options.maxConfidenceScore !== undefined && e.confidenceScore > options.maxConfidenceScore) {
+      return false;
+    }
+    return true;
+  });
+}