@optave/codegraph 3.8.1 → 3.9.1

package/src/ast-analysis/engine.ts

@@ -215,25 +215,37 @@ function runNativeAnalysis(
   }
 }
 
+/** Index native results by line number and match to a definition by name. */
+function indexNativeByLine<T extends { line: number; name: string }>(
+  results: T[],
+): Map<number, T[]> {
+  const byLine = new Map<number, T[]>();
+  for (const r of results) {
+    if (!byLine.has(r.line)) byLine.set(r.line, []);
+    byLine.get(r.line)!.push(r);
+  }
+  return byLine;
+}
+
+function matchNativeResult<T extends { name: string }>(
+  candidates: T[] | undefined,
+  defName: string,
+): T | undefined {
+  if (!candidates) return undefined;
+  if (candidates.length === 1) return candidates[0];
+  return candidates.find((r) => r.name === defName) ?? candidates[0];
+}
+
 /** Store native complexity results on definitions, matched by line number. */
 function storeNativeComplexityResults(
   results: NativeFunctionComplexityResult[],
   defs: Definition[],
 ): void {
-  const byLine = new Map<number, NativeFunctionComplexityResult[]>();
-  for (const r of results) {
-    if (!byLine.has(r.line)) byLine.set(r.line, []);
-    byLine.get(r.line)!.push(r);
-  }
+  const byLine = indexNativeByLine(results);
 
   for (const def of defs) {
     if ((def.kind === 'function' || def.kind === 'method') && def.line && !def.complexity) {
-      const candidates = byLine.get(def.line);
-      if (!candidates) continue;
-      const match =
-        candidates.length === 1
-          ? candidates[0]
-          : (candidates.find((r) => r.name === def.name) ?? candidates[0]);
+      const match = matchNativeResult(byLine.get(def.line), def.name);
       if (!match) continue;
       const { complexity: c } = match;
       def.complexity = {
@@ -242,6 +254,12 @@ function storeNativeComplexityResults(
         maxNesting: c.maxNesting,
         halstead: c.halstead
           ? {
+              n1: c.halstead.n1,
+              n2: c.halstead.n2,
+              bigN1: c.halstead.bigN1,
+              bigN2: c.halstead.bigN2,
+              vocabulary: c.halstead.vocabulary,
+              length: c.halstead.length,
               volume: c.halstead.volume,
               difficulty: c.halstead.difficulty,
               effort: c.halstead.effort,
@@ -278,11 +296,7 @@ function overrideCyclomaticFromCfg(def: Definition, cfgCyclomatic: number): void
 
 /** Store native CFG results on definitions, matched by line number. */
 function storeNativeCfgResults(results: NativeFunctionCfgResult[], defs: Definition[]): void {
-  const byLine = new Map<number, NativeFunctionCfgResult[]>();
-  for (const r of results) {
-    if (!byLine.has(r.line)) byLine.set(r.line, []);
-    byLine.get(r.line)!.push(r);
-  }
+  const byLine = indexNativeByLine(results);
 
   for (const def of defs) {
     if (
@@ -291,12 +305,7 @@ function storeNativeCfgResults(results: NativeFunctionCfgResult[], defs: Definit
       def.cfg !== null &&
       !def.cfg?.blocks?.length
     ) {
-      const candidates = byLine.get(def.line);
-      if (!candidates) continue;
-      const match =
-        candidates.length === 1
-          ? candidates[0]
-          : (candidates.find((r) => r.name === def.name) ?? candidates[0]);
+      const match = matchNativeResult(byLine.get(def.line), def.name);
       if (!match) continue;
       def.cfg = match.cfg;
 
@@ -309,44 +318,99 @@ function storeNativeCfgResults(results: NativeFunctionCfgResult[], defs: Definit
   }
 }
 
+// ─── CFG cyclomatic reconciliation ──────────────────────────────────────
+
+/**
+ * Apply CFG-derived cyclomatic override for definitions that already have both
+ * `complexity` and `cfg` with blocks/edges but whose cyclomatic was never
+ * overridden (e.g., native extractors provide both fields inline, so the
+ * normal override path in storeNativeCfgResults / storeCfgResults is skipped).
+ */
+/** Type guard for cfg objects with blocks and edges arrays. */
+function hasCfgBlocksAndEdges(cfg: unknown): cfg is { blocks: unknown[]; edges: unknown[] } {
+  return (
+    cfg != null &&
+    typeof cfg === 'object' &&
+    Array.isArray((cfg as { blocks?: unknown }).blocks) &&
+    Array.isArray((cfg as { edges?: unknown }).edges)
+  );
+}
+
+function reconcileCfgCyclomatic(fileSymbols: Map<string, ExtractorOutput>): void {
+  for (const [, symbols] of fileSymbols) {
+    const defs = symbols.definitions || [];
+    for (const def of defs) {
+      if (
+        (def.kind === 'function' || def.kind === 'method') &&
+        def.complexity &&
+        hasCfgBlocksAndEdges(def.cfg)
+      ) {
+        const cfgCyclomatic = Math.max(def.cfg.edges.length - def.cfg.blocks.length + 2, 1);
+        if (cfgCyclomatic !== def.complexity.cyclomatic) {
+          overrideCyclomaticFromCfg(def, cfgCyclomatic);
+        }
+      }
+    }
+  }
+}
+
 // ─── WASM pre-parse ─────────────────────────────────────────────────────
 
+/** Check whether a single file needs a WASM tree for any enabled analysis pass. */
+function fileNeedsWasmTree(
+  relPath: string,
+  symbols: ExtractorOutput,
+  flags: { doAst: boolean; doComplexity: boolean; doCfg: boolean; doDataflow: boolean },
+): boolean {
+  if (symbols._tree) return false;
+  const ext = path.extname(relPath).toLowerCase();
+  const defs = symbols.definitions || [];
+  const lid = symbols._langId || '';
+
+  if (
+    flags.doAst &&
+    !Array.isArray(symbols.astNodes) &&
+    (WALK_EXTENSIONS.has(ext) || AST_TYPE_MAPS.has(lid))
+  )
+    return true;
+  if (
+    flags.doComplexity &&
+    (COMPLEXITY_EXTENSIONS.has(ext) || COMPLEXITY_RULES.has(lid)) &&
+    defs.some((d) => hasFuncBody(d) && !d.complexity)
+  )
+    return true;
+  if (
+    flags.doCfg &&
+    (CFG_EXTENSIONS.has(ext) || CFG_RULES.has(lid)) &&
+    defs.some((d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks))
+  )
+    return true;
+  if (
+    flags.doDataflow &&
+    !symbols.dataflow &&
+    (DATAFLOW_EXTENSIONS.has(ext) || DATAFLOW_RULES.has(lid))
+  )
+    return true;
+  return false;
+}
+
 async function ensureWasmTreesIfNeeded(
   fileSymbols: Map<string, ExtractorOutput>,
   opts: AnalysisOpts,
   rootDir: string,
 ): Promise<void> {
-  const doAst = opts.ast !== false;
-  const doComplexity = opts.complexity !== false;
-  const doCfg = opts.cfg !== false;
-  const doDataflow = opts.dataflow !== false;
+  const flags = {
+    doAst: opts.ast !== false,
+    doComplexity: opts.complexity !== false,
+    doCfg: opts.cfg !== false,
+    doDataflow: opts.dataflow !== false,
+  };
 
-  if (!doAst && !doComplexity && !doCfg && !doDataflow) return;
+  if (!flags.doAst && !flags.doComplexity && !flags.doCfg && !flags.doDataflow) return;
 
   let needsWasmTrees = false;
   for (const [relPath, symbols] of fileSymbols) {
-    if (symbols._tree) continue;
-    const ext = path.extname(relPath).toLowerCase();
-    const defs = symbols.definitions || [];
-
-    // AST: need tree when native didn't provide non-call astNodes
-    const lid = symbols._langId || '';
-    const needsAst =
-      doAst &&
-      !Array.isArray(symbols.astNodes) &&
-      (WALK_EXTENSIONS.has(ext) || AST_TYPE_MAPS.has(lid));
-    const needsComplexity =
-      doComplexity &&
-      (COMPLEXITY_EXTENSIONS.has(ext) || COMPLEXITY_RULES.has(lid)) &&
-      defs.some((d) => hasFuncBody(d) && !d.complexity);
-    const needsCfg =
-      doCfg &&
-      (CFG_EXTENSIONS.has(ext) || CFG_RULES.has(lid)) &&
-      defs.some((d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks));
-    const needsDataflow =
-      doDataflow && !symbols.dataflow && (DATAFLOW_EXTENSIONS.has(ext) || DATAFLOW_RULES.has(lid));
-
-    if (needsAst || needsComplexity || needsCfg || needsDataflow) {
+    if (fileNeedsWasmTree(relPath, symbols, flags)) {
       needsWasmTrees = true;
       break;
     }
@@ -565,7 +629,7 @@ async function delegateToBuildFunctions(
     } catch (err: unknown) {
       debug(`buildAstNodes failed: ${toErrorMessage(err)}`);
     }
-    timing.astMs = performance.now() - t0;
+    timing.astMs += performance.now() - t0;
   }
 
   if (opts.complexity !== false) {
@@ -576,7 +640,7 @@ async function delegateToBuildFunctions(
     } catch (err: unknown) {
       debug(`buildComplexityMetrics failed: ${toErrorMessage(err)}`);
     }
-    timing.complexityMs = performance.now() - t0;
+    timing.complexityMs += performance.now() - t0;
   }
 
   if (opts.cfg !== false) {
@@ -587,7 +651,7 @@ async function delegateToBuildFunctions(
     } catch (err: unknown) {
       debug(`buildCFGData failed: ${toErrorMessage(err)}`);
     }
-    timing.cfgMs = performance.now() - t0;
+    timing.cfgMs += performance.now() - t0;
   }
 
   if (opts.dataflow !== false) {
@@ -598,7 +662,7 @@ async function delegateToBuildFunctions(
     } catch (err: unknown) {
       debug(`buildDataflowEdges failed: ${toErrorMessage(err)}`);
     }
-    timing.dataflowMs = performance.now() - t0;
+    timing.dataflowMs += performance.now() - t0;
   }
 }
 
@@ -626,7 +690,7 @@ export async function runAnalyses(
   // This fills in complexity/CFG/dataflow for files that the native parse pipeline
   // missed, avoiding the need to parse with WASM + run JS visitors.
   const native = loadNative();
-  if (native?.analyzeComplexity ?? native?.buildCfgAnalysis ?? native?.extractDataflowAnalysis) {
+  if (native?.analyzeComplexity || native?.buildCfgAnalysis || native?.extractDataflowAnalysis) {
     const t0native = performance.now();
     runNativeAnalysis(native, fileSymbols, rootDir, opts, extToLang);
     debug(`native standalone analysis: ${(performance.now() - t0native).toFixed(1)}ms`);
@@ -635,7 +699,10 @@ export async function runAnalyses(
   // WASM pre-parse for files that still need it (AST store, or native gaps)
   await ensureWasmTreesIfNeeded(fileSymbols, opts, rootDir);
 
-  // Unified pre-walk: run all applicable visitors in a single DFS per file
+  // Unified pre-walk: run all applicable visitors in a single DFS per file.
+  // Time each file's walk and distribute equally among active visitors
+  // so that phase timers (astMs, complexityMs, etc.) reflect real work — not
+  // just the DB-write tail in delegateToBuildFunctions.
   const t0walk = performance.now();
 
   for (const [relPath, symbols] of fileSymbols) {
@@ -650,7 +717,22 @@ export async function runAnalyses(
 
     if (visitors.length === 0) continue;
 
+    const walkStart = performance.now();
     const results = walkWithVisitors(symbols._tree.rootNode, visitors, langId, walkerOpts);
+    const walkMs = performance.now() - walkStart;
+
+    // Distribute walk time equally among active visitors
+    const activeCount = [astVisitor, complexityVisitor, cfgVisitor, dataflowVisitor].filter(
+      Boolean,
+    ).length;
+    if (activeCount > 0) {
+      const share = walkMs / activeCount;
+      if (astVisitor) timing.astMs += share;
+      if (complexityVisitor) timing.complexityMs += share;
+      if (cfgVisitor) timing.cfgMs += share;
+      if (dataflowVisitor) timing.dataflowMs += share;
+    }
+
     const defs = symbols.definitions || [];
 
     if (astVisitor) {
@@ -663,8 +745,21 @@ export async function runAnalyses(
     if (dataflowVisitor) symbols.dataflow = results.dataflow as DataflowResult;
   }
 
+  // Total wall-clock time for the unified walk loop, including per-file
+  // setupVisitors overhead. Walk time is already distributed into per-phase
+  // timers above, so this field overlaps with (astMs + complexityMs + ...).
+  // It is kept as a diagnostic cross-check, not an additive bucket.
   timing._unifiedWalkMs = performance.now() - t0walk;
 
+  // Reconcile: apply CFG-derived cyclomatic override for any definitions that have
+  // both precomputed complexity and CFG data but whose cyclomatic was never overridden.
+  // This closes a parity gap where native extractors provide both fields inline but
+  // the override step (storeNativeCfgResults / storeCfgResults) is skipped because
+  // detectNativeNeeds sees both as already present.
+  if (doComplexity && doCfg) {
+    reconcileCfgCyclomatic(fileSymbols);
+  }
+
   // Delegate to buildXxx functions for DB writes + native fallback
   await delegateToBuildFunctions(db, fileSymbols, rootDir, opts, engineOpts, timing);
 

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

@@ -102,27 +102,25 @@ export function createAstStoreVisitor(
     return nodeIdMap.get(`${parentDef.name}|${parentDef.kind}|${parentDef.line}`) || null;
   }
 
-  function resolveNameAndText(
-    node: TreeSitterNode,
-    kind: string,
-  ): { name: string | null | undefined; text: string | null; skip?: boolean } {
-    switch (kind) {
-      case 'new':
-        return { name: extractNewName(node), text: truncate(node.text) };
-      case 'throw':
-        return { name: extractThrowName(node), text: extractExpressionText(node) };
-      case 'await':
-        return { name: extractAwaitName(node), text: extractExpressionText(node) };
-      case 'string': {
-        const content = node.text?.replace(/^['"`]|['"`]$/g, '') || '';
-        if (content.length < 2) return { name: null, text: null, skip: true };
-        return { name: truncate(content, 100), text: truncate(node.text) };
-      }
-      case 'regex':
-        return { name: node.text || '?', text: truncate(node.text) };
-      default:
-        return { name: undefined, text: null };
-    }
+  type NameTextResult = { name: string | null | undefined; text: string | null; skip?: boolean };
+  type KindHandler = (node: TreeSitterNode) => NameTextResult;
+
+  const kindHandlers: Record<string, KindHandler> = {
+    new: (node) => ({ name: extractNewName(node), text: truncate(node.text) }),
+    throw: (node) => ({ name: extractThrowName(node), text: extractExpressionText(node) }),
+    await: (node) => ({ name: extractAwaitName(node), text: extractExpressionText(node) }),
+    string: (node) => {
+      const content = node.text?.replace(/^['"`]|['"`]$/g, '') || '';
+      if (content.length < 2) return { name: null, text: null, skip: true };
+      return { name: truncate(content, 100), text: truncate(node.text) };
+    },
+    regex: (node) => ({ name: node.text || '?', text: truncate(node.text) }),
+  };
+  const defaultResult: NameTextResult = { name: undefined, text: null };
+
+  function resolveNameAndText(node: TreeSitterNode, kind: string): NameTextResult {
+    const handler = kindHandlers[kind];
+    return handler ? handler(node) : defaultResult;
   }
 
   function collectNode(node: TreeSitterNode, kind: string): void {

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

@@ -40,6 +40,32 @@ function classifyHalstead(node: TreeSitterNode, hRules: AnyRules, acc: Complexit
   }
 }
 
+/**
+ * Detect whether a branch node is an else-if that the DFS walk would NOT
+ * increment nesting for.  Returns true for:
+ *  - Pattern A (JS/C#/Rust): if_statement whose parent is else_clause
+ *  - Pattern C (Go/Java): if_statement that is the alternative of parent if
+ *
+ * Pattern B (Python elif_clause) is not an issue because elif_clause is
+ * never in nestingNodes.
+ */
+function isElseIfNonNesting(node: TreeSitterNode, type: string, cRules: AnyRules): boolean {
+  if (type !== cRules.ifNodeType) return false;
+
+  if (cRules.elseViaAlternative) {
+    // Pattern C
+    return (
+      node.parent?.type === cRules.ifNodeType &&
+      node.parent?.childForFieldName('alternative')?.id === node.id
+    );
+  }
+  if (cRules.elseNodeType) {
+    // Pattern A
+    return node.parent?.type === cRules.elseNodeType;
+  }
+  return false;
+}
+
 function classifyBranchNode(
   node: TreeSitterNode,
   type: string,
@@ -190,6 +216,13 @@ export function createComplexityVisitor(
   let funcDepth = 0;
   const results: PerFunctionResult[] = [];
 
+  // The walker increments context.nestingLevel for ALL nodes in nestingNodeTypes
+  // (including if_statement). But the DFS engine does NOT increment nesting for
+  // else-if if_statement nodes. Track a correction counter so children of else-if
+  // nodes see the correct (non-inflated) nesting level.
+  let nestingAdjust = 0;
+  const adjustNodeIds = new Set<number>();
+
   return {
     name: 'complexity',
     functionNodeTypes: cRules.functionNodes,
@@ -204,6 +237,8 @@ export function createComplexityVisitor(
         activeFuncNode = funcNode;
         activeFuncName = funcName;
         funcDepth = 0;
+        nestingAdjust = 0;
+        adjustNodeIds.clear();
       } else {
         funcDepth++;
       }
@@ -230,11 +265,30 @@ export function createComplexityVisitor(
     enterNode(node: TreeSitterNode, context: VisitorContext): EnterNodeResult | undefined {
       if (fileLevelWalk && !activeFuncNode) return;
 
-      const nestingLevel = fileLevelWalk ? context.nestingLevel + funcDepth : context.nestingLevel;
+      // In file-level mode, funcDepth starts at 0 for the active function.
+      // In function-level mode, funcDepth starts at 1 for the root function
+      // (since enterFunction always increments it). Nested functions add +1
+      // each level — subtract 1 so the root function contributes 0 nesting
+      // and each nested level adds +1, matching the Rust engine's behavior.
+      const funcNesting = fileLevelWalk ? funcDepth : Math.max(0, funcDepth - 1);
+      const nestingLevel = context.nestingLevel + funcNesting - nestingAdjust;
       classifyNode(node, nestingLevel, cRules, hRules, acc);
+
+      // If this is an else-if if_statement that the walker will treat as a
+      // nesting node (incrementing context.nestingLevel for children), but
+      // the DFS walk would NOT increment nesting for, compensate by bumping
+      // nestingAdjust so children see the correct level.
+      if (cRules.nestingNodes.has(node.type) && isElseIfNonNesting(node, node.type, cRules)) {
+        nestingAdjust++;
+        adjustNodeIds.add(node.id);
+      }
     },
 
     exitNode(node: TreeSitterNode): void {
+      if (adjustNodeIds.has(node.id)) {
+        nestingAdjust--;
+        adjustNodeIds.delete(node.id);
+      }
       if (hRules?.skipTypes.has(node.type)) acc.halsteadSkipDepth--;
     },
 

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/db/connection.ts

@@ -311,6 +311,7 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
   }
   const Database = getDatabase();
   const db = new Database(dbPath, { readonly: true }) as unknown as BetterSqlite3Database;
+  db.pragma('busy_timeout = 5000');
 
   warnOnVersionMismatch(() => {
     const row = db
@@ -359,7 +360,7 @@ function openRepoNative(customDbPath?: string): { repo: Repository; close(): voi
  */
 export function openRepo(
   customDbPath?: string,
-  opts: { repo?: Repository } = {},
+  opts: { repo?: Repository; engine?: 'native' | 'wasm' | 'auto' } = {},
 ): { repo: Repository; close(): void } {
   if (opts.repo != null) {
     if (!(opts.repo instanceof Repository)) {
@@ -370,15 +371,25 @@ export function openRepo(
     return { repo: opts.repo, close() {} };
   }
 
+  // Respect explicit engine selection: opts.engine > CODEGRAPH_ENGINE env > auto.
+  // This ensures --engine wasm and benchmark workers bypass the native path.
+  const engine = opts.engine || process.env.CODEGRAPH_ENGINE || 'auto';
+
   // Try native rusqlite path first (Phase 6.14)
-  if (isNativeAvailable()) {
+  if (engine !== 'wasm' && isNativeAvailable()) {
     try {
       return openRepoNative(customDbPath);
     } catch (e) {
       // 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: ${toErrorMessage(e)}`);
+      // Re-throw locking/busy errors — falling back to better-sqlite3 would
+      // hit the same contention (and potentially hang without busy_timeout).
+      const msg = toErrorMessage(e);
+      if (/\b(busy|locked|SQLITE_BUSY|SQLITE_LOCKED)\b/i.test(msg)) {
+        throw new DbError(`Database is busy (another process may be writing): ${msg}`, {});
+      }
+      debug(`openRepo: native path failed, falling back to better-sqlite3: ${msg}`);
     }
   }
 
@@ -405,14 +416,22 @@ export function openReadonlyWithNative(customPath?: string): {
 } {
   const db = openReadonlyOrFail(customPath);
 
+  // Respect explicit engine selection, consistent with openRepo().
+  const engine = process.env.CODEGRAPH_ENGINE || 'auto';
+
   let nativeDb: NativeDatabase | undefined;
-  if (isNativeAvailable()) {
+  if (engine !== 'wasm' && isNativeAvailable()) {
     try {
       const dbPath = findDbPath(customPath);
       const native = getNative();
       nativeDb = native.NativeDatabase.openReadonly(dbPath);
     } catch (e) {
-      debug(`openReadonlyWithNative: native path failed: ${toErrorMessage(e)}`);
+      const msg = toErrorMessage(e);
+      if (/\b(busy|locked|SQLITE_BUSY|SQLITE_LOCKED)\b/i.test(msg)) {
+        debug(`openReadonlyWithNative: native path busy, skipping native DB: ${msg}`);
+      } else {
+        debug(`openReadonlyWithNative: native path failed: ${msg}`);
+      }
     }
   }
 

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');
   }
@@ -209,4 +223,47 @@ export class Repository implements IRepository {
   hasCoChangesTable(): boolean {
     return false;
   }
+
+  // ── Composite queries ──────────────────────────────────────────────
+  /**
+   * Complete fnDeps query in a single call. Returns null when not natively
+   * supported — callers should fall back to the JS-orchestrated path.
+   */
+  fnDeps(
+    _name: string,
+    _opts?: { depth?: number; noTests?: boolean; file?: string; kind?: string },
+  ): FnDepsResult | null {
+    return null;
+  }
+}
+
+// ── Composite query result types ────────────────────────────────────────
+
+export interface FnDepsNode {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+}
+
+export interface FnDepsCallerNode extends FnDepsNode {
+  viaHierarchy?: string;
+}
+
+export interface FnDepsEntry {
+  name: string;
+  kind: string;
+  file: string;
+  line: number | null;
+  endLine: number | null;
+  role: string | null;
+  fileHash: string | null;
+  callees: FnDepsNode[];
+  callers: FnDepsCallerNode[];
+  transitiveCallers: Record<number, FnDepsNode[]>;
+}
+
+export interface FnDepsResult {
+  name: string;
+  results: FnDepsEntry[];
 }

package/src/db/repository/index.ts

@@ -1,5 +1,6 @@
 // Barrel re-export for repository/ modules.
 
+export type { FnDepsCallerNode, FnDepsEntry, FnDepsNode, FnDepsResult } from './base.js';
 export { Repository } from './base.js';
 export { purgeFileData, purgeFilesData } from './build-stmts.js';
 export { cachedStmt } from './cached-stmt.js';