fix+perf: dogfood fixes 9.1-9.4 and sub-100ms incremental rebuilds

CHANGELOG.md

@@ -40,6 +40,10 @@ All notable changes to this project will be documented in this file. See [commit
 * add `npm run bench` script and stale embeddings warning ([#604](https://github.com/optave/codegraph/pull/604))
 * bump `commit-and-tag-version`, `tree-sitter-cli`, `web-tree-sitter`, `@commitlint/cli`, `@commitlint/config-conventional` ([#560](https://github.com/optave/codegraph/pull/560), [#561](https://github.com/optave/codegraph/pull/561), [#562](https://github.com/optave/codegraph/pull/562), [#563](https://github.com/optave/codegraph/pull/563), [#564](https://github.com/optave/codegraph/pull/564))
 
+### Notes
+
+* **constants:** `EXTENSIONS` and `IGNORE_DIRS` in the programmatic API are now `Set<string>` (changed during TypeScript migration). Both expose a `.toArray()` convenience method for consumers that need array semantics.
+
 ## [3.3.1](https://github.com/optave/codegraph/compare/v3.3.0...v3.3.1) (2026-03-20)
 
 **Incremental rebuild accuracy and post-3.3.0 stabilization.** This patch fixes a critical edge gap in the file watcher's single-file rebuild path where call edges were silently dropped during incremental rebuilds, aligns the native Rust engine's edge builder kind filters with the JS engine for parity, plugs a WASM tree memory leak in native engine typeMap backfill, and restores query performance to pre-3.1.4 levels. Several post-reorganization import path issues are also corrected.

package.json

@@ -94,6 +94,7 @@
     "@commitlint/config-conventional": "^20.0",
     "@huggingface/transformers": "^3.8.1",
     "@tree-sitter-grammars/tree-sitter-hcl": "^1.2.0",
+    "@types/better-sqlite3": "^7.6.13",
     "@vitest/coverage-v8": "^4.0.18",
     "commit-and-tag-version": "^12.5",
     "husky": "^9.1",

src/cli/commands/info.ts

@@ -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');

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

src/db/connection.ts

@@ -1,13 +1,32 @@
 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';
 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);
@@ -122,13 +146,7 @@ export function openDb(dbPath: string): LockedDatabase {
   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`;
@@ -190,12 +208,33 @@ export function openReadonlyOrFail(customPath?: string): BetterSqlite3Database {
       { file: dbPath },
     );
   }
-  return new (
+  const db = new (
     Database as unknown as new (
       path: string,
       opts?: Record<string, unknown>,
     ) => BetterSqlite3Database
   )(dbPath, { readonly: true });
+
+  // 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;
 }
 
 /**

src/domain/graph/builder/context.ts

@@ -4,8 +4,8 @@
  * Each stage reads what it needs and writes what it produces.
  * This replaces the closure-captured locals in the old monolithic buildGraph().
  */
-import type BetterSqlite3 from 'better-sqlite3';
 import type {
+  BetterSqlite3Database,
   BuildGraphOpts,
   CodegraphConfig,
   EngineOpts,
@@ -20,7 +20,7 @@ import type {
 export class PipelineContext {
   // ── Inputs (set during setup) ──────────────────────────────────────
   rootDir!: string;
-  db!: BetterSqlite3.Database;
+  db!: BetterSqlite3Database;
   dbPath!: string;
   config!: CodegraphConfig;
   opts!: BuildGraphOpts;

src/domain/graph/builder/helpers.ts

@@ -6,11 +6,15 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import type BetterSqlite3 from 'better-sqlite3';
 import { purgeFilesData } from '../../../db/index.js';
-import { warn } from '../../../infrastructure/logger.js';
+import { debug, warn } from '../../../infrastructure/logger.js';
 import { EXTENSIONS, IGNORE_DIRS } from '../../../shared/constants.js';
-import type { BetterSqlite3Database, CodegraphConfig, PathAliases } from '../../../types.js';
+import type {
+  BetterSqlite3Database,
+  CodegraphConfig,
+  PathAliases,
+  SqliteStatement,
+} from '../../../types.js';
 
 export const BUILTIN_RECEIVERS: Set<string> = new Set([
   'console',
@@ -149,7 +153,7 @@ export function loadPathAliases(rootDir: string): PathAliases {
       }
       break;
     } catch (err: unknown) {
-      warn(`Failed to parse ${configName}: ${(err as Error).message}`);
+      debug(`Failed to parse ${configName}: ${(err as Error).message}`);
     }
   }
   return aliases;
@@ -199,7 +203,7 @@ export function readFileSafe(filePath: string, retries: number = 2): string {
  * Purge all graph data for the specified files.
  */
 export function purgeFilesFromGraph(
-  db: BetterSqlite3.Database,
+  db: BetterSqlite3Database,
   files: string[],
   options: Record<string, unknown> = {},
 ): void {
@@ -211,10 +215,10 @@ export function purgeFilesFromGraph(
 const BATCH_CHUNK = 500;
 
 // Statement caches keyed by chunk size — avoids recompiling for every batch.
-const nodeStmtCache = new WeakMap<BetterSqlite3.Database, Map<number, BetterSqlite3.Statement>>();
-const edgeStmtCache = new WeakMap<BetterSqlite3.Database, Map<number, BetterSqlite3.Statement>>();
+const nodeStmtCache = new WeakMap<BetterSqlite3Database, Map<number, SqliteStatement>>();
+const edgeStmtCache = new WeakMap<BetterSqlite3Database, Map<number, SqliteStatement>>();
 
-function getNodeStmt(db: BetterSqlite3.Database, chunkSize: number): BetterSqlite3.Statement {
+function getNodeStmt(db: BetterSqlite3Database, chunkSize: number): SqliteStatement {
   let cache = nodeStmtCache.get(db);
   if (!cache) {
     cache = new Map();
@@ -232,7 +236,7 @@ function getNodeStmt(db: BetterSqlite3.Database, chunkSize: number): BetterSqlit
   return stmt;
 }
 
-function getEdgeStmt(db: BetterSqlite3.Database, chunkSize: number): BetterSqlite3.Statement {
+function getEdgeStmt(db: BetterSqlite3Database, chunkSize: number): SqliteStatement {
   let cache = edgeStmtCache.get(db);
   if (!cache) {
     cache = new Map();
@@ -254,7 +258,7 @@ function getEdgeStmt(db: BetterSqlite3.Database, chunkSize: number): BetterSqlit
  * Batch-insert node rows via multi-value INSERT statements.
  * Each row: [name, kind, file, line, end_line, parent_id, qualified_name, scope, visibility]
  */
-export function batchInsertNodes(db: BetterSqlite3.Database, rows: unknown[][]): void {
+export function batchInsertNodes(db: BetterSqlite3Database, rows: unknown[][]): void {
   if (!rows.length) return;
   for (let i = 0; i < rows.length; i += BATCH_CHUNK) {
     const end = Math.min(i + BATCH_CHUNK, rows.length);
@@ -273,7 +277,7 @@ export function batchInsertNodes(db: BetterSqlite3.Database, rows: unknown[][]):
  * Batch-insert edge rows via multi-value INSERT statements.
  * Each row: [source_id, target_id, kind, confidence, dynamic]
  */
-export function batchInsertEdges(db: BetterSqlite3.Database, rows: unknown[][]): void {
+export function batchInsertEdges(db: BetterSqlite3Database, rows: unknown[][]): void {
   if (!rows.length) return;
   for (let i = 0; i < rows.length; i += BATCH_CHUNK) {
     const end = Math.min(i + BATCH_CHUNK, rows.length);