@optave/codegraph 3.1.2 → 3.1.4

package/src/cli/commands/export.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs';
+import { openReadonlyOrFail } from '../../db.js';
+import {
+  exportDOT,
+  exportGraphML,
+  exportGraphSON,
+  exportJSON,
+  exportMermaid,
+  exportNeo4jCSV,
+} from '../../export.js';
+
+export const command = {
+  name: 'export',
+  description: 'Export dependency graph as DOT, Mermaid, JSON, GraphML, GraphSON, or Neo4j CSV',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-f, --format <format>', 'Output format: dot, mermaid, json, graphml, graphson, neo4j', 'dot'],
+    ['--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'],
+    ['--direction <dir>', 'Flowchart direction for Mermaid: TB, LR, RL, BT', 'LR'],
+    ['-o, --output <file>', 'Write to file instead of stdout'],
+  ],
+  execute(_args, opts, ctx) {
+    const db = openReadonlyOrFail(opts.db);
+    const exportOpts = {
+      fileLevel: !opts.functions,
+      noTests: ctx.resolveNoTests(opts),
+      minConfidence: parseFloat(opts.minConfidence),
+      direction: opts.direction,
+    };
+
+    let output;
+    switch (opts.format) {
+      case 'mermaid':
+        output = exportMermaid(db, exportOpts);
+        break;
+      case 'json':
+        output = JSON.stringify(exportJSON(db, exportOpts), null, 2);
+        break;
+      case 'graphml':
+        output = exportGraphML(db, exportOpts);
+        break;
+      case 'graphson':
+        output = JSON.stringify(exportGraphSON(db, exportOpts), null, 2);
+        break;
+      case 'neo4j': {
+        const csv = exportNeo4jCSV(db, exportOpts);
+        if (opts.output) {
+          const base = opts.output.replace(/\.[^.]+$/, '') || opts.output;
+          fs.writeFileSync(`${base}-nodes.csv`, csv.nodes, 'utf-8');
+          fs.writeFileSync(`${base}-relationships.csv`, csv.relationships, 'utf-8');
+          db.close();
+          console.log(`Exported to ${base}-nodes.csv and ${base}-relationships.csv`);
+          return;
+        }
+        output = `--- nodes.csv ---\n${csv.nodes}\n\n--- relationships.csv ---\n${csv.relationships}`;
+        break;
+      }
+      default:
+        output = exportDOT(db, exportOpts);
+        break;
+    }
+
+    db.close();
+
+    if (opts.output) {
+      fs.writeFileSync(opts.output, output, 'utf-8');
+      console.log(`Exported ${opts.format} to ${opts.output}`);
+    } else {
+      console.log(output);
+    }
+  },
+};

package/src/cli/commands/exports.js

