@optave/codegraph 2.4.0 → 2.5.1

package/src/queries.js

@@ -5,6 +5,7 @@ import { coChangeForFiles } from './cochange.js';
 import { findCycles } from './cycles.js';
 import { findDbPath, openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
+import { paginateResult } from './paginate.js';
 import { LANGUAGE_REGISTRY } from './parser.js';
 
 /**
@@ -172,7 +173,7 @@ function findMatchingNodes(db, name, opts = {}) {
   return nodes;
 }
 
-function kindIcon(kind) {
+export function kindIcon(kind) {
   switch (kind) {
     case 'function':
       return 'f';
@@ -248,7 +249,8 @@ export function queryNameData(name, customDbPath, opts = {}) {
   });
 
   db.close();
-  return { query: name, results };
+  const base = { query: name, results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 export function impactAnalysisData(file, customDbPath, opts = {}) {
@@ -565,6 +567,255 @@ export function fnImpactData(name, customDbPath, opts = {}) {
   return { name, results };
 }
 
+export function pathData(from, to, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+  const maxDepth = opts.maxDepth || 10;
+  const edgeKinds = opts.edgeKinds || ['calls'];
+  const reverse = opts.reverse || false;
+
+  const fromNodes = findMatchingNodes(db, from, {
+    noTests,
+    file: opts.fromFile,
+    kind: opts.kind,
+  });
+  if (fromNodes.length === 0) {
+    db.close();
+    return {
+      from,
+      to,
+      found: false,
+      error: `No symbol matching "${from}"`,
+      fromCandidates: [],
+      toCandidates: [],
+    };
+  }
+
+  const toNodes = findMatchingNodes(db, to, {
+    noTests,
+    file: opts.toFile,
+    kind: opts.kind,
+  });
+  if (toNodes.length === 0) {
+    db.close();
+    return {
+      from,
+      to,
+      found: false,
+      error: `No symbol matching "${to}"`,
+      fromCandidates: fromNodes
+        .slice(0, 5)
+        .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line })),
+      toCandidates: [],
+    };
+  }
+
+  const sourceNode = fromNodes[0];
+  const targetNode = toNodes[0];
+
+  const fromCandidates = fromNodes
+    .slice(0, 5)
+    .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line }));
+  const toCandidates = toNodes
+    .slice(0, 5)
+    .map((n) => ({ name: n.name, kind: n.kind, file: n.file, line: n.line }));
+
+  // Self-path
+  if (sourceNode.id === targetNode.id) {
+    db.close();
+    return {
+      from,
+      to,
+      fromCandidates,
+      toCandidates,
+      found: true,
+      hops: 0,
+      path: [
+        {
+          name: sourceNode.name,
+          kind: sourceNode.kind,
+          file: sourceNode.file,
+          line: sourceNode.line,
+          edgeKind: null,
+        },
+      ],
+      alternateCount: 0,
+      edgeKinds,
+      reverse,
+      maxDepth,
+    };
+  }
+
+  // Build edge kind filter
+  const kindPlaceholders = edgeKinds.map(() => '?').join(', ');
+
+  // BFS — direction depends on `reverse` flag
+  // Forward: source_id → target_id (A calls... calls B)
+  // Reverse: target_id → source_id (B is called by... called by A)
+  const neighborQuery = reverse
+    ? `SELECT n.id, 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 = ? AND e.kind IN (${kindPlaceholders})`
+    : `SELECT n.id, 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 = ? AND e.kind IN (${kindPlaceholders})`;
+  const neighborStmt = db.prepare(neighborQuery);
+
+  const visited = new Set([sourceNode.id]);
+  // parent map: nodeId → { parentId, edgeKind }
+  const parent = new Map();
+  let queue = [sourceNode.id];
+  let found = false;
+  let alternateCount = 0;
+  let foundDepth = -1;
+
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const nextQueue = [];
+    for (const currentId of queue) {
+      const neighbors = neighborStmt.all(currentId, ...edgeKinds);
+      for (const n of neighbors) {
+        if (noTests && isTestFile(n.file)) continue;
+        if (n.id === targetNode.id) {
+          if (!found) {
+            found = true;
+            foundDepth = depth;
+            parent.set(n.id, { parentId: currentId, edgeKind: n.edge_kind });
+          }
+          alternateCount++;
+          continue;
+        }
+        if (!visited.has(n.id)) {
+          visited.add(n.id);
+          parent.set(n.id, { parentId: currentId, edgeKind: n.edge_kind });
+          nextQueue.push(n.id);
+        }
+      }
+    }
+    if (found) break;
+    queue = nextQueue;
+    if (queue.length === 0) break;
+  }
+
+  if (!found) {
+    db.close();
+    return {
+      from,
+      to,
+      fromCandidates,
+      toCandidates,
+      found: false,
+      hops: null,
+      path: [],
+      alternateCount: 0,
+      edgeKinds,
+      reverse,
+      maxDepth,
+    };
+  }
+
+  // alternateCount includes the one we kept; subtract 1 for "alternates"
+  alternateCount = Math.max(0, alternateCount - 1);
+
+  // Reconstruct path from target back to source
+  const pathIds = [targetNode.id];
+  let cur = targetNode.id;
+  while (cur !== sourceNode.id) {
+    const p = parent.get(cur);
+    pathIds.push(p.parentId);
+    cur = p.parentId;
+  }
+  pathIds.reverse();
+
+  // Build path with node info
+  const nodeCache = new Map();
+  const getNode = (id) => {
+    if (nodeCache.has(id)) return nodeCache.get(id);
+    const row = db.prepare('SELECT name, kind, file, line FROM nodes WHERE id = ?').get(id);
+    nodeCache.set(id, row);
+    return row;
+  };
+
+  const resultPath = pathIds.map((id, idx) => {
+    const node = getNode(id);
+    const edgeKind = idx === 0 ? null : parent.get(id).edgeKind;
+    return { name: node.name, kind: node.kind, file: node.file, line: node.line, edgeKind };
+  });
+
+  db.close();
+  return {
+    from,
+    to,
+    fromCandidates,
+    toCandidates,
+    found: true,
+    hops: foundDepth,
+    path: resultPath,
+    alternateCount,
+    edgeKinds,
+    reverse,
+    maxDepth,
+  };
+}
+
+export function symbolPath(from, to, customDbPath, opts = {}) {
+  const data = pathData(from, to, customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (data.error) {
+    console.log(data.error);
+    return;
+  }
+
+  if (!data.found) {
+    const dir = data.reverse ? 'reverse ' : '';
+    console.log(`No ${dir}path from "${from}" to "${to}" within ${data.maxDepth} hops.`);
+    if (data.fromCandidates.length > 1) {
+      console.log(
+        `\n  "${from}" matched ${data.fromCandidates.length} symbols — using top match: ${data.fromCandidates[0].name} (${data.fromCandidates[0].file}:${data.fromCandidates[0].line})`,
+      );
+    }
+    if (data.toCandidates.length > 1) {
+      console.log(
+        `  "${to}" matched ${data.toCandidates.length} symbols — using top match: ${data.toCandidates[0].name} (${data.toCandidates[0].file}:${data.toCandidates[0].line})`,
+      );
+    }
+    return;
+  }
+
+  if (data.hops === 0) {
+    console.log(`\n"${from}" and "${to}" resolve to the same symbol (0 hops):`);
+    const n = data.path[0];
+    console.log(`  ${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}\n`);
+    return;
+  }
+
+  const dir = data.reverse ? ' (reverse)' : '';
+  console.log(
+    `\nPath from ${from} to ${to} (${data.hops} ${data.hops === 1 ? 'hop' : 'hops'})${dir}:\n`,
+  );
+  for (let i = 0; i < data.path.length; i++) {
+    const n = data.path[i];
+    const indent = '  '.repeat(i + 1);
+    if (i === 0) {
+      console.log(`${indent}${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}`);
+    } else {
+      console.log(
+        `${indent}--[${n.edgeKind}]--> ${kindIcon(n.kind)} ${n.name} (${n.kind}) -- ${n.file}:${n.line}`,
+      );
+    }
+  }
+
+  if (data.alternateCount > 0) {
+    console.log(
+      `\n  (${data.alternateCount} alternate shortest ${data.alternateCount === 1 ? 'path' : 'paths'} at same depth)`,
+    );
+  }
+  console.log();
+}
+
 /**
  * Fix #2: Shell injection vulnerability.
  * Uses execFileSync instead of execSync to prevent shell interpretation of user input.
@@ -904,7 +1155,8 @@ export function listFunctionsData(customDbPath, opts = {}) {
   if (noTests) rows = rows.filter((r) => !isTestFile(r.file));
 
   db.close();
-  return { count: rows.length, functions: rows };
+  const base = { count: rows.length, functions: rows };
+  return paginateResult(base, 'functions', { limit: opts.limit, offset: opts.offset });
 }
 
 export function statsData(customDbPath, opts = {}) {
@@ -1114,6 +1366,32 @@ export function statsData(customDbPath, opts = {}) {
   const roles = {};
   for (const r of roleRows) roles[r.role] = r.c;
 
+  // Complexity summary
+  let complexity = null;
+  try {
+    const cRows = db
+      .prepare(
+        `SELECT fc.cognitive, fc.cyclomatic, fc.max_nesting, fc.maintainability_index
+       FROM function_complexity fc JOIN nodes n ON fc.node_id = n.id
+       WHERE n.kind IN ('function','method') ${testFilter}`,
+      )
+      .all();
+    if (cRows.length > 0) {
+      const miValues = cRows.map((r) => r.maintainability_index || 0);
+      complexity = {
+        analyzed: cRows.length,
+        avgCognitive: +(cRows.reduce((s, r) => s + r.cognitive, 0) / cRows.length).toFixed(1),
+        avgCyclomatic: +(cRows.reduce((s, r) => s + r.cyclomatic, 0) / cRows.length).toFixed(1),
+        maxCognitive: Math.max(...cRows.map((r) => r.cognitive)),
+        maxCyclomatic: Math.max(...cRows.map((r) => r.cyclomatic)),
+        avgMI: +(miValues.reduce((s, v) => s + v, 0) / miValues.length).toFixed(1),
+        minMI: +Math.min(...miValues).toFixed(1),
+      };
+    }
+  } catch {
+    /* table may not exist in older DBs */
+  }
+
   db.close();
   return {
     nodes: { total: totalNodes, byKind: nodesByKind },
@@ -1124,11 +1402,21 @@ export function statsData(customDbPath, opts = {}) {
     embeddings,
     quality,
     roles,
+    complexity,
   };
 }
 
