feat: add build metadata tracking and excludeTests config shorthand

Track engine name, version, and codegraph version in a new build_meta
table (migration v7). Warn during incremental builds when the engine or
codegraph version has changed since the last build, suggesting
--no-incremental. Display build metadata in the info command with
mismatch warnings.

Accept excludeTests at the top level of .codegraphrc.json as a
shorthand for query.excludeTests, with the nested form taking
precedence.

Impact: 4 functions changed, 8 affected

Author: github-actions[bot]

README.md

@@ -532,10 +532,15 @@ Create a `.codegraphrc.json` in your project root to customize behavior:
   },
   "build": {
     "incremental": true
+  },
+  "query": {
+    "excludeTests": true
   }
 }
 ```
 
+> **Tip:** `excludeTests` can also be set at the top level as a shorthand — `{ "excludeTests": true }` is equivalent to nesting it under `query`. If both are present, the nested `query.excludeTests` takes precedence.
+
 ### LLM credentials
 
 Codegraph supports an `apiKeyCommand` field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:

src/builder.js

@@ -3,14 +3,19 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadConfig } from './config.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-import { initSchema, openDb } from './db.js';
+import { getBuildMeta, initSchema, openDb, setBuildMeta } from './db.js';
 import { readJournal, writeJournalHeader } from './journal.js';
 import { debug, info, warn } from './logger.js';
 import { getActiveEngine, parseFilesAuto } from './parser.js';
 import { computeConfidence, resolveImportPath, resolveImportsBatch } from './resolve.js';
 
 export { resolveImportPath } from './resolve.js';
 
+const __builderDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
+const CODEGRAPH_VERSION = JSON.parse(
+  fs.readFileSync(path.join(__builderDir, '..', 'package.json'), 'utf-8'),
+).version;
+
 const BUILTIN_RECEIVERS = new Set([
   'console',
   'Math',
@@ -346,6 +351,22 @@ export async function buildGraph(rootDir, opts = {}) {
   const { name: engineName, version: engineVersion } = getActiveEngine(engineOpts);
   info(`Using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
 
+  // Check for engine/version mismatch on incremental builds
+  if (incremental) {
+    const prevEngine = getBuildMeta(db, 'engine');
+    const prevVersion = getBuildMeta(db, 'codegraph_version');
+    if (prevEngine && prevEngine !== engineName) {
+      warn(
+        `Engine changed (${prevEngine} → ${engineName}). Consider rebuilding with --no-incremental for consistency.`,
+      );
+    }
+    if (prevVersion && prevVersion !== CODEGRAPH_VERSION) {
+      warn(
+        `Codegraph version changed (${prevVersion} → ${CODEGRAPH_VERSION}). Consider rebuilding with --no-incremental for consistency.`,
+      );
+    }
+  }
+
   const aliases = loadPathAliases(rootDir);
   // Merge config aliases
   if (config.aliases) {
@@ -925,6 +946,18 @@ export async function buildGraph(rootDir, opts = {}) {
     }
   }
 
+  // Persist build metadata for mismatch detection
+  try {
+    setBuildMeta(db, {
+      engine: engineName,
+      engine_version: engineVersion || '',
+      codegraph_version: CODEGRAPH_VERSION,
+      built_at: new Date().toISOString(),
+    });
+  } catch (err) {
+    debug(`Failed to write build metadata: ${err.message}`);
+  }
+
   db.close();
 
   // Write journal header after successful build

src/cli.js

@@ -668,6 +668,43 @@ program
     console.log(`  Engine flag   : --engine ${engine}`);
     console.log(`  Active engine : ${activeName}${activeVersion ? ` (v${activeVersion})` : ''}`);
     console.log();
+
+    // Build metadata from DB
+    try {
+      const { findDbPath, getBuildMeta } = await import('./db.js');
+      const Database = (await import('better-sqlite3')).default;
+      const dbPath = findDbPath();
+      const fs = await import('node:fs');
+      if (fs.existsSync(dbPath)) {
+        const db = new Database(dbPath, { readonly: true });
+        const buildEngine = getBuildMeta(db, 'engine');
+        const buildVersion = getBuildMeta(db, 'codegraph_version');
+        const builtAt = getBuildMeta(db, 'built_at');
+        db.close();
+
+        if (buildEngine || buildVersion || builtAt) {
+          console.log('Build metadata');
+          console.log('──────────────');
+          if (buildEngine) console.log(`  Engine        : ${buildEngine}`);
+          if (buildVersion) console.log(`  Version       : ${buildVersion}`);
+          if (builtAt) console.log(`  Built at      : ${builtAt}`);
+
+          if (buildVersion && buildVersion !== program.version()) {
+            console.log(
+              `  ⚠ DB was built with v${buildVersion}, current is v${program.version()}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          if (buildEngine && buildEngine !== activeName) {
+            console.log(
+              `  ⚠ DB was built with ${buildEngine} engine, active is ${activeName}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          console.log();
+        }
+      }
+    } catch {
+      /* diagnostics must never crash */
+    }
   });
 
 program.parse();

src/config.js

@@ -45,7 +45,12 @@ export function loadConfig(cwd) {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const config = JSON.parse(raw);
         debug(`Loaded config from ${filePath}`);
-        return resolveSecrets(applyEnvOverrides(mergeConfig(DEFAULTS, config)));
+        const merged = mergeConfig(DEFAULTS, config);
+        if ('excludeTests' in config && !(config.query && 'excludeTests' in config.query)) {
+          merged.query.excludeTests = Boolean(config.excludeTests);
+        }
+        delete merged.excludeTests;
+        return resolveSecrets(applyEnvOverrides(merged));
       } catch (err) {
         debug(`Failed to parse config ${filePath}: ${err.message}`);
       }

