@optave/codegraph 3.1.3 → 3.1.5

package/src/features/graph-enrichment.js

@@ -0,0 +1,327 @@
+import path from 'node:path';
+import { louvainCommunities } from '../graph/algorithms/louvain.js';
+import { CodeGraph } from '../graph/model.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import {
+  COMMUNITY_COLORS,
+  DEFAULT_NODE_COLORS,
+  DEFAULT_ROLE_COLORS,
+} from '../presentation/colors.js';
+import { DEFAULT_CONFIG, renderPlotHTML } from '../presentation/viewer.js';
+
+// Re-export presentation utilities for backward compatibility
+export { loadPlotConfig } from '../presentation/viewer.js';
+
+const DEFAULT_MIN_CONFIDENCE = 0.5;
+
+// ─── Data Preparation ─────────────────────────────────────────────────
+
+/**
+ * Prepare enriched graph data for the HTML viewer.
+ */
+export function prepareGraphData(db, opts = {}) {
+  const fileLevel = opts.fileLevel !== false;
+  const noTests = opts.noTests || false;
+  const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+  const cfg = opts.config || DEFAULT_CONFIG;
+
+  return fileLevel
+    ? prepareFileLevelData(db, noTests, minConf, cfg)
+    : prepareFunctionLevelData(db, noTests, minConf, cfg);
+}
+
+function prepareFunctionLevelData(db, noTests, minConf, cfg) {
+  let edges = db
+    .prepare(
+      `
+      SELECT n1.id AS source_id, n1.name AS source_name, n1.kind AS source_kind,
+             n1.file AS source_file, n1.line AS source_line, n1.role AS source_role,
+             n2.id AS target_id, n2.name AS target_name, n2.kind AS target_kind,
+             n2.file AS target_file, n2.line AS target_line, n2.role AS target_role,
+             e.kind AS edge_kind
+      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 e.confidence >= ?
+    `,
+    )
+    .all(minConf);
+  if (noTests)
+    edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
+
+  if (cfg.filter.kinds) {
+    const kinds = new Set(cfg.filter.kinds);
+    edges = edges.filter((e) => kinds.has(e.source_kind) && kinds.has(e.target_kind));
+  }
+  if (cfg.filter.files) {
+    const patterns = cfg.filter.files;
+    edges = edges.filter(
+      (e) =>
+        patterns.some((p) => e.source_file.includes(p)) &&
+        patterns.some((p) => e.target_file.includes(p)),
+    );
+  }
+
+  const nodeMap = new Map();
+  for (const e of edges) {
+    if (!nodeMap.has(e.source_id)) {
+      nodeMap.set(e.source_id, {
+        id: e.source_id,
+        name: e.source_name,
+        kind: e.source_kind,
+        file: e.source_file,
+        line: e.source_line,
+        role: e.source_role,
+      });
+    }
+    if (!nodeMap.has(e.target_id)) {
+      nodeMap.set(e.target_id, {
+        id: e.target_id,
+        name: e.target_name,
+        kind: e.target_kind,
+        file: e.target_file,
+        line: e.target_line,
+        role: e.target_role,
+      });
+    }
+  }
+
+  if (cfg.filter.roles) {
+    const roles = new Set(cfg.filter.roles);
+    for (const [id, n] of nodeMap) {
+      if (!roles.has(n.role)) nodeMap.delete(id);
+    }
+    const nodeIds = new Set(nodeMap.keys());
+    edges = edges.filter((e) => nodeIds.has(e.source_id) && nodeIds.has(e.target_id));
+  }
+
+  // Complexity data
+  const complexityMap = new Map();
+  try {
+    const rows = db
+      .prepare(
+        'SELECT node_id, cognitive, cyclomatic, max_nesting, maintainability_index FROM function_complexity',
+      )
+      .all();
+    for (const r of rows) {
+      complexityMap.set(r.node_id, {
+        cognitive: r.cognitive,
+        cyclomatic: r.cyclomatic,
+        maintainabilityIndex: r.maintainability_index,
+      });
+    }
+  } catch {
+    // table may not exist in old DBs
+  }
+
+  // Fan-in / fan-out via graph subsystem
+  const fnGraph = new CodeGraph();
+  for (const [id] of nodeMap) fnGraph.addNode(String(id));
+  for (const e of edges) {
+    const src = String(e.source_id);
+    const tgt = String(e.target_id);
+    if (src !== tgt && !fnGraph.hasEdge(src, tgt)) fnGraph.addEdge(src, tgt);
+  }
+
+  // Use DB-level fan-in/fan-out (counts ALL call edges, not just visible)
+  const fanInMap = new Map();
+  const fanOutMap = new Map();
+  const fanInRows = db
+    .prepare(
+      "SELECT target_id AS node_id, COUNT(*) AS fan_in FROM edges WHERE kind = 'calls' GROUP BY target_id",
+    )
+    .all();
+  for (const r of fanInRows) fanInMap.set(r.node_id, r.fan_in);
+
+  const fanOutRows = db
+    .prepare(
+      "SELECT source_id AS node_id, COUNT(*) AS fan_out FROM edges WHERE kind = 'calls' GROUP BY source_id",
+    )
+    .all();
+  for (const r of fanOutRows) fanOutMap.set(r.node_id, r.fan_out);
+
+  // Communities (Louvain) via graph subsystem
+  const communityMap = new Map();
+  if (nodeMap.size > 0) {
+    try {
+      const { assignments } = louvainCommunities(fnGraph);
+      for (const [nid, cid] of assignments) communityMap.set(Number(nid), cid);
+    } catch {
+      // louvain can fail on disconnected graphs
+    }
+  }
+
+  // Build enriched nodes
+  const visNodes = [...nodeMap.values()].map((n) => {
+    const cx = complexityMap.get(n.id) || null;
+    const fanIn = fanInMap.get(n.id) || 0;
+    const fanOut = fanOutMap.get(n.id) || 0;
+    const community = communityMap.get(n.id) ?? null;
+    const directory = path.dirname(n.file);
+    const risk = [];
+    if (n.role === 'dead') risk.push('dead-code');
+    if (fanIn >= (cfg.riskThresholds?.highBlastRadius ?? 10)) risk.push('high-blast-radius');
+    if (cx && cx.maintainabilityIndex < (cfg.riskThresholds?.lowMI ?? 40)) risk.push('low-mi');
+
+    const color =
+      cfg.colorBy === 'role' && n.role
+        ? cfg.roleColors[n.role] || DEFAULT_ROLE_COLORS[n.role] || '#ccc'
+        : cfg.colorBy === 'community' && community !== null
+          ? COMMUNITY_COLORS[community % COMMUNITY_COLORS.length]
+          : cfg.nodeColors[n.kind] || DEFAULT_NODE_COLORS[n.kind] || '#ccc';
+
+    return {
+      id: n.id,
+      label: n.name,
+      title: `${n.file}:${n.line} (${n.kind}${n.role ? `, ${n.role}` : ''})`,
+      color,
+      kind: n.kind,
+      role: n.role || '',
+      file: n.file,
+      line: n.line,
+      community,
+      cognitive: cx?.cognitive ?? null,
+      cyclomatic: cx?.cyclomatic ?? null,
+      maintainabilityIndex: cx?.maintainabilityIndex ?? null,
+      fanIn,
+      fanOut,
+      directory,
+      risk,
+    };
+  });
+
+  const visEdges = edges.map((e, i) => ({
+    id: `e${i}`,
+    from: e.source_id,
+    to: e.target_id,
+  }));
+
+  // Seed strategy
+  let seedNodeIds;
+  if (cfg.seedStrategy === 'top-fanin') {
+    const sorted = [...visNodes].sort((a, b) => b.fanIn - a.fanIn);
+    seedNodeIds = sorted.slice(0, cfg.seedCount || 30).map((n) => n.id);
+  } else if (cfg.seedStrategy === 'entry') {
+    seedNodeIds = visNodes.filter((n) => n.role === 'entry').map((n) => n.id);
+  } else {
+    seedNodeIds = visNodes.map((n) => n.id);
+  }
+
+  return { nodes: visNodes, edges: visEdges, seedNodeIds };
+}
+
+function prepareFileLevelData(db, noTests, minConf, cfg) {
+  let 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', 'calls')
+        AND e.confidence >= ?
+    `,
+    )
+    .all(minConf);
+  if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
+
+  const files = new Set();
+  for (const { source, target } of edges) {
+    files.add(source);
+    files.add(target);
+  }
+
+  const fileIds = new Map();
+  let idx = 0;
+  for (const f of files) fileIds.set(f, idx++);
+
+  // Fan-in/fan-out
+  const fanInCount = new Map();
+  const fanOutCount = new Map();
+  for (const { source, target } of edges) {
+    fanOutCount.set(source, (fanOutCount.get(source) || 0) + 1);
+    fanInCount.set(target, (fanInCount.get(target) || 0) + 1);
+  }
+
+  // Communities via graph subsystem
+  const communityMap = new Map();
+  if (files.size > 0) {
+    try {
+      const fileGraph = new CodeGraph();
+      for (const f of files) fileGraph.addNode(f);
+      for (const { source, target } of edges) {
+        if (source !== target && !fileGraph.hasEdge(source, target))
+          fileGraph.addEdge(source, target);
+      }
+      const { assignments } = louvainCommunities(fileGraph);
+      for (const [file, cid] of assignments) communityMap.set(file, cid);
+    } catch {
+      // ignore
+    }
+  }
+
+  const visNodes = [...files].map((f) => {
+    const id = fileIds.get(f);
+    const community = communityMap.get(f) ?? null;
+    const fanIn = fanInCount.get(f) || 0;
+    const fanOut = fanOutCount.get(f) || 0;
+    const directory = path.dirname(f);
+    const color =
+      cfg.colorBy === 'community' && community !== null
+        ? COMMUNITY_COLORS[community % COMMUNITY_COLORS.length]
+        : cfg.nodeColors.file || DEFAULT_NODE_COLORS.file;
+
+    return {
+      id,
+      label: path.basename(f),
+      title: f,
+      color,
+      kind: 'file',
+      role: '',
+      file: f,
+      line: 0,
+      community,
+      cognitive: null,
+      cyclomatic: null,
+      maintainabilityIndex: null,
+      fanIn,
+      fanOut,
+      directory,
+      risk: [],
+    };
+  });
+
+  const visEdges = edges.map(({ source, target }, i) => ({
+    id: `e${i}`,
+    from: fileIds.get(source),
+    to: fileIds.get(target),
+  }));
+
+  let seedNodeIds;
+  if (cfg.seedStrategy === 'top-fanin') {
+    const sorted = [...visNodes].sort((a, b) => b.fanIn - a.fanIn);
+    seedNodeIds = sorted.slice(0, cfg.seedCount || 30).map((n) => n.id);
+  } else if (cfg.seedStrategy === 'entry') {
+    seedNodeIds = visNodes.map((n) => n.id);
+  } else {
+    seedNodeIds = visNodes.map((n) => n.id);
+  }
+
+  return { nodes: visNodes, edges: visEdges, seedNodeIds };
+}
+
+// ─── HTML Generation (thin wrapper) ──────────────────────────────────
+
+/**
+ * Generate a self-contained interactive HTML file with vis-network.
+ *
+ * Loads graph data from the DB, then delegates to the presentation layer.
+ */
+export function generatePlotHTML(db, opts = {}) {
+  const cfg = opts.config || DEFAULT_CONFIG;
+  const data = prepareGraphData(db, opts);
+  return renderPlotHTML(data, cfg);
+}

package/src/{manifesto.js → features/manifesto.js}

@@ -1,9 +1,9 @@
+import { openReadonlyOrFail } from '../db/index.js';
+import { findCycles } from '../domain/graph/cycles.js';
+import { loadConfig } from '../infrastructure/config.js';
+import { debug } from '../infrastructure/logger.js';
+import { paginateResult } from '../shared/paginate.js';
 import { evaluateBoundaries } from './boundaries.js';
-import { loadConfig } from './config.js';
-import { findCycles } from './cycles.js';
-import { openReadonlyOrFail } from './db.js';
-import { debug } from './logger.js';
-import { paginateResult } from './paginate.js';
 
 // ─── Rule Definitions ─────────────────────────────────────────────────
 
@@ -395,7 +395,7 @@ export function manifestoData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
 
   try {
-    const config = loadConfig(process.cwd());
+    const config = opts.config || loadConfig(process.cwd());
     const rules = resolveRules(config.manifesto?.rules);
 
     const violations = [];

package/src/{owners.js → features/owners.js}

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { findDbPath, openReadonlyOrFail } from './db.js';
-import { isTestFile } from './infrastructure/test-filter.js';
+import { findDbPath, openReadonlyOrFail } from '../db/index.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
 
 // ─── CODEOWNERS Parsing ──────────────────────────────────────────────
 

package/src/{sequence.js → features/sequence.js}

@@ -6,10 +6,11 @@
  * sequence-diagram conventions.
  */
 
-import { findCallees, openReadonlyOrFail } from './db.js';
-import { isTestFile } from './infrastructure/test-filter.js';
-import { paginateResult } from './paginate.js';
-import { findMatchingNodes } from './queries.js';
+import { openRepo } from '../db/index.js';
+import { SqliteRepository } from '../db/repository/sqlite-repository.js';
+import { findMatchingNodes } from '../domain/queries.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { paginateResult } from '../shared/paginate.js';
 import { FRAMEWORK_ENTRY_PREFIXES } from './structure.js';
 
 // ─── Alias generation ────────────────────────────────────────────────
@@ -85,19 +86,19 @@ function buildAliases(files) {
  * @returns {{ entry, participants, messages, depth, totalMessages, truncated }}
  */
 export function sequenceData(name, dbPath, opts = {}) {
-  const db = openReadonlyOrFail(dbPath);
+  const { repo, close } = openRepo(dbPath, opts);
   try {
     const maxDepth = opts.depth || 10;
     const noTests = opts.noTests || false;
     const withDataflow = opts.dataflow || false;
 
     // Phase 1: Direct LIKE match
-    let matchNode = findMatchingNodes(db, name, opts)[0] ?? null;
+    let matchNode = findMatchingNodes(repo, name, opts)[0] ?? null;
 
     // Phase 2: Prefix-stripped matching
     if (!matchNode) {
       for (const prefix of FRAMEWORK_ENTRY_PREFIXES) {
-        matchNode = findMatchingNodes(db, `${prefix}${name}`, opts)[0] ?? null;
+        matchNode = findMatchingNodes(repo, `${prefix}${name}`, opts)[0] ?? null;
         if (matchNode) break;
       }
     }
@@ -133,7 +134,7 @@ export function sequenceData(name, dbPath, opts = {}) {
       const nextFrontier = [];
 
       for (const fid of frontier) {
-        const callees = findCallees(db, fid);
+        const callees = repo.findCallees(fid);
 
         const caller = idToNode.get(fid);
 
@@ -163,18 +164,17 @@ export function sequenceData(name, dbPath, opts = {}) {
 
       if (d === maxDepth && frontier.length > 0) {
         // Only mark truncated if at least one frontier node has further callees
-        const hasMoreCalls = frontier.some((fid) => findCallees(db, fid).length > 0);
+        const hasMoreCalls = frontier.some((fid) => repo.findCallees(fid).length > 0);
         if (hasMoreCalls) truncated = true;
       }
     }
 
     // Dataflow annotations: add return arrows
     if (withDataflow && messages.length > 0) {
-      const hasTable = db
-        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='dataflow'")
-        .get();
+      const hasTable = repo.hasDataflowTable();
 
-      if (hasTable) {
+      if (hasTable && repo instanceof SqliteRepository) {
+        const db = repo.db;
         // Build name|file lookup for O(1) target node access
         const nodeByNameFile = new Map();
         for (const n of idToNode.values()) {
@@ -281,45 +281,9 @@ export function sequenceData(name, dbPath, opts = {}) {
     }
     return result;
   } finally {
-    db.close();
+    close();
   }
 }
 
-// ─── Mermaid formatter ───────────────────────────────────────────────
-
-/**
- * Escape special Mermaid characters in labels.
- */
-function escapeMermaid(str) {
-  return str
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/:/g, '#colon;')
-    .replace(/"/g, '#quot;');
-}
-
-/**
- * Convert sequenceData result to Mermaid sequenceDiagram syntax.
- * @param {{ participants, messages, truncated }} seqResult
- * @returns {string}
- */
-export function sequenceToMermaid(seqResult) {
-  const lines = ['sequenceDiagram'];
-
-  for (const p of seqResult.participants) {
-    lines.push(`    participant ${p.id} as ${escapeMermaid(p.label)}`);
-  }
-
-  for (const msg of seqResult.messages) {
-    const arrow = msg.type === 'return' ? '-->>' : '->>';
-    lines.push(`    ${msg.from}${arrow}${msg.to}: ${escapeMermaid(msg.label)}`);
-  }
-
-  if (seqResult.truncated && seqResult.participants.length > 0) {
-    lines.push(
-      `    note right of ${seqResult.participants[0].id}: Truncated at depth ${seqResult.depth}`,
-    );
-  }
-
-  return lines.join('\n');
-}
+// Re-export Mermaid renderer from presentation layer
+export { sequenceToMermaid } from '../presentation/sequence-renderer.js';

package/src/{snapshot.js → features/snapshot.js}

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
-import { findDbPath } from './db.js';
-import { debug } from './logger.js';
+import { findDbPath } from '../db/index.js';
+import { debug } from '../infrastructure/logger.js';
+import { ConfigError, DbError } from '../shared/errors.js';
 
 const NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
@@ -12,7 +13,7 @@ const NAME_RE = /^[a-zA-Z0-9_-]+$/;
  */
 export function validateSnapshotName(name) {
   if (!name || !NAME_RE.test(name)) {
-    throw new Error(
+    throw new ConfigError(
       `Invalid snapshot name "${name}". Use only letters, digits, hyphens, and underscores.`,
     );
   }
@@ -39,7 +40,7 @@ export function snapshotSave(name, options = {}) {
   validateSnapshotName(name);
   const dbPath = options.dbPath || findDbPath();
   if (!fs.existsSync(dbPath)) {
-    throw new Error(`Database not found: ${dbPath}`);
+    throw new DbError(`Database not found: ${dbPath}`, { file: dbPath });
   }
 
   const dir = snapshotsDir(dbPath);
@@ -47,7 +48,7 @@ export function snapshotSave(name, options = {}) {
 
   if (fs.existsSync(dest)) {
     if (!options.force) {
-      throw new Error(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+      throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
     }
     fs.unlinkSync(dest);
     debug(`Deleted existing snapshot: ${dest}`);
@@ -82,7 +83,7 @@ export function snapshotRestore(name, options = {}) {
   const src = path.join(dir, `${name}.db`);
 
   if (!fs.existsSync(src)) {
-    throw new Error(`Snapshot "${name}" not found at ${src}`);
+    throw new DbError(`Snapshot "${name}" not found at ${src}`, { file: src });
   }
 
   // Remove WAL/SHM sidecar files for a clean restore
@@ -141,7 +142,7 @@ export function snapshotDelete(name, options = {}) {
   const target = path.join(dir, `${name}.db`);
 
   if (!fs.existsSync(target)) {
-    throw new Error(`Snapshot "${name}" not found at ${target}`);
+    throw new DbError(`Snapshot "${name}" not found at ${target}`, { file: target });
   }
 
   fs.unlinkSync(target);

package/src/{structure.js → features/structure.js}

@@ -1,9 +1,9 @@
 import path from 'node:path';
-import { normalizePath } from './constants.js';
-import { getNodeId, openReadonlyOrFail, testFilterSQL } from './db.js';
-import { isTestFile } from './infrastructure/test-filter.js';
-import { debug } from './logger.js';
-import { paginateResult } from './paginate.js';
+import { getNodeId, openReadonlyOrFail, testFilterSQL } from '../db/index.js';
+import { debug } from '../infrastructure/logger.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { normalizePath } from '../shared/constants.js';
+import { paginateResult } from '../shared/paginate.js';
 
 // ─── Build-time: insert directory nodes, contains edges, and metrics ────
 
@@ -312,13 +312,10 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
 
 // ─── Node role classification ─────────────────────────────────────────
 
-export const FRAMEWORK_ENTRY_PREFIXES = ['route:', 'event:', 'command:'];
+// Re-export from classifier for backward compatibility
+export { FRAMEWORK_ENTRY_PREFIXES } from '../graph/classifiers/roles.js';
 
-function median(sorted) {
-  if (sorted.length === 0) return 0;
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
-}
+import { classifyRoles } from '../graph/classifiers/roles.js';
 
 export function classifyNodeRoles(db) {
   const rows = db
@@ -354,44 +351,22 @@ export function classifyNodeRoles(db) {
       .map((r) => r.target_id),
   );
 
-  const nonZeroFanIn = rows
-    .filter((r) => r.fan_in > 0)
-    .map((r) => r.fan_in)
-    .sort((a, b) => a - b);
-  const nonZeroFanOut = rows
-    .filter((r) => r.fan_out > 0)
-    .map((r) => r.fan_out)
-    .sort((a, b) => a - b);
+  // Delegate classification to the pure-logic classifier
+  const classifierInput = rows.map((r) => ({
+    id: String(r.id),
+    name: r.name,
+    fanIn: r.fan_in,
+    fanOut: r.fan_out,
+    isExported: exportedIds.has(r.id),
+  }));
 
-  const medFanIn = median(nonZeroFanIn);
-  const medFanOut = median(nonZeroFanOut);
+  const roleMap = classifyRoles(classifierInput);
 
-  const updates = [];
+  // Build summary and updates
   const summary = { entry: 0, core: 0, utility: 0, adapter: 0, dead: 0, leaf: 0 };
-
+  const updates = [];
   for (const row of rows) {
-    const highIn = row.fan_in >= medFanIn && row.fan_in > 0;
-    const highOut = row.fan_out >= medFanOut && row.fan_out > 0;
-    const isExported = exportedIds.has(row.id);
-
-    let role;
-    const isFrameworkEntry = FRAMEWORK_ENTRY_PREFIXES.some((p) => row.name.startsWith(p));
-    if (isFrameworkEntry) {
-      role = 'entry';
-    } else if (row.fan_in === 0 && !isExported) {
-      role = 'dead';
-    } else if (row.fan_in === 0 && isExported) {
-      role = 'entry';
-    } else if (highIn && !highOut) {
-      role = 'core';
-    } else if (highIn && highOut) {
-      role = 'utility';
-    } else if (!highIn && highOut) {
-      role = 'adapter';
-    } else {
-      role = 'leaf';
-    }
-
+    const role = roleMap.get(String(row.id)) || 'leaf';
     updates.push({ id: row.id, role });
     summary[role]++;
   }