-export function stats(customDbPath, opts = {}) {
+export async function stats(customDbPath, opts = {}) {
   const data = statsData(customDbPath, { noTests: opts.noTests });
+
+  // Community detection summary (async import for lazy-loading)
+  try {
+    const { communitySummaryForStats } = await import('./communities.js');
+    data.communities = communitySummaryForStats(customDbPath, { noTests: opts.noTests });
+  } catch {
+    /* graphology may not be available */
+  }
+
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1236,13 +1524,39 @@ export function stats(customDbPath, opts = {}) {
     }
   }
 
+  // Complexity
+  if (data.complexity) {
+    const cx = data.complexity;
+    const miPart = cx.avgMI != null ? ` | avg MI: ${cx.avgMI} | min MI: ${cx.minMI}` : '';
+    console.log(
+      `\nComplexity: ${cx.analyzed} functions | avg cognitive: ${cx.avgCognitive} | avg cyclomatic: ${cx.avgCyclomatic} | max cognitive: ${cx.maxCognitive}${miPart}`,
+    );
+  }
+
+  // Communities
+  if (data.communities) {
+    const cm = data.communities;
+    console.log(
+      `\nCommunities: ${cm.communityCount} detected | modularity: ${cm.modularity} | drift: ${cm.driftScore}%`,
+    );
+  }
+
   console.log();
 }
 
 // ─── Human-readable output (original formatting) ───────────────────────
 
 export function queryName(name, customDbPath, opts = {}) {
-  const data = queryNameData(name, customDbPath, { noTests: opts.noTests });
+  const data = queryNameData(name, customDbPath, {
+    noTests: opts.noTests,
+    limit: opts.limit,
+    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));
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -1698,6 +2012,27 @@ export function contextData(name, customDbPath, opts = {}) {
       });
     }
 
