@optave/codegraph 3.1.3 → 3.1.5

package/src/cli/commands/mcp.js

@@ -0,0 +1,18 @@
+export const command = {
+  name: 'mcp',
+  description: 'Start MCP (Model Context Protocol) server for AI assistant integration',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--multi-repo', 'Enable access to all registered repositories'],
+    ['--repos <names>', 'Comma-separated list of allowed repo names (restricts access)'],
+  ],
+  async execute(_args, opts) {
+    const { startMCPServer } = await import('../../mcp/index.js');
+    const mcpOpts = {};
+    mcpOpts.multiRepo = opts.multiRepo || !!opts.repos;
+    if (opts.repos) {
+      mcpOpts.allowedRepos = opts.repos.split(',').map((s) => s.trim());
+    }
+    await startMCPServer(opts.db, mcpOpts);
+  },
+};

package/src/cli/commands/models.js

@@ -0,0 +1,19 @@
+import { DEFAULT_MODEL, MODELS } from '../../domain/search/index.js';
+
+export const command = {
+  name: 'models',
+  description: 'List available embedding models',
+  execute(_args, _opts, ctx) {
+    const defaultModel = ctx.config.embeddings?.model || DEFAULT_MODEL;
+    console.log('\nAvailable embedding models:\n');
+    for (const [key, cfg] of Object.entries(MODELS)) {
+      const def = key === defaultModel ? ' (default)' : '';
+      const ctxWindow = cfg.contextWindow ? `${cfg.contextWindow} ctx` : '';
+      console.log(
+        `  ${key.padEnd(12)} ${String(cfg.dim).padStart(4)}d  ${ctxWindow.padEnd(9)} ${cfg.desc}${def}`,
+      );
+    }
+    console.log('\nUsage: codegraph embed --model <name> --strategy <structured|source>');
+    console.log('       codegraph search "query" --model <name>\n');
+  },
+};

package/src/cli/commands/owners.js

