@optave/codegraph 3.5.0 → 3.6.0

package/src/domain/analysis/fn-impact.ts

@@ -4,13 +4,12 @@ import {
   findImplementors,
   findImportDependents,
   findNodeById,
-  openReadonlyOrFail,
 } from '../../db/index.js';
-import { loadConfig } from '../../infrastructure/config.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
 import { normalizeSymbol } from '../../shared/normalize.js';
 import { paginateResult } from '../../shared/paginate.js';
 import type { BetterSqlite3Database, NodeRow, RelatedNodeRow } from '../../types.js';
+import { resolveAnalysisOpts, withReadonlyDb } from './query-helpers.js';
 import { findMatchingNodes } from './symbol-lookup.js';
 
 // --- Shared BFS: transitive callers ---
@@ -36,6 +35,62 @@ function hasImplementsEdges(db: BetterSqlite3Database): boolean {
  * during traversal), its concrete implementors are also added to the frontier
  * so that changes to an interface signature propagate to all implementors.
  */
+type BfsLevel = Array<{
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  viaImplements?: boolean;
+}>;
+type BfsLevels = Record<number, BfsLevel>;
+type BfsOnVisit = (
+  caller: RelatedNodeRow & { viaImplements?: boolean },
+  parentId: number,
+  depth: number,
+) => void;
+
+/** Record an implementor node at the given depth, adding to frontier and levels. */
+function recordImplementor(
+  impl: RelatedNodeRow,
+  parentId: number,
+  depth: number,
+  visited: Set<number>,
+  frontier: number[],
+  levels: BfsLevels,
+  noTests: boolean,
+  onVisit?: BfsOnVisit,
+): void {
+  if (visited.has(impl.id) || (noTests && isTestFile(impl.file))) return;
+  visited.add(impl.id);
+  frontier.push(impl.id);
+  if (!levels[depth]) levels[depth] = [];
+  levels[depth].push({
+    name: impl.name,
+    kind: impl.kind,
+    file: impl.file,
+    line: impl.line,
+    viaImplements: true,
+  });
+  if (onVisit) onVisit({ ...impl, viaImplements: true }, parentId, depth);
+}
+
+/** Expand implementors for an interface/trait node into the BFS frontier. */
+function expandImplementors(
+  db: BetterSqlite3Database,
+  nodeId: number,
+  depth: number,
+  visited: Set<number>,
+  frontier: number[],
+  levels: BfsLevels,
+  noTests: boolean,
+  onVisit?: BfsOnVisit,
+): void {
+  const impls = findImplementors(db, nodeId) as RelatedNodeRow[];
+  for (const impl of impls) {
+    recordImplementor(impl, nodeId, depth, visited, frontier, levels, noTests, onVisit);
+  }
+}
+
 export function bfsTransitiveCallers(
   db: BetterSqlite3Database,
   startId: number,
@@ -48,50 +103,24 @@ export function bfsTransitiveCallers(
     noTests?: boolean;
     maxDepth?: number;
     includeImplementors?: boolean;
-    onVisit?: (
-      caller: RelatedNodeRow & { viaImplements?: boolean },
-      parentId: number,
-      depth: number,
-    ) => void;
+    onVisit?: BfsOnVisit;
   } = {},
 ) {
-  // Skip all implementor lookups when the graph has no implements edges
   const resolveImplementors = includeImplementors && hasImplementsEdges(db);
-
   const visited = new Set([startId]);
-  const levels: Record<
-    number,
-    Array<{ name: string; kind: string; file: string; line: number; viaImplements?: boolean }>
-  > = {};
+  const levels: BfsLevels = {};
   let frontier = [startId];
 
-  // Seed: if start node is an interface/trait, include its implementors at depth 1.
-  // Implementors go into a separate list so their callers appear at depth 2, not depth 1.
+  // Seed: if start node is an interface/trait, include its implementors at depth 1
   const implNextFrontier: number[] = [];
   if (resolveImplementors) {
     const startNode = findNodeById(db, startId) as NodeRow | undefined;
     if (startNode && INTERFACE_LIKE_KINDS.has(startNode.kind)) {
-      const impls = findImplementors(db, startId) as RelatedNodeRow[];
-      for (const impl of impls) {
-        if (!visited.has(impl.id) && (!noTests || !isTestFile(impl.file))) {
-          visited.add(impl.id);
-          implNextFrontier.push(impl.id);
-          if (!levels[1]) levels[1] = [];
-          levels[1].push({
-            name: impl.name,
-            kind: impl.kind,
-            file: impl.file,
-            line: impl.line,
-            viaImplements: true,
-          });
-          if (onVisit) onVisit({ ...impl, viaImplements: true }, startId, 1);
-        }
-      }
+      expandImplementors(db, startId, 1, visited, implNextFrontier, levels, noTests, onVisit);
     }
   }
 
   for (let d = 1; d <= maxDepth; d++) {
-    // On the first wave, merge seeded implementors so their callers appear at d=2
     if (d === 1 && implNextFrontier.length > 0) {
       frontier = [...frontier, ...implNextFrontier];
     }
@@ -106,27 +135,8 @@ export function bfsTransitiveCallers(
           levels[d]!.push({ name: c.name, kind: c.kind, file: c.file, line: c.line });
           if (onVisit) onVisit(c, fid, d);
         }
-
-        // If a caller is an interface/trait, also pull in its implementors
-        // Implementors are one extra hop away, so record at d+1
         if (resolveImplementors && INTERFACE_LIKE_KINDS.has(c.kind)) {
-          const impls = findImplementors(db, c.id) as RelatedNodeRow[];
-          for (const impl of impls) {
-            if (!visited.has(impl.id) && (!noTests || !isTestFile(impl.file))) {
-              visited.add(impl.id);
-              nextFrontier.push(impl.id);
-              const implDepth = d + 1;
-              if (!levels[implDepth]) levels[implDepth] = [];
-              levels[implDepth].push({
-                name: impl.name,
-                kind: impl.kind,
-                file: impl.file,
-                line: impl.line,
-                viaImplements: true,
-              });
-              if (onVisit) onVisit({ ...impl, viaImplements: true }, c.id, implDepth);
-            }
-          }
+          expandImplementors(db, c.id, d + 1, visited, nextFrontier, levels, noTests, onVisit);
         }
       }
     }
