@optave/codegraph 3.5.0 → 3.7.0

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
+        }
+      }
+    },
+  };
+}

package/src/db/index.ts

@@ -11,6 +11,7 @@ export {
   flushDeferredClose,
   openDb,
   openReadonlyOrFail,
+  openReadonlyWithNative,
   openRepo,
 } from './connection.js';
 export { getBuildMeta, initSchema, MIGRATIONS, setBuildMeta } from './migrations.js';

package/src/db/migrations.ts

@@ -304,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();
@@ -322,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/domain/analysis/context.ts

@@ -15,10 +15,8 @@ import {
   getComplexityForNode,
   getLineCountForNode,
   getMaxEndLineForFile,
-  openReadonlyOrFail,
 } from '../../db/index.js';
 import { cachedStmt } from '../../db/repository/cached-stmt.js';
-import { loadConfig } from '../../infrastructure/config.js';
 import { debug } from '../../infrastructure/logger.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import {
@@ -40,6 +38,7 @@ import type {
   RelatedNodeRow,
   StmtCache,
 } from '../../types.js';
+import { resolveAnalysisOpts, withReadonlyDb } from './query-helpers.js';
 import { findMatchingNodes } from './symbol-lookup.js';
 
 interface DisplayOpts {
@@ -52,6 +51,60 @@ interface DisplayOpts {
   [key: string]: unknown;
 }
 
+/** Format a callee row into the output shape with summary and source. */
+function formatCalleeRow(
+  c: RelatedNodeRow,
+  repoRoot: string,
+  getFileLines: (file: string) => string[] | null,
+  displayOpts: DisplayOpts,
+  includeSource: boolean,
+) {
+  const cLines = getFileLines(c.file);
+  return {
+    name: c.name,
+    kind: c.kind,
+    file: c.file,
+    line: c.line,
+    endLine: c.end_line || null,
+    summary: cLines ? extractSummary(cLines, c.line, displayOpts) : null,
+    source: includeSource
+      ? readSourceRange(repoRoot, c.file, c.line, c.end_line ?? undefined, displayOpts)
+      : null,
+  };
+}
+
+/** BFS to collect deeper callees beyond the first level. */
+function collectDeeperCallees(
+  db: BetterSqlite3Database,
+  startIds: number[],
+  rootId: number,
+  repoRoot: string,
+  getFileLines: (file: string) => string[] | null,
+  opts: { noTests: boolean; maxDepth: number; displayOpts: DisplayOpts },
+) {
+  const { noTests, maxDepth, displayOpts } = opts;
+  const visited = new Set(startIds);
+  visited.add(rootId);
+  let frontier = [...startIds];
+  const result: ReturnType<typeof formatCalleeRow>[] = [];
+
+  for (let d = 2; d <= maxDepth; d++) {
+    const nextFrontier: number[] = [];
+    for (const fid of frontier) {
+      const deeper = findCallees(db, fid) as RelatedNodeRow[];
+      for (const c of deeper) {
+        if (visited.has(c.id) || (noTests && isTestFile(c.file))) continue;
+        visited.add(c.id);
+        nextFrontier.push(c.id);
+        result.push(formatCalleeRow(c, repoRoot, getFileLines, displayOpts, true));
+      }
+    }
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+  }
+  return result;
+}
+
 function buildCallees(
   db: BetterSqlite3Database,
   node: NodeRow,
@@ -63,65 +116,20 @@ function buildCallees(
   const calleeRows = findCallees(db, node.id) as RelatedNodeRow[];
   const filteredCallees = noTests ? calleeRows.filter((c) => !isTestFile(c.file)) : calleeRows;
 
-  const callees = filteredCallees.map((c) => {
-    const cLines = getFileLines(c.file);
-    const summary = cLines ? extractSummary(cLines, c.line, displayOpts) : null;
-    let calleeSource: string | null = null;
-    if (depth >= 1) {
-      calleeSource = readSourceRange(
-        repoRoot,
-        c.file,
-        c.line,
-        c.end_line ?? undefined,
-        displayOpts,
-      );
-    }
-    return {
-      name: c.name,
-      kind: c.kind,
-      file: c.file,
-      line: c.line,
-      endLine: c.end_line || null,
-      summary,
-      source: calleeSource,
-    };
-  });
+  const callees = filteredCallees.map((c) =>
+    formatCalleeRow(c, repoRoot, getFileLines, displayOpts, depth >= 1),
+  );
 
   if (depth > 1) {
-    const visited = new Set(filteredCallees.map((c) => c.id));
-    visited.add(node.id);
-    let frontier = filteredCallees.map((c) => c.id);
-    const maxDepth = Math.min(depth, 5);
-    for (let d = 2; d <= maxDepth; d++) {
-      const nextFrontier: number[] = [];
-      for (const fid of frontier) {
-        const deeper = findCallees(db, fid) as RelatedNodeRow[];
-        for (const c of deeper) {
-          if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
-            visited.add(c.id);
-            nextFrontier.push(c.id);
-            const cLines = getFileLines(c.file);
-            callees.push({
-              name: c.name,
-              kind: c.kind,
-              file: c.file,
-              line: c.line,
-              endLine: c.end_line || null,
-              summary: cLines ? extractSummary(cLines, c.line, displayOpts) : null,
-              source: readSourceRange(
-                repoRoot,
-                c.file,
-                c.line,
-                c.end_line ?? undefined,
-                displayOpts,
-              ),
-            });
-          }
-        }
-      }
-      frontier = nextFrontier;
-      if (frontier.length === 0) break;
-    }
+    const deeper = collectDeeperCallees(
+      db,
+      filteredCallees.map((c) => c.id),
+      node.id,
+      repoRoot,
+      getFileLines,
+      { noTests, maxDepth: Math.min(depth, 5), displayOpts },
+    );
+    callees.push(...deeper);
   }
 
   return callees;
@@ -433,15 +441,12 @@ export function contextData(
     config?: any;
   } = {},
 ) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
+  return withReadonlyDb(customDbPath, (db) => {
     const depth = opts.depth || 0;
     const noSource = opts.noSource || false;
-    const noTests = opts.noTests || false;
     const includeTests = opts.includeTests || false;
 
-    const config = opts.config || loadConfig();
-    const displayOpts: DisplayOpts = config.display || {};
+    const { noTests, displayOpts } = resolveAnalysisOpts(opts);
 
     const dbPath = findDbPath(customDbPath);
     const repoRoot = path.resolve(path.dirname(dbPath), '..');
@@ -494,9 +499,7 @@ export function contextData(
 
     const base = { name, results };
     return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
-  } finally {
-    db.close();
-  }
+  });
 }
 
 export function explainData(
@@ -510,14 +513,11 @@ export function explainData(
     config?: any;
   } = {},
 ) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
-    const noTests = opts.noTests || false;
+  return withReadonlyDb(customDbPath, (db) => {
     const depth = opts.depth || 0;
     const kind = isFileLikeTarget(target) ? 'file' : 'function';
 
-    const config = opts.config || loadConfig();
-    const displayOpts: DisplayOpts = config.display || {};
+    const { noTests, displayOpts } = resolveAnalysisOpts(opts);
 
     const dbPath = findDbPath(customDbPath);
     const repoRoot = path.resolve(path.dirname(dbPath), '..');
@@ -536,7 +536,5 @@ export function explainData(
 
     const base = { target, kind, results };
     return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
-  } finally {
-    db.close();
-  }
+  });
 }