@optave/codegraph 3.1.2 → 3.1.4

package/src/cli/commands/search.js

@@ -0,0 +1,42 @@
+import { search } from '../../embeddings/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,32 @@
+import { EVERY_SYMBOL_KIND } from '../../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('../../commands/sequence.js');
+    sequence(name, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      dataflow: opts.dataflow,
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+      ndjson: opts.ndjson,
+    });
+  },
+};

package/src/cli/commands/snapshot.js

@@ -0,0 +1,61 @@
+import { snapshotDelete, snapshotList, snapshotRestore, snapshotSave } from '../../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 '../../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,32 @@
+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('../../commands/structure.js');
+    const data = structureData(opts.db, {
+      directory: dir,
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      sort: opts.sort,
+      full: opts.full,
+      noTests: ctx.resolveNoTests(opts),
+      limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+      offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+    });
+    if (!ctx.outputResult(data, 'directories', opts)) {
+      console.log(formatStructure(data));
+    }
+  },
+};

package/src/cli/commands/triage.js

@@ -0,0 +1,78 @@
+import { ConfigError } from '../../errors.js';
+import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../queries.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('../../commands/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('../../commands/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 '../../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,24 @@
+import { where } from '../../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,
+      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/index.js

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { ConfigError } from '../errors.js';
+import { setVerbose } from '../logger.js';
+import { checkForUpdates, printUpdateNotification } from '../update-check.js';
+import { applyQueryOpts, config, formatSize, resolveNoTests } from './shared/options.js';
+import { outputResult } from './shared/output.js';
+
+const __cliDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
+const pkg = JSON.parse(fs.readFileSync(path.join(__cliDir, '..', '..', 'package.json'), 'utf-8'));
+
+const program = new Command();
+program
+  .name('codegraph')
+  .description('Local code dependency graph tool')
+  .version(pkg.version)
+  .option('-v, --verbose', 'Enable verbose/debug output')
+  .option('--engine <engine>', 'Parser engine: native, wasm, or auto (default: auto)', 'auto')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) setVerbose(true);
+  })
+  .hook('postAction', async (_thisCommand, actionCommand) => {
+    const name = actionCommand.name();
+    if (name === 'mcp' || name === 'watch') return;
+    if (actionCommand.opts().json) return;
+    try {
+      const result = await checkForUpdates(pkg.version);
+      if (result) printUpdateNotification(result.current, result.latest);
+    } catch {
+      /* never break CLI */
+    }
+  });
+
+/** Shared context passed to every command's execute(). */
+const ctx = { config, resolveNoTests, formatSize, outputResult, program };
+
+/**
+ * Register a command definition onto a Commander parent.
+ *
+ * Command shape:
+ *   { name, description, queryOpts?, options?, validate?, execute(args, opts, ctx), subcommands? }
+ *
+ * - `name` includes positional args, e.g. 'build [dir]' or 'path <from> <to>'
+ * - `queryOpts` (boolean) — if true, attaches shared query options
+ * - `options` — array of arrays passed to cmd.option(), e.g. [['--depth <n>', 'Max depth', '3']]
+ * - `validate(args, opts, ctx)` — return an error string to abort, or falsy to proceed
+ * - `execute(args, opts, ctx)` — the action handler
+ * - `subcommands` — nested command definitions (for groups like registry, snapshot)
+ */
+function registerCommand(parent, def) {
+  const cmd = parent.command(def.name).description(def.description);
+
+  if (def.queryOpts) applyQueryOpts(cmd);
+
+  for (const opt of def.options || []) {
+    cmd.option(...opt);
+  }
+
+  if (def.execute) {
+    const argCount = (def.name.match(/<[^>]+>|\[[^\]]+\]/g) || []).length;
+
+    cmd.action((...actionArgs) => {
+      const args = actionArgs.slice(0, argCount);
+      const opts = actionArgs[argCount];
+
+      if (def.validate) {
+        const err = def.validate(args, opts, ctx);
+        if (err) {
+          throw new ConfigError(err);
+        }
+      }
+
+      return def.execute(args, opts, ctx);
+    });
+  }
+
+  if (def.subcommands) {
+    for (const sub of def.subcommands) {
+      registerCommand(cmd, sub);
+    }
+  }
+
+  return cmd;
+}
+
+/**
+ * Auto-discover and register all command modules from src/cli/commands/.
+ * Each module must export a `command` (single definition) or `commands` (array).
+ */
+async function discoverCommands() {
+  const commandsDir = path.join(__cliDir, 'commands');
+  const files = fs
+    .readdirSync(commandsDir)
+    .filter((f) => f.endsWith('.js'))
+    .sort();
+
+  for (const file of files) {
+    const mod = await import(pathToFileURL(path.join(commandsDir, file)).href);
+    if (mod.command) {
+      registerCommand(program, mod.command);
+    }
+    if (mod.commands) {
+      for (const def of mod.commands) {
+        registerCommand(program, def);
+      }
+    }
+  }
+}
+
+export async function run() {
+  await discoverCommands();
+  await program.parseAsync();
+}
+
+export { ctx, program, registerCommand };

package/src/cli/shared/options.js

@@ -0,0 +1,39 @@
+import { loadConfig } from '../../config.js';
+
+const config = loadConfig(process.cwd());
+
+/**
+ * Attach the common query options shared by most analysis commands.
+ * @param {import('commander').Command} cmd
+ * @returns {import('commander').Command}
+ */
+export function applyQueryOpts(cmd) {
+  return cmd
+    .option('-d, --db <path>', 'Path to graph.db')
+    .option('-T, --no-tests', 'Exclude test/spec files from results')
+    .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+    .option('-j, --json', 'Output as JSON')
+    .option('--limit <number>', 'Max results to return')
+    .option('--offset <number>', 'Skip N results (default: 0)')
+    .option('--ndjson', 'Newline-delimited JSON output');
+}
+
+/**
+ * Resolve the effective noTests value: CLI flag > config > false.
+ * Commander sets opts.tests to false when --no-tests is passed.
+ * When --include-tests is passed, always return false (include tests).
+ * Otherwise, fall back to config.query.excludeTests.
+ */
+export function resolveNoTests(opts) {
+  if (opts.includeTests) return false;
+  if (opts.tests === false) return true;
+  return config.query?.excludeTests || false;
+}
+
+export 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`;
+}
+
+export { config };

package/src/cli/shared/output.js

@@ -0,0 +1 @@
+export { outputResult } from '../../infrastructure/result-formatter.js';