@@ -142,8 +152,7 @@ export function impactAnalysisData(
   customDbPath: string,
   opts: { noTests?: boolean } = {},
 ) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
+  return withReadonlyDb(customDbPath, (db) => {
     const noTests = opts.noTests || false;
     const fileNodes = findFileNodes(db, `%${file}%`) as NodeRow[];
     if (fileNodes.length === 0) {
@@ -187,9 +196,7 @@ export function impactAnalysisData(
       levels: byLevel,
       totalDependents: visited.size - fileNodes.length,
     };
-  } finally {
-    db.close();
-  }
+  });
 }
 
 export function fnImpactData(
@@ -206,11 +213,9 @@ export function fnImpactData(
     config?: any;
   } = {},
 ) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
-    const config = opts.config || loadConfig();
+  return withReadonlyDb(customDbPath, (db) => {
+    const { noTests, config } = resolveAnalysisOpts(opts);
     const maxDepth = opts.depth || config.analysis?.fnImpactDepth || 5;
-    const noTests = opts.noTests || false;
     const hc = new Map();
 
     const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
@@ -235,7 +240,5 @@ export function fnImpactData(
 
     const base = { name, results };
     return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
-  } finally {
-    db.close();
-  }
+  });
 }

package/src/domain/analysis/module-map.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { openReadonlyOrFail, testFilterSQL } from '../../db/index.js';
+import { openReadonlyOrFail, openReadonlyWithNative, testFilterSQL } from '../../db/index.js';
 import { cachedStmt } from '../../db/repository/cached-stmt.js';
 import { loadConfig } from '../../infrastructure/config.js';
 import { debug } from '../../infrastructure/logger.js';
