@optave/codegraph 3.1.2 → 3.1.4

package/src/resolve.js

@@ -178,4 +178,4 @@ export function resolveImportsBatch(inputs, rootDir, aliases, knownFiles) {
 
 // ── Exported for testing ────────────────────────────────────────────
 
-export { resolveImportPathJS, computeConfidenceJS };
+export { computeConfidenceJS, resolveImportPathJS };

package/src/sequence.js

@@ -285,41 +285,5 @@ export function sequenceData(name, dbPath, opts = {}) {
   }
 }
 
-// ─── 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/shared/file-utils.js

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { debug } from '../logger.js';
+import { LANGUAGE_REGISTRY } from '../parser.js';
+
+/**
+ * Resolve a file path relative to repoRoot, rejecting traversal outside the repo.
+ * Returns null if the resolved path escapes repoRoot.
+ */
+export function safePath(repoRoot, file) {
+  const resolved = path.resolve(repoRoot, file);
+  if (!resolved.startsWith(repoRoot + path.sep) && resolved !== repoRoot) return null;
+  return resolved;
+}
+
+export function readSourceRange(repoRoot, file, startLine, endLine) {
+  try {
+    const absPath = safePath(repoRoot, file);
+    if (!absPath) return null;
+    const content = fs.readFileSync(absPath, 'utf-8');
+    const lines = content.split('\n');
+    const start = Math.max(0, (startLine || 1) - 1);
+    const end = Math.min(lines.length, endLine || startLine + 50);
+    return lines.slice(start, end).join('\n');
+  } catch (e) {
+    debug(`readSourceRange failed for ${file}: ${e.message}`);
+    return null;
+  }
+}
+
+export function extractSummary(fileLines, line) {
+  if (!fileLines || !line || line <= 1) return null;
+  const idx = line - 2; // line above the definition (0-indexed)
+  // Scan up to 10 lines above for JSDoc or comment
+  let jsdocEnd = -1;
+  for (let i = idx; i >= Math.max(0, idx - 10); i--) {
+    const trimmed = fileLines[i].trim();
+    if (trimmed.endsWith('*/')) {
+      jsdocEnd = i;
+      break;
+    }
+    if (trimmed.startsWith('//') || trimmed.startsWith('#')) {
+      // Single-line comment immediately above
+      const text = trimmed
+        .replace(/^\/\/\s*/, '')
+        .replace(/^#\s*/, '')
+        .trim();
+      return text.length > 100 ? `${text.slice(0, 100)}...` : text;
+    }
+    if (trimmed !== '' && !trimmed.startsWith('*') && !trimmed.startsWith('/*')) break;
+  }
+  if (jsdocEnd >= 0) {
+    // Find opening /**
+    for (let i = jsdocEnd; i >= Math.max(0, jsdocEnd - 20); i--) {
+      if (fileLines[i].trim().startsWith('/**')) {
+        // Extract first non-tag, non-empty line
+        for (let j = i + 1; j <= jsdocEnd; j++) {
+          const docLine = fileLines[j]
+            .trim()
+            .replace(/^\*\s?/, '')
+            .trim();
+          if (docLine && !docLine.startsWith('@') && docLine !== '/' && docLine !== '*/') {
+            return docLine.length > 100 ? `${docLine.slice(0, 100)}...` : docLine;
+          }
+        }
+        break;
+      }
+    }
+  }
+  return null;
+}
+
+export function extractSignature(fileLines, line) {
+  if (!fileLines || !line) return null;
+  const idx = line - 1;
+  // Gather up to 5 lines to handle multi-line params
+  const chunk = fileLines.slice(idx, Math.min(fileLines.length, idx + 5)).join('\n');
+
+  // JS/TS: function name(params) or (params) => or async function
+  let m = chunk.match(
+    /(?:export\s+)?(?:async\s+)?function\s*\*?\s*\w*\s*\(([^)]*)\)\s*(?::\s*([^\n{]+))?/,
+  );
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim().replace(/\s*\{$/, '') : null,
+    };
+  }
+  // Arrow: const name = (params) => or (params):ReturnType =>
+  m = chunk.match(/=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*([^=>\n{]+))?\s*=>/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim() : null,
+    };
+  }
+  // Python: def name(params) -> return:
+  m = chunk.match(/def\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^:\n]+))?/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim() : null,
+    };
+  }
+  // Go: func (recv) name(params) (returns)
+  m = chunk.match(/func\s+(?:\([^)]*\)\s+)?\w+\s*\(([^)]*)\)\s*(?:\(([^)]+)\)|(\w[^\n{]*))?/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: (m[2] || m[3] || '').trim() || null,
+    };
+  }
+  // Rust: fn name(params) -> ReturnType
+  m = chunk.match(/fn\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^\n{]+))?/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim() : null,
+    };
+  }
+  return null;
+}
+
+export function createFileLinesReader(repoRoot) {
+  const cache = new Map();
+  return function getFileLines(file) {
+    if (cache.has(file)) return cache.get(file);
+    try {
+      const absPath = safePath(repoRoot, file);
+      if (!absPath) {
+        cache.set(file, null);
+        return null;
+      }
+      const lines = fs.readFileSync(absPath, 'utf-8').split('\n');
+      cache.set(file, lines);
+      return lines;
+    } catch (e) {
+      debug(`getFileLines failed for ${file}: ${e.message}`);
+      cache.set(file, null);
+      return null;
+    }
+  };
+}
+
+export function isFileLikeTarget(target) {
+  if (target.includes('/') || target.includes('\\')) return true;
+  const ext = path.extname(target).toLowerCase();
+  if (!ext) return false;
+  for (const entry of LANGUAGE_REGISTRY) {
+    if (entry.extensions.includes(ext)) return true;
+  }
+  return false;
+}

package/src/shared/generators.js

@@ -0,0 +1,125 @@
+import { iterateFunctionNodes, openReadonlyOrFail } from '../db.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { ALL_SYMBOL_KINDS } from '../kinds.js';
+
+/**
+ * Generator: stream functions one-by-one using .iterate() for memory efficiency.
+ * @param {string} [customDbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.file]
+ * @param {string} [opts.pattern]
+ * @yields {{ name: string, kind: string, file: string, line: number, role: string|null }}
+ */
+export function* iterListFunctions(customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+
+    for (const row of iterateFunctionNodes(db, { file: opts.file, pattern: opts.pattern })) {
+      if (noTests && isTestFile(row.file)) continue;
+      yield {
+        name: row.name,
+        kind: row.kind,
+        file: row.file,
+        line: row.line,
+        endLine: row.end_line ?? null,
+        role: row.role ?? null,
+      };
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Generator: stream role-classified symbols one-by-one.
+ * @param {string} [customDbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.role]
+ * @param {string} [opts.file]
+ * @yields {{ name: string, kind: string, file: string, line: number, endLine: number|null, role: string }}
+ */
+export function* iterRoles(customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const conditions = ['role IS NOT NULL'];
+    const params = [];
+
+    if (opts.role) {
+      conditions.push('role = ?');
+      params.push(opts.role);
+    }
+    if (opts.file) {
+      conditions.push('file LIKE ?');
+      params.push(`%${opts.file}%`);
+    }
+
+    const stmt = db.prepare(
+      `SELECT name, kind, file, line, end_line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
+    );
+    for (const row of stmt.iterate(...params)) {
+      if (noTests && isTestFile(row.file)) continue;
+      yield {
+        name: row.name,
+        kind: row.kind,
+        file: row.file,
+        line: row.line,
+        endLine: row.end_line ?? null,
+        role: row.role ?? null,
+      };
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Generator: stream symbol lookup results one-by-one.
+ * @param {string} target - Symbol name to search for (partial match)
+ * @param {string} [customDbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @yields {{ name: string, kind: string, file: string, line: number, role: string|null, exported: boolean, uses: object[] }}
+ */
+export function* iterWhere(target, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const placeholders = ALL_SYMBOL_KINDS.map(() => '?').join(', ');
+    const stmt = db.prepare(
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN (${placeholders}) ORDER BY file, line`,
+    );
+    const crossFileCallersStmt = db.prepare(
+      `SELECT COUNT(*) as cnt FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id = ? AND e.kind = 'calls' AND n.file != ?`,
+    );
+    const usesStmt = db.prepare(
+      `SELECT n.name, n.file, n.line FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id = ? AND e.kind = 'calls'`,
+    );
+    for (const node of stmt.iterate(`%${target}%`, ...ALL_SYMBOL_KINDS)) {
+      if (noTests && isTestFile(node.file)) continue;
+
+      const crossFileCallers = crossFileCallersStmt.get(node.id, node.file);
+      const exported = crossFileCallers.cnt > 0;
+
+      let uses = usesStmt.all(node.id);
+      if (noTests) uses = uses.filter((u) => !isTestFile(u.file));
+
+      yield {
+        name: node.name,
+        kind: node.kind,
+        file: node.file,
+        line: node.line,
+        role: node.role || null,
+        exported,
+        uses: uses.map((u) => ({ name: u.name, file: u.file, line: u.line })),
+      };
+    }
+  } finally {
+    db.close();
+  }
+}

package/src/shared/hierarchy.js

@@ -0,0 +1,27 @@
+import { getClassHierarchy } from '../db.js';
+
+export function resolveMethodViaHierarchy(db, methodName) {
+  const methods = db
+    .prepare(`SELECT * FROM nodes WHERE kind = 'method' AND name LIKE ?`)
+    .all(`%.${methodName}`);
+
+  const results = [...methods];
+  for (const m of methods) {
+    const className = m.name.split('.')[0];
+    const classNode = db
+      .prepare(`SELECT * FROM nodes WHERE name = ? AND kind = 'class' AND file = ?`)
+      .get(className, m.file);
+    if (!classNode) continue;
+
+    const ancestors = getClassHierarchy(db, classNode.id);
+    for (const ancestorId of ancestors) {
+      const ancestor = db.prepare('SELECT name FROM nodes WHERE id = ?').get(ancestorId);
+      if (!ancestor) continue;
+      const parentMethods = db
+        .prepare(`SELECT * FROM nodes WHERE name = ? AND kind = 'method'`)
+        .all(`${ancestor.name}.${methodName}`);
+      results.push(...parentMethods);
+    }
+  }
+  return results;
+}

package/src/shared/normalize.js

@@ -0,0 +1,59 @@
+export function getFileHash(db, file) {
+  const row = db.prepare('SELECT hash FROM file_hashes WHERE file = ?').get(file);
+  return row ? row.hash : null;
+}
+
+export function kindIcon(kind) {
+  switch (kind) {
+    case 'function':
+      return 'f';
+    case 'class':
+      return '*';
+    case 'method':
+      return 'o';
+    case 'file':
+      return '#';
+    case 'interface':
+      return 'I';
+    case 'type':
+      return 'T';
+    case 'parameter':
+      return 'p';
+    case 'property':
+      return '.';
+    case 'constant':
+      return 'C';
+    default:
+      return '-';
+  }
+}
+
+/**
+ * Normalize a raw DB/query row into the stable 7-field symbol shape.
+ * @param {object} row    - Raw row (from SELECT * or explicit columns)
+ * @param {object} [db]   - Open DB handle; when null, fileHash will be null
+ * @param {Map}    [hashCache] - Optional per-file cache to avoid repeated getFileHash calls
+ * @returns {{ name: string, kind: string, file: string, line: number, endLine: number|null, role: string|null, fileHash: string|null }}
+ */
+export function normalizeSymbol(row, db, hashCache) {
+  let fileHash = null;
+  if (db) {
+    if (hashCache) {
+      if (!hashCache.has(row.file)) {
+        hashCache.set(row.file, getFileHash(db, row.file));
+      }
+      fileHash = hashCache.get(row.file);
+    } else {
+      fileHash = getFileHash(db, row.file);
+    }
+  }
+  return {
+    name: row.name,
+    kind: row.kind,
+    file: row.file,
+    line: row.line,
+    endLine: row.end_line ?? row.endLine ?? null,
+    role: row.role ?? null,
+    fileHash,
+  };
+}

package/src/snapshot.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
 import { findDbPath } from './db.js';
+import { ConfigError, DbError } from './errors.js';
 import { debug } from './logger.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

@@ -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]++;
   }

