@optave/codegraph 3.9.4 → 3.9.5

package/src/cli.ts

@@ -1,14 +1,37 @@
 #!/usr/bin/env node
 
 import { run } from './cli/index.js';
+import { disposeParsers } from './domain/parser.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 {
-    console.error(`codegraph: fatal error — ${toErrorMessage(err)}`);
+/**
+ * After the CLI command finishes, tear down any cached WASM parsers and the
+ * worker thread pool. The WASM parse worker (see `domain/wasm-worker-pool.ts`)
+ * keeps the event loop alive until `worker.terminate()` is called, so without
+ * this teardown short-lived commands like `codegraph build` would hang for
+ * minutes before Node gives up — surfacing in CI as `spawnSync ETIMEDOUT`
+ * even though the command's work is already complete.
+ *
+ * `disposeParsers` is safe to call when the pool was never instantiated
+ * (e.g. native engine, or commands that never parse): it no-ops cleanly.
+ */
+async function shutdown(): Promise<void> {
+  try {
+    await disposeParsers();
+  } catch {
+    /* don't mask the real exit status over a teardown failure */
   }
-  process.exit(1);
-});
+}
+
+run()
+  .then(shutdown)
+  .catch(async (err: unknown) => {
+    if (err instanceof CodegraphError) {
+      console.error(`codegraph [${err.code}]: ${err.message}`);
+      if (err.file) console.error(`  file: ${err.file}`);
+    } else {
+      console.error(`codegraph: fatal error — ${toErrorMessage(err)}`);
+    }
+    await shutdown();
+    process.exit(1);
+  });

package/src/domain/graph/builder/context.ts