@@ -381,20 +381,115 @@ export function moduleMapData(customDbPath: string, limit = 20, opts: { noTests?
 }
 
 export function statsData(customDbPath: string, opts: { noTests?: boolean; config?: any } = {}) {
-  const db = openReadonlyOrFail(customDbPath);
+  const { db, nativeDb, close } = openReadonlyWithNative(customDbPath);
   try {
     const noTests = opts.noTests || false;
     const config = opts.config || loadConfig();
-    const testFilter = testFilterSQL('n.file', noTests);
 
+    // These always need JS (non-SQL logic)
+    const files = countFilesByLanguage(db, noTests);
+    const fileCycles = findCycles(db, { fileLevel: true, noTests });
+    const fnCycles = findCycles(db, { fileLevel: false, noTests });
+
+    // ── Native fast path: batch all SQL aggregations in one napi call ──
+    if (nativeDb?.getGraphStats) {
+      const s = nativeDb.getGraphStats(noTests);
+      const nodesByKind: Record<string, number> = {};
+      for (const k of s.nodesByKind) nodesByKind[k.kind] = k.count;
+      const edgesByKind: Record<string, number> = {};
+      for (const k of s.edgesByKind) edgesByKind[k.kind] = k.count;
+      const roles: Record<string, number> & { dead?: number } = {};
+      let deadTotal = 0;
+      for (const r of s.roleCounts) {
+        roles[r.role] = r.count;
+        if (r.role.startsWith(DEAD_ROLE_PREFIX)) deadTotal += r.count;
+      }
+      if (deadTotal > 0) roles.dead = deadTotal;
+
+      const callerCoverage =
+        s.quality.callableTotal > 0 ? s.quality.callableWithCallers / s.quality.callableTotal : 0;
+      const callConfidence =
+        s.quality.callEdges > 0 ? s.quality.highConfCallEdges / s.quality.callEdges : 0;
+
+      // False-positive analysis still uses JS (needs FALSE_POSITIVE_NAMES set)
+      const fpThreshold = config.analysis?.falsePositiveCallers ?? FALSE_POSITIVE_CALLER_THRESHOLD;
+      const fpRows = db
+        .prepare(`
+          SELECT n.name, n.file, n.line, COUNT(e.source_id) as caller_count
+          FROM nodes n
+          LEFT JOIN edges e ON n.id = e.target_id AND e.kind = 'calls'
+          WHERE n.kind IN ('function', 'method')
+          GROUP BY n.id
+          HAVING caller_count > ?
+          ORDER BY caller_count DESC
+        `)
+        .all(fpThreshold) as Array<{
+        name: string;
+        file: string;
+        line: number;
+        caller_count: number;
+      }>;
+      const falsePositiveWarnings = fpRows
+        .filter((r) =>
+          FALSE_POSITIVE_NAMES.has(r.name.includes('.') ? r.name.split('.').pop()! : r.name),
+        )
+        .map((r) => ({ name: r.name, file: r.file, line: r.line, callerCount: r.caller_count }));
+      let fpEdgeCount = 0;
+      for (const fp of falsePositiveWarnings) fpEdgeCount += fp.callerCount;
+      const falsePositiveRatio = s.quality.callEdges > 0 ? fpEdgeCount / s.quality.callEdges : 0;
+      const score = Math.round(
+        callerCoverage * 40 + callConfidence * 40 + (1 - falsePositiveRatio) * 20,
+      );
+
+      return {
+        nodes: { total: s.totalNodes, byKind: nodesByKind },
+        edges: { total: s.totalEdges, byKind: edgesByKind },
+        files,
+        cycles: { fileLevel: fileCycles.length, functionLevel: fnCycles.length },
+        hotspots: s.hotspots.map((h) => ({ file: h.file, fanIn: h.fanIn, fanOut: h.fanOut })),
+        embeddings: s.embeddings
+          ? {
+              count: s.embeddings.count,
+              model: s.embeddings.model,
+              dim: s.embeddings.dim,
+              builtAt: s.embeddings.builtAt,
+            }
+          : null,
+        quality: {
+          score,
+          callerCoverage: {
+            ratio: callerCoverage,
+            covered: s.quality.callableWithCallers,
+            total: s.quality.callableTotal,
+          },
+          callConfidence: {
+            ratio: callConfidence,
+            highConf: s.quality.highConfCallEdges,
+            total: s.quality.callEdges,
+          },
+          falsePositiveWarnings,
+        },
+        roles,
+        complexity: s.complexity
+          ? {
+              analyzed: s.complexity.analyzed,
+              avgCognitive: s.complexity.avgCognitive,
+              avgCyclomatic: s.complexity.avgCyclomatic,
+              maxCognitive: s.complexity.maxCognitive,
+              maxCyclomatic: s.complexity.maxCyclomatic,
+              avgMI: s.complexity.avgMi,
+              minMI: s.complexity.minMi,
+            }
+          : null,
+      };
+    }
+
+    // ── JS fallback ───────────────────────────────────────────────────
+    const testFilter = testFilterSQL('n.file', noTests);
     const testFileIds = noTests ? buildTestFileIds(db) : null;
 
     const { total: totalNodes, byKind: nodesByKind } = countNodesByKind(db, testFileIds);
     const { total: totalEdges, byKind: edgesByKind } = countEdgesByKind(db, testFileIds);
-    const files = countFilesByLanguage(db, noTests);
-
-    const fileCycles = findCycles(db, { fileLevel: true, noTests });
-    const fnCycles = findCycles(db, { fileLevel: false, noTests });
 
     const hotspots = findHotspots(db, noTests, 5);
     const embeddings = getEmbeddingsInfo(db);
@@ -415,6 +510,6 @@ export function statsData(customDbPath: string, opts: { noTests?: boolean; confi
       complexity,
     };
   } finally {
-    db.close();
+    close();
   }
 }

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);
 }