@optave/codegraph 2.4.0 → 2.5.1

package/src/cli.js

@@ -29,6 +29,7 @@ import {
   queryName,
   roles,
   stats,
+  symbolPath,
   VALID_ROLES,
   where,
 } from './queries.js';
@@ -99,8 +100,17 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((name, opts) => {
-    queryName(name, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+    queryName(name, opts.db, {
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
   });
 
 program
@@ -136,8 +146,8 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
-  .action((opts) => {
-    stats(opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+  .action(async (opts) => {
+    await stats(opts.db, { noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -199,6 +209,36 @@ program
     });
   });
 
+program
+  .command('path <from> <to>')
+  .description('Find shortest path between two symbols (A calls...calls B)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--max-depth <n>', 'Maximum BFS depth', '10')
+  .option('--kinds <kinds>', 'Comma-separated edge kinds to follow (default: calls)')
+  .option('--reverse', 'Follow edges backward (B is called by...called by A)')
+  .option('--from-file <path>', 'Disambiguate source symbol by file (partial match)')
+  .option('--to-file <path>', 'Disambiguate target symbol by file (partial match)')
+  .option('-k, --kind <kind>', 'Filter both symbols by kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action((from, to, opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
+    symbolPath(from, to, opts.db, {
+      maxDepth: parseInt(opts.maxDepth, 10),
+      edgeKinds: opts.kinds ? opts.kinds.split(',').map((s) => s.trim()) : undefined,
+      reverse: opts.reverse,
+      fromFile: opts.fromFile,
+      toFile: opts.toFile,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
+  });
+
 program
   .command('context <name>')
   .description('Full context for a function: source, deps, callers, tests, signature')
@@ -251,13 +291,23 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((name, opts) => {
     if (!name && !opts.file) {
       console.error('Provide a symbol name or use --file <path>');
       process.exit(1);
     }
     const target = opts.file || name;
-    where(target, opts.db, { file: !!opts.file, noTests: resolveNoTests(opts), json: opts.json });
+    where(target, opts.db, {
+      file: !!opts.file,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
   });
 
 program
@@ -418,6 +468,7 @@ registry
   .description('Remove stale registry entries (missing directories or idle beyond TTL)')
   .option('--ttl <days>', 'Days of inactivity before pruning (default: 30)', '30')
   .option('--exclude <names>', 'Comma-separated repo names to preserve from pruning')
+  .option('--dry-run', 'Show what would be pruned without removing anything')
   .action((opts) => {
     const excludeNames = opts.exclude
       ? opts.exclude
@@ -425,15 +476,25 @@ registry
           .map((s) => s.trim())
           .filter((s) => s.length > 0)
       : [];
-    const pruned = pruneRegistry(undefined, parseInt(opts.ttl, 10), excludeNames);
+    const dryRun = !!opts.dryRun;
+    const pruned = pruneRegistry(undefined, parseInt(opts.ttl, 10), excludeNames, dryRun);
     if (pruned.length === 0) {
       console.log('No stale entries found.');
     } else {
+      const prefix = dryRun ? 'Would prune' : 'Pruned';
       for (const entry of pruned) {
         const tag = entry.reason === 'expired' ? 'expired' : 'missing';
-        console.log(`Pruned "${entry.name}" (${entry.path}) [${tag}]`);
+        console.log(`${prefix} "${entry.name}" (${entry.path}) [${tag}]`);
+      }
+      if (dryRun) {
+        console.log(
+          `\nDry run: ${pruned.length} ${pruned.length === 1 ? 'entry' : 'entries'} would be removed.`,
+        );
+      } else {
+        console.log(
+          `\nRemoved ${pruned.length} stale ${pruned.length === 1 ? 'entry' : 'entries'}.`,
+        );
       }
-      console.log(`\nRemoved ${pruned.length} stale ${pruned.length === 1 ? 'entry' : 'entries'}.`);
     }
   });
 
@@ -470,6 +531,7 @@ program
     `Embedding strategy: ${EMBEDDING_STRATEGIES.join(', ')}. "structured" uses graph context (callers/callees), "source" embeds raw code`,
     'structured',
   )
+  .option('-d, --db <path>', 'Path to graph.db')
   .action(async (dir, opts) => {
     if (!EMBEDDING_STRATEGIES.includes(opts.strategy)) {
       console.error(
@@ -479,7 +541,7 @@ program
     }
     const root = path.resolve(dir || '.');
     const model = opts.model || config.embeddings?.model || DEFAULT_MODEL;
-    await buildEmbeddings(root, model, undefined, { strategy: opts.strategy });
+    await buildEmbeddings(root, model, opts.db, { strategy: opts.strategy });
   });
 
 program
@@ -516,6 +578,7 @@ program
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--depth <n>', 'Max directory depth')
   .option('--sort <metric>', 'Sort by: cohesion | fan-in | fan-out | density | files', 'files')
+  .option('--full', 'Show all files without limit')
   .option('-T, --no-tests', 'Exclude test/spec files')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
@@ -525,6 +588,7 @@ program
       directory: dir,
       depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
       sort: opts.sort,
+      full: opts.full,
       noTests: resolveNoTests(opts),
     });
     if (opts.json) {
@@ -570,6 +634,9 @@ program
   .option('-T, --no-tests', 'Exclude test/spec files')
   .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((opts) => {
     if (opts.role && !VALID_ROLES.includes(opts.role)) {
       console.error(`Invalid role "${opts.role}". Valid roles: ${VALID_ROLES.join(', ')}`);
@@ -580,6 +647,9 @@ program
       file: opts.file,
       noTests: resolveNoTests(opts),
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
     });
   });
 
@@ -645,6 +715,144 @@ program
     }
   });
 
+program
+  .command('flow [name]')
+  .description(
+    'Trace execution flow forward from an entry point (route, command, event) through callees to leaves',
+  )
+  .option('--list', 'List all entry points grouped by type')
+  .option('--depth <n>', 'Max forward traversal depth', '10')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-f, --file <path>', 'Scope to a specific file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .action(async (name, opts) => {
+    if (!name && !opts.list) {
+      console.error('Provide a function/entry point name or use --list to see all entry points.');
+      process.exit(1);
+    }
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
+    const { flow } = await import('./flow.js');
+    flow(name, opts.db, {
+      list: opts.list,
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  });
+
+program
+  .command('complexity [target]')
+  .description('Show per-function complexity metrics (cognitive, cyclomatic, nesting depth, MI)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Max results', '20')
+  .option(
+    '--sort <metric>',
+    'Sort by: cognitive | cyclomatic | nesting | mi | volume | effort | bugs | loc',
+    'cognitive',
+  )
+  .option('--above-threshold', 'Only functions exceeding warn thresholds')
+  .option('--health', 'Show health metrics (Halstead, MI) columns')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (target, opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
+    const { complexity } = await import('./complexity.js');
+    complexity(opts.db, {
+      target,
+      limit: parseInt(opts.limit, 10),
+      sort: opts.sort,
+      aboveThreshold: opts.aboveThreshold,
+      health: opts.health,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
+  });
+
+program
+  .command('manifesto')
+  .description('Evaluate manifesto rules (pass/fail verdicts for code health)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-f, --file <path>', 'Scope to file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
+    const { manifesto } = await import('./manifesto.js');
+    manifesto(opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
+  });
+
+program
+  .command('communities')
+  .description('Detect natural module boundaries using Louvain community detection')
+  .option('--functions', 'Function-level instead of file-level')
+  .option('--resolution <n>', 'Louvain resolution parameter (default 1.0)', '1.0')
+  .option('--drift', 'Show only drift analysis')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (opts) => {
+    const { communities } = await import('./communities.js');
+    communities(opts.db, {
+      functions: opts.functions,
+      resolution: parseFloat(opts.resolution),
+      drift: opts.drift,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
+  });
+
+program
+  .command('branch-compare <base> <target>')
+  .description('Compare code structure between two branches/refs')
+  .option('--depth <n>', 'Max transitive caller depth', '3')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .option('-f, --format <format>', 'Output format: text, mermaid, json', 'text')
+  .action(async (base, target, opts) => {
+    const { branchCompare } = await import('./branch-compare.js');
+    await branchCompare(base, target, {
+      engine: program.opts().engine,
+      depth: parseInt(opts.depth, 10),
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      format: opts.format,
+    });
+  });
+
 program
   .command('watch [dir]')
   .description('Watch project for file changes and incrementally update the graph')
@@ -680,6 +888,43 @@ program
     console.log(`  Engine flag   : --engine ${engine}`);
     console.log(`  Active engine : ${activeName}${activeVersion ? ` (v${activeVersion})` : ''}`);
     console.log();
+
+    // Build metadata from DB
+    try {
+      const { findDbPath, getBuildMeta } = await import('./db.js');
+      const Database = (await import('better-sqlite3')).default;
+      const dbPath = findDbPath();
+      const fs = await import('node:fs');
+      if (fs.existsSync(dbPath)) {
+        const db = new Database(dbPath, { readonly: true });
+        const buildEngine = getBuildMeta(db, 'engine');
+        const buildVersion = getBuildMeta(db, 'codegraph_version');
+        const builtAt = getBuildMeta(db, 'built_at');
+        db.close();
+
+        if (buildEngine || buildVersion || builtAt) {
+          console.log('Build metadata');
+          console.log('──────────────');
+          if (buildEngine) console.log(`  Engine        : ${buildEngine}`);
+          if (buildVersion) console.log(`  Version       : ${buildVersion}`);
+          if (builtAt) console.log(`  Built at      : ${builtAt}`);
+
+          if (buildVersion && buildVersion !== program.version()) {
+            console.log(
+              `  ⚠ DB was built with v${buildVersion}, current is v${program.version()}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          if (buildEngine && buildEngine !== activeName) {
+            console.log(
+              `  ⚠ DB was built with ${buildEngine} engine, active is ${activeName}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          console.log();
+        }
+      }
+    } catch {
+      /* diagnostics must never crash */
+    }
   });
 
 program.parse();

package/src/cochange.js

@@ -9,7 +9,7 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { normalizePath } from './constants.js';
-import { findDbPath, initSchema, openDb, openReadonlyOrFail } from './db.js';
+import { closeDb, findDbPath, initSchema, openDb, openReadonlyOrFail } from './db.js';
 import { warn } from './logger.js';
 import { isTestFile } from './queries.js';
 
@@ -145,7 +145,7 @@ export function analyzeCoChanges(customDbPath, opts = {}) {
   const repoRoot = path.resolve(path.dirname(dbPath), '..');
 
   if (!fs.existsSync(path.join(repoRoot, '.git'))) {
-    db.close();
+    closeDb(db);
     return { error: `Not a git repository: ${repoRoot}` };
   }
 
@@ -245,7 +245,7 @@ export function analyzeCoChanges(customDbPath, opts = {}) {
 
   const totalPairs = db.prepare('SELECT COUNT(*) as cnt FROM co_changes').get().cnt;
 
-  db.close();
+  closeDb(db);
 
   return {
     pairsFound: totalPairs,
@@ -275,14 +275,14 @@ export function coChangeData(file, customDbPath, opts = {}) {
   try {
     db.prepare('SELECT 1 FROM co_changes LIMIT 1').get();
   } catch {
-    db.close();
+    closeDb(db);
     return { error: 'No co-change data found. Run `codegraph co-change --analyze` first.' };
   }
 
   // Resolve file via partial match
   const resolvedFile = resolveCoChangeFile(db, file);
   if (!resolvedFile) {
-    db.close();
+    closeDb(db);
     return { error: `No co-change data found for file matching "${file}"` };
   }
 
@@ -311,7 +311,7 @@ export function coChangeData(file, customDbPath, opts = {}) {
   }
 
   const meta = getCoChangeMeta(db);
-  db.close();
+  closeDb(db);
 
   return { file: resolvedFile, partners, meta };
 }
@@ -334,7 +334,7 @@ export function coChangeTopData(customDbPath, opts = {}) {
   try {
     db.prepare('SELECT 1 FROM co_changes LIMIT 1').get();
   } catch {
-    db.close();
+    closeDb(db);
     return { error: 'No co-change data found. Run `codegraph co-change --analyze` first.' };
   }
 
@@ -363,7 +363,7 @@ export function coChangeTopData(customDbPath, opts = {}) {
   }
 
   const meta = getCoChangeMeta(db);
-  db.close();
+  closeDb(db);
 
   return { pairs, meta };
 }