@optave/codegraph 3.11.0 → 3.11.2

package/src/domain/graph/builder/stages/build-structure.ts

@@ -11,87 +11,104 @@ import type { ExtractorOutput } from '../../../../types.js';
 import type { PipelineContext } from '../context.js';
 import { readFileSafe } from '../helpers.js';
 
-export async function buildStructure(ctx: PipelineContext): Promise<void> {
-  const { db, fileSymbols, rootDir, discoveredDirs, allSymbols, isFullBuild } = ctx;
-
-  // Build line count map (prefer cached _lineCount from parser)
+/** Populate `ctx.lineCountMap` from cached parser results, falling back to disk. */
+function populateLineCountMap(ctx: PipelineContext): void {
+  const { fileSymbols, rootDir } = ctx;
   ctx.lineCountMap = new Map();
   for (const [relPath, symbols] of fileSymbols) {
     const lineCount =
       (symbols as ExtractorOutput & { lineCount?: number }).lineCount ?? symbols._lineCount;
     if (lineCount) {
       ctx.lineCountMap.set(relPath, lineCount);
-    } else {
-      const absPath = path.join(rootDir, relPath);
-      try {
-        const content = readFileSafe(absPath);
-        ctx.lineCountMap.set(relPath, content.split('\n').length);
-      } catch {
-        ctx.lineCountMap.set(relPath, 0);
-      }
+      continue;
+    }
+    const absPath = path.join(rootDir, relPath);
+    try {
+      const content = readFileSafe(absPath);
+      ctx.lineCountMap.set(relPath, content.split('\n').length);
+    } catch {
+      ctx.lineCountMap.set(relPath, 0);
     }
   }
+}
 
-  const changedFileList = isFullBuild ? null : [...allSymbols.keys()];
-
-  // For small incremental builds on large codebases, use a fast path that
-  // updates only the changed files' metrics via targeted SQL instead of
-  // loading ALL definitions from DB (~8ms) and recomputing ALL metrics (~15ms).
-  // Gate: ≤smallFilesThreshold changed files AND significantly more existing files (>20) to
-  // avoid triggering on small test fixtures where directory metrics matter.
+/** Count file-kind nodes already in the DB, preferring the native connection. */
+function countExistingFiles(ctx: PipelineContext): number {
   const useNativeReads = ctx.engineName === 'native' && !!ctx.nativeDb;
-  const existingFileCount = !isFullBuild
-    ? (
-        (useNativeReads
-          ? ctx.nativeDb!.queryGet("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'", [])
-          : db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get()) as {
-          c: number;
-        }
-      ).c
-    : 0;
-  const useSmallIncrementalFastPath =
-    !isFullBuild &&
-    changedFileList != null &&
-    changedFileList.length <= ctx.config.build.smallFilesThreshold &&
-    existingFileCount > 20;
-
-  if (!isFullBuild && !useSmallIncrementalFastPath) {
-    // Medium/large incremental: load unchanged files from DB for complete structure
-    loadUnchangedFilesFromDb(ctx);
-  }
+  const row = (
+    useNativeReads
+      ? ctx.nativeDb!.queryGet("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'", [])
+      : ctx.db.prepare("SELECT COUNT(*) as c FROM nodes WHERE kind = 'file'").get()
+  ) as { c: number };
+  return row.c;
+}
 
-  // Build directory structure
-  const t0 = performance.now();
+/**
+ * Build directory structure + metrics. Chooses between the fast incremental
+ * path (a handful of files changed on a large codebase) and the full path
+ * (delegated to `features/structure`).
+ */
+async function buildDirectoryStructure(
+  ctx: PipelineContext,
+  changedFileList: string[] | null,
+  useSmallIncrementalFastPath: boolean,
+): Promise<void> {
   if (useSmallIncrementalFastPath) {
     updateChangedFileMetrics(ctx, changedFileList!);
-  } else {
-    const relDirs = new Set<string>();
-    for (const absDir of discoveredDirs) {
-      relDirs.add(normalizePath(path.relative(rootDir, absDir)));
-    }
-    try {
-      const { buildStructure: buildStructureFn } = (await import(
-        '../../../../features/structure.js'
-      )) as {
-        buildStructure: (
-          db: PipelineContext['db'],
-          fileSymbols: Map<string, ExtractorOutput>,
-          rootDir: string,
-          lineCountMap: Map<string, number>,
-          directories: Set<string>,
-          changedFiles: string[] | null,
-        ) => void;
-      };
-      const changedFilePaths = isFullBuild ? null : [...allSymbols.keys()];
-      buildStructureFn(db, fileSymbols, rootDir, ctx.lineCountMap, relDirs, changedFilePaths);
-    } catch (err) {
-      debug(`Structure analysis failed: ${(err as Error).message}`);
-    }
+    return;
   }
-  ctx.timing.structureMs = performance.now() - t0;
 
-  // Classify node roles (incremental: only reclassify changed files' nodes)
-  const t1 = performance.now();
+  const { db, fileSymbols, rootDir, discoveredDirs, allSymbols, isFullBuild } = ctx;
+  const relDirs = new Set<string>();
+  for (const absDir of discoveredDirs) {
+    relDirs.add(normalizePath(path.relative(rootDir, absDir)));
+  }
+  try {
+    const { buildStructure: buildStructureFn } = (await import(
+      '../../../../features/structure.js'
+    )) as {
+      buildStructure: (
+        db: PipelineContext['db'],
+        fileSymbols: Map<string, ExtractorOutput>,
+        rootDir: string,
+        lineCountMap: Map<string, number>,
+        directories: Set<string>,
+        changedFiles: string[] | null,
+      ) => void;
+    };
+    const changedFilePaths = isFullBuild ? null : [...allSymbols.keys()];
+    buildStructureFn(db, fileSymbols, rootDir, ctx.lineCountMap, relDirs, changedFilePaths);
+  } catch (err) {
+    debug(`Structure analysis failed: ${(err as Error).message}`);
+  }
+}
+
+/** Convert a `NativeDatabase.classifyRoles*` result into the JS summary shape. */
+function nativeRoleSummaryToRecord(
+  nativeResult: NonNullable<
+    ReturnType<NonNullable<PipelineContext['nativeDb']>['classifyRolesFull']>
+  >,
+): Record<string, number> {
+  return {
+    entry: nativeResult.entry,
+    core: nativeResult.core,
+    utility: nativeResult.utility,
+    adapter: nativeResult.adapter,
+    dead: nativeResult.dead,
+    'dead-leaf': nativeResult.deadLeaf,
+    'dead-entry': nativeResult.deadEntry,
+    'dead-ffi': nativeResult.deadFfi,
+    'dead-unresolved': nativeResult.deadUnresolved,
+    'test-only': nativeResult.testOnly,
+    leaf: nativeResult.leaf,
+  };
+}
+
+async function classifyRoles(
+  ctx: PipelineContext,
+  changedFileList: string[] | null,
+): Promise<void> {
+  const useNativeReads = ctx.engineName === 'native' && !!ctx.nativeDb;
   try {
     let roleSummary: Record<string, number> | null = null;
 
@@ -103,24 +120,9 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
         changedFileList && changedFileList.length > 0
           ? ctx.nativeDb.classifyRolesIncremental(changedFileList)
           : ctx.nativeDb.classifyRolesFull();
-      if (nativeResult) {
-        roleSummary = {
-          entry: nativeResult.entry,
-          core: nativeResult.core,
-          utility: nativeResult.utility,
-          adapter: nativeResult.adapter,
-          dead: nativeResult.dead,
-          'dead-leaf': nativeResult.deadLeaf,
-          'dead-entry': nativeResult.deadEntry,
-          'dead-ffi': nativeResult.deadFfi,
-          'dead-unresolved': nativeResult.deadUnresolved,
-          'test-only': nativeResult.testOnly,
-          leaf: nativeResult.leaf,
-        };
-      }
+      if (nativeResult) roleSummary = nativeRoleSummaryToRecord(nativeResult);
     }
 
-    // Fall back to JS path
     if (!roleSummary) {
       const { classifyNodeRoles } = (await import('../../../../features/structure.js')) as {
         classifyNodeRoles: (
@@ -141,6 +143,37 @@ export async function buildStructure(ctx: PipelineContext): Promise<void> {
   } catch (err) {
     debug(`Role classification failed: ${(err as Error).message}`);
   }
+}
+
+export async function buildStructure(ctx: PipelineContext): Promise<void> {
+  const { allSymbols, isFullBuild } = ctx;
+
+  populateLineCountMap(ctx);
+
+  const changedFileList = isFullBuild ? null : [...allSymbols.keys()];
+
+  // For small incremental builds on large codebases, use a fast path that
+  // updates only the changed files' metrics via targeted SQL instead of
+  // loading ALL definitions from DB (~8ms) and recomputing ALL metrics (~15ms).
+  // Gate: ≤smallFilesThreshold changed files AND significantly more existing files (>20) to
+  // avoid triggering on small test fixtures where directory metrics matter.
+  const existingFileCount = !isFullBuild ? countExistingFiles(ctx) : 0;
+  const useSmallIncrementalFastPath =
+    !isFullBuild &&
+    changedFileList != null &&
+    changedFileList.length <= ctx.config.build.smallFilesThreshold &&
+    existingFileCount > 20;
+
+  if (!isFullBuild && !useSmallIncrementalFastPath) {
+    loadUnchangedFilesFromDb(ctx);
+  }
+
+  const t0 = performance.now();
+  await buildDirectoryStructure(ctx, changedFileList, useSmallIncrementalFastPath);
+  ctx.timing.structureMs = performance.now() - t0;
+
+  const t1 = performance.now();
+  await classifyRoles(ctx, changedFileList);
   ctx.timing.rolesMs = performance.now() - t1;
 }
 

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

@@ -162,14 +162,14 @@ function tryJournalTier(
   return { changed, removed: [...removedSet], isFullBuild: false };
 }
 
-function mtimeAndHashTiers(
+/** Tier 1: mtime+size triage. Returns the files that still need hashing. */
+function tierMtimeSize(
   existing: Map<string, FileHashRow>,
   allFiles: string[],
   rootDir: string,
-  removed: string[],
-): ChangeResult {
+): { needsHash: NeedsHashItem[]; skipped: number } {
   const needsHash: NeedsHashItem[] = [];
-  const skipped: string[] = [];
+  let skipped = 0;
 
   for (const file of allFiles) {
     const relPath = normalizePath(path.relative(rootDir, file));
@@ -183,16 +183,17 @@ function mtimeAndHashTiers(
     const storedMtime = record.mtime || 0;
     const storedSize = record.size || 0;
     if (storedSize > 0 && stat.mtime === storedMtime && stat.size === storedSize) {
-      skipped.push(relPath);
+      skipped++;
       continue;
     }
     needsHash.push({ file, relPath, stat });
   }
 
-  if (needsHash.length > 0) {
-    debug(`Tier 1: ${skipped.length} skipped by mtime+size, ${needsHash.length} need hash check`);
-  }
+  return { needsHash, skipped };
+}
 
+/** Tier 2: hash candidates from tier 1, classifying changed vs metadata-only. */
+function tierHash(existing: Map<string, FileHashRow>, needsHash: NeedsHashItem[]): ChangedFile[] {
   const changed: ChangedFile[] = [];
   for (const item of needsHash) {
     let content: string | undefined;
@@ -217,11 +218,26 @@ function mtimeAndHashTiers(
       });
     }
   }
+  return changed;
+}
+
+function mtimeAndHashTiers(
+  existing: Map<string, FileHashRow>,
+  allFiles: string[],
+  rootDir: string,
+  removed: string[],
+): ChangeResult {
+  const { needsHash, skipped } = tierMtimeSize(existing, allFiles, rootDir);
+  if (needsHash.length > 0) {
+    debug(`Tier 1: ${skipped} skipped by mtime+size, ${needsHash.length} need hash check`);
+  }
+
+  const changed = tierHash(existing, needsHash);
 
-  const parseChanged = changed.filter((c) => !c.metadataOnly);
   if (needsHash.length > 0) {
+    const parseChangedLen = changed.filter((c) => !c.metadataOnly).length;
     debug(
-      `Tier 2: ${parseChanged.length} actually changed, ${changed.length - parseChanged.length} metadata-only`,
+      `Tier 2: ${parseChangedLen} actually changed, ${changed.length - parseChangedLen} metadata-only`,
     );
   }
 
@@ -512,61 +528,43 @@ function handleIncrementalBuild(ctx: PipelineContext): void {
   purgeAndAddReverseDeps(ctx, changePaths, reverseDeps);
 }
 
-/**
- * Read-only pre-flight check for the native orchestrator.
- *
- * Returns true iff every collected source file has matching mtime+size in
- * `file_hashes` and no DB-tracked file has been removed. When true, the
- * caller can short-circuit before invoking the native orchestrator —
- * matching WASM's ~20 ms early-exit path and avoiding the ~2s flat
- * per-call native rebuild overhead seen in CI (#1054).
- *
- * Intentionally Tier-0/Tier-1 only (journal + mtime/size). Tier-2 content
- * hashing is left to the native side: when this returns false the caller
- * falls through to the orchestrator, which performs its own complete
- * detection and is the source of truth.
- *
- * Conservatively returns false when CFG or dataflow analysis is enabled
- * but the corresponding tables are empty — otherwise the fast-skip would
- * silently suppress the pending-analysis pass that the JS path runs via
- * `runPendingAnalysis`, and CFG/dataflow data would never populate on
- * repos where source files don't change between builds.
- *
- * Pure read of `db` and the filesystem — never mutates either.
- */
-export function detectNoChanges(
-  db: BetterSqlite3Database,
-  allFiles: string[],
-  rootDir: string,
-  opts?: Record<string, unknown>,
-): boolean {
-  // Diagnostic logging gated by env var — used by the bench gate to surface
-  // why the fast-skip is not firing on CI runners (#1066). Off by default to
-  // avoid noise on every regular incremental build.
+/** Diagnostic logger gated by env var, used by both `detectNoChanges` branches. */
+function makeFastSkipLogger(): (reason: string) => void {
   const diag = process.env.CODEGRAPH_FAST_SKIP_DIAG === '1';
-  const log = (reason: string): void => {
+  return (reason: string): void => {
     if (diag) info(`[fast-skip] ${reason}`);
   };
+}
 
-  let hasTable = false;
+/**
+ * Load the `file_hashes` table for the no-change pre-flight.  Returns null
+ * if the table is missing or empty (both → caller must fall through).
+ */
+function loadFileHashesForPreflight(
+  db: BetterSqlite3Database,
+  log: (reason: string) => void,
+): Map<string, FileHashRow> | null {
   try {
     db.prepare('SELECT 1 FROM file_hashes LIMIT 1').get();
-    hasTable = true;
   } catch {
-    /* table missing — first build */
-  }
-  if (!hasTable) {
     log('false: file_hashes table missing');
-    return false;
+    return null;
   }
-
   const rows = db.prepare('SELECT file, hash, mtime, size FROM file_hashes').all() as FileHashRow[];
   if (rows.length === 0) {
     log('false: file_hashes table empty');
-    return false;
+    return null;
   }
-  const existing = new Map<string, FileHashRow>(rows.map((r) => [r.file, r]));
+  return new Map<string, FileHashRow>(rows.map((r) => [r.file, r]));
+}
 
+/** Returns true iff every file in `allFiles` matches a stored mtime+size record. */
+function allFilesMatchStoredStat(
+  existing: Map<string, FileHashRow>,
+  allFiles: string[],
+  rootDir: string,
+  log: (reason: string) => void,
+): boolean {
   const currentFiles = new Set<string>();
   for (const file of allFiles) {
     currentFiles.add(normalizePath(path.relative(rootDir, file)));
@@ -603,21 +601,66 @@ export function detectNoChanges(
       return false;
     }
   }
+  return true;
+}
 
-  // Pending-analysis guard: if CFG/dataflow is enabled but the corresponding
-  // table is empty (analysis newly enabled, or tables wiped between builds),
-  // fall through so the orchestrator / JS pipeline can run runPendingAnalysis.
-  // Mirrors the check at the top of runPendingAnalysis (see line ~244).
-  if (opts) {
-    if (opts.cfg !== false && hasEmptyAnalysisTable(db, 'cfg_blocks')) {
-      log('false: pending-analysis guard — cfg_blocks is empty');
-      return false;
-    }
-    if (opts.dataflow !== false && hasEmptyAnalysisTable(db, 'dataflow')) {
-      log('false: pending-analysis guard — dataflow is empty');
-      return false;
-    }
+/**
+ * Pending-analysis guard: if CFG/dataflow is enabled but the corresponding
+ * table is empty (analysis newly enabled, or tables wiped between builds),
+ * fall through so the orchestrator / JS pipeline can run runPendingAnalysis.
+ * Mirrors the check at the top of runPendingAnalysis.
+ */
+function passesPendingAnalysisGuard(
+  db: BetterSqlite3Database,
+  opts: Record<string, unknown> | undefined,
+  log: (reason: string) => void,
+): boolean {
+  if (!opts) return true;
+  if (opts.cfg !== false && hasEmptyAnalysisTable(db, 'cfg_blocks')) {
+    log('false: pending-analysis guard — cfg_blocks is empty');
+    return false;
   }
+  if (opts.dataflow !== false && hasEmptyAnalysisTable(db, 'dataflow')) {
+    log('false: pending-analysis guard — dataflow is empty');
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Read-only pre-flight check for the native orchestrator.
+ *
+ * Returns true iff every collected source file has matching mtime+size in
+ * `file_hashes` and no DB-tracked file has been removed. When true, the
+ * caller can short-circuit before invoking the native orchestrator —
+ * matching WASM's ~20 ms early-exit path and avoiding the ~2s flat
+ * per-call native rebuild overhead seen in CI (#1054).
+ *
+ * Intentionally Tier-0/Tier-1 only (journal + mtime/size). Tier-2 content
+ * hashing is left to the native side: when this returns false the caller
+ * falls through to the orchestrator, which performs its own complete
+ * detection and is the source of truth.
+ *
+ * Conservatively returns false when CFG or dataflow analysis is enabled
+ * but the corresponding tables are empty — otherwise the fast-skip would
+ * silently suppress the pending-analysis pass that the JS path runs via
+ * `runPendingAnalysis`, and CFG/dataflow data would never populate on
+ * repos where source files don't change between builds.
+ *
+ * Pure read of `db` and the filesystem — never mutates either.
+ */
+export function detectNoChanges(
+  db: BetterSqlite3Database,
+  allFiles: string[],
+  rootDir: string,
+  opts?: Record<string, unknown>,
+): boolean {
+  const log = makeFastSkipLogger();
+  const existing = loadFileHashesForPreflight(db, log);
+  if (!existing) return false;
+
+  if (!allFilesMatchStoredStat(existing, allFiles, rootDir, log)) return false;
+  if (!passesPendingAnalysisGuard(db, opts, log)) return false;
 
   log(`true: all checks passed (${allFiles.length} files)`);
   return true;

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

@@ -136,82 +136,72 @@ function persistBuildMetadata(
   }
 }
 
-/**
- * Run advisory checks on full builds: orphaned embeddings, stale embeddings,
- * and unused exports. Informational only — does not affect correctness.
- */
-function runAdvisoryChecks(ctx: PipelineContext, hasEmbeddings: boolean, buildNow: Date): void {
-  // Batched native path: single napi call for all 3 advisory checks
-  if (ctx.engineName === 'native' && ctx.nativeDb?.runAdvisoryChecks) {
-    const result = ctx.nativeDb.runAdvisoryChecks(hasEmbeddings);
-    if (result.orphanedEmbeddings > 0) {
-      warn(
-        `${result.orphanedEmbeddings} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
-      );
-    }
-    if (result.embedBuiltAt) {
-      const embedTime = new Date(result.embedBuiltAt).getTime();
-      if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
-        warn(
-          'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
-        );
-      }
-    }
-    if (result.unusedExports > 0) {
-      warn(
-        `${result.unusedExports} exported symbol${result.unusedExports > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
-      );
+/** Format the "X exports have zero consumers" warning, with correct plural agreement. */
+function unusedExportsMessage(count: number): string {
+  return `${count} exported symbol${count > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`;
+}
+
+/** Run all three advisory checks via the batched native FFI. */
+function runAdvisoryChecksNative(
+  ctx: PipelineContext,
+  hasEmbeddings: boolean,
+  buildNow: Date,
+): void {
+  const result = ctx.nativeDb!.runAdvisoryChecks!(hasEmbeddings);
+  if (result.orphanedEmbeddings > 0) {
+    warn(
+      `${result.orphanedEmbeddings} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+    );
+  }
+  if (result.embedBuiltAt) {
+    const embedTime = new Date(result.embedBuiltAt).getTime();
+    if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
+      warn('Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.');
     }
-    return;
   }
+  if (result.unusedExports > 0) {
+    warn(unusedExportsMessage(result.unusedExports));
+  }
+}
 
-  const { db } = ctx;
-
-  // Orphaned embeddings warning
-  if (hasEmbeddings) {
-    try {
-      const orphaned = (
-        db
-          .prepare(
-            'SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)',
-          )
-          .get() as { c: number }
-      ).c;
-      if (orphaned > 0) {
-        warn(
-          `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
-        );
-      }
-    } catch {
-      /* ignore - embeddings table may have been dropped */
+function checkOrphanedEmbeddings(ctx: PipelineContext): void {
+  try {
+    const orphaned = (
+      ctx.db
+        .prepare('SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)')
+        .get() as { c: number }
+    ).c;
+    if (orphaned > 0) {
+      warn(
+        `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+      );
     }
+  } catch {
+    /* ignore - embeddings table may have been dropped */
   }
+}
 
-  // Stale embeddings warning (built before current graph rebuild)
-  if (hasEmbeddings) {
-    try {
-      const embedBuiltAt = (
-        db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
-          | { value: string }
-          | undefined
-      )?.value;
-      if (embedBuiltAt) {
-        const embedTime = new Date(embedBuiltAt).getTime();
-        if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
-          warn(
-            'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
-          );
-        }
-      }
-    } catch {
-      /* ignore - embedding_meta table may not exist */
+function checkStaleEmbeddings(ctx: PipelineContext, buildNow: Date): void {
+  try {
+    const embedBuiltAt = (
+      ctx.db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
+        | { value: string }
+        | undefined
+    )?.value;
+    if (!embedBuiltAt) return;
+    const embedTime = new Date(embedBuiltAt).getTime();
+    if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
+      warn('Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.');
     }
+  } catch {
+    /* ignore - embedding_meta table may not exist */
   }
+}
 
-  // Unused exports warning
+function checkUnusedExports(ctx: PipelineContext): void {
   try {
     const unusedCount = (
-      db
+      ctx.db
         .prepare(
           `SELECT COUNT(*) as c FROM nodes
          WHERE exported = 1 AND kind != 'file'
@@ -224,16 +214,28 @@ function runAdvisoryChecks(ctx: PipelineContext, hasEmbeddings: boolean, buildNo
         )
         .get() as { c: number }
     ).c;
-    if (unusedCount > 0) {
-      warn(
-        `${unusedCount} exported symbol${unusedCount > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
-      );
-    }
+    if (unusedCount > 0) warn(unusedExportsMessage(unusedCount));
   } catch {
     /* exported column may not exist on older DBs */
   }
 }
 
+/**
+ * Run advisory checks on full builds: orphaned embeddings, stale embeddings,
+ * and unused exports. Informational only — does not affect correctness.
+ */
+function runAdvisoryChecks(ctx: PipelineContext, hasEmbeddings: boolean, buildNow: Date): void {
+  if (ctx.engineName === 'native' && ctx.nativeDb?.runAdvisoryChecks) {
+    runAdvisoryChecksNative(ctx, hasEmbeddings, buildNow);
+    return;
+  }
+  if (hasEmbeddings) {
+    checkOrphanedEmbeddings(ctx);
+    checkStaleEmbeddings(ctx, buildNow);
+  }
+  checkUnusedExports(ctx);
+}
+
 export async function finalize(ctx: PipelineContext): Promise<void> {
   const { allSymbols, rootDir, isFullBuild, hasEmbeddings, opts } = ctx;