@optave/codegraph 2.5.1 → 2.6.0

package/src/queries.js

@@ -1,11 +1,14 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { evaluateBoundaries } from './boundaries.js';
 import { coChangeForFiles } from './cochange.js';
+import { loadConfig } from './config.js';
 import { findCycles } from './cycles.js';
 import { findDbPath, openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
-import { paginateResult } from './paginate.js';
+import { ownersForFiles } from './owners.js';
+import { paginateResult, printNdjson } from './paginate.js';
 import { LANGUAGE_REGISTRY } from './parser.js';
 
 /**
@@ -391,7 +394,8 @@ export function fileDepsData(file, customDbPath, opts = {}) {
   });
 
   db.close();
-  return { file, results };
+  const base = { file, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function fnDepsData(name, customDbPath, opts = {}) {
@@ -511,7 +515,8 @@ export function fnDepsData(name, customDbPath, opts = {}) {
   });
 
   db.close();
-  return { name, results };
+  const base = { name, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function fnImpactData(name, customDbPath, opts = {}) {
@@ -525,7 +530,7 @@ export function fnImpactData(name, customDbPath, opts = {}) {
     return { name, results: [] };
   }
 
-  const results = nodes.slice(0, 3).map((node) => {
+  const results = nodes.map((node) => {
     const visited = new Set([node.id]);
     const levels = {};
     let frontier = [node.id];
@@ -564,7 +569,8 @@ export function fnImpactData(name, customDbPath, opts = {}) {
   });
 
   db.close();
-  return { name, results };
+  const base = { name, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function pathData(from, to, customDbPath, opts = {}) {
@@ -998,20 +1004,60 @@ export function diffImpactData(customDbPath, opts = {}) {
     /* co_changes table doesn't exist — skip silently */
   }
 
+  // Look up CODEOWNERS for changed + affected files
+  let ownership = null;
+  try {
+    const allFilePaths = [...new Set([...changedRanges.keys(), ...affectedFiles])];
+    const ownerResult = ownersForFiles(allFilePaths, repoRoot);
+    if (ownerResult.affectedOwners.length > 0) {
+      ownership = {
+        owners: Object.fromEntries(ownerResult.owners),
+        affectedOwners: ownerResult.affectedOwners,
+        suggestedReviewers: ownerResult.suggestedReviewers,
+      };
+    }
+  } catch {
+    /* CODEOWNERS missing or unreadable — skip silently */
+  }
+
+  // Check boundary violations scoped to changed files
+  let boundaryViolations = [];
+  let boundaryViolationCount = 0;
+  try {
+    const config = loadConfig(repoRoot);
+    const boundaryConfig = config.manifesto?.boundaries;
+    if (boundaryConfig) {
+      const result = evaluateBoundaries(db, boundaryConfig, {
+        scopeFiles: [...changedRanges.keys()],
+        noTests,
+      });
+      boundaryViolations = result.violations;
+      boundaryViolationCount = result.violationCount;
+    }
+  } catch {
+    /* boundary check failed — skip silently */
+  }
+
   db.close();
