@optave/codegraph 3.1.1 → 3.1.3

package/src/db/repository/build-stmts.js

@@ -0,0 +1,104 @@
+/**
+ * Prepare all purge statements once, returning an object of runnable stmts.
+ * Optional tables are wrapped in try/catch — if the table doesn't exist,
+ * that slot is set to null.
+ *
+ * @param {object} db - Open read-write database handle
+ * @returns {object} prepared statements (some may be null)
+ */
+function preparePurgeStmts(db) {
+  const tryPrepare = (sql) => {
+    try {
+      return db.prepare(sql);
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    embeddings: tryPrepare(
+      'DELETE FROM embeddings WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    cfgEdges: tryPrepare(
+      'DELETE FROM cfg_edges WHERE function_node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    cfgBlocks: tryPrepare(
+      'DELETE FROM cfg_blocks WHERE function_node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    dataflow: tryPrepare(
+      'DELETE FROM dataflow WHERE source_id IN (SELECT id FROM nodes WHERE file = ?) OR target_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    complexity: tryPrepare(
+      'DELETE FROM function_complexity WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    nodeMetrics: tryPrepare(
+      'DELETE FROM node_metrics WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+    ),
+    astNodes: tryPrepare('DELETE FROM ast_nodes WHERE file = ?'),
+    // Core tables — always exist
+    edges: db.prepare(
+      'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f) OR target_id IN (SELECT id FROM nodes WHERE file = @f)',
+    ),
+    nodes: db.prepare('DELETE FROM nodes WHERE file = ?'),
+    fileHashes: tryPrepare('DELETE FROM file_hashes WHERE file = ?'),
+  };
+}
+
+/**
+ * Cascade-delete all graph data for a single file across all tables.
+ * Order: dependent tables first, then edges, then nodes, then hashes.
+ *
+ * @param {object} db - Open read-write database handle
+ * @param {string} file - Relative file path to purge
+ * @param {object} [opts]
+ * @param {boolean} [opts.purgeHashes=true] - Also delete file_hashes entry
+ */
+export function purgeFileData(db, file, opts = {}) {
+  const stmts = preparePurgeStmts(db);
+  runPurge(stmts, file, opts);
+}
+
+/**
+ * Run purge using pre-prepared statements for a single file.
+ * @param {object} stmts - Prepared statements from preparePurgeStmts
+ * @param {string} file - Relative file path to purge
+ * @param {object} [opts]
+ * @param {boolean} [opts.purgeHashes=true]
+ */
+function runPurge(stmts, file, opts = {}) {
+  const { purgeHashes = true } = opts;
+
+  // Optional tables
+  stmts.embeddings?.run(file);
+  stmts.cfgEdges?.run(file);
+  stmts.cfgBlocks?.run(file);
+  stmts.dataflow?.run(file, file);
+  stmts.complexity?.run(file);
+  stmts.nodeMetrics?.run(file);
+  stmts.astNodes?.run(file);
+
+  // Core tables
+  stmts.edges.run({ f: file });
+  stmts.nodes.run(file);
+
+  if (purgeHashes) {
+    stmts.fileHashes?.run(file);
+  }
+}
+
+/**
+ * Purge all graph data for multiple files.
+ * Prepares statements once and loops over files for efficiency.
+ *
+ * @param {object} db - Open read-write database handle
+ * @param {string[]} files - Relative file paths to purge
+ * @param {object} [opts]
+ * @param {boolean} [opts.purgeHashes=true]
+ */
+export function purgeFilesData(db, files, opts = {}) {
+  if (!files || files.length === 0) return;
+  const stmts = preparePurgeStmts(db);
+  for (const file of files) {
+    runPurge(stmts, file, opts);
+  }
+}

package/src/db/repository/cached-stmt.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve a cached prepared statement, compiling on first use per db.
+ * Each `cache` WeakMap must always be called with the same `sql` —
+ * the sql argument is only used on the first compile; subsequent calls
+ * return the cached statement regardless of the sql passed.
+ *
+ * @param {WeakMap} cache  - WeakMap keyed by db instance
+ * @param {object}  db     - better-sqlite3 database instance
+ * @param {string}  sql    - SQL to compile on first use
+ * @returns {object} prepared statement
+ */
+export function cachedStmt(cache, db, sql) {
+  let stmt = cache.get(db);
+  if (!stmt) {
+    stmt = db.prepare(sql);
+    cache.set(db, stmt);
+  }
+  return stmt;
+}

package/src/db/repository/cfg.js

@@ -0,0 +1,72 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _getCfgBlocksStmt = new WeakMap();
+const _getCfgEdgesStmt = new WeakMap();
+const _deleteCfgEdgesStmt = new WeakMap();
+const _deleteCfgBlocksStmt = new WeakMap();
+
+/**
+ * Check whether CFG tables exist.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasCfgTables(db) {
+  try {
+    db.prepare('SELECT 1 FROM cfg_blocks LIMIT 0').get();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get CFG blocks for a function node.
+ * @param {object} db
+ * @param {number} functionNodeId
+ * @returns {object[]}
+ */
+export function getCfgBlocks(db, functionNodeId) {
+  return cachedStmt(
+    _getCfgBlocksStmt,
+    db,
+    `SELECT id, block_index, block_type, start_line, end_line, label
+     FROM cfg_blocks WHERE function_node_id = ?
+     ORDER BY block_index`,
+  ).all(functionNodeId);
+}
+
+/**
+ * Get CFG edges for a function node (with block info).
+ * @param {object} db
+ * @param {number} functionNodeId
+ * @returns {object[]}
+ */
+export function getCfgEdges(db, functionNodeId) {
+  return cachedStmt(
+    _getCfgEdgesStmt,
+    db,
+    `SELECT e.kind,
+            sb.block_index AS source_index, sb.block_type AS source_type,
+            tb.block_index AS target_index, tb.block_type AS target_type
+     FROM cfg_edges e
+     JOIN cfg_blocks sb ON e.source_block_id = sb.id
+     JOIN cfg_blocks tb ON e.target_block_id = tb.id
+     WHERE e.function_node_id = ?
+     ORDER BY sb.block_index, tb.block_index`,
+  ).all(functionNodeId);
+}
+
+/**
+ * Delete all CFG data for a function node.
+ * @param {object} db
+ * @param {number} functionNodeId
+ */
+export function deleteCfgForNode(db, functionNodeId) {
+  cachedStmt(_deleteCfgEdgesStmt, db, 'DELETE FROM cfg_edges WHERE function_node_id = ?').run(
+    functionNodeId,
+  );
+  cachedStmt(_deleteCfgBlocksStmt, db, 'DELETE FROM cfg_blocks WHERE function_node_id = ?').run(
+    functionNodeId,
+  );
+}

package/src/db/repository/cochange.js

@@ -0,0 +1,54 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _hasCoChangesStmt = new WeakMap();
+const _getCoChangeMetaStmt = new WeakMap();
+const _upsertCoChangeMetaStmt = new WeakMap();
+
+/**
+ * Check whether the co_changes table has data.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasCoChanges(db) {
+  try {
+    return !!cachedStmt(_hasCoChangesStmt, db, 'SELECT 1 FROM co_changes LIMIT 1').get();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all co-change metadata as a key-value map.
+ * @param {object} db
+ * @returns {Record<string, string>}
+ */
+export function getCoChangeMeta(db) {
+  const meta = {};
+  try {
+    for (const row of cachedStmt(
+      _getCoChangeMetaStmt,
+      db,
+      'SELECT key, value FROM co_change_meta',
+    ).all()) {
+      meta[row.key] = row.value;
+    }
+  } catch {
+    /* table may not exist */
+  }
+  return meta;
+}
+
+/**
+ * Upsert a co-change metadata key-value pair.
+ * @param {object} db
+ * @param {string} key
+ * @param {string} value
+ */
+export function upsertCoChangeMeta(db, key, value) {
+  cachedStmt(
+    _upsertCoChangeMetaStmt,
+    db,
+    'INSERT INTO co_change_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+  ).run(key, value);
+}

package/src/db/repository/complexity.js

@@ -0,0 +1,20 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _getComplexityForNodeStmt = new WeakMap();
+
+/**
+ * Get complexity metrics for a node.
+ * Used by contextData and explainFunctionImpl in queries.js.
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ cognitive: number, cyclomatic: number, max_nesting: number, maintainability_index: number, halstead_volume: number }|undefined}
+ */
+export function getComplexityForNode(db, nodeId) {
+  return cachedStmt(
+    _getComplexityForNodeStmt,
+    db,
+    `SELECT cognitive, cyclomatic, max_nesting, maintainability_index, halstead_volume
+     FROM function_complexity WHERE node_id = ?`,
+  ).get(nodeId);
+}

package/src/db/repository/dataflow.js

@@ -0,0 +1,17 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _hasDataflowTableStmt = new WeakMap();
+
+/**
+ * Check whether the dataflow table exists and has data.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasDataflowTable(db) {
+  try {
+    return cachedStmt(_hasDataflowTableStmt, db, 'SELECT COUNT(*) AS c FROM dataflow').get().c > 0;
+  } catch {
+    return false;
+  }
+}

package/src/db/repository/edges.js

@@ -0,0 +1,281 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Prepared-statement caches (one per db instance) ────────────────────
+const _findCalleesStmt = new WeakMap();
+const _findCallersStmt = new WeakMap();
+const _findDistinctCallersStmt = new WeakMap();
+const _findAllOutgoingStmt = new WeakMap();
+const _findAllIncomingStmt = new WeakMap();
+const _findCalleeNamesStmt = new WeakMap();
+const _findCallerNamesStmt = new WeakMap();
+const _findImportTargetsStmt = new WeakMap();
+const _findImportSourcesStmt = new WeakMap();
+const _findImportDependentsStmt = new WeakMap();
+const _findCrossFileCallTargetsStmt = new WeakMap();
+const _countCrossFileCallersStmt = new WeakMap();
+const _getClassAncestorsStmt = new WeakMap();
+const _findIntraFileCallEdgesStmt = new WeakMap();
+
+// ─── Call-edge queries ──────────────────────────────────────────────────
+
+/**
+ * Find all callees of a node (outgoing 'calls' edges).
+ * Returns full node info including end_line for source display.
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ id: number, name: string, kind: string, file: string, line: number, end_line: number|null }[]}
+ */
+export function findCallees(db, nodeId) {
+  return cachedStmt(
+    _findCalleesStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line, n.end_line
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'calls'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find all callers of a node (incoming 'calls' edges).
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ id: number, name: string, kind: string, file: string, line: number }[]}
+ */
+export function findCallers(db, nodeId) {
+  return cachedStmt(
+    _findCallersStmt,
+    db,
+    `SELECT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls'`,
+  ).all(nodeId);
+}
+
+/**
+ * Find distinct callers of a node (for impact analysis BFS).
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ id: number, name: string, kind: string, file: string, line: number }[]}
+ */
+export function findDistinctCallers(db, nodeId) {
+  return cachedStmt(
+    _findDistinctCallersStmt,
+    db,
+    `SELECT DISTINCT n.id, n.name, n.kind, n.file, n.line
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls'`,
+  ).all(nodeId);
+}
+
+// ─── All-edge queries (no kind filter) ─────────────────────────────────
+
+/**
+ * Find all outgoing edges with edge kind (for queryNameData).
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ name: string, kind: string, file: string, line: number, edge_kind: string }[]}
+ */
+export function findAllOutgoingEdges(db, nodeId) {
+  return cachedStmt(
+    _findAllOutgoingStmt,
+    db,
+    `SELECT n.name, n.kind, n.file, n.line, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ?`,
+  ).all(nodeId);
+}
+
+/**
+ * Find all incoming edges with edge kind (for queryNameData).
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ name: string, kind: string, file: string, line: number, edge_kind: string }[]}
+ */
+export function findAllIncomingEdges(db, nodeId) {
+  return cachedStmt(
+    _findAllIncomingStmt,
+    db,
+    `SELECT n.name, n.kind, n.file, n.line, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ?`,
+  ).all(nodeId);
+}
+
+// ─── Name-only callee/caller lookups (for embedder) ────────────────────
+
+/**
+ * Get distinct callee names for a node, sorted alphabetically.
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {string[]}
+ */
+export function findCalleeNames(db, nodeId) {
+  return cachedStmt(
+    _findCalleeNamesStmt,
+    db,
+    `SELECT DISTINCT n.name
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'calls'
+     ORDER BY n.name`,
+  )
+    .all(nodeId)
+    .map((r) => r.name);
+}
+
+/**
+ * Get distinct caller names for a node, sorted alphabetically.
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {string[]}
+ */
+export function findCallerNames(db, nodeId) {
+  return cachedStmt(
+    _findCallerNamesStmt,
+    db,
+    `SELECT DISTINCT n.name
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls'
+     ORDER BY n.name`,
+  )
+    .all(nodeId)
+    .map((r) => r.name);
+}
+
+// ─── Import-edge queries ───────────────────────────────────────────────
+
+/**
+ * Find outgoing import edges (files this node imports).
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ file: string, edge_kind: string }[]}
+ */
+export function findImportTargets(db, nodeId) {
+  return cachedStmt(
+    _findImportTargetsStmt,
+    db,
+    `SELECT n.file, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind IN ('imports', 'imports-type')`,
+  ).all(nodeId);
+}
+
+/**
+ * Find incoming import edges (files that import this node).
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {{ file: string, edge_kind: string }[]}
+ */
+export function findImportSources(db, nodeId) {
+  return cachedStmt(
+    _findImportSourcesStmt,
+    db,
+    `SELECT n.file, e.kind AS edge_kind
+     FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')`,
+  ).all(nodeId);
+}
+
+/**
+ * Find nodes that import a given node (BFS-ready, returns full node info).
+ * Used by impactAnalysisData for transitive import traversal.
+ * @param {object} db
+ * @param {number} nodeId
+ * @returns {object[]}
+ */
+export function findImportDependents(db, nodeId) {
+  return cachedStmt(
+    _findImportDependentsStmt,
+    db,
+    `SELECT n.* FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')`,
+  ).all(nodeId);
+}
+
+// ─── Cross-file and hierarchy queries ──────────────────────────────────
+
+/**
+ * Get IDs of symbols in a file that are called from other files.
+ * Used for "exported" detection in explain/where/exports.
+ * @param {object} db
+ * @param {string} file
+ * @returns {Set<number>}
+ */
+export function findCrossFileCallTargets(db, file) {
+  return new Set(
+    cachedStmt(
+      _findCrossFileCallTargetsStmt,
+      db,
+      `SELECT DISTINCT e.target_id FROM edges e
+       JOIN nodes caller ON e.source_id = caller.id
+       JOIN nodes target ON e.target_id = target.id
+       WHERE target.file = ? AND caller.file != ? AND e.kind = 'calls'`,
+    )
+      .all(file, file)
+      .map((r) => r.target_id),
+  );
+}
+
+/**
+ * Count callers that are in a different file than the target node.
+ * Used by whereSymbolImpl to determine if a symbol is exported.
+ * @param {object} db
+ * @param {number} nodeId
+ * @param {string} file - The target node's file
+ * @returns {number}
+ */
+export function countCrossFileCallers(db, nodeId, file) {
+  return cachedStmt(
+    _countCrossFileCallersStmt,
+    db,
+    `SELECT COUNT(*) AS cnt FROM edges e JOIN nodes n ON e.source_id = n.id
+     WHERE e.target_id = ? AND e.kind = 'calls' AND n.file != ?`,
+  ).get(nodeId, file).cnt;
+}
+
+/**
+ * Get all ancestor class IDs via extends edges (BFS).
+ * @param {object} db
+ * @param {number} classNodeId
+ * @returns {Set<number>}
+ */
+export function getClassHierarchy(db, classNodeId) {
+  const ancestors = new Set();
+  const queue = [classNodeId];
+  const stmt = cachedStmt(
+    _getClassAncestorsStmt,
+    db,
+    `SELECT n.id, n.name FROM edges e JOIN nodes n ON e.target_id = n.id
+     WHERE e.source_id = ? AND e.kind = 'extends'`,
+  );
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const parents = stmt.all(current);
+    for (const p of parents) {
+      if (!ancestors.has(p.id)) {
+        ancestors.add(p.id);
+        queue.push(p.id);
+      }
+    }
+  }
+  return ancestors;
+}
+
+/**
+ * Find intra-file call edges (caller → callee within the same file).
+ * Used by explainFileImpl for data flow visualization.
+ * @param {object} db
+ * @param {string} file
+ * @returns {{ caller_name: string, callee_name: string }[]}
+ */
+export function findIntraFileCallEdges(db, file) {
+  return cachedStmt(
+    _findIntraFileCallEdgesStmt,
+    db,
+    `SELECT caller.name AS caller_name, callee.name AS callee_name
+     FROM edges e
+     JOIN nodes caller ON e.source_id = caller.id
+     JOIN nodes callee ON e.target_id = callee.id
+     WHERE caller.file = ? AND callee.file = ? AND e.kind = 'calls'
+     ORDER BY caller.line`,
+  ).all(file, file);
+}

package/src/db/repository/embeddings.js

@@ -0,0 +1,51 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _hasEmbeddingsStmt = new WeakMap();
+const _getEmbeddingCountStmt = new WeakMap();
+const _getEmbeddingMetaStmt = new WeakMap();
+
+/**
+ * Check whether the embeddings table has data.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasEmbeddings(db) {
+  try {
+    return !!cachedStmt(_hasEmbeddingsStmt, db, 'SELECT 1 FROM embeddings LIMIT 1').get();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the count of embeddings.
+ * @param {object} db
+ * @returns {number}
+ */
+export function getEmbeddingCount(db) {
+  try {
+    return cachedStmt(_getEmbeddingCountStmt, db, 'SELECT COUNT(*) AS c FROM embeddings').get().c;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Get a single embedding metadata value by key.
+ * @param {object} db
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+export function getEmbeddingMeta(db, key) {
+  try {
+    const row = cachedStmt(
+      _getEmbeddingMetaStmt,
+      db,
+      'SELECT value FROM embedding_meta WHERE key = ?',
+    ).get(key);
+    return row?.value;
+  } catch {
+    return undefined;
+  }
+}

package/src/db/repository/graph-read.js

@@ -0,0 +1,59 @@
+import { cachedStmt } from './cached-stmt.js';
+
+// ─── Statement caches (one prepared statement per db instance) ────────────
+const _getCallableNodesStmt = new WeakMap();
+const _getCallEdgesStmt = new WeakMap();
+const _getFileNodesAllStmt = new WeakMap();
+const _getImportEdgesStmt = new WeakMap();
+
+/**
+ * Get callable nodes (function/method/class) for community detection.
+ * @param {object} db
+ * @returns {{ id: number, name: string, kind: string, file: string }[]}
+ */
+export function getCallableNodes(db) {
+  return cachedStmt(
+    _getCallableNodesStmt,
+    db,
+    "SELECT id, name, kind, file FROM nodes WHERE kind IN ('function','method','class')",
+  ).all();
+}
+
+/**
+ * Get all 'calls' edges.
+ * @param {object} db
+ * @returns {{ source_id: number, target_id: number }[]}
+ */
+export function getCallEdges(db) {
+  return cachedStmt(
+    _getCallEdgesStmt,
+    db,
+    "SELECT source_id, target_id FROM edges WHERE kind = 'calls'",
+  ).all();
+}
+
+/**
+ * Get all file-kind nodes.
+ * @param {object} db
+ * @returns {{ id: number, name: string, file: string }[]}
+ */
+export function getFileNodesAll(db) {
+  return cachedStmt(
+    _getFileNodesAllStmt,
+    db,
+    "SELECT id, name, file FROM nodes WHERE kind = 'file'",
+  ).all();
+}
+
+/**
+ * Get all import edges.
+ * @param {object} db
+ * @returns {{ source_id: number, target_id: number }[]}
+ */
+export function getImportEdges(db) {
+  return cachedStmt(
+    _getImportEdgesStmt,
+    db,
+    "SELECT source_id, target_id FROM edges WHERE kind IN ('imports','imports-type')",
+  ).all();
+}