@@ -87,6 +87,8 @@ export class PipelineContext {
   // ── Phase timing ───────────────────────────────────────────────────
   timing: {
     setupMs?: number;
+    collectMs?: number;
+    detectMs?: number;
     parseMs?: number;
     insertMs?: number;
     resolveMs?: number;

package/src/domain/graph/builder/helpers.ts

@@ -8,7 +8,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { purgeFilesData } from '../../../db/index.js';
 import { warn } from '../../../infrastructure/logger.js';
-import { EXTENSIONS, IGNORE_DIRS } from '../../../shared/constants.js';
+import { EXTENSIONS, IGNORE_DIRS, normalizePath } from '../../../shared/constants.js';
+import { compileGlobs, matchesAny } from '../../../shared/globs.js';
 import type {
   BetterSqlite3Database,
   CodegraphConfig,
@@ -58,9 +59,29 @@ function shouldSkipEntry(entry: fs.Dirent, extraIgnore: Set<string> | null): boo
   return false;
 }
 
+/**
+ * Check whether a source file passes the configured include/exclude globs.
+ *
+ * Patterns are matched against the path relative to the project root,
+ * normalized to forward slashes (e.g. `src/foo/bar.ts`). When both lists
+ * are set, a file must match at least one include and no exclude.
+ */
+export function passesIncludeExclude(
+  relPath: string,
+  includeRegexes: readonly RegExp[],
+  excludeRegexes: readonly RegExp[],
+): boolean {
+  if (includeRegexes.length > 0 && !matchesAny(includeRegexes, relPath)) return false;
+  if (excludeRegexes.length > 0 && matchesAny(excludeRegexes, relPath)) return false;
+  return true;
+}
+
 /**
  * Recursively collect all source files under `dir`.
  * When `directories` is a Set, also tracks which directories contain files.
+ *
+ * The first invocation establishes `dir` as the project root against which
+ * `config.include` / `config.exclude` globs are matched.
  */
 export function collectFiles(
   dir: string,
@@ -68,6 +89,9 @@ export function collectFiles(
   config: Partial<CodegraphConfig>,
   directories: Set<string>,
   _visited?: Set<string>,
+  _rootDir?: string,
+  _includeRegexes?: readonly RegExp[],
+  _excludeRegexes?: readonly RegExp[],
 ): { files: string[]; directories: Set<string> };
 export function collectFiles(
   dir: string,
@@ -75,6 +99,9 @@ export function collectFiles(
   config?: Partial<CodegraphConfig>,
   directories?: null,
   _visited?: Set<string>,
+  _rootDir?: string,
+  _includeRegexes?: readonly RegExp[],
+  _excludeRegexes?: readonly RegExp[],
 ): string[];
 export function collectFiles(
   dir: string,
@@ -82,10 +109,20 @@ export function collectFiles(
   config: Partial<CodegraphConfig> = {},
   directories: Set<string> | null = null,
   _visited: Set<string> = new Set(),
+  _rootDir?: string,
+  _includeRegexes?: readonly RegExp[],
+  _excludeRegexes?: readonly RegExp[],
 ): string[] | { files: string[]; directories: Set<string> } {
   const trackDirs = directories instanceof Set;
   let hasFiles = false;
 
+  // First call: compute root and compile include/exclude patterns once,
+  // then pass them down recursive calls so we don't recompile per directory.
+  const rootDir = _rootDir ?? dir;
+  const includeRegexes = _includeRegexes ?? compileGlobs(config.include);
+  const excludeRegexes = _excludeRegexes ?? compileGlobs(config.exclude);
+  const hasGlobFilters = includeRegexes.length > 0 || excludeRegexes.length > 0;
+
   // Merge config ignoreDirs with defaults
   const extraIgnore = config.ignoreDirs ? new Set(config.ignoreDirs) : null;
 
@@ -116,11 +153,24 @@ export function collectFiles(
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (trackDirs) {
-        collectFiles(full, files, config, directories as Set<string>, _visited);
+        collectFiles(
+          full,
+          files,
+          config,
+          directories as Set<string>,
+          _visited,
+          rootDir,
+          includeRegexes,
+          excludeRegexes,
+        );
       } else {
-        collectFiles(full, files, config, null, _visited);
+        collectFiles(full, files, config, null, _visited, rootDir, includeRegexes, excludeRegexes);
       }
     } else if (EXTENSIONS.has(path.extname(entry.name))) {
+      if (hasGlobFilters) {
+        const rel = normalizePath(path.relative(rootDir, full));
+        if (!passesIncludeExclude(rel, includeRegexes, excludeRegexes)) continue;
+      }
       files.push(full);
       hasFiles = true;
     }

package/src/domain/graph/builder/pipeline.ts

@@ -21,6 +21,7 @@ import { detectWorkspaces, loadConfig } from '../../../infrastructure/config.js'
 import { debug, info, warn } from '../../../infrastructure/logger.js';
 import { loadNative } from '../../../infrastructure/native.js';
 import { semverCompare } from '../../../infrastructure/update-check.js';
+import { normalizePath } from '../../../shared/constants.js';
 import { toErrorMessage } from '../../../shared/errors.js';
 import { CODEGRAPH_VERSION } from '../../../shared/version.js';
 import type {
@@ -29,11 +30,12 @@ import type {
   BuildResult,
   Definition,
   ExtractorOutput,
+  SqliteStatement,
 } from '../../../types.js';
-import { getActiveEngine } from '../../parser.js';
+import { getActiveEngine, getInstalledWasmExtensions, parseFilesAuto } from '../../parser.js';
 import { setWorkspaces } from '../resolve.js';
 import { PipelineContext } from './context.js';
-import { loadPathAliases } from './helpers.js';
+import { batchInsertNodes, collectFiles as collectFilesUtil, loadPathAliases } from './helpers.js';
 import { NativeDbProxy } from './native-db-proxy.js';
 import { buildEdges } from './stages/build-edges.js';
 import { buildStructure } from './stages/build-structure.js';
@@ -104,6 +106,21 @@ function checkEngineSchemaMismatch(ctx: PipelineContext): void {
   }
 }
 
+function warnOnEmbeddingsWipe(ctx: PipelineContext): void {
+  const willBeFullBuild = !ctx.incremental || ctx.forceFullRebuild;
+  if (!willBeFullBuild) return;
+  let count = 0;
+  try {
+    count = (ctx.db.prepare('SELECT COUNT(*) AS c FROM embeddings').get() as { c: number }).c;
+  } catch {
+    return; // embeddings table missing — nothing to warn about
+  }
+  if (count === 0) return;
+  warn(
+    `Full rebuild will discard ${count} embedding${count === 1 ? '' : 's'}; re-run \`codegraph embed\` after the build.`,
+  );
+}
+
 function loadAliases(ctx: PipelineContext): void {
   ctx.aliases = loadPathAliases(ctx.rootDir);
   if (ctx.config.aliases) {
@@ -149,6 +166,7 @@ function setupPipeline(ctx: PipelineContext): void {
 
   initializeEngine(ctx);
   checkEngineSchemaMismatch(ctx);
+  warnOnEmbeddingsWipe(ctx);
   loadAliases(ctx);
 
   // Workspace packages (monorepo)
@@ -166,6 +184,8 @@ function formatTimingResult(ctx: PipelineContext): BuildResult {
   return {
     phases: {
       setupMs: +(t.setupMs ?? 0).toFixed(1),
+      collectMs: +(t.collectMs ?? 0).toFixed(1),
+      detectMs: +(t.detectMs ?? 0).toFixed(1),
       parseMs: +(t.parseMs ?? 0).toFixed(1),
       insertMs: +(t.insertMs ?? 0).toFixed(1),
       resolveMs: +(t.resolveMs ?? 0).toFixed(1),
@@ -540,7 +560,9 @@ function formatNativeTimingResult(
 ): BuildResult {
   return {
     phases: {
-      setupMs: +((p.setupMs ?? 0) + (p.collectMs ?? 0) + (p.detectMs ?? 0)).toFixed(1),
+      setupMs: +(p.setupMs ?? 0).toFixed(1),
+      collectMs: +(p.collectMs ?? 0).toFixed(1),
+      detectMs: +(p.detectMs ?? 0).toFixed(1),
       parseMs: +(p.parseMs ?? 0).toFixed(1),
       insertMs: +(p.insertMs ?? 0).toFixed(1),
       resolveMs: +(p.resolveMs ?? 0).toFixed(1),
@@ -696,10 +718,123 @@ async function tryNativeOrchestrator(
     }
   }
 
+  // Engine parity: the native orchestrator silently drops files whose
+  // Rust extractor/grammar is missing or fails (e.g. HCL, Scala, Swift on
+  // stale native binaries). WASM handles those — backfill via WASM so both
+  // engines process the same file set (#967).
+  //
+  // Only runs on full builds: incremental builds only touch changed files,
+  // which are parsed through parseFilesAuto (which has its own per-file
+  // backfill), so a full filesystem scan here would be wasted work.
+  if (result.isFullBuild) {
+    await backfillNativeDroppedFiles(ctx);
+  }
+
   closeDbPair({ db: ctx.db, nativeDb: ctx.nativeDb });
   return formatNativeTimingResult(p, structurePatchMs, analysisTiming);
 }
 
+/**
+ * Backfill files that the native orchestrator silently dropped during parse.
+ * Falls back to WASM + inserts file/symbol nodes so engine counts match (#967).
+ */
+async function backfillNativeDroppedFiles(ctx: PipelineContext): Promise<void> {
+  // Needs a real better-sqlite3 connection for INSERT.
+  if (ctx.nativeFirstProxy) {
+    closeNativeDb(ctx, 'pre-parity-backfill');
+    ctx.db = openDb(ctx.dbPath);
+    ctx.nativeFirstProxy = false;
+  }
+
+  const collected = collectFilesUtil(ctx.rootDir, [], ctx.config, new Set<string>());
+  const expected = new Set(
+    collected.files.map((f) => normalizePath(path.relative(ctx.rootDir, f))),
+  );
+
+  const existingRows = ctx.db
+    .prepare("SELECT DISTINCT file FROM nodes WHERE kind = 'file'")
+    .all() as Array<{ file: string }>;
+  const existing = new Set(existingRows.map((r) => r.file));
+
+  // Restrict backfill to files with an installed WASM grammar. Extensions in
+  // LANGUAGE_REGISTRY without a shipped grammar file (e.g. groovy, erlang on
+  // minimal installs) can't be parsed by either engine, so they're not a
+  // native regression — excluding them keeps the warn count meaningful.
+  const installedExts = getInstalledWasmExtensions();
+  const missingAbs: string[] = [];
+  for (const rel of expected) {
+    if (existing.has(rel)) continue;
+    const ext = path.extname(rel).toLowerCase();
+    if (!installedExts.has(ext)) continue;
+    missingAbs.push(path.join(ctx.rootDir, rel));
+  }
+  if (missingAbs.length === 0) return;
+
+  warn(
+    `Native orchestrator dropped ${missingAbs.length} file(s); backfilling via WASM for engine parity`,
+  );
+  const wasmResults = await parseFilesAuto(missingAbs, ctx.rootDir, { engine: 'wasm' });
+
+  const rows: unknown[][] = [];
+  const exportKeys: unknown[][] = [];
+  for (const [relPath, symbols] of wasmResults) {
+    // File row — mirrors insertDefinitionsAndExports: qualified_name is null.
+    rows.push([relPath, 'file', relPath, 0, null, null, null, null, null]);
+    for (const def of symbols.definitions ?? []) {
+      // Populate qualified_name/scope the same way the JS fallback does so
+      // downstream queries (cross-file references, "go to definition") find
+      // these symbols.
+      const dotIdx = def.name.lastIndexOf('.');
+      const scope = dotIdx !== -1 ? def.name.slice(0, dotIdx) : null;
+      rows.push([
+        def.name,
+        def.kind,
+        relPath,
+        def.line,
+        def.endLine ?? null,
+        null,
+        def.name,
+        scope,
+        def.visibility ?? null,
+      ]);
+    }
+    // Exports: insert the row (INSERT OR IGNORE — a matching definition row
+    // is a no-op) and queue a key for the second-pass exported=1 update, so
+    // queries filtering on exported=1 find backfilled symbols (#970).
+    for (const exp of symbols.exports ?? []) {
+      rows.push([exp.name, exp.kind, relPath, exp.line, null, null, exp.name, null, null]);
+      exportKeys.push([exp.name, exp.kind, relPath, exp.line]);
+    }
+  }
+  const db = ctx.db as unknown as BetterSqlite3Database;
+  batchInsertNodes(db, rows);
+
+  // Mark exported symbols in batches — mirrors insertDefinitionsAndExports.
+  if (exportKeys.length > 0) {
+    const EXPORT_CHUNK = 500;
+    const exportStmtCache = new Map<number, SqliteStatement>();
+    for (let i = 0; i < exportKeys.length; i += EXPORT_CHUNK) {
+      const end = Math.min(i + EXPORT_CHUNK, exportKeys.length);
+      const chunkSize = end - i;
+      let updateStmt = exportStmtCache.get(chunkSize);
+      if (!updateStmt) {
+        const conditions = Array.from(
+          { length: chunkSize },
+          () => '(name = ? AND kind = ? AND file = ? AND line = ?)',
+        ).join(' OR ');
+        updateStmt = db.prepare(`UPDATE nodes SET exported = 1 WHERE ${conditions}`);
+        exportStmtCache.set(chunkSize, updateStmt);
+      }
+      const vals: unknown[] = [];
+      for (let j = i; j < end; j++) {
+        const k = exportKeys[j] as unknown[];
+        vals.push(k[0], k[1], k[2], k[3]);
+      }
+      updateStmt.run(...vals);
+    }
+  }
+}
+
 // ── Pipeline stages execution ───────────────────────────────────────────
 
 async function runPipelineStages(ctx: PipelineContext): Promise<void> {
@@ -845,6 +980,10 @@ export async function buildGraph(
             `Codegraph version changed (${prevVersion} → ${CODEGRAPH_VERSION}), promoting to full rebuild.`,
           );
           ctx.forceFullRebuild = true;
+          // Re-check embeddings: the initial warnOnEmbeddingsWipe ran before
+          // forceFullRebuild was set here, so the silent-data-loss guard
+          // would otherwise miss this late-promotion path (#986 follow-up).
+          warnOnEmbeddingsWipe(ctx);
         }
       }
     }

package/src/domain/graph/builder/stages/collect-files.ts

@@ -7,11 +7,13 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
+import { compileGlobs } from '../../../../shared/globs.js';
 import { readJournal } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
-import { collectFiles as collectFilesUtil } from '../helpers.js';
+import { collectFiles as collectFilesUtil, passesIncludeExclude } from '../helpers.js';
 
 /**
  * Reconstruct allFiles from DB file_hashes + journal deltas.
@@ -20,7 +22,7 @@ import { collectFiles as collectFilesUtil } from '../helpers.js';
 function tryFastCollect(
   ctx: PipelineContext,
 ): { files: string[]; directories: Set<string> } | null {
-  const { db, rootDir } = ctx;
+  const { db, rootDir, config } = ctx;
   const useNative = ctx.engineName === 'native' && !!ctx.nativeDb?.getCollectFilesData;
 
   // 1. Check that file_hashes table exists and has entries
@@ -70,10 +72,20 @@ function tryFastCollect(
     }
   }
 
-  // 5. Convert to absolute paths and compute directories
+  // 5. Convert to absolute paths and compute directories, honoring
+  //    config.include / config.exclude globs so incremental builds reflect
+  //    config changes (paths from the DB were collected under older config).
+  const includeRegexes = compileGlobs(config?.include);
+  const excludeRegexes = compileGlobs(config?.exclude);
+  const hasGlobFilters = includeRegexes.length > 0 || excludeRegexes.length > 0;
+
   const files: string[] = [];
   const directories = new Set<string>();
   for (const relPath of fileSet) {
+    if (hasGlobFilters) {
+      const normRel = normalizePath(relPath);
+      if (!passesIncludeExclude(normRel, includeRegexes, excludeRegexes)) continue;
+    }
     const absPath = path.join(rootDir, relPath);
     files.push(absPath);
     directories.add(path.dirname(absPath));
@@ -89,42 +101,60 @@ export async function collectFiles(ctx: PipelineContext): Promise<void> {
   const { rootDir, config, opts } = ctx;
 
   if (opts.scope) {
-    // Scoped rebuild: rebuild only specified files
+    // Scoped rebuild: rebuild only specified files.
+    //
+    // Timer only wraps the filesystem-walk portion (existence checks + file
+    // list construction). Change-detection outputs (parseChanges, removed,
+    // isFullBuild) are attributed to detectMs for semantic consistency with
+    // the non-scoped path, even though this stage computes them.
+    const start = performance.now();
     const scopedFiles = opts.scope.map((f: string) => normalizePath(f));
     const existing: Array<{ file: string; relPath: string }> = [];
     const missing: string[] = [];
-    for (const rel of scopedFiles) {
-      const abs = path.join(rootDir, rel);
-      if (fs.existsSync(abs)) {
-        existing.push({ file: abs, relPath: rel });
-      } else {
-        missing.push(rel);
+    try {
+      for (const rel of scopedFiles) {
+        const abs = path.join(rootDir, rel);
+        if (fs.existsSync(abs)) {
+          existing.push({ file: abs, relPath: rel });
+        } else {
+          missing.push(rel);
+        }
       }
+      ctx.allFiles = existing.map((e) => e.file);
+      ctx.discoveredDirs = new Set(existing.map((e) => path.dirname(e.file)));
+    } finally {
+      ctx.timing.collectMs = performance.now() - start;
     }
-    ctx.allFiles = existing.map((e) => e.file);
-    ctx.discoveredDirs = new Set(existing.map((e) => path.dirname(e.file)));
+    // Change-detection outputs — timed under detectMs for semantic parity.
+    const detectStart = performance.now();
     ctx.parseChanges = existing;
     ctx.metadataUpdates = [];
     ctx.removed = missing;
     ctx.isFullBuild = false;
+    ctx.timing.detectMs = (ctx.timing.detectMs ?? 0) + (performance.now() - detectStart);
     info(`Scoped rebuild: ${existing.length} files to rebuild, ${missing.length} to purge`);
     return;
   }
 
-  // Incremental fast path: reconstruct file list from DB + journal deltas
-  // instead of full recursive filesystem scan (~8ms savings on 473 files).
-  if (ctx.incremental && !ctx.forceFullRebuild) {
-    const fast = tryFastCollect(ctx);
-    if (fast) {
-      ctx.allFiles = fast.files;
-      ctx.discoveredDirs = fast.directories;
-      info(`Found ${ctx.allFiles.length} files (cached)`);
-      return;
+  const start = performance.now();
+  try {
+    // Incremental fast path: reconstruct file list from DB + journal deltas
+    // instead of full recursive filesystem scan (~8ms savings on 473 files).
+    if (ctx.incremental && !ctx.forceFullRebuild) {
+      const fast = tryFastCollect(ctx);
+      if (fast) {
+        ctx.allFiles = fast.files;
+        ctx.discoveredDirs = fast.directories;
+        info(`Found ${ctx.allFiles.length} files (cached)`);
+        return;
+      }
     }
-  }
 
-  const collected = collectFilesUtil(rootDir, [], config, new Set<string>());
-  ctx.allFiles = collected.files;
-  ctx.discoveredDirs = collected.directories;
-  info(`Found ${ctx.allFiles.length} files to parse`);
+    const collected = collectFilesUtil(rootDir, [], config, new Set<string>());
+    ctx.allFiles = collected.files;
+    ctx.discoveredDirs = collected.directories;
+    info(`Found ${ctx.allFiles.length} files to parse`);
+  } finally {
+    ctx.timing.collectMs = performance.now() - start;
+  }
 }

package/src/domain/graph/builder/stages/detect-changes.ts

@@ -7,6 +7,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { closeDb } from '../../../../db/index.js';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
@@ -512,59 +513,66 @@ function handleIncrementalBuild(ctx: PipelineContext): void {
 }
 
 export async function detectChanges(ctx: PipelineContext): Promise<void> {
-  const { db, allFiles, rootDir, incremental, forceFullRebuild, opts } = ctx;
-  if ((opts as Record<string, unknown>).scope) {
-    handleScopedBuild(ctx);
-    return;
-  }
-  const increResult =
-    incremental && !forceFullRebuild
-      ? getChangedFiles(db, allFiles, rootDir)
-      : {
-          changed: allFiles.map((f): ChangedFile => ({ file: f })),
-          removed: [] as string[],
-          isFullBuild: true,
-        };
-  ctx.removed = increResult.removed;
-  ctx.isFullBuild = increResult.isFullBuild;
-  ctx.parseChanges = increResult.changed
-    .filter((c) => !c.metadataOnly)
-    .map((c) => ({
-      file: c.file,
-      relPath: c.relPath,
-      content: c.content,
-      hash: c.hash,
-      stat: c.stat ? { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size } : undefined,
-      _reverseDepOnly: c._reverseDepOnly,
-    }));
-  ctx.metadataUpdates = increResult.changed
-    .filter(
-      (c): c is ChangedFile & { relPath: string; hash: string; stat: FileStat } =>
-        !!c.metadataOnly && !!c.relPath && !!c.hash && !!c.stat,
-    )
-    .map((c) => ({
-      relPath: c.relPath,
-      hash: c.hash,
-      stat: { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size },
-    }));
-  if (!ctx.isFullBuild && ctx.parseChanges.length === 0 && ctx.removed.length === 0) {
-    const ranAnalysis = await runPendingAnalysis(ctx);
-    if (ranAnalysis) {
+  const start = performance.now();
+  try {
+    const { db, allFiles, rootDir, incremental, forceFullRebuild, opts } = ctx;
+    if ((opts as Record<string, unknown>).scope) {
+      handleScopedBuild(ctx);
+      return;
+    }
+    const increResult =
+      incremental && !forceFullRebuild
+        ? getChangedFiles(db, allFiles, rootDir)
+        : {
+            changed: allFiles.map((f): ChangedFile => ({ file: f })),
+            removed: [] as string[],
+            isFullBuild: true,
+          };
+    ctx.removed = increResult.removed;
+    ctx.isFullBuild = increResult.isFullBuild;
+    ctx.parseChanges = increResult.changed
+      .filter((c) => !c.metadataOnly)
+      .map((c) => ({
+        file: c.file,
+        relPath: c.relPath,
+        content: c.content,
+        hash: c.hash,
+        stat: c.stat ? { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size } : undefined,
+        _reverseDepOnly: c._reverseDepOnly,
+      }));
+    ctx.metadataUpdates = increResult.changed
+      .filter(
+        (c): c is ChangedFile & { relPath: string; hash: string; stat: FileStat } =>
+          !!c.metadataOnly && !!c.relPath && !!c.hash && !!c.stat,
+      )
+      .map((c) => ({
+        relPath: c.relPath,
+        hash: c.hash,
+        stat: { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size },
+      }));
+    if (!ctx.isFullBuild && ctx.parseChanges.length === 0 && ctx.removed.length === 0) {
+      const ranAnalysis = await runPendingAnalysis(ctx);
+      if (ranAnalysis) {
+        closeDb(db);
+        writeJournalHeader(rootDir, Date.now());
+        ctx.earlyExit = true;
+        return;
+      }
+      healMetadata(ctx);
+      info('No changes detected. Graph is up to date.');
       closeDb(db);
       writeJournalHeader(rootDir, Date.now());
       ctx.earlyExit = true;
       return;
     }
-    healMetadata(ctx);
-    info('No changes detected. Graph is up to date.');
-    closeDb(db);
-    writeJournalHeader(rootDir, Date.now());
-    ctx.earlyExit = true;
-    return;
-  }
-  if (ctx.isFullBuild) {
-    handleFullBuild(ctx);
-  } else {
-    handleIncrementalBuild(ctx);
+    if (ctx.isFullBuild) {
+      handleFullBuild(ctx);
+    } else {
+      handleIncrementalBuild(ctx);
+    }
+  } finally {
+    // Additive to respect any partial detectMs contribution from collectFiles
+    // (scoped-rebuild path splits change-detection outputs across both stages).
+    ctx.timing.detectMs = (ctx.timing.detectMs ?? 0) + (performance.now() - start);
   }
 }

package/src/domain/graph/builder/stages/finalize.ts

@@ -3,6 +3,7 @@
  *
  * WASM cleanup, stats logging, drift detection, build metadata, registry, journal.
  */
+import fs from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
@@ -88,6 +89,19 @@ function persistBuildMetadata(
   // subsequent build to be a full rebuild.
   const codeVersionToWrite =
     ctx.engineName === 'native' && ctx.engineVersion ? ctx.engineVersion : CODEGRAPH_VERSION;
+  // Persist the repo root so downstream commands (e.g. `codegraph embed`)
+  // can resolve relative file paths regardless of the invoking cwd.
+  // Use realpathSync (symlink-resolving) to match the Rust engine's
+  // std::fs::canonicalize — otherwise the JS write here would overwrite the
+  // canonical path Rust wrote for native full builds and could re-introduce
+  // a non-canonical path when the project root is behind a symlink.
+  const resolvedRootDir = path.resolve(ctx.rootDir);
+  let rootDirToWrite = resolvedRootDir;
+  try {
+    rootDirToWrite = fs.realpathSync(resolvedRootDir);
+  } catch {
+    /* realpath can fail (e.g. path no longer exists); fall back to resolve() */
+  }
   try {
     if (useNativeDb) {
       ctx.nativeDb!.setBuildMeta(
@@ -99,6 +113,7 @@ function persistBuildMetadata(
           built_at: buildNow.toISOString(),
           node_count: String(nodeCount),
           edge_count: String(actualEdgeCount),
+          root_dir: rootDirToWrite,
         }).map(([key, value]) => ({ key, value: String(value) })),
       );
     } else {
@@ -110,6 +125,7 @@ function persistBuildMetadata(
         built_at: buildNow.toISOString(),
         node_count: nodeCount,
         edge_count: actualEdgeCount,
+        root_dir: rootDirToWrite,
       });
     }
   } catch (err) {