@optave/codegraph 3.8.0 → 3.8.1

package/src/db/connection.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 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 { DbError, toErrorMessage } from '../shared/errors.js';
 import type { BetterSqlite3Database, NativeDatabase } from '../types.js';
 import { getDatabase } from './better-sqlite3.js';
 import { Repository } from './repository/base.js';
@@ -20,7 +20,8 @@ function getPackageVersion(): string {
     const pkgPath = path.join(connDir, '..', '..', 'package.json');
     _packageVersion = (JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version: string })
       .version;
-  } catch {
+  } catch (e) {
+    debug(`Failed to read package version: ${toErrorMessage(e)}`);
     _packageVersion = '';
   }
   return _packageVersion;
@@ -41,8 +42,8 @@ function warnOnVersionMismatch(getBuildVersion: () => string | undefined | null)
         `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
+  } catch (e) {
+    debug(`Version mismatch check skipped (build_meta may not exist): ${toErrorMessage(e)}`);
   }
 }
 
@@ -78,11 +79,11 @@ export function findRepoRoot(fromDir?: string): string | null {
     try {
       root = fs.realpathSync(raw);
     } catch (e) {
-      debug(`realpathSync failed for git root "${raw}", using resolve: ${(e as Error).message}`);
+      debug(`realpathSync failed for git root "${raw}", using resolve: ${toErrorMessage(e)}`);
       root = path.resolve(raw);
     }
   } catch (e) {
-    debug(`git rev-parse failed for "${dir}": ${(e as Error).message}`);
+    debug(`git rev-parse failed for "${dir}": ${toErrorMessage(e)}`);
     root = null;
   }
   if (!fromDir) {
@@ -103,7 +104,7 @@ function isProcessAlive(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (e) {
-    debug(`PID ${pid} not alive: ${(e as NodeJS.ErrnoException).code || (e as Error).message}`);
+    debug(`PID ${pid} not alive: ${(e as NodeJS.ErrnoException).code || toErrorMessage(e)}`);
     return false;
   }
 }
@@ -119,12 +120,12 @@ function acquireAdvisoryLock(dbPath: string): void {
       }
     }
   } catch (e) {
-    debug(`Advisory lock read failed: ${(e as Error).message}`);
+    debug(`Advisory lock read failed: ${toErrorMessage(e)}`);
   }
   try {
     fs.writeFileSync(lockPath, String(process.pid), 'utf-8');
   } catch (e) {
-    debug(`Advisory lock write failed: ${(e as Error).message}`);
+    debug(`Advisory lock write failed: ${toErrorMessage(e)}`);
   }
 }
 
@@ -135,7 +136,7 @@ function releaseAdvisoryLock(lockPath: string): void {
       fs.unlinkSync(lockPath);
     }
   } catch (e) {
-    debug(`Advisory lock release failed for ${lockPath}: ${(e as Error).message}`);
+    debug(`Advisory lock release failed for ${lockPath}: ${toErrorMessage(e)}`);
   }
 }
 
@@ -151,7 +152,7 @@ function isSameDirectory(a: string, b: string): boolean {
     const sb = fs.statSync(b);
     return sa.dev === sb.dev && sa.ino === sb.ino;
   } catch (e) {
-    debug(`isSameDirectory stat failed: ${(e as Error).message}`);
+    debug(`isSameDirectory stat failed: ${toErrorMessage(e)}`);
     return false;
   }
 }
@@ -187,8 +188,8 @@ export function flushDeferredClose(): void {
     const db = _deferredDbs.pop()!;
     try {
       db.close();
-    } catch {
-      /* ignore — handle may already be closed */
+    } catch (e) {
+      debug(`Deferred DB close failed (handle may already be closed): ${toErrorMessage(e)}`);
     }
   }
 }
@@ -216,8 +217,8 @@ export function closeDbDeferred(db: LockedDatabase): void {
       _deferredDbs.splice(idx, 1);
       try {
         db.close();
-      } catch {
-        /* ignore — handle may already be closed by flush */
+      } catch (e) {
+        debug(`Deferred DB close failed (may already be closed by flush): ${toErrorMessage(e)}`);
       }
     }
   });
@@ -239,8 +240,8 @@ export function closeDbPair(pair: LockedDatabasePair): void {
   if (pair.nativeDb) {
     try {
       pair.nativeDb.close();
-    } catch {
-      /* ignore */
+    } catch (e) {
+      debug(`closeDbPair: native close failed: ${toErrorMessage(e)}`);
     }
   }
   closeDb(pair.db);
@@ -251,8 +252,8 @@ export function closeDbPairDeferred(pair: LockedDatabasePair): void {
   if (pair.nativeDb) {
     try {
       pair.nativeDb.close();
-    } catch {
-      /* ignore */
+    } catch (e) {
+      debug(`closeDbPairDeferred: native close failed: ${toErrorMessage(e)}`);
     }
   }
   closeDbDeferred(pair.db);
@@ -270,7 +271,7 @@ export function findDbPath(customPath?: string): string {
     try {
       ceiling = fs.realpathSync(rawCeiling);
     } catch (e) {
-      debug(`realpathSync failed for ceiling "${rawCeiling}": ${(e as Error).message}`);
+      debug(`realpathSync failed for ceiling "${rawCeiling}": ${toErrorMessage(e)}`);
       ceiling = rawCeiling;
     }
   } else {
@@ -281,7 +282,7 @@ export function findDbPath(customPath?: string): string {
   try {
     dir = fs.realpathSync(process.cwd());
   } catch (e) {
-    debug(`realpathSync failed for cwd: ${(e as Error).message}`);
+    debug(`realpathSync failed for cwd: ${toErrorMessage(e)}`);
     dir = process.cwd();
   }
   while (true) {
@@ -334,9 +335,11 @@ function openRepoNative(customDbPath?: string): { repo: Repository; close(): voi
   const ndb = native.NativeDatabase.openReadonly(dbPath);
   try {
     warnOnVersionMismatch(() => ndb.getBuildMeta('codegraph_version'));
+    const repo = new NativeRepository(ndb, dbPath);
     return {
-      repo: new NativeRepository(ndb),
+      repo,
       close() {
+        repo.closeFallback();
         ndb.close();
       },
     };
@@ -375,9 +378,7 @@ export function openRepo(
       // 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}`,
