@optave/codegraph 3.4.0 → 3.5.0

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

@@ -5,7 +5,6 @@ import {
   computeMaintainabilityIndex,
 } from '../metrics.js';
 
-// biome-ignore lint/suspicious/noExplicitAny: complexity/halstead rules are opaque language-specific objects
 type AnyRules = any;
 
 interface ComplexityAcc {

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

@@ -10,7 +10,6 @@ import {
   truncate,
 } from '../visitor-utils.js';
 
-// biome-ignore lint/suspicious/noExplicitAny: dataflow rules are opaque language-specific objects
 type AnyRules = any;
 
 interface ScopeEntry {

package/src/cli/commands/batch.ts

@@ -3,7 +3,7 @@ import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { BATCH_COMMANDS, multiBatchData, splitTargets } from '../../features/batch.js';
 import { batch } from '../../presentation/batch.js';
-import { ConfigError } from '../../shared/errors.js';
+import { ConfigError, toErrorMessage } from '../../shared/errors.js';
 import type { CommandDefinition } from '../types.js';
 
 interface MultiBatchItem {
@@ -58,8 +58,9 @@ export const command: CommandDefinition = {
         targets = splitTargets(positionalTargets as unknown as string[]);
       }
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new ConfigError(`Failed to parse targets: ${message}`, { cause: err as Error });
+      throw new ConfigError(`Failed to parse targets: ${toErrorMessage(err)}`, {
+        cause: err as Error,
+      });
     }
 
     if (!targets || targets.length === 0) {

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

@@ -13,7 +13,7 @@ export const command: CommandDefinition = {
   async execute([base, target], opts, ctx) {
     const { branchCompare } = await import('../../presentation/branch-compare.js');
     await branchCompare(base!, target!, {
-      engine: ctx.program.opts()['engine'],
+      engine: ctx.program.opts().engine,
       depth: parseInt(opts.depth as string, 10),
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,

package/src/cli/commands/build.ts

@@ -15,7 +15,7 @@ export const command: CommandDefinition = {
   ],
   async execute([dir], opts, ctx) {
     const root = path.resolve(dir || '.');
-    const engine = ctx.program.opts()['engine'];
+    const engine = ctx.program.opts().engine;
     await buildGraph(root, {
       incremental: opts.incremental as boolean,
       ast: opts.ast as boolean,

package/src/cli/commands/info.ts

@@ -9,7 +9,7 @@ export const command: CommandDefinition = {
     );
     const { getActiveEngine } = await import('../../domain/parser.js');
 
-    const engine = ctx.program.opts()['engine'];
+    const engine = ctx.program.opts().engine;
     const { name: activeName, version: activeVersion } = getActiveEngine({ engine });
     const nativeAvailable = isNativeAvailable();
 
@@ -43,7 +43,6 @@ export const command: CommandDefinition = {
       const dbPath = findDbPath();
       const fs = await import('node:fs');
       if (fs.existsSync(dbPath)) {
-        // @ts-expect-error -- better-sqlite3 default export typing
         const db = new Database(dbPath, { readonly: true });
         const buildEngine = getBuildMeta(db, 'engine');
         const buildVersion = getBuildMeta(db, 'codegraph_version');

package/src/cli/commands/path.ts

@@ -4,11 +4,15 @@ import type { CommandDefinition } from '../types.js';
 
 export const command: CommandDefinition = {
   name: 'path <from> <to>',
-  description: 'Find shortest path between two symbols',
+  description: 'Find shortest path between two symbols (or files with --file)',
   options: [
     ['-d, --db <path>', 'Path to graph.db'],
+    ['-f, --file', 'Treat <from> and <to> as file paths instead of symbol names'],
     ['--reverse', 'Follow edges backward'],
-    ['--kinds <kinds>', 'Comma-separated edge kinds to follow (default: calls)'],
+    [
+      '--kinds <kinds>',
+      'Comma-separated edge kinds to follow (default: calls; file mode: imports,imports-type)',
+    ],
     ['--from-file <path>', 'Disambiguate source symbol by file'],
     ['--to-file <path>', 'Disambiguate target symbol by file'],
     ['--depth <n>', 'Max traversal depth', '10'],
@@ -32,6 +36,7 @@ export const command: CommandDefinition = {
       kind: opts.kind,
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,
+      file: opts.file,
     });
   },
 };

package/src/cli/commands/plot.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { toErrorMessage } from '../../shared/errors.js';
 import { openGraph } from '../shared/open-graph.js';
 import type { CommandDefinition } from '../types.js';
 
@@ -51,8 +52,7 @@ export const command: CommandDefinition = {
         try {
           plotCfg = JSON.parse(fs.readFileSync(opts.config as string, 'utf-8')) as PlotConfig;
         } catch (e: unknown) {
-          const message = e instanceof Error ? e.message : String(e);
-          console.error(`Failed to load config: ${message}`);
+          console.error(`Failed to load config: ${toErrorMessage(e)}`);
           process.exitCode = 1;
           return;
         }

package/src/cli/commands/watch.ts

@@ -7,7 +7,7 @@ export const command: CommandDefinition = {
   description: 'Watch project for file changes and incrementally update the graph',
   async execute([dir], _opts, ctx) {
     const root = path.resolve(dir || '.');
-    const engine = ctx.program.opts()['engine'];
+    const engine = ctx.program.opts().engine;
     await watchProject(root, { engine });
   },
 };

package/src/cli/index.ts

@@ -27,12 +27,12 @@ program
   .option('--engine <engine>', 'Parser engine: native, wasm, or auto (default: auto)', 'auto')
   .hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
-    if (opts['verbose']) setVerbose(true);
+    if (opts.verbose) setVerbose(true);
   })
   .hook('postAction', async (_thisCommand, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'mcp' || name === 'watch') return;
-    if (actionCommand.opts()['json']) return;
+    if (actionCommand.opts().json) return;
     try {
       const result = await checkForUpdates(pkg.version);
       if (result) printUpdateNotification(result.current, result.latest);

package/src/cli/shared/open-graph.ts

@@ -1,11 +1,11 @@
-import type Database from 'better-sqlite3';
 import { openReadonlyOrFail } from '../../db/index.js';
+import type { BetterSqlite3Database } from '../../types.js';
 
 /**
  * Open the graph database in readonly mode with a clean close() handle.
  */
 export function openGraph(opts: { db?: string } = {}): {
-  db: Database.Database;
+  db: BetterSqlite3Database;
   close: () => void;
 } {
   const db = openReadonlyOrFail(opts.db);

package/src/cli/types.ts

@@ -27,7 +27,7 @@ export interface CommandDefinition {
   description: string;
   queryOpts?: boolean;
   options?: Array<[string, string, ...unknown[]]>;
-  validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | void;
+  validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | undefined;
   execute?(args: string[], opts: CommandOpts, ctx: CliContext): void | Promise<void>;
   subcommands?: CommandDefinition[];
 }

package/src/cli.ts

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 import { run } from './cli/index.js';
-import { CodegraphError } from './shared/errors.js';
+import { CodegraphError, toErrorMessage } from './shared/errors.js';
 
 run().catch((err: unknown) => {
   if (err instanceof CodegraphError) {
     console.error(`codegraph [${err.code}]: ${err.message}`);
     if (err.file) console.error(`  file: ${err.file}`);
   } else {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`codegraph: fatal error — ${message}`);
+    console.error(`codegraph: fatal error — ${toErrorMessage(err)}`);
   }
   process.exit(1);
 });

package/src/db/better-sqlite3.ts

@@ -0,0 +1,20 @@
+/**
+ * Lazy-loaded better-sqlite3 constructor.
+ *
+ * Centralises the `createRequire` + cache pattern so every call site that
+ * needs a JS-side SQLite handle can `import { getDatabase } from '…/db/better-sqlite3.js'`
+ * instead of duplicating the boilerplate.  The native engine path (NativeDatabase /
+ * rusqlite) never touches this module.
+ */
+import { createRequire } from 'node:module';
+
+const _require = createRequire(import.meta.url);
+let _Database: any;
+
+/** Return the `better-sqlite3` Database constructor, loading it on first call. */
+export function getDatabase(): new (...args: any[]) => any {
+  if (!_Database) {
+    _Database = _require('better-sqlite3');
+  }
+  return _Database;
+}

package/src/db/connection.ts

@@ -1,13 +1,34 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import Database from 'better-sqlite3';
+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 type { BetterSqlite3Database } from '../types.js';
+import type { BetterSqlite3Database, NativeDatabase } from '../types.js';
+import { getDatabase } from './better-sqlite3.js';
 import { Repository } from './repository/base.js';
+import { NativeRepository } from './repository/native-repository.js';
 import { SqliteRepository } from './repository/sqlite-repository.js';
 
+/** Lazy-loaded package version (read once from package.json). */
+let _packageVersion: string | undefined;
+function getPackageVersion(): string {
+  if (_packageVersion !== undefined) return _packageVersion;
+  try {
+    const connDir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.join(connDir, '..', '..', 'package.json');
+    _packageVersion = (JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version: string })
+      .version;
+  } catch {
+    _packageVersion = '';
+  }
+  return _packageVersion;
+}
+
+/** Warn once per process when DB version mismatches the running codegraph version. */
+let _versionWarned = false;
+
 /** DB instance with optional advisory lock path. */
 export type LockedDatabase = BetterSqlite3Database & { __lockPath?: string };
 
@@ -60,6 +81,11 @@ 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);
@@ -119,16 +145,13 @@ function isSameDirectory(a: string, b: string): boolean {
 }
 
 export function openDb(dbPath: string): LockedDatabase {
+  // Flush any deferred DB close from a previous build (avoids WAL contention)
+  flushDeferredClose();
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   acquireAdvisoryLock(dbPath);
-  // vendor.d.ts declares Database as a callable; cast through unknown for construct usage
-  const db = new (
-    Database as unknown as new (
-      path: string,
-      opts?: Record<string, unknown>,
-    ) => LockedDatabase
-  )(dbPath);
+  const Database = getDatabase();
+  const db = new Database(dbPath) as unknown as LockedDatabase;
   db.pragma('journal_mode = WAL');
   db.pragma('busy_timeout = 5000');
   db.__lockPath = `${dbPath}.lock`;
@@ -140,6 +163,89 @@ export function closeDb(db: LockedDatabase): void {
   if (db.__lockPath) releaseAdvisoryLock(db.__lockPath);
 }
 
+/** Pending deferred-close DB handles (not yet closed). */
+const _deferredDbs: LockedDatabase[] = [];
+
+/**
+ * Synchronously close any DB handles queued by `closeDbDeferred()`.
+ * Call before deleting DB files or in test teardown to avoid EBUSY on Windows.
+ */
+export function flushDeferredClose(): void {
+  while (_deferredDbs.length > 0) {
+    const db = _deferredDbs.pop()!;
+    try {
+      db.close();
+    } catch {
+      /* ignore — handle may already be closed */
+    }
+  }
+}
+
+/**
+ * Schedule DB close on the next event loop tick. Useful for incremental
+ * builds where the WAL checkpoint in db.close() is expensive (~250ms on
+ * Windows) and doesn't need to block the caller.
+ *
+ * The advisory lock is released immediately so subsequent opens succeed.
+ * The actual handle close (+ WAL checkpoint) happens asynchronously.
+ * Call `flushDeferredClose()` before deleting the DB file.
+ */
+export function closeDbDeferred(db: LockedDatabase): void {
+  // Release the advisory lock immediately so the next open can proceed
+  if (db.__lockPath) {
+    releaseAdvisoryLock(db.__lockPath);
+    db.__lockPath = undefined;
+  }
+  _deferredDbs.push(db);
+  // Defer the expensive WAL checkpoint to after the caller returns
+  setImmediate(() => {
+    const idx = _deferredDbs.indexOf(db);
+    if (idx !== -1) {
+      _deferredDbs.splice(idx, 1);
+      try {
+        db.close();
+      } catch {
+        /* ignore — handle may already be closed by flush */
+      }
+    }
+  });
+}
+
+// ── Paired close helpers (Phase 6.16) ──────────────────────────────────
+// When both a NativeDatabase and better-sqlite3 handle are open on the same
+// DB file, these helpers ensure NativeDatabase is closed first (fast, ~1ms)
+// before the better-sqlite3 close (which forces a WAL checkpoint, ~250ms).
+
+/** A better-sqlite3 handle optionally paired with a NativeDatabase. */
+export interface LockedDatabasePair {
+  db: LockedDatabase;
+  nativeDb?: NativeDatabase;
+}
+
+/** Close both handles: NativeDatabase first (fast), then better-sqlite3 (releases lock). */
+export function closeDbPair(pair: LockedDatabasePair): void {
+  if (pair.nativeDb) {
+    try {
+      pair.nativeDb.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  closeDb(pair.db);
+}
+
+/** Close NativeDatabase immediately, defer better-sqlite3 WAL checkpoint. */
+export function closeDbPairDeferred(pair: LockedDatabasePair): void {
+  if (pair.nativeDb) {
+    try {
+      pair.nativeDb.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  closeDbDeferred(pair.db);
+}
+
 export function findDbPath(customPath?: string): string {
   if (customPath) return path.resolve(customPath);
   const rawCeiling = findRepoRoot();
@@ -190,19 +296,38 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
       { file: dbPath },
     );
   }
-  return new (
-    Database as unknown as new (
-      path: string,
-      opts?: Record<string, unknown>,
-    ) => BetterSqlite3Database
-  )(dbPath, { readonly: true });
+  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;
+  }
+
+  return db;
 }
 
 /**
  * Open a Repository from either an injected instance or a DB path.
  *
  * When `opts.repo` is a Repository instance, returns it directly (no DB opened).
- * Otherwise opens a readonly SQLite DB and wraps it in SqliteRepository.
+ * When the native engine is available, opens a NativeDatabase (rusqlite) and
+ * wraps it in NativeRepository. Otherwise falls back to better-sqlite3 via
+ * SqliteRepository.
  */
 export function openRepo(
   customDbPath?: string,
@@ -216,6 +341,56 @@ export function openRepo(
     }
     return { repo: opts.repo, close() {} };
   }
+
+  // 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;
+      }
+    } 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: ${(e as Error).message}`,
+      );
+    }
+  }
+
   const db = openReadonlyOrFail(customDbPath);
   return {
     repo: new SqliteRepository(db),

package/src/db/index.ts

@@ -1,10 +1,14 @@
 // Barrel re-export — keeps all existing `import { ... } from '…/db/index.js'` working.
 
-export type { LockedDatabase } from './connection.js';
+export type { LockedDatabase, LockedDatabasePair } from './connection.js';
 export {
   closeDb,
+  closeDbDeferred,
+  closeDbPair,
+  closeDbPairDeferred,
   findDbPath,
   findRepoRoot,
+  flushDeferredClose,
   openDb,
   openReadonlyOrFail,
   openRepo,

package/src/db/migrations.ts

@@ -8,6 +8,8 @@ interface Migration {
   up: string;
 }
 
+// IMPORTANT: Migration DDL is mirrored in crates/codegraph-core/src/native_db.rs.
+// Any changes here MUST be reflected there (and vice-versa).
 export const MIGRATIONS: Migration[] = [
   {
     version: 1,
@@ -247,6 +249,13 @@ export const MIGRATIONS: Migration[] = [
       CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope);
     `,
   },
+  {
+    version: 16,
+    up: `
+      CREATE INDEX IF NOT EXISTS idx_edges_kind_target ON edges(kind, target_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_kind_source ON edges(kind, source_id);
+    `,
+  },
 ];
 
 interface PragmaColumnInfo {

package/src/db/query-builder.ts

@@ -1,6 +1,6 @@
 import { DbError } from '../shared/errors.js';
 import { DEAD_ROLE_PREFIX, EVERY_EDGE_KIND } from '../shared/kinds.js';
-import type { BetterSqlite3Database } from '../types.js';
+import type { BetterSqlite3Database, NativeDatabase } from '../types.js';
 
 // ─── Validation Helpers ─────────────────────────────────────────────
 
@@ -66,6 +66,17 @@ function validateEdgeKind(edgeKind: string): void {
   }
 }
 
+/** Runtime-validate that every param is string, number, or null before sending to nativeDb. */
+function validateNativeParams(params: (string | number)[]): Array<string | number | null> {
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i];
+    if (p !== null && typeof p !== 'string' && typeof p !== 'number') {
+      throw new DbError(`NodeQuery param[${i}] has unsupported type: ${typeof p}`);
+    }
+  }
+  return params as Array<string | number | null>;
+}
+
 // ─── LIKE Escaping ──────────────────────────────────────────────────
 
 /** Escape LIKE wildcards in a literal string segment. */
@@ -314,15 +325,29 @@ export class NodeQuery {
     return { sql, params };
   }
 
-  /** Execute and return all rows. */
-  all<TRow = Record<string, unknown>>(db: BetterSqlite3Database): TRow[] {
+  /** Execute and return all rows. When `nativeDb` is provided, dispatches through rusqlite. */
+  all<TRow = Record<string, unknown>>(
+    db: BetterSqlite3Database,
+    nativeDb?: NativeDatabase,
+  ): TRow[] {
     const { sql, params } = this.build();
+    if (nativeDb) {
+      return nativeDb.queryAll(sql, validateNativeParams(params)) as TRow[];
+    }
     return db.prepare<TRow>(sql).all(...params) as TRow[];
   }
 
-  /** Execute and return first row. */
-  get<TRow = Record<string, unknown>>(db: BetterSqlite3Database): TRow | undefined {
+  /** Execute and return first row. When `nativeDb` is provided, dispatches through rusqlite. */
+  get<TRow = Record<string, unknown>>(
+    db: BetterSqlite3Database,
+    nativeDb?: NativeDatabase,
+  ): TRow | undefined {
     const { sql, params } = this.build();
+    if (nativeDb) {
+      return (nativeDb.queryGet(sql, validateNativeParams(params)) ?? undefined) as
+        | TRow
+        | undefined;
+    }
     return db.prepare<TRow>(sql).get(...params) as TRow | undefined;
   }
 

package/src/db/repository/index.ts

@@ -28,6 +28,7 @@ export {
 export { getEmbeddingCount, getEmbeddingMeta, hasEmbeddings } from './embeddings.js';
 export { getCallableNodes, getCallEdges, getFileNodesAll, getImportEdges } from './graph-read.js';
 export { InMemoryRepository } from './in-memory-repository.js';
+export { NativeRepository } from './native-repository.js';
 export {
   bulkNodeIdsByFile,
   countEdges,