@@ -0,0 +1,18 @@
+import { fileExports } from '../../queries-cli.js';
+
+export const command = {
+  name: 'exports <file>',
+  description: 'Show exported symbols with per-symbol consumers (who calls each export)',
+  queryOpts: true,
+  options: [['--unused', 'Show only exports with zero consumers (dead exports)']],
+  execute([file], opts, ctx) {
+    fileExports(file, opts.db, {
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      unused: opts.unused || false,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  },
+};

package/src/cli/commands/flow.js

@@ -0,0 +1,36 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+
+export const command = {
+  name: 'flow [name]',
+  description:
+    'Trace execution flow forward from an entry point (route, command, event) through callees to leaves',
+  queryOpts: true,
+  options: [
+    ['--list', 'List all entry points grouped by type'],
+    ['--depth <n>', 'Max forward traversal depth', '10'],
+    ['-f, --file <path>', 'Scope to a specific file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+  ],
+  validate([name], opts) {
+    if (!name && !opts.list) {
+      return 'Provide a function/entry point name or use --list to see all entry points.';
+    }
+    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 { flow } = await import('../../commands/flow.js');
+    flow(name, opts.db, {
+      list: opts.list,
+      depth: parseInt(opts.depth, 10),
+      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/fn-impact.js

@@ -0,0 +1,30 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+import { fnImpact } from '../../queries-cli.js';
+
+export const command = {
+  name: 'fn-impact <name>',
+  description: 'Function-level impact: what functions break if this one changes',
+  queryOpts: true,
+  options: [
+    ['--depth <n>', 'Max transitive depth', '5'],
+    ['-f, --file <path>', 'Scope search to functions in this file (partial match)'],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+  ],
+  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) {
+    fnImpact(name, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      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/impact.js

@@ -0,0 +1,16 @@
+import { impactAnalysis } from '../../queries-cli.js';
+
+export const command = {
+  name: 'impact <file>',
+  description: 'Show what depends on this file (transitive)',
+  queryOpts: true,
+  execute([file], opts, ctx) {
+    impactAnalysis(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/info.js

@@ -0,0 +1,76 @@
+export const command = {
+  name: 'info',
+  description: 'Show codegraph engine info and diagnostics',
+  async execute(_args, _opts, ctx) {
+    const { getNativePackageVersion, isNativeAvailable, loadNative } = await import(
+      '../../native.js'
+    );
+    const { getActiveEngine } = await import('../../parser.js');
+
+    const engine = ctx.program.opts().engine;
+    const { name: activeName, version: activeVersion } = getActiveEngine({ engine });
+    const nativeAvailable = isNativeAvailable();
+
+    console.log('\nCodegraph Diagnostics');
+    console.log('====================');
+    console.log(`  Version       : ${ctx.program.version()}`);
+    console.log(`  Node.js       : ${process.version}`);
+    console.log(`  Platform      : ${process.platform}-${process.arch}`);
+    console.log(`  Native engine : ${nativeAvailable ? 'available' : 'unavailable'}`);
+    if (nativeAvailable) {
+      const native = loadNative();
+      const binaryVersion =
+        typeof native.engineVersion === 'function' ? native.engineVersion() : 'unknown';
+      const pkgVersion = getNativePackageVersion();
+      const knownBinaryVersion = binaryVersion !== 'unknown' ? binaryVersion : null;
+      if (pkgVersion && knownBinaryVersion && pkgVersion !== knownBinaryVersion) {
+        console.log(
+          `  Native version: ${pkgVersion} (binary reports ${knownBinaryVersion} — stale)`,
+        );
+      } else {
+        console.log(`  Native version: ${pkgVersion ?? binaryVersion}`);
+      }
+    }
+    console.log(`  Engine flag   : --engine ${engine}`);
+    console.log(`  Active engine : ${activeName}${activeVersion ? ` (v${activeVersion})` : ''}`);
+    console.log();
+
+    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(
+            '\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500',
+          );
+          if (buildEngine) console.log(`  Engine        : ${buildEngine}`);
+          if (buildVersion) console.log(`  Version       : ${buildVersion}`);
+          if (builtAt) console.log(`  Built at      : ${builtAt}`);
+
+          if (buildVersion && buildVersion !== ctx.program.version()) {
+            console.log(
+              `  \u26A0 DB was built with v${buildVersion}, current is v${ctx.program.version()}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          if (buildEngine && buildEngine !== activeName) {
+            console.log(
+              `  \u26A0 DB was built with ${buildEngine} engine, active is ${activeName}. Consider: codegraph build --no-incremental`,
+            );
+          }
+          console.log();
+        }
+      }
+    } catch {
+      /* diagnostics must never crash */
+    }
+  },
+};

package/src/cli/commands/map.js

@@ -0,0 +1,19 @@
+import { moduleMap } from '../../queries-cli.js';
+
+export const command = {
+  name: 'map',
+  description: 'High-level module overview with most-connected nodes',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-n, --limit <number>', 'Number of top nodes', '20'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+  ],
+  execute(_args, opts, ctx) {
+    moduleMap(opts.db, parseInt(opts.limit, 10), {
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+    });
+  },
+};

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.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 '../../embeddings/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('../../commands/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 '../../queries.js';
+import { symbolPath } from '../../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,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { openReadonlyOrFail } from '../../db.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('../../viewer.js');
+    const os = await import('node:os');
+    const db = openReadonlyOrFail(opts.db);
+
+    let plotCfg;
+    if (opts.config) {
+      try {
+        plotCfg = JSON.parse(fs.readFileSync(opts.config, 'utf-8'));
+      } catch (e) {
+        console.error(`Failed to load config: ${e.message}`);
+        db.close();
+        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;
+    }
+
+    const html = generatePlotHTML(db, {
+      fileLevel: !opts.functions,
+      noTests: ctx.resolveNoTests(opts),
+      minConfidence: parseFloat(opts.minConfidence),
+      config: plotCfg,
+    });
+    db.close();
+
+    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,49 @@
+import { EVERY_SYMBOL_KIND } from '../../queries.js';
+import { fnDeps, symbolPath } from '../../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,
+        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/registry.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ConfigError } from '../../errors.js';
+import {
+  listRepos,
+  pruneRegistry,
+  REGISTRY_PATH,
+  registerRepo,
+  unregisterRepo,
+} from '../../registry.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,34 @@
+import { VALID_ROLES } from '../../queries.js';
+import { roles } from '../../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,
+      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,
+    });
+  },
+};