@optave/codegraph 3.1.2 → 3.1.4

package/src/embeddings/search/semantic.js

@@ -0,0 +1,145 @@
+import { warn } from '../../logger.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 = {}) {
+  const limit = opts.limit || 15;
+  const minScore = opts.minScore || 0.2;
+
+  const prepared = prepareSearch(customDbPath, opts);
+  if (!prepared) return null;
+  const { db, rows, modelKey, storedDim } = prepared;
+
+  try {
+    const {
+      vectors: [queryVec],
+      dim,
+    } = await embed([query], modelKey);
+
+    if (storedDim && dim !== storedDim) {
+      console.log(
+        `Warning: query model dimension (${dim}) doesn't match stored embeddings (${storedDim}).`,
+      );
+      console.log(`  Re-run \`codegraph embed\` with the same model, or use --model to match.`);
+      return null;
+    }
+
+    const hc = new Map();
+    const results = [];
+    for (const row of rows) {
+      const vec = new Float32Array(new Uint8Array(row.vector).buffer);
+      const sim = cosineSim(queryVec, vec);
+
+      if (sim >= minScore) {
+        results.push({
+          ...normalizeSymbol(row, db, hc),
+          similarity: sim,
+        });
+      }
+    }
+
+    results.sort((a, b) => b.similarity - a.similarity);
+    return { results: results.slice(0, limit) };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * 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 = {}) {
+  const limit = opts.limit || 15;
+  const minScore = opts.minScore || 0.2;
+  const k = opts.rrfK || 60;
+
+  const prepared = prepareSearch(customDbPath, opts);
+  if (!prepared) return null;
+  const { db, rows, modelKey, storedDim } = prepared;
+
+  try {
+    const { vectors: queryVecs, dim } = await embed(queries, modelKey);
+
+    // Warn about similar queries that may bias RRF results
+    const SIMILARITY_WARN_THRESHOLD = 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]);
+        if (sim >= SIMILARITY_WARN_THRESHOLD) {
+          warn(
+            `Queries "${queries[i]}" and "${queries[j]}" are very similar ` +
+              `(${(sim * 100).toFixed(0)}% cosine similarity). ` +
+              `This may bias RRF results toward their shared matches. ` +
+              `Consider using more distinct queries.`,
+          );
+        }
+      }
+    }
+
+    if (storedDim && dim !== storedDim) {
+      console.log(
+        `Warning: query model dimension (${dim}) doesn't match stored embeddings (${storedDim}).`,
+      );
+      console.log(`  Re-run \`codegraph embed\` with the same model, or use --model to match.`);
+      return null;
+    }
+
+    // Parse row vectors once
+    const rowVecs = rows.map((row) => new Float32Array(new Uint8Array(row.vector).buffer));
+
+    // For each query: compute similarities, filter by minScore, rank
+    const perQueryRanked = queries.map((_query, qi) => {
+      const scored = [];
+      for (let ri = 0; ri < rows.length; 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[] }
+    for (let qi = 0; qi < queries.length; 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);
+        entry.rrfScore += 1 / (k + item.rank);
+        entry.queryScores.push({
+          query: queries[qi],
+          similarity: item.similarity,
+          rank: item.rank,
+        });
+      }
+    }
+
+    // Build results sorted by RRF score
+    const hc = new Map();
+    const results = [];
+    for (const [rowIndex, entry] of fusionMap) {
+      const row = rows[rowIndex];
+      results.push({
+        ...normalizeSymbol(row, db, hc),
+        rrf: entry.rrfScore,
+        queryScores: entry.queryScores,
+      });
+    }
+
+    results.sort((a, b) => b.rrf - a.rrf);
+    return { results: results.slice(0, limit) };
+  } finally {
+    db.close();
+  }
+}

package/src/embeddings/stores/fts5.js

