@optave/codegraph 3.5.0 → 3.7.0

package/src/domain/analysis/query-helpers.ts

@@ -0,0 +1,35 @@
+import { openReadonlyOrFail } from '../../db/index.js';
+import { loadConfig } from '../../infrastructure/config.js';
+import type { BetterSqlite3Database, CodegraphConfig } from '../../types.js';
+
+/**
+ * Open a readonly DB connection, run `fn`, and close the DB on completion.
+ * Eliminates the duplicated `openReadonlyOrFail` + `try/finally/db.close()` pattern
+ * that appears in every analysis query function.
+ */
+export function withReadonlyDb<T>(
+  customDbPath: string | undefined,
+  fn: (db: BetterSqlite3Database) => T,
+): T {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    return fn(db);
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Resolve common analysis options into a normalized form.
+ * Shared across fn-impact, context, dependencies, and exports modules.
+ */
+export function resolveAnalysisOpts(opts: { noTests?: boolean; config?: CodegraphConfig }): {
+  noTests: boolean;
+  config: CodegraphConfig;
+  displayOpts: Record<string, unknown>;
+} {
+  const noTests = opts.noTests || false;
+  const config = opts.config || loadConfig();
+  const displayOpts = config.display || {};
+  return { noTests, config, displayOpts };
+}

package/src/domain/graph/builder/helpers.ts

@@ -47,6 +47,17 @@ export const BUILTIN_RECEIVERS: Set<string> = new Set([
   'require',
 ]);
 
+/** Check if a directory entry should be skipped (ignored dirs, dotfiles). */
+function shouldSkipEntry(entry: fs.Dirent, extraIgnore: Set<string> | null): boolean {
+  if (entry.name.startsWith('.') && entry.name !== '.') {
+    if (IGNORE_DIRS.has(entry.name)) return true;
+    if (entry.isDirectory()) return true;
+  }
+  if (IGNORE_DIRS.has(entry.name)) return true;
+  if (extraIgnore?.has(entry.name)) return true;
+  return false;
+}
+
 /**
  * Recursively collect all source files under `dir`.
  * When `directories` is a Set, also tracks which directories contain files.
@@ -100,12 +111,7 @@ export function collectFiles(
   }
 
   for (const entry of entries) {
-    if (entry.name.startsWith('.') && entry.name !== '.') {
-      if (IGNORE_DIRS.has(entry.name)) continue;
-      if (entry.isDirectory()) continue;
-    }
-    if (IGNORE_DIRS.has(entry.name)) continue;
-    if (extraIgnore?.has(entry.name)) continue;
+    if (shouldSkipEntry(entry, extraIgnore)) continue;
 
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {

package/src/domain/graph/builder/incremental.ts

@@ -10,7 +10,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { bulkNodeIdsByFile } from '../../../db/index.js';
-import { warn } from '../../../infrastructure/logger.js';
+import { debug, warn } from '../../../infrastructure/logger.js';
 import { normalizePath } from '../../../shared/constants.js';
 import type {
   BetterSqlite3Database,
@@ -154,7 +154,8 @@ async function parseReverseDep(
   let code: string;
   try {
     code = readFileSafe(absPath);
-  } catch {
+  } catch (e: unknown) {
+    debug(`parseReverseDep: cannot read ${absPath}: ${e instanceof Error ? e.message : String(e)}`);
     return null;
   }
 

package/src/domain/graph/builder/pipeline.ts

@@ -35,6 +35,18 @@ function initializeEngine(ctx: PipelineContext): void {
     dataflow: ctx.opts.dataflow !== false,
     ast: ctx.opts.ast !== false,
     nativeDb: ctx.nativeDb,
+    // WAL checkpoint callbacks for dual-connection WAL guard (#696).
+    // Feature modules (ast, cfg, complexity, dataflow) receive `db` as a
+    // parameter and cannot tolerate close/reopen (stale reference). Instead,
+    // checkpoint the WAL so native writes start with a clean slate. Features
+    // return early on native success and never read native-written WAL data
+    // through the JS connection, so a post-write checkpoint is unnecessary.
+    suspendJsDb: ctx.nativeDb
+      ? () => {
+          ctx.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+      : undefined,
+    resumeJsDb: ctx.nativeDb ? () => {} : undefined,
   };
   const { name: engineName, version: engineVersion } = getActiveEngine(ctx.engineOpts);
   ctx.engineName = engineName as 'native' | 'wasm';
@@ -48,9 +60,11 @@ function checkEngineSchemaMismatch(ctx: PipelineContext): void {
   ctx.forceFullRebuild = false;
   if (!ctx.incremental) return;
 
-  // Route metadata reads through NativeDatabase when available (Phase 6.13)
+  // Route metadata reads through NativeDatabase only when using the native engine,
+  // to avoid dual-SQLite WAL conflicts (rusqlite + better-sqlite3 on same file).
+  const useNativeDb = ctx.engineName === 'native' && !!ctx.nativeDb;
   const meta = (key: string): string | null =>
-    ctx.nativeDb ? ctx.nativeDb.getBuildMeta(key) : getBuildMeta(ctx.db, key);
+    useNativeDb ? ctx.nativeDb!.getBuildMeta(key) : getBuildMeta(ctx.db, key);
 
   const prevEngine = meta('engine');
   if (prevEngine && prevEngine !== ctx.engineName) {
@@ -109,8 +123,10 @@ function setupPipeline(ctx: PipelineContext): void {
     } catch (err) {
       warn(`NativeDatabase init failed, falling back to JS: ${(err as Error).message}`);
       ctx.nativeDb = undefined;
-      initSchema(ctx.db);
     }
+    // Always run JS initSchema so better-sqlite3 sees the schema —
+    // nativeDb is closed during pipeline stages and reopened for analyses.
+    initSchema(ctx.db);
   } else {
     initSchema(ctx.db);
   }
@@ -156,6 +172,26 @@ function formatTimingResult(ctx: PipelineContext): BuildResult {
 // ── Pipeline stages execution ───────────────────────────────────────────
 
 async function runPipelineStages(ctx: PipelineContext): Promise<void> {
+  // Prevent dual-connection WAL corruption during pipeline stages: when both
+  // better-sqlite3 (ctx.db) and rusqlite (ctx.nativeDb) are open to the same
+  // WAL-mode file, native writes corrupt the DB. Close nativeDb so stages
+  // use JS fallback paths. Reopened before runAnalyses for feature modules
+  // that use suspendJsDb/resumeJsDb WAL checkpoint pattern (#696).
+  const hadNativeDb = !!ctx.nativeDb;
+  if (ctx.db && ctx.nativeDb) {
+    try {
+      ctx.nativeDb.close();
+    } catch {
+      /* ignore close errors */
+    }
+    ctx.nativeDb = undefined;
+    // Also clear stale reference in engineOpts to prevent stages from
+    // calling methods on the closed NativeDatabase.
+    if (ctx.engineOpts?.nativeDb) {
+      ctx.engineOpts.nativeDb = undefined;
+    }
+  }
+
   await collectFiles(ctx);
   await detectChanges(ctx);
 
