@optave/codegraph 3.8.0 → 3.9.0

package/src/ast-analysis/visitors/dataflow-visitor.ts

@@ -116,14 +116,13 @@ function isCall(node: TreeSitterNode | null, isCallNode: (t: string) => boolean)
   return node != null && isCallNode(node.type);
 }
 
-function handleVarDeclarator(
+/** Resolve the value node from a variable declarator, trying multiple strategies. */
+function resolveValueNode(
   node: TreeSitterNode,
+  nameNode: TreeSitterNode | null,
   rules: AnyRules,
-  scopeStack: ScopeEntry[],
-  assignments: DataflowAssignment[],
   isCallNode: (t: string) => boolean,
-): void {
-  let nameNode = node.childForFieldName(rules.varNameField);
+): TreeSitterNode | null {
   let valueNode: TreeSitterNode | null = rules.varValueField
     ? node.childForFieldName(rules.varValueField)
     : null;
@@ -146,52 +145,97 @@ function handleVarDeclarator(
     }
   }
 
-  if (rules.expressionListType) {
-    if (nameNode && nameNode.type === rules.expressionListType)
-      nameNode = nameNode.namedChildren[0] ?? null;
-    if (valueNode && valueNode.type === rules.expressionListType)
-      valueNode = valueNode.namedChildren[0] ?? null;
+  return valueNode;
+}
+
+/** Unwrap expression-list wrappers from name/value nodes. */
+function unwrapExpressionList(
+  nameNode: TreeSitterNode | null,
+  valueNode: TreeSitterNode | null,
+  rules: AnyRules,
+): { name: TreeSitterNode | null; value: TreeSitterNode | null } {
+  if (!rules.expressionListType) return { name: nameNode, value: valueNode };
+  const name =
+    nameNode && nameNode.type === rules.expressionListType
+      ? (nameNode.namedChildren[0] ?? null)
+      : nameNode;
+  const value =
+    valueNode && valueNode.type === rules.expressionListType
+      ? (valueNode.namedChildren[0] ?? null)
+      : valueNode;
+  return { name, value };
+}
+
+/** Record a destructured call assignment (object or array destructuring). */
+function recordDestructuredAssignment(
+  nameNode: TreeSitterNode,
+  node: TreeSitterNode,
+  callee: string,
+  scope: ScopeEntry,
+  assignments: DataflowAssignment[],
+  rules: AnyRules,
+): void {
+  const names = extractParamNames(nameNode, rules);
+  for (const n of names) {
+    assignments.push({
+      varName: n,
+      callerFunc: scope.funcName!,
+      sourceCallName: callee,
+      expression: truncate(node.text),
+      line: node.startPosition.row + 1,
+    });
+    scope.locals.set(n, { type: 'destructured', callee });
   }
+}
+
+/** Record a simple (non-destructured) call assignment. */
+function recordSimpleAssignment(
+  nameNode: TreeSitterNode,
+  node: TreeSitterNode,
+  callee: string,
+  scope: ScopeEntry,
+  assignments: DataflowAssignment[],
+): void {
+  const varName = nameNode.text;
+  assignments.push({
+    varName,
+    callerFunc: scope.funcName!,
+    sourceCallName: callee,
+    expression: truncate(node.text),
+    line: node.startPosition.row + 1,
+  });
+  scope.locals.set(varName, { type: 'call_return', callee });
+}
+
+function handleVarDeclarator(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  assignments: DataflowAssignment[],
+  isCallNode: (t: string) => boolean,
+): void {
+  const rawName = node.childForFieldName(rules.varNameField);
+  const rawValue = resolveValueNode(node, rawName, rules, isCallNode);
+  const { name: nameNode, value: valueNode } = unwrapExpressionList(rawName, rawValue, rules);
 
   const scope = currentScope(scopeStack);
   if (!nameNode || !valueNode || !scope) return;
 
   const unwrapped = unwrapAwait(valueNode, rules);
   const callExpr = isCall(unwrapped, isCallNode) ? unwrapped : null;
+  if (!callExpr) return;
 
-  if (callExpr) {
-    const callee = resolveCalleeName(callExpr, rules);
-    if (callee && scope.funcName) {
-      if (
-        (rules.objectDestructType && nameNode.type === rules.objectDestructType) ||
-        (rules.arrayDestructType && nameNode.type === rules.arrayDestructType)
-      ) {
-        const names = extractParamNames(nameNode, rules);
-        for (const n of names) {
-          assignments.push({
-            varName: n,
-            callerFunc: scope.funcName,
-            sourceCallName: callee,
-            expression: truncate(node.text),
-            line: node.startPosition.row + 1,
-          });
-          scope.locals.set(n, { type: 'destructured', callee });
-        }
-      } else {
-        const varName =
-          nameNode.type === 'identifier' || nameNode.type === rules.paramIdentifier
-            ? nameNode.text
-            : nameNode.text;
-        assignments.push({
-          varName,
-          callerFunc: scope.funcName,
-          sourceCallName: callee,
-          expression: truncate(node.text),
-          line: node.startPosition.row + 1,
-        });
-        scope.locals.set(varName, { type: 'call_return', callee });
-      }
-    }
+  const callee = resolveCalleeName(callExpr, rules);
+  if (!callee || !scope.funcName) return;
+
+  const isDestructured =
+    (rules.objectDestructType && nameNode.type === rules.objectDestructType) ||
+    (rules.arrayDestructType && nameNode.type === rules.arrayDestructType);
+
+  if (isDestructured) {
+    recordDestructuredAssignment(nameNode, node, callee, scope, assignments, rules);
+  } else {
+    recordSimpleAssignment(nameNode, node, callee, scope, assignments);
   }
 }
 

package/src/cli/commands/branch-compare.ts

@@ -5,6 +5,7 @@ export const command: CommandDefinition = {
   description: 'Compare code structure between two branches/refs',
   options: [
     ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-d, --db <path>', 'Path to graph.db'],
     ['-T, --no-tests', 'Exclude test/spec files'],
     ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
     ['-j, --json', 'Output as JSON'],
@@ -12,12 +13,15 @@ export const command: CommandDefinition = {
   ],
   async execute([base, target], opts, ctx) {
     const { branchCompare } = await import('../../presentation/branch-compare.js');
+    const path = await import('node:path');
+    const repoRoot = opts.db ? path.resolve(path.dirname(opts.db as string), '..') : undefined;
     await branchCompare(base!, target!, {
       engine: ctx.program.opts().engine,
       depth: parseInt(opts.depth as string, 10),
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,
       format: opts.format,
+      repoRoot,
     });
   },
 };

package/src/cli/commands/diff-impact.ts

@@ -13,6 +13,7 @@ export const command: CommandDefinition = {
     ['--ndjson', 'Newline-delimited JSON output'],
     ['--staged', 'Analyze staged changes instead of unstaged'],
     ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-j, --json', 'Output as JSON (shorthand for -f json)'],
     ['-f, --format <format>', 'Output format: text, mermaid, json', 'text'],
     ['--no-implementations', 'Exclude interface/trait implementors from blast radius'],
   ],
@@ -21,7 +22,7 @@ export const command: CommandDefinition = {
       ref,
       staged: opts.staged,
       depth: parseInt(opts.depth as string, 10),
-      format: opts.format,
+      format: opts.json ? 'json' : opts.format,
       includeImplementors: opts.implementations !== false,
       ...ctx.resolveQueryOpts(opts),
     });

package/src/cli/commands/info.ts

@@ -3,7 +3,8 @@ import type { CommandDefinition } from '../types.js';
 export const command: CommandDefinition = {
   name: 'info',
   description: 'Show codegraph engine info and diagnostics',
-  async execute(_args, _opts, ctx) {
+  options: [['-d, --db <path>', 'Path to graph.db']],
+  async execute(_args, opts, ctx) {
     const { getNativePackageVersion, isNativeAvailable, loadNative } = await import(
       '../../infrastructure/native.js'
     );
@@ -40,7 +41,7 @@ export const command: CommandDefinition = {
     try {
       const { findDbPath, getBuildMeta } = await import('../../db/index.js');
       const Database = (await import('better-sqlite3')).default;
-      const dbPath = findDbPath();
+      const dbPath = findDbPath(opts.db as string | undefined);
       const fs = await import('node:fs');
       if (fs.existsSync(dbPath)) {
         const db = new Database(dbPath, { readonly: true });

package/src/cli/commands/watch.ts

@@ -5,9 +5,23 @@ import type { CommandDefinition } from '../types.js';
 export const command: CommandDefinition = {
   name: 'watch [dir]',
   description: 'Watch project for file changes and incrementally update the graph',
-  async execute([dir], _opts, ctx) {
+  options: [
+    ['--poll', 'Use stat-based polling (default on Windows to avoid ReFS/Dev Drive crashes)'],
+    ['--native', 'Force native OS file watchers instead of polling'],
+    ['--poll-interval <ms>', 'Polling interval in milliseconds (default: 2000)'],
+  ],
+  async execute([dir], opts, ctx) {
     const root = path.resolve(dir || '.');
     const engine = ctx.program.opts().engine;
-    await watchProject(root, { engine });
+    if (opts.poll && opts.native) {
+      ctx.program.error('--poll and --native are mutually exclusive');
+    }
+    // Explicit --poll or --native wins; otherwise let watcher auto-detect by platform
+    const poll = opts.poll ? true : opts.native ? false : undefined;
+    await watchProject(root, {
+      engine,
+      poll,
+      pollInterval: opts.pollInterval ? Number(opts.pollInterval) : undefined,
+    });
   },
 };

package/src/db/connection.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { debug, warn } from '../infrastructure/logger.js';
 import { getNative, isNativeAvailable } from '../infrastructure/native.js';
-import { DbError } from '../shared/errors.js';
+import { DbError, toErrorMessage } from '../shared/errors.js';
 import type { BetterSqlite3Database, NativeDatabase } from '../types.js';
 import { getDatabase } from './better-sqlite3.js';
 import { Repository } from './repository/base.js';
@@ -20,7 +20,8 @@ function getPackageVersion(): string {
     const pkgPath = path.join(connDir, '..', '..', 'package.json');
     _packageVersion = (JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version: string })
       .version;
-  } catch {
+  } catch (e) {
+    debug(`Failed to read package version: ${toErrorMessage(e)}`);
     _packageVersion = '';
   }
   return _packageVersion;
@@ -41,8 +42,8 @@ function warnOnVersionMismatch(getBuildVersion: () => string | undefined | null)
         `DB was built with codegraph v${buildVersion}, running v${currentVersion}. Consider: codegraph build --no-incremental`,
       );
     }
-  } catch {
-    // build_meta table may not exist in older DBs — silently ignore
+  } catch (e) {
+    debug(`Version mismatch check skipped (build_meta may not exist): ${toErrorMessage(e)}`);
   }
 }
 
@@ -78,11 +79,11 @@ export function findRepoRoot(fromDir?: string): string | null {
     try {
       root = fs.realpathSync(raw);
     } catch (e) {
-      debug(`realpathSync failed for git root "${raw}", using resolve: ${(e as Error).message}`);
+      debug(`realpathSync failed for git root "${raw}", using resolve: ${toErrorMessage(e)}`);
       root = path.resolve(raw);
     }
   } catch (e) {
-    debug(`git rev-parse failed for "${dir}": ${(e as Error).message}`);
+    debug(`git rev-parse failed for "${dir}": ${toErrorMessage(e)}`);
     root = null;
   }
   if (!fromDir) {
@@ -103,7 +104,7 @@ function isProcessAlive(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (e) {
-    debug(`PID ${pid} not alive: ${(e as NodeJS.ErrnoException).code || (e as Error).message}`);
+    debug(`PID ${pid} not alive: ${(e as NodeJS.ErrnoException).code || toErrorMessage(e)}`);
     return false;
   }
 }
@@ -119,12 +120,12 @@ function acquireAdvisoryLock(dbPath: string): void {
       }
     }
   } catch (e) {
-    debug(`Advisory lock read failed: ${(e as Error).message}`);
+    debug(`Advisory lock read failed: ${toErrorMessage(e)}`);
   }
   try {
     fs.writeFileSync(lockPath, String(process.pid), 'utf-8');
   } catch (e) {
-    debug(`Advisory lock write failed: ${(e as Error).message}`);
+    debug(`Advisory lock write failed: ${toErrorMessage(e)}`);
   }
 }
 
@@ -135,7 +136,7 @@ function releaseAdvisoryLock(lockPath: string): void {
       fs.unlinkSync(lockPath);
     }
   } catch (e) {
-    debug(`Advisory lock release failed for ${lockPath}: ${(e as Error).message}`);
+    debug(`Advisory lock release failed for ${lockPath}: ${toErrorMessage(e)}`);
   }
 }
 