package/src/triage.js

@@ -1,40 +1,9 @@
 import { findNodesForTriage, openReadonlyOrFail } from './db.js';
+import { DEFAULT_WEIGHTS, scoreRisk } from './graph/classifiers/risk.js';
 import { isTestFile } from './infrastructure/test-filter.js';
 import { warn } from './logger.js';
 import { paginateResult } from './paginate.js';
 
-// ─── Constants ────────────────────────────────────────────────────────
-
-const DEFAULT_WEIGHTS = {
-  fanIn: 0.25,
-  complexity: 0.3,
-  churn: 0.2,
-  role: 0.15,
-  mi: 0.1,
-};
-
-const ROLE_WEIGHTS = {
-  core: 1.0,
-  utility: 0.9,
-  entry: 0.8,
-  adapter: 0.5,
-  leaf: 0.2,
-  dead: 0.1,
-};
-
-const DEFAULT_ROLE_WEIGHT = 0.5;
-
-// ─── Helpers ──────────────────────────────────────────────────────────
-
-/** Min-max normalize an array of numbers. All-equal → all zeros. */
-function minMaxNormalize(values) {
-  const min = Math.min(...values);
-  const max = Math.max(...values);
-  if (max === min) return values.map(() => 0);
-  const range = max - min;
-  return values.map((v) => (v - min) / range);
-}
-
 // ─── Data Function ────────────────────────────────────────────────────
 
 /**
@@ -81,48 +50,27 @@ export function triageData(customDbPath, opts = {}) {
       };
     }
 
-    // Extract raw signal arrays
-    const fanIns = filtered.map((r) => r.fan_in);
-    const cognitives = filtered.map((r) => r.cognitive);
-    const churns = filtered.map((r) => r.churn);
-    const mis = filtered.map((r) => r.mi);
-
-    // Min-max normalize
-    const normFanIns = minMaxNormalize(fanIns);
-    const normCognitives = minMaxNormalize(cognitives);
-    const normChurns = minMaxNormalize(churns);
-    // MI: higher is better, so invert: 1 - norm(mi)
-    const normMIsRaw = minMaxNormalize(mis);
-    const normMIs = normMIsRaw.map((v) => round4(1 - v));
+    // Delegate scoring to classifier
+    const riskMetrics = scoreRisk(filtered, weights);
 
     // Compute risk scores
-    const items = filtered.map((r, i) => {
-      const roleWeight = ROLE_WEIGHTS[r.role] ?? DEFAULT_ROLE_WEIGHT;
-      const riskScore =
-        weights.fanIn * normFanIns[i] +
-        weights.complexity * normCognitives[i] +
-        weights.churn * normChurns[i] +
-        weights.role * roleWeight +
-        weights.mi * normMIs[i];
-
-      return {
-        name: r.name,
-        kind: r.kind,
-        file: r.file,
-        line: r.line,
-        role: r.role || null,
-        fanIn: r.fan_in,
-        cognitive: r.cognitive,
-        churn: r.churn,
-        maintainabilityIndex: r.mi,
-        normFanIn: round4(normFanIns[i]),
-        normComplexity: round4(normCognitives[i]),
-        normChurn: round4(normChurns[i]),
-        normMI: round4(normMIs[i]),
-        roleWeight,
-        riskScore: round4(riskScore),
-      };
-    });
+    const items = filtered.map((r, i) => ({
+      name: r.name,
+      kind: r.kind,
+      file: r.file,
+      line: r.line,
+      role: r.role || null,
+      fanIn: r.fan_in,
+      cognitive: r.cognitive,
+      churn: r.churn,
+      maintainabilityIndex: r.mi,
+      normFanIn: riskMetrics[i].normFanIn,
+      normComplexity: riskMetrics[i].normComplexity,
+      normChurn: riskMetrics[i].normChurn,
+      normMI: riskMetrics[i].normMI,
+      roleWeight: riskMetrics[i].roleWeight,
+      riskScore: riskMetrics[i].riskScore,
+    }));
 
     // Apply minScore filter
     const scored = minScore != null ? items.filter((it) => it.riskScore >= minScore) : items;