@optave/codegraph 3.3.0 → 3.4.0

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

@@ -1,17 +1,47 @@
 import { openReadonlyOrFail } from '../../../db/index.js';
 import { buildFileConditionSQL } from '../../../db/query-builder.js';
+import type { BetterSqlite3Database } from '../../../types.js';
 import { normalizeSymbol } from '../../queries.js';
 import { hasFtsIndex, sanitizeFtsQuery } from '../stores/fts5.js';
 import { applyFilters } from './filters.js';
 
-/**
- * BM25 keyword search via FTS5.
- * Returns { results: [{ name, kind, file, line, bm25Score }] } or null if no FTS5 index.
- */
-export function ftsSearchData(query, customDbPath, opts = {}) {
+export interface FtsSearchOpts {
+  limit?: number;
+  kind?: string;
+  filePattern?: string | string[];
+  noTests?: boolean;
+}
+
+interface FtsRow {
+  node_id: number;
+  bm25_score: number;
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  end_line: number | null;
+  role: string | null;
+}
+
+export interface FtsSearchResult {
+  results: Array<{
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    bm25Score: number;
+    [key: string]: unknown;
+  }>;
+}
+
+export function ftsSearchData(
+  query: string,
+  customDbPath: string | undefined,
+  opts: FtsSearchOpts = {},
+): FtsSearchResult | null {
   const limit = opts.limit || 15;
 
-  const db = openReadonlyOrFail(customDbPath);
+  const db = openReadonlyOrFail(customDbPath) as BetterSqlite3Database;
 
   try {
     if (!hasFtsIndex(db)) {
@@ -30,7 +60,7 @@ export function ftsSearchData(query, customDbPath, opts = {}) {
       JOIN nodes n ON f.rowid = n.id
       WHERE fts_index MATCH ?
     `;
-    const params = [ftsQuery];
+    const params: unknown[] = [ftsQuery];
 
     if (opts.kind) {
       sql += ' AND n.kind = ?';
@@ -40,9 +70,6 @@ export function ftsSearchData(query, customDbPath, opts = {}) {
     const fp = opts.filePattern;
     const fpArr = Array.isArray(fp) ? fp : fp ? [fp] : [];
     const isGlob = fpArr.length > 0 && fpArr.some((p) => /[*?[\]]/.test(p));
-    // For non-glob patterns, push filtering into SQL via buildFileConditionSQL
-    // (handles escapeLike + ESCAPE clause). Glob patterns are handled post-query
-    // by applyFilters.
     if (fpArr.length > 0 && !isGlob) {
       const fc = buildFileConditionSQL(fpArr, 'n.file');
       sql += fc.sql;
@@ -50,22 +77,21 @@ export function ftsSearchData(query, customDbPath, opts = {}) {
     }
 
     sql += ' ORDER BY rank LIMIT ?';
-    params.push(limit * 5); // fetch generous set for post-filtering
+    params.push(limit * 5);
 
-    let rows;
+    let rows: FtsRow[];
     try {
-      rows = db.prepare(sql).all(...params);
+      rows = db.prepare(sql).all(...params) as FtsRow[];
     } catch {
-      // Invalid FTS5 query syntax — return empty
       return { results: [] };
     }
 
     rows = applyFilters(rows, opts);
 
-    const hc = new Map();
+    const hc = new Map<string, string>();
     const results = rows.slice(0, limit).map((row) => ({
       ...normalizeSymbol(row, db, hc),
-      bm25Score: -row.bm25_score, // FTS5 rank is negative; negate for display
+      bm25Score: -row.bm25_score,
     }));
 
     return { results };

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

@@ -1,17 +1,39 @@
 import { openReadonlyOrFail } from '../../../db/index.js';
 import { escapeLike } from '../../../db/query-builder.js';
 import { getEmbeddingCount, getEmbeddingMeta } from '../../../db/repository/embeddings.js';
+import type { BetterSqlite3Database } from '../../../types.js';
 import { MODELS } from '../models.js';
 import { applyFilters } from './filters.js';
 
-/**
- * Shared setup for search functions: opens DB, validates embeddings/model, loads rows.
- * Returns { db, rows, modelKey, storedDim } or null on failure (prints error).
- * On null return, the DB is closed. On exception, the DB is also closed
- * (callers only need to close DB from the returned object on the happy path).
- */
-export function prepareSearch(customDbPath, opts = {}) {
-  const db = openReadonlyOrFail(customDbPath);
+export interface PreparedSearch {
+  db: BetterSqlite3Database;
+  rows: Array<{
+    node_id: number;
+    vector: Buffer;
+    text_preview: string;
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    end_line: number | null;
+    role: string | null;
+  }>;
+  modelKey: string | null;
+  storedDim: number | null;
+}
+
+export interface PrepareSearchOpts {
+  model?: string;
+  kind?: string;
+  filePattern?: string | string[];
+  noTests?: boolean;
+}
+
+export function prepareSearch(
+  customDbPath: string | undefined,
+  opts: PrepareSearchOpts = {},
+): PreparedSearch | null {
+  const db = openReadonlyOrFail(customDbPath) as BetterSqlite3Database;
 
   try {
     const count = getEmbeddingCount(db);
@@ -35,7 +57,6 @@ export function prepareSearch(customDbPath, opts = {}) {
       }
     }
 
-    // Pre-filter: allow filtering by kind or file pattern to reduce search space
     const fp = opts.filePattern;
     const fpArr = Array.isArray(fp) ? fp : fp ? [fp] : [];
     const isGlob = fpArr.length > 0 && fpArr.some((p) => /[*?[\]]/.test(p));
@@ -44,8 +65,8 @@ export function prepareSearch(customDbPath, opts = {}) {
     FROM embeddings e
     JOIN nodes n ON e.node_id = n.id
   `;
-    const params = [];
-    const conditions = [];
+    const params: unknown[] = [];
+    const conditions: string[] = [];
     if (opts.kind) {
       conditions.push('n.kind = ?');
       params.push(opts.kind);
@@ -53,7 +74,7 @@ export function prepareSearch(customDbPath, opts = {}) {
     if (fpArr.length > 0 && !isGlob) {
       if (fpArr.length === 1) {
         conditions.push("n.file LIKE ? ESCAPE '\\'");
-        params.push(`%${escapeLike(fpArr[0])}%`);
+        params.push(`%${escapeLike(fpArr[0]!)}%`);
       } else {
         conditions.push(`(${fpArr.map(() => "n.file LIKE ? ESCAPE '\\'").join(' OR ')})`);
         params.push(...fpArr.map((f) => `%${escapeLike(f)}%`));
@@ -63,7 +84,7 @@ export function prepareSearch(customDbPath, opts = {}) {
       sql += ` WHERE ${conditions.join(' AND ')}`;
     }
 
-    let rows = db.prepare(sql).all(...params);
+    let rows = db.prepare(sql).all(...params) as PreparedSearch['rows'];
     rows = applyFilters(rows, opts);
 
     return { db, rows, modelKey, storedDim };

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

@@ -1,17 +1,42 @@
 import { loadConfig } from '../../../infrastructure/config.js';
 import { warn } from '../../../infrastructure/logger.js';
+import type { BetterSqlite3Database, CodegraphConfig } from '../../../types.js';
 import { normalizeSymbol } from '../../queries.js';
 import { embed } from '../models.js';
 import { cosineSim } from '../stores/sqlite-blob.js';
 import { prepareSearch } from './prepare.js';
 
-/**
- * Single-query semantic search — returns data instead of printing.
- * Returns { results: [{ name, kind, file, line, similarity }] } or null on failure.
- */
-export async function searchData(query, customDbPath, opts = {}) {
+export interface SemanticSearchOpts {
+  config?: CodegraphConfig;
+  limit?: number;
+  minScore?: number;
+  model?: string;
+  kind?: string;
+  filePattern?: string | string[];
+  noTests?: boolean;
+  rrfK?: number;
+}
+
+interface SemanticResult {
+  name: string;
+  kind: string;
+  file: string;
+  line: number;
+  similarity: number;
+  [key: string]: unknown;
+}
+
+export interface SearchDataResult {
+  results: SemanticResult[];
+}
+
+export async function searchData(
+  query: string,
+  customDbPath: string | undefined,
+  opts: SemanticSearchOpts = {},
+): Promise<SearchDataResult | 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 minScore = opts.minScore ?? searchCfg.defaultMinScore ?? 0.2;
 
@@ -23,7 +48,7 @@ export async function searchData(query, customDbPath, opts = {}) {
     const {
       vectors: [queryVec],
       dim,
-    } = await embed([query], modelKey);
+    } = await embed([query], modelKey ?? undefined);
 
     if (storedDim && dim !== storedDim) {
       console.log(
@@ -33,15 +58,15 @@ export async function searchData(query, customDbPath, opts = {}) {
       return null;
     }
 
-    const hc = new Map();
-    const results = [];
+    const hc = new Map<string, string>();
+    const results: SemanticResult[] = [];
     for (const row of rows) {
-      const vec = new Float32Array(new Uint8Array(row.vector).buffer);
-      const sim = cosineSim(queryVec, vec);
+      const vec = new Float32Array(new Uint8Array(row.vector as unknown as ArrayBuffer).buffer);
+      const sim = cosineSim(queryVec!, vec);
 
       if (sim >= minScore) {
         results.push({
-          ...normalizeSymbol(row, db, hc),
+          ...normalizeSymbol(row, db as BetterSqlite3Database, hc),
           similarity: sim,
         });
       }
@@ -54,13 +79,25 @@ export async function searchData(query, customDbPath, opts = {}) {
   }
 }
 
-/**
- * Multi-query semantic search with Reciprocal Rank Fusion (RRF).
- * Returns { results: [{ name, kind, file, line, rrf, queryScores }] } or null on failure.
- */
-export async function multiSearchData(queries, customDbPath, opts = {}) {
+export interface MultiSearchResult {
+  results: Array<{
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    rrf: number;
+    queryScores: Array<{ query: string; similarity: number; rank: number }>;
+    [key: string]: unknown;
+  }>;
+}
+
+export async function multiSearchData(
+  queries: string[],
+  customDbPath: string | undefined,
+  opts: SemanticSearchOpts = {},
+): Promise<MultiSearchResult | 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 minScore = opts.minScore ?? searchCfg.defaultMinScore ?? 0.2;
   const k = opts.rrfK ?? searchCfg.rrfK ?? 60;
@@ -70,13 +107,12 @@ export async function multiSearchData(queries, customDbPath, opts = {}) {
   const { db, rows, modelKey, storedDim } = prepared;
 
   try {
-    const { vectors: queryVecs, dim } = await embed(queries, modelKey);
+    const { vectors: queryVecs, dim } = await embed(queries, modelKey ?? undefined);
 
-    // Warn about similar queries that may bias RRF results
     const SIMILARITY_WARN_THRESHOLD = searchCfg.similarityWarnThreshold ?? 0.85;
     for (let i = 0; i < queryVecs.length; i++) {
       for (let j = i + 1; j < queryVecs.length; j++) {
-        const sim = cosineSim(queryVecs[i], queryVecs[j]);
+        const sim = cosineSim(queryVecs[i]!, queryVecs[j]!);
         if (sim >= SIMILARITY_WARN_THRESHOLD) {
           warn(
             `Queries "${queries[i]}" and "${queries[j]}" are very similar ` +
@@ -96,47 +132,47 @@ export async function multiSearchData(queries, customDbPath, opts = {}) {
       return null;
     }
 
-    // Parse row vectors once
-    const rowVecs = rows.map((row) => new Float32Array(new Uint8Array(row.vector).buffer));
+    const rowVecs = rows.map(
+      (row) => new Float32Array(new Uint8Array(row.vector as unknown as ArrayBuffer).buffer),
+    );
 
-    // For each query: compute similarities, filter by minScore, rank
     const perQueryRanked = queries.map((_query, qi) => {
-      const scored = [];
+      const scored: Array<{ rowIndex: number; similarity: number }> = [];
       for (let ri = 0; ri < rows.length; ri++) {
-        const sim = cosineSim(queryVecs[qi], rowVecs[ri]);
+        const sim = cosineSim(queryVecs[qi]!, rowVecs[ri]!);
         if (sim >= minScore) {
           scored.push({ rowIndex: ri, similarity: sim });
         }
       }
       scored.sort((a, b) => b.similarity - a.similarity);
-      // Assign 1-indexed ranks
       return scored.map((item, rank) => ({ ...item, rank: rank + 1 }));
     });
 
-    // Fuse results using RRF: for each unique row, sum 1/(k + rank_i) across queries
-    const fusionMap = new Map(); // rowIndex -> { rrfScore, queryScores[] }
+    const fusionMap = new Map<
+      number,
+      { rrfScore: number; queryScores: Array<{ query: string; similarity: number; rank: number }> }
+    >();
     for (let qi = 0; qi < queries.length; qi++) {
-      for (const item of perQueryRanked[qi]) {
+      for (const item of perQueryRanked[qi]!) {
         if (!fusionMap.has(item.rowIndex)) {
           fusionMap.set(item.rowIndex, { rrfScore: 0, queryScores: [] });
         }
-        const entry = fusionMap.get(item.rowIndex);
+        const entry = fusionMap.get(item.rowIndex)!;
         entry.rrfScore += 1 / (k + item.rank);
         entry.queryScores.push({
-          query: queries[qi],
+          query: queries[qi]!,
           similarity: item.similarity,
           rank: item.rank,
         });
       }
     }
 
-    // Build results sorted by RRF score
-    const hc = new Map();
-    const results = [];
+    const hc = new Map<string, string>();
+    const results: MultiSearchResult['results'] = [];
     for (const [rowIndex, entry] of fusionMap) {
-      const row = rows[rowIndex];
+      const row = rows[rowIndex]!;
       results.push({
-        ...normalizeSymbol(row, db, hc),
+        ...normalizeSymbol(row, db as BetterSqlite3Database, hc),
         rrf: entry.rrfScore,
         queryScores: entry.queryScores,
       });

package/src/domain/search/stores/{fts5.js → fts5.ts}

@@ -1,12 +1,11 @@
+import type { BetterSqlite3Database } from '../../../types.js';
+
 /**
  * Sanitize a user query for FTS5 MATCH syntax.
- * Wraps each token as an implicit OR and escapes special FTS5 characters.
  */
-export function sanitizeFtsQuery(query) {
-  // Remove FTS5 special chars that could cause syntax errors
+export function sanitizeFtsQuery(query: string): string | null {
   const cleaned = query.replace(/[*"():^{}~<>]/g, ' ').trim();
   if (!cleaned) return null;
-  // Split into tokens, wrap with OR for multi-token queries
   const tokens = cleaned.split(/\s+/).filter((t) => t.length > 0);
   if (tokens.length === 0) return null;
   if (tokens.length === 1) return `"${tokens[0]}"`;
@@ -15,12 +14,13 @@ export function sanitizeFtsQuery(query) {
 
 /**
  * Check if the FTS5 index exists in the database.
- * Returns true if fts_index table exists and has rows, false otherwise.
  */
-export function hasFtsIndex(db) {
+export function hasFtsIndex(db: BetterSqlite3Database): boolean {
   try {
-    const row = db.prepare('SELECT COUNT(*) as c FROM fts_index').get();
-    return row.c > 0;
+    const row = db.prepare('SELECT COUNT(*) as c FROM fts_index').get() as
+      | { c: number }
+      | undefined;
+    return (row?.c ?? 0) > 0;
   } catch {
     return false;
   }

package/src/domain/search/stores/sqlite-blob.ts

@@ -0,0 +1,15 @@
+/**
+ * Cosine similarity between two Float32Arrays.
+ */
+export function cosineSim(a: Float32Array, b: Float32Array): number {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}

package/src/domain/search/strategies/{source.js → source.ts}

@@ -1,9 +1,14 @@
+import type { NodeRow } from '../../../types.js';
 import { splitIdentifier } from './text-utils.js';
 
 /**
  * Build raw source-code text for a symbol (original strategy).
  */
-export function buildSourceText(node, file, lines) {
+export function buildSourceText(
+  node: Pick<NodeRow, 'name' | 'kind' | 'line' | 'end_line'>,
+  file: string,
+  lines: string[],
+): string {
   const startLine = Math.max(0, node.line - 1);
   const endLine = node.end_line
     ? Math.min(lines.length, node.end_line)

package/src/domain/search/strategies/{structured.js → structured.ts}

@@ -1,35 +1,40 @@
 import { findCalleeNames, findCallerNames } from '../../../db/index.js';
+import type { BetterSqlite3Database, NodeRow } from '../../../types.js';
 import { extractLeadingComment, splitIdentifier } from './text-utils.js';
 
+interface NodeWithId extends Pick<NodeRow, 'name' | 'kind' | 'file' | 'line'> {
+  id: number;
+}
+
 /**
  * Build graph-enriched text for a symbol using dependency context.
- * Produces compact, semantic text (~100 tokens) instead of full source code.
  */
-export function buildStructuredText(node, file, lines, db) {
+export function buildStructuredText(
+  node: NodeWithId,
+  file: string,
+  lines: string[],
+  db: BetterSqlite3Database,
+): string {
   const readable = splitIdentifier(node.name);
-  const parts = [`${node.kind} ${node.name} (${readable}) in ${file}`];
+  const parts: string[] = [`${node.kind} ${node.name} (${readable}) in ${file}`];
   const startLine = Math.max(0, node.line - 1);
 
-  // Extract parameters from signature (best-effort, single-line)
   const sigLine = lines[startLine] || '';
   const paramMatch = sigLine.match(/\(([^)]*)\)/);
   if (paramMatch?.[1]?.trim()) {
     parts.push(`Parameters: ${paramMatch[1].trim()}`);
   }
 
-  // Graph context: callees (capped at 10)
   const callees = findCalleeNames(db, node.id);
   if (callees.length > 0) {
     parts.push(`Calls: ${callees.slice(0, 10).join(', ')}`);
   }
 
-  // Graph context: callers (capped at 10)
   const callers = findCallerNames(db, node.id);
   if (callers.length > 0) {
     parts.push(`Called by: ${callers.slice(0, 10).join(', ')}`);
   }
 
-  // Leading comment (high semantic value) or first few lines of code
   const comment = extractLeadingComment(lines, startLine);
   if (comment) {
     parts.push(comment);

package/src/domain/search/strategies/{text-utils.js → text-utils.ts}

@@ -1,8 +1,7 @@
 /**
  * Split an identifier into readable words.
- * camelCase/PascalCase -> "camel Case", snake_case -> "snake case", kebab-case -> "kebab case"
  */
-export function splitIdentifier(name) {
+export function splitIdentifier(name: string): string {
   return name
     .replace(/([a-z])([A-Z])/g, '$1 $2')
     .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
@@ -11,15 +10,14 @@ export function splitIdentifier(name) {
 }
 
 /**
- * Extract leading comment text (JSDoc, //, #, etc.) above a function line.
- * Returns the cleaned comment text or null if none found.
+ * Extract leading comment text above a function line.
  */
-export function extractLeadingComment(lines, fnLineIndex) {
+export function extractLeadingComment(lines: string[], fnLineIndex: number): string | null {
   if (fnLineIndex > lines.length) return null;
-  const raw = [];
+  const raw: string[] = [];
   for (let i = fnLineIndex - 1; i >= Math.max(0, fnLineIndex - 15); i--) {
     if (i >= lines.length) continue;
-    const trimmed = lines[i].trim();
+    const trimmed = lines[i]!.trim();
     if (/^(\/\/|\/\*|\*\/|\*|#|\/\/\/)/.test(trimmed)) {
       raw.unshift(trimmed);
     } else if (trimmed === '') {
@@ -32,10 +30,10 @@ export function extractLeadingComment(lines, fnLineIndex) {
   return raw
     .map((line) =>
       line
-        .replace(/^\/\*\*?\s?|\*\/$/g, '') // opening /** or /* and closing */
-        .replace(/^\*\s?/, '') // middle * lines
-        .replace(/^\/\/\/?\s?/, '') // // or ///
-        .replace(/^#\s?/, '') // # (Python/Ruby)
+        .replace(/^\/\*\*?\s?|\*\/$/g, '')
+        .replace(/^\*\s?/, '')
+        .replace(/^\/\/\/?\s?/, '')
+        .replace(/^#\s?/, '')
         .trim(),
     )
     .filter((l) => l.length > 0)