@optave/codegraph 3.1.5 → 3.3.0

package/src/db/migrations.js

@@ -242,11 +242,23 @@ export const MIGRATIONS = [
   },
 ];
 
+function hasColumn(db, table, column) {
+  const cols = db.pragma(`table_info(${table})`);
+  return cols.some((c) => c.name === column);
+}
+
+function hasTable(db, table) {
+  const row = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table);
+  return !!row;
+}
+
 export function getBuildMeta(db, key) {
+  if (!hasTable(db, 'build_meta')) return null;
   try {
     const row = db.prepare('SELECT value FROM build_meta WHERE key = ?').get(key);
     return row ? row.value : null;
-  } catch {
+  } catch (e) {
+    debug(`getBuildMeta failed for key "${key}": ${e.message}`);
     return null;
   }
 }
@@ -280,74 +292,39 @@ export function initSchema(db) {
     }
   }
 
-  try {
-    db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER');
-  } catch {
-    /* already exists */
-  }
-  try {
-    db.exec('ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0');
-  } catch {
-    /* already exists */
-  }
-  try {
-    db.exec('ALTER TABLE edges ADD COLUMN dynamic INTEGER DEFAULT 0');
-  } catch {
-    /* already exists */
-  }
-  try {
-    db.exec('ALTER TABLE nodes ADD COLUMN role TEXT');
-  } catch {
-    /* already exists */
-  }
-  try {
+  // Legacy column compat — add columns that may be missing from pre-migration DBs
+  if (hasTable(db, 'nodes')) {
+    if (!hasColumn(db, 'nodes', 'end_line')) {
+      db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER');
+    }
+    if (!hasColumn(db, 'nodes', 'role')) {
+      db.exec('ALTER TABLE nodes ADD COLUMN role TEXT');
+    }
     db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_role ON nodes(role)');
-  } catch {
-    /* already exists */
-  }
-  try {
-    db.exec('ALTER TABLE nodes ADD COLUMN parent_id INTEGER REFERENCES nodes(id)');
-  } catch {
-    /* already exists */
-  }
-  try {
+    if (!hasColumn(db, 'nodes', 'parent_id')) {
+      db.exec('ALTER TABLE nodes ADD COLUMN parent_id INTEGER REFERENCES nodes(id)');
+    }
     db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id)');
-  } catch {
-    /* already exists */
-  }
-  try {
     db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_kind_parent ON nodes(kind, parent_id)');
-  } 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 {
+    if (!hasColumn(db, 'nodes', 'qualified_name')) {
+      db.exec('ALTER TABLE nodes ADD COLUMN qualified_name TEXT');
+    }
+    if (!hasColumn(db, 'nodes', 'scope')) {
+      db.exec('ALTER TABLE nodes ADD COLUMN scope TEXT');
+    }
+    if (!hasColumn(db, 'nodes', 'visibility')) {
+      db.exec('ALTER TABLE nodes ADD COLUMN visibility TEXT');
+    }
     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 */
+  }
+  if (hasTable(db, 'edges')) {
+    if (!hasColumn(db, 'edges', 'confidence')) {
+      db.exec('ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0');
+    }
+    if (!hasColumn(db, 'edges', 'dynamic')) {
+      db.exec('ALTER TABLE edges ADD COLUMN dynamic INTEGER DEFAULT 0');
+    }
   }
 }

package/src/db/query-builder.js

@@ -1,5 +1,5 @@
 import { DbError } from '../shared/errors.js';
-import { EVERY_EDGE_KIND } from '../shared/kinds.js';
+import { DEAD_ROLE_PREFIX, EVERY_EDGE_KIND } from '../shared/kinds.js';
 
 // ─── Validation Helpers ─────────────────────────────────────────────
 
@@ -72,6 +72,55 @@ export function escapeLike(s) {
   return s.replace(/[%_\\]/g, '\\$&');
 }
 
