@optave/codegraph 2.5.0 → 2.6.0

package/src/cli.js

@@ -3,6 +3,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
+import { audit } from './audit.js';
+import { BATCH_COMMANDS, batch } from './batch.js';
 import { buildGraph } from './builder.js';
 import { loadConfig } from './config.js';
 import { findCycles, formatCycles } from './cycles.js';
@@ -16,6 +18,7 @@ import {
 } from './embedder.js';
 import { exportDOT, exportJSON, exportMermaid } from './export.js';
 import { setVerbose } from './logger.js';
+import { printNdjson } from './paginate.js';
 import {
   ALL_SYMBOL_KINDS,
   context,
@@ -40,6 +43,7 @@ import {
   registerRepo,
   unregisterRepo,
 } from './registry.js';
+import { snapshotDelete, snapshotList, snapshotRestore, snapshotSave } from './snapshot.js';
 import { checkForUpdates, printUpdateNotification } from './update-check.js';
 import { watchProject } from './watcher.js';
 
@@ -83,6 +87,12 @@ function resolveNoTests(opts) {
   return config.query?.excludeTests || false;
 }
 
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
 program
   .command('build [dir]')
   .description('Parse repo and build graph in .codegraph/graph.db')
@@ -120,8 +130,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((file, opts) => {
-    impactAnalysis(file, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+    impactAnalysis(file, 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
@@ -157,8 +176,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((file, opts) => {
-    fileDeps(file, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
+    fileDeps(file, 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
@@ -171,6 +199,9 @@ 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 (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
       console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
@@ -182,6 +213,9 @@ program
       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,
     });
   });
 
@@ -195,6 +229,9 @@ 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 (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
       console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
@@ -206,6 +243,9 @@ program
       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,
     });
   });
 
@@ -251,6 +291,9 @@ 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 (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
       console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
@@ -264,6 +307,9 @@ program
       noTests: resolveNoTests(opts),
       includeTests: opts.withTestSource,
       json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
     });
   });
 