-      );
+      debug(`openRepo: native path failed, falling back to better-sqlite3: ${toErrorMessage(e)}`);
     }
   }
 
@@ -411,7 +412,7 @@ export function openReadonlyWithNative(customPath?: string): {
       const native = getNative();
       nativeDb = native.NativeDatabase.openReadonly(dbPath);
     } catch (e) {
-      debug(`openReadonlyWithNative: native path failed: ${(e as Error).message}`);
+      debug(`openReadonlyWithNative: native path failed: ${toErrorMessage(e)}`);
     }
   }
 
@@ -423,8 +424,8 @@ export function openReadonlyWithNative(customPath?: string): {
       if (nativeDb) {
         try {
           nativeDb.close();
-        } catch {
-          // already closed or not closeable
+        } catch (e) {
+          debug(`openReadonlyWithNative: native close failed: ${toErrorMessage(e)}`);
         }
       }
     },

package/src/db/query-builder.ts

@@ -33,14 +33,26 @@ function validateOrderBy(clause: string): void {
   }
 }
 
+/**
+ * Track parenthesis depth change for a character.
+ * Returns non-zero only for '(' / ')'; a character that is '(' or ')'
+ * can never simultaneously be ',' so the comma check in the caller
+ * remains mutually exclusive with the depth update.
+ */
+function parenDepthDelta(ch: string): number {
+  if (ch === '(') return 1;
+  if (ch === ')') return -1;
+  return 0;
+}
+
 function splitTopLevelCommas(str: string): string[] {
   const parts: string[] = [];
   let depth = 0;
   let start = 0;
   for (let i = 0; i < str.length; i++) {
-    if (str[i] === '(') depth++;
-    else if (str[i] === ')') depth--;
-    else if (str[i] === ',' && depth === 0) {
+    const ch = str[i]!;
+    depth += parenDepthDelta(ch);
+    if (ch === ',' && depth === 0) {
       parts.push(str.slice(start, i).trim());
       start = i + 1;
     }

package/src/db/repository/base.ts

@@ -189,4 +189,24 @@ export class Repository implements IRepository {
   getComplexityForNode(_nodeId: number): ComplexityMetrics | undefined {
     throw new Error('not implemented');
   }
+
+  // ── Convenience queries ──────────────────────────────────────────────
+  /**
+   * Look up the stored content hash for a file.
+   * Returns null when the file is not in file_hashes or the method is
+   * not yet implemented on the concrete repository.
+   */
+  getFileHash(_file: string): string | null {
+    return null;
+  }
+
+  /** Check whether the graph contains any 'implements' edges. */
+  hasImplementsEdges(): boolean {
+    return false;
+  }
+
+  /** Check whether the co_changes table exists and has data. */
+  hasCoChangesTable(): boolean {
+    return false;
+  }
 }

package/src/db/repository/native-repository.ts

@@ -8,9 +8,11 @@
  * back to the snake_case field names that the Repository interface expects.
  */
 
+import Database from 'better-sqlite3';
 import { ConfigError } from '../../shared/errors.js';
 import type {
   AdjacentEdgeRow,
+  BetterSqlite3Database,
   CallableNodeRow,
   CallEdgeRow,
   ChildNodeRow,
@@ -159,10 +161,33 @@ function toComplexityMetrics(r: NativeComplexityMetrics): ComplexityMetrics {
 
 export class NativeRepository extends Repository {
   #ndb: NativeDatabase;
+  #dbPath?: string;
+  #fallbackDb?: BetterSqlite3Database;
 
-  constructor(ndb: NativeDatabase) {
+  constructor(ndb: NativeDatabase, dbPath?: string) {
     super();
     this.#ndb = ndb;
+    this.#dbPath = dbPath;
+  }
+
+  /** Lazy better-sqlite3 handle for methods not yet ported to Rust. */
+  #getFallbackDb(): BetterSqlite3Database | undefined {
+    if (this.#fallbackDb) return this.#fallbackDb;
+    if (!this.#dbPath) return undefined;
+    try {
+      this.#fallbackDb = new Database(this.#dbPath, { readonly: true });
+      return this.#fallbackDb;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Close the lazy fallback connection if it was opened. */
+  closeFallback(): void {
+    if (this.#fallbackDb) {
+      this.#fallbackDb.close();
+      this.#fallbackDb = undefined;
+    }
   }
 
   // ── Node lookups ──────────────────────────────────────────────────
@@ -358,4 +383,57 @@ export class NativeRepository extends Repository {
     const r = this.#ndb.getComplexityForNode(nodeId);
     return r ? toComplexityMetrics(r) : undefined;
   }
+
+  // ── Convenience queries ────────────────────────────────────────────
+
+  getFileHash(file: string): string | null {
+    if (typeof this.#ndb.getFileHash === 'function') return this.#ndb.getFileHash(file);
+    // Fallback to better-sqlite3 until Rust implements getFileHash
+    const db = this.#getFallbackDb();
+    if (db) {
+      const row = db.prepare('SELECT hash FROM file_hashes WHERE file = ?').get(file) as
+        | { hash: string }
+        | undefined;
+      return row?.hash ?? null;
+    }
+    return null;
+  }
+
+  #implementsEdgesCache?: boolean;
+  hasImplementsEdges(): boolean {
+    if (this.#implementsEdgesCache !== undefined) return this.#implementsEdgesCache;
+    if (typeof this.#ndb.hasImplementsEdges === 'function') {
+      this.#implementsEdgesCache = this.#ndb.hasImplementsEdges();
+      return this.#implementsEdgesCache;
+    }
+    // Fallback to better-sqlite3
+    const db = this.#getFallbackDb();
+    if (db) {
+      this.#implementsEdgesCache = !!db
+        .prepare("SELECT 1 FROM edges WHERE kind = 'implements' LIMIT 1")
+        .get();
+      return this.#implementsEdgesCache;
+    }
+    return true; // conservative: assume yes when no fallback available
+  }
+
+  #coChangesTableCache?: boolean;
+  hasCoChangesTable(): boolean {
+    if (this.#coChangesTableCache !== undefined) return this.#coChangesTableCache;
+    if (typeof this.#ndb.hasCoChangesTable === 'function') {
+      this.#coChangesTableCache = this.#ndb.hasCoChangesTable();
+      return this.#coChangesTableCache;
+    }
+    // Fallback to better-sqlite3
+    const db = this.#getFallbackDb();
+    if (db) {
+      try {
+        this.#coChangesTableCache = !!db.prepare('SELECT 1 FROM co_changes LIMIT 1').get();
+      } catch {
+        this.#coChangesTableCache = false;
+      }
+      return this.#coChangesTableCache;
+    }
+    return false;
+  }
 }

package/src/db/repository/nodes.ts

@@ -42,14 +42,8 @@ export function findNodesWithFanIn(
   return q.all(db, nativeDb);
 }
 
-/**
- * Fetch nodes for triage scoring: fan-in + complexity + churn.
- */
-export function findNodesForTriage(
-  db: BetterSqlite3Database,
-  opts: TriageQueryOpts = {},
-  nativeDb?: NativeDatabase,
-): TriageNodeRow[] {
+/** Validate kind and role options, throwing on invalid values. */
+function validateTriageOpts(opts: TriageQueryOpts): void {
   if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
     throw new ConfigError(
       `Invalid kind: ${opts.kind} (expected one of ${EVERY_SYMBOL_KIND.join(', ')})`,
@@ -58,6 +52,17 @@ export function findNodesForTriage(
   if (opts.role && !VALID_ROLES.includes(opts.role)) {
     throw new ConfigError(`Invalid role: ${opts.role} (expected one of ${VALID_ROLES.join(', ')})`);
   }
+}
+
+/**
+ * Fetch nodes for triage scoring: fan-in + complexity + churn.
+ */
+export function findNodesForTriage(
+  db: BetterSqlite3Database,
+  opts: TriageQueryOpts = {},
+  nativeDb?: NativeDatabase,
+): TriageNodeRow[] {
+  validateTriageOpts(opts);
 
   const kindsToUse = opts.kind ? [opts.kind] : ['function', 'method', 'class'];
   const q = new NodeQuery()

package/src/db/repository/sqlite-repository.ts

@@ -245,4 +245,33 @@ export class SqliteRepository extends Repository {
   getComplexityForNode(nodeId: number): ComplexityMetrics | undefined {
     return getComplexityForNode(this.#db, nodeId);
   }
+
+  // ── Convenience queries ────────────────────────────────────────────
+
+  getFileHash(file: string): string | null {
+    const row = this.#db.prepare('SELECT hash FROM file_hashes WHERE file = ?').get(file) as
+      | { hash: string }
+      | undefined;
+    return row?.hash ?? null;
+  }
+
+  #implementsEdgesCache?: boolean;
+  hasImplementsEdges(): boolean {
+    if (this.#implementsEdgesCache !== undefined) return this.#implementsEdgesCache;
+    this.#implementsEdgesCache = !!this.#db
+      .prepare("SELECT 1 FROM edges WHERE kind = 'implements' LIMIT 1")
+      .get();
+    return this.#implementsEdgesCache;
+  }
+
+  #coChangesTableCache?: boolean;
+  hasCoChangesTable(): boolean {
+    if (this.#coChangesTableCache !== undefined) return this.#coChangesTableCache;
+    try {
+      this.#coChangesTableCache = !!this.#db.prepare('SELECT 1 FROM co_changes LIMIT 1').get();
+    } catch {
+      this.#coChangesTableCache = false;
+    }
+    return this.#coChangesTableCache;
+  }
 }

package/src/domain/analysis/brief.ts

@@ -1,15 +1,8 @@
-import {
-  findDistinctCallers,
-  findFileNodes,
-  findImportDependents,
-  findImportSources,
-  findImportTargets,
-  findNodesByFile,
-  openReadonlyOrFail,
-} from '../../db/index.js';
+import type { Repository } from '../../db/index.js';
 import { loadConfig } from '../../infrastructure/config.js';
 import { isTestFile } from '../../infrastructure/test-filter.js';
-import type { BetterSqlite3Database, ImportEdgeRow, NodeRow, RelatedNodeRow } from '../../types.js';
+import type { ImportEdgeRow, NodeRow, RelatedNodeRow } from '../../types.js';
+import { withRepo } from './query-helpers.js';
 
 /** Symbol kinds meaningful for a file brief — excludes parameters, properties, constants. */
 const BRIEF_KINDS = new Set([
@@ -49,7 +42,7 @@ function computeRiskTier(
  * Lightweight variant — only counts, does not collect details.
  */
 function countTransitiveCallers(
-  db: BetterSqlite3Database,
+  repo: InstanceType<typeof Repository>,
   startId: number,
   noTests: boolean,
   maxDepth = 5,
@@ -60,7 +53,7 @@ function countTransitiveCallers(
   for (let d = 1; d <= maxDepth; d++) {
     const nextFrontier: number[] = [];
     for (const fid of frontier) {
-      const callers = findDistinctCallers(db, fid) as RelatedNodeRow[];
+      const callers = repo.findDistinctCallers(fid) as RelatedNodeRow[];
       for (const c of callers) {
         if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
           visited.add(c.id);
@@ -80,7 +73,7 @@ function countTransitiveCallers(
  * Depth-bounded to match countTransitiveCallers and keep hook latency predictable.
  */
 function countTransitiveImporters(
-  db: BetterSqlite3Database,
+  repo: InstanceType<typeof Repository>,
   fileNodeIds: number[],
   noTests: boolean,
   maxDepth = 5,
@@ -91,7 +84,7 @@ function countTransitiveImporters(
   for (let d = 1; d <= maxDepth; d++) {
     const nextFrontier: number[] = [];
     for (const current of frontier) {
-      const dependents = findImportDependents(db, current) as RelatedNodeRow[];
+      const dependents = repo.findImportDependents(current) as RelatedNodeRow[];
       for (const dep of dependents) {
         if (!visited.has(dep.id) && (!noTests || !isTestFile(dep.file))) {
           visited.add(dep.id);
@@ -115,38 +108,37 @@ export function briefData(
   customDbPath: string,
   opts: { noTests?: boolean; config?: any } = {},
 ) {
-  const db = openReadonlyOrFail(customDbPath);
-  try {
+  return withRepo(customDbPath, (repo) => {
     const noTests = opts.noTests || false;
     const config = opts.config || loadConfig();
     const callerDepth = config.analysis?.briefCallerDepth ?? 5;
     const importerDepth = config.analysis?.briefImporterDepth ?? 5;
     const highRiskCallers = config.analysis?.briefHighRiskCallers ?? 10;
     const mediumRiskCallers = config.analysis?.briefMediumRiskCallers ?? 3;
-    const fileNodes = findFileNodes(db, `%${file}%`) as NodeRow[];
+    const fileNodes = repo.findFileNodes(`%${file}%`) as NodeRow[];
     if (fileNodes.length === 0) {
       return { file, results: [] };
     }
 
     const results = fileNodes.map((fn) => {
       // Direct importers
-      let importedBy = findImportSources(db, fn.id) as ImportEdgeRow[];
+      let importedBy = repo.findImportSources(fn.id) as ImportEdgeRow[];
       if (noTests) importedBy = importedBy.filter((i) => !isTestFile(i.file));
       const directImporters = [...new Set(importedBy.map((i) => i.file))];
 
       // Transitive importer count
-      const totalImporterCount = countTransitiveImporters(db, [fn.id], noTests, importerDepth);
+      const totalImporterCount = countTransitiveImporters(repo, [fn.id], noTests, importerDepth);
 
       // Direct imports
-      let importsTo = findImportTargets(db, fn.id) as ImportEdgeRow[];
+      let importsTo = repo.findImportTargets(fn.id) as ImportEdgeRow[];
       if (noTests) importsTo = importsTo.filter((i) => !isTestFile(i.file));
 
       // Symbol definitions with roles and caller counts
-      const defs = (findNodesByFile(db, fn.file) as NodeRow[]).filter((d) =>
+      const defs = (repo.findNodesByFile(fn.file) as NodeRow[]).filter((d) =>
         BRIEF_KINDS.has(d.kind),
       );
       const symbols = defs.map((d) => {
-        const callerCount = countTransitiveCallers(db, d.id, noTests, callerDepth);
+        const callerCount = countTransitiveCallers(repo, d.id, noTests, callerDepth);
         return {
           name: d.name,
           kind: d.kind,
@@ -169,7 +161,5 @@ export function briefData(
     });
 
     return { file, results };
-  } finally {
-    db.close();
-  }
+  });
 }

package/src/domain/analysis/context.ts

@@ -264,6 +264,22 @@ function getNodeChildrenSafe(db: BetterSqlite3Database, nodeId: number) {
   }
 }
 
+function buildIntraFileDataFlow(
+  db: BetterSqlite3Database,
+  file: string,
+): Array<{ caller: string; callees: string[] }> {
+  const intraEdges = findIntraFileCallEdges(db, file) as IntraFileCallEdge[];
+  const dataFlowMap = new Map<string, string[]>();
+  for (const edge of intraEdges) {
+    if (!dataFlowMap.has(edge.caller_name)) dataFlowMap.set(edge.caller_name, []);
+    dataFlowMap.get(edge.caller_name)!.push(edge.callee_name);
+  }
+  return [...dataFlowMap.entries()].map(([caller, callees]) => ({
+    caller,
+    callees,
+  }));
+}
+
 function explainFileImpl(
   db: BetterSqlite3Database,
   target: string,
@@ -299,16 +315,7 @@ function explainFileImpl(
       file: r.file,
     }));
 
-    const intraEdges = findIntraFileCallEdges(db, fn.file) as IntraFileCallEdge[];
-    const dataFlowMap = new Map<string, string[]>();
-    for (const edge of intraEdges) {
-      if (!dataFlowMap.has(edge.caller_name)) dataFlowMap.set(edge.caller_name, []);
-      dataFlowMap.get(edge.caller_name)!.push(edge.callee_name);
-    }
-    const dataFlow = [...dataFlowMap.entries()].map(([caller, callees]) => ({
-      caller,
-      callees,
-    }));
+    const dataFlow = buildIntraFileDataFlow(db, fn.file);
 
     const metric = getLineCountForNode(db, fn.id) as { line_count: number } | undefined;
     let lineCount: number | null = metric?.line_count || null;