+    // Complexity metrics
+    let complexityMetrics = null;
+    try {
+      const cRow = db
+        .prepare(
+          'SELECT cognitive, cyclomatic, max_nesting, maintainability_index, halstead_volume FROM function_complexity WHERE node_id = ?',
+        )
+        .get(node.id);
+      if (cRow) {
+        complexityMetrics = {
+          cognitive: cRow.cognitive,
+          cyclomatic: cRow.cyclomatic,
+          maxNesting: cRow.max_nesting,
+          maintainabilityIndex: cRow.maintainability_index || 0,
+          halsteadVolume: cRow.halstead_volume || 0,
+        };
+      }
+    } catch {
+      /* table may not exist */
+    }
+
     return {
       name: node.name,
       kind: node.kind,
@@ -1707,6 +2042,7 @@ export function contextData(name, customDbPath, opts = {}) {
       endLine: node.end_line || null,
       source,
       signature,
+      complexity: complexityMetrics,
       callees,
       callers,
       relatedTests,
@@ -1741,6 +2077,17 @@ export function context(name, customDbPath, opts = {}) {
       console.log();
     }
 
+    // Complexity
+    if (r.complexity) {
+      const cx = r.complexity;
+      const miPart = cx.maintainabilityIndex ? ` | MI: ${cx.maintainabilityIndex}` : '';
+      console.log('## Complexity');
+      console.log(
+        `  Cognitive: ${cx.cognitive} | Cyclomatic: ${cx.cyclomatic} | Max Nesting: ${cx.maxNesting}${miPart}`,
+      );
+      console.log();
+    }
+
     // Source
     if (r.source) {
       console.log('## Source');
@@ -1959,6 +2306,27 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
       .filter((r) => isTestFile(r.file))
       .map((r) => ({ file: r.file }));
 
+    // Complexity metrics
+    let complexityMetrics = null;
+    try {
+      const cRow = db
+        .prepare(
+          'SELECT cognitive, cyclomatic, max_nesting, maintainability_index, halstead_volume FROM function_complexity WHERE node_id = ?',
+        )
+        .get(node.id);
+      if (cRow) {
+        complexityMetrics = {
+          cognitive: cRow.cognitive,
+          cyclomatic: cRow.cyclomatic,
+          maxNesting: cRow.max_nesting,
+          maintainabilityIndex: cRow.maintainability_index || 0,
+          halsteadVolume: cRow.halstead_volume || 0,
+        };
+      }
+    } catch {
+      /* table may not exist */
+    }
+
     return {
       name: node.name,
       kind: node.kind,
@@ -1969,6 +2337,7 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
       lineCount,
       summary,
       signature,
+      complexity: complexityMetrics,
       callees,
       callers,
       relatedTests,
@@ -2118,6 +2487,14 @@ export function explain(target, customDbPath, opts = {}) {
         if (r.signature.returnType) console.log(`${indent}  Returns: ${r.signature.returnType}`);
       }
 
+      if (r.complexity) {
+        const cx = r.complexity;
+        const miPart = cx.maintainabilityIndex ? ` MI=${cx.maintainabilityIndex}` : '';
+        console.log(
+          `${indent}  Complexity: cognitive=${cx.cognitive} cyclomatic=${cx.cyclomatic} nesting=${cx.maxNesting}${miPart}`,
+        );
+      }
+
       if (r.callees.length > 0) {
         console.log(`\n${indent}  Calls (${r.callees.length}):`);
         for (const c of r.callees) {
@@ -2261,11 +2638,17 @@ export function whereData(target, customDbPath, opts = {}) {
   const results = fileMode ? whereFileImpl(db, target) : whereSymbolImpl(db, target, noTests);
 
   db.close();
-  return { target, mode: fileMode ? 'file' : 'symbol', results };
+  const base = { target, mode: fileMode ? 'file' : 'symbol', results };
+  return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
 }
 
 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));
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -2347,11 +2730,17 @@ export function rolesData(customDbPath, opts = {}) {
   }
 
   db.close();
-  return { count: rows.length, summary, symbols: rows };
+  const base = { count: rows.length, summary, symbols: rows };
+  return paginateResult(base, 'symbols', { limit: opts.limit, offset: opts.offset });
 }
 
 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));
+    return;
+  }
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;

