@optave/codegraph 3.1.3 → 3.1.5

package/src/db/connection.js

@@ -1,7 +1,60 @@
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
-import { warn } from '../logger.js';
+import { debug, warn } from '../infrastructure/logger.js';
+import { DbError } from '../shared/errors.js';
+import { Repository } from './repository/base.js';
+import { SqliteRepository } from './repository/sqlite-repository.js';
+
+let _cachedRepoRoot; // undefined = not computed, null = not a git repo
+let _cachedRepoRootCwd; // cwd at the time the cache was populated
+
+/**
+ * Return the git worktree/repo root for the given directory (or cwd).
+ * Uses `git rev-parse --show-toplevel` which returns the correct root
+ * for both regular repos and git worktrees.
+ * Results are cached per-process when called without arguments.
+ * The cache is keyed on cwd so it invalidates if the working directory changes
+ * (e.g. MCP server serving multiple sessions).
+ * @param {string} [fromDir] - Directory to resolve from (defaults to cwd)
+ * @returns {string | null} Absolute path to repo root, or null if not in a git repo
+ */
+export function findRepoRoot(fromDir) {
+  const dir = fromDir || process.cwd();
+  if (!fromDir && _cachedRepoRoot !== undefined && _cachedRepoRootCwd === dir) {
+    return _cachedRepoRoot;
+  }
+  let root = null;
+  try {
+    const raw = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: dir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    // Use realpathSync to resolve symlinks (macOS /var → /private/var) and
+    // 8.3 short names (Windows RUNNER~1 → runneradmin) so the ceiling path
+    // matches the realpathSync'd dir in findDbPath.
+    try {
+      root = fs.realpathSync(raw);
+    } catch {
+      root = path.resolve(raw);
+    }
+  } catch {
+    root = null;
+  }
+  if (!fromDir) {
+    _cachedRepoRoot = root;
+    _cachedRepoRootCwd = dir;
+  }
+  return root;
+}
+
+/** Reset the cached repo root (for testing). */
+export function _resetRepoRootCache() {
+  _cachedRepoRoot = undefined;
+  _cachedRepoRootCwd = undefined;
+}
 
 function isProcessAlive(pid) {
   try {
@@ -43,6 +96,22 @@ function releaseAdvisoryLock(lockPath) {
   }
 }
 
+/**
+ * Check if two paths refer to the same directory.
+ * Handles Windows 8.3 short names (RUNNER~1 vs runneradmin) and macOS
+ * symlinks (/tmp vs /private/tmp) where string comparison fails.
+ */
+function isSameDirectory(a, b) {
+  if (path.resolve(a) === path.resolve(b)) return true;
+  try {
+    const sa = fs.statSync(a);
+    const sb = fs.statSync(b);
+    return sa.dev === sb.dev && sa.ino === sb.ino;
+  } catch {
+    return false;
+  }
+}
+
 export function openDb(dbPath) {
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -61,15 +130,41 @@ export function closeDb(db) {
 
 export function findDbPath(customPath) {
   if (customPath) return path.resolve(customPath);
-  let dir = process.cwd();
+  const rawCeiling = findRepoRoot();
+  // Normalize ceiling with realpathSync to resolve 8.3 short names (Windows
+  // RUNNER~1 → runneradmin) and symlinks (macOS /var → /private/var).
+  // findRepoRoot already applies realpathSync internally, but the git output
+  // may still contain short names on some Windows CI environments.
+  let ceiling;
+  if (rawCeiling) {
+    try {
+      ceiling = fs.realpathSync(rawCeiling);
+    } catch {
+      ceiling = rawCeiling;
+    }
+  } else {
+    ceiling = null;
+  }
+  // Resolve symlinks (e.g. macOS /var → /private/var) so dir matches ceiling from git
+  let dir;
+  try {
+    dir = fs.realpathSync(process.cwd());
+  } catch {
+    dir = process.cwd();
+  }
   while (true) {
     const candidate = path.join(dir, '.codegraph', 'graph.db');
     if (fs.existsSync(candidate)) return candidate;
+    if (ceiling && isSameDirectory(dir, ceiling)) {
+      debug(`findDbPath: stopped at git ceiling ${ceiling}`);
+      break;
+    }
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return path.join(process.cwd(), '.codegraph', 'graph.db');
+  const base = ceiling || process.cwd();
+  return path.join(base, '.codegraph', 'graph.db');
 }
 
 /**
@@ -78,11 +173,39 @@ export function findDbPath(customPath) {
 export function openReadonlyOrFail(customPath) {
   const dbPath = findDbPath(customPath);
   if (!fs.existsSync(dbPath)) {
-    console.error(
-      `No codegraph database found at ${dbPath}.\n` +
-        `Run "codegraph build" first to analyze your codebase.`,
+    throw new DbError(
+      `No codegraph database found at ${dbPath}.\nRun "codegraph build" first to analyze your codebase.`,
+      { file: dbPath },
     );
-    process.exit(1);
   }
   return new Database(dbPath, { readonly: true });
 }
+
+/**
+ * Open a Repository from either an injected instance or a DB path.
+ *
+ * When `opts.repo` is a Repository instance, returns it directly (no DB opened).
+ * Otherwise opens a readonly SQLite DB and wraps it in SqliteRepository.
+ *
+ * @param {string} [customDbPath] - Path to graph.db (ignored when opts.repo is set)
+ * @param {object} [opts]
+ * @param {Repository} [opts.repo] - Pre-built Repository to use instead of SQLite
+ * @returns {{ repo: Repository, close(): void }}
+ */
+export function openRepo(customDbPath, opts = {}) {
+  if (opts.repo != null) {
+    if (!(opts.repo instanceof Repository)) {
+      throw new TypeError(
+        `openRepo: opts.repo must be a Repository instance, got ${Object.prototype.toString.call(opts.repo)}`,
+      );
+    }
+    return { repo: opts.repo, close() {} };
+  }
+  const db = openReadonlyOrFail(customDbPath);
+  return {
+    repo: new SqliteRepository(db),
+    close() {
+      db.close();
+    },
+  };
+}

package/src/{db.js → db/index.js}

@@ -1,13 +1,20 @@
-// Barrel re-export — keeps all existing `import { ... } from './db.js'` working.
-export { closeDb, findDbPath, openDb, openReadonlyOrFail } from './db/connection.js';
-export { getBuildMeta, initSchema, MIGRATIONS, setBuildMeta } from './db/migrations.js';
+// Barrel re-export — keeps all existing `import { ... } from '…/db/index.js'` working.
+export {
+  closeDb,
+  findDbPath,
+  findRepoRoot,
+  openDb,
+  openReadonlyOrFail,
+  openRepo,
+} from './connection.js';
+export { getBuildMeta, initSchema, MIGRATIONS, setBuildMeta } from './migrations.js';
 export {
   fanInJoinSQL,
   fanOutJoinSQL,
   kindInClause,
   NodeQuery,
   testFilterSQL,
-} from './db/query-builder.js';
+} from './query-builder.js';
 export {
   bulkNodeIdsByFile,
   countCrossFileCallers,
@@ -29,8 +36,10 @@ export {
   findImportTargets,
   findIntraFileCallEdges,
   findNodeById,
+  findNodeByQualifiedName,
   findNodeChildren,
   findNodesByFile,
+  findNodesByScope,
   findNodesForTriage,
   findNodesWithFanIn,
   getCallableNodes,
@@ -50,9 +59,12 @@ export {
   hasCoChanges,
   hasDataflowTable,
   hasEmbeddings,
+  InMemoryRepository,
   iterateFunctionNodes,
   listFunctionNodes,
   purgeFileData,
   purgeFilesData,
+  Repository,
+  SqliteRepository,
   upsertCoChangeMeta,
-} from './db/repository/index.js';
+} from './repository/index.js';

package/src/db/migrations.js

@@ -1,4 +1,4 @@
-import { debug } from '../logger.js';
+import { debug } from '../infrastructure/logger.js';
 
 // ─── Schema Migrations ─────────────────────────────────────────────────
 export const MIGRATIONS = [
@@ -229,6 +229,17 @@ export const MIGRATIONS = [
       CREATE INDEX IF NOT EXISTS idx_nodes_exported ON nodes(exported);
     `,
   },
+  {
+    version: 15,
+    up: `
+      ALTER TABLE nodes ADD COLUMN qualified_name TEXT;
+      ALTER TABLE nodes ADD COLUMN scope TEXT;
+      ALTER TABLE nodes ADD COLUMN visibility TEXT;
+      UPDATE nodes SET qualified_name = name WHERE qualified_name IS NULL;
+      CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name);
+      CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope);
+    `,
+  },
 ];
 
 export function getBuildMeta(db, key) {
@@ -309,4 +320,34 @@ export function initSchema(db) {
   } catch {
     /* already exists */
   }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN qualified_name TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN scope TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN visibility TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('UPDATE nodes SET qualified_name = name WHERE qualified_name IS NULL');
+  } catch {
+    /* nodes table may not exist yet */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_qualified_name ON nodes(qualified_name)');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_scope ON nodes(scope)');
+  } catch {
+    /* already exists */
+  }
 }

package/src/db/query-builder.js

@@ -1,4 +1,5 @@
-import { EVERY_EDGE_KIND } from '../kinds.js';
+import { DbError } from '../shared/errors.js';
+import { EVERY_EDGE_KIND } from '../shared/kinds.js';
 
 // ─── Validation Helpers ─────────────────────────────────────────────
 
@@ -12,13 +13,13 @@ const SAFE_SELECT_TOKEN_RE =
 
 function validateAlias(alias) {
   if (!SAFE_ALIAS_RE.test(alias)) {
-    throw new Error(`Invalid SQL alias: ${alias}`);
+    throw new DbError(`Invalid SQL alias: ${alias}`);
   }
 }
 
 function validateColumn(column) {
   if (!SAFE_COLUMN_RE.test(column)) {
-    throw new Error(`Invalid SQL column: ${column}`);
+    throw new DbError(`Invalid SQL column: ${column}`);
   }
 }
 
@@ -26,7 +27,7 @@ function validateOrderBy(clause) {
   const terms = clause.split(',').map((t) => t.trim());
   for (const term of terms) {
     if (!SAFE_ORDER_TERM_RE.test(term)) {
-      throw new Error(`Invalid ORDER BY term: ${term}`);
+      throw new DbError(`Invalid ORDER BY term: ${term}`);
     }
   }
 }
@@ -51,19 +52,26 @@ function validateSelectCols(cols) {
   const tokens = splitTopLevelCommas(cols);
   for (const token of tokens) {
     if (!SAFE_SELECT_TOKEN_RE.test(token)) {
-      throw new Error(`Invalid SELECT expression: ${token}`);
+      throw new DbError(`Invalid SELECT expression: ${token}`);
     }
   }
 }
 
 function validateEdgeKind(edgeKind) {
   if (!EVERY_EDGE_KIND.includes(edgeKind)) {
-    throw new Error(
+    throw new DbError(
       `Invalid edge kind: ${edgeKind} (expected one of ${EVERY_EDGE_KIND.join(', ')})`,
     );
   }
 }
 
+// ─── LIKE Escaping ──────────────────────────────────────────────────
+
+/** Escape LIKE wildcards in a literal string segment. */
+export function escapeLike(s) {
+  return s.replace(/[%_\\]/g, '\\$&');
+}
+
 // ─── Standalone Helpers ──────────────────────────────────────────────
 
 /**
@@ -163,11 +171,11 @@ export class NodeQuery {
     return this;
   }
 
-  /** WHERE n.file LIKE ? (no-op if falsy). */
+  /** WHERE n.file LIKE ? (no-op if falsy). Escapes LIKE wildcards in the value. */
   fileFilter(file) {
     if (!file) return this;
-    this.#conditions.push('n.file LIKE ?');
-    this.#params.push(`%${file}%`);
+    this.#conditions.push("n.file LIKE ? ESCAPE '\\'");
+    this.#params.push(`%${escapeLike(file)}%`);
     return this;
   }
 
@@ -187,11 +195,11 @@ export class NodeQuery {
     return this;
   }
 
-  /** WHERE n.name LIKE ? (no-op if falsy). */
+  /** WHERE n.name LIKE ? (no-op if falsy). Escapes LIKE wildcards in the value. */
   nameLike(pattern) {
     if (!pattern) return this;
-    this.#conditions.push('n.name LIKE ?');
-    this.#params.push(`%${pattern}%`);
+    this.#conditions.push("n.name LIKE ? ESCAPE '\\'");
+    this.#params.push(`%${escapeLike(pattern)}%`);
     return this;
   }
 

package/src/db/repository/base.js

@@ -0,0 +1,201 @@
+/**
+ * Abstract Repository base class.
+ *
+ * Defines the contract for all graph data access. Every method throws
+ * "not implemented" by default — concrete subclasses override what they support.
+ */
+export class Repository {
+  // ── Node lookups ────────────────────────────────────────────────────
+  /** @param {number} id @returns {object|undefined} */
+  findNodeById(_id) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} file @returns {object[]} */
+  findNodesByFile(_file) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} fileLike @returns {object[]} */
+  findFileNodes(_fileLike) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} namePattern @param {object} [opts] @returns {object[]} */
+  findNodesWithFanIn(_namePattern, _opts) {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {number} */
+  countNodes() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {number} */
+  countEdges() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {number} */
+  countFiles() {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} name @param {string} kind @param {string} file @param {number} line @returns {number|undefined} */
+  getNodeId(_name, _kind, _file, _line) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} name @param {string} file @param {number} line @returns {number|undefined} */
+  getFunctionNodeId(_name, _file, _line) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} file @returns {{ id: number, name: string, kind: string, line: number }[]} */
+  bulkNodeIdsByFile(_file) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} parentId @returns {object[]} */
+  findNodeChildren(_parentId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} scopeName @param {object} [opts] @returns {object[]} */
+  findNodesByScope(_scopeName, _opts) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} qualifiedName @param {object} [opts] @returns {object[]} */
+  findNodeByQualifiedName(_qualifiedName, _opts) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {object} [opts] @returns {object[]} */
+  listFunctionNodes(_opts) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {object} [opts] @returns {IterableIterator} */
+  iterateFunctionNodes(_opts) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {object} [opts] @returns {object[]} */
+  findNodesForTriage(_opts) {
+    throw new Error('not implemented');
+  }
+
+  // ── Edge queries ────────────────────────────────────────────────────
+  /** @param {number} nodeId @returns {object[]} */
+  findCallees(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {object[]} */
+  findCallers(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {object[]} */
+  findDistinctCallers(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {object[]} */
+  findAllOutgoingEdges(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {object[]} */
+  findAllIncomingEdges(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {string[]} */
+  findCalleeNames(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {string[]} */
+  findCallerNames(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {{ file: string, edge_kind: string }[]} */
+  findImportTargets(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {{ file: string, edge_kind: string }[]} */
+  findImportSources(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {object[]} */
+  findImportDependents(_nodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} file @returns {Set<number>} */
+  findCrossFileCallTargets(_file) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @param {string} file @returns {number} */
+  countCrossFileCallers(_nodeId, _file) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} classNodeId @returns {Set<number>} */
+  getClassHierarchy(_classNodeId) {
+    throw new Error('not implemented');
+  }
+
+  /** @param {string} file @returns {{ caller_name: string, callee_name: string }[]} */
+  findIntraFileCallEdges(_file) {
+    throw new Error('not implemented');
+  }
+
+  // ── Graph-read queries ──────────────────────────────────────────────
+  /** @returns {{ id: number, name: string, kind: string, file: string }[]} */
+  getCallableNodes() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {{ source_id: number, target_id: number, confidence: number|null }[]} */
+  getCallEdges() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {{ id: number, name: string, file: string }[]} */
+  getFileNodesAll() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {{ source_id: number, target_id: number }[]} */
+  getImportEdges() {
+    throw new Error('not implemented');
+  }
+
+  // ── Optional table checks (default: false/undefined) ────────────────
+  /** @returns {boolean} */
+  hasCfgTables() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {boolean} */
+  hasEmbeddings() {
+    throw new Error('not implemented');
+  }
+
+  /** @returns {boolean} */
+  hasDataflowTable() {
+    throw new Error('not implemented');
+  }
+
+  /** @param {number} nodeId @returns {object|undefined} */
+  getComplexityForNode(_nodeId) {
+    throw new Error('not implemented');
+  }
+}

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

@@ -1,3 +1,4 @@
+import { CORE_SYMBOL_KINDS } from '../../shared/kinds.js';
 import { cachedStmt } from './cached-stmt.js';
 
 // ─── Statement caches (one prepared statement per db instance) ────────────
@@ -6,8 +7,10 @@ const _getCallEdgesStmt = new WeakMap();
 const _getFileNodesAllStmt = new WeakMap();
 const _getImportEdgesStmt = new WeakMap();
 
+const CALLABLE_KINDS_SQL = CORE_SYMBOL_KINDS.map((k) => `'${k}'`).join(',');
+
 /**
- * Get callable nodes (function/method/class) for community detection.
+ * Get callable nodes (all core symbol kinds) for graph construction.
  * @param {object} db
  * @returns {{ id: number, name: string, kind: string, file: string }[]}
  */
@@ -15,20 +18,20 @@ export function getCallableNodes(db) {
   return cachedStmt(
     _getCallableNodesStmt,
     db,
-    "SELECT id, name, kind, file FROM nodes WHERE kind IN ('function','method','class')",
+    `SELECT id, name, kind, file FROM nodes WHERE kind IN (${CALLABLE_KINDS_SQL})`,
   ).all();
 }
 
 /**
  * Get all 'calls' edges.
  * @param {object} db
- * @returns {{ source_id: number, target_id: number }[]}
+ * @returns {{ source_id: number, target_id: number, confidence: number|null }[]}
  */
 export function getCallEdges(db) {
   return cachedStmt(
     _getCallEdgesStmt,
     db,
-    "SELECT source_id, target_id FROM edges WHERE kind = 'calls'",
+    "SELECT source_id, target_id, confidence FROM edges WHERE kind = 'calls'",
   ).all();
 }