@optave/codegraph 3.1.0 → 3.1.2

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/cfg.js

@@ -0,0 +1,83 @@
+// ─── Statement caches (one prepared statement per db instance) ────────────
+// WeakMap keys on the db object so statements are GC'd when the db closes.
+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) {
+  let stmt = _getCfgBlocksStmt.get(db);
+  if (!stmt) {
+    stmt = db.prepare(
+      `SELECT id, block_index, block_type, start_line, end_line, label
+       FROM cfg_blocks WHERE function_node_id = ?
+       ORDER BY block_index`,
+    );
+    _getCfgBlocksStmt.set(db, stmt);
+  }
+  return stmt.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) {
+  let stmt = _getCfgEdgesStmt.get(db);
+  if (!stmt) {
+    stmt = db.prepare(
+      `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`,
+    );
+    _getCfgEdgesStmt.set(db, stmt);
+  }
+  return stmt.all(functionNodeId);
+}
+
+/**
+ * Delete all CFG data for a function node.
+ * @param {object} db
+ * @param {number} functionNodeId
+ */
+export function deleteCfgForNode(db, functionNodeId) {
+  let delEdges = _deleteCfgEdgesStmt.get(db);
+  if (!delEdges) {
+    delEdges = db.prepare('DELETE FROM cfg_edges WHERE function_node_id = ?');
+    _deleteCfgEdgesStmt.set(db, delEdges);
+  }
+  let delBlocks = _deleteCfgBlocksStmt.get(db);
+  if (!delBlocks) {
+    delBlocks = db.prepare('DELETE FROM cfg_blocks WHERE function_node_id = ?');
+    _deleteCfgBlocksStmt.set(db, delBlocks);
+  }
+  delEdges.run(functionNodeId);
+  delBlocks.run(functionNodeId);
+}

package/src/db/repository/cochange.js

@@ -0,0 +1,41 @@
+/**
+ * Check whether the co_changes table has data.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasCoChanges(db) {
+  try {
+    return !!db.prepare('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 db.prepare('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) {
+  db.prepare(
+    '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,15 @@
+/**
+ * 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 db
+    .prepare(
+      `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,12 @@
+/**
+ * Check whether the dataflow table exists and has data.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasDataflowTable(db) {
+  try {
+    return db.prepare('SELECT COUNT(*) AS c FROM dataflow').get().c > 0;
+  } catch {
+    return false;
+  }
+}

package/src/db/repository/edges.js

@@ -0,0 +1,259 @@
+// ─── 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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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 db
+    .prepare(
+      `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(
+    db
+      .prepare(
+        `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 db
+    .prepare(
+      `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];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const parents = db
+      .prepare(
+        `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'`,
+      )
+      .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 db
+    .prepare(
+      `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,40 @@
+/**
+ * Check whether the embeddings table has data.
+ * @param {object} db
+ * @returns {boolean}
+ */
+export function hasEmbeddings(db) {
+  try {
+    return !!db.prepare('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 db.prepare('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 = db.prepare('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,39 @@
+/**
+ * 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 db
+    .prepare("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 db.prepare("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 db.prepare("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 db
+    .prepare("SELECT source_id, target_id FROM edges WHERE kind IN ('imports','imports-type')")
+    .all();
+}

package/src/db/repository/index.js

@@ -0,0 +1,42 @@
+// Barrel re-export for repository/ modules.
+
+export { purgeFileData, purgeFilesData } from './build-stmts.js';
+export { deleteCfgForNode, getCfgBlocks, getCfgEdges, hasCfgTables } from './cfg.js';
+export { getCoChangeMeta, hasCoChanges, upsertCoChangeMeta } from './cochange.js';
+
+export { getComplexityForNode } from './complexity.js';
+export { hasDataflowTable } from './dataflow.js';
+export {
+  countCrossFileCallers,
+  findAllIncomingEdges,
+  findAllOutgoingEdges,
+  findCalleeNames,
+  findCallees,
+  findCallerNames,
+  findCallers,
+  findCrossFileCallTargets,
+  findDistinctCallers,
+  findImportDependents,
+  findImportSources,
+  findImportTargets,
+  findIntraFileCallEdges,
+  getClassHierarchy,
+} from './edges.js';
+export { getEmbeddingCount, getEmbeddingMeta, hasEmbeddings } from './embeddings.js';
+export { getCallableNodes, getCallEdges, getFileNodesAll, getImportEdges } from './graph-read.js';
+export {
+  bulkNodeIdsByFile,
+  countEdges,
+  countFiles,
+  countNodes,
+  findFileNodes,
+  findNodeById,
+  findNodeChildren,
+  findNodesByFile,
+  findNodesForTriage,
+  findNodesWithFanIn,
+  getFunctionNodeId,
+  getNodeId,
+  iterateFunctionNodes,
+  listFunctionNodes,
+} from './nodes.js';