@@ -0,0 +1,25 @@
+export const command = {
+  name: 'owners [target]',
+  description: 'Show CODEOWNERS mapping for files and functions',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--owner <owner>', 'Filter to a specific owner'],
+    ['--boundary', 'Show cross-owner boundary edges'],
+    ['-f, --file <path>', 'Scope to a specific file'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  async execute([target], opts, ctx) {
+    const { owners } = await import('../../presentation/owners.js');
+    owners(opts.db, {
+      owner: opts.owner,
+      boundary: opts.boundary,
+      file: opts.file || target,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+  },
+};

package/src/cli/commands/path.js

@@ -0,0 +1,36 @@
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { symbolPath } from '../../presentation/queries-cli.js';
+
+export const command = {
+  name: 'path <from> <to>',
+  description: 'Find shortest path between two symbols',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--reverse', 'Follow edges backward'],
+    ['--kinds <kinds>', 'Comma-separated edge kinds to follow (default: calls)'],
+    ['--from-file <path>', 'Disambiguate source symbol by file'],
+    ['--to-file <path>', 'Disambiguate target symbol by file'],
+    ['--depth <n>', 'Max traversal depth', '10'],
+    ['-k, --kind <kind>', 'Filter to a specific 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'],
+  ],
+  validate([_from, _to], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([from, to], opts, ctx) {
+    symbolPath(from, to, opts.db, {
+      maxDepth: opts.depth ? parseInt(opts.depth, 10) : 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: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+  },
+};

package/src/cli/commands/plot.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { openGraph } from '../shared/open-graph.js';
+
+export const command = {
+  name: 'plot',
+  description: 'Generate an interactive HTML dependency graph viewer',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--functions', 'Function-level graph instead of file-level'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['--min-confidence <score>', 'Minimum edge confidence threshold (default: 0.5)', '0.5'],
+    ['-o, --output <file>', 'Write HTML to file'],
+    ['-c, --config <path>', 'Path to .plotDotCfg config file'],
+    ['--no-open', 'Do not open in browser'],
+    ['--cluster <mode>', 'Cluster nodes: none | community | directory'],
+    ['--overlay <list>', 'Comma-separated overlays: complexity,risk'],
+    ['--seed <strategy>', 'Seed strategy: all | top-fanin | entry'],
+    ['--seed-count <n>', 'Number of seed nodes (default: 30)'],
+    ['--size-by <metric>', 'Size nodes by: uniform | fan-in | fan-out | complexity'],
+    ['--color-by <mode>', 'Color nodes by: kind | role | community | complexity'],
+  ],
+  async execute(_args, opts, ctx) {
+    const { generatePlotHTML, loadPlotConfig } = await import('../../features/graph-enrichment.js');
+    const os = await import('node:os');
+    const { db, close } = openGraph(opts);
+
+    let plotCfg;
+    let html;
+    try {
+      if (opts.config) {
+        try {
+          plotCfg = JSON.parse(fs.readFileSync(opts.config, 'utf-8'));
+        } catch (e) {
+          console.error(`Failed to load config: ${e.message}`);
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        plotCfg = loadPlotConfig(process.cwd());
+      }
+
+      if (opts.cluster) plotCfg.clusterBy = opts.cluster;
+      if (opts.colorBy) plotCfg.colorBy = opts.colorBy;
+      if (opts.sizeBy) plotCfg.sizeBy = opts.sizeBy;
+      if (opts.seed) plotCfg.seedStrategy = opts.seed;
+      if (opts.seedCount) plotCfg.seedCount = parseInt(opts.seedCount, 10);
+      if (opts.overlay) {
+        const parts = opts.overlay.split(',').map((s) => s.trim());
+        if (!plotCfg.overlays) plotCfg.overlays = {};
+        if (parts.includes('complexity')) plotCfg.overlays.complexity = true;
+        if (parts.includes('risk')) plotCfg.overlays.risk = true;
+      }
+
+      html = generatePlotHTML(db, {
+        fileLevel: !opts.functions,
+        noTests: ctx.resolveNoTests(opts),
+        minConfidence: parseFloat(opts.minConfidence),
+        config: plotCfg,
+      });
+    } finally {
+      close();
+    }
+
+    if (!html) {
+      console.error('generatePlotHTML returned no output');
+      process.exitCode = 1;
+      return;
+    }
+
+    const outPath = opts.output || path.join(os.tmpdir(), `codegraph-plot-${Date.now()}.html`);
+    fs.writeFileSync(outPath, html, 'utf-8');
+    console.log(`Plot written to ${outPath}`);
+
+    if (opts.open !== false) {
+      const { execFile } = await import('node:child_process');
+      const args =
+        process.platform === 'win32'
+          ? ['cmd', ['/c', 'start', '', outPath]]
+          : process.platform === 'darwin'
+            ? ['open', [outPath]]
+            : ['xdg-open', [outPath]];
+      execFile(args[0], args[1], (err) => {
+        if (err) console.error('Could not open browser:', err.message);
+      });
+    }
+  },
+};

package/src/cli/commands/query.js

@@ -0,0 +1,45 @@
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { fnDeps, symbolPath } from '../../presentation/queries-cli.js';
+
+export const command = {
+  name: 'query <name>',
+  description: 'Function-level dependency chain or shortest path between symbols',
+  queryOpts: true,
+  options: [
+    ['--depth <n>', 'Transitive caller depth', '3'],
+    ['-f, --file <path>', 'Scope search to functions in this file (partial match)'],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['--path <to>', 'Path mode: find shortest path to <to>'],
+    ['--kinds <kinds>', 'Path mode: comma-separated edge kinds to follow (default: calls)'],
+    ['--reverse', 'Path mode: follow edges backward'],
+    ['--from-file <path>', 'Path mode: disambiguate source symbol by file'],
+    ['--to-file <path>', 'Path mode: disambiguate target symbol by file'],
+  ],
+  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) {
+    if (opts.path) {
+      console.error('Note: "query --path" is deprecated, use "codegraph path <from> <to>" instead');
+      symbolPath(name, opts.path, opts.db, {
+        maxDepth: opts.depth ? parseInt(opts.depth, 10) : 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: ctx.resolveNoTests(opts),
+        json: opts.json,
+      });
+    } else {
+      fnDeps(name, opts.db, {
+        depth: parseInt(opts.depth, 10),
+        file: opts.file,
+        kind: opts.kind,
+        ...ctx.resolveQueryOpts(opts),
+      });
+    }
+  },
+};

package/src/cli/commands/registry.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  listRepos,
+  pruneRegistry,
+  REGISTRY_PATH,
+  registerRepo,
+  unregisterRepo,
+} from '../../infrastructure/registry.js';
+import { ConfigError } from '../../shared/errors.js';
+
+export const command = {
+  name: 'registry',
+  description: 'Manage the multi-repo project registry',
+  subcommands: [
+    {
+      name: 'list',
+      description: 'List all registered repositories',
+      options: [['-j, --json', 'Output as JSON']],
+      execute(_args, opts) {
+        pruneRegistry();
+        const repos = listRepos();
+        if (opts.json) {
+          console.log(JSON.stringify(repos, null, 2));
+        } else if (repos.length === 0) {
+          console.log(`No repositories registered.\nRegistry: ${REGISTRY_PATH}`);
+        } else {
+          console.log(`Registered repositories (${REGISTRY_PATH}):\n`);
+          for (const r of repos) {
+            const dbExists = fs.existsSync(r.dbPath);
+            const status = dbExists ? '' : ' [DB missing]';
+            console.log(`  ${r.name}${status}`);
+            console.log(`    Path: ${r.path}`);
+            console.log(`    DB:   ${r.dbPath}`);
+            console.log();
+          }
+        }
+      },
+    },
+    {
+      name: 'add <dir>',
+      description: 'Register a project directory',
+      options: [['-n, --name <name>', 'Custom name (defaults to directory basename)']],
+      execute([dir], opts) {
+        const absDir = path.resolve(dir);
+        const { name, entry } = registerRepo(absDir, opts.name);
+        console.log(`Registered "${name}" → ${entry.path}`);
+      },
+    },
+    {
+      name: 'remove <name>',
+      description: 'Unregister a repository by name',
+      execute([name]) {
+        const removed = unregisterRepo(name);
+        if (removed) {
+          console.log(`Removed "${name}" from registry.`);
+        } else {
+          throw new ConfigError(`Repository "${name}" not found in registry.`);
+        }
+      },
+    },
+    {
+      name: 'prune',
+      description: 'Remove stale registry entries (missing directories or idle beyond TTL)',
+      options: [
+        ['--ttl <days>', 'Days of inactivity before pruning (default: 30)', '30'],
+        ['--exclude <names>', 'Comma-separated repo names to preserve from pruning'],
+        ['--dry-run', 'Show what would be pruned without removing anything'],
+      ],
+      execute(_args, opts) {
+        const excludeNames = opts.exclude
+          ? opts.exclude
+              .split(',')
+              .map((s) => s.trim())
+              .filter((s) => s.length > 0)
+          : [];
+        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(`${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'}.`,
+            );
+          }
+        }
+      },
+    },
+  ],
+};

package/src/cli/commands/roles.js

@@ -0,0 +1,30 @@
+import { VALID_ROLES } from '../../domain/queries.js';
+import { roles } from '../../presentation/queries-cli.js';
+
+export const command = {
+  name: 'roles',
+  description: 'Show node role classification: entry, core, utility, adapter, dead, leaf',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--role <role>', `Filter by role (${VALID_ROLES.join(', ')})`],
+    ['-f, --file <path>', 'Scope to a specific file (partial match)'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+  ],
+  validate(_args, opts) {
+    if (opts.role && !VALID_ROLES.includes(opts.role)) {
+      return `Invalid role "${opts.role}". Valid roles: ${VALID_ROLES.join(', ')}`;
+    }
+  },
+  execute(_args, opts, ctx) {
+    roles(opts.db, {
+      role: opts.role,
+      file: opts.file,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/search.js

@@ -0,0 +1,42 @@
+import { search } from '../../domain/search/index.js';
+
+export const command = {
+  name: 'search <query>',
+  description: 'Semantic search: find functions by natural language description',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-m, --model <name>', 'Override embedding model (auto-detects from DB)'],
+    ['-n, --limit <number>', 'Max results', '15'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['--min-score <score>', 'Minimum similarity threshold', '0.2'],
+    ['-k, --kind <kind>', 'Filter by kind: function, method, class'],
+    ['--file <pattern>', 'Filter by file path pattern'],
+    ['--rrf-k <number>', 'RRF k parameter for multi-query ranking', '60'],
+    ['--mode <mode>', 'Search mode: hybrid, semantic, keyword (default: hybrid)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+  ],
+  validate([_query], opts) {
+    const validModes = ['hybrid', 'semantic', 'keyword'];
+    if (opts.mode && !validModes.includes(opts.mode)) {
+      return `Invalid mode "${opts.mode}". Valid: ${validModes.join(', ')}`;
+    }
+  },
+  async execute([query], opts, ctx) {
+    await search(query, opts.db, {
+      limit: parseInt(opts.limit, 10),
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      noTests: ctx.resolveNoTests(opts),
+      minScore: parseFloat(opts.minScore),
+      model: opts.model,
+      kind: opts.kind,
+      filePattern: opts.file,
+      rrfK: parseInt(opts.rrfK, 10),
+      mode: opts.mode,
+      json: opts.json,
+      ndjson: opts.ndjson,
+    });
+  },
+};

package/src/cli/commands/sequence.js

@@ -0,0 +1,28 @@
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+
+export const command = {
+  name: 'sequence <name>',
+  description: 'Generate a Mermaid sequence diagram from call graph edges (participants = files)',
+  queryOpts: true,
+  options: [
+    ['--depth <n>', 'Max forward traversal depth', '10'],
+    ['--dataflow', 'Annotate with parameter names and return arrows from dataflow table'],
+    ['-f, --file <path>', 'Scope to a specific 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 { sequence } = await import('../../presentation/sequence.js');
+    sequence(name, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      dataflow: opts.dataflow,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/snapshot.js

@@ -0,0 +1,66 @@
+import {
+  snapshotDelete,
+  snapshotList,
+  snapshotRestore,
+  snapshotSave,
+} from '../../features/snapshot.js';
+
+export const command = {
+  name: 'snapshot',
+  description: 'Save and restore graph database snapshots',
+  subcommands: [
+    {
+      name: 'save <name>',
+      description: 'Save a snapshot of the current graph database',
+      options: [
+        ['-d, --db <path>', 'Path to graph.db'],
+        ['--force', 'Overwrite existing snapshot'],
+      ],
+      execute([name], opts, ctx) {
+        const result = snapshotSave(name, { dbPath: opts.db, force: opts.force });
+        console.log(`Snapshot saved: ${result.name} (${ctx.formatSize(result.size)})`);
+      },
+    },
+    {
+      name: 'restore <name>',
+      description: 'Restore a snapshot over the current graph database',
+      options: [['-d, --db <path>', 'Path to graph.db']],
+      execute([name], opts) {
+        snapshotRestore(name, { dbPath: opts.db });
+        console.log(`Snapshot "${name}" restored.`);
+      },
+    },
+    {
+      name: 'list',
+      description: 'List all saved snapshots',
+      options: [
+        ['-d, --db <path>', 'Path to graph.db'],
+        ['-j, --json', 'Output as JSON'],
+      ],
+      execute(_args, opts, ctx) {
+        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)} ${ctx.formatSize(s.size).padStart(10)}  ${s.createdAt.toISOString()}`,
+            );
+          }
+        }
+      },
+    },
+    {
+      name: 'delete <name>',
+      description: 'Delete a saved snapshot',
+      options: [['-d, --db <path>', 'Path to graph.db']],
+      execute([name], opts) {
+        snapshotDelete(name, { dbPath: opts.db });
+        console.log(`Snapshot "${name}" deleted.`);
+      },
+    },
+  ],
+};

package/src/cli/commands/stats.js

@@ -0,0 +1,15 @@
+import { stats } from '../../presentation/queries-cli.js';
+
+export const command = {
+  name: 'stats',
+  description: 'Show graph health overview: nodes, edges, languages, cycles, hotspots, embeddings',
+  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)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  async execute(_args, opts, ctx) {
+    await stats(opts.db, { noTests: ctx.resolveNoTests(opts), json: opts.json });
+  },
+};

package/src/cli/commands/structure.js

@@ -0,0 +1,33 @@
+export const command = {
+  name: 'structure [dir]',
+  description:
+    'Show project directory structure with hierarchy, cohesion scores, and per-file metrics',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--depth <n>', 'Max directory depth'],
+    ['--sort <metric>', 'Sort by: cohesion | fan-in | fan-out | density | files', 'files'],
+    ['--full', 'Show all files without limit'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+  ],
+  async execute([dir], opts, ctx) {
+    const { structureData, formatStructure } = await import('../../presentation/structure.js');
+    const qOpts = ctx.resolveQueryOpts(opts);
+    const data = structureData(opts.db, {
+      directory: dir,
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      sort: opts.sort,
+      full: opts.full,
+      noTests: qOpts.noTests,
+      limit: qOpts.limit,
+      offset: qOpts.offset,
+    });
+    if (!ctx.outputResult(data, 'directories', opts)) {
+      console.log(formatStructure(data));
+    }
+  },
+};

package/src/cli/commands/triage.js

@@ -0,0 +1,78 @@
+import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../domain/queries.js';
+import { ConfigError } from '../../shared/errors.js';
+
+export const command = {
+  name: 'triage',
+  description:
+    'Ranked audit queue by composite risk score (connectivity + complexity + churn + role)',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-n, --limit <number>', 'Max results to return', '20'],
+    [
+      '--level <level>',
+      'Granularity: function (default) | file | directory. File/directory level shows hotspots',
+      'function',
+    ],
+    [
+      '--sort <metric>',
+      'Sort metric: risk | complexity | churn | fan-in | mi (function level); fan-in | fan-out | density | coupling (file/directory level)',
+      'risk',
+    ],
+    ['--min-score <score>', 'Only show symbols with risk score >= threshold'],
+    ['--role <role>', 'Filter by role (entry, core, utility, adapter, leaf, dead)'],
+    ['-f, --file <path>', 'Scope to a specific file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind (function, method, class)'],
+    ['-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'],
+    ['--weights <json>', 'Custom weights JSON (e.g. \'{"fanIn":1,"complexity":0}\')'],
+  ],
+  async execute(_args, opts, ctx) {
+    if (opts.level === 'file' || opts.level === 'directory') {
+      const { hotspotsData, formatHotspots } = await import('../../presentation/structure.js');
+      const metric = opts.sort === 'risk' ? 'fan-in' : opts.sort;
+      const data = hotspotsData(opts.db, {
+        metric,
+        level: opts.level,
+        limit: parseInt(opts.limit, 10),
+        offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+        noTests: ctx.resolveNoTests(opts),
+      });
+      if (!ctx.outputResult(data, 'hotspots', opts)) {
+        console.log(formatHotspots(data));
+      }
+      return;
+    }
+
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      throw new ConfigError(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+    }
+    if (opts.role && !VALID_ROLES.includes(opts.role)) {
+      throw new ConfigError(`Invalid role "${opts.role}". Valid: ${VALID_ROLES.join(', ')}`);
+    }
+    let weights;
+    if (opts.weights) {
+      try {
+        weights = JSON.parse(opts.weights);
+      } catch (err) {
+        throw new ConfigError('Invalid --weights JSON', { cause: err });
+      }
+    }
+    const { triage } = await import('../../presentation/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: ctx.resolveNoTests(opts),
+      json: opts.json,
+      ndjson: opts.ndjson,
+      weights,
+    });
+  },
+};

package/src/cli/commands/watch.js

@@ -0,0 +1,12 @@
+import path from 'node:path';
+import { watchProject } from '../../domain/graph/watcher.js';
+
+export const command = {
+  name: 'watch [dir]',
+  description: 'Watch project for file changes and incrementally update the graph',
+  async execute([dir], _opts, ctx) {
+    const root = path.resolve(dir || '.');
+    const engine = ctx.program.opts().engine;
+    await watchProject(root, { engine });
+  },
+};

package/src/cli/commands/where.js

@@ -0,0 +1,20 @@
+import { where } from '../../presentation/queries-cli.js';
+
+export const command = {
+  name: 'where [name]',
+  description: 'Find where a symbol is defined and used (minimal, fast lookup)',
+  queryOpts: true,
+  options: [['-f, --file <path>', 'File overview: list symbols, imports, exports']],
+  validate([name], opts) {
+    if (!name && !opts.file) {
+      return 'Provide a symbol name or use --file <path>';
+    }
+  },
+  execute([name], opts, ctx) {
+    const target = opts.file || name;
+    where(target, opts.db, {
+      file: !!opts.file,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};