@@ -0,0 +1,27 @@
+/**
+ * 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
+  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]}"`;
+  return tokens.map((t) => `"${t}"`).join(' OR ');
+}
+
+/**
+ * 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) {
+  try {
+    const row = db.prepare('SELECT COUNT(*) as c FROM fts_index').get();
+    return row.c > 0;
+  } catch {
+    return false;
+  }
+}

package/src/embeddings/stores/sqlite-blob.js

@@ -0,0 +1,24 @@
+/**
+ * @typedef {object} VectorStore
+ * @property {(queryVec: Float32Array, rows: Array<{vector: Buffer}>) => Array<{index: number, score: number}>} search
+ *   Score every row against a query vector and return scored indices.
+ *
+ * Future implementations (e.g. HNSW via `hnsw.js`) implement this same shape
+ * for approximate nearest-neighbor search.
+ */
+
+/**
+ * Cosine similarity between two Float32Arrays.
+ */
+export function cosineSim(a, b) {
+  let dot = 0,
+    normA = 0,
+    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/embeddings/strategies/source.js

@@ -0,0 +1,14 @@
+import { splitIdentifier } from './text-utils.js';
+
+/**
+ * Build raw source-code text for a symbol (original strategy).
+ */
+export function buildSourceText(node, file, lines) {
+  const startLine = Math.max(0, node.line - 1);
+  const endLine = node.end_line
+    ? Math.min(lines.length, node.end_line)
+    : Math.min(lines.length, startLine + 15);
+  const context = lines.slice(startLine, endLine).join('\n');
+  const readable = splitIdentifier(node.name);
+  return `${node.kind} ${node.name} (${readable}) in ${file}\n${context}`;
+}

package/src/embeddings/strategies/structured.js

@@ -0,0 +1,43 @@
+import { findCalleeNames, findCallerNames } from '../../db.js';
+import { extractLeadingComment, splitIdentifier } from './text-utils.js';
+
+/**
+ * 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) {
+  const readable = splitIdentifier(node.name);
+  const parts = [`${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);
+  } else {
+    const endLine = Math.min(lines.length, startLine + 4);
+    const snippet = lines.slice(startLine, endLine).join('\n').trim();
+    if (snippet) parts.push(snippet);
+  }
+
+  return parts.join('\n');
+}

package/src/embeddings/strategies/text-utils.js

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

package/src/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Domain error hierarchy for codegraph.
+ *
+ * Library code throws these instead of calling process.exit() or throwing
+ * bare Error instances. The CLI top-level catch formats them for humans;
+ * MCP returns structured { isError, code } responses.
+ */
+
+export class CodegraphError extends Error {
+  /** @type {string} */
+  code;
+
+  /** @type {string|undefined} */
+  file;
+
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code]
+   * @param {string} [opts.file]  - Related file path, if applicable
+   * @param {Error}  [opts.cause] - Original error that triggered this one
+   */
+  constructor(message, { code = 'CODEGRAPH_ERROR', file, cause } = {}) {
+    super(message, { cause });
+    this.name = 'CodegraphError';
+    this.code = code;
+    this.file = file;
+  }
+}
+
+export class ParseError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'PARSE_FAILED', ...opts });
+    this.name = 'ParseError';
+  }
+}
+
+export class DbError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'DB_ERROR', ...opts });
+    this.name = 'DbError';
+  }
+}
+
+export class ConfigError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'CONFIG_INVALID', ...opts });
+    this.name = 'ConfigError';
+  }
+}
+
+export class ResolutionError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'RESOLUTION_FAILED', ...opts });
+    this.name = 'ResolutionError';
+  }
+}
+
+export class EngineError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'ENGINE_UNAVAILABLE', ...opts });
+    this.name = 'EngineError';
+  }
+}
+
+export class AnalysisError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'ANALYSIS_FAILED', ...opts });
+    this.name = 'AnalysisError';
+  }
+}
+
+export class BoundaryError extends CodegraphError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'BOUNDARY_VIOLATION', ...opts });
+    this.name = 'BoundaryError';
+  }
+}