@optave/codegraph 3.3.0 → 3.4.0

package/src/domain/{queries.js → queries.ts}

@@ -1,5 +1,5 @@
 /**
- * queries.js — Barrel re-export file.
+ * queries.ts — Barrel re-export file.
  *
  * All query logic lives in the sub-modules under src/analysis/ and src/shared/.
  * This file exists purely for backward compatibility so that all existing

package/src/domain/search/{generator.js → generator.ts}

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import type BetterSqlite3 from 'better-sqlite3';
 import { closeDb, findDbPath, openDb } from '../../db/index.js';
 import { warn } from '../../infrastructure/logger.js';
 import { DbError } from '../../shared/errors.js';
+import type { NodeRow } from '../../types.js';
 import { embed, getModelConfig } from './models.js';
 import { buildSourceText } from './strategies/source.js';
 import { buildStructuredText } from './strategies/structured.js';
@@ -11,11 +13,11 @@ import { buildStructuredText } from './strategies/structured.js';
  * Rough token estimate (~4 chars per token for code/English).
  * Conservative — avoids adding a tokenizer dependency.
  */
-export function estimateTokens(text) {
+export function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
-function initEmbeddingsSchema(db) {
+function initEmbeddingsSchema(db: BetterSqlite3.Database): void {
   db.exec(`
     CREATE TABLE IF NOT EXISTS embeddings (
       node_id INTEGER PRIMARY KEY,
@@ -46,17 +48,21 @@ function initEmbeddingsSchema(db) {
   `);
 }
 
+export interface BuildEmbeddingsOptions {
+  strategy?: 'structured' | 'source';
+}
+
 /**
  * Build embeddings for all functions/methods/classes in the graph.
- * @param {string} rootDir - Project root directory
- * @param {string} modelKey - Model identifier from MODELS registry
- * @param {string} [customDbPath] - Override path to graph.db
- * @param {object} [options] - Embedding options
- * @param {string} [options.strategy='structured'] - 'structured' (graph-enriched) or 'source' (raw code)
  */
-export async function buildEmbeddings(rootDir, modelKey, customDbPath, options = {}) {
+export async function buildEmbeddings(
+  rootDir: string,
+  modelKey: string,
+  customDbPath?: string,
+  options: BuildEmbeddingsOptions = {},
+): Promise<void> {
   const strategy = options.strategy || 'structured';
-  const dbPath = customDbPath || findDbPath(null);
+  const dbPath = customDbPath || findDbPath(undefined);
 
   if (!fs.existsSync(dbPath)) {
     throw new DbError(
@@ -65,7 +71,7 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath, options =
     );
   }
 
-  const db = openDb(dbPath);
+  const db = openDb(dbPath) as BetterSqlite3.Database;
   initEmbeddingsSchema(db);
 
   db.exec('DELETE FROM embeddings');
@@ -76,31 +82,31 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath, options =
     .prepare(
       `SELECT * FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
     )
-    .all();
+    .all() as Array<NodeRow & { id: number }>;
 
   console.log(`Building embeddings for ${nodes.length} symbols (strategy: ${strategy})...`);
 
-  const byFile = new Map();
+  const byFile = new Map<string, typeof nodes>();
   for (const node of nodes) {
     if (!byFile.has(node.file)) byFile.set(node.file, []);
-    byFile.get(node.file).push(node);
+    byFile.get(node.file)?.push(node);
   }
 
-  const texts = [];
-  const nodeIds = [];
-  const nodeNames = [];
-  const previews = [];
+  const texts: string[] = [];
+  const nodeIds: number[] = [];
+  const nodeNames: string[] = [];
+  const previews: string[] = [];
   const config = getModelConfig(modelKey);
   const contextWindow = config.contextWindow;
   let overflowCount = 0;
 
   for (const [file, fileNodes] of byFile) {
     const fullPath = path.join(rootDir, file);
-    let lines;
+    let lines: string[];
     try {
       lines = fs.readFileSync(fullPath, 'utf-8').split('\n');
-    } catch (err) {
-      warn(`Cannot read ${file} for embeddings: ${err.message}`);
+    } catch (err: unknown) {
+      warn(`Cannot read ${file} for embeddings: ${(err as Error).message}`);
       continue;
     }
 
@@ -141,7 +147,8 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath, options =
   const insertMeta = db.prepare('INSERT OR REPLACE INTO embedding_meta (key, value) VALUES (?, ?)');
   const insertAll = db.transaction(() => {
     for (let i = 0; i < vectors.length; i++) {
-      insert.run(nodeIds[i], Buffer.from(vectors[i].buffer), previews[i], texts[i]);
+      const vec = vectors[i] as Float32Array;
+      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);

package/src/domain/search/{index.js → index.ts}

@@ -4,7 +4,9 @@
  * Re-exports everything consumers previously imported from `../embedder.js`.
  */
 
+export type { BuildEmbeddingsOptions } from './generator.js';
 export { buildEmbeddings, estimateTokens } from './generator.js';
+export type { ModelConfig } from './models.js';
 export { DEFAULT_MODEL, disposeModel, EMBEDDING_STRATEGIES, embed, MODELS } from './models.js';
 export { search } from './search/cli-formatter.js';
 export { hybridSearchData } from './search/hybrid.js';

package/src/domain/search/{models.js → models.ts}

@@ -3,12 +3,23 @@ import { createInterface } from 'node:readline';
 import { info } from '../../infrastructure/logger.js';
 import { ConfigError, EngineError } from '../../shared/errors.js';
 
-// Lazy-load transformers (heavy, optional module)
-let pipeline = null;
-let extractor = null;
-let activeModel = null;
+export interface ModelConfig {
+  name: string;
+  dim: number;
+  contextWindow: number;
+  desc: string;
+  quantized: boolean;
+}
 
-export const MODELS = {
+// Lazy-load transformers (heavy, optional module)
+let pipeline: unknown = null;
+let extractor: null | {
+  dispose(): Promise<void>;
+  (batch: string[], opts: Record<string, unknown>): Promise<{ data: number[] }>;
+} = null;
+let activeModel: string | null = null;
+
+export const MODELS: Record<string, ModelConfig> = {
   minilm: {
     name: 'Xenova/all-MiniLM-L6-v2',
     dim: 384,
@@ -60,10 +71,10 @@ export const MODELS = {
   },
 };
 
-export const EMBEDDING_STRATEGIES = ['structured', 'source'];
+export const EMBEDDING_STRATEGIES: readonly string[] = ['structured', 'source'];
 
-export const DEFAULT_MODEL = 'nomic-v1.5';
-const BATCH_SIZE_MAP = {
+export const DEFAULT_MODEL: string = 'nomic-v1.5';
+const BATCH_SIZE_MAP: Record<string, number> = {
   minilm: 32,
   'jina-small': 16,
   'jina-base': 8,
@@ -75,7 +86,7 @@ const BATCH_SIZE_MAP = {
 const DEFAULT_BATCH_SIZE = 32;
 
 /** @internal Used by generator.js — not part of the public barrel. */
-export function getModelConfig(modelKey) {
+export function getModelConfig(modelKey?: string): ModelConfig {
   const key = modelKey || DEFAULT_MODEL;
   const config = MODELS[key];
   if (!config) {
@@ -90,24 +101,27 @@ export function getModelConfig(modelKey) {
  * Skips the prompt entirely in non-TTY environments (CI, piped stdin).
  * @internal Not part of the public barrel.
  */
-export function promptInstall(packageName) {
+export function promptInstall(packageName: string): Promise<boolean> {
   if (!process.stdin.isTTY) return Promise.resolve(false);
 
   return new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
-    rl.question(`Semantic search requires ${packageName}. Install it now? [y/N] `, (answer) => {
-      rl.close();
-      if (answer.trim().toLowerCase() !== 'y') return resolve(false);
-      try {
-        execFileSync('npm', ['install', packageName], {
-          stdio: 'inherit',
-          timeout: 300_000,
-        });
-        resolve(true);
-      } catch {
-        resolve(false);
-      }
-    });
+    rl.question(
+      `Semantic search requires ${packageName}. Install it now? [y/N] `,
+      (answer: string) => {
+        rl.close();
+        if (answer.trim().toLowerCase() !== 'y') return resolve(false);
+        try {
+          execFileSync('npm', ['install', packageName], {
+            stdio: 'inherit',
+            timeout: 300_000,
+          });
+          resolve(true);
+        } catch {
+          resolve(false);
+        }
+      },
+    );
   });
 }
 
@@ -117,7 +131,7 @@ export function promptInstall(packageName) {
  * In non-TTY environments, prints an error and exits.
  * @internal Not part of the public barrel.
  */
-export async function loadTransformers() {
+export async function loadTransformers(): Promise<unknown> {
   try {
     return await import('@huggingface/transformers');
   } catch {
@@ -129,7 +143,7 @@ export async function loadTransformers() {
       } catch (loadErr) {
         throw new EngineError(
           `${pkg} was installed but failed to load. Please check your environment.`,
-          { cause: loadErr },
+          { cause: loadErr instanceof Error ? loadErr : undefined },
         );
       }
     }
@@ -141,7 +155,7 @@ export async function loadTransformers() {
  * Dispose the current ONNX session and free memory.
  * Safe to call when no model is loaded (no-op).
  */
-export async function disposeModel() {
+export async function disposeModel(): Promise<void> {
   if (extractor) {
     await extractor.dispose();
     extractor = null;
@@ -149,7 +163,7 @@ export async function disposeModel() {
   activeModel = null;
 }
 
-async function loadModel(modelKey) {
+async function loadModel(modelKey?: string): Promise<{ extractor: unknown; config: ModelConfig }> {
   const config = getModelConfig(modelKey);
 
   if (extractor && activeModel === config.name) return { extractor, config };
@@ -157,15 +171,18 @@ async function loadModel(modelKey) {
   // Dispose previous model before loading a different one
   await disposeModel();
 
-  const transformers = await loadTransformers();
+  const transformers = (await loadTransformers()) as { pipeline: unknown };
   pipeline = transformers.pipeline;
 
   info(`Loading embedding model: ${config.name} (${config.dim}d)...`);
   const pipelineOpts = config.quantized ? { quantized: true } : {};
   try {
-    extractor = await pipeline('feature-extraction', config.name, pipelineOpts);
-  } catch (err) {
-    const msg = err.message || String(err);
+    extractor =
+      await // biome-ignore lint/complexity/noBannedTypes: dynamically loaded transformers pipeline is untyped
+      (pipeline as Function)('feature-extraction', config.name, pipelineOpts);
+  } catch (err: unknown) {
+    const cause = err instanceof Error ? err : undefined;
+    const msg = cause?.message || String(err);
     if (msg.includes('Unauthorized') || msg.includes('401') || msg.includes('gated')) {
       throw new EngineError(
         `Model "${config.name}" requires authentication.\n` +
@@ -173,13 +190,13 @@ async function loadModel(modelKey) {
           `Options:\n` +
           `  1. Set HF_TOKEN env var: export HF_TOKEN=hf_...\n` +
           `  2. Use a public model instead: codegraph embed --model minilm`,
-        { cause: err },
+        { cause },
       );
     }
     throw new EngineError(
       `Failed to load model "${config.name}": ${msg}\n` +
         `Try a different model: codegraph embed --model minilm`,
-      { cause: err },
+      { cause },
     );
   }
   activeModel = config.name;
@@ -190,21 +207,28 @@ async function loadModel(modelKey) {
 /**
  * Generate embeddings for an array of texts.
  */
-export async function embed(texts, modelKey) {
+export async function embed(
+  texts: string[],
+  modelKey?: string,
+): Promise<{ vectors: Float32Array[]; dim: number }> {
   const { extractor: ext, config } = await loadModel(modelKey);
   const dim = config.dim;
-  const results = [];
-  const batchSize = BATCH_SIZE_MAP[modelKey || DEFAULT_MODEL] || DEFAULT_BATCH_SIZE;
+  const results: Float32Array[] = [];
+  const batchSize = BATCH_SIZE_MAP[modelKey || DEFAULT_MODEL] ?? DEFAULT_BATCH_SIZE;
 
   for (let i = 0; i < texts.length; i += batchSize) {
     const batch = texts.slice(i, i + batchSize);
-    const output = await ext(batch, { pooling: 'mean', normalize: true });
+    const output =
+      (await // biome-ignore lint/complexity/noBannedTypes: dynamically loaded extractor is untyped
+      (ext as Function)(batch, { pooling: 'mean', normalize: true })) as {
+        data: number[];
+      };
 
     for (let j = 0; j < batch.length; j++) {
       const start = j * dim;
       const vec = new Float32Array(dim);
       for (let k = 0; k < dim; k++) {
-        vec[k] = output.data[start + k];
+        vec[k] = output.data[start + k] ?? 0;
       }
       results.push(vec);
     }

package/src/domain/search/search/{cli-formatter.js → cli-formatter.ts}

@@ -1,37 +1,43 @@
 import { warn } from '../../../infrastructure/logger.js';
 import { hybridSearchData } from './hybrid.js';
 import { ftsSearchData } from './keyword.js';
+import type { SemanticSearchOpts } from './semantic.js';
 import { multiSearchData, searchData } from './semantic.js';
 
-/**
- * Search with mode support — CLI wrapper with multi-query detection.
- * Modes: 'hybrid' (default), 'semantic', 'keyword'
- */
-export async function search(query, customDbPath, opts = {}) {
+interface SearchOpts extends SemanticSearchOpts {
+  mode?: 'hybrid' | 'semantic' | 'keyword';
+  json?: boolean;
+  ndjson?: boolean;
+  offset?: number;
+}
+
+export async function search(
+  query: string,
+  customDbPath: string | undefined,
+  opts: SearchOpts = {},
+): Promise<void> {
   const mode = opts.mode || 'hybrid';
 
-  // Split by semicolons, trim, filter empties
   const queries = query
     .split(';')
     .map((q) => q.trim())
     .filter((q) => q.length > 0);
 
-  const kindIcon = (kind) => (kind === 'function' ? 'f' : kind === 'class' ? '*' : 'o');
+  const kindIcon = (kind: string): string =>
+    kind === 'function' ? 'f' : kind === 'class' ? '*' : 'o';
 
-  // ─── Keyword-only mode ──────────────────────────────────────────────
+  // Keyword-only mode
   if (mode === 'keyword') {
-    const singleQuery = queries.length === 1 ? queries[0] : query;
+    const singleQuery = queries.length === 1 ? queries[0]! : query;
     const data = ftsSearchData(singleQuery, customDbPath, opts);
     if (!data) {
       console.log('No FTS5 index found. Run `codegraph embed` to build the keyword index.');
       return;
     }
-
     if (opts.json) {
       console.log(JSON.stringify(data, null, 2));
       return;
     }
-
     console.log(`\nKeyword search: "${singleQuery}" (BM25)\n`);
     if (data.results.length === 0) {
       console.log('  No results found.');
@@ -46,18 +52,16 @@ export async function search(query, customDbPath, opts = {}) {
     return;
   }
 
-  // ─── Semantic-only mode ─────────────────────────────────────────────
+  // Semantic-only mode
   if (mode === 'semantic') {
     if (queries.length <= 1) {
       const singleQuery = queries[0] || query;
       const data = await searchData(singleQuery, customDbPath, opts);
       if (!data) return;
-
       if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
         return;
       }
-
       console.log(`\nSemantic search: "${singleQuery}"\n`);
       if (data.results.length === 0) {
         console.log('  No results above threshold.');
@@ -72,12 +76,10 @@ export async function search(query, customDbPath, opts = {}) {
     } else {
       const data = await multiSearchData(queries, customDbPath, opts);
       if (!data) return;
-
       if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
         return;
       }
-
       console.log(`\nMulti-query semantic search (RRF, k=${opts.rrfK || 60}):`);
       for (let i = 0; i < queries.length; i++) console.log(`  [${i + 1}] "${queries[i]}"`);
       console.log();
@@ -101,11 +103,10 @@ export async function search(query, customDbPath, opts = {}) {
     return;
   }
 
-  // ─── Hybrid mode (default) ──────────────────────────────────────────
+  // Hybrid mode (default)
   const data = await hybridSearchData(query, customDbPath, opts);
 
   if (!data) {
-    // No FTS5 index — fall back to semantic-only
     warn(
       'FTS5 index not found — using semantic search only. Re-run `codegraph embed` to enable hybrid mode.',
     );
@@ -134,12 +135,12 @@ export async function search(query, customDbPath, opts = {}) {
       console.log(
         `  RRF ${r.rrf.toFixed(4)}  ${kindIcon(r.kind)} ${r.name} -- ${r.file}:${r.line}`,
       );
-      const parts = [];
+      const parts: string[] = [];
       if (r.bm25Rank != null) {
-        parts.push(`BM25: rank ${r.bm25Rank} (score ${r.bm25Score.toFixed(2)})`);
+        parts.push(`BM25: rank ${r.bm25Rank} (score ${r.bm25Score!.toFixed(2)})`);
       }
       if (r.semanticRank != null) {
-        parts.push(`Semantic: rank ${r.semanticRank} (${(r.similarity * 100).toFixed(1)}%)`);
+        parts.push(`Semantic: rank ${r.semanticRank} (${(r.similarity! * 100).toFixed(1)}%)`);
       }
       if (parts.length > 0) {
         console.log(`    ${parts.join('  |  ')}`);

package/src/domain/search/search/{filters.js → filters.ts}

@@ -1,13 +1,6 @@
-/**
- * Match a file path against a glob pattern.
- * Supports *, **, and ? wildcards. Zero dependencies.
- */
-export function globMatch(filePath, pattern) {
-  // Normalize separators to forward slashes
+export function globMatch(filePath: string, pattern: string): boolean {
   const normalized = filePath.replace(/\\/g, '/');
-  // Escape regex specials except glob chars
   let regex = pattern.replace(/\\/g, '/').replace(/[.+^${}()|[\]\\]/g, '\\$&');
-  // Replace ** first (matches any path segment), then * and ?
   regex = regex.replace(/\*\*/g, '\0');
   regex = regex.replace(/\*/g, '[^/]*');
   regex = regex.replace(/\0/g, '.*');
@@ -15,23 +8,18 @@ export function globMatch(filePath, pattern) {
   try {
     return new RegExp(`^${regex}$`).test(normalized);
   } catch {
-    // Malformed pattern — fall back to substring match
     return normalized.includes(pattern);
   }
 }
 
 const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
 
-/**
- * Apply post-query filters (glob pattern, noTests) to a set of rows.
- * Mutates nothing — returns a new filtered array.
- * @param {Array} rows - Rows with at least a `file` property
- * @param {object} opts
- * @param {string} [opts.filePattern] - Glob pattern (only applied if it contains glob chars)
- * @param {boolean} [opts.noTests] - Exclude test/spec files
- * @returns {Array}
- */
-export function applyFilters(rows, opts = {}) {
+export interface FilterOpts {
+  filePattern?: string | string[];
+  noTests?: boolean;
+}
+
+export function applyFilters<T extends { file: string }>(rows: T[], opts: FilterOpts = {}): T[] {
   let filtered = rows;
   const fp = opts.filePattern;
   const fpArr = Array.isArray(fp) ? fp : fp ? [fp] : [];

package/src/domain/search/search/{hybrid.js → hybrid.ts}

@@ -1,22 +1,41 @@
 import { openReadonlyOrFail } from '../../../db/index.js';
 import { loadConfig } from '../../../infrastructure/config.js';
+import type { BetterSqlite3Database, CodegraphConfig } from '../../../types.js';
 import { hasFtsIndex } from '../stores/fts5.js';
 import { ftsSearchData } from './keyword.js';
+import type { SemanticSearchOpts } from './semantic.js';
 import { searchData } from './semantic.js';
 
-/**
- * Hybrid BM25 + semantic search with RRF fusion.
- * Returns { results: [{ name, kind, file, line, rrf, bm25Score, bm25Rank, similarity, semanticRank }] }
- * or null if no FTS5 index (caller should fall back to semantic-only).
- */
-export async function hybridSearchData(query, customDbPath, opts = {}) {
+interface HybridResult {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  endLine: number | null;
+  role: string | null;
+  fileHash: string | null;
+  rrf: number;
+  bm25Score: number | null;
+  bm25Rank: number | null;
+  similarity: number | null;
+  semanticRank: number | null;
+}
+
+export interface HybridSearchResult {
+  results: HybridResult[];
+}
+
+export async function hybridSearchData(
+  query: string,
+  customDbPath: string | undefined,
+  opts: SemanticSearchOpts = {},
+): Promise<HybridSearchResult | null> {
   const config = opts.config || loadConfig();
-  const searchCfg = config.search || {};
+  const searchCfg = config.search || ({} as CodegraphConfig['search']);
   const limit = opts.limit ?? searchCfg.topK ?? 15;
   const k = opts.rrfK ?? searchCfg.rrfK ?? 60;
   const topK = (opts.limit ?? searchCfg.topK ?? 15) * 5;
 
-  // Split semicolons for multi-query support
   const queries =
     typeof query === 'string'
       ? query
@@ -25,30 +44,41 @@ export async function hybridSearchData(query, customDbPath, opts = {}) {
           .filter((q) => q.length > 0)
       : [query];
 
-  // Check FTS5 availability first (sync, cheap)
-  const checkDb = openReadonlyOrFail(customDbPath);
+  const checkDb = openReadonlyOrFail(customDbPath) as BetterSqlite3Database;
   const ftsAvailable = hasFtsIndex(checkDb);
   checkDb.close();
   if (!ftsAvailable) return null;
 
-  // Collect ranked lists: for each query, one BM25 list + one semantic list
-  const rankedLists = [];
+  interface RankedItem {
+    key: string;
+    rank: number;
+    source: 'bm25' | 'semantic';
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    endLine?: number | null;
+    role?: string | null;
+    fileHash?: string | null;
+    bm25Score?: number;
+    similarity?: number;
+  }
+
+  const rankedLists: RankedItem[][] = [];
 
   for (const q of queries) {
-    // BM25 ranked list (sync)
     const bm25Data = ftsSearchData(q, customDbPath, { ...opts, limit: topK });
     if (bm25Data?.results) {
       rankedLists.push(
         bm25Data.results.map((r, idx) => ({
           key: `${r.name}:${r.file}:${r.line}`,
           rank: idx + 1,
-          source: 'bm25',
+          source: 'bm25' as const,
           ...r,
         })),
       );
     }
 
-    // Semantic ranked list (async)
     const semData = await searchData(q, customDbPath, {
       ...opts,
       limit: topK,
@@ -59,15 +89,29 @@ export async function hybridSearchData(query, customDbPath, opts = {}) {
         semData.results.map((r, idx) => ({
           key: `${r.name}:${r.file}:${r.line}`,
           rank: idx + 1,
-          source: 'semantic',
+          source: 'semantic' as const,
           ...r,
         })),
       );
     }
   }
 
-  // RRF fusion across all ranked lists
-  const fusionMap = new Map();
+  interface FusionEntry {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    endLine: number | null;
+    role: string | null;
+    fileHash: string | null;
+    rrfScore: number;
+    bm25Score: number | null;
+    bm25Rank: number | null;
+    similarity: number | null;
+    semanticRank: number | null;
+  }
+
+  const fusionMap = new Map<string, FusionEntry>();
   for (const list of rankedLists) {
     for (const item of list) {
       if (!fusionMap.has(item.key)) {
@@ -76,9 +120,9 @@ export async function hybridSearchData(query, customDbPath, opts = {}) {
           kind: item.kind,
           file: item.file,
           line: item.line,
-          endLine: item.endLine ?? null,
-          role: item.role ?? null,
-          fileHash: item.fileHash ?? null,
+          endLine: (item.endLine as number | null) ?? null,
+          role: (item.role as string | null) ?? null,
+          fileHash: (item.fileHash as string | null) ?? null,
           rrfScore: 0,
           bm25Score: null,
           bm25Rank: null,
@@ -86,23 +130,23 @@ export async function hybridSearchData(query, customDbPath, opts = {}) {
           semanticRank: null,
         });
       }
-      const entry = fusionMap.get(item.key);
+      const entry = fusionMap.get(item.key)!;
       entry.rrfScore += 1 / (k + item.rank);
       if (item.source === 'bm25') {
         if (entry.bm25Rank === null || item.rank < entry.bm25Rank) {
-          entry.bm25Score = item.bm25Score;
+          entry.bm25Score = (item as RankedItem & { bm25Score?: number }).bm25Score ?? null;
           entry.bm25Rank = item.rank;
         }
       } else {
         if (entry.semanticRank === null || item.rank < entry.semanticRank) {
-          entry.similarity = item.similarity;
+          entry.similarity = (item as RankedItem & { similarity?: number }).similarity ?? null;
           entry.semanticRank = item.rank;
         }
       }
     }
   }
 
-  const results = [...fusionMap.values()]
+  const results: HybridResult[] = [...fusionMap.values()]
     .sort((a, b) => b.rrfScore - a.rrfScore)
     .slice(0, limit)
     .map((e) => ({