@optave/codegraph 3.4.1 → 3.6.0

package/src/db/connection.ts

@@ -2,11 +2,13 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import Database from 'better-sqlite3';
 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). */
@@ -27,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 };
 
@@ -79,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);
@@ -148,6 +162,7 @@ export function openDb(dbPath: string): LockedDatabase {
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   acquireAdvisoryLock(dbPath);
+  const Database = getDatabase();
   const db = new Database(dbPath) as unknown as LockedDatabase;
   db.pragma('journal_mode = WAL');
   db.pragma('busy_timeout = 5000');
@@ -208,6 +223,41 @@ export function closeDbDeferred(db: LockedDatabase): void {
   });
 }
 
+// ── 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();
@@ -258,35 +308,51 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
       { file: dbPath },
     );
   }
+  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.
  *
  * 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,
@@ -300,6 +366,21 @@ export function openRepo(
     }
     return { repo: opts.repo, close() {} };
   }
+
+  // Try native rusqlite path first (Phase 6.14)
+  if (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: ${(e as Error).message}`,
+      );
+    }
+  }
+
   const db = openReadonlyOrFail(customDbPath);
   return {
     repo: new SqliteRepository(db),
@@ -308,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
+        }
+      }
+    },
+  };
+}

package/src/db/index.ts

@@ -1,14 +1,17 @@
 // 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,
+  openReadonlyWithNative,
   openRepo,
 } from './connection.js';
 export { getBuildMeta, initSchema, MIGRATIONS, setBuildMeta } from './migrations.js';

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,
@@ -302,7 +304,8 @@ export function setBuildMeta(
   tx();
 }
 
-export function initSchema(db: BetterSqlite3Database): void {
+/** Run numbered migrations that haven't been applied yet. */
+function applyMigrations(db: BetterSqlite3Database): void {
   db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL DEFAULT 0)`);
 
   const row = db.prepare<{ version: number }>('SELECT version FROM schema_version').get();
@@ -320,40 +323,43 @@ export function initSchema(db: BetterSqlite3Database): void {
       currentVersion = migration.version;
     }
   }
+}
 
-  // Legacy column compat — add columns that may be missing from pre-migration DBs
+/** Ensure columns and indexes exist for pre-migration DBs (legacy compat). */
+function ensureLegacyColumns(db: BetterSqlite3Database): void {
   if (hasTable(db, 'nodes')) {
-    if (!hasColumn(db, 'nodes', 'end_line')) {
-      db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER');
-    }
-    if (!hasColumn(db, 'nodes', 'role')) {
-      db.exec('ALTER TABLE nodes ADD COLUMN role TEXT');
-    }
-    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_role ON nodes(role)');
-    if (!hasColumn(db, 'nodes', 'parent_id')) {
-      db.exec('ALTER TABLE nodes ADD COLUMN parent_id INTEGER REFERENCES nodes(id)');
-    }
-    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id)');
-    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_kind_parent ON nodes(kind, parent_id)');
-    if (!hasColumn(db, 'nodes', 'qualified_name')) {
-      db.exec('ALTER TABLE nodes ADD COLUMN qualified_name TEXT');
-    }
-    if (!hasColumn(db, 'nodes', 'scope')) {
-      db.exec('ALTER TABLE nodes ADD COLUMN scope TEXT');
-    }
-    if (!hasColumn(db, 'nodes', 'visibility')) {
-      db.exec('ALTER TABLE nodes ADD COLUMN visibility TEXT');
-    }
-    db.exec('UPDATE nodes SET qualified_name = name WHERE qualified_name IS NULL');
-    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name)');
-    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope)');
+    ensureNodeColumns(db);
   }
   if (hasTable(db, 'edges')) {
-    if (!hasColumn(db, 'edges', 'confidence')) {
-      db.exec('ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0');
-    }
-    if (!hasColumn(db, 'edges', 'dynamic')) {
-      db.exec('ALTER TABLE edges ADD COLUMN dynamic INTEGER DEFAULT 0');
-    }
+    ensureEdgeColumns(db);
   }
 }
+
+function ensureNodeColumns(db: BetterSqlite3Database): void {
+  const missing = (col: string) => !hasColumn(db, 'nodes', col);
+  if (missing('end_line')) db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER');
+  if (missing('role')) db.exec('ALTER TABLE nodes ADD COLUMN role TEXT');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_role ON nodes(role)');
+  if (missing('parent_id'))
+    db.exec('ALTER TABLE nodes ADD COLUMN parent_id INTEGER REFERENCES nodes(id)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_kind_parent ON nodes(kind, parent_id)');
+  if (missing('qualified_name')) db.exec('ALTER TABLE nodes ADD COLUMN qualified_name TEXT');
+  if (missing('scope')) db.exec('ALTER TABLE nodes ADD COLUMN scope TEXT');
+  if (missing('visibility')) db.exec('ALTER TABLE nodes ADD COLUMN visibility TEXT');
+  db.exec('UPDATE nodes SET qualified_name = name WHERE qualified_name IS NULL');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope)');
+}
+
+function ensureEdgeColumns(db: BetterSqlite3Database): void {
+  if (!hasColumn(db, 'edges', 'confidence'))
+    db.exec('ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0');
+  if (!hasColumn(db, 'edges', 'dynamic'))
+    db.exec('ALTER TABLE edges ADD COLUMN dynamic INTEGER DEFAULT 0');
+}
+
+export function initSchema(db: BetterSqlite3Database): void {
+  applyMigrations(db);
+  ensureLegacyColumns(db);
+}

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,