-  return {
+  const base = {
     changedFiles: changedRanges.size,
     newFiles: [...newFiles],
     affectedFunctions: functionResults,
     affectedFiles: [...affectedFiles],
     historicallyCoupled,
+    ownership,
+    boundaryViolations,
+    boundaryViolationCount,
     summary: {
       functionsChanged: affectedFunctions.length,
       callersAffected: allAffected.size,
       filesAffected: affectedFiles.size,
       historicallyCoupledCount: historicallyCoupled.length,
+      ownersAffected: ownership ? ownership.affectedOwners.length : 0,
+      boundaryViolationCount,
     },
   };
+  return paginateResult(base, 'affectedFunctions', { limit: opts.limit, offset: opts.offset });
 }
 
 export function diffImpactMermaid(customDbPath, opts = {}) {
@@ -1159,6 +1205,131 @@ export function listFunctionsData(customDbPath, opts = {}) {
   return paginateResult(base, 'functions', { limit: opts.limit, offset: opts.offset });
 }
 
+/**
+ * Generator: stream functions one-by-one using .iterate() for memory efficiency.
+ * @param {string} [customDbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.file]
+ * @param {string} [opts.pattern]
+ * @yields {{ name: string, kind: string, file: string, line: number, role: string|null }}
+ */
+export function* iterListFunctions(customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const kinds = ['function', 'method', 'class'];
+    const placeholders = kinds.map(() => '?').join(', ');
+
+    const conditions = [`kind IN (${placeholders})`];
+    const params = [...kinds];
+
+    if (opts.file) {
+      conditions.push('file LIKE ?');
+      params.push(`%${opts.file}%`);
+    }
+    if (opts.pattern) {
+      conditions.push('name LIKE ?');
+      params.push(`%${opts.pattern}%`);
+    }
+
+    const stmt = db.prepare(
+      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY file, line`,
+    );
+    for (const row of stmt.iterate(...params)) {
+      if (noTests && isTestFile(row.file)) continue;
+      yield { name: row.name, kind: row.kind, file: row.file, line: row.line, role: row.role };
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Generator: stream role-classified symbols one-by-one.
+ * @param {string} [customDbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @param {string} [opts.role]
+ * @param {string} [opts.file]
+ * @yields {{ name: string, kind: string, file: string, line: number, role: string }}
+ */
+export function* iterRoles(customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const conditions = ['role IS NOT NULL'];
+    const params = [];
+
+    if (opts.role) {
+      conditions.push('role = ?');
+      params.push(opts.role);
+    }
+    if (opts.file) {
+      conditions.push('file LIKE ?');
+      params.push(`%${opts.file}%`);
+    }
+
+    const stmt = db.prepare(
+      `SELECT name, kind, file, line, role FROM nodes WHERE ${conditions.join(' AND ')} ORDER BY role, file, line`,
+    );
+    for (const row of stmt.iterate(...params)) {
+      if (noTests && isTestFile(row.file)) continue;
+      yield { name: row.name, kind: row.kind, file: row.file, line: row.line, role: row.role };
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Generator: stream symbol lookup results one-by-one.
+ * @param {string} target - Symbol name to search for (partial match)
+ * @param {string} [customDbPath]
+ * @param {object} [opts]
+ * @param {boolean} [opts.noTests]
+ * @yields {{ name: string, kind: string, file: string, line: number, role: string|null, exported: boolean, uses: object[] }}
+ */
+export function* iterWhere(target, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const placeholders = ALL_SYMBOL_KINDS.map(() => '?').join(', ');
+    const stmt = db.prepare(
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN (${placeholders}) ORDER BY file, line`,
+    );
+    const crossFileCallersStmt = 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 != ?`,
+    );
+    const usesStmt = db.prepare(
+      `SELECT n.name, n.file, n.line FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id = ? AND e.kind = 'calls'`,
+    );
+    for (const node of stmt.iterate(`%${target}%`, ...ALL_SYMBOL_KINDS)) {
+      if (noTests && isTestFile(node.file)) continue;
+
+      const crossFileCallers = crossFileCallersStmt.get(node.id, node.file);
+      const exported = crossFileCallers.cnt > 0;
+
+      let uses = usesStmt.all(node.id);
+      if (noTests) uses = uses.filter((u) => !isTestFile(u.file));
+
+      yield {
+        name: node.name,
+        kind: node.kind,
+        file: node.file,
+        line: node.line,
+        role: node.role || null,
+        exported,
+        uses: uses.map((u) => ({ name: u.name, file: u.file, line: u.line })),
+      };
+    }
+  } finally {
+    db.close();
+  }
+}
+
 export function statsData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
   const noTests = opts.noTests || false;
@@ -1553,8 +1724,7 @@ export function queryName(name, customDbPath, opts = {}) {
     offset: opts.offset,
   });
   if (opts.ndjson) {
-    if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
-    for (const r of data.results) console.log(JSON.stringify(r));
+    printNdjson(data, 'results');
     return;
   }
   if (opts.json) {
@@ -1586,7 +1756,11 @@ export function queryName(name, customDbPath, opts = {}) {
 }
 
 export function impactAnalysis(file, customDbPath, opts = {}) {
-  const data = impactAnalysisData(file, customDbPath, { noTests: opts.noTests });
+  const data = impactAnalysisData(file, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'sources');
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1645,7 +1819,11 @@ export function moduleMap(customDbPath, limit = 20, opts = {}) {
 }
 
 export function fileDeps(file, customDbPath, opts = {}) {
-  const data = fileDepsData(file, customDbPath, { noTests: opts.noTests });
+  const data = fileDepsData(file, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'results');
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1676,6 +1854,10 @@ export function fileDeps(file, customDbPath, opts = {}) {
 
 export function fnDeps(name, customDbPath, opts = {}) {
   const data = fnDepsData(name, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'results');
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1838,14 +2020,13 @@ export function contextData(name, customDbPath, opts = {}) {
   const dbPath = findDbPath(customDbPath);
   const repoRoot = path.resolve(path.dirname(dbPath), '..');
 
-  let nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
+  const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
   if (nodes.length === 0) {
     db.close();
     return { name, results: [] };
   }
 
-  // Limit to first 5 results
-  nodes = nodes.slice(0, 5);
+  // No hardcoded slice — pagination handles bounding via limit/offset
 
   // File-lines cache to avoid re-reading the same file
   const fileCache = new Map();
@@ -2050,11 +2231,16 @@ export function contextData(name, customDbPath, opts = {}) {
   });
 
   db.close();
-  return { name, results };
+  const base = { name, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function context(name, customDbPath, opts = {}) {
   const data = contextData(name, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'results');
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -2410,11 +2596,16 @@ export function explainData(target, customDbPath, opts = {}) {
   }
 
   db.close();
-  return { target, kind, results };
+  const base = { target, kind, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function explain(target, customDbPath, opts = {}) {
   const data = explainData(target, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'results');
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -2645,8 +2836,7 @@ export function whereData(target, customDbPath, opts = {}) {
 export function where(target, customDbPath, opts = {}) {
   const data = whereData(target, customDbPath, opts);
   if (opts.ndjson) {
-    if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
-    for (const r of data.results) console.log(JSON.stringify(r));
+    printNdjson(data, 'results');
     return;
   }
   if (opts.json) {
@@ -2737,8 +2927,7 @@ export function rolesData(customDbPath, opts = {}) {
 export function roles(customDbPath, opts = {}) {
   const data = rolesData(customDbPath, opts);
   if (opts.ndjson) {
-    if (data._pagination) console.log(JSON.stringify({ _meta: data._pagination }));
-    for (const s of data.symbols) console.log(JSON.stringify(s));
+    printNdjson(data, 'symbols');
     return;
   }
   if (opts.json) {
@@ -2779,6 +2968,10 @@ export function roles(customDbPath, opts = {}) {
 
 export function fnImpact(name, customDbPath, opts = {}) {
   const data = fnImpactData(name, customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'results');
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -2811,6 +3004,10 @@ export function diffImpact(customDbPath, opts = {}) {
     return;
   }
   const data = diffImpactData(customDbPath, opts);
+  if (opts.ndjson) {
+    printNdjson(data, 'affectedFunctions');
+    return;
+  }
   if (opts.json || opts.format === 'json') {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -2845,11 +3042,28 @@ export function diffImpact(customDbPath, opts = {}) {
       );
     }
   }
+  if (data.ownership) {
+    console.log(`\n  Affected owners: ${data.ownership.affectedOwners.join(', ')}`);
+    console.log(`  Suggested reviewers: ${data.ownership.suggestedReviewers.join(', ')}`);
+  }
+  if (data.boundaryViolations && data.boundaryViolations.length > 0) {
+    console.log(`\n  Boundary violations (${data.boundaryViolationCount}):\n`);
+    for (const v of data.boundaryViolations) {
+      console.log(`    [${v.name}] ${v.file} -> ${v.targetFile}`);
+      if (v.message) console.log(`      ${v.message}`);
+    }
+  }
   if (data.summary) {
     let summaryLine = `\n  Summary: ${data.summary.functionsChanged} functions changed -> ${data.summary.callersAffected} callers affected across ${data.summary.filesAffected} files`;
     if (data.summary.historicallyCoupledCount > 0) {
       summaryLine += `, ${data.summary.historicallyCoupledCount} historically coupled`;
     }
+    if (data.summary.ownersAffected > 0) {
+      summaryLine += `, ${data.summary.ownersAffected} owners affected`;
+    }
+    if (data.summary.boundaryViolationCount > 0) {
+      summaryLine += `, ${data.summary.boundaryViolationCount} boundary violations`;
+    }
     console.log(`${summaryLine}\n`);
   }
 }

package/src/snapshot.js

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { findDbPath } from './db.js';
+import { debug } from './logger.js';
+
+const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Validate a snapshot name (alphanumeric, hyphens, underscores only).
+ * Throws on invalid input.
+ */
+export function validateSnapshotName(name) {
+  if (!name || !NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid snapshot name "${name}". Use only letters, digits, hyphens, and underscores.`,
+    );
+  }
+}
+
+/**
+ * Return the snapshots directory for a given DB path.
+ */
+export function snapshotsDir(dbPath) {
+  return path.join(path.dirname(dbPath), 'snapshots');
+}
+
+/**
+ * Save a snapshot of the current graph database.
+ * Uses VACUUM INTO for an atomic, WAL-free copy.
+ *
+ * @param {string} name - Snapshot name
+ * @param {object} [options]
+ * @param {string} [options.dbPath] - Explicit path to graph.db
+ * @param {boolean} [options.force] - Overwrite existing snapshot
+ * @returns {{ name: string, path: string, size: number }}
+ */
+export function snapshotSave(name, options = {}) {
+  validateSnapshotName(name);
+  const dbPath = options.dbPath || findDbPath();
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}`);
+  }
+
+  const dir = snapshotsDir(dbPath);
+  const dest = path.join(dir, `${name}.db`);
+
+  if (fs.existsSync(dest)) {
+    if (!options.force) {
+      throw new Error(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+    }
+    fs.unlinkSync(dest);
+    debug(`Deleted existing snapshot: ${dest}`);
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+  } finally {
+    db.close();
+  }
+
+  const stat = fs.statSync(dest);
+  debug(`Snapshot saved: ${dest} (${stat.size} bytes)`);
+  return { name, path: dest, size: stat.size };
+}
+
+/**
+ * Restore a snapshot over the current graph database.
+ * Removes WAL/SHM sidecar files before overwriting.
+ *
+ * @param {string} name - Snapshot name
+ * @param {object} [options]
+ * @param {string} [options.dbPath] - Explicit path to graph.db
+ */
+export function snapshotRestore(name, options = {}) {
+  validateSnapshotName(name);
+  const dbPath = options.dbPath || findDbPath();
+  const dir = snapshotsDir(dbPath);
+  const src = path.join(dir, `${name}.db`);
+
+  if (!fs.existsSync(src)) {
+    throw new Error(`Snapshot "${name}" not found at ${src}`);
+  }
+
+  // Remove WAL/SHM sidecar files for a clean restore
+  for (const suffix of ['-wal', '-shm']) {
+    const sidecar = dbPath + suffix;
+    if (fs.existsSync(sidecar)) {
+      fs.unlinkSync(sidecar);
+      debug(`Removed sidecar: ${sidecar}`);
+    }
+  }
+
+  fs.copyFileSync(src, dbPath);
+  debug(`Restored snapshot "${name}" → ${dbPath}`);
+}
+
+/**
+ * List all saved snapshots.
+ *
+ * @param {object} [options]
+ * @param {string} [options.dbPath] - Explicit path to graph.db
+ * @returns {Array<{ name: string, path: string, size: number, createdAt: Date }>}
+ */
+export function snapshotList(options = {}) {
+  const dbPath = options.dbPath || findDbPath();
+  const dir = snapshotsDir(dbPath);
+
+  if (!fs.existsSync(dir)) return [];
+
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.db'))
+    .map((f) => {
+      const filePath = path.join(dir, f);
+      const stat = fs.statSync(filePath);
+      return {
+        name: f.replace(/\.db$/, ''),
+        path: filePath,
+        size: stat.size,
+        createdAt: stat.birthtime,
+      };
+    })
+    .sort((a, b) => b.createdAt - a.createdAt);
+}
+
+/**
+ * Delete a named snapshot.
+ *
+ * @param {string} name - Snapshot name
+ * @param {object} [options]
+ * @param {string} [options.dbPath] - Explicit path to graph.db
+ */
+export function snapshotDelete(name, options = {}) {
+  validateSnapshotName(name);
+  const dbPath = options.dbPath || findDbPath();
+  const dir = snapshotsDir(dbPath);
+  const target = path.join(dir, `${name}.db`);
+
+  if (!fs.existsSync(target)) {
+    throw new Error(`Snapshot "${name}" not found at ${target}`);
+  }
+
+  fs.unlinkSync(target);
+  debug(`Deleted snapshot: ${target}`);
+}

package/src/structure.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { normalizePath } from './constants.js';
 import { openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
+import { paginateResult } from './paginate.js';
 import { isTestFile } from './queries.js';
 
 // ─── Build-time: insert directory nodes, contains edges, and metrics ────
@@ -463,7 +464,8 @@ export function structureData(customDbPath, opts = {}) {
     }
   }
 
-  return { directories: result, count: result.length };
+  const base = { directories: result, count: result.length };
+  return paginateResult(base, 'directories', { limit: opts.limit, offset: opts.offset });
 }
 
 /**
@@ -534,7 +536,8 @@ export function hotspotsData(customDbPath, opts = {}) {
   }));
 
   db.close();
-  return { metric, level, limit, hotspots };
+  const base = { metric, level, limit, hotspots };
+  return paginateResult(base, 'hotspots', { limit: opts.limit, offset: opts.offset });
 }
 
 /**