@optave/codegraph 3.10.0 → 3.11.1

package/src/domain/parser.ts

@@ -322,12 +322,15 @@ export function getParser(parsers: Map<string, Parser | null>, filePath: string)
  * without _tree", which was the source of #1036 — a single file missing one
  * analysis triggered a full-build re-parse of every WASM-parseable file.
  */
-export async function ensureWasmTrees(
+/**
+ * Select files from `fileSymbols` that still need analysis data and are
+ * parseable by an installed WASM grammar. Pure (no I/O) — safe to unit-test.
+ */
+function collectBackfillPending(
   fileSymbols: Map<string, any>,
   rootDir: string,
   needsFn?: (relPath: string, symbols: any) => boolean,
-): Promise<void> {
-  // Collect files that still need analysis data and are parseable by WASM.
+): Array<{ relPath: string; absPath: string; symbols: any }> {
   const pending: Array<{ relPath: string; absPath: string; symbols: any }> = [];
   for (const [relPath, symbols] of fileSymbols) {
     if (symbols._tree) continue; // legacy path — leave existing trees alone
@@ -335,6 +338,15 @@ export async function ensureWasmTrees(
     if (needsFn && !needsFn(relPath, symbols)) continue;
     pending.push({ relPath, absPath: path.join(rootDir, relPath), symbols });
   }
+  return pending;
+}
+
+export async function ensureWasmTrees(
+  fileSymbols: Map<string, any>,
+  rootDir: string,
+  needsFn?: (relPath: string, symbols: any) => boolean,
+): Promise<void> {
+  const pending = collectBackfillPending(fileSymbols, rootDir, needsFn);
   if (pending.length === 0) return;
 
   const pool = getWasmWorkerPool();
@@ -352,30 +364,37 @@ export async function ensureWasmTrees(
   }
 }
 
-/**
- * Merge pre-computed analysis data from a worker result onto existing symbols.
- * Only fills gaps — never overwrites fields the caller already populated.
- * Used to patch native-parsed symbols with worker-produced astNodes / dataflow /
- * per-definition complexity and cfg.
- */
-function mergeAnalysisData(symbols: any, worker: ExtractorOutput): void {
+/** Fill gap-only scalar metadata (`_langId`, `_lineCount`) from the worker output. */
+function mergeScalarMetadata(symbols: any, worker: ExtractorOutput): void {
   if (!symbols._langId && worker._langId) symbols._langId = worker._langId;
   if (!symbols._lineCount && worker._lineCount) symbols._lineCount = worker._lineCount;
+}
+
+/** Fill gap-only analysis arrays (`astNodes`, `dataflow`) from the worker output. */
+function mergeAnalysisArrays(symbols: any, worker: ExtractorOutput): void {
   if (!Array.isArray(symbols.astNodes) && Array.isArray(worker.astNodes)) {
     symbols.astNodes = worker.astNodes;
   }
   if (!symbols.dataflow && worker.dataflow) symbols.dataflow = worker.dataflow;
-  if (worker.typeMap && worker.typeMap.size > 0) {
-    if (!symbols.typeMap || !(symbols.typeMap instanceof Map)) {
-      symbols.typeMap = new Map(worker.typeMap);
-    } else {
-      for (const [k, v] of worker.typeMap) {
-        if (!symbols.typeMap.has(k)) symbols.typeMap.set(k, v);
-      }
-    }
+}
+
+/** Merge worker typeMap into existing symbols.typeMap with first-wins semantics. */
+function mergeTypeMap(symbols: any, worker: ExtractorOutput): void {
+  if (!worker.typeMap || worker.typeMap.size === 0) return;
+  if (!symbols.typeMap || !(symbols.typeMap instanceof Map)) {
+    symbols.typeMap = new Map(worker.typeMap);
+    return;
+  }
+  for (const [k, v] of worker.typeMap) {
+    if (!symbols.typeMap.has(k)) symbols.typeMap.set(k, v);
   }
+}
+
+/** Patch existing definitions with worker complexity/cfg when absent. */
+function mergeDefinitionAnalysis(symbols: any, worker: ExtractorOutput): void {
   const existingDefs: any[] = Array.isArray(symbols.definitions) ? symbols.definitions : [];
   const workerDefs: any[] = Array.isArray(worker.definitions) ? worker.definitions : [];
+  if (existingDefs.length === 0 || workerDefs.length === 0) return;
   // Index existing defs by (kind, name, line) — mirrors engine.ts matching key.
   const byKey = new Map<string, any>();
   for (const d of existingDefs) byKey.set(`${d.kind}|${d.name}|${d.line}`, d);
@@ -389,6 +408,19 @@ function mergeAnalysisData(symbols: any, worker: ExtractorOutput): void {
   }
 }
 
+/**
+ * Merge pre-computed analysis data from a worker result onto existing symbols.
+ * Only fills gaps — never overwrites fields the caller already populated.
+ * Used to patch native-parsed symbols with worker-produced astNodes / dataflow /
+ * per-definition complexity and cfg.
+ */
+function mergeAnalysisData(symbols: any, worker: ExtractorOutput): void {
+  mergeScalarMetadata(symbols, worker);
+  mergeAnalysisArrays(symbols, worker);
+  mergeTypeMap(symbols, worker);
+  mergeDefinitionAnalysis(symbols, worker);
+}
+
 /**
  * Check whether the required WASM grammar files exist on disk.
  */
@@ -457,6 +489,8 @@ export const NATIVE_SUPPORTED_EXTENSIONS: ReadonlySet<string> = new Set([
   '.cc',
   '.cxx',
   '.hpp',
+  '.cu',
+  '.cuh',
   '.kt',
   '.kts',
   '.swift',
@@ -471,6 +505,23 @@ export const NATIVE_SUPPORTED_EXTENSIONS: ReadonlySet<string> = new Set([
   '.hs',
   '.ml',
   '.mli',
+  '.fs',
+  '.fsx',
+  '.fsi',
+  '.m',
+  '.gleam',
+  '.jl',
+  '.clj',
+  '.cljs',
+  '.cljc',
+  '.erl',
+  '.hrl',
+  '.groovy',
+  '.gvy',
+  '.r',
+  '.sol',
+  '.v',
+  '.sv',
 ]);
 
 /**
@@ -520,25 +571,36 @@ export function classifyNativeDrops(relPaths: Iterable<string>): NativeDropClass
 }
 
 /**
- * Render `{ ext → paths[] }` as `ext (n: sample.ext, ...)` slices for log lines.
- * Caps at 3 sample paths per extension and 6 extensions total to keep warnings
- * readable when many languages are dropped at once. Extensions are sorted by
- * descending file count so the loudest offender shows up first; ties keep
- * insertion order. Pure function — safe to unit-test independently.
+ * Render `{ ext → paths[] }` as a multi-line tabular breakdown for log lines.
+ * Each extension occupies its own line so a long warning scans like a table
+ * instead of a wall of semicolon-separated slices. Caps at 3 sample paths per
+ * extension and 6 extensions total to keep output bounded when many languages
+ * are dropped at once. Extensions are sorted by descending file count so the
+ * loudest offender shows up first; ties keep insertion order.
+ *
+ * Returns the empty string for empty input, and otherwise a string that
+ * begins with `\n` so callers can append it directly after the header line
+ * (`"Backfilling via WASM:" + formatDropExtensionSummary(...)`).
+ *
+ * Pure function — safe to unit-test independently.
  */
 export function formatDropExtensionSummary(buckets: Map<string, string[]>): string {
   const MAX_EXTS = 6;
   const MAX_SAMPLES = 3;
   const entries = Array.from(buckets.entries()).sort((a, b) => b[1].length - a[1].length);
-  const shown = entries.slice(0, MAX_EXTS).map(([ext, paths]) => {
+  if (entries.length === 0) return '';
+  const shown = entries.slice(0, MAX_EXTS);
+  const extWidth = Math.max(...shown.map(([ext]) => ext.length));
+  const countWidth = Math.max(...shown.map(([, paths]) => String(paths.length).length));
+  const lines = shown.map(([ext, paths]) => {
     const sample = paths.slice(0, MAX_SAMPLES).join(', ');
-    const more = paths.length > MAX_SAMPLES ? `, +${paths.length - MAX_SAMPLES} more` : '';
-    return `${ext} (${paths.length}: ${sample}${more})`;
+    const more = paths.length > MAX_SAMPLES ? ` (+${paths.length - MAX_SAMPLES} more)` : '';
+    return `  ${ext.padEnd(extWidth)}  ${String(paths.length).padStart(countWidth)}  ${sample}${more}`;
   });
   if (entries.length > MAX_EXTS) {
-    shown.push(`+${entries.length - MAX_EXTS} more extension(s)`);
+    lines.push(`  (+${entries.length - MAX_EXTS} more extension(s))`);
   }
-  return shown.join('; ');
+  return `\n${lines.join('\n')}`;
 }
 
 // ── Unified API ──────────────────────────────────────────────────────────────
@@ -573,24 +635,36 @@ function patchDefinitions(definitions: any[]): void {
   }
 }
 
+/**
+ * Field renames applied to each import record to bridge older native binaries
+ * that emit snake_case names. Each `[camel, snake]` pair becomes:
+ *   `if (imp[camel] === undefined) imp[camel] = imp[snake];`
+ * Defined as data so the loop body stays trivially linear in cognitive complexity.
+ */
+const IMPORT_FIELD_RENAMES: ReadonlyArray<readonly [string, string]> = [
+  ['typeOnly', 'type_only'],
+  ['wildcardReexport', 'wildcard_reexport'],
+  ['pythonImport', 'python_import'],
+  ['goImport', 'go_import'],
+  ['rustUse', 'rust_use'],
+  ['javaImport', 'java_import'],
+  ['csharpUsing', 'csharp_using'],
+  ['rubyRequire', 'ruby_require'],
+  ['phpUse', 'php_use'],
+  ['cInclude', 'c_include'],
+  ['kotlinImport', 'kotlin_import'],
+  ['swiftImport', 'swift_import'],
+  ['scalaImport', 'scala_import'],
+  ['bashSource', 'bash_source'],
+  ['dynamicImport', 'dynamic_import'],
+];
+
 /** Patch import fields for backward compat with older native binaries. */
 function patchImports(imports: any[]): void {
   for (const i of imports) {
-    if (i.typeOnly === undefined) i.typeOnly = i.type_only;
-    if (i.wildcardReexport === undefined) i.wildcardReexport = i.wildcard_reexport;
-    if (i.pythonImport === undefined) i.pythonImport = i.python_import;
-    if (i.goImport === undefined) i.goImport = i.go_import;
-    if (i.rustUse === undefined) i.rustUse = i.rust_use;
-    if (i.javaImport === undefined) i.javaImport = i.java_import;
-    if (i.csharpUsing === undefined) i.csharpUsing = i.csharp_using;
-    if (i.rubyRequire === undefined) i.rubyRequire = i.ruby_require;
-    if (i.phpUse === undefined) i.phpUse = i.php_use;
-    if (i.cInclude === undefined) i.cInclude = i.c_include;
-    if (i.kotlinImport === undefined) i.kotlinImport = i.kotlin_import;
-    if (i.swiftImport === undefined) i.swiftImport = i.swift_import;
-    if (i.scalaImport === undefined) i.scalaImport = i.scala_import;
-    if (i.bashSource === undefined) i.bashSource = i.bash_source;
-    if (i.dynamicImport === undefined) i.dynamicImport = i.dynamic_import;
+    for (const [camel, snake] of IMPORT_FIELD_RENAMES) {
+      if (i[camel] === undefined) i[camel] = i[snake];
+    }
   }
 }
 
@@ -812,11 +886,18 @@ export const LANGUAGE_REGISTRY: LanguageRegistryEntry[] = [
   },
   {
     id: 'fsharp',
-    extensions: ['.fs', '.fsx', '.fsi'],
+    extensions: ['.fs', '.fsx'],
     grammarFile: 'tree-sitter-fsharp.wasm',
     extractor: extractFSharpSymbols,
     required: false,
   },
+  {
+    id: 'fsharp-signature',
+    extensions: ['.fsi'],
+    grammarFile: 'tree-sitter-fsharp_signature.wasm',
+    extractor: extractFSharpSymbols,
+    required: false,
+  },
   {
     id: 'gleam',
     extensions: ['.gleam'],
@@ -1133,18 +1214,16 @@ export async function parseFilesWasmForBackfill(
 }
 
 /**
- * Parse multiple files in bulk and return a Map<relPath, symbols>.
+ * Run the native engine over `filePaths` and ingest the results into `result`.
+ * Returns the set of file paths the native engine successfully parsed and the
+ * TS/TSX files that need a typeMap backfill pass.
  */
-export async function parseFilesAuto(
+function ingestNativeResults(
+  native: any,
   filePaths: string[],
   rootDir: string,
-  opts: ParseEngineOpts = {},
-): Promise<Map<string, ExtractorOutput>> {
-  const { native } = resolveEngine(opts);
-
-  if (!native) return parseFilesWasm(filePaths, rootDir);
-
-  const result = new Map<string, ExtractorOutput>();
+  result: Map<string, ExtractorOutput>,
+): { nativeParsed: Set<string>; needsTypeMap: { filePath: string; relPath: string }[] } {
   // Always extract all analysis data (dataflow + AST nodes) during native parse.
   // This eliminates the need for any downstream WASM re-parse or native standalone calls.
   const nativeResults = native.parseFilesFull
@@ -1167,27 +1246,51 @@ export async function parseFilesAuto(
       needsTypeMap.push({ filePath: r.file, relPath });
     }
   }
-  if (needsTypeMap.length > 0) {
-    await backfillTypeMapBatch(needsTypeMap, result);
-  }
+  return { nativeParsed, needsTypeMap };
+}
 
-  // Engine parity: native may silently drop files whose extensions are in
-  // SUPPORTED_EXTENSIONS (because a WASM grammar exists) but whose Rust
-  // extractor/grammar is missing or fails. WASM handles these — fall back so
-  // both engines process the same file set (#967). Restrict to installed WASM
-  // grammars so we don't warn about files that neither engine can parse.
+/**
+ * Engine parity: native may silently drop files whose extensions are in
+ * SUPPORTED_EXTENSIONS (because a WASM grammar exists) but whose Rust
+ * extractor/grammar is missing or fails. WASM handles these — fall back so
+ * both engines process the same file set (#967). Restrict to installed WASM
+ * grammars so we don't warn about files that neither engine can parse.
+ */
+async function backfillNativeDrops(
+  filePaths: string[],
+  nativeParsed: Set<string>,
+  rootDir: string,
+  result: Map<string, ExtractorOutput>,
+): Promise<void> {
   const installedExts = getInstalledWasmExtensions();
   const dropped = filePaths.filter(
     (f) => !nativeParsed.has(f) && installedExts.has(path.extname(f).toLowerCase()),
   );
-  if (dropped.length > 0) {
-    warn(`Native engine dropped ${dropped.length} file(s); falling back to WASM for parity`);
-    const wasmResults = await parseFilesWasmForBackfill(dropped, rootDir);
-    for (const [relPath, symbols] of wasmResults) {
-      result.set(relPath, symbols);
-    }
+  if (dropped.length === 0) return;
+  warn(`Native engine dropped ${dropped.length} file(s); falling back to WASM for parity`);
+  const wasmResults = await parseFilesWasmForBackfill(dropped, rootDir);
+  for (const [relPath, symbols] of wasmResults) {
+    result.set(relPath, symbols);
   }
+}
 
+/**
+ * Parse multiple files in bulk and return a Map<relPath, symbols>.
+ */
+export async function parseFilesAuto(
+  filePaths: string[],
+  rootDir: string,
+  opts: ParseEngineOpts = {},
+): Promise<Map<string, ExtractorOutput>> {
+  const { native } = resolveEngine(opts);
+  if (!native) return parseFilesWasm(filePaths, rootDir);
+
+  const result = new Map<string, ExtractorOutput>();
+  const { nativeParsed, needsTypeMap } = ingestNativeResults(native, filePaths, rootDir, result);
+  if (needsTypeMap.length > 0) {
+    await backfillTypeMapBatch(needsTypeMap, result);
+  }
+  await backfillNativeDrops(filePaths, nativeParsed, rootDir, result);
   return result;
 }
 

package/src/domain/search/generator.ts

@@ -8,6 +8,19 @@ import { embed, getModelConfig } from './models.js';
 import { buildSourceText } from './strategies/source.js';
 import { buildStructuredText } from './strategies/structured.js';
 
+type EmbeddingNode = NodeRow & { id: number };
+type EmbeddingStrategy = 'structured' | 'source';
+
+interface PreparedEmbeddings {
+  texts: string[];
+  nodeIds: number[];
+  nodeNames: string[];
+  previews: string[];
+  overflowCount: number;
+  filesRead: number;
+  filesSkipped: number;
+}
+
 /**
  * Rough token estimate (~4 chars per token for code/English).
  * Conservative — avoids adding a tokenizer dependency.
@@ -47,47 +60,22 @@ function initEmbeddingsSchema(db: BetterSqlite3Database): void {
   `);
 }
 
-export interface BuildEmbeddingsOptions {
-  strategy?: 'structured' | 'source';
-}
-
 /**
- * Build embeddings for all functions/methods/classes in the graph.
+ * Resolve the repo root for embedding. Prefer the root recorded at build time;
+ * fall back to `<dbParent>` only when the DB lives at the conventional
+ * `<root>/.codegraph/graph.db` layout — otherwise trust the caller's rootDir.
  */
-export async function buildEmbeddings(
-  rootDir: string,
-  modelKey: string,
-  customDbPath?: string,
-  options: BuildEmbeddingsOptions = {},
-): Promise<void> {
-  const strategy = options.strategy || 'structured';
-  const dbPath = customDbPath || findDbPath(undefined);
-
-  if (!fs.existsSync(dbPath)) {
-    throw new DbError(
-      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
-      { file: dbPath },
-    );
-  }
-
-  const db = openDb(dbPath) as BetterSqlite3Database;
-  initEmbeddingsSchema(db);
-
-  // Prefer the repo root recorded at build time — embed may be invoked from a
-  // different cwd (e.g. `codegraph embed --db /abs/path/graph.db`) and the
-  // positional rootDir will be wrong in that case. For legacy DBs without
-  // root_dir metadata, fall back to `<dbParent>` only when the DB lives at
-  // the conventional `<root>/.codegraph/graph.db` layout — otherwise trust
-  // the caller-provided rootDir (which may be an explicit positional arg).
-  // `path.dirname(...)` is always non-empty (`'.'` at minimum), so the
-  // conventional-layout check is required to keep the rootDir path reachable.
+function resolveRoot(db: BetterSqlite3Database, dbPath: string, rootDir: string): string {
   const metaRoot = getBuildMeta(db, 'root_dir');
   const resolvedDbPath = path.resolve(dbPath);
   const dbDirName = path.basename(path.dirname(resolvedDbPath));
   const dbParent =
     dbDirName === '.codegraph' ? path.dirname(path.dirname(resolvedDbPath)) : undefined;
-  const resolvedRoot = metaRoot || dbParent || rootDir;
+  return metaRoot || dbParent || rootDir;
+}
 
+/** Reset embedding tables and load eligible symbols grouped by file. */
+function loadNodesByFile(db: BetterSqlite3Database): Map<string, EmbeddingNode[]> {
   db.exec('DELETE FROM embeddings');
   db.exec('DELETE FROM embedding_meta');
   db.exec('DELETE FROM fts_index');
@@ -96,22 +84,52 @@ export async function buildEmbeddings(
     .prepare(
       `SELECT * FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
     )
-    .all() as Array<NodeRow & { id: number }>;
+    .all() as EmbeddingNode[];
 
-  console.log(`Building embeddings for ${nodes.length} symbols (strategy: ${strategy})...`);
-
-  const byFile = new Map<string, typeof nodes>();
+  const byFile = new Map<string, EmbeddingNode[]>();
   for (const node of nodes) {
     if (!byFile.has(node.file)) byFile.set(node.file, []);
     byFile.get(node.file)?.push(node);
   }
+  return byFile;
+}
+
+/** Build embedding text for a single node, truncating if it would overflow. */
+function buildNodeText(
+  node: EmbeddingNode,
+  file: string,
+  lines: string[],
+  db: BetterSqlite3Database,
+  strategy: EmbeddingStrategy,
+  contextWindow: number,
+): { text: string; overflowed: boolean } {
+  let text =
+    strategy === 'structured'
+      ? buildStructuredText(node, file, lines, db)
+      : buildSourceText(node, file, lines);
+  const tokens = estimateTokens(text);
+  if (tokens > contextWindow) {
+    text = text.slice(0, contextWindow * 4);
+    return { text, overflowed: true };
+  }
+  return { text, overflowed: false };
+}
 
+/**
+ * Walk files in the graph, read source, and produce parallel arrays of
+ * texts / nodeIds / nodeNames / previews ready for embedding.
+ */
+function prepareEmbeddingTexts(
+  byFile: Map<string, EmbeddingNode[]>,
+  db: BetterSqlite3Database,
+  resolvedRoot: string,
+  strategy: EmbeddingStrategy,
+  contextWindow: number,
+): PreparedEmbeddings {
   const texts: string[] = [];
   const nodeIds: number[] = [];
   const nodeNames: string[] = [];
   const previews: string[] = [];
-  const config = getModelConfig(modelKey);
-  const contextWindow = config.contextWindow;
   let overflowCount = 0;
   let filesRead = 0;
   let filesSkipped = 0;
@@ -129,19 +147,8 @@ export async function buildEmbeddings(
     }
 
     for (const node of fileNodes) {
-      let text =
-        strategy === 'structured'
-          ? buildStructuredText(node, file, lines, db)
-          : buildSourceText(node, file, lines);
-
-      // Detect and handle context window overflow
-      const tokens = estimateTokens(text);
-      if (tokens > contextWindow) {
-        overflowCount++;
-        const maxChars = contextWindow * 4;
-        text = text.slice(0, maxChars);
-      }
-
+      const { text, overflowed } = buildNodeText(node, file, lines, db, strategy, contextWindow);
+      if (overflowed) overflowCount++;
       texts.push(text);
       nodeIds.push(node.id);
       nodeNames.push(node.name);
@@ -149,28 +156,19 @@ export async function buildEmbeddings(
     }
   }
 
-  if (overflowCount > 0) {
-    warn(
-      `${overflowCount} symbol(s) exceeded model context window (${contextWindow} tokens) and were truncated`,
-    );
-  }
-
-  // If there were symbols to embed but every file failed to read, the DB was
-  // almost certainly built from a different location than the current cwd.
-  // Surface this clearly instead of emitting a silent "Stored 0 embeddings".
-  if (byFile.size > 0 && filesRead === 0) {
-    closeDb(db);
-    throw new DbError(
-      `embed: could not read any of the ${filesSkipped} source files recorded in the graph — the DB may have been built from a different location than the current working directory.\n` +
-        `Tried resolving against: ${resolvedRoot}\n` +
-        'Pass a positional <dir> argument pointing at the original repo root, or re-run "codegraph build" from that directory.',
-      { file: dbPath },
-    );
-  }
-
-  console.log(`Embedding ${texts.length} symbols...`);
-  const { vectors, dim } = await embed(texts, modelKey);
+  return { texts, nodeIds, nodeNames, previews, overflowCount, filesRead, filesSkipped };
+}
 
+/** Persist vectors, FTS rows, and embedding metadata in a single transaction. */
+function persistEmbeddings(
+  db: BetterSqlite3Database,
+  prepared: PreparedEmbeddings,
+  vectors: Float32Array[],
+  dim: number,
+  modelName: string,
+  strategy: EmbeddingStrategy,
+): void {
+  const { nodeIds, nodeNames, previews, texts, overflowCount } = prepared;
   const insert = db.prepare(
     'INSERT OR REPLACE INTO embeddings (node_id, vector, text_preview, full_text) VALUES (?, ?, ?, ?)',
   );
@@ -182,7 +180,7 @@ export async function buildEmbeddings(
       insert.run(nodeIds[i], Buffer.from(vec.buffer), previews[i], texts[i]);
       insertFts.run(nodeIds[i], nodeNames[i], texts[i]);
     }
-    insertMeta.run('model', config.name);
+    insertMeta.run('model', modelName);
     insertMeta.run('dim', String(dim));
     insertMeta.run('count', String(vectors.length));
     insertMeta.run('fts_count', String(vectors.length));
@@ -193,6 +191,66 @@ export async function buildEmbeddings(
     }
   });
   insertAll();
+}
+
+export interface BuildEmbeddingsOptions {
+  strategy?: EmbeddingStrategy;
+}
+
+/**
+ * Build embeddings for all functions/methods/classes in the graph.
+ */
+export async function buildEmbeddings(
+  rootDir: string,
+  modelKey: string,
+  customDbPath?: string,
+  options: BuildEmbeddingsOptions = {},
+): Promise<void> {
+  const strategy = options.strategy || 'structured';
+  const dbPath = customDbPath || findDbPath(undefined);
+
+  if (!fs.existsSync(dbPath)) {
+    throw new DbError(
+      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
+      { file: dbPath },
+    );
+  }
+
+  const db = openDb(dbPath) as BetterSqlite3Database;
+  initEmbeddingsSchema(db);
+
+  const resolvedRoot = resolveRoot(db, dbPath, rootDir);
+  const byFile = loadNodesByFile(db);
+
+  const nodeCount = [...byFile.values()].reduce((acc, list) => acc + list.length, 0);
+  console.log(`Building embeddings for ${nodeCount} symbols (strategy: ${strategy})...`);
+
+  const config = getModelConfig(modelKey);
+  const prepared = prepareEmbeddingTexts(byFile, db, resolvedRoot, strategy, config.contextWindow);
+
+  if (prepared.overflowCount > 0) {
+    warn(
+      `${prepared.overflowCount} symbol(s) exceeded model context window (${config.contextWindow} tokens) and were truncated`,
+    );
+  }
+
+  // If there were symbols to embed but every file failed to read, the DB was
+  // almost certainly built from a different location than the current cwd.
+  // Surface this clearly instead of emitting a silent "Stored 0 embeddings".
+  if (byFile.size > 0 && prepared.filesRead === 0) {
+    closeDb(db);
+    throw new DbError(
+      `embed: could not read any of the ${prepared.filesSkipped} source files recorded in the graph — the DB may have been built from a different location than the current working directory.\n` +
+        `Tried resolving against: ${resolvedRoot}\n` +
+        'Pass a positional <dir> argument pointing at the original repo root, or re-run "codegraph build" from that directory.',
+      { file: dbPath },
+    );
+  }
+
+  console.log(`Embedding ${prepared.texts.length} symbols...`);
+  const { vectors, dim } = await embed(prepared.texts, modelKey);
+
+  persistEmbeddings(db, prepared, vectors as Float32Array[], dim, config.name, strategy);
 
   console.log(
     `\nStored ${vectors.length} embeddings (${dim}d, ${config.name}, strategy: ${strategy}) in graph.db`,