@@ -166,7 +202,39 @@ async function runPipelineStages(ctx: PipelineContext): Promise<void> {
   await resolveImports(ctx);
   await buildEdges(ctx);
   await buildStructure(ctx);
+
+  // Reopen nativeDb for feature modules (ast, cfg, complexity, dataflow)
+  // which use suspendJsDb/resumeJsDb WAL checkpoint before native writes.
+  if (hadNativeDb) {
+    const native = loadNative();
+    if (native?.NativeDatabase) {
+      try {
+        ctx.nativeDb = native.NativeDatabase.openReadWrite(ctx.dbPath);
+        if (ctx.engineOpts) {
+          ctx.engineOpts.nativeDb = ctx.nativeDb;
+        }
+      } catch {
+        ctx.nativeDb = undefined;
+        if (ctx.engineOpts) {
+          ctx.engineOpts.nativeDb = undefined;
+        }
+      }
+    }
+  }
+
   await runAnalyses(ctx);
+
+  // Close nativeDb after analyses — finalize uses JS paths for setBuildMeta
+  // and closeDbPair handles cleanup. Avoids dual-connection during finalize.
+  if (ctx.nativeDb) {
+    try {
+      ctx.nativeDb.close();
+    } catch {
+      /* ignore close errors */
+    }
+    ctx.nativeDb = undefined;
+  }
+
   await finalize(ctx);
 }
 

