@optave/codegraph 3.1.3 → 3.1.4

package/src/commands/check.js

@@ -1,19 +1,19 @@
 import { checkData } from '../check.js';
+import { AnalysisError } from '../errors.js';
 import { outputResult } from '../infrastructure/result-formatter.js';
 
 /**
- * CLI formatter — prints check results and exits with code 1 on failure.
+ * CLI formatter — prints check results and sets exitCode 1 on failure.
  */
 export function check(customDbPath, opts = {}) {
   const data = checkData(customDbPath, opts);
 
   if (data.error) {
-    console.error(data.error);
-    process.exit(1);
+    throw new AnalysisError(data.error);
   }
 
   if (outputResult(data, null, opts)) {
-    if (!data.passed) process.exit(1);
+    if (!data.passed) process.exitCode = 1;
     return;
   }
 
@@ -77,6 +77,6 @@ export function check(customDbPath, opts = {}) {
   console.log(`\n  ${s.total} predicates | ${s.passed} passed | ${s.failed} failed\n`);
 
   if (!data.passed) {
-    process.exit(1);
+    process.exitCode = 1;
   }
 }

package/src/commands/manifesto.js

@@ -2,13 +2,13 @@ import { outputResult } from '../infrastructure/result-formatter.js';
 import { manifestoData } from '../manifesto.js';
 
 /**
- * CLI formatter — prints manifesto results and exits with code 1 on failure.
+ * CLI formatter — prints manifesto results and sets exitCode 1 on failure.
  */
 export function manifesto(customDbPath, opts = {}) {
   const data = manifestoData(customDbPath, opts);
 
   if (outputResult(data, 'violations', opts)) {
-    if (!data.passed) process.exit(1);
+    if (!data.passed) process.exitCode = 1;
     return;
   }
 
@@ -72,6 +72,6 @@ export function manifesto(customDbPath, opts = {}) {
   console.log();
 
   if (!data.passed) {
-    process.exit(1);
+    process.exitCode = 1;
   }
 }

package/src/commands/structure.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { hotspotsData, moduleBoundariesData, structureData } from '../structure.js';
 
-export { structureData, hotspotsData, moduleBoundariesData };
+export { hotspotsData, moduleBoundariesData, structureData };
 
 export function formatStructure(data) {
   if (data.count === 0) return 'No directory structure found. Run "codegraph build" first.';

package/src/communities.js

@@ -1,79 +1,9 @@
 import path from 'node:path';
-import Graph from 'graphology';
-import louvain from 'graphology-communities-louvain';
-import {
-  getCallableNodes,
-  getCallEdges,
-  getFileNodesAll,
-  getImportEdges,
-  openReadonlyOrFail,
-} from './db.js';
-import { isTestFile } from './infrastructure/test-filter.js';
+import { openReadonlyOrFail } from './db.js';
+import { louvainCommunities } from './graph/algorithms/louvain.js';
+import { buildDependencyGraph } from './graph/builders/dependency.js';
 import { paginateResult } from './paginate.js';
 
-// ─── Graph Construction ───────────────────────────────────────────────
-
-/**
- * Build a graphology graph from the codegraph SQLite database.
- *
- * @param {object} db - open better-sqlite3 database (readonly)
- * @param {object} opts
- * @param {boolean} [opts.functions] - Function-level instead of file-level
- * @param {boolean} [opts.noTests] - Exclude test files
- * @returns {Graph}
- */
-function buildGraphologyGraph(db, opts = {}) {
-  const graph = new Graph({ type: 'undirected' });
-
-  if (opts.functions) {
-    // Function-level: nodes = function/method/class symbols, edges = calls
-    let nodes = getCallableNodes(db);
-    if (opts.noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
-
-    const nodeIds = new Set();
-    for (const n of nodes) {
-      const key = String(n.id);
-      graph.addNode(key, { label: n.name, file: n.file, kind: n.kind });
-      nodeIds.add(n.id);
-    }
-
-    const edges = getCallEdges(db);
-    for (const e of edges) {
-      if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
-      const src = String(e.source_id);
-      const tgt = String(e.target_id);
-      if (src === tgt) continue;
-      if (!graph.hasEdge(src, tgt)) {
-        graph.addEdge(src, tgt);
-      }
-    }
-  } else {
-    // File-level: nodes = files, edges = imports + imports-type (deduplicated, cross-file)
-    let nodes = getFileNodesAll(db);
-    if (opts.noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
-
-    const nodeIds = new Set();
-    for (const n of nodes) {
-      const key = String(n.id);
-      graph.addNode(key, { label: n.file, file: n.file });
-      nodeIds.add(n.id);
-    }
-
-    const edges = getImportEdges(db);
-    for (const e of edges) {
-      if (!nodeIds.has(e.source_id) || !nodeIds.has(e.target_id)) continue;
-      const src = String(e.source_id);
-      const tgt = String(e.target_id);
-      if (src === tgt) continue;
-      if (!graph.hasEdge(src, tgt)) {
-        graph.addEdge(src, tgt);
-      }
-    }
-  }
-
-  return graph;
-}
-
 // ─── Directory Helpers ────────────────────────────────────────────────
 
 function getDirectory(filePath) {
@@ -97,11 +27,10 @@ function getDirectory(filePath) {
  */
 export function communitiesData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
-  const resolution = opts.resolution ?? 1.0;
   let graph;
   try {
-    graph = buildGraphologyGraph(db, {
-      functions: opts.functions,
+    graph = buildDependencyGraph(db, {
+      fileLevel: !opts.functions,
       noTests: opts.noTests,
     });
   } finally {
@@ -109,27 +38,27 @@ export function communitiesData(customDbPath, opts = {}) {
   }
 
   // Handle empty or trivial graphs
-  if (graph.order === 0 || graph.size === 0) {
+  if (graph.nodeCount === 0 || graph.edgeCount === 0) {
     return {
       communities: [],
       modularity: 0,
       drift: { splitCandidates: [], mergeCandidates: [] },
-      summary: { communityCount: 0, modularity: 0, nodeCount: graph.order, driftScore: 0 },
+      summary: { communityCount: 0, modularity: 0, nodeCount: graph.nodeCount, driftScore: 0 },
     };
   }
 
   // Run Louvain
-  const details = louvain.detailed(graph, { resolution });
-  const assignments = details.communities; // node → community id
-  const modularity = details.modularity;
+  const resolution = opts.resolution ?? 1.0;
+  const { assignments, modularity } = louvainCommunities(graph, { resolution });
 
   // Group nodes by community
   const communityMap = new Map(); // community id → node keys[]
-  graph.forEachNode((key) => {
-    const cid = assignments[key];
+  for (const [key] of graph.nodes()) {
+    const cid = assignments.get(key);
+    if (cid == null) continue;
     if (!communityMap.has(cid)) communityMap.set(cid, []);
     communityMap.get(cid).push(key);
-  });
+  }
 
   // Build community objects
   const communities = [];
@@ -139,7 +68,7 @@ export function communitiesData(customDbPath, opts = {}) {
     const dirCounts = {};
     const memberData = [];
     for (const key of members) {
-      const attrs = graph.getNodeAttributes(key);
+      const attrs = graph.getNodeAttrs(key);
       const dir = getDirectory(attrs.file);
       dirCounts[dir] = (dirCounts[dir] || 0) + 1;
       memberData.push({
@@ -196,7 +125,6 @@ export function communitiesData(customDbPath, opts = {}) {
   mergeCandidates.sort((a, b) => b.directoryCount - a.directoryCount);
 
   // Drift score: 0-100 based on how much directory structure diverges from communities
-  // Higher = more drift (directories don't match communities)
   const totalDirs = dirToCommunities.size;
   const splitDirs = splitCandidates.length;
   const splitRatio = totalDirs > 0 ? splitDirs / totalDirs : 0;
@@ -214,7 +142,7 @@ export function communitiesData(customDbPath, opts = {}) {
     summary: {
       communityCount: communities.length,
       modularity: +modularity.toFixed(4),
-      nodeCount: graph.order,
+      nodeCount: graph.nodeCount,
       driftScore,
     },
   };

package/src/cycles.js

@@ -1,4 +1,6 @@
-import { isTestFile } from './infrastructure/test-filter.js';
+import { tarjan } from './graph/algorithms/tarjan.js';
+import { buildDependencyGraph } from './graph/builders/dependency.js';
+import { CodeGraph } from './graph/model.js';
 import { loadNative } from './native.js';
 
 /**
@@ -12,107 +14,50 @@ export function findCycles(db, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
 
-  // Build adjacency list from SQLite (stays in JS — only the algorithm can move to Rust)
-  let edges;
-  if (fileLevel) {
-    edges = db
-      .prepare(`
-      SELECT DISTINCT n1.file AS source, n2.file AS target
-      FROM edges e
-      JOIN nodes n1 ON e.source_id = n1.id
-      JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type')
-    `)
-      .all();
-    if (noTests) {
-      edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
-    }
-  } else {
-    edges = db
-      .prepare(`
-      SELECT DISTINCT
-        (n1.name || '|' || n1.file) AS source,
-        (n2.name || '|' || n2.file) AS target
-      FROM edges e
-      JOIN nodes n1 ON e.source_id = n1.id
-      JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
-        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
-        AND e.kind = 'calls'
-        AND n1.id != n2.id
-    `)
-      .all();
-    if (noTests) {
-      edges = edges.filter((e) => {
-        const sourceFile = e.source.split('|').pop();
-        const targetFile = e.target.split('|').pop();
-        return !isTestFile(sourceFile) && !isTestFile(targetFile);
-      });
+  const graph = buildDependencyGraph(db, { fileLevel, noTests });
+
+  // Build a label map: DB string ID → human-readable key
+  // File-level: file path; Function-level: name|file composite (for native Rust compat)
+  const idToLabel = new Map();
+  for (const [id, attrs] of graph.nodes()) {
+    if (fileLevel) {
+      idToLabel.set(id, attrs.file);
+    } else {
+      idToLabel.set(id, `${attrs.label}|${attrs.file}`);
     }
   }
 
+  // Build edge array with human-readable keys (for native engine)
+  const edges = graph.toEdgeArray().map((e) => ({
+    source: idToLabel.get(e.source),
+    target: idToLabel.get(e.target),
+  }));
+
   // Try native Rust implementation
   const native = loadNative();
   if (native) {
     return native.detectCycles(edges);
   }
 
-  // Fallback: JS Tarjan
-  return findCyclesJS(edges);
+  // Fallback: JS Tarjan via graph subsystem
+  // Re-key graph with human-readable labels for consistent output
+  const labelGraph = new CodeGraph();
+  for (const { source, target } of edges) {
+    labelGraph.addEdge(source, target);
+  }
+  return tarjan(labelGraph);
 }
 
 /**
  * Pure-JS Tarjan's SCC implementation.
+ * Kept for backward compatibility — accepts raw {source, target}[] edges.
  */
 export function findCyclesJS(edges) {
-  const graph = new Map();
+  const graph = new CodeGraph();
   for (const { source, target } of edges) {
-    if (!graph.has(source)) graph.set(source, []);
-    graph.get(source).push(target);
-    if (!graph.has(target)) graph.set(target, []);
+    graph.addEdge(source, target);
   }
-
-  // Tarjan's strongly connected components algorithm
-  let index = 0;
-  const stack = [];
-  const onStack = new Set();
-  const indices = new Map();
-  const lowlinks = new Map();
-  const sccs = [];
-
-  function strongconnect(v) {
-    indices.set(v, index);
-    lowlinks.set(v, index);
-    index++;
-    stack.push(v);
-    onStack.add(v);
-
-    for (const w of graph.get(v) || []) {
-      if (!indices.has(w)) {
-        strongconnect(w);
-        lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
-      } else if (onStack.has(w)) {
-        lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
-      }
-    }
-
-    if (lowlinks.get(v) === indices.get(v)) {
-      const scc = [];
-      let w;
-      do {
-        w = stack.pop();
-        onStack.delete(w);
-        scc.push(w);
-      } while (w !== v);
-      if (scc.length > 1) sccs.push(scc);
-    }
-  }
-
-  for (const node of graph.keys()) {
-    if (!indices.has(node)) strongconnect(node);
-  }
-
-  return sccs;
+  return tarjan(graph);
 }
 
 /**

package/src/dataflow.js

@@ -26,8 +26,7 @@ import { paginateResult } from './paginate.js';
 import { ALL_SYMBOL_KINDS, normalizeSymbol } from './queries.js';
 
 // Re-export for backward compatibility
-export { DATAFLOW_RULES };
-export { _makeDataflowRules as makeDataflowRules };
+export { _makeDataflowRules as makeDataflowRules, DATAFLOW_RULES };
 
 export const DATAFLOW_EXTENSIONS = buildExtensionSet(DATAFLOW_RULES);
 

package/src/db/connection.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
+import { DbError } from '../errors.js';
 import { warn } from '../logger.js';
 
 function isProcessAlive(pid) {
@@ -78,11 +79,10 @@ export function findDbPath(customPath) {
 export function openReadonlyOrFail(customPath) {
   const dbPath = findDbPath(customPath);
   if (!fs.existsSync(dbPath)) {
-    console.error(
-      `No codegraph database found at ${dbPath}.\n` +
-        `Run "codegraph build" first to analyze your codebase.`,
+    throw new DbError(
+      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
+      { file: dbPath },
     );
-    process.exit(1);
   }
   return new Database(dbPath, { readonly: true });
 }

package/src/db/migrations.js

@@ -229,6 +229,17 @@ export const MIGRATIONS = [
       CREATE INDEX IF NOT EXISTS idx_nodes_exported ON nodes(exported);
     `,
   },
+  {
+    version: 15,
+    up: `
+      ALTER TABLE nodes ADD COLUMN qualified_name TEXT;
+      ALTER TABLE nodes ADD COLUMN scope TEXT;
+      ALTER TABLE nodes ADD COLUMN visibility TEXT;
+      UPDATE nodes SET qualified_name = name WHERE qualified_name IS NULL;
+      CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name);
+      CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope);
+    `,
+  },
 ];
 
 export function getBuildMeta(db, key) {
@@ -309,4 +320,34 @@ export function initSchema(db) {
   } catch {
     /* already exists */
   }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN qualified_name TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN scope TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN visibility TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('UPDATE nodes SET qualified_name = name WHERE qualified_name IS NULL');
+  } catch {
+    /* nodes table may not exist yet */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name)');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope)');
+  } catch {
+    /* already exists */
+  }
 }

package/src/db/query-builder.js

@@ -1,3 +1,4 @@
+import { DbError } from '../errors.js';
 import { EVERY_EDGE_KIND } from '../kinds.js';
 
 // ─── Validation Helpers ─────────────────────────────────────────────
@@ -12,13 +13,13 @@ const SAFE_SELECT_TOKEN_RE =
 
 function validateAlias(alias) {
   if (!SAFE_ALIAS_RE.test(alias)) {
-    throw new Error(`Invalid SQL alias: ${alias}`);
+    throw new DbError(`Invalid SQL alias: ${alias}`);
   }
 }
 
 function validateColumn(column) {
   if (!SAFE_COLUMN_RE.test(column)) {
-    throw new Error(`Invalid SQL column: ${column}`);
+    throw new DbError(`Invalid SQL column: ${column}`);
   }
 }
 
@@ -26,7 +27,7 @@ function validateOrderBy(clause) {
   const terms = clause.split(',').map((t) => t.trim());
   for (const term of terms) {
     if (!SAFE_ORDER_TERM_RE.test(term)) {
-      throw new Error(`Invalid ORDER BY term: ${term}`);
+      throw new DbError(`Invalid ORDER BY term: ${term}`);
     }
   }
 }
@@ -51,14 +52,14 @@ function validateSelectCols(cols) {
   const tokens = splitTopLevelCommas(cols);
   for (const token of tokens) {
     if (!SAFE_SELECT_TOKEN_RE.test(token)) {
-      throw new Error(`Invalid SELECT expression: ${token}`);
+      throw new DbError(`Invalid SELECT expression: ${token}`);
     }
   }
 }
 
 function validateEdgeKind(edgeKind) {
   if (!EVERY_EDGE_KIND.includes(edgeKind)) {
-    throw new Error(
+    throw new DbError(
       `Invalid edge kind: ${edgeKind} (expected one of ${EVERY_EDGE_KIND.join(', ')})`,
     );
   }