@optave/codegraph 3.1.2 → 3.1.4

package/src/db/repository/nodes.js

@@ -1,5 +1,7 @@
+import { ConfigError } from '../../errors.js';
 import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../kinds.js';
 import { NodeQuery } from '../query-builder.js';
+import { cachedStmt } from './cached-stmt.js';
 
 // ─── Query-builder based lookups (moved from src/db/repository.js) ─────
 
@@ -36,10 +38,12 @@ export function findNodesWithFanIn(db, namePattern, opts = {}) {
  */
 export function findNodesForTriage(db, opts = {}) {
   if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
-    throw new Error(`Invalid kind: ${opts.kind} (expected one of ${EVERY_SYMBOL_KIND.join(', ')})`);
+    throw new ConfigError(
+      `Invalid kind: ${opts.kind} (expected one of ${EVERY_SYMBOL_KIND.join(', ')})`,
+    );
   }
   if (opts.role && !VALID_ROLES.includes(opts.role)) {
-    throw new Error(`Invalid role: ${opts.role} (expected one of ${VALID_ROLES.join(', ')})`);
+    throw new ConfigError(`Invalid role: ${opts.role} (expected one of ${VALID_ROLES.join(', ')})`);
   }
 
   const kindsToUse = opts.kind ? [opts.kind] : ['function', 'method', 'class'];
@@ -100,13 +104,27 @@ export function iterateFunctionNodes(db, opts = {}) {
   return _functionNodeQuery(opts).iterate(db);
 }
 
+// ─── Statement caches (one prepared statement per db instance) ────────────
+// WeakMap keys on the db object so statements are GC'd when the db closes.
+const _countNodesStmt = new WeakMap();
+const _countEdgesStmt = new WeakMap();
+const _countFilesStmt = new WeakMap();
+const _findNodeByIdStmt = new WeakMap();
+const _findNodesByFileStmt = new WeakMap();
+const _findFileNodesStmt = new WeakMap();
+const _getNodeIdStmt = new WeakMap();
+const _getFunctionNodeIdStmt = new WeakMap();
+const _bulkNodeIdsByFileStmt = new WeakMap();
+const _findNodeChildrenStmt = new WeakMap();
+const _findNodeByQualifiedNameStmt = new WeakMap();
+
 /**
  * Count total nodes.
  * @param {object} db
  * @returns {number}
  */
 export function countNodes(db) {
-  return db.prepare('SELECT COUNT(*) AS cnt FROM nodes').get().cnt;
+  return cachedStmt(_countNodesStmt, db, 'SELECT COUNT(*) AS cnt FROM nodes').get().cnt;
 }
 
 /**
@@ -115,7 +133,7 @@ export function countNodes(db) {
  * @returns {number}
  */
 export function countEdges(db) {
-  return db.prepare('SELECT COUNT(*) AS cnt FROM edges').get().cnt;
+  return cachedStmt(_countEdgesStmt, db, 'SELECT COUNT(*) AS cnt FROM edges').get().cnt;
 }
 
 /**
@@ -124,7 +142,7 @@ export function countEdges(db) {
  * @returns {number}
  */
 export function countFiles(db) {
-  return db.prepare('SELECT COUNT(DISTINCT file) AS cnt FROM nodes').get().cnt;
+  return cachedStmt(_countFilesStmt, db, 'SELECT COUNT(DISTINCT file) AS cnt FROM nodes').get().cnt;
 }
 
 // ─── Shared node lookups ───────────────────────────────────────────────
@@ -136,7 +154,7 @@ export function countFiles(db) {
  * @returns {object|undefined}
  */
 export function findNodeById(db, id) {
-  return db.prepare('SELECT * FROM nodes WHERE id = ?').get(id);
+  return cachedStmt(_findNodeByIdStmt, db, 'SELECT * FROM nodes WHERE id = ?').get(id);
 }
 
 /**
@@ -146,9 +164,11 @@ export function findNodeById(db, id) {
  * @returns {object[]}
  */
 export function findNodesByFile(db, file) {
-  return db
-    .prepare("SELECT * FROM nodes WHERE file = ? AND kind != 'file' ORDER BY line")
-    .all(file);
+  return cachedStmt(
+    _findNodesByFileStmt,
+    db,
+    "SELECT * FROM nodes WHERE file = ? AND kind != 'file' ORDER BY line",
+  ).all(file);
 }
 
 /**
@@ -158,15 +178,13 @@ export function findNodesByFile(db, file) {
  * @returns {object[]}
  */
 export function findFileNodes(db, fileLike) {
-  return db.prepare("SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'").all(fileLike);
+  return cachedStmt(
+    _findFileNodesStmt,
+    db,
+    "SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'",
+  ).all(fileLike);
 }
 
-// ─── Statement caches (one prepared statement per db instance) ────────────
-// WeakMap keys on the db object so statements are GC'd when the db closes.
-const _getNodeIdStmt = new WeakMap();
-const _getFunctionNodeIdStmt = new WeakMap();
-const _bulkNodeIdsByFileStmt = new WeakMap();
-
 /**
  * Look up a node's ID by its unique (name, kind, file, line) tuple.
  * Shared by builder, watcher, structure, complexity, cfg, engine.
@@ -178,12 +196,11 @@ const _bulkNodeIdsByFileStmt = new WeakMap();
  * @returns {number|undefined}
  */
 export function getNodeId(db, name, kind, file, line) {
-  let stmt = _getNodeIdStmt.get(db);
-  if (!stmt) {
-    stmt = db.prepare('SELECT id FROM nodes WHERE name = ? AND kind = ? AND file = ? AND line = ?');
-    _getNodeIdStmt.set(db, stmt);
-  }
-  return stmt.get(name, kind, file, line)?.id;
+  return cachedStmt(
+    _getNodeIdStmt,
+    db,
+    'SELECT id FROM nodes WHERE name = ? AND kind = ? AND file = ? AND line = ?',
+  ).get(name, kind, file, line)?.id;
 }
 
 /**
@@ -196,14 +213,11 @@ export function getNodeId(db, name, kind, file, line) {
  * @returns {number|undefined}
  */
 export function getFunctionNodeId(db, name, file, line) {
-  let stmt = _getFunctionNodeIdStmt.get(db);
-  if (!stmt) {
-    stmt = db.prepare(
-      "SELECT id FROM nodes WHERE name = ? AND kind IN ('function','method') AND file = ? AND line = ?",
-    );
-    _getFunctionNodeIdStmt.set(db, stmt);
-  }
-  return stmt.get(name, file, line)?.id;
+  return cachedStmt(
+    _getFunctionNodeIdStmt,
+    db,
+    "SELECT id FROM nodes WHERE name = ? AND kind IN ('function','method') AND file = ? AND line = ?",
+  ).get(name, file, line)?.id;
 }
 
 /**
@@ -215,22 +229,78 @@ export function getFunctionNodeId(db, name, file, line) {
  * @returns {{ id: number, name: string, kind: string, line: number }[]}
  */
 export function bulkNodeIdsByFile(db, file) {
-  let stmt = _bulkNodeIdsByFileStmt.get(db);
-  if (!stmt) {
-    stmt = db.prepare('SELECT id, name, kind, line FROM nodes WHERE file = ?');
-    _bulkNodeIdsByFileStmt.set(db, stmt);
-  }
-  return stmt.all(file);
+  return cachedStmt(
+    _bulkNodeIdsByFileStmt,
+    db,
+    'SELECT id, name, kind, line FROM nodes WHERE file = ?',
+  ).all(file);
 }
 
 /**
  * Find child nodes (parameters, properties, constants) of a parent.
  * @param {object} db
  * @param {number} parentId
- * @returns {{ name: string, kind: string, line: number, end_line: number|null }[]}
+ * @returns {{ name: string, kind: string, line: number, end_line: number|null, qualified_name: string|null, scope: string|null, visibility: string|null }[]}
  */
 export function findNodeChildren(db, parentId) {
-  return db
-    .prepare('SELECT name, kind, line, end_line FROM nodes WHERE parent_id = ? ORDER BY line')
-    .all(parentId);
+  return cachedStmt(
+    _findNodeChildrenStmt,
+    db,
+    'SELECT name, kind, line, end_line, qualified_name, scope, visibility FROM nodes WHERE parent_id = ? ORDER BY line',
+  ).all(parentId);
+}
+
+/** Escape LIKE wildcards in a literal string segment. */
+function escapeLike(s) {
+  return s.replace(/[%_\\]/g, '\\$&');
+}
+
+/**
+ * Find all nodes that belong to a given scope (by scope column).
+ * Enables "all methods of class X" without traversing edges.
+ * @param {object} db
+ * @param {string} scopeName - The scope to search for (e.g., class name)
+ * @param {object} [opts]
+ * @param {string} [opts.kind] - Filter by node kind
+ * @param {string} [opts.file] - Filter by file path (LIKE match)
+ * @returns {object[]}
+ */
+export function findNodesByScope(db, scopeName, opts = {}) {
+  let sql = 'SELECT * FROM nodes WHERE scope = ?';
+  const params = [scopeName];
+  if (opts.kind) {
+    sql += ' AND kind = ?';
+    params.push(opts.kind);
+  }
+  if (opts.file) {
+    sql += " AND file LIKE ? ESCAPE '\\'";
+    params.push(`%${escapeLike(opts.file)}%`);
+  }
+  sql += ' ORDER BY file, line';
+  return db.prepare(sql).all(...params);
+}
+
+/**
+ * Find nodes by qualified name. Returns all matches since the same
+ * qualified_name can exist in different files (e.g., two classes named
+ * `DateHelper.format` in separate modules). Pass `opts.file` to narrow.
+ * @param {object} db
+ * @param {string} qualifiedName - e.g., 'DateHelper.format'
+ * @param {object} [opts]
+ * @param {string} [opts.file] - Filter by file path (LIKE match)
+ * @returns {object[]}
+ */
+export function findNodeByQualifiedName(db, qualifiedName, opts = {}) {
+  if (opts.file) {
+    return db
+      .prepare(
+        "SELECT * FROM nodes WHERE qualified_name = ? AND file LIKE ? ESCAPE '\\' ORDER BY file, line",
+      )
+      .all(qualifiedName, `%${escapeLike(opts.file)}%`);
+  }
+  return cachedStmt(
+    _findNodeByQualifiedNameStmt,
+    db,
+    'SELECT * FROM nodes WHERE qualified_name = ? ORDER BY file, line',
+  ).all(qualifiedName);
 }

package/src/db/repository/sqlite-repository.js

@@ -0,0 +1,219 @@
+import { Repository } from './base.js';
+import { hasCfgTables } from './cfg.js';
+import { getComplexityForNode } from './complexity.js';
+import { hasDataflowTable } from './dataflow.js';
+import {
+  countCrossFileCallers,
+  findAllIncomingEdges,
+  findAllOutgoingEdges,
+  findCalleeNames,
+  findCallees,
+  findCallerNames,
+  findCallers,
+  findCrossFileCallTargets,
+  findDistinctCallers,
+  findImportDependents,
+  findImportSources,
+  findImportTargets,
+  findIntraFileCallEdges,
+  getClassHierarchy,
+} from './edges.js';
+import { hasEmbeddings } from './embeddings.js';
+import { getCallableNodes, getCallEdges, getFileNodesAll, getImportEdges } from './graph-read.js';
+import {
+  bulkNodeIdsByFile,
+  countEdges,
+  countFiles,
+  countNodes,
+  findFileNodes,
+  findNodeById,
+  findNodeByQualifiedName,
+  findNodeChildren,
+  findNodesByFile,
+  findNodesByScope,
+  findNodesForTriage,
+  findNodesWithFanIn,
+  getFunctionNodeId,
+  getNodeId,
+  iterateFunctionNodes,
+  listFunctionNodes,
+} from './nodes.js';
+
+/**
+ * SqliteRepository — wraps existing `fn(db, ...)` repository functions
+ * behind the Repository interface so callers can use `repo.method(...)`.
+ */
+export class SqliteRepository extends Repository {
+  #db;
+
+  /** @param {object} db - better-sqlite3 Database instance */
+  constructor(db) {
+    super();
+    this.#db = db;
+  }
+
+  /** Expose the underlying db for code that still needs raw access. */
+  get db() {
+    return this.#db;
+  }
+
+  // ── Node lookups ──────────────────────────────────────────────────
+
+  findNodeById(id) {
+    return findNodeById(this.#db, id);
+  }
+
+  findNodesByFile(file) {
+    return findNodesByFile(this.#db, file);
+  }
+
+  findFileNodes(fileLike) {
+    return findFileNodes(this.#db, fileLike);
+  }
+
+  findNodesWithFanIn(namePattern, opts) {
+    return findNodesWithFanIn(this.#db, namePattern, opts);
+  }
+
+  countNodes() {
+    return countNodes(this.#db);
+  }
+
+  countEdges() {
+    return countEdges(this.#db);
+  }
+
+  countFiles() {
+    return countFiles(this.#db);
+  }
+
+  getNodeId(name, kind, file, line) {
+    return getNodeId(this.#db, name, kind, file, line);
+  }
+
+  getFunctionNodeId(name, file, line) {
+    return getFunctionNodeId(this.#db, name, file, line);
+  }
+
+  bulkNodeIdsByFile(file) {
+    return bulkNodeIdsByFile(this.#db, file);
+  }
+
+  findNodeChildren(parentId) {
+    return findNodeChildren(this.#db, parentId);
+  }
+
+  findNodesByScope(scopeName, opts) {
+    return findNodesByScope(this.#db, scopeName, opts);
+  }
+
+  findNodeByQualifiedName(qualifiedName, opts) {
+    return findNodeByQualifiedName(this.#db, qualifiedName, opts);
+  }
+
+  listFunctionNodes(opts) {
+    return listFunctionNodes(this.#db, opts);
+  }
+
+  iterateFunctionNodes(opts) {
+    return iterateFunctionNodes(this.#db, opts);
+  }
+
+  findNodesForTriage(opts) {
+    return findNodesForTriage(this.#db, opts);
+  }
+
+  // ── Edge queries ──────────────────────────────────────────────────
+
+  findCallees(nodeId) {
+    return findCallees(this.#db, nodeId);
+  }
+
+  findCallers(nodeId) {
+    return findCallers(this.#db, nodeId);
+  }
+
+  findDistinctCallers(nodeId) {
+    return findDistinctCallers(this.#db, nodeId);
+  }
+
+  findAllOutgoingEdges(nodeId) {
+    return findAllOutgoingEdges(this.#db, nodeId);
+  }
+
+  findAllIncomingEdges(nodeId) {
+    return findAllIncomingEdges(this.#db, nodeId);
+  }
+
+  findCalleeNames(nodeId) {
+    return findCalleeNames(this.#db, nodeId);
+  }
+
+  findCallerNames(nodeId) {
+    return findCallerNames(this.#db, nodeId);
+  }
+
+  findImportTargets(nodeId) {
+    return findImportTargets(this.#db, nodeId);
+  }
+
+  findImportSources(nodeId) {
+    return findImportSources(this.#db, nodeId);
+  }
+
+  findImportDependents(nodeId) {
+    return findImportDependents(this.#db, nodeId);
+  }
+
+  findCrossFileCallTargets(file) {
+    return findCrossFileCallTargets(this.#db, file);
+  }
+
+  countCrossFileCallers(nodeId, file) {
+    return countCrossFileCallers(this.#db, nodeId, file);
+  }
+
+  getClassHierarchy(classNodeId) {
+    return getClassHierarchy(this.#db, classNodeId);
+  }
+
+  findIntraFileCallEdges(file) {
+    return findIntraFileCallEdges(this.#db, file);
+  }
+
+  // ── Graph-read queries ────────────────────────────────────────────
+
+  getCallableNodes() {
+    return getCallableNodes(this.#db);
+  }
+
+  getCallEdges() {
+    return getCallEdges(this.#db);
+  }
+
+  getFileNodesAll() {
+    return getFileNodesAll(this.#db);
+  }
+
+  getImportEdges() {
+    return getImportEdges(this.#db);
+  }
+
+  // ── Optional table checks ─────────────────────────────────────────
+
+  hasCfgTables() {
+    return hasCfgTables(this.#db);
+  }
+
+  hasEmbeddings() {
+    return hasEmbeddings(this.#db);
+  }
+
+  hasDataflowTable() {
+    return hasDataflowTable(this.#db);
+  }
+
+  getComplexityForNode(nodeId) {
+    return getComplexityForNode(this.#db, nodeId);
+  }
+}

package/src/db.js

@@ -29,8 +29,10 @@ export {
   findImportTargets,
   findIntraFileCallEdges,
   findNodeById,
+  findNodeByQualifiedName,
   findNodeChildren,
   findNodesByFile,
+  findNodesByScope,
   findNodesForTriage,
   findNodesWithFanIn,
   getCallableNodes,
@@ -50,9 +52,12 @@ export {
   hasCoChanges,
   hasDataflowTable,
   hasEmbeddings,
+  InMemoryRepository,
   iterateFunctionNodes,
   listFunctionNodes,
   purgeFileData,
   purgeFilesData,
+  Repository,
+  SqliteRepository,
   upsertCoChangeMeta,
 } from './db/repository/index.js';

package/src/embeddings/generator.js

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { closeDb, findDbPath, openDb } from '../db.js';
+import { DbError } from '../errors.js';
+import { warn } from '../logger.js';
+import { embed, getModelConfig } from './models.js';
+import { buildSourceText } from './strategies/source.js';
+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) {
+  return Math.ceil(text.length / 4);
+}
+
+function initEmbeddingsSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS embeddings (
+      node_id INTEGER PRIMARY KEY,
+      vector BLOB NOT NULL,
+      text_preview TEXT,
+      FOREIGN KEY(node_id) REFERENCES nodes(id)
+    );
+    CREATE TABLE IF NOT EXISTS embedding_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT
+    );
+  `);
+
+  // Add full_text column (idempotent — ignore if already exists)
+  try {
+    db.exec('ALTER TABLE embeddings ADD COLUMN full_text TEXT');
+  } catch {
+    /* column already exists */
+  }
+
+  // FTS5 virtual table for BM25 keyword search
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS fts_index USING fts5(
+      name,
+      content,
+      tokenize='unicode61'
+    );
+  `);
+}
+
+/**
+ * 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 = {}) {
+  const strategy = options.strategy || 'structured';
+  const dbPath = customDbPath || findDbPath(null);
+
+  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);
+  initEmbeddingsSchema(db);
+
+  db.exec('DELETE FROM embeddings');
+  db.exec('DELETE FROM embedding_meta');
+  db.exec('DELETE FROM fts_index');
+
+  const nodes = db
+    .prepare(
+      `SELECT * FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
+    )
+    .all();
+
+  console.log(`Building embeddings for ${nodes.length} symbols (strategy: ${strategy})...`);
+
+  const byFile = new Map();
+  for (const node of nodes) {
+    if (!byFile.has(node.file)) byFile.set(node.file, []);
+    byFile.get(node.file).push(node);
+  }
+
+  const texts = [];
+  const nodeIds = [];
+  const nodeNames = [];
+  const previews = [];
+  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;
+    try {
+      lines = fs.readFileSync(fullPath, 'utf-8').split('\n');
+    } catch (err) {
+      warn(`Cannot read ${file} for embeddings: ${err.message}`);
+      continue;
+    }
+
+    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);
+      }
+
+      texts.push(text);
+      nodeIds.push(node.id);
+      nodeNames.push(node.name);
+      previews.push(`${node.name} (${node.kind}) -- ${file}:${node.line}`);
+    }
+  }
+
+  if (overflowCount > 0) {
+    warn(
+      `${overflowCount} symbol(s) exceeded model context window (${contextWindow} tokens) and were truncated`,
+    );
+  }
+
+  console.log(`Embedding ${texts.length} symbols...`);
+  const { vectors, dim } = await embed(texts, modelKey);
+
+  const insert = db.prepare(
+    'INSERT OR REPLACE INTO embeddings (node_id, vector, text_preview, full_text) VALUES (?, ?, ?, ?)',
+  );
+  const insertFts = db.prepare('INSERT INTO fts_index(rowid, name, content) VALUES (?, ?, ?)');
+  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]);
+      insertFts.run(nodeIds[i], nodeNames[i], texts[i]);
+    }
+    insertMeta.run('model', config.name);
+    insertMeta.run('dim', String(dim));
+    insertMeta.run('count', String(vectors.length));
+    insertMeta.run('fts_count', String(vectors.length));
+    insertMeta.run('strategy', strategy);
+    insertMeta.run('built_at', new Date().toISOString());
+    if (overflowCount > 0) {
+      insertMeta.run('truncated_count', String(overflowCount));
+    }
+  });
+  insertAll();
+
+  console.log(
+    `\nStored ${vectors.length} embeddings (${dim}d, ${config.name}, strategy: ${strategy}) in graph.db`,
+  );
+  closeDb(db);
+}

package/src/embeddings/index.js

@@ -0,0 +1,13 @@
+/**
+ * Embeddings subsystem — public API barrel.
+ *
+ * Re-exports everything consumers previously imported from `../embedder.js`.
+ */
+
+export { buildEmbeddings, estimateTokens } from './generator.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';
+export { ftsSearchData } from './search/keyword.js';
+export { multiSearchData, searchData } from './search/semantic.js';
+export { cosineSim } from './stores/sqlite-blob.js';