@optave/codegraph 3.4.0 → 3.4.1

package/src/ast-analysis/visitors/complexity-visitor.ts

@@ -5,7 +5,6 @@ import {
   computeMaintainabilityIndex,
 } from '../metrics.js';
 
-// biome-ignore lint/suspicious/noExplicitAny: complexity/halstead rules are opaque language-specific objects
 type AnyRules = any;
 
 interface ComplexityAcc {

package/src/ast-analysis/visitors/dataflow-visitor.ts

@@ -10,7 +10,6 @@ import {
   truncate,
 } from '../visitor-utils.js';
 
-// biome-ignore lint/suspicious/noExplicitAny: dataflow rules are opaque language-specific objects
 type AnyRules = any;
 
 interface ScopeEntry {

package/src/cli/commands/batch.ts

@@ -3,7 +3,7 @@ import { collectFile } from '../../db/query-builder.js';
 import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
 import { BATCH_COMMANDS, multiBatchData, splitTargets } from '../../features/batch.js';
 import { batch } from '../../presentation/batch.js';
-import { ConfigError } from '../../shared/errors.js';
+import { ConfigError, toErrorMessage } from '../../shared/errors.js';
 import type { CommandDefinition } from '../types.js';
 
 interface MultiBatchItem {
@@ -58,8 +58,9 @@ export const command: CommandDefinition = {
         targets = splitTargets(positionalTargets as unknown as string[]);
       }
     } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new ConfigError(`Failed to parse targets: ${message}`, { cause: err as Error });
+      throw new ConfigError(`Failed to parse targets: ${toErrorMessage(err)}`, {
+        cause: err as Error,
+      });
     }
 
     if (!targets || targets.length === 0) {

package/src/cli/commands/branch-compare.ts

@@ -13,7 +13,7 @@ export const command: CommandDefinition = {
   async execute([base, target], opts, ctx) {
     const { branchCompare } = await import('../../presentation/branch-compare.js');
     await branchCompare(base!, target!, {
-      engine: ctx.program.opts()['engine'],
+      engine: ctx.program.opts().engine,
       depth: parseInt(opts.depth as string, 10),
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,

package/src/cli/commands/build.ts

@@ -15,7 +15,7 @@ export const command: CommandDefinition = {
   ],
   async execute([dir], opts, ctx) {
     const root = path.resolve(dir || '.');
-    const engine = ctx.program.opts()['engine'];
+    const engine = ctx.program.opts().engine;
     await buildGraph(root, {
       incremental: opts.incremental as boolean,
       ast: opts.ast as boolean,

package/src/cli/commands/info.ts

@@ -9,7 +9,7 @@ export const command: CommandDefinition = {
     );
     const { getActiveEngine } = await import('../../domain/parser.js');
 
-    const engine = ctx.program.opts()['engine'];
+    const engine = ctx.program.opts().engine;
     const { name: activeName, version: activeVersion } = getActiveEngine({ engine });
     const nativeAvailable = isNativeAvailable();
 
@@ -43,7 +43,6 @@ export const command: CommandDefinition = {
       const dbPath = findDbPath();
       const fs = await import('node:fs');
       if (fs.existsSync(dbPath)) {
-        // @ts-expect-error -- better-sqlite3 default export typing
         const db = new Database(dbPath, { readonly: true });
         const buildEngine = getBuildMeta(db, 'engine');
         const buildVersion = getBuildMeta(db, 'codegraph_version');

package/src/cli/commands/path.ts

@@ -4,11 +4,15 @@ import type { CommandDefinition } from '../types.js';
 
 export const command: CommandDefinition = {
   name: 'path <from> <to>',
-  description: 'Find shortest path between two symbols',
+  description: 'Find shortest path between two symbols (or files with --file)',
   options: [
     ['-d, --db <path>', 'Path to graph.db'],
+    ['-f, --file', 'Treat <from> and <to> as file paths instead of symbol names'],
     ['--reverse', 'Follow edges backward'],
-    ['--kinds <kinds>', 'Comma-separated edge kinds to follow (default: calls)'],
+    [
+      '--kinds <kinds>',
+      'Comma-separated edge kinds to follow (default: calls; file mode: imports,imports-type)',
+    ],
     ['--from-file <path>', 'Disambiguate source symbol by file'],
     ['--to-file <path>', 'Disambiguate target symbol by file'],
     ['--depth <n>', 'Max traversal depth', '10'],
@@ -32,6 +36,7 @@ export const command: CommandDefinition = {
       kind: opts.kind,
       noTests: ctx.resolveNoTests(opts),
       json: opts.json,
+      file: opts.file,
     });
   },
 };

package/src/cli/commands/plot.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { toErrorMessage } from '../../shared/errors.js';
 import { openGraph } from '../shared/open-graph.js';
 import type { CommandDefinition } from '../types.js';
 
@@ -51,8 +52,7 @@ export const command: CommandDefinition = {
         try {
           plotCfg = JSON.parse(fs.readFileSync(opts.config as string, 'utf-8')) as PlotConfig;
         } catch (e: unknown) {
-          const message = e instanceof Error ? e.message : String(e);
-          console.error(`Failed to load config: ${message}`);
+          console.error(`Failed to load config: ${toErrorMessage(e)}`);
           process.exitCode = 1;
           return;
         }

package/src/cli/commands/watch.ts

@@ -7,7 +7,7 @@ export const command: CommandDefinition = {
   description: 'Watch project for file changes and incrementally update the graph',
   async execute([dir], _opts, ctx) {
     const root = path.resolve(dir || '.');
-    const engine = ctx.program.opts()['engine'];
+    const engine = ctx.program.opts().engine;
     await watchProject(root, { engine });
   },
 };

package/src/cli/index.ts

@@ -27,12 +27,12 @@ program
   .option('--engine <engine>', 'Parser engine: native, wasm, or auto (default: auto)', 'auto')
   .hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
-    if (opts['verbose']) setVerbose(true);
+    if (opts.verbose) setVerbose(true);
   })
   .hook('postAction', async (_thisCommand, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'mcp' || name === 'watch') return;
-    if (actionCommand.opts()['json']) return;
+    if (actionCommand.opts().json) return;
     try {
       const result = await checkForUpdates(pkg.version);
       if (result) printUpdateNotification(result.current, result.latest);

package/src/cli/shared/open-graph.ts

@@ -1,11 +1,11 @@
-import type Database from 'better-sqlite3';
 import { openReadonlyOrFail } from '../../db/index.js';
+import type { BetterSqlite3Database } from '../../types.js';
 
 /**
  * Open the graph database in readonly mode with a clean close() handle.
  */
 export function openGraph(opts: { db?: string } = {}): {
-  db: Database.Database;
+  db: BetterSqlite3Database;
   close: () => void;
 } {
   const db = openReadonlyOrFail(opts.db);

package/src/cli/types.ts

@@ -27,7 +27,7 @@ export interface CommandDefinition {
   description: string;
   queryOpts?: boolean;
   options?: Array<[string, string, ...unknown[]]>;
-  validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | void;
+  validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | undefined;
   execute?(args: string[], opts: CommandOpts, ctx: CliContext): void | Promise<void>;
   subcommands?: CommandDefinition[];
 }

package/src/cli.ts

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 import { run } from './cli/index.js';
-import { CodegraphError } from './shared/errors.js';
+import { CodegraphError, toErrorMessage } from './shared/errors.js';
 
 run().catch((err: unknown) => {
   if (err instanceof CodegraphError) {
     console.error(`codegraph [${err.code}]: ${err.message}`);
     if (err.file) console.error(`  file: ${err.file}`);
   } else {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`codegraph: fatal error — ${message}`);
+    console.error(`codegraph: fatal error — ${toErrorMessage(err)}`);
   }
   process.exit(1);
 });

package/src/db/connection.ts

@@ -1,6 +1,7 @@
 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 { DbError } from '../shared/errors.js';
@@ -8,6 +9,24 @@ import type { BetterSqlite3Database } from '../types.js';
 import { Repository } from './repository/base.js';
 import { SqliteRepository } from './repository/sqlite-repository.js';
 
+/** Lazy-loaded package version (read once from package.json). */
+let _packageVersion: string | undefined;
+function getPackageVersion(): string {
+  if (_packageVersion !== undefined) return _packageVersion;
+  try {
+    const connDir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgPath = path.join(connDir, '..', '..', 'package.json');
+    _packageVersion = (JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version: string })
+      .version;
+  } catch {
+    _packageVersion = '';
+  }
+  return _packageVersion;
+}
+
+/** Warn once per process when DB version mismatches the running codegraph version. */
+let _versionWarned = false;
+
 /** DB instance with optional advisory lock path. */
 export type LockedDatabase = BetterSqlite3Database & { __lockPath?: string };
 
@@ -60,6 +79,11 @@ 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);
@@ -119,16 +143,12 @@ function isSameDirectory(a: string, b: string): boolean {
 }
 
 export function openDb(dbPath: string): LockedDatabase {
+  // Flush any deferred DB close from a previous build (avoids WAL contention)
+  flushDeferredClose();
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   acquireAdvisoryLock(dbPath);
-  // vendor.d.ts declares Database as a callable; cast through unknown for construct usage
-  const db = new (
-    Database as unknown as new (
-      path: string,
-      opts?: Record<string, unknown>,
-    ) => LockedDatabase
-  )(dbPath);
+  const db = new Database(dbPath) as unknown as LockedDatabase;
   db.pragma('journal_mode = WAL');
   db.pragma('busy_timeout = 5000');
   db.__lockPath = `${dbPath}.lock`;
@@ -140,6 +160,54 @@ export function closeDb(db: LockedDatabase): void {
   if (db.__lockPath) releaseAdvisoryLock(db.__lockPath);
 }
 
+/** Pending deferred-close DB handles (not yet closed). */
+const _deferredDbs: LockedDatabase[] = [];
+
+/**
+ * Synchronously close any DB handles queued by `closeDbDeferred()`.
+ * Call before deleting DB files or in test teardown to avoid EBUSY on Windows.
+ */
+export function flushDeferredClose(): void {
+  while (_deferredDbs.length > 0) {
+    const db = _deferredDbs.pop()!;
+    try {
+      db.close();
+    } catch {
+      /* ignore — handle may already be closed */
+    }
+  }
+}
+
+/**
+ * Schedule DB close on the next event loop tick. Useful for incremental
+ * builds where the WAL checkpoint in db.close() is expensive (~250ms on
+ * Windows) and doesn't need to block the caller.
+ *
+ * The advisory lock is released immediately so subsequent opens succeed.
+ * The actual handle close (+ WAL checkpoint) happens asynchronously.
+ * Call `flushDeferredClose()` before deleting the DB file.
+ */
+export function closeDbDeferred(db: LockedDatabase): void {
+  // Release the advisory lock immediately so the next open can proceed
+  if (db.__lockPath) {
+    releaseAdvisoryLock(db.__lockPath);
+    db.__lockPath = undefined;
+  }
+  _deferredDbs.push(db);
+  // Defer the expensive WAL checkpoint to after the caller returns
+  setImmediate(() => {
+    const idx = _deferredDbs.indexOf(db);
+    if (idx !== -1) {
+      _deferredDbs.splice(idx, 1);
+      try {
+        db.close();
+      } catch {
+        /* ignore — handle may already be closed by flush */
+      }
+    }
+  });
+}
+
 export function findDbPath(customPath?: string): string {
   if (customPath) return path.resolve(customPath);
   const rawCeiling = findRepoRoot();
@@ -190,12 +258,28 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
       { file: dbPath },
     );
   }
-  return new (
-    Database as unknown as new (
-      path: string,
-      opts?: Record<string, unknown>,
-    ) => BetterSqlite3Database
-  )(dbPath, { readonly: true });
+  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;
+  }
+
+  return db;
 }
 
 /**

package/src/db/index.ts

@@ -3,8 +3,10 @@
 export type { LockedDatabase } from './connection.js';
 export {
   closeDb,
+  closeDbDeferred,
   findDbPath,
   findRepoRoot,
+  flushDeferredClose,
   openDb,
   openReadonlyOrFail,
   openRepo,

package/src/db/migrations.ts

@@ -247,6 +247,13 @@ export const MIGRATIONS: Migration[] = [
       CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope);
     `,
   },
+  {
+    version: 16,
+    up: `
+      CREATE INDEX IF NOT EXISTS idx_edges_kind_target ON edges(kind, target_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_kind_source ON edges(kind, source_id);
+    `,
+  },
 ];
 
 interface PragmaColumnInfo {

package/src/domain/analysis/brief.ts

@@ -113,7 +113,6 @@ function countTransitiveImporters(
 export function briefData(
   file: string,
   customDbPath: string,
-  // biome-ignore lint/suspicious/noExplicitAny: config shape is dynamic
   opts: { noTests?: boolean; config?: any } = {},
 ) {
   const db = openReadonlyOrFail(customDbPath);

package/src/domain/analysis/context.ts

@@ -379,7 +379,6 @@ function explainFunctionImpl(
   });
 }
 
-// biome-ignore lint/suspicious/noExplicitAny: explainFunctionImpl results have dynamic shape with _depth
 function explainCallees(
   parentResults: any[],
   currentDepth: number,
@@ -405,8 +404,8 @@ function explainCallees(
       );
       const exact = calleeResults.find((cr) => cr.file === callee.file && cr.line === callee.line);
       if (exact) {
-        (exact as Record<string, unknown>)['_depth'] =
-          (((r as Record<string, unknown>)['_depth'] as number) || 0) + 1;
+        (exact as Record<string, unknown>)._depth =
+          (((r as Record<string, unknown>)._depth as number) || 0) + 1;
         newCallees.push(exact);
       }
     }
@@ -431,7 +430,6 @@ export function contextData(
     kind?: string;
     limit?: number;
     offset?: number;
-    // biome-ignore lint/suspicious/noExplicitAny: config shape is dynamic
     config?: any;
   } = {},
 ) {
@@ -509,7 +507,6 @@ export function explainData(
     depth?: number;
     limit?: number;
     offset?: number;
-    // biome-ignore lint/suspicious/noExplicitAny: config shape is dynamic
     config?: any;
   } = {},
 ) {
@@ -533,7 +530,6 @@ export function explainData(
         : explainFunctionImpl(db, target, noTests, getFileLines, displayOpts);
 
     if (kind === 'function' && depth > 0 && results.length > 0) {
-      // biome-ignore lint/suspicious/noExplicitAny: results are function results when kind === 'function'
       const visited = new Set(results.map((r: any) => `${r.name}:${r.file}:${r.line ?? ''}`));
       explainCallees(results, depth, visited, db, noTests, getFileLines, displayOpts);
     }

package/src/domain/analysis/dependencies.ts

@@ -481,3 +481,168 @@ export function pathData(
     db.close();
   }
 }
+
+// ── File-level shortest path ────────────────────────────────────────────
+
+/**
+ * BFS at the file level: find shortest import/edge path between two files.
+ * Adjacency: file A → file B if any symbol in A has an edge to any symbol in B.
+ */
+export function filePathData(
+  from: string,
+  to: string,
+  customDbPath: string,
+  opts: {
+    noTests?: boolean;
+    maxDepth?: number;
+    edgeKinds?: string[];
+    reverse?: boolean;
+  } = {},
+) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const maxDepth = opts.maxDepth || 10;
+    const edgeKinds = opts.edgeKinds || ['imports', 'imports-type'];
+    const reverse = opts.reverse || false;
+
+    // Resolve from/to as file paths (LIKE match)
+    const fromFiles = findFileNodes(db, `%${from}%`) as NodeRow[];
+    if (fromFiles.length === 0) {
+      return {
+        from,
+        to,
+        found: false,
+        error: `No file matching "${from}"`,
+        path: [],
+        fromCandidates: [],
+        toCandidates: [],
+      };
+    }
+    const toFiles = findFileNodes(db, `%${to}%`) as NodeRow[];
+    if (toFiles.length === 0) {
+      return {
+        from,
+        to,
+        found: false,
+        error: `No file matching "${to}"`,
+        path: [],
+        fromCandidates: fromFiles.slice(0, 5).map((f) => f.file),
+        toCandidates: [],
+      };
+    }
+
+    const sourceFile = fromFiles[0]!.file;
+    const targetFile = toFiles[0]!.file;
+
+    const fromCandidates = fromFiles.slice(0, 5).map((f) => f.file);
+    const toCandidates = toFiles.slice(0, 5).map((f) => f.file);
+
+    if (sourceFile === targetFile) {
+      return {
+        from,
+        to,
+        fromCandidates,
+        toCandidates,
+        found: true,
+        hops: 0,
+        path: [sourceFile],
+        alternateCount: 0,
+        edgeKinds,
+        reverse,
+        maxDepth,
+      };
+    }
+
+    // Build neighbor query: find all distinct files adjacent to a given file via edges
+    const kindPlaceholders = edgeKinds.map(() => '?').join(', ');
+    const neighborQuery = reverse
+      ? `SELECT DISTINCT n_src.file AS neighbor_file
+         FROM nodes n_tgt
+         JOIN edges e ON e.target_id = n_tgt.id
+         JOIN nodes n_src ON e.source_id = n_src.id
+         WHERE n_tgt.file = ? AND e.kind IN (${kindPlaceholders}) AND n_src.file != n_tgt.file`
+      : `SELECT DISTINCT n_tgt.file AS neighbor_file
+         FROM nodes n_src
+         JOIN edges e ON e.source_id = n_src.id
+         JOIN nodes n_tgt ON e.target_id = n_tgt.id
+         WHERE n_src.file = ? AND e.kind IN (${kindPlaceholders}) AND n_tgt.file != n_src.file`;
+    const neighborStmt = db.prepare(neighborQuery);
+
+    // BFS
+    const visited = new Set([sourceFile]);
+    const parentMap = new Map<string, string>();
+    let queue = [sourceFile];
+    let found = false;
+    let alternateCount = 0;
+
+    for (let depth = 1; depth <= maxDepth; depth++) {
+      const nextQueue: string[] = [];
+      for (const currentFile of queue) {
+        const neighbors = neighborStmt.all(currentFile, ...edgeKinds) as Array<{
+          neighbor_file: string;
+        }>;
+        for (const n of neighbors) {
+          if (noTests && isTestFile(n.neighbor_file)) continue;
+          if (n.neighbor_file === targetFile) {
+            if (!found) {
+              found = true;
+              parentMap.set(n.neighbor_file, currentFile);
+            }
+            alternateCount++;
+            continue;
+          }
+          if (!visited.has(n.neighbor_file)) {
+            visited.add(n.neighbor_file);
+            parentMap.set(n.neighbor_file, currentFile);
+            nextQueue.push(n.neighbor_file);
+          }
+        }
+      }
+      if (found) break;
+      queue = nextQueue;
+      if (queue.length === 0) break;
+    }
+
+    if (!found) {
+      return {
+        from,
+        to,
+        fromCandidates,
+        toCandidates,
+        found: false,
+        hops: null,
+        path: [],
+        alternateCount: 0,
+        edgeKinds,
+        reverse,
+        maxDepth,
+      };
+    }
+
+    // Reconstruct path
+    const filePath: string[] = [targetFile];
+    let cur = targetFile;
+    while (cur !== sourceFile) {
+      cur = parentMap.get(cur)!;
+      filePath.push(cur);
+    }
+    filePath.reverse();
+
+    return {
+      from,
+      to,
+      fromCandidates,
+      toCandidates,
+      found: true,
+      hops: filePath.length - 1,
+      path: filePath,
+      alternateCount: Math.max(0, alternateCount - 1),
+      edgeKinds,
+      reverse,
+      maxDepth,
+    };
+  } finally {
+    db.close();
+  }
+}