package/src/domain/graph/builder/stages/build-edges.ts

@@ -6,9 +6,9 @@
  */
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { getNodeId } from '#db/index.js';
-import { debug } from '#infrastructure/logger.js';
-import { loadNative } from '#infrastructure/native.js';
+import { getNodeId } from '../../../../db/index.js';
+import { debug } from '../../../../infrastructure/logger.js';
+import { loadNative } from '../../../../infrastructure/native.js';
 import type {
   BetterSqlite3Database,
   Call,
@@ -18,10 +18,11 @@ import type {
   NativeAddon,
   NodeRow,
   TypeMapEntry,
-} from '#types';
+} from '../../../../types.js';
 import { computeConfidence } from '../../resolve.js';
 import type { PipelineContext } from '../context.js';
 import { BUILTIN_RECEIVERS, batchInsertEdges } from '../helpers.js';
+
 import { getResolved, isBarrelFile, resolveBarrelExport } from './resolve-imports.js';
 
 // ── Local types ──────────────────────────────────────────────────────────
@@ -61,12 +62,6 @@ interface NativeEdge {
   dynamic: number;
 }
 
-/** TypeMap entry used in receiver supplement (normalized from native format). */
-interface NormalizedTypeEntry {
-  type: string;
-  confidence: number;
-}
-
 // ── Node lookup setup ───────────────────────────────────────────────────
 
 function makeGetNodeIdStmt(db: BetterSqlite3Database): NodeIdStmt {
@@ -210,14 +205,6 @@ function buildCallEdgesNative(
   for (const e of nativeEdges) {
     allEdgeRows.push([e.sourceId, e.targetId, e.kind, e.confidence, e.dynamic]);
   }
-
-  // Older native binaries (< 3.2.0) don't emit receiver or type-resolved method-call
-  // edges. Supplement them on the JS side if the native binary missed them.
-  // TODO: Remove once all published native binaries handle receivers (>= 3.2.0)
-  const hasReceiver = nativeEdges.some((e) => e.kind === 'receiver');
-  if (!hasReceiver) {
-    supplementReceiverEdges(ctx, nativeFiles, getNodeIdStmt, allEdgeRows);
-  }
 }
 
 function buildImportedNamesForNative(
@@ -242,58 +229,6 @@ function buildImportedNamesForNative(
   return importedNames;
 }
 
-// ── Receiver edge supplement for older native binaries ──────────────────
-
-function supplementReceiverEdges(
-  ctx: PipelineContext,
-  nativeFiles: NativeFileEntry[],
-  getNodeIdStmt: NodeIdStmt,
-  allEdgeRows: EdgeRowTuple[],
-): void {
-  const seenCallEdges = new Set<string>();
-  // Collect existing edges to avoid duplicates
-  for (const row of allEdgeRows) {
-    seenCallEdges.add(`${row[0]}|${row[1]}|${row[2]}`);
-  }
-
-  for (const nf of nativeFiles) {
-    const relPath = nf.file;
-    const typeMap = new Map<string, NormalizedTypeEntry>(
-      nf.typeMap.map((t) => [t.name, { type: t.typeName, confidence: t.confidence ?? 0.9 }]),
-    );
-    const fileNodeRow = { id: nf.fileNodeId };
-
-    for (const call of nf.calls) {
-      if (!call.receiver || BUILTIN_RECEIVERS.has(call.receiver)) continue;
-      if (call.receiver === 'this' || call.receiver === 'self' || call.receiver === 'super')
-        continue;
-
-      const caller = findCaller(call, nf.definitions, relPath, getNodeIdStmt, fileNodeRow);
-
-      // Receiver edge: caller → receiver type node
-      buildReceiverEdge(ctx, call, caller, relPath, seenCallEdges, allEdgeRows, typeMap);
-
-      // Type-resolved method call: caller → Type.method
-      const typeEntry = typeMap.get(call.receiver);
-      const typeName = typeEntry ? typeEntry.type : null;
-      if (typeName) {
-        const qualifiedName = `${typeName}.${call.name}`;
-        const targets = (ctx.nodesByName.get(qualifiedName) || []).filter(
-          (n) => n.kind === 'method',
-        );
-        for (const t of targets) {
-          const key = `${caller.id}|${t.id}|calls`;
-          if (t.id !== caller.id && !seenCallEdges.has(key)) {
-            seenCallEdges.add(key);
-            const confidence = computeConfidence(relPath, t.file, null);
-            allEdgeRows.push([caller.id, t.id, 'calls', confidence, call.dynamic ? 1 : 0]);
-          }
-        }
-      }
-    }
-  }
-}
-
 // ── Call edges (JS fallback) ────────────────────────────────────────────
 
 function buildCallEdgesJS(
@@ -495,7 +430,7 @@ function buildReceiverEdge(
   relPath: string,
   seenCallEdges: Set<string>,
   allEdgeRows: EdgeRowTuple[],
-  typeMap: Map<string, TypeMapEntry | NormalizedTypeEntry | string>,
+  typeMap: Map<string, TypeMapEntry | string>,
 ): void {
   const receiverKinds = new Set(['class', 'struct', 'interface', 'type', 'module']);
   const typeEntry = typeMap?.get(call.receiver!);
@@ -608,7 +543,7 @@ function loadNodes(ctx: PipelineContext): { rows: QueryNodeRow[]; scoped: boolea
 
 /**
  * For scoped node loading, patch nodesByName.get with a lazy SQL fallback
- * so global name-only lookups (resolveByMethodOrGlobal, supplementReceiverEdges)
+ * so global name-only lookups (resolveByMethodOrGlobal)
  * can still find nodes outside the scoped set.
  */
 function addLazyFallback(ctx: PipelineContext, scopedLoad: boolean): void {
@@ -673,7 +608,7 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
 
     // When using native edge insert, skip JS insert here — do it after tx commits.
     // Otherwise insert edges within this transaction for atomicity.
-    const useNativeEdgeInsert = !!ctx.nativeDb?.bulkInsertEdges;
+    const useNativeEdgeInsert = ctx.engineName === 'native' && !!ctx.nativeDb?.bulkInsertEdges;
     if (!useNativeEdgeInsert) {
       batchInsertEdges(db, allEdgeRows);
     }
@@ -683,7 +618,7 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
   // Phase 2: Native rusqlite bulk insert (outside better-sqlite3 transaction
   // to avoid SQLITE_BUSY contention). Uses NativeDatabase persistent connection.
   // Standalone napi functions were removed in 6.17.
-  if (ctx.nativeDb?.bulkInsertEdges && allEdgeRows.length > 0) {
+  if (ctx.engineName === 'native' && ctx.nativeDb?.bulkInsertEdges && allEdgeRows.length > 0) {
     const nativeEdges = allEdgeRows.map((r) => ({
       sourceId: r[0],
       targetId: r[1],
@@ -694,7 +629,7 @@ export async function buildEdges(ctx: PipelineContext): Promise<void> {
     const ok = ctx.nativeDb.bulkInsertEdges(nativeEdges);
     if (!ok) {
       debug('Native bulkInsertEdges failed — falling back to JS batchInsertEdges');
-      batchInsertEdges(db, allEdgeRows);
+      batchInsertEdges(ctx.db, allEdgeRows);
     }
   }
 

package/src/domain/graph/builder/stages/build-structure.ts

@@ -5,9 +5,9 @@
  */
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { debug } from '#infrastructure/logger.js';
-import { normalizePath } from '#shared/constants.js';
-import type { ExtractorOutput } from '#types';
+import { debug } from '../../../../infrastructure/logger.js';
+import { normalizePath } from '../../../../shared/constants.js';
+import type { ExtractorOutput } from '../../../../types.js';
 import type { PipelineContext } from '../context.js';
 import { readFileSafe } from '../helpers.js';
 
@@ -39,10 +39,11 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   // loading ALL definitions from DB (~8ms) and recomputing ALL metrics (~15ms).
   // Gate: ≤5 changed files AND significantly more existing files (>20) to
   // avoid triggering on small test fixtures where directory metrics matter.
+  const useNativeReads = ctx.engineName === 'native' && !!ctx.nativeDb;
   const existingFileCount = !isFullBuild
     ? (
-        (ctx.nativeDb
-          ? ctx.nativeDb.queryGet("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'", [])
+        (useNativeReads
+          ? ctx.nativeDb!.queryGet("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'", [])
           : db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get()) as {
           c: number;
         }
@@ -96,7 +97,8 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
 
     // Use NativeDatabase persistent connection (Phase 6.15+).
     // Standalone napi functions were removed in 6.17 — falls through to JS if nativeDb unavailable.
-    if (ctx.nativeDb?.classifyRolesFull) {
+    // Note: classifyRoles* both read (fan-in/fan-out) and write (UPDATE nodes SET role).
+    if (useNativeReads && ctx.nativeDb?.classifyRolesFull) {
       const nativeResult =
         changedFileList && changedFileList.length > 0
           ? ctx.nativeDb.classifyRolesIncremental(changedFileList)
@@ -126,7 +128,7 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
           changedFiles?: string[] | null,
         ) => Record<string, number>;
       };
-      roleSummary = classifyNodeRoles(db, changedFileList);
+      roleSummary = classifyNodeRoles(ctx.db, changedFileList);
     }
 
     debug(

package/src/domain/graph/builder/stages/collect-files.ts

@@ -7,8 +7,8 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { debug, info } from '#infrastructure/logger.js';
-import { normalizePath } from '#shared/constants.js';
+import { debug, info } from '../../../../infrastructure/logger.js';
+import { normalizePath } from '../../../../shared/constants.js';
 import { readJournal } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
 import { collectFiles as collectFilesUtil } from '../helpers.js';

package/src/domain/graph/builder/stages/detect-changes.ts

@@ -338,7 +338,7 @@ function purgeAndAddReverseDeps(
   if (hasPurge || hasReverseDeps) {
     const filesToPurge = hasPurge ? [...ctx.removed, ...changePaths] : [];
     // Prefer NativeDatabase: purge + reverse-dep edge deletion in one transaction (#670)
-    if (ctx.nativeDb?.purgeFilesData) {
+    if (ctx.engineName === 'native' && ctx.nativeDb?.purgeFilesData) {
       ctx.nativeDb.purgeFilesData(filesToPurge, false, hasReverseDeps ? reverseDepList : undefined);
     } else {
       if (hasPurge) {
@@ -433,7 +433,12 @@ export async function detectChanges(ctx: PipelineContext): Promise<void> {
   }
   const increResult =
     incremental && !forceFullRebuild
-      ? getChangedFiles(db, allFiles, rootDir, ctx.nativeDb)
+      ? getChangedFiles(
+          db,
+          allFiles,
+          rootDir,
+          ctx.engineName === 'native' ? ctx.nativeDb : undefined,
+        )
       : {
           changed: allFiles.map((f): ChangedFile => ({ file: f })),
           removed: [] as string[],