@@ -275,11 +321,41 @@ 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((target, opts) => {
     explain(target, opts.db, {
       depth: parseInt(opts.depth, 10),
       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('audit <target>')
+  .description('Composite report: explain + impact + health metrics per function')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Impact analysis depth', '3')
+  .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((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);
+    }
+    audit(target, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
     });
   });
 
@@ -320,6 +396,9 @@ program
   .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')
+  .option('--limit <number>', 'Max results to return')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action((ref, opts) => {
     diffImpact(opts.db, {
       ref,
@@ -328,6 +407,37 @@ program
       noTests: resolveNoTests(opts),
       json: opts.json,
       format: opts.format,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  });
+
+program
+  .command('check [ref]')
+  .description('Run validation predicates against git changes (CI gate)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--staged', 'Analyze staged changes')
+  .option('--cycles', 'Assert no dependency cycles involve changed files')
+  .option('--blast-radius <n>', 'Assert no function exceeds N transitive callers')
+  .option('--signatures', 'Assert no function declaration lines were modified')
+  .option('--boundaries', 'Assert no cross-owner boundary violations')
+  .option('--depth <n>', 'Max BFS depth for blast radius (default: 3)')
+  .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 (ref, opts) => {
+    const { check } = await import('./check.js');
+    check(opts.db, {
+      ref,
+      staged: opts.staged,
+      cycles: opts.cycles || undefined,
+      blastRadius: opts.blastRadius ? parseInt(opts.blastRadius, 10) : undefined,
+      signatures: opts.signatures || undefined,
+      boundaries: opts.boundaries || undefined,
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
     });
   });
 
@@ -468,6 +578,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
@@ -475,15 +586,100 @@ 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'}.`);
+    }
+  });
+
+// ─── Snapshot commands ──────────────────────────────────────────────────
+
+const snapshot = program
+  .command('snapshot')
+  .description('Save and restore graph database snapshots');
+
+snapshot
+  .command('save <name>')
+  .description('Save a snapshot of the current graph database')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--force', 'Overwrite existing snapshot')
+  .action((name, opts) => {
+    try {
+      const result = snapshotSave(name, { dbPath: opts.db, force: opts.force });
+      console.log(`Snapshot saved: ${result.name} (${formatSize(result.size)})`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('restore <name>')
+  .description('Restore a snapshot over the current graph database')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .action((name, opts) => {
+    try {
+      snapshotRestore(name, { dbPath: opts.db });
+      console.log(`Snapshot "${name}" restored.`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('list')
+  .description('List all saved snapshots')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => {
+    try {
+      const snapshots = snapshotList({ dbPath: opts.db });
+      if (opts.json) {
+        console.log(JSON.stringify(snapshots, null, 2));
+      } else if (snapshots.length === 0) {
+        console.log('No snapshots found.');
+      } else {
+        console.log(`Snapshots (${snapshots.length}):\n`);
+        for (const s of snapshots) {
+          console.log(
+            `  ${s.name.padEnd(30)} ${formatSize(s.size).padStart(10)}  ${s.createdAt.toISOString()}`,
+          );
+        }
+      }
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  });
+
+snapshot
+  .command('delete <name>')
+  .description('Delete a saved snapshot')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .action((name, opts) => {
+    try {
+      snapshotDelete(name, { dbPath: opts.db });
+      console.log(`Snapshot "${name}" deleted.`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
     }
   });
 
@@ -545,8 +741,16 @@ program
   .option('-k, --kind <kind>', 'Filter by kind: function, method, class')
   .option('--file <pattern>', 'Filter by file path pattern')
   .option('--rrf-k <number>', 'RRF k parameter for multi-query ranking', '60')
+  .option('--mode <mode>', 'Search mode: hybrid, semantic, keyword (default: hybrid)')
   .option('-j, --json', 'Output as JSON')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (query, opts) => {
+    const validModes = ['hybrid', 'semantic', 'keyword'];
+    if (opts.mode && !validModes.includes(opts.mode)) {
+      console.error(`Invalid mode "${opts.mode}". Valid: ${validModes.join(', ')}`);
+      process.exit(1);
+    }
     await search(query, opts.db, {
       limit: parseInt(opts.limit, 10),
       noTests: resolveNoTests(opts),
@@ -555,6 +759,7 @@ program
       kind: opts.kind,
       filePattern: opts.file,
       rrfK: parseInt(opts.rrfK, 10),
+      mode: opts.mode,
       json: opts.json,
     });
   });
@@ -571,6 +776,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(async (dir, opts) => {
     const { structureData, formatStructure } = await import('./structure.js');
     const data = structureData(opts.db, {
@@ -579,8 +787,12 @@ program
       sort: opts.sort,
       full: opts.full,
       noTests: resolveNoTests(opts),
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
     });
-    if (opts.json) {
+    if (opts.ndjson) {
+      printNdjson(data, 'directories');
+    } else if (opts.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
       console.log(formatStructure(data));
@@ -599,15 +811,20 @@ 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('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (opts) => {
     const { hotspotsData, formatHotspots } = await import('./structure.js');
     const data = hotspotsData(opts.db, {
       metric: opts.metric,
       level: opts.level,
       limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
       noTests: resolveNoTests(opts),
     });
-    if (opts.json) {
+    if (opts.ndjson) {
+      printNdjson(data, 'hotspots');
+    } else if (opts.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
       console.log(formatHotspots(data));
@@ -657,6 +874,8 @@ 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('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (file, opts) => {
     const { analyzeCoChanges, coChangeData, coChangeTopData, formatCoChange, formatCoChangeTop } =
       await import('./cochange.js');
@@ -683,20 +902,25 @@ program
 
     const queryOpts = {
       limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
       minJaccard: opts.minJaccard ? parseFloat(opts.minJaccard) : config.coChange?.minJaccard,
       noTests: resolveNoTests(opts),
     };
 
     if (file) {
       const data = coChangeData(file, opts.db, queryOpts);
-      if (opts.json) {
+      if (opts.ndjson) {
+        printNdjson(data, 'partners');
+      } else if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
       } else {
         console.log(formatCoChange(data));
       }
     } else {
       const data = coChangeTopData(opts.db, queryOpts);
-      if (opts.json) {
+      if (opts.ndjson) {
+        printNdjson(data, 'pairs');
+      } else if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
       } else {
         console.log(formatCoChangeTop(data));
@@ -760,6 +984,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')
+  .option('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
   .action(async (target, opts) => {
     if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
       console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
@@ -769,6 +995,7 @@ program
     complexity(opts.db, {
       target,
       limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
       sort: opts.sort,
       aboveThreshold: opts.aboveThreshold,
       health: opts.health,
@@ -776,6 +1003,7 @@ program
       kind: opts.kind,
       noTests: resolveNoTests(opts),
       json: opts.json,
+      ndjson: opts.ndjson,
     });
   });
 
@@ -788,6 +1016,9 @@ program
   .option('-f, --file <path>', 'Scope to file (partial match)')
   .option('-k, --kind <kind>', 'Filter by symbol kind')
   .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 (opts) => {
     if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
       console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
@@ -799,6 +1030,9 @@ program
       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,
     });
   });
 
@@ -812,6 +1046,9 @@ 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(async (opts) => {
     const { communities } = await import('./communities.js');
     communities(opts.db, {
@@ -820,6 +1057,84 @@ program
       drift: opts.drift,
       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('triage')
+  .description(
+    'Ranked audit queue by composite risk score (connectivity + complexity + churn + role)',
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-n, --limit <number>', 'Max results to return', '20')
+  .option('--sort <metric>', 'Sort metric: risk | complexity | churn | fan-in | mi', 'risk')
+  .option('--min-score <score>', 'Only show symbols with risk score >= threshold')
+  .option('--role <role>', 'Filter by role (entry, core, utility, adapter, leaf, dead)')
+  .option('-f, --file <path>', 'Scope to a specific file (partial match)')
+  .option('-k, --kind <kind>', 'Filter by symbol kind (function, method, class)')
+  .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('--offset <number>', 'Skip N results (default: 0)')
+  .option('--ndjson', 'Newline-delimited JSON output')
+  .option('--weights <json>', 'Custom weights JSON (e.g. \'{"fanIn":1,"complexity":0}\')')
+  .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);
+    }
+    if (opts.role && !VALID_ROLES.includes(opts.role)) {
+      console.error(`Invalid role "${opts.role}". Valid: ${VALID_ROLES.join(', ')}`);
+      process.exit(1);
+    }
+    let weights;
+    if (opts.weights) {
+      try {
+        weights = JSON.parse(opts.weights);
+      } catch {
+        console.error('Invalid --weights JSON');
+        process.exit(1);
+      }
+    }
+    const { triage } = await import('./triage.js');
+    triage(opts.db, {
+      limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      sort: opts.sort,
+      minScore: opts.minScore,
+      role: opts.role,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      weights,
+    });
+  });
+
+program
+  .command('owners [target]')
+  .description('Show CODEOWNERS mapping for files and functions')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--owner <owner>', 'Filter to a specific owner')
+  .option('--boundary', 'Show cross-owner boundary edges')
+  .option('-f, --file <path>', 'Scope to a specific file')
+  .option('-k, --kind <kind>', 'Filter by symbol kind')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (target, opts) => {
+    const { owners } = await import('./owners.js');
+    owners(opts.db, {
+      owner: opts.owner,
+      boundary: opts.boundary,
+      file: opts.file || target,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+      json: opts.json,
     });
   });
 
@@ -916,4 +1231,55 @@ program
     }
   });
 
+program
+  .command('batch <command> [targets...]')
+  .description(
+    `Run a query against multiple targets in one call. Output is always JSON.\nValid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
+  )
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--from-file <path>', 'Read targets from file (JSON array or newline-delimited)')
+  .option('--stdin', 'Read targets from stdin (JSON array)')
+  .option('--depth <n>', 'Traversal depth passed to underlying command')
+  .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)')
+  .action(async (command, positionalTargets, opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
+
+    let targets;
+    if (opts.fromFile) {
+      const raw = fs.readFileSync(opts.fromFile, 'utf-8').trim();
+      if (raw.startsWith('[')) {
+        targets = JSON.parse(raw);
+      } else {
+        targets = raw.split(/\r?\n/).filter(Boolean);
+      }
+    } else if (opts.stdin) {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(chunk);
+      const raw = Buffer.concat(chunks).toString('utf-8').trim();
+      targets = raw.startsWith('[') ? JSON.parse(raw) : raw.split(/\r?\n/).filter(Boolean);
+    } else {
+      targets = positionalTargets;
+    }
+
+    if (!targets || targets.length === 0) {
+      console.error('No targets provided. Pass targets as arguments, --from-file, or --stdin.');
+      process.exit(1);
+    }
+
+    const batchOpts = {
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: resolveNoTests(opts),
+    };
+
+    batch(command, targets, opts.db, batchOpts);
+  });
+
 program.parse();

package/src/cochange.js

@@ -11,6 +11,7 @@ import path from 'node:path';
 import { normalizePath } from './constants.js';
 import { closeDb, findDbPath, initSchema, openDb, openReadonlyOrFail } from './db.js';
 import { warn } from './logger.js';
+import { paginateResult } from './paginate.js';
 import { isTestFile } from './queries.js';
 
 /**
@@ -313,7 +314,8 @@ export function coChangeData(file, customDbPath, opts = {}) {
   const meta = getCoChangeMeta(db);
   closeDb(db);
 
-  return { file: resolvedFile, partners, meta };
+  const base = { file: resolvedFile, partners, meta };
+  return paginateResult(base, 'partners', { limit: opts.limit, offset: opts.offset });
 }
 
 /**
@@ -365,7 +367,8 @@ export function coChangeTopData(customDbPath, opts = {}) {
   const meta = getCoChangeMeta(db);
   closeDb(db);
 
-  return { pairs, meta };
+  const base = { pairs, meta };
+  return paginateResult(base, 'pairs', { limit: opts.limit, offset: opts.offset });
 }
 
 /**