src/db.js

@@ -101,8 +101,36 @@ export const MIGRATIONS = [
       );
     `,
   },
+  {
+    version: 7,
+    up: `
+      CREATE TABLE IF NOT EXISTS build_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `,
+  },
 ];
 
+export function getBuildMeta(db, key) {
+  try {
+    const row = db.prepare('SELECT value FROM build_meta WHERE key = ?').get(key);
+    return row ? row.value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function setBuildMeta(db, entries) {
+  const upsert = db.prepare('INSERT OR REPLACE INTO build_meta (key, value) VALUES (?, ?)');
+  const tx = db.transaction(() => {
+    for (const [key, value] of Object.entries(entries)) {
+      upsert.run(key, String(value));
+    }
+  });
+  tx();
+}
+
 export function openDb(dbPath) {
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });

src/index.js

@@ -23,7 +23,14 @@ export { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
 // Circular dependency detection
 export { findCycles, formatCycles } from './cycles.js';
 // Database utilities
-export { findDbPath, initSchema, openDb, openReadonlyOrFail } from './db.js';
+export {
+  findDbPath,
+  getBuildMeta,
+  initSchema,
+  openDb,
+  openReadonlyOrFail,
+  setBuildMeta,
+} from './db.js';
 
 // Embeddings
 export {

tests/unit/config.test.js

@@ -162,6 +162,34 @@ describe('loadConfig', () => {
   });
 });
 
+describe('excludeTests hoisting', () => {
+  it('hoists top-level excludeTests into query.excludeTests', () => {
+    const dir = fs.mkdtempSync(path.join(tmpDir, 'exclude-top-'));
+    fs.writeFileSync(path.join(dir, '.codegraphrc.json'), JSON.stringify({ excludeTests: true }));
+    const config = loadConfig(dir);
+    expect(config.query.excludeTests).toBe(true);
+    expect(config.excludeTests).toBeUndefined();
+  });
+
+  it('nested query.excludeTests takes precedence over top-level', () => {
+    const dir = fs.mkdtempSync(path.join(tmpDir, 'exclude-nested-'));
+    fs.writeFileSync(
+      path.join(dir, '.codegraphrc.json'),
+      JSON.stringify({ excludeTests: true, query: { excludeTests: false } }),
+    );
+    const config = loadConfig(dir);
+    expect(config.query.excludeTests).toBe(false);
+  });
+
+  it('hoists top-level excludeTests: false correctly', () => {
+    const dir = fs.mkdtempSync(path.join(tmpDir, 'exclude-false-'));
+    fs.writeFileSync(path.join(dir, '.codegraphrc.json'), JSON.stringify({ excludeTests: false }));
+    const config = loadConfig(dir);
+    expect(config.query.excludeTests).toBe(false);
+    expect(config.excludeTests).toBeUndefined();
+  });
+});
+
 describe('applyEnvOverrides', () => {
   const ENV_KEYS = ['CODEGRAPH_LLM_PROVIDER', 'CODEGRAPH_LLM_API_KEY', 'CODEGRAPH_LLM_MODEL'];
 

tests/unit/db.test.js

@@ -1,13 +1,21 @@
 /**
- * Unit tests for src/db.js
+ * Unit tests for src/db.js — build_meta helpers included
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import Database from 'better-sqlite3';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
-import { findDbPath, initSchema, MIGRATIONS, openDb, openReadonlyOrFail } from '../../src/db.js';
+import {
+  findDbPath,
+  getBuildMeta,
+  initSchema,
+  MIGRATIONS,
+  openDb,
+  openReadonlyOrFail,
+  setBuildMeta,
+} from '../../src/db.js';
 
 let tmpDir;
 
@@ -126,6 +134,47 @@ describe('findDbPath', () => {
   });
 });
 
+describe('build_meta', () => {
+  it('table is created by migration v7', () => {
+    const db = new Database(':memory:');
+    initSchema(db);
+    const tables = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table'")
+      .all()
+      .map((r) => r.name);
+    expect(tables).toContain('build_meta');
+    db.close();
+  });
+
+  it('getBuildMeta returns null for missing table (pre-v7 schema)', () => {
+    const db = new Database(':memory:');
+    // No initSchema — no build_meta table
+    const result = getBuildMeta(db, 'engine');
+    expect(result).toBeNull();
+    db.close();
+  });
+
+  it('setBuildMeta writes and getBuildMeta reads', () => {
+    const db = new Database(':memory:');
+    initSchema(db);
+    setBuildMeta(db, { engine: 'wasm', codegraph_version: '1.0.0' });
+    expect(getBuildMeta(db, 'engine')).toBe('wasm');
+    expect(getBuildMeta(db, 'codegraph_version')).toBe('1.0.0');
+    expect(getBuildMeta(db, 'nonexistent')).toBeNull();
+    db.close();
+  });
+
+  it('setBuildMeta upserts existing keys', () => {
+    const db = new Database(':memory:');
+    initSchema(db);
+    setBuildMeta(db, { engine: 'wasm' });
+    expect(getBuildMeta(db, 'engine')).toBe('wasm');
+    setBuildMeta(db, { engine: 'native' });
+    expect(getBuildMeta(db, 'engine')).toBe('native');
+    db.close();
+  });
+});
+
 describe('openReadonlyOrFail', () => {
   it('exits with error when DB does not exist', () => {
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {