@optave/codegraph 3.1.5 → 3.2.0

package/src/db/query-builder.js

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

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

@@ -1,6 +1,6 @@
 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 { escapeLike, normalizeFileFilter } from '../query-builder.js';
 import { Repository } from './base.js';
 
 /**
@@ -27,6 +27,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 +132,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 +208,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 +219,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,9 +259,9 @@ 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);
@@ -541,9 +552,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/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,155 @@
+import {
+  findDistinctCallers,
+  findFileNodes,
+  findImportDependents,
+  findImportSources,
+  findImportTargets,
+  findNodesByFile,
+  openReadonlyOrFail,
+} from '../../db/index.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) {
+  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 >= 10 || hasCoreRole) return 'high';
+  if (maxCallers >= 3) 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 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);
+
+      // 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);
+        return {
+          name: d.name,
+          kind: d.kind,
+          line: d.line,
+          role: d.role || null,
+          callerCount,
+        };
+      });
+
+      const riskTier = computeRiskTier(symbols);
+
+      return {
+        file: fn.file,
+        risk: riskTier,
+        imports: importsTo.map((i) => i.file),
+        importedBy: directImporters,
+        totalImporterCount,
+        symbols,
+      };
+    });
+
+    return { file, results };
+  } finally {
+    db.close();
+  }
+}