@optave/codegraph 3.13.0 → 3.15.0

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

@@ -287,6 +287,28 @@ function handleAssignment(
   }
 }
 
+/** Unwrap argument wrapper and spread nodes to get the core argument node. */
+function unwrapArg(
+  arg: TreeSitterNode,
+  rules: AnyRules,
+): { unwrapped: TreeSitterNode; raw: TreeSitterNode } {
+  let raw = arg;
+  if (rules.argumentWrapperType && arg.type === rules.argumentWrapperType) {
+    raw = arg.namedChildren[0] || arg;
+  }
+  const unwrapped =
+    rules.spreadType && raw.type === rules.spreadType ? raw.namedChildren[0] || raw : raw;
+  return { unwrapped, raw };
+}
+
+/** Resolve the tracked name for a call argument (identifier or member receiver). */
+function resolveArgTrackedName(node: TreeSitterNode, rules: AnyRules): string | null {
+  const argName = isIdent(node.type, rules) ? node.text : null;
+  const argMember =
+    rules.memberNode && node.type === rules.memberNode ? memberReceiver(node, rules) : null;
+  return argName || argMember;
+}
+
 function handleCallExpr(
   node: TreeSitterNode,
   rules: AnyRules,
@@ -299,24 +321,14 @@ function handleCallExpr(
   if (!callee || !argsNode || !scope?.funcName) return;
 
   let argIndex = 0;
-  for (let arg of argsNode.namedChildren) {
-    if (rules.argumentWrapperType && arg.type === rules.argumentWrapperType) {
-      arg = arg.namedChildren[0] || arg;
-    }
-    const unwrapped =
-      rules.spreadType && arg.type === rules.spreadType ? arg.namedChildren[0] || arg : arg;
+  for (const arg of argsNode.namedChildren) {
+    const { unwrapped, raw } = unwrapArg(arg, rules);
     if (!unwrapped) {
       argIndex++;
       continue;
     }
 
-    const argName = isIdent(unwrapped.type, rules) ? unwrapped.text : null;
-    const argMember =
-      rules.memberNode && unwrapped.type === rules.memberNode
-        ? memberReceiver(unwrapped, rules)
-        : null;
-    const trackedName = argName || argMember;
-
+    const trackedName = resolveArgTrackedName(unwrapped, rules);
     if (trackedName) {
       const binding = findBinding(trackedName, scopeStack);
       if (binding) {
@@ -327,7 +339,7 @@ function handleCallExpr(
           argName: trackedName,
           binding,
           confidence: bindingConfidence(binding),
-          expression: truncate(arg.text),
+          expression: truncate(raw.text),
           line: node.startPosition.row + 1,
         });
       }
@@ -336,17 +348,11 @@ function handleCallExpr(
   }
 }
 
-function handleExprStmtMutation(
-  node: TreeSitterNode,
+/** Resolve the method name and receiver from a call expression node. */
+function resolveMutationCallParts(
+  expr: TreeSitterNode,
   rules: AnyRules,
-  scopeStack: ScopeEntry[],
-  mutations: DataflowMutation[],
-  isCallNode: (t: string) => boolean,
-): void {
-  if (rules.mutatingMethods.size === 0) return;
-  const expr = node.namedChildren[0];
-  if (!expr || !isCall(expr, isCallNode)) return;
-
+): { methodName: string | null; receiver: string | null } {
   let methodName: string | null = null;
   let receiver: string | null = null;
 
@@ -366,6 +372,21 @@ function handleExprStmtMutation(
     }
   }
 
+  return { methodName, receiver };
+}
+
+function handleExprStmtMutation(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  mutations: DataflowMutation[],
+  isCallNode: (t: string) => boolean,
+): void {
+  if (rules.mutatingMethods.size === 0) return;
+  const expr = node.namedChildren[0];
+  if (!expr || !isCall(expr, isCallNode)) return;
+
+  const { methodName, receiver } = resolveMutationCallParts(expr, rules);
   if (!methodName || !rules.mutatingMethods.has(methodName)) return;
 
   const scope = currentScope(scopeStack);
@@ -405,15 +426,27 @@ function handleReturn(
   }
 }
 
-/** Collect parameter entries for a function and push a new scope onto the stack. */
+/**
+ * Collect parameter entries for a function and push a new scope onto the stack.
+ *
+ * Returns `true` if a scope was pushed, `false` if the node was skipped (i.e.
+ * `nameExtractor` rejected it). Callers must pop the stack only when this
+ * returns `true` to keep push/pop symmetric.
+ */
 function enterFunctionScope(
   funcNode: TreeSitterNode,
   rules: AnyRules,
   scopeStack: ScopeEntry[],
   parameters: DataflowParam[],
-): void {
+): boolean {
+  // When nameExtractor is set it acts as a gate: null means this node is not a function
+  // definition. Needed for languages (Elixir, Clojure) where functionNodes includes generic
+  // node types (call/list_lit) that are only sometimes function definitions.
+  if (rules.nameExtractor && !rules.nameExtractor(funcNode)) return false;
   const name = functionName(funcNode, rules);
-  const paramsNode = funcNode.childForFieldName(rules.paramListField);
+  const paramsNode = rules.getParamListNode
+    ? rules.getParamListNode(funcNode)
+    : funcNode.childForFieldName(rules.paramListField);
   const paramList = extractParams(paramsNode, rules);
   const paramMap = new Map<string, number>();
   for (const p of paramList) {
@@ -428,6 +461,7 @@ function enterFunctionScope(
     }
   }
   scopeStack.push({ funcName: name, funcNode, params: paramMap, locals: new Map() });
+  return true;
 }
 
 interface DataflowDispatchCtx {
@@ -489,6 +523,11 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
   const argFlows: DataflowArgFlow[] = [];
   const mutations: DataflowMutation[] = [];
   const scopeStack: ScopeEntry[] = [];
+  // Parallel stack that records whether each enterFunction call actually pushed a
+  // scope frame.  exitFunction pops scopeStack only when the matching entry is true,
+  // keeping push/pop symmetric even for languages (Elixir, Clojure) where
+  // enterFunctionScope may return early without pushing.
+  const pushRecord: boolean[] = [];
 
   const dispatchCtx: DataflowDispatchCtx = {
     rules,
@@ -509,7 +548,7 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
       _funcName: string | null,
       _context: VisitorContext,
     ): void {
-      enterFunctionScope(funcNode, rules, scopeStack, parameters);
+      pushRecord.push(enterFunctionScope(funcNode, rules, scopeStack, parameters));
     },
 
     exitFunction(
@@ -517,7 +556,7 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
       _funcName: string | null,
       _context: VisitorContext,
     ): void {
-      scopeStack.pop();
+      if (pushRecord.pop()) scopeStack.pop();
     },
 
     enterNode(node: TreeSitterNode, _context: VisitorContext): EnterNodeResult | undefined {

package/src/cli/commands/config.ts

@@ -148,6 +148,181 @@ function buildInitTemplate(): string {
   return `${JSON.stringify(template, null, 2)}\n`;
 }
 
+// ─── Subcommand handlers ───────────────────────────────────────────────
+
+function handleInit(): void {
+  const targetPath = getDefaultUserConfigPath();
+  if (fs.existsSync(targetPath)) {
+    process.stderr.write(
+      `Global config already exists at ${targetPath}\n` +
+        `Run \`codegraph config --edit\` to open it, or delete it and re-run --init.\n`,
+    );
+    process.exit(1);
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, buildInitTemplate(), 'utf-8');
+  process.stdout.write(`Created global config at ${targetPath}\n`);
+  process.stdout.write(
+    `Next steps:\n` +
+      `  1. Edit the file: codegraph config --edit\n` +
+      `  2. Enable it for this repo: codegraph config --enable-global\n`,
+  );
+}
+
+function handleEdit(): void {
+  // Prefer the existing file; fall back to the default path so the user
+  // can create-and-edit in one step even before running --init.
+  const filePath = resolveUserConfigPath() ?? getDefaultUserConfigPath();
+
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) {
+    process.stdout.write(`${filePath}\n`);
+    process.stderr.write(
+      `$EDITOR is not set. Set it in your shell profile (e.g. export EDITOR=nano)\n` +
+        `or open the file manually at the path printed above.\n`,
+    );
+    return;
+  }
+
+  // Ensure the directory exists so the editor can create the file
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const result = spawnSync(editor, [filePath], { stdio: 'inherit' });
+  if (result.error) {
+    process.stderr.write(`Failed to launch editor "${editor}": ${result.error.message}\n`);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function handleEnableGlobal(rootDir: string): void {
+  setUserConfigConsent(rootDir, 'enabled');
+  clearConfigCache();
+  const globalPath = resolveUserConfigPath();
+  if (!globalPath) {
+    process.stderr.write(
+      `Consent recorded: "enabled" for ${rootDir}\n` +
+        `Note: no global config file found. Create one at ~/.config/codegraph/config.json\n`,
+    );
+  } else {
+    process.stderr.write(
+      `Consent recorded: "enabled" for ${rootDir}\n` + `Global config: ${globalPath}\n`,
+    );
+  }
+}
+
+function handleDisableGlobal(rootDir: string): void {
+  setUserConfigConsent(rootDir, 'disabled');
+  clearConfigCache();
+  process.stderr.write(`Consent recorded: "disabled" for ${rootDir}\n`);
+}
+
+function handleListGlobal(json: boolean): void {
+  const entries = listUserConfigConsent(REGISTRY_PATH);
+  if (json) {
+    process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+    return;
+  }
+  if (entries.length === 0) {
+    process.stdout.write('No repos have a recorded global-config consent decision.\n');
+    return;
+  }
+  process.stdout.write('Global config consent decisions:\n\n');
+  for (const { path: p, decision } of entries) {
+    process.stdout.write(`  ${decision === 'enabled' ? '✔' : '✘'} ${decision.padEnd(8)} ${p}\n`);
+  }
+}
+
+function handleExplain(
+  rootDir: string,
+  json: boolean,
+  userConfigOverride: string | undefined,
+): void {
+  const { config, provenance, appliedGlobalPath, consentDecision } = loadConfigWithProvenance(
+    rootDir,
+    { userConfig: userConfigOverride },
+  );
+  const globalPath = resolveUserConfigPath();
+  const consent = getUserConfigConsent(rootDir);
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          config,
+          provenance,
+          appliedGlobalPath,
+          globalFilePath: globalPath,
+          consentDecision: consentDecision ?? consent ?? 'undecided',
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+
+  // Human-readable explain output
+  process.stdout.write('=== Codegraph config provenance ===\n\n');
+
+  const consentStr = consentDecision ?? consent ?? 'undecided';
+  process.stdout.write(`Global config file : ${globalPath ?? '(none found)'}\n`);
+  process.stdout.write(`Applied this run   : ${appliedGlobalPath ? 'yes' : 'no'}\n`);
+  process.stdout.write(`Consent for repo   : ${consentStr}\n`);
+  process.stdout.write(
+    `  (change with \`codegraph config --enable-global\` or \`--disable-global\`)\n`,
+  );
+
+  if (!globalPath) {
+    process.stdout.write(
+      `\nDiscovery hint: create a global config at ~/.config/codegraph/config.json\n` +
+        `then run \`codegraph config --enable-global\` in repos where you want it applied.\n`,
+    );
+  } else if (!appliedGlobalPath) {
+    process.stdout.write(
+      `\nDiscovery hint: global config exists but is not applied to this repo.\n` +
+        `Run \`codegraph config --enable-global\` to enable it here.\n`,
+    );
+  }
+
+  process.stdout.write('\n--- Per-key provenance ---\n\n');
+  const provenanceEntries = Object.entries(provenance).sort(([a], [b]) => a.localeCompare(b));
+  for (const [key, source] of provenanceEntries) {
+    process.stdout.write(`  ${source.padEnd(8)} ${key}\n`);
+  }
+}
+
+function handleShowConfig(
+  rootDir: string,
+  json: boolean,
+  userConfigOverride: string | undefined,
+): void {
+  const globalPath = resolveUserConfigPath();
+  const consent = getUserConfigConsent(rootDir);
+
+  if (json) {
+    const config = loadConfig(rootDir, { userConfig: userConfigOverride });
+    process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+    return;
+  }
+
+  // Human-readable table: Key | Value | Source
+  const { config, provenance } = loadConfigWithProvenance(rootDir, {
+    userConfig: userConfigOverride,
+  });
+  process.stdout.write(renderConfigTable(config as unknown as Record<string, unknown>, provenance));
+
+  if (globalPath && !consent) {
+    process.stderr.write(
+      `\nℹ Global config found at ${globalPath} — not applied to this repo.\n` +
+        `  Run \`codegraph config --enable-global\` to opt in, or\n` +
+        `  \`codegraph config --disable-global\` to dismiss this notice.\n`,
+    );
+  }
+}
+
 export const command: CommandDefinition = {
   name: 'config',
   description: 'Show or manage codegraph configuration (project + user-level global config)',
@@ -165,189 +340,14 @@ export const command: CommandDefinition = {
   ],
   execute(_args, opts, ctx) {
     const rootDir = path.resolve('.');
-
-    // ── Init: scaffold global config ───────────────────────────────────
-
-    if (opts.init) {
-      const targetPath = getDefaultUserConfigPath();
-      if (fs.existsSync(targetPath)) {
-        process.stderr.write(
-          `Global config already exists at ${targetPath}\n` +
-            `Run \`codegraph config --edit\` to open it, or delete it and re-run --init.\n`,
-        );
-        process.exit(1);
-      }
-      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-      fs.writeFileSync(targetPath, buildInitTemplate(), 'utf-8');
-      process.stdout.write(`Created global config at ${targetPath}\n`);
-      process.stdout.write(
-        `Next steps:\n` +
-          `  1. Edit the file: codegraph config --edit\n` +
-          `  2. Enable it for this repo: codegraph config --enable-global\n`,
-      );
-      return;
-    }
-
-    // ── Edit: open global config in $EDITOR ────────────────────────────
-
-    if (opts.edit) {
-      // Prefer the existing file; fall back to the default path so the user
-      // can create-and-edit in one step even before running --init.
-      const filePath = resolveUserConfigPath() ?? getDefaultUserConfigPath();
-
-      const editor = process.env.EDITOR || process.env.VISUAL;
-      if (!editor) {
-        process.stdout.write(`${filePath}\n`);
-        process.stderr.write(
-          `$EDITOR is not set. Set it in your shell profile (e.g. export EDITOR=nano)\n` +
-            `or open the file manually at the path printed above.\n`,
-        );
-        return;
-      }
-
-      // Ensure the directory exists so the editor can create the file
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-
-      const result = spawnSync(editor, [filePath], { stdio: 'inherit' });
-      if (result.error) {
-        process.stderr.write(`Failed to launch editor "${editor}": ${result.error.message}\n`);
-        process.exit(1);
-      }
-      if (result.status !== 0) {
-        process.exit(result.status ?? 1);
-      }
-      return;
-    }
-
-    // ── Consent management ─────────────────────────────────────────────
-
-    if (opts.enableGlobal) {
-      setUserConfigConsent(rootDir, 'enabled');
-      clearConfigCache();
-      const globalPath = resolveUserConfigPath();
-      if (!globalPath) {
-        process.stderr.write(
-          `Consent recorded: "enabled" for ${rootDir}\n` +
-            `Note: no global config file found. Create one at ~/.config/codegraph/config.json\n`,
-        );
-      } else {
-        process.stderr.write(
-          `Consent recorded: "enabled" for ${rootDir}\n` + `Global config: ${globalPath}\n`,
-        );
-      }
-      return;
-    }
-
-    if (opts.disableGlobal) {
-      setUserConfigConsent(rootDir, 'disabled');
-      clearConfigCache();
-      process.stderr.write(`Consent recorded: "disabled" for ${rootDir}\n`);
-      return;
-    }
-
-    if (opts.listGlobal) {
-      const entries = listUserConfigConsent(REGISTRY_PATH);
-      if (opts.json) {
-        process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
-        return;
-      }
-      if (entries.length === 0) {
-        process.stdout.write('No repos have a recorded global-config consent decision.\n');
-        return;
-      }
-      process.stdout.write('Global config consent decisions:\n\n');
-      for (const { path: p, decision } of entries) {
-        process.stdout.write(
-          `  ${decision === 'enabled' ? '✔' : '✘'} ${decision.padEnd(8)} ${p}\n`,
-        );
-      }
-      return;
-    }
-
-    // ── Explain mode ───────────────────────────────────────────────────
-
-    if (opts.explain) {
-      const { config, provenance, appliedGlobalPath, consentDecision } = loadConfigWithProvenance(
-        rootDir,
-        {
-          userConfig: ctx.program.opts().userConfig,
-        },
-      );
-      const globalPath = resolveUserConfigPath();
-      const consent = getUserConfigConsent(rootDir);
-
-      if (opts.json) {
-        process.stdout.write(
-          `${JSON.stringify(
-            {
-              config,
-              provenance,
-              appliedGlobalPath,
-              globalFilePath: globalPath,
-              consentDecision: consentDecision ?? consent ?? 'undecided',
-            },
-            null,
-            2,
-          )}\n`,
-        );
-        return;
-      }
-
-      // Human-readable explain output
-      process.stdout.write('=== Codegraph config provenance ===\n\n');
-
-      const consentStr = consentDecision ?? consent ?? 'undecided';
-      process.stdout.write(`Global config file : ${globalPath ?? '(none found)'}\n`);
-      process.stdout.write(`Applied this run   : ${appliedGlobalPath ? 'yes' : 'no'}\n`);
-      process.stdout.write(`Consent for repo   : ${consentStr}\n`);
-      process.stdout.write(
-        `  (change with \`codegraph config --enable-global\` or \`--disable-global\`)\n`,
-      );
-
-      if (!globalPath) {
-        process.stdout.write(
-          `\nDiscovery hint: create a global config at ~/.config/codegraph/config.json\n` +
-            `then run \`codegraph config --enable-global\` in repos where you want it applied.\n`,
-        );
-      } else if (!appliedGlobalPath) {
-        process.stdout.write(
-          `\nDiscovery hint: global config exists but is not applied to this repo.\n` +
-            `Run \`codegraph config --enable-global\` to enable it here.\n`,
-        );
-      }
-
-      process.stdout.write('\n--- Per-key provenance ---\n\n');
-      const provenanceEntries = Object.entries(provenance).sort(([a], [b]) => a.localeCompare(b));
-      for (const [key, source] of provenanceEntries) {
-        process.stdout.write(`  ${source.padEnd(8)} ${key}\n`);
-      }
-      return;
-    }
-
-    // ── Default: print effective config ────────────────────────────────
-
-    const globalPath = resolveUserConfigPath();
-    const consent = getUserConfigConsent(rootDir);
-
-    if (opts.json) {
-      const config = loadConfig(rootDir, { userConfig: ctx.program.opts().userConfig });
-      process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
-    } else {
-      // Human-readable table: Key | Value | Source
-      const { config, provenance } = loadConfigWithProvenance(rootDir, {
-        userConfig: ctx.program.opts().userConfig,
-      });
-      process.stdout.write(
-        renderConfigTable(config as unknown as Record<string, unknown>, provenance),
-      );
-
-      if (globalPath && !consent) {
-        process.stderr.write(
-          `\nℹ Global config found at ${globalPath} — not applied to this repo.\n` +
-            `  Run \`codegraph config --enable-global\` to opt in, or\n` +
-            `  \`codegraph config --disable-global\` to dismiss this notice.\n`,
-        );
-      }
-    }
+    const userConfigOverride = ctx.program.opts().userConfig as string | undefined;
+
+    if (opts.init) return handleInit();
+    if (opts.edit) return handleEdit();
+    if (opts.enableGlobal) return handleEnableGlobal(rootDir);
+    if (opts.disableGlobal) return handleDisableGlobal(rootDir);
+    if (opts.listGlobal) return handleListGlobal(opts.json);
+    if (opts.explain) return handleExplain(rootDir, opts.json, userConfigOverride);
+    return handleShowConfig(rootDir, opts.json, userConfigOverride);
   },
 };

package/src/cli/commands/roles.ts

@@ -1,6 +1,6 @@
 import { collectFile } from '../../db/query-builder.js';
 import { VALID_ROLES } from '../../domain/queries.js';
-import { roles } from '../../presentation/queries-cli.js';
+import { dynamicCalls, roles } from '../../presentation/queries-cli.js';
 import type { CommandDefinition } from '../types.js';
 
 export const command: CommandDefinition = {
@@ -17,6 +17,7 @@ export const command: CommandDefinition = {
     ['-n, --limit <number>', 'Max results to return'],
     ['--offset <number>', 'Skip N results (default: 0)'],
     ['--ndjson', 'Newline-delimited JSON output'],
+    ['--dynamic', 'Show flagged dynamic call sites instead of symbol roles'],
   ],
   validate(_args, opts) {
     if (opts.role && !(VALID_ROLES as readonly string[]).includes(opts.role)) {
@@ -24,6 +25,10 @@ export const command: CommandDefinition = {
     }
   },
   execute(_args, opts, ctx) {
+    if (opts.dynamic) {
+      dynamicCalls(opts.db, ctx.resolveQueryOpts(opts));
+      return;
+    }
     roles(opts.db, {
       role: opts.role,
       file: opts.file,

package/src/db/better-sqlite3.ts

@@ -7,14 +7,15 @@
  * rusqlite) never touches this module.
  */
 import { createRequire } from 'node:module';
+import type Database from 'better-sqlite3';
 
 const _require = createRequire(import.meta.url);
-let _Database: any;
+let _Database: typeof Database | undefined;
 
 /** Return the `better-sqlite3` Database constructor, loading it on first call. */
-export function getDatabase(): new (...args: any[]) => any {
+export function getDatabase(): typeof Database {
   if (!_Database) {
-    _Database = _require('better-sqlite3');
+    _Database = _require('better-sqlite3') as typeof Database;
   }
-  return _Database;
+  return _Database!;
 }

package/src/db/connection.ts

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../infrastructure/config.js';
 import { debug, warn } from '../infrastructure/logger.js';
 import { getNative, isNativeAvailable } from '../infrastructure/native.js';
 import { DbError, toErrorMessage } from '../shared/errors.js';
@@ -379,9 +380,14 @@ export function openRepo(
     return { repo: opts.repo, close() {} };
   }
 
-  // Respect explicit engine selection: opts.engine > CODEGRAPH_ENGINE env > auto.
+  // Derive rootDir from customDbPath so loadConfig reads the right project config.
+  // Convention: customDbPath = <rootDir>/.codegraph/graph.db
+  const rootDir = customDbPath ? path.dirname(path.dirname(path.resolve(customDbPath))) : undefined;
+  // Respect explicit engine selection: opts.engine > config.build.engine > auto.
+  // config.build.engine is already populated from CODEGRAPH_ENGINE env by applyEnvOverrides,
+  // so this covers both the env-var path and the .codegraphrc.json config-file path.
   // This ensures --engine wasm and benchmark workers bypass the native path.
-  const engine = opts.engine || process.env.CODEGRAPH_ENGINE || 'auto';
+  const engine = opts.engine ?? loadConfig(rootDir).build.engine ?? 'auto';
 
   // Try native rusqlite path first (Phase 6.14)
   if (engine !== 'wasm' && isNativeAvailable()) {
@@ -416,16 +422,28 @@ export function openRepo(
  * Returns the better-sqlite3 handle (for backwards compat) plus an optional
  * NativeDatabase for modules that can use batched Rust query methods.
  * Callers should use nativeDb when available and fall back to db.prepare().
+ *
+ * @param opts.engine - Per-call engine override: 'native' | 'wasm' | 'auto'.
+ *   When omitted, falls back to config.build.engine then 'auto', mirroring
+ *   the priority chain used by openRepo().
  */
-export function openReadonlyWithNative(customPath?: string): {
+export function openReadonlyWithNative(
+  customPath?: string,
+  opts: { engine?: 'native' | 'wasm' | 'auto' } = {},
+): {
   db: BetterSqlite3Database;
   nativeDb: NativeDatabase | undefined;
   close(): void;
 } {
   const db = openReadonlyOrFail(customPath);
 
-  // Respect explicit engine selection, consistent with openRepo().
-  const engine = process.env.CODEGRAPH_ENGINE || 'auto';
+  // Derive rootDir from customPath so loadConfig reads the right project config,
+  // consistent with openRepo(). Convention: customPath = <rootDir>/.codegraph/graph.db
+  const rootDir = customPath ? path.dirname(path.dirname(path.resolve(customPath))) : undefined;
+  // Respect explicit engine selection: opts.engine > config.build.engine > auto.
+  // config.build.engine covers both CODEGRAPH_ENGINE env (via applyEnvOverrides)
+  // and the .codegraphrc.json config-file path. Mirrors openRepo() priority chain.
+  const engine = opts.engine ?? loadConfig(rootDir).build.engine ?? 'auto';
 
   let nativeDb: NativeDatabase | undefined;
   if (engine !== 'wasm' && isNativeAvailable()) {

package/src/db/index.ts

@@ -71,6 +71,7 @@ export {
   hasCfgTables,
   hasCoChanges,
   hasDataflowTable,
+  hasDataflowVertices,
   hasEmbeddings,
   InMemoryRepository,
   iterateFunctionNodes,