+/**
+ * Normalize a file filter value (string, string[], or falsy) into a flat array.
+ * Returns an empty array when the input is falsy.
+ * @param {string|string[]|undefined|null} file
+ * @returns {string[]}
+ */
+export function normalizeFileFilter(file) {
+  if (!file) return [];
+  return Array.isArray(file) ? file : [file];
+}
+
+/**
+ * Build a SQL condition + params for a multi-value file LIKE filter.
+ * Returns `{ sql: '', params: [] }` when the filter is empty.
+ *
+ * @param {string|string[]} file - One or more partial file paths
+ * @param {string} [column='file'] - The column name to filter on (e.g. 'n.file', 'a.file')
+ * @returns {{ sql: string, params: string[] }}
+ */
+export function buildFileConditionSQL(file, column = 'file') {
+  validateColumn(column);
+  const files = normalizeFileFilter(file);
+  if (files.length === 0) return { sql: '', params: [] };
+  if (files.length === 1) {
+    return {
+      sql: ` AND ${column} LIKE ? ESCAPE '\\'`,
+      params: [`%${escapeLike(files[0])}%`],
+    };
+  }
+  const clauses = files.map(() => `${column} LIKE ? ESCAPE '\\'`);
+  return {
+    sql: ` AND (${clauses.join(' OR ')})`,
+    params: files.map((f) => `%${escapeLike(f)}%`),
+  };
+}
+
+/**
+ * Commander option accumulator for repeatable `--file` flag.
+ * Use as: `['-f, --file <path>', 'Scope to file (partial match, repeatable)', collectFile]`
+ * @param {string} val - New value from Commander
+ * @param {string[]} acc - Accumulated values (undefined on first call)
+ * @returns {string[]}
+ */
+export function collectFile(val, acc) {
+  acc = acc || [];
+  acc.push(val);
+  return acc;
+}
+
 // ─── Standalone Helpers ──────────────────────────────────────────────
 
 /**
@@ -171,11 +220,18 @@ export class NodeQuery {
     return this;
   }
 
-  /** WHERE n.file LIKE ? (no-op if falsy). Escapes LIKE wildcards in the value. */
+  /** WHERE n.file LIKE ? (no-op if falsy). Accepts a single string or string[]. */
   fileFilter(file) {
-    if (!file) return this;
-    this.#conditions.push("n.file LIKE ? ESCAPE '\\'");
-    this.#params.push(`%${escapeLike(file)}%`);
+    const files = normalizeFileFilter(file);
+    if (files.length === 0) return this;
+    if (files.length === 1) {
+      this.#conditions.push("n.file LIKE ? ESCAPE '\\'");
+      this.#params.push(`%${escapeLike(files[0])}%`);
+    } else {
+      const clauses = files.map(() => "n.file LIKE ? ESCAPE '\\'");
+      this.#conditions.push(`(${clauses.join(' OR ')})`);
+      this.#params.push(...files.map((f) => `%${escapeLike(f)}%`));
+    }
     return this;
   }
 
@@ -187,11 +243,16 @@ export class NodeQuery {
     return this;
   }
 
-  /** WHERE n.role = ? (no-op if falsy). */
+  /** WHERE n.role = ? (no-op if falsy). 'dead' matches all dead-* sub-roles. */
   roleFilter(role) {
     if (!role) return this;
-    this.#conditions.push('n.role = ?');
-    this.#params.push(role);
+    if (role === DEAD_ROLE_PREFIX) {
+      this.#conditions.push('n.role LIKE ?');
+      this.#params.push(`${DEAD_ROLE_PREFIX}%`);
+    } else {
+      this.#conditions.push('n.role = ?');
+      this.#params.push(role);
+    }
     return this;
   }
 

package/src/db/repository/edges.js

@@ -15,6 +15,8 @@ const _findCrossFileCallTargetsStmt = new WeakMap();
 const _countCrossFileCallersStmt = new WeakMap();
 const _getClassAncestorsStmt = new WeakMap();
 const _findIntraFileCallEdgesStmt = new WeakMap();
+const _findImplementorsStmt = new WeakMap();
+const _findInterfacesStmt = new WeakMap();
 
 // ─── Call-edge queries ──────────────────────────────────────────────────
 
@@ -260,6 +262,42 @@ export function getClassHierarchy(db, classNodeId) {
   return ancestors;
 }
 
