@optave/codegraph 3.1.3 → 3.1.4

package/src/cfg.js

@@ -28,8 +28,7 @@ import { info } from './logger.js';
 import { paginateResult } from './paginate.js';
 
 // Re-export for backward compatibility
-export { CFG_RULES };
-export { _makeCfgRules as makeCfgRules };
+export { _makeCfgRules as makeCfgRules, CFG_RULES };
 
 const CFG_EXTENSIONS = buildExtensionSet(CFG_RULES);
 

package/src/cli/commands/ast.js

@@ -0,0 +1,26 @@
+import { ConfigError } from '../../errors.js';
+
+export const command = {
+  name: 'ast [pattern]',
+  description: 'Search stored AST nodes (calls, new, string, regex, throw, await) by pattern',
+  queryOpts: true,
+  options: [
+    ['-k, --kind <kind>', 'Filter by AST node kind (call, new, string, regex, throw, await)'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+  ],
+  async execute([pattern], opts, ctx) {
+    const { AST_NODE_KINDS, astQuery } = await import('../../ast.js');
+    if (opts.kind && !AST_NODE_KINDS.includes(opts.kind)) {
+      throw new ConfigError(`Invalid AST kind "${opts.kind}". Valid: ${AST_NODE_KINDS.join(', ')}`);
+    }
+    astQuery(pattern, opts.db, {
+      kind: opts.kind,
+      file: opts.file,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    });
+  },
+};

package/src/cli/commands/audit.js

@@ -0,0 +1,46 @@
+import { audit } from '../../commands/audit.js';
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+import { explain } from '../../queries-cli.js';
+
+export const command = {
+  name: 'audit <target>',
+  description: 'Composite report: explain + impact + health metrics per function',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--quick', 'Structural summary only (skip impact analysis and health metrics)'],
+    ['--depth <n>', 'Impact/explain depth', '3'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--limit <number>', 'Max results to return (quick mode)'],
+    ['--offset <number>', 'Skip N results (quick mode)'],
+    ['--ndjson', 'Newline-delimited JSON output (quick mode)'],
+  ],
+  validate([_target], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([target], opts, ctx) {
+    if (opts.quick) {
+      explain(target, opts.db, {
+        depth: parseInt(opts.depth, 10),
+        noTests: ctx.resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+      return;
+    }
+    audit(target, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+  },
+};

package/src/cli/commands/batch.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import { BATCH_COMMANDS, multiBatchData, splitTargets } from '../../batch.js';
+import { batch } from '../../commands/batch.js';
+import { ConfigError } from '../../errors.js';
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+
+export const command = {
+  name: 'batch <command> [targets...]',
+  description: `Run a query against multiple targets in one call. Output is always JSON.\nValid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--from-file <path>', 'Read targets from file (JSON array or newline-delimited)'],
+    ['--stdin', 'Read targets from stdin (JSON array)'],
+    ['--depth <n>', 'Traversal depth passed to underlying command'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+  ],
+  validate([_command, _targets], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([command, positionalTargets], opts, ctx) {
+    let targets;
+    try {
+      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 = splitTargets(positionalTargets);
+      }
+    } catch (err) {
+      throw new ConfigError(`Failed to parse targets: ${err.message}`, { cause: err });
+    }
+
+    if (!targets || targets.length === 0) {
+      throw new ConfigError(
+        'No targets provided. Pass targets as arguments, --from-file, or --stdin.',
+      );
+    }
+
+    const batchOpts = {
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+    };
+
+    const isMulti = targets.length > 0 && typeof targets[0] === 'object' && targets[0].command;
+    if (isMulti) {
+      const data = multiBatchData(targets, opts.db, batchOpts);
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      batch(command, targets, opts.db, batchOpts);
+    }
+  },
+};

package/src/cli/commands/branch-compare.js

@@ -0,0 +1,21 @@
+export const command = {
+  name: 'branch-compare <base> <target>',
+  description: 'Compare code structure between two branches/refs',
+  options: [
+    ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['-f, --format <format>', 'Output format: text, mermaid, json', 'text'],
+  ],
+  async execute([base, target], opts, ctx) {
+    const { branchCompare } = await import('../../commands/branch-compare.js');
+    await branchCompare(base, target, {
+      engine: ctx.program.opts().engine,
+      depth: parseInt(opts.depth, 10),
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      format: opts.format,
+    });
+  },
+};

package/src/cli/commands/build.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { buildGraph } from '../../builder.js';
+
+export const command = {
+  name: 'build [dir]',
+  description: 'Parse repo and build graph in .codegraph/graph.db',
+  options: [
+    ['--no-incremental', 'Force full rebuild (ignore file hashes)'],
+    ['--no-ast', 'Skip AST node extraction (calls, new, string, regex, throw, await)'],
+    ['--no-complexity', 'Skip complexity metrics computation'],
+    ['--no-dataflow', 'Skip data flow edge extraction'],
+    ['--no-cfg', 'Skip control flow graph building'],
+  ],
+  async execute([dir], opts, ctx) {
+    const root = path.resolve(dir || '.');
+    const engine = ctx.program.opts().engine;
+    await buildGraph(root, {
+      incremental: opts.incremental,
+      ast: opts.ast,
+      complexity: opts.complexity,
+      engine,
+      dataflow: opts.dataflow,
+      cfg: opts.cfg,
+    });
+  },
+};

package/src/cli/commands/cfg.js

@@ -0,0 +1,30 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+
+export const command = {
+  name: 'cfg <name>',
+  description: 'Show control flow graph for a function',
+  queryOpts: true,
+  options: [
+    ['--format <fmt>', 'Output format: text, dot, mermaid', 'text'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([name], opts, ctx) {
+    const { cfg } = await import('../../commands/cfg.js');
+    cfg(name, opts.db, {
+      format: opts.format,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    });
+  },
+};

package/src/cli/commands/check.js

@@ -0,0 +1,79 @@
+import { ConfigError } from '../../errors.js';
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+
+export const command = {
+  name: 'check [ref]',
+  description:
+    'CI gate: run manifesto rules (no args), diff predicates (with ref/--staged), or both (--rules)',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--staged', 'Analyze staged changes'],
+    ['--rules', 'Also run manifesto rules alongside diff predicates'],
+    ['--cycles', 'Assert no dependency cycles involve changed files'],
+    ['--blast-radius <n>', 'Assert no function exceeds N transitive callers'],
+    ['--signatures', 'Assert no function declaration lines were modified'],
+    ['--boundaries', 'Assert no cross-owner boundary violations'],
+    ['--depth <n>', 'Max BFS depth for blast radius (default: 3)'],
+    ['-f, --file <path>', 'Scope to file (partial match, manifesto mode)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind (manifesto mode)'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--limit <number>', 'Max results to return (manifesto mode)'],
+    ['--offset <number>', 'Skip N results (manifesto mode)'],
+    ['--ndjson', 'Newline-delimited JSON output (manifesto mode)'],
+  ],
+  async execute([ref], opts, ctx) {
+    const isDiffMode = ref || opts.staged;
+
+    if (!isDiffMode && !opts.rules) {
+      if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+        throw new ConfigError(
+          `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`,
+        );
+      }
+      const { manifesto } = await import('../../commands/manifesto.js');
+      manifesto(opts.db, {
+        file: opts.file,
+        kind: opts.kind,
+        noTests: ctx.resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+      return;
+    }
+
+    const { check } = await import('../../commands/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: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+
+    if (opts.rules) {
+      if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+        throw new ConfigError(
+          `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`,
+        );
+      }
+      const { manifesto } = await import('../../commands/manifesto.js');
+      manifesto(opts.db, {
+        file: opts.file,
+        kind: opts.kind,
+        noTests: ctx.resolveNoTests(opts),
+        json: opts.json,
+        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        ndjson: opts.ndjson,
+      });
+    }
+  },
+};

package/src/cli/commands/children.js

@@ -0,0 +1,31 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+import { children } from '../../queries-cli.js';
+
+export const command = {
+  name: 'children <name>',
+  description: 'List parameters, properties, and constants of a symbol',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-f, --file <path>', 'Scope search to symbols in this file (partial match)'],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['-j, --json', 'Output as JSON'],
+    ['--limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    children(name, opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    });
+  },
+};

package/src/cli/commands/co-change.js

@@ -0,0 +1,65 @@
+import { AnalysisError } from '../../errors.js';
+
+export const command = {
+  name: 'co-change [file]',
+  description:
+    'Analyze git history for files that change together. Use --analyze to scan, or query existing data.',
+  options: [
+    ['--analyze', 'Scan git history and populate co-change data'],
+    ['--since <date>', 'Git date for history window (default: "1 year ago")'],
+    ['--min-support <n>', 'Minimum co-occurrence count (default: 3)'],
+    ['--min-jaccard <n>', 'Minimum Jaccard similarity 0-1 (default: 0.3)'],
+    ['--full', 'Force full re-scan (ignore incremental state)'],
+    ['-n, --limit <n>', 'Max results', '20'],
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+  ],
+  async execute([file], opts, ctx) {
+    const { analyzeCoChanges, coChangeData, coChangeTopData } = await import('../../cochange.js');
+    const { formatCoChange, formatCoChangeTop } = await import('../../commands/cochange.js');
+
+    if (opts.analyze) {
+      const result = analyzeCoChanges(opts.db, {
+        since: opts.since || ctx.config.coChange?.since,
+        minSupport: opts.minSupport
+          ? parseInt(opts.minSupport, 10)
+          : ctx.config.coChange?.minSupport,
+        maxFilesPerCommit: ctx.config.coChange?.maxFilesPerCommit,
+        full: opts.full,
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (result.error) {
+        throw new AnalysisError(result.error);
+      } else {
+        console.log(
+          `\nCo-change analysis complete: ${result.pairsFound} pairs from ${result.commitsScanned} commits (since: ${result.since})\n`,
+        );
+      }
+      return;
+    }
+
+    const queryOpts = {
+      limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      minJaccard: opts.minJaccard ? parseFloat(opts.minJaccard) : ctx.config.coChange?.minJaccard,
+      noTests: ctx.resolveNoTests(opts),
+    };
+
+    if (file) {
+      const data = coChangeData(file, opts.db, queryOpts);
+      if (!ctx.outputResult(data, 'partners', opts)) {
+        console.log(formatCoChange(data));
+      }
+    } else {
+      const data = coChangeTopData(opts.db, queryOpts);
+      if (!ctx.outputResult(data, 'pairs', opts)) {
+        console.log(formatCoChangeTop(data));
+      }
+    }
+  },
+};

package/src/cli/commands/communities.js

@@ -0,0 +1,23 @@
+export const command = {
+  name: 'communities',
+  description: 'Detect natural module boundaries using Louvain community detection',
+  queryOpts: true,
+  options: [
+    ['--functions', 'Function-level instead of file-level'],
+    ['--resolution <n>', 'Louvain resolution parameter (default 1.0)', '1.0'],
+    ['--drift', 'Show only drift analysis'],
+  ],
+  async execute(_args, opts, ctx) {
+    const { communities } = await import('../../commands/communities.js');
+    communities(opts.db, {
+      functions: opts.functions,
+      resolution: parseFloat(opts.resolution),
+      drift: opts.drift,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  },
+};

package/src/cli/commands/complexity.js

@@ -0,0 +1,45 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+
+export const command = {
+  name: 'complexity [target]',
+  description: 'Show per-function complexity metrics (cognitive, cyclomatic, nesting depth, MI)',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-n, --limit <number>', 'Max results', '20'],
+    [
+      '--sort <metric>',
+      'Sort by: cognitive | cyclomatic | nesting | mi | volume | effort | bugs | loc',
+      'cognitive',
+    ],
+    ['--above-threshold', 'Only functions exceeding warn thresholds'],
+    ['--health', 'Show health metrics (Halstead, MI) columns'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+  ],
+  validate([_target], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([target], opts, ctx) {
+    const { complexity } = await import('../../commands/complexity.js');
+    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,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+    });
+  },
+};

package/src/cli/commands/context.js

@@ -0,0 +1,34 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+import { context } from '../../queries-cli.js';
+
+export const command = {
+  name: 'context <name>',
+  description: 'Full context for a function: source, deps, callers, tests, signature',
+  queryOpts: true,
+  options: [
+    ['--depth <n>', 'Include callee source up to N levels deep', '0'],
+    ['-f, --file <path>', 'Scope search to functions in this file (partial match)'],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['--no-source', 'Metadata only (skip source extraction)'],
+    ['--with-test-source', 'Include test source code'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    context(name, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      noSource: !opts.source,
+      noTests: ctx.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,
+    });
+  },
+};

package/src/cli/commands/cycles.js

@@ -0,0 +1,28 @@
+import { findCycles, formatCycles } from '../../cycles.js';
+import { openReadonlyOrFail } from '../../db.js';
+
+export const command = {
+  name: 'cycles',
+  description: 'Detect circular dependencies in the codebase',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--functions', 'Function-level cycle detection'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  execute(_args, opts, ctx) {
+    const db = openReadonlyOrFail(opts.db);
+    const cycles = findCycles(db, {
+      fileLevel: !opts.functions,
+      noTests: ctx.resolveNoTests(opts),
+    });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ cycles, count: cycles.length }, null, 2));
+    } else {
+      console.log(formatCycles(cycles));
+    }
+  },
+};

package/src/cli/commands/dataflow.js

@@ -0,0 +1,32 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+
+export const command = {
+  name: 'dataflow <name>',
+  description: 'Show data flow for a function: parameters, return consumers, mutations',
+  queryOpts: true,
+  options: [
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['--impact', 'Show data-dependent blast radius'],
+    ['--depth <n>', 'Max traversal depth', '5'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([name], opts, ctx) {
+    const { dataflow } = await import('../../commands/dataflow.js');
+    dataflow(name, opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      impact: opts.impact,
+      depth: parseInt(opts.depth, 10),
+    });
+  },
+};

package/src/cli/commands/deps.js

@@ -0,0 +1,16 @@
+import { fileDeps } from '../../queries-cli.js';
+
+export const command = {
+  name: 'deps <file>',
+  description: 'Show what this file imports and what imports it',
+  queryOpts: true,
+  execute([file], opts, ctx) {
+    fileDeps(file, opts.db, {
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  },
+};

package/src/cli/commands/diff-impact.js

@@ -0,0 +1,30 @@
+import { diffImpact } from '../../queries-cli.js';
+
+export const command = {
+  name: 'diff-impact [ref]',
+  description: 'Show impact of git changes (unstaged, staged, or vs a ref)',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['--limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+    ['--staged', 'Analyze staged changes instead of unstaged'],
+    ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-f, --format <format>', 'Output format: text, mermaid, json', 'text'],
+  ],
+  execute([ref], opts, ctx) {
+    diffImpact(opts.db, {
+      ref,
+      staged: opts.staged,
+      depth: parseInt(opts.depth, 10),
+      noTests: ctx.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,
+    });
+  },
+};

package/src/cli/commands/embed.js

@@ -0,0 +1,30 @@
+import path from 'node:path';
+import { buildEmbeddings, DEFAULT_MODEL, EMBEDDING_STRATEGIES } from '../../embeddings/index.js';
+
+export const command = {
+  name: 'embed [dir]',
+  description:
+    'Build semantic embeddings for all functions/methods/classes (requires prior `build`)',
+  options: [
+    [
+      '-m, --model <name>',
+      'Embedding model (default from config or minilm). Run `codegraph models` for details',
+    ],
+    [
+      '-s, --strategy <name>',
+      `Embedding strategy: ${EMBEDDING_STRATEGIES.join(', ')}. "structured" uses graph context (callers/callees), "source" embeds raw code`,
+      'structured',
+    ],
+    ['-d, --db <path>', 'Path to graph.db'],
+  ],
+  validate([_dir], opts) {
+    if (!EMBEDDING_STRATEGIES.includes(opts.strategy)) {
+      return `Unknown strategy: ${opts.strategy}. Available: ${EMBEDDING_STRATEGIES.join(', ')}`;
+    }
+  },
+  async execute([dir], opts, ctx) {
+    const root = path.resolve(dir || '.');
+    const model = opts.model || ctx.config.embeddings?.model || DEFAULT_MODEL;
+    await buildEmbeddings(root, model, opts.db, { strategy: opts.strategy });
+  },
+};