@optave/codegraph 3.1.0 → 3.1.1

package/src/db/connection.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { warn } from '../logger.js';
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireAdvisoryLock(dbPath) {
+  const lockPath = `${dbPath}.lock`;
+  try {
+    if (fs.existsSync(lockPath)) {
+      const content = fs.readFileSync(lockPath, 'utf-8').trim();
+      const pid = Number(content);
+      if (pid && pid !== process.pid && isProcessAlive(pid)) {
+        warn(`Another process (PID ${pid}) may be using this database. Proceeding with caution.`);
+      }
+    }
+  } catch {
+    /* ignore read errors */
+  }
+  try {
+    fs.writeFileSync(lockPath, String(process.pid), 'utf-8');
+  } catch {
+    /* best-effort */
+  }
+}
+
+function releaseAdvisoryLock(lockPath) {
+  try {
+    const content = fs.readFileSync(lockPath, 'utf-8').trim();
+    if (Number(content) === process.pid) {
+      fs.unlinkSync(lockPath);
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+export function openDb(dbPath) {
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  acquireAdvisoryLock(dbPath);
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('busy_timeout = 5000');
+  db.__lockPath = `${dbPath}.lock`;
+  return db;
+}
+
+export function closeDb(db) {
+  db.close();
+  if (db.__lockPath) releaseAdvisoryLock(db.__lockPath);
+}
+
+export function findDbPath(customPath) {
+  if (customPath) return path.resolve(customPath);
+  let dir = process.cwd();
+  while (true) {
+    const candidate = path.join(dir, '.codegraph', 'graph.db');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.join(process.cwd(), '.codegraph', 'graph.db');
+}
+
+/**
+ * Open a database in readonly mode, with a user-friendly error if the DB doesn't exist.
+ */
+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.`,
+    );
+    process.exit(1);
+  }
+  return new Database(dbPath, { readonly: true });
+}

package/src/db/migrations.js

@@ -0,0 +1,312 @@
+import { debug } from '../logger.js';
+
+// ─── Schema Migrations ─────────────────────────────────────────────────
+export const MIGRATIONS = [
+  {
+    version: 1,
+    up: `
+      CREATE TABLE IF NOT EXISTS nodes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        file TEXT NOT NULL,
+        line INTEGER,
+        end_line INTEGER,
+        UNIQUE(name, kind, file, line)
+      );
+      CREATE TABLE IF NOT EXISTS edges (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_id INTEGER NOT NULL,
+        target_id INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        confidence REAL DEFAULT 1.0,
+        dynamic INTEGER DEFAULT 0,
+        FOREIGN KEY(source_id) REFERENCES nodes(id),
+        FOREIGN KEY(target_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
+      CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file);
+      CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+      CREATE INDEX IF NOT EXISTS idx_edges_kind ON edges(kind);
+      CREATE TABLE IF NOT EXISTS node_metrics (
+        node_id INTEGER PRIMARY KEY,
+        line_count INTEGER,
+        symbol_count INTEGER,
+        import_count INTEGER,
+        export_count INTEGER,
+        fan_in INTEGER,
+        fan_out INTEGER,
+        cohesion REAL,
+        file_count INTEGER,
+        FOREIGN KEY(node_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_node_metrics_node ON node_metrics(node_id);
+    `,
+  },
+  {
+    version: 2,
+    up: `
+      CREATE INDEX IF NOT EXISTS idx_nodes_name_kind_file ON nodes(name, kind, file);
+      CREATE INDEX IF NOT EXISTS idx_nodes_file_kind ON nodes(file, kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_source_kind ON edges(source_id, kind);
+      CREATE INDEX IF NOT EXISTS idx_edges_target_kind ON edges(target_id, kind);
+    `,
+  },
+  {
+    version: 3,
+    up: `
+      CREATE TABLE IF NOT EXISTS file_hashes (
+        file TEXT PRIMARY KEY,
+        hash TEXT NOT NULL,
+        mtime INTEGER NOT NULL
+      );
+    `,
+  },
+  {
+    version: 4,
+    up: `ALTER TABLE file_hashes ADD COLUMN size INTEGER DEFAULT 0;`,
+  },
+  {
+    version: 5,
+    up: `
+      CREATE TABLE IF NOT EXISTS co_changes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        file_a TEXT NOT NULL,
+        file_b TEXT NOT NULL,
+        commit_count INTEGER NOT NULL,
+        jaccard REAL NOT NULL,
+        last_commit_epoch INTEGER,
+        UNIQUE(file_a, file_b)
+      );
+      CREATE INDEX IF NOT EXISTS idx_co_changes_file_a ON co_changes(file_a);
+      CREATE INDEX IF NOT EXISTS idx_co_changes_file_b ON co_changes(file_b);
+      CREATE INDEX IF NOT EXISTS idx_co_changes_jaccard ON co_changes(jaccard DESC);
+      CREATE TABLE IF NOT EXISTS co_change_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `,
+  },
+  {
+    version: 6,
+    up: `
+      CREATE TABLE IF NOT EXISTS file_commit_counts (
+        file TEXT PRIMARY KEY,
+        commit_count INTEGER NOT NULL DEFAULT 0
+      );
+    `,
+  },
+  {
+    version: 7,
+    up: `
+      CREATE TABLE IF NOT EXISTS build_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `,
+  },
+  {
+    version: 8,
+    up: `
+      CREATE TABLE IF NOT EXISTS function_complexity (
+        node_id INTEGER PRIMARY KEY,
+        cognitive INTEGER NOT NULL,
+        cyclomatic INTEGER NOT NULL,
+        max_nesting INTEGER NOT NULL,
+        FOREIGN KEY(node_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_fc_cognitive ON function_complexity(cognitive DESC);
+      CREATE INDEX IF NOT EXISTS idx_fc_cyclomatic ON function_complexity(cyclomatic DESC);
+    `,
+  },
+  {
+    version: 9,
+    up: `
+      ALTER TABLE function_complexity ADD COLUMN loc INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN sloc INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN comment_lines INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_n1 INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_n2 INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_big_n1 INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_big_n2 INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_vocabulary INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_length INTEGER DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_volume REAL DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_difficulty REAL DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_effort REAL DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN halstead_bugs REAL DEFAULT 0;
+      ALTER TABLE function_complexity ADD COLUMN maintainability_index REAL DEFAULT 0;
+      CREATE INDEX IF NOT EXISTS idx_fc_mi ON function_complexity(maintainability_index ASC);
+    `,
+  },
+  {
+    version: 10,
+    up: `
+      CREATE TABLE IF NOT EXISTS dataflow (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_id INTEGER NOT NULL,
+        target_id INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        param_index INTEGER,
+        expression TEXT,
+        line INTEGER,
+        confidence REAL DEFAULT 1.0,
+        FOREIGN KEY(source_id) REFERENCES nodes(id),
+        FOREIGN KEY(target_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_dataflow_source ON dataflow(source_id);
+      CREATE INDEX IF NOT EXISTS idx_dataflow_target ON dataflow(target_id);
+      CREATE INDEX IF NOT EXISTS idx_dataflow_kind ON dataflow(kind);
+      CREATE INDEX IF NOT EXISTS idx_dataflow_source_kind ON dataflow(source_id, kind);
+    `,
+  },
+  {
+    version: 11,
+    up: `
+      ALTER TABLE nodes ADD COLUMN parent_id INTEGER REFERENCES nodes(id);
+      CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id);
+      CREATE INDEX IF NOT EXISTS idx_nodes_kind_parent ON nodes(kind, parent_id);
+    `,
+  },
+  {
+    version: 12,
+    up: `
+      CREATE TABLE IF NOT EXISTS cfg_blocks (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        function_node_id INTEGER NOT NULL,
+        block_index INTEGER NOT NULL,
+        block_type TEXT NOT NULL,
+        start_line INTEGER,
+        end_line INTEGER,
+        label TEXT,
+        FOREIGN KEY(function_node_id) REFERENCES nodes(id),
+        UNIQUE(function_node_id, block_index)
+      );
+      CREATE INDEX IF NOT EXISTS idx_cfg_blocks_fn ON cfg_blocks(function_node_id);
+
+      CREATE TABLE IF NOT EXISTS cfg_edges (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        function_node_id INTEGER NOT NULL,
+        source_block_id INTEGER NOT NULL,
+        target_block_id INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        FOREIGN KEY(function_node_id) REFERENCES nodes(id),
+        FOREIGN KEY(source_block_id) REFERENCES cfg_blocks(id),
+        FOREIGN KEY(target_block_id) REFERENCES cfg_blocks(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_cfg_edges_fn ON cfg_edges(function_node_id);
+      CREATE INDEX IF NOT EXISTS idx_cfg_edges_src ON cfg_edges(source_block_id);
+      CREATE INDEX IF NOT EXISTS idx_cfg_edges_tgt ON cfg_edges(target_block_id);
+    `,
+  },
+  {
+    version: 13,
+    up: `
+      CREATE TABLE IF NOT EXISTS ast_nodes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        file TEXT NOT NULL,
+        line INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        name TEXT NOT NULL,
+        text TEXT,
+        receiver TEXT,
+        parent_node_id INTEGER,
+        FOREIGN KEY(parent_node_id) REFERENCES nodes(id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_ast_kind ON ast_nodes(kind);
+      CREATE INDEX IF NOT EXISTS idx_ast_name ON ast_nodes(name);
+      CREATE INDEX IF NOT EXISTS idx_ast_file ON ast_nodes(file);
+      CREATE INDEX IF NOT EXISTS idx_ast_parent ON ast_nodes(parent_node_id);
+      CREATE INDEX IF NOT EXISTS idx_ast_kind_name ON ast_nodes(kind, name);
+    `,
+  },
+  {
+    version: 14,
+    up: `
+      ALTER TABLE nodes ADD COLUMN exported INTEGER DEFAULT 0;
+      CREATE INDEX IF NOT EXISTS idx_nodes_exported ON nodes(exported);
+    `,
+  },
+];
+
+export function getBuildMeta(db, key) {
+  try {
+    const row = db.prepare('SELECT value FROM build_meta WHERE key = ?').get(key);
+    return row ? row.value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function setBuildMeta(db, entries) {
+  const upsert = db.prepare('INSERT OR REPLACE INTO build_meta (key, value) VALUES (?, ?)');
+  const tx = db.transaction(() => {
+    for (const [key, value] of Object.entries(entries)) {
+      upsert.run(key, String(value));
+    }
+  });
+  tx();
+}
+
+export function initSchema(db) {
+  db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL DEFAULT 0)`);
+
+  const row = db.prepare('SELECT version FROM schema_version').get();
+  let currentVersion = row ? row.version : 0;
+
+  if (!row) {
+    db.prepare('INSERT INTO schema_version (version) VALUES (0)').run();
+  }
+
+  for (const migration of MIGRATIONS) {
+    if (migration.version > currentVersion) {
+      debug(`Running migration v${migration.version}`);
+      db.exec(migration.up);
+      db.prepare('UPDATE schema_version SET version = ?').run(migration.version);
+      currentVersion = migration.version;
+    }
+  }
+
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE edges ADD COLUMN dynamic INTEGER DEFAULT 0');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN role TEXT');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_role ON nodes(role)');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('ALTER TABLE nodes ADD COLUMN parent_id INTEGER REFERENCES nodes(id)');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_parent ON nodes(parent_id)');
+  } catch {
+    /* already exists */
+  }
+  try {
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_kind_parent ON nodes(kind, parent_id)');
+  } catch {
+    /* already exists */
+  }
+}

package/src/db/query-builder.js

@@ -0,0 +1,280 @@
+import { EVERY_EDGE_KIND } from '../kinds.js';
+
+// ─── Validation Helpers ─────────────────────────────────────────────
+
+const SAFE_ALIAS_RE = /^[a-z_][a-z0-9_]*$/i;
+const SAFE_COLUMN_RE = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/i;
+// Matches: column, table.column, column ASC, table.column DESC
+const SAFE_ORDER_TERM_RE = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?\s*(?:asc|desc)?$/i;
+// Matches safe SELECT expressions: column refs, *, table.*, COALESCE(...) AS alias
+const SAFE_SELECT_TOKEN_RE =
+  /^(?:[a-z_][a-z0-9_]*(?:\.[a-z_*][a-z0-9_]*)?\s*(?:as\s+[a-z_][a-z0-9_]*)?|[a-z_]+\([^)]*\)\s*(?:as\s+[a-z_][a-z0-9_]*)?)$/i;
+
+function validateAlias(alias) {
+  if (!SAFE_ALIAS_RE.test(alias)) {
+    throw new Error(`Invalid SQL alias: ${alias}`);
+  }
+}
+
+function validateColumn(column) {
+  if (!SAFE_COLUMN_RE.test(column)) {
+    throw new Error(`Invalid SQL column: ${column}`);
+  }
+}
+
+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}`);
+    }
+  }
+}
+
+function splitTopLevelCommas(str) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < str.length; i++) {
+    if (str[i] === '(') depth++;
+    else if (str[i] === ')') depth--;
+    else if (str[i] === ',' && depth === 0) {
+      parts.push(str.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  parts.push(str.slice(start).trim());
+  return parts;
+}
+
+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}`);
+    }
+  }
+}
+
+function validateEdgeKind(edgeKind) {
+  if (!EVERY_EDGE_KIND.includes(edgeKind)) {
+    throw new Error(
+      `Invalid edge kind: ${edgeKind} (expected one of ${EVERY_EDGE_KIND.join(', ')})`,
+    );
+  }
+}
+
+// ─── Standalone Helpers ──────────────────────────────────────────────
+
+/**
+ * Return a SQL AND clause that excludes test/spec/stories files.
+ * Returns empty string when disabled.
+ * @param {string} [column='n.file'] - Column to filter on
+ * @param {boolean} [enabled=true] - No-op when false
+ */
+export function testFilterSQL(column = 'n.file', enabled = true) {
+  if (!enabled) return '';
+  validateColumn(column);
+  return `AND ${column} NOT LIKE '%.test.%'
+       AND ${column} NOT LIKE '%.spec.%'
+       AND ${column} NOT LIKE '%__test__%'
+       AND ${column} NOT LIKE '%__tests__%'
+       AND ${column} NOT LIKE '%.stories.%'`;
+}
+
+/**
+ * Build IN (?, ?, ?) placeholders and params array for a kind filter.
+ * @param {string[]} kinds
+ * @returns {{ placeholders: string, params: string[] }}
+ */
+export function kindInClause(kinds) {
+  return {
+    placeholders: kinds.map(() => '?').join(', '),
+    params: [...kinds],
+  };
+}
+
+/**
+ * Return a LEFT JOIN subquery for fan-in (incoming edge count).
+ * @param {string} [edgeKind='calls'] - Edge kind to count
+ * @param {string} [alias='fi'] - Subquery alias
+ */
+export function fanInJoinSQL(edgeKind = 'calls', alias = 'fi') {
+  validateEdgeKind(edgeKind);
+  validateAlias(alias);
+  return `LEFT JOIN (
+    SELECT target_id, COUNT(*) AS cnt FROM edges WHERE kind = '${edgeKind}' GROUP BY target_id
+  ) ${alias} ON ${alias}.target_id = n.id`;
+}
+
+/**
+ * Return a LEFT JOIN subquery for fan-out (outgoing edge count).
+ * @param {string} [edgeKind='calls'] - Edge kind to count
+ * @param {string} [alias='fo'] - Subquery alias
+ */
+export function fanOutJoinSQL(edgeKind = 'calls', alias = 'fo') {
+  validateEdgeKind(edgeKind);
+  validateAlias(alias);
+  return `LEFT JOIN (
+    SELECT source_id, COUNT(*) AS cnt FROM edges WHERE kind = '${edgeKind}' GROUP BY source_id
+  ) ${alias} ON ${alias}.source_id = n.id`;
+}
+
+// ─── NodeQuery Fluent Builder ────────────────────────────────────────
+
+/**
+ * Fluent builder for the common `SELECT ... FROM nodes n WHERE ...` pattern.
+ * Not an ORM — complex queries (BFS, correlated subqueries) stay as raw SQL.
+ */
+export class NodeQuery {
+  #selectCols = 'n.*';
+  #joins = [];
+  #conditions = [];
+  #params = [];
+  #orderByClause = '';
+  #limitValue = null;
+
+  /** Set SELECT columns (default: `n.*`). */
+  select(cols) {
+    validateSelectCols(cols);
+    this.#selectCols = cols;
+    return this;
+  }
+
+  /** WHERE n.kind IN (?, ?, ...) */
+  kinds(kindArray) {
+    if (!kindArray || kindArray.length === 0) return this;
+    const { placeholders, params } = kindInClause(kindArray);
+    this.#conditions.push(`n.kind IN (${placeholders})`);
+    this.#params.push(...params);
+    return this;
+  }
+
+  /** Add 5 NOT LIKE conditions to exclude test files. No-op when enabled is falsy. */
+  excludeTests(enabled) {
+    if (!enabled) return this;
+    this.#conditions.push(
+      `n.file NOT LIKE '%.test.%'`,
+      `n.file NOT LIKE '%.spec.%'`,
+      `n.file NOT LIKE '%__test__%'`,
+      `n.file NOT LIKE '%__tests__%'`,
+      `n.file NOT LIKE '%.stories.%'`,
+    );
+    return this;
+  }
+
+  /** WHERE n.file LIKE ? (no-op if falsy). */
+  fileFilter(file) {
+    if (!file) return this;
+    this.#conditions.push('n.file LIKE ?');
+    this.#params.push(`%${file}%`);
+    return this;
+  }
+
+  /** WHERE n.kind = ? (no-op if falsy). */
+  kindFilter(kind) {
+    if (!kind) return this;
+    this.#conditions.push('n.kind = ?');
+    this.#params.push(kind);
+    return this;
+  }
+
+  /** WHERE n.role = ? (no-op if falsy). */
+  roleFilter(role) {
+    if (!role) return this;
+    this.#conditions.push('n.role = ?');
+    this.#params.push(role);
+    return this;
+  }
+
+  /** WHERE n.name LIKE ? (no-op if falsy). */
+  nameLike(pattern) {
+    if (!pattern) return this;
+    this.#conditions.push('n.name LIKE ?');
+    this.#params.push(`%${pattern}%`);
+    return this;
+  }
+
+  /** Raw WHERE condition escape hatch. */
+  where(sql, ...params) {
+    this.#conditions.push(sql);
+    this.#params.push(...params);
+    return this;
+  }
+
+  /** Add fan-in LEFT JOIN subquery. */
+  withFanIn(edgeKind = 'calls') {
+    return this._join(fanInJoinSQL(edgeKind));
+  }
+
+  /** Add fan-out LEFT JOIN subquery. */
+  withFanOut(edgeKind = 'calls') {
+    return this._join(fanOutJoinSQL(edgeKind));
+  }
+
+  /** LEFT JOIN function_complexity. */
+  withComplexity() {
+    return this._join('LEFT JOIN function_complexity fc ON fc.node_id = n.id');
+  }
+
+  /** LEFT JOIN file_commit_counts. */
+  withChurn() {
+    return this._join('LEFT JOIN file_commit_counts fcc ON n.file = fcc.file');
+  }
+
+  /** @private Raw JOIN — internal use only; external callers should use withFanIn/withFanOut/withComplexity/withChurn. */
+  _join(sql) {
+    this.#joins.push(sql);
+    return this;
+  }
+
+  /** ORDER BY clause. */
+  orderBy(clause) {
+    validateOrderBy(clause);
+    this.#orderByClause = clause;
+    return this;
+  }
+
+  /** LIMIT ?. */
+  limit(n) {
+    if (n == null) return this;
+    this.#limitValue = n;
+    return this;
+  }
+
+  /** Build the SQL and params without executing. */
+  build() {
+    const joins = this.#joins.length > 0 ? `\n       ${this.#joins.join('\n       ')}` : '';
+    const where =
+      this.#conditions.length > 0 ? `\n       WHERE ${this.#conditions.join(' AND ')}` : '';
+    const orderBy = this.#orderByClause ? `\n       ORDER BY ${this.#orderByClause}` : '';
+
+    let limitClause = '';
+    const params = [...this.#params];
+    if (this.#limitValue != null) {
+      limitClause = '\n       LIMIT ?';
+      params.push(this.#limitValue);
+    }
+
+    const sql = `SELECT ${this.#selectCols}\n       FROM nodes n${joins}${where}${orderBy}${limitClause}`;
+    return { sql, params };
+  }
+
+  /** Execute and return all rows. */
+  all(db) {
+    const { sql, params } = this.build();
+    return db.prepare(sql).all(...params);
+  }
+
+  /** Execute and return first row. */
+  get(db) {
+    const { sql, params } = this.build();
+    return db.prepare(sql).get(...params);
+  }
+
+  /** Execute and return an iterator. */
+  iterate(db) {
+    const { sql, params } = this.build();
+    return db.prepare(sql).iterate(...params);
+  }
+}