@@ -151,7 +152,7 @@ function isSameDirectory(a: string, b: string): boolean {
     const sb = fs.statSync(b);
     return sa.dev === sb.dev && sa.ino === sb.ino;
   } catch (e) {
-    debug(`isSameDirectory stat failed: ${(e as Error).message}`);
+    debug(`isSameDirectory stat failed: ${toErrorMessage(e)}`);
     return false;
   }
 }
@@ -187,8 +188,8 @@ export function flushDeferredClose(): void {
     const db = _deferredDbs.pop()!;
     try {
       db.close();
-    } catch {
-      /* ignore — handle may already be closed */
+    } catch (e) {
+      debug(`Deferred DB close failed (handle may already be closed): ${toErrorMessage(e)}`);
     }
   }
 }
@@ -216,8 +217,8 @@ export function closeDbDeferred(db: LockedDatabase): void {
       _deferredDbs.splice(idx, 1);
       try {
         db.close();
-      } catch {
-        /* ignore — handle may already be closed by flush */
+      } catch (e) {
+        debug(`Deferred DB close failed (may already be closed by flush): ${toErrorMessage(e)}`);
       }
     }
   });
@@ -239,8 +240,8 @@ export function closeDbPair(pair: LockedDatabasePair): void {
   if (pair.nativeDb) {
     try {
       pair.nativeDb.close();
-    } catch {
-      /* ignore */
+    } catch (e) {
+      debug(`closeDbPair: native close failed: ${toErrorMessage(e)}`);
     }
   }
   closeDb(pair.db);
@@ -251,8 +252,8 @@ export function closeDbPairDeferred(pair: LockedDatabasePair): void {
   if (pair.nativeDb) {
     try {
       pair.nativeDb.close();
-    } catch {
-      /* ignore */
+    } catch (e) {
+      debug(`closeDbPairDeferred: native close failed: ${toErrorMessage(e)}`);
     }
   }
   closeDbDeferred(pair.db);
@@ -270,7 +271,7 @@ export function findDbPath(customPath?: string): string {
     try {
       ceiling = fs.realpathSync(rawCeiling);
     } catch (e) {
-      debug(`realpathSync failed for ceiling "${rawCeiling}": ${(e as Error).message}`);
+      debug(`realpathSync failed for ceiling "${rawCeiling}": ${toErrorMessage(e)}`);
       ceiling = rawCeiling;
     }
   } else {
@@ -281,7 +282,7 @@ export function findDbPath(customPath?: string): string {
   try {
     dir = fs.realpathSync(process.cwd());
   } catch (e) {
-    debug(`realpathSync failed for cwd: ${(e as Error).message}`);
+    debug(`realpathSync failed for cwd: ${toErrorMessage(e)}`);
     dir = process.cwd();
   }
   while (true) {
@@ -334,9 +335,11 @@ function openRepoNative(customDbPath?: string): { repo: Repository; close(): voi
   const ndb = native.NativeDatabase.openReadonly(dbPath);
   try {
     warnOnVersionMismatch(() => ndb.getBuildMeta('codegraph_version'));
+    const repo = new NativeRepository(ndb, dbPath);
     return {
-      repo: new NativeRepository(ndb),
+      repo,
       close() {
+        repo.closeFallback();
         ndb.close();
       },
     };
@@ -375,9 +378,7 @@ export function openRepo(
       // Re-throw user-visible errors (e.g. DB not found) — only silently
       // fall back for native-engine failures (e.g. incompatible native binary).
       if (e instanceof DbError) throw e;
-      debug(
-        `openRepo: native path failed, falling back to better-sqlite3: ${(e as Error).message}`,
-      );
+      debug(`openRepo: native path failed, falling back to better-sqlite3: ${toErrorMessage(e)}`);
     }
   }
 
@@ -411,7 +412,7 @@ export function openReadonlyWithNative(customPath?: string): {
       const native = getNative();
       nativeDb = native.NativeDatabase.openReadonly(dbPath);
     } catch (e) {
-      debug(`openReadonlyWithNative: native path failed: ${(e as Error).message}`);
+      debug(`openReadonlyWithNative: native path failed: ${toErrorMessage(e)}`);
     }
   }
 
@@ -423,8 +424,8 @@ export function openReadonlyWithNative(customPath?: string): {
       if (nativeDb) {
         try {
           nativeDb.close();
-        } catch {
-          // already closed or not closeable
+        } catch (e) {
+          debug(`openReadonlyWithNative: native close failed: ${toErrorMessage(e)}`);
         }
       }
     },

package/src/db/query-builder.ts

@@ -33,14 +33,26 @@ function validateOrderBy(clause: string): void {
   }
 }
 
+/**
+ * Track parenthesis depth change for a character.
+ * Returns non-zero only for '(' / ')'; a character that is '(' or ')'
+ * can never simultaneously be ',' so the comma check in the caller
+ * remains mutually exclusive with the depth update.
+ */
+function parenDepthDelta(ch: string): number {
+  if (ch === '(') return 1;
+  if (ch === ')') return -1;
+  return 0;
+}
+
 function splitTopLevelCommas(str: string): string[] {
   const parts: string[] = [];
   let depth = 0;
   let start = 0;
   for (let i = 0; i < str.length; i++) {
-    if (str[i] === '(') depth++;
-    else if (str[i] === ')') depth--;
-    else if (str[i] === ',' && depth === 0) {
+    const ch = str[i]!;
+    depth += parenDepthDelta(ch);
+    if (ch === ',' && depth === 0) {
       parts.push(str.slice(start, i).trim());
       start = i + 1;
     }

package/src/db/repository/base.ts

@@ -100,6 +100,20 @@ export class Repository implements IRepository {
     throw new Error('not implemented');
   }
 
+  /**
+   * Batch version of findCallers — returns callers for multiple node IDs in a
+   * single query. Default implementation loops; subclasses override with SQL
+   * `IN (...)` for efficiency.
+   */
+  findCallersBatch(nodeIds: number[]): Map<number, RelatedNodeRow[]> {
+    const result = new Map<number, RelatedNodeRow[]>();
+    for (const id of nodeIds) {
+      const callers = this.findCallers(id);
+      if (callers.length > 0) result.set(id, callers);
+    }
+    return result;
+  }
+
   findDistinctCallers(_nodeId: number): RelatedNodeRow[] {
     throw new Error('not implemented');
   }
@@ -189,4 +203,24 @@ export class Repository implements IRepository {
   getComplexityForNode(_nodeId: number): ComplexityMetrics | undefined {
     throw new Error('not implemented');
   }
+
+  // ── Convenience queries ──────────────────────────────────────────────
+  /**
+   * Look up the stored content hash for a file.
+   * Returns null when the file is not in file_hashes or the method is
+   * not yet implemented on the concrete repository.
+   */
+  getFileHash(_file: string): string | null {
+    return null;
+  }
+
+  /** Check whether the graph contains any 'implements' edges. */
+  hasImplementsEdges(): boolean {
+    return false;
+  }
+
+  /** Check whether the co_changes table exists and has data. */
+  hasCoChangesTable(): boolean {
+    return false;
+  }
 }

package/src/db/repository/native-repository.ts

@@ -8,9 +8,11 @@
  * back to the snake_case field names that the Repository interface expects.
  */
 
+import Database from 'better-sqlite3';
 import { ConfigError } from '../../shared/errors.js';
 import type {
   AdjacentEdgeRow,
+  BetterSqlite3Database,
   CallableNodeRow,
   CallEdgeRow,
   ChildNodeRow,
@@ -159,10 +161,33 @@ function toComplexityMetrics(r: NativeComplexityMetrics): ComplexityMetrics {
 
 export class NativeRepository extends Repository {
   #ndb: NativeDatabase;
+  #dbPath?: string;
+  #fallbackDb?: BetterSqlite3Database;
 
-  constructor(ndb: NativeDatabase) {
+  constructor(ndb: NativeDatabase, dbPath?: string) {
     super();
     this.#ndb = ndb;
+    this.#dbPath = dbPath;
+  }
+
+  /** Lazy better-sqlite3 handle for methods not yet ported to Rust. */
+  #getFallbackDb(): BetterSqlite3Database | undefined {
+    if (this.#fallbackDb) return this.#fallbackDb;
+    if (!this.#dbPath) return undefined;
+    try {
+      this.#fallbackDb = new Database(this.#dbPath, { readonly: true });
+      return this.#fallbackDb;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Close the lazy fallback connection if it was opened. */
+  closeFallback(): void {
+    if (this.#fallbackDb) {
+      this.#fallbackDb.close();
+      this.#fallbackDb = undefined;
+    }
   }
 
   // ── Node lookups ──────────────────────────────────────────────────
@@ -266,6 +291,31 @@ export class NativeRepository extends Repository {
     return this.#ndb.findCallers(nodeId).map(toRelatedNodeRow);
   }
 
+  findCallersBatch(nodeIds: number[]): Map<number, RelatedNodeRow[]> {
+    if (nodeIds.length === 0) return new Map();
+    const placeholders = nodeIds.map(() => '?').join(',');
+    const rows = this.#ndb.queryAll(
+      `SELECT e.target_id AS queried_id, n.id, n.name, n.kind, n.file, n.line, n.end_line
+       FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id IN (${placeholders}) AND e.kind = 'calls'`,
+      nodeIds,
+    ) as Array<Record<string, unknown>>;
+    const result = new Map<number, RelatedNodeRow[]>();
+    for (const row of rows) {
+      const qid = row.queried_id as number;
+      if (!result.has(qid)) result.set(qid, []);
+      result.get(qid)!.push({
+        id: row.id as number,
+        name: row.name as string,
+        kind: row.kind as string,
+        file: row.file as string,
+        line: row.line as number,
+        end_line: (row.end_line as number | null) ?? null,
+      });
+    }
+    return result;
+  }
+
   findDistinctCallers(nodeId: number): RelatedNodeRow[] {
     return this.#ndb.findDistinctCallers(nodeId).map(toRelatedNodeRow);
   }
@@ -358,4 +408,57 @@ export class NativeRepository extends Repository {
     const r = this.#ndb.getComplexityForNode(nodeId);
     return r ? toComplexityMetrics(r) : undefined;
   }
+
+  // ── Convenience queries ────────────────────────────────────────────
+
+  getFileHash(file: string): string | null {
+    if (typeof this.#ndb.getFileHash === 'function') return this.#ndb.getFileHash(file);
+    // Fallback to better-sqlite3 until Rust implements getFileHash
+    const db = this.#getFallbackDb();
+    if (db) {
+      const row = db.prepare('SELECT hash FROM file_hashes WHERE file = ?').get(file) as
+        | { hash: string }
+        | undefined;
+      return row?.hash ?? null;
+    }
+    return null;
+  }
+
+  #implementsEdgesCache?: boolean;
+  hasImplementsEdges(): boolean {
+    if (this.#implementsEdgesCache !== undefined) return this.#implementsEdgesCache;
+    if (typeof this.#ndb.hasImplementsEdges === 'function') {
+      this.#implementsEdgesCache = this.#ndb.hasImplementsEdges();
+      return this.#implementsEdgesCache;
+    }
+    // Fallback to better-sqlite3
+    const db = this.#getFallbackDb();
+    if (db) {
+      this.#implementsEdgesCache = !!db
+        .prepare("SELECT 1 FROM edges WHERE kind = 'implements' LIMIT 1")
+        .get();
+      return this.#implementsEdgesCache;
+    }
+    return true; // conservative: assume yes when no fallback available
+  }
+
+  #coChangesTableCache?: boolean;
+  hasCoChangesTable(): boolean {
+    if (this.#coChangesTableCache !== undefined) return this.#coChangesTableCache;
+    if (typeof this.#ndb.hasCoChangesTable === 'function') {
+      this.#coChangesTableCache = this.#ndb.hasCoChangesTable();
+      return this.#coChangesTableCache;
+    }
+    // Fallback to better-sqlite3
+    const db = this.#getFallbackDb();
+    if (db) {
+      try {
+        this.#coChangesTableCache = !!db.prepare('SELECT 1 FROM co_changes LIMIT 1').get();
+      } catch {
+        this.#coChangesTableCache = false;
+      }
+      return this.#coChangesTableCache;
+    }
+    return false;
+  }
 }

package/src/db/repository/nodes.ts

@@ -42,14 +42,8 @@ export function findNodesWithFanIn(
   return q.all(db, nativeDb);
 }
 
-/**
- * Fetch nodes for triage scoring: fan-in + complexity + churn.
- */
-export function findNodesForTriage(
-  db: BetterSqlite3Database,
-  opts: TriageQueryOpts = {},
-  nativeDb?: NativeDatabase,
-): TriageNodeRow[] {
+/** Validate kind and role options, throwing on invalid values. */
+function validateTriageOpts(opts: TriageQueryOpts): void {
   if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
     throw new ConfigError(
       `Invalid kind: ${opts.kind} (expected one of ${EVERY_SYMBOL_KIND.join(', ')})`,
@@ -58,6 +52,17 @@ export function findNodesForTriage(
   if (opts.role && !VALID_ROLES.includes(opts.role)) {
     throw new ConfigError(`Invalid role: ${opts.role} (expected one of ${VALID_ROLES.join(', ')})`);
   }
+}
+
+/**
+ * Fetch nodes for triage scoring: fan-in + complexity + churn.
+ */
+export function findNodesForTriage(
+  db: BetterSqlite3Database,
+  opts: TriageQueryOpts = {},
+  nativeDb?: NativeDatabase,
+): TriageNodeRow[] {
+  validateTriageOpts(opts);
 
   const kindsToUse = opts.kind ? [opts.kind] : ['function', 'method', 'class'];
   const q = new NodeQuery()