package/src/registry.js

@@ -135,11 +135,14 @@ export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
  * Remove registry entries whose repo directory no longer exists on disk,
  * or that haven't been accessed within `ttlDays` days.
  * Returns an array of `{ name, path, reason }` for each pruned entry.
+ *
+ * When `dryRun` is true, entries are identified but not removed from disk.
  */
 export function pruneRegistry(
   registryPath = REGISTRY_PATH,
   ttlDays = DEFAULT_TTL_DAYS,
   excludeNames = [],
+  dryRun = false,
 ) {
   const registry = loadRegistry(registryPath);
   const pruned = [];
@@ -152,17 +155,17 @@ export function pruneRegistry(
     if (excludeSet.has(name)) continue;
     if (!fs.existsSync(entry.path)) {
       pruned.push({ name, path: entry.path, reason: 'missing' });
-      delete registry.repos[name];
+      if (!dryRun) delete registry.repos[name];
       continue;
     }
     const lastAccess = Date.parse(entry.lastAccessedAt || entry.addedAt);
     if (lastAccess < cutoff) {
       pruned.push({ name, path: entry.path, reason: 'expired' });
-      delete registry.repos[name];
+      if (!dryRun) delete registry.repos[name];
     }
   }
 
-  if (pruned.length > 0) {
+  if (!dryRun && pruned.length > 0) {
     saveRegistry(registry, registryPath);
   }