+// ─── Implements-edge queries ──────────────────────────────────────────
+
+/**
+ * Find all concrete types that implement a given interface/trait node.
+ * Follows incoming 'implements' edges (source = implementor, target = interface).
+ * @param {object} db
+ * @param {number} nodeId - The interface/trait node ID
+ * @returns {{ id: number, name: string, kind: string, file: string, line: number }[]}
+ */
+export function findImplementors(db, nodeId) {
+  return cachedStmt(
+    _findImplementorsStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'implements'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find all interfaces/traits that a given class/struct implements.
+ * Follows outgoing 'implements' edges (source = class, target = interface).
+ * @param {object} db
+ * @param {number} nodeId - The class/struct node ID
+ * @returns {{ id: number, name: string, kind: string, file: string, line: number }[]}
+ */
+export function findInterfaces(db, nodeId) {
+  return cachedStmt(
+    _findInterfacesStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'implements'`,
+  ).all(nodeId);
+}
+
 /**
  * Find intra-file call edges (caller → callee within the same file).
  * Used by explainFileImpl for data flow visualization.

package/src/db/repository/in-memory-repository.js

@@ -1,6 +1,11 @@
 import { ConfigError } from '../../shared/errors.js';
-import { CORE_SYMBOL_KINDS, EVERY_SYMBOL_KIND, VALID_ROLES } from '../../shared/kinds.js';
-import { escapeLike } from '../query-builder.js';
+import {
+  CORE_SYMBOL_KINDS,
+  DEAD_ROLE_PREFIX,
+  EVERY_SYMBOL_KIND,
+  VALID_ROLES,
+} from '../../shared/kinds.js';
+import { escapeLike, normalizeFileFilter } from '../query-builder.js';
 import { Repository } from './base.js';
 
 /**
@@ -27,6 +32,17 @@ function likeToRegex(pattern) {
   return new RegExp(`^${regex}$`, 'i');
 }
 
+/**
+ * Build a filter predicate for file matching.
+ * Accepts string, string[], or falsy. Returns null when no filtering needed.
+ */
+function buildFileFilterFn(file) {
+  const files = normalizeFileFilter(file);
+  if (files.length === 0) return null;
+  const regexes = files.map((f) => likeToRegex(`%${escapeLike(f)}%`));
+  return (filePath) => regexes.some((re) => re.test(filePath));
+}
+
 /**
  * In-memory Repository implementation backed by Maps.
  * No SQLite dependency — suitable for fast unit tests.
@@ -121,9 +137,9 @@ export class InMemoryRepository extends Repository {
     if (opts.kinds) {
       nodes = nodes.filter((n) => opts.kinds.includes(n.kind));
     }
-    if (opts.file) {
-      const fileRe = likeToRegex(`%${escapeLike(opts.file)}%`);
-      nodes = nodes.filter((n) => fileRe.test(n.file));
+    {
+      const fileFn = buildFileFilterFn(opts.file);
+      if (fileFn) nodes = nodes.filter((n) => fileFn(n.file));
     }
 
     // Compute fan-in per node
@@ -197,9 +213,9 @@ export class InMemoryRepository extends Repository {
     if (opts.kind) {
       nodes = nodes.filter((n) => n.kind === opts.kind);
     }
-    if (opts.file) {
-      const fileRe = likeToRegex(`%${escapeLike(opts.file)}%`);
-      nodes = nodes.filter((n) => fileRe.test(n.file));
+    {
+      const fileFn = buildFileFilterFn(opts.file);
+      if (fileFn) nodes = nodes.filter((n) => fileFn(n.file));
     }
 
     return nodes.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
@@ -208,9 +224,9 @@ export class InMemoryRepository extends Repository {
   findNodeByQualifiedName(qualifiedName, opts = {}) {
     let nodes = [...this.#nodes.values()].filter((n) => n.qualified_name === qualifiedName);
 
-    if (opts.file) {
-      const fileRe = likeToRegex(`%${escapeLike(opts.file)}%`);
-      nodes = nodes.filter((n) => fileRe.test(n.file));
+    {
+      const fileFn = buildFileFilterFn(opts.file);
+      if (fileFn) nodes = nodes.filter((n) => fileFn(n.file));
     }
 
     return nodes.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
@@ -248,12 +264,16 @@ export class InMemoryRepository extends Repository {
           !n.file.includes('.stories.'),
       );
     }
-    if (opts.file) {
-      const fileRe = likeToRegex(`%${escapeLike(opts.file)}%`);
-      nodes = nodes.filter((n) => fileRe.test(n.file));
+    {
+      const fileFn = buildFileFilterFn(opts.file);
+      if (fileFn) nodes = nodes.filter((n) => fileFn(n.file));
     }
     if (opts.role) {
-      nodes = nodes.filter((n) => n.role === opts.role);
+      nodes = nodes.filter((n) =>
+        opts.role === DEAD_ROLE_PREFIX
+          ? n.role?.startsWith(DEAD_ROLE_PREFIX)
+          : n.role === opts.role,
+      );
     }
 
     const fanInMap = this.#computeFanIn();
@@ -541,9 +561,9 @@ export class InMemoryRepository extends Repository {
       ['function', 'method', 'class'].includes(n.kind),
     );
 
-    if (opts.file) {
-      const fileRe = likeToRegex(`%${escapeLike(opts.file)}%`);
-      nodes = nodes.filter((n) => fileRe.test(n.file));
+    {
+      const fileFn = buildFileFilterFn(opts.file);
+      if (fileFn) nodes = nodes.filter((n) => fileFn(n.file));
     }
     if (opts.pattern) {
       const patternRe = likeToRegex(`%${escapeLike(opts.pattern)}%`);

package/src/db/repository/index.js

@@ -17,9 +17,11 @@ export {
   findCallers,
   findCrossFileCallTargets,
   findDistinctCallers,
+  findImplementors,
   findImportDependents,
   findImportSources,
   findImportTargets,
+  findInterfaces,
   findIntraFileCallEdges,
   getClassHierarchy,
 } from './edges.js';

package/src/db/repository/nodes.js

@@ -1,6 +1,6 @@
 import { ConfigError } from '../../shared/errors.js';
 import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../shared/kinds.js';
-import { escapeLike, NodeQuery } from '../query-builder.js';
+import { buildFileConditionSQL, NodeQuery } from '../query-builder.js';
 import { cachedStmt } from './cached-stmt.js';
 
 // ─── Query-builder based lookups (moved from src/db/repository.js) ─────
@@ -267,10 +267,9 @@ export function findNodesByScope(db, scopeName, opts = {}) {
     sql += ' AND kind = ?';
     params.push(opts.kind);
   }
-  if (opts.file) {
-    sql += " AND file LIKE ? ESCAPE '\\'";
-    params.push(`%${escapeLike(opts.file)}%`);
-  }
+  const fc = buildFileConditionSQL(opts.file, 'file');
+  sql += fc.sql;
+  params.push(...fc.params);
   sql += ' ORDER BY file, line';
   return db.prepare(sql).all(...params);
 }
@@ -286,12 +285,11 @@ export function findNodesByScope(db, scopeName, opts = {}) {
  * @returns {object[]}
  */
 export function findNodeByQualifiedName(db, qualifiedName, opts = {}) {
-  if (opts.file) {
+  const fc = buildFileConditionSQL(opts.file, 'file');
+  if (fc.sql) {
     return db
-      .prepare(
-        "SELECT * FROM nodes WHERE qualified_name = ? AND file LIKE ? ESCAPE '\\' ORDER BY file, line",
-      )
-      .all(qualifiedName, `%${escapeLike(opts.file)}%`);
+      .prepare(`SELECT * FROM nodes WHERE qualified_name = ?${fc.sql} ORDER BY file, line`)
+      .all(qualifiedName, ...fc.params);
   }
   return cachedStmt(
     _findNodeByQualifiedNameStmt,

package/src/domain/analysis/brief.js

@@ -0,0 +1,161 @@
+import {
+  findDistinctCallers,
+  findFileNodes,
+  findImportDependents,
+  findImportSources,
+  findImportTargets,
+  findNodesByFile,
+  openReadonlyOrFail,
+} from '../../db/index.js';
+import { loadConfig } from '../../infrastructure/config.js';
+import { isTestFile } from '../../infrastructure/test-filter.js';
+
+/** Symbol kinds meaningful for a file brief — excludes parameters, properties, constants. */
+const BRIEF_KINDS = new Set([
+  'function',
+  'method',
+  'class',
+  'interface',
+  'type',
+  'struct',
+  'enum',
+  'trait',
+  'record',
+  'module',
+]);
+
+/**
+ * Compute file risk tier from symbol roles and max fan-in.
+ * @param {{ role: string|null, callerCount: number }[]} symbols
+ * @returns {'high'|'medium'|'low'}
+ */
+function computeRiskTier(symbols, highThreshold = 10, mediumThreshold = 3) {
+  let maxCallers = 0;
+  let hasCoreRole = false;
+  for (const s of symbols) {
+    if (s.callerCount > maxCallers) maxCallers = s.callerCount;
+    if (s.role === 'core') hasCoreRole = true;
+  }
+  if (maxCallers >= highThreshold || hasCoreRole) return 'high';
+  if (maxCallers >= mediumThreshold) return 'medium';
+  return 'low';
+}
+
+/**
+ * BFS to count transitive callers for a single node.
+ * Lightweight variant — only counts, does not collect details.
+ */
+function countTransitiveCallers(db, startId, noTests, maxDepth = 5) {
+  const visited = new Set([startId]);
+  let frontier = [startId];
+
+  for (let d = 1; d <= maxDepth; d++) {
+    const nextFrontier = [];
+    for (const fid of frontier) {
+      const callers = findDistinctCallers(db, fid);
+      for (const c of callers) {
+        if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
+          visited.add(c.id);
+          nextFrontier.push(c.id);
+        }
+      }
+    }
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+  }
+
+  return visited.size - 1;
+}
+
+/**
+ * Count transitive file-level import dependents via BFS.
+ * Depth-bounded to match countTransitiveCallers and keep hook latency predictable.
+ */
+function countTransitiveImporters(db, fileNodeIds, noTests, maxDepth = 5) {
+  const visited = new Set(fileNodeIds);
+  let frontier = [...fileNodeIds];
+
+  for (let d = 1; d <= maxDepth; d++) {
+    const nextFrontier = [];
+    for (const current of frontier) {
+      const dependents = findImportDependents(db, current);
+      for (const dep of dependents) {
+        if (!visited.has(dep.id) && (!noTests || !isTestFile(dep.file))) {
+          visited.add(dep.id);
+          nextFrontier.push(dep.id);
+        }
+      }
+    }
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+  }
+
+  return visited.size - fileNodeIds.length;
+}
+
+/**
+ * Produce a token-efficient file brief: symbols with roles and caller counts,
+ * importer info with transitive count, and file risk tier.
+ *
+ * @param {string} file - File path (partial match)
+ * @param {string} customDbPath - Path to graph.db
+ * @param {{ noTests?: boolean }} opts
+ * @returns {{ file: string, results: object[] }}
+ */
+export function briefData(file, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const config = opts.config || loadConfig();
+    const callerDepth = config.analysis?.briefCallerDepth ?? 5;
+    const importerDepth = config.analysis?.briefImporterDepth ?? 5;
+    const highRiskCallers = config.analysis?.briefHighRiskCallers ?? 10;
+    const mediumRiskCallers = config.analysis?.briefMediumRiskCallers ?? 3;
+    const fileNodes = findFileNodes(db, `%${file}%`);
+    if (fileNodes.length === 0) {
+      return { file, results: [] };
+    }
+
+    const results = fileNodes.map((fn) => {
+      // Direct importers
+      let importedBy = findImportSources(db, fn.id);
+      if (noTests) importedBy = importedBy.filter((i) => !isTestFile(i.file));
+      const directImporters = [...new Set(importedBy.map((i) => i.file))];
+
+      // Transitive importer count
+      const totalImporterCount = countTransitiveImporters(db, [fn.id], noTests, importerDepth);
+
+      // Direct imports
+      let importsTo = findImportTargets(db, fn.id);
+      if (noTests) importsTo = importsTo.filter((i) => !isTestFile(i.file));
+
+      // Symbol definitions with roles and caller counts
+      const defs = findNodesByFile(db, fn.file).filter((d) => BRIEF_KINDS.has(d.kind));
+      const symbols = defs.map((d) => {
+        const callerCount = countTransitiveCallers(db, d.id, noTests, callerDepth);
+        return {
+          name: d.name,
+          kind: d.kind,
+          line: d.line,
+          role: d.role || null,
+          callerCount,
+        };
+      });
+
+      const riskTier = computeRiskTier(symbols, highRiskCallers, mediumRiskCallers);
+
+      return {
+        file: fn.file,
+        risk: riskTier,
+        imports: importsTo.map((i) => i.file),
+        importedBy: directImporters,
+        totalImporterCount,
+        symbols,
+      };
+    });
+
+    return { file, results };
+  } finally {
+    db.close();
+  }
+}