@optave/codegraph 3.5.0 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "dist/index.js",
@@ -131,12 +131,12 @@
   },
   "optionalDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "3.5.0",
-    "@optave/codegraph-darwin-x64": "3.5.0",
-    "@optave/codegraph-linux-arm64-gnu": "3.5.0",
-    "@optave/codegraph-linux-x64-gnu": "3.5.0",
-    "@optave/codegraph-linux-x64-musl": "3.5.0",
-    "@optave/codegraph-win32-x64-msvc": "3.5.0"
+    "@optave/codegraph-darwin-arm64": "3.6.0",
+    "@optave/codegraph-darwin-x64": "3.6.0",
+    "@optave/codegraph-linux-arm64-gnu": "3.6.0",
+    "@optave/codegraph-linux-x64-gnu": "3.6.0",
+    "@optave/codegraph-linux-x64-musl": "3.6.0",
+    "@optave/codegraph-win32-x64-msvc": "3.6.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",
@@ -148,15 +148,21 @@
     "@vitest/coverage-v8": "^4.0.18",
     "commit-and-tag-version": "^12.5",
     "husky": "^9.1",
+    "tree-sitter-bash": "^0.25.1",
+    "tree-sitter-c": "^0.24.1",
     "tree-sitter-c-sharp": "^0.23.1",
     "tree-sitter-cli": "^0.26.5",
+    "tree-sitter-cpp": "^0.23.4",
     "tree-sitter-go": "^0.25.0",
     "tree-sitter-java": "^0.23.5",
     "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-php": "^0.24.2",
     "tree-sitter-python": "^0.25.0",
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-scala": "^0.24.0",
+    "tree-sitter-swift": "^0.7.1",
     "tree-sitter-typescript": "^0.23.2",
     "typescript": "^6.0.2",
     "vitest": "^4.0.18"

package/src/ast-analysis/engine.ts

@@ -102,11 +102,12 @@ async function ensureWasmTreesIfNeeded(
   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;
 
-  if (!doComplexity && !doCfg && !doDataflow) return;
+  if (!doAst && !doComplexity && !doCfg && !doDataflow) return;
 
   let needsWasmTrees = false;
   for (const [relPath, symbols] of fileSymbols) {
@@ -131,6 +132,8 @@ async function ensureWasmTreesIfNeeded(
       d.endLine > d.line &&
       !d.name.includes('.');
 
+    // AST: need tree when native didn't provide non-call astNodes
+    const needsAst = doAst && !Array.isArray(symbols.astNodes) && WALK_EXTENSIONS.has(ext);
     const needsComplexity =
       doComplexity &&
       COMPLEXITY_EXTENSIONS.has(ext) &&
@@ -141,7 +144,7 @@ async function ensureWasmTreesIfNeeded(
       defs.some((d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks));
     const needsDataflow = doDataflow && !symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext);
 
-    if (needsComplexity || needsCfg || needsDataflow) {
+    if (needsAst || needsComplexity || needsCfg || needsDataflow) {
       needsWasmTrees = true;
       break;
     }
@@ -159,6 +162,80 @@ async function ensureWasmTreesIfNeeded(
 
 // ─── Per-file visitor setup ─────────────────────────────────────────────
 
+/** Check if a definition has a real function body (not a type signature). */
+function hasFuncBody(d: {
+  name: string;
+  kind: string;
+  line: number;
+  endLine?: number | null;
+}): boolean {
+  return (
+    (d.kind === 'function' || d.kind === 'method') &&
+    d.line > 0 &&
+    d.endLine != null &&
+    d.endLine > d.line &&
+    !d.name.includes('.')
+  );
+}
+
+/** Set up AST-store visitor if applicable. */
+function setupAstVisitor(
+  db: BetterSqlite3Database,
+  relPath: string,
+  symbols: ExtractorOutput,
+  langId: string,
+  ext: string,
+): Visitor | null {
+  const astTypeMap = AST_TYPE_MAPS.get(langId);
+  if (!astTypeMap || !WALK_EXTENSIONS.has(ext) || Array.isArray(symbols.astNodes)) return null;
+  const nodeIdMap = new Map<string, number>();
+  for (const row of bulkNodeIdsByFile(db, relPath)) {
+    nodeIdMap.set(`${row.name}|${row.kind}|${row.line}`, row.id);
+  }
+  return createAstStoreVisitor(astTypeMap, symbols.definitions || [], relPath, nodeIdMap);
+}
+
+/** Set up complexity visitor if any definitions need WASM complexity analysis. */
+function setupComplexityVisitorForFile(
+  defs: Definition[],
+  langId: string,
+  walkerOpts: WalkOptions,
+): Visitor | null {
+  const cRules = COMPLEXITY_RULES.get(langId);
+  if (!cRules) return null;
+
+  const hRules = HALSTEAD_RULES.get(langId);
+  const needsWasmComplexity = defs.some((d) => hasFuncBody(d) && !d.complexity);
+  if (!needsWasmComplexity) return null;
+
+  const visitor = createComplexityVisitor(cRules, hRules, { fileLevelWalk: true, langId });
+
+  for (const t of cRules.nestingNodes) walkerOpts.nestingNodeTypes?.add(t);
+
+  const dfRules = DATAFLOW_RULES.get(langId);
+  walkerOpts.getFunctionName = (node: TreeSitterNode): string | null => {
+    const nameNode = node.childForFieldName('name');
+    if (nameNode) return nameNode.text;
+    if (dfRules) return getFuncName(node, dfRules as any);
+    return null;
+  };
+
+  return visitor;
+}
+
+/** Set up CFG visitor if any definitions need WASM CFG analysis. */
+function setupCfgVisitorForFile(defs: Definition[], langId: string, ext: string): Visitor | null {
+  const cfgRulesForLang = CFG_RULES.get(langId);
+  if (!cfgRulesForLang || !CFG_EXTENSIONS.has(ext)) return null;
+
+  const needsWasmCfg = defs.some(
+    (d) => hasFuncBody(d) && d.cfg !== null && !Array.isArray(d.cfg?.blocks),
+  );
+  if (!needsWasmCfg) return null;
+
+  return createCfgVisitor(cfgRulesForLang);
+}
+
 function setupVisitors(
   db: BetterSqlite3Database,
   relPath: string,
@@ -168,10 +245,6 @@ function setupVisitors(
 ): SetupResult {
   const ext = path.extname(relPath).toLowerCase();
   const defs = symbols.definitions || [];
-  const doAst = opts.ast !== false;
-  const doComplexity = opts.complexity !== false;
-  const doCfg = opts.cfg !== false;
-  const doDataflow = opts.dataflow !== false;
 
   const visitors: Visitor[] = [];
   const walkerOpts: WalkOptions = {
@@ -180,75 +253,19 @@ function setupVisitors(
     getFunctionName: (_node: TreeSitterNode) => null,
   };
 
-  // AST-store visitor
-  let astVisitor: Visitor | null = null;
-  const astTypeMap = AST_TYPE_MAPS.get(langId);
-  if (doAst && astTypeMap && WALK_EXTENSIONS.has(ext) && !Array.isArray(symbols.astNodes)) {
-    const nodeIdMap = new Map<string, number>();
-    for (const row of bulkNodeIdsByFile(db, relPath)) {
-      nodeIdMap.set(`${row.name}|${row.kind}|${row.line}`, row.id);
-    }
-    astVisitor = createAstStoreVisitor(astTypeMap, defs, relPath, nodeIdMap);
-    visitors.push(astVisitor);
-  }
+  const astVisitor = opts.ast !== false ? setupAstVisitor(db, relPath, symbols, langId, ext) : null;
+  if (astVisitor) visitors.push(astVisitor);
 
-  // Complexity visitor (file-level mode)
-  let complexityVisitor: Visitor | null = null;
-  const cRules = COMPLEXITY_RULES.get(langId);
-  const hRules = HALSTEAD_RULES.get(langId);
-  if (doComplexity && cRules) {
-    // Only trigger WASM complexity for definitions with real function bodies.
-    // Interface/type property signatures (dotted names, single-line span)
-    // correctly lack native complexity data and should not trigger a fallback.
-    const needsWasmComplexity = defs.some(
-      (d) =>
-        (d.kind === 'function' || d.kind === 'method') &&
-        d.line > 0 &&
-        d.endLine != null &&
-        d.endLine > d.line &&
-        !d.name.includes('.') &&
-        !d.complexity,
-    );
-    if (needsWasmComplexity) {
-      complexityVisitor = createComplexityVisitor(cRules, hRules, { fileLevelWalk: true, langId });
-      visitors.push(complexityVisitor);
-
-      for (const t of cRules.nestingNodes) walkerOpts.nestingNodeTypes?.add(t);
-
-      const dfRules = DATAFLOW_RULES.get(langId);
-      walkerOpts.getFunctionName = (node: TreeSitterNode): string | null => {
-        const nameNode = node.childForFieldName('name');
-        if (nameNode) return nameNode.text;
-        if (dfRules) return getFuncName(node, dfRules as any);
-        return null;
-      };
-    }
-  }
+  const complexityVisitor =
+    opts.complexity !== false ? setupComplexityVisitorForFile(defs, langId, walkerOpts) : null;
+  if (complexityVisitor) visitors.push(complexityVisitor);
 
-  // CFG visitor
-  let cfgVisitor: Visitor | null = null;
-  const cfgRulesForLang = CFG_RULES.get(langId);
-  if (doCfg && cfgRulesForLang && CFG_EXTENSIONS.has(ext)) {
-    const needsWasmCfg = defs.some(
-      (d) =>
-        (d.kind === 'function' || d.kind === 'method') &&
-        d.line > 0 &&
-        d.endLine != null &&
-        d.endLine > d.line &&
-        !d.name.includes('.') &&
-        d.cfg !== null &&
-        !Array.isArray(d.cfg?.blocks),
-    );
-    if (needsWasmCfg) {
-      cfgVisitor = createCfgVisitor(cfgRulesForLang);
-      visitors.push(cfgVisitor);
-    }
-  }
+  const cfgVisitor = opts.cfg !== false ? setupCfgVisitorForFile(defs, langId, ext) : null;
+  if (cfgVisitor) visitors.push(cfgVisitor);
 
-  // Dataflow visitor
   let dataflowVisitor: Visitor | null = null;
   const dfRules = DATAFLOW_RULES.get(langId);
-  if (doDataflow && dfRules && DATAFLOW_EXTENSIONS.has(ext) && !symbols.dataflow) {
+  if (opts.dataflow !== false && dfRules && DATAFLOW_EXTENSIONS.has(ext) && !symbols.dataflow) {
     dataflowVisitor = createDataflowVisitor(dfRules);
     visitors.push(dataflowVisitor);
   }
@@ -258,88 +275,80 @@ function setupVisitors(
 
 // ─── Result storage helpers ─────────────────────────────────────────────
 
-function storeComplexityResults(results: WalkResults, defs: Definition[], langId: string): void {
-  const complexityResults = (results.complexity || []) as ComplexityFuncResult[];
-  const resultByLine = new Map<number, ComplexityFuncResult[]>();
-  for (const r of complexityResults) {
-    if (r.funcNode) {
-      const line = r.funcNode.startPosition.row + 1;
-      if (!resultByLine.has(line)) resultByLine.set(line, []);
-      resultByLine.get(line)?.push(r);
-    }
+/** Index per-function results by start line for O(1) lookup. */
+function indexByLine<T extends { funcNode: TreeSitterNode }>(results: T[]): Map<number, T[]> {
+  const byLine = new Map<number, T[]>();
+  for (const r of results) {
+    if (!r.funcNode) continue;
+    const line = r.funcNode.startPosition.row + 1;
+    if (!byLine.has(line)) byLine.set(line, []);
+    byLine.get(line)?.push(r);
   }
+  return byLine;
+}
+
+/** Find the best matching result for a definition by line + name. */
+function matchResultToDef<T extends { funcNode: TreeSitterNode }>(
+  candidates: T[] | undefined,
+  defName: string,
+): T | undefined {
+  if (!candidates) return undefined;
+  if (candidates.length === 1) return candidates[0];
+  return (
+    candidates.find((r) => {
+      const n = r.funcNode.childForFieldName('name');
+      return n && n.text === defName;
+    }) ?? candidates[0]
+  );
+}
+
+function storeComplexityResults(results: WalkResults, defs: Definition[], langId: string): void {
+  const byLine = indexByLine((results.complexity || []) as ComplexityFuncResult[]);
   for (const def of defs) {
     if ((def.kind === 'function' || def.kind === 'method') && def.line && !def.complexity) {
-      const candidates = resultByLine.get(def.line);
-      const funcResult = !candidates
-        ? undefined
-        : candidates.length === 1
-          ? candidates[0]
-          : (candidates.find((r) => {
-              const n = r.funcNode.childForFieldName('name');
-              return n && n.text === def.name;
-            }) ?? candidates[0]);
-      if (funcResult) {
-        const { metrics } = funcResult;
-        const loc = computeLOCMetrics(funcResult.funcNode, langId);
-        const volume = metrics.halstead ? metrics.halstead.volume : 0;
-        const commentRatio = loc.loc > 0 ? loc.commentLines / loc.loc : 0;
-        const mi = computeMaintainabilityIndex(volume, metrics.cyclomatic, loc.sloc, commentRatio);
-
-        def.complexity = {
-          cognitive: metrics.cognitive,
-          cyclomatic: metrics.cyclomatic,
-          maxNesting: metrics.maxNesting,
-          halstead: metrics.halstead,
-          loc,
-          maintainabilityIndex: mi,
-        };
-      }
+      const funcResult = matchResultToDef(byLine.get(def.line), def.name);
+      if (!funcResult) continue;
+      const { metrics } = funcResult;
+      const loc = computeLOCMetrics(funcResult.funcNode, langId);
+      const volume = metrics.halstead ? metrics.halstead.volume : 0;
+      const commentRatio = loc.loc > 0 ? loc.commentLines / loc.loc : 0;
+      const mi = computeMaintainabilityIndex(volume, metrics.cyclomatic, loc.sloc, commentRatio);
+      def.complexity = {
+        cognitive: metrics.cognitive,
+        cyclomatic: metrics.cyclomatic,
+        maxNesting: metrics.maxNesting,
+        halstead: metrics.halstead,
+        loc,
+        maintainabilityIndex: mi,
+      };
     }
   }
 }
 
 function storeCfgResults(results: WalkResults, defs: Definition[]): void {
-  const cfgResults = (results.cfg || []) as CfgFuncResult[];
-  const cfgByLine = new Map<number, CfgFuncResult[]>();
-  for (const r of cfgResults) {
-    if (r.funcNode) {
-      const line = r.funcNode.startPosition.row + 1;
-      if (!cfgByLine.has(line)) cfgByLine.set(line, []);
-      cfgByLine.get(line)?.push(r);
-    }
-  }
+  const byLine = indexByLine((results.cfg || []) as CfgFuncResult[]);
   for (const def of defs) {
     if (
       (def.kind === 'function' || def.kind === 'method') &&
       def.line &&
       !def.cfg?.blocks?.length
     ) {
-      const candidates = cfgByLine.get(def.line);
-      const cfgResult = !candidates
-        ? undefined
-        : candidates.length === 1
-          ? candidates[0]
-          : (candidates.find((r) => {
-              const n = r.funcNode.childForFieldName('name');
-              return n && n.text === def.name;
-            }) ?? candidates[0]);
-      if (cfgResult) {
-        def.cfg = { blocks: cfgResult.blocks, edges: cfgResult.edges };
-
-        // Override complexity's cyclomatic with CFG-derived value (single source of truth)
-        if (def.complexity && cfgResult.cyclomatic != null) {
-          def.complexity.cyclomatic = cfgResult.cyclomatic;
-          const { loc, halstead } = def.complexity;
-          const volume = halstead ? halstead.volume : 0;
-          const commentRatio = loc && loc.loc > 0 ? loc.commentLines / loc.loc : 0;
-          def.complexity.maintainabilityIndex = computeMaintainabilityIndex(
-            volume,
-            cfgResult.cyclomatic,
-            loc?.sloc ?? 0,
-            commentRatio,
-          );
-        }
+      const cfgResult = matchResultToDef(byLine.get(def.line), def.name);
+      if (!cfgResult) continue;
+      def.cfg = { blocks: cfgResult.blocks, edges: cfgResult.edges };
+
+      // Override complexity's cyclomatic with CFG-derived value (single source of truth)
+      if (def.complexity && cfgResult.cyclomatic != null) {
+        def.complexity.cyclomatic = cfgResult.cyclomatic;
+        const { loc, halstead } = def.complexity;
+        const volume = halstead ? halstead.volume : 0;
+        const commentRatio = loc && loc.loc > 0 ? loc.commentLines / loc.loc : 0;
+        def.complexity.maintainabilityIndex = computeMaintainabilityIndex(
+          volume,
+          cfgResult.cyclomatic,
+          loc?.sloc ?? 0,
+          commentRatio,
+        );
       }
     }
   }

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

@@ -14,7 +14,7 @@ interface AstStoreRow {
   kind: string;
   name: string | null | undefined;
   text: string | null;
-  receiver: null;
+  receiver: string | null;
   parentNodeId: number | null;
 }
 
@@ -52,6 +52,14 @@ function extractCallName(node: TreeSitterNode): string {
   return node.text?.split('(')[0] || '?';
 }
 
+/** Extract receiver for call expressions (e.g. "obj" in "obj.method()"). */
+function extractCallReceiver(node: TreeSitterNode): string | null {
+  const fn = node.childForFieldName('function');
+  if (!fn || fn.type !== 'member_expression') return null;
+  const obj = fn.childForFieldName('object');
+  return obj ? obj.text : null;
+}
+
 function extractName(kind: string, node: TreeSitterNode): string | null {
   if (kind === 'throw') {
     for (let i = 0; i < node.childCount; i++) {
@@ -161,10 +169,12 @@ export function createAstStoreVisitor(
     const line = node.startPosition.row + 1;
     let name: string | null | undefined;
     let text: string | null = null;
+    let receiver: string | null = null;
 
     if (kind === 'call') {
       name = extractCallName(node);
       text = truncate(node.text);
+      receiver = extractCallReceiver(node);
     } else if (kind === 'new') {
       name = extractNewName(node);
       text = truncate(node.text);
@@ -190,7 +200,7 @@ export function createAstStoreVisitor(
       kind,
       name,
       text,
-      receiver: null,
+      receiver,
       parentNodeId: resolveParentNodeId(line),
     });
 
@@ -201,6 +211,9 @@ export function createAstStoreVisitor(
     name: 'ast-store',
 
     enterNode(node: TreeSitterNode, _context: VisitorContext): EnterNodeResult | undefined {
+      // Guard: skip re-collection but do NOT skipChildren — node.id (memory address)
+      // can be reused by tree-sitter, so a collision would incorrectly suppress an
+      // unrelated subtree. The parent call's skipChildren handles the intended case.
       if (matched.has(node.id)) return;
 
       const kind = astTypeMap[node.type];

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

@@ -87,6 +87,16 @@ function classifyBranchNode(
   }
 }
 
+function classifyLogicalOp(node: TreeSitterNode, cRules: AnyRules, acc: ComplexityAcc): void {
+  const op = node.child(1)?.type;
+  if (!op || !cRules.logicalOperators.has(op)) return;
+  acc.cyclomatic++;
+  const parent = node.parent;
+  const sameSequence =
+    parent != null && parent.type === cRules.logicalNodeType && parent.child(1)?.type === op;
+  if (!sameSequence) acc.cognitive++;
+}
+
 function classifyPlainElse(
   node: TreeSitterNode,
   type: string,
@@ -215,17 +225,7 @@ export function createComplexityVisitor(
       if (nestingLevel > acc.maxNesting) acc.maxNesting = nestingLevel;
 
       if (type === cRules.logicalNodeType) {
-        const op = node.child(1)?.type;
-        if (op && cRules.logicalOperators.has(op)) {
-          acc.cyclomatic++;
-          const parent = node.parent;
-          let sameSequence = false;
-          if (parent && parent.type === cRules.logicalNodeType) {
-            const parentOp = parent.child(1)?.type;
-            if (parentOp === op) sameSequence = true;
-          }
-          if (!sameSequence) acc.cognitive++;
-        }
+        classifyLogicalOp(node, cRules, acc);
       }
 
       if (type === cRules.optionalChainType) acc.cyclomatic++;

package/src/db/connection.ts

@@ -29,6 +29,23 @@ function getPackageVersion(): string {
 /** Warn once per process when DB version mismatches the running codegraph version. */
 let _versionWarned = false;
 
+/** Check and warn (once) if the running codegraph version differs from the DB build version. */
+function warnOnVersionMismatch(getBuildVersion: () => string | undefined | null): void {
+  if (_versionWarned) return;
+  _versionWarned = true;
+  try {
+    const buildVersion = getBuildVersion();
+    const currentVersion = getPackageVersion();
+    if (buildVersion && currentVersion && buildVersion !== currentVersion) {
+      warn(
+        `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
+  }
+}
+
 /** DB instance with optional advisory lock path. */
 export type LockedDatabase = BetterSqlite3Database & { __lockPath?: string };
 
@@ -81,11 +98,6 @@ export function _resetRepoRootCache(): void {
   _cachedRepoRootCwd = undefined;
 }
 
-/** Reset the version warning flag (for testing). */
-export function _resetVersionWarning(): void {
-  _versionWarned = false;
-}
-
 function isProcessAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -299,28 +311,41 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
   const Database = getDatabase();
   const db = new Database(dbPath, { readonly: true }) as unknown as BetterSqlite3Database;
 
-  // Warn once per process if the DB was built with a different codegraph version
-  if (!_versionWarned) {
-    try {
-      const row = db
-        .prepare<{ value: string }>('SELECT value FROM build_meta WHERE key = ?')
-        .get('codegraph_version');
-      const buildVersion = row?.value;
-      const currentVersion = getPackageVersion();
-      if (buildVersion && currentVersion && buildVersion !== currentVersion) {
-        warn(
-          `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
-    }
-    _versionWarned = true;
-  }
+  warnOnVersionMismatch(() => {
+    const row = db
+      .prepare<{ value: string }>('SELECT value FROM build_meta WHERE key = ?')
+      .get('codegraph_version');
+    return row?.value;
+  });
 
   return db;
 }
 
+/** Open a NativeRepository via rusqlite, throwing DbError if the DB file is missing. */
+function openRepoNative(customDbPath?: string): { repo: Repository; close(): void } {
+  const dbPath = findDbPath(customDbPath);
+  if (!fs.existsSync(dbPath)) {
+    throw new DbError(
+      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
+      { file: dbPath },
+    );
+  }
+  const native = getNative();
+  const ndb = native.NativeDatabase.openReadonly(dbPath);
+  try {
+    warnOnVersionMismatch(() => ndb.getBuildMeta('codegraph_version'));
+    return {
+      repo: new NativeRepository(ndb),
+      close() {
+        ndb.close();
+      },
+    };
+  } catch (innerErr) {
+    ndb.close();
+    throw innerErr;
+  }
+}
+
 /**
  * Open a Repository from either an injected instance or a DB path.
  *
@@ -345,42 +370,7 @@ export function openRepo(
   // Try native rusqlite path first (Phase 6.14)
   if (isNativeAvailable()) {
     try {
-      const dbPath = findDbPath(customDbPath);
-      if (!fs.existsSync(dbPath)) {
-        throw new DbError(
-          `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
-          { file: dbPath },
-        );
-      }
-      const native = getNative();
-      const ndb = native.NativeDatabase.openReadonly(dbPath);
-      try {
-        // Version check (same logic as openReadonlyOrFail)
-        if (!_versionWarned) {
-          try {
-            const buildVersion = ndb.getBuildMeta('codegraph_version');
-            const currentVersion = getPackageVersion();
-            if (buildVersion && currentVersion && buildVersion !== currentVersion) {
-              warn(
-                `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
-          }
-          _versionWarned = true;
-        }
-
-        return {
-          repo: new NativeRepository(ndb),
-          close() {
-            ndb.close();
-          },
-        };
-      } catch (innerErr) {
-        ndb.close();
-        throw innerErr;
-      }
+      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).
@@ -399,3 +389,44 @@ export function openRepo(
     },
   };
 }
+
+/**
+ * Open a readonly DB with an optional NativeDatabase alongside it.
+ *
+ * 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().
+ */
+export function openReadonlyWithNative(customPath?: string): {
+  db: BetterSqlite3Database;
+  nativeDb: NativeDatabase | undefined;
+  close(): void;
+} {
+  const db = openReadonlyOrFail(customPath);
+
+  let nativeDb: NativeDatabase | undefined;
+  if (isNativeAvailable()) {
+    try {
+      const dbPath = findDbPath(customPath);
+      const native = getNative();
+      nativeDb = native.NativeDatabase.openReadonly(dbPath);
+    } catch (e) {
+      debug(`openReadonlyWithNative: native path failed: ${(e as Error).message}`);
+    }
+  }
+
+  return {
+    db,
+    nativeDb,
+    close() {
+      db.close();
+      if (nativeDb) {
+        try {
+          nativeDb.close();
+        } catch {
+          // already closed or not closeable
+        }
+      }
+    },
+  };
+}