optave-codegraph 3.13.0

package/src/cli/commands/roles.ts

@@ -0,0 +1,38 @@
+import { collectFile } from '../../db/query-builder.js';
+import { VALID_ROLES } from '../../domain/queries.js';
+import { dynamicCalls, roles } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'roles',
+  description:
+    'Show node role classification: entry, core, utility, adapter, dead (dead-leaf, dead-entry, dead-ffi, dead-unresolved), 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, repeatable)', collectFile],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['-n, --limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+    ['--dynamic', 'Show flagged dynamic call sites instead of symbol roles'],
+  ],
+  validate(_args, opts) {
+    if (opts.role && !(VALID_ROLES as readonly string[]).includes(opts.role)) {
+      return `Invalid role "${opts.role}". Valid roles: ${VALID_ROLES.join(', ')}`;
+    }
+  },
+  execute(_args, opts, ctx) {
+    if (opts.dynamic) {
+      dynamicCalls(opts.db, ctx.resolveQueryOpts(opts));
+      return;
+    }
+    roles(opts.db, {
+      role: opts.role,
+      file: opts.file,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/search.ts

@@ -0,0 +1,45 @@
+import { collectFile } from '../../db/query-builder.js';
+import { search } from '../../domain/search/index.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  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 (repeatable)', collectFile],
+    ['--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 as string)) {
+      return `Invalid mode "${opts.mode}". Valid: ${validModes.join(', ')}`;
+    }
+  },
+  async execute([query], opts, ctx) {
+    const fileArr = (opts.file || []) as string[];
+    const filePattern =
+      fileArr.length === 1 ? fileArr[0] : fileArr.length > 1 ? fileArr : undefined;
+    await search(query!, opts.db as string | undefined, {
+      limit: parseInt(opts.limit as string, 10),
+      noTests: ctx.resolveNoTests(opts),
+      minScore: parseFloat(opts.minScore as string),
+      model: opts.model as string | undefined,
+      kind: opts.kind as string | undefined,
+      filePattern,
+      rrfK: parseInt(opts.rrfK as string, 10),
+      mode: opts.mode as 'hybrid' | 'semantic' | 'keyword' | undefined,
+      json: opts.json as boolean | undefined,
+    });
+  },
+};

package/src/cli/commands/sequence.ts

@@ -0,0 +1,30 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  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, repeatable)', collectFile],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).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 as string, 10),
+      file: opts.file,
+      kind: opts.kind,
+      dataflow: opts.dataflow,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/snapshot.ts

@@ -0,0 +1,67 @@
+import {
+  snapshotDelete,
+  snapshotList,
+  snapshotRestore,
+  snapshotSave,
+} from '../../features/snapshot.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  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.ts

@@ -0,0 +1,16 @@
+import { stats } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  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.ts

@@ -0,0 +1,55 @@
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  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'],
+    ['-n, --limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+    ['--ndjson', 'Newline-delimited JSON output'],
+    ['--modules', 'Show module boundaries (directories with high cohesion)'],
+    ['--threshold <number>', 'Cohesion threshold for --modules (default: 0.3)'],
+  ],
+  async execute([dir], opts, ctx) {
+    const { structureData, formatStructure, moduleBoundariesData, formatModuleBoundaries } =
+      await import('../../presentation/structure.js');
+
+    if (opts.modules) {
+      const parsed = opts.threshold ? parseFloat(opts.threshold as string) : undefined;
+      if (parsed !== undefined && Number.isNaN(parsed)) {
+        console.error('Error: --threshold must be a number');
+        process.exitCode = 1;
+        return;
+      }
+      const data = moduleBoundariesData(opts.db, {
+        threshold: parsed,
+      });
+      if (!ctx.outputResult(data, 'modules', opts)) {
+        console.log(formatModuleBoundaries(data));
+      }
+      return;
+    }
+
+    const qOpts = ctx.resolveQueryOpts(opts);
+    const data = structureData(opts.db, {
+      directory: dir,
+      depth: opts.depth ? parseInt(opts.depth as string, 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.ts

@@ -0,0 +1,93 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND, VALID_ROLES } from '../../domain/queries.js';
+import { ConfigError } from '../../shared/errors.js';
+import type { CliContext, CommandDefinition, CommandOpts } from '../types.js';
+
+function validateFilters(opts: CommandOpts): void {
+  if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {
+    throw new ConfigError(`Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`);
+  }
+  if (opts.role && !(VALID_ROLES as readonly string[]).includes(opts.role)) {
+    throw new ConfigError(`Invalid role "${opts.role}". Valid: ${VALID_ROLES.join(', ')}`);
+  }
+}
+
+function parseWeights(raw: unknown): Record<string, number> | undefined {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw as string);
+  } catch (err: unknown) {
+    throw new ConfigError('Invalid --weights JSON', { cause: err as Error });
+  }
+}
+
+async function runHotspots(opts: CommandOpts, ctx: CliContext): Promise<void> {
+  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 as string, 10),
+    offset: opts.offset ? parseInt(opts.offset as string, 10) : undefined,
+    noTests: ctx.resolveNoTests(opts),
+  });
+  if (!ctx.outputResult(data, 'items', opts)) {
+    console.log(formatHotspots(data));
+  }
+}
+
+export const command: CommandDefinition = {
+  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, dead-leaf, dead-entry, dead-ffi, dead-unresolved)',
+    ],
+    ['-f, --file <path>', 'Scope to a specific file (partial match, repeatable)', collectFile],
+    ['-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') {
+      await runHotspots(opts, ctx);
+      return;
+    }
+
+    validateFilters(opts);
+    const weights = parseWeights(opts.weights);
+    const { triage } = await import('../../presentation/triage.js');
+    triage(opts.db, {
+      limit: parseInt(opts.limit as string, 10),
+      offset: opts.offset ? parseInt(opts.offset as string, 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.ts

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { watchProject } from '../../domain/graph/watcher.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'watch [dir]',
+  description: 'Watch project for file changes and incrementally update the graph',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--poll', 'Use stat-based polling (default on Windows to avoid ReFS/Dev Drive crashes)'],
+    ['--native', 'Force native OS file watchers instead of polling'],
+    ['--poll-interval <ms>', 'Polling interval in milliseconds (default: 2000)'],
+  ],
+  async execute([dir], opts, ctx) {
+    const root = path.resolve(dir || '.');
+    const engine = ctx.program.opts().engine;
+    if (opts.poll && opts.native) {
+      ctx.program.error('--poll and --native are mutually exclusive');
+    }
+    // Explicit --poll or --native wins; otherwise let watcher auto-detect by platform
+    const poll = opts.poll ? true : opts.native ? false : undefined;
+    await watchProject(root, {
+      engine,
+      poll,
+      pollInterval: opts.pollInterval ? Number(opts.pollInterval) : undefined,
+      dbPath: opts.db ? path.resolve(opts.db) : undefined,
+    });
+  },
+};

package/src/cli/commands/where.ts

@@ -0,0 +1,21 @@
+import { where } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  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) as string;
+    where(target, opts.db, {
+      file: !!opts.file,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/index.ts

@@ -0,0 +1,159 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { setUserConfigOverride } from '../infrastructure/config.js';
+import { setVerbose } from '../infrastructure/logger.js';
+import { checkForUpdates, printUpdateNotification } from '../infrastructure/update-check.js';
+import { ConfigError } from '../shared/errors.js';
+import {
+  applyQueryOpts,
+  config,
+  formatSize,
+  resolveNoTests,
+  resolveQueryOpts,
+} from './shared/options.js';
+import { outputResult } from './shared/output.js';
+import type { CliContext, CommandDefinition, CommandOpts } from './types.js';
+
+const __cliDir = path.dirname(fileURLToPath(import.meta.url));
+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')
+  .option('--user-config [path]', 'Apply global user config for this run (optional custom path)')
+  .option('--no-user-config', 'Skip global user config for this run')
+  .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.verbose) setVerbose(true);
+    // Wire user-config flags into the config loader before any command runs.
+    // Commander sets opts.userConfig = true (bare flag), a string (path), or undefined.
+    // opts.userConfig is false when --no-user-config is passed (Commander negation).
+    const uc = opts.userConfig as string | boolean | undefined;
+    setUserConfigOverride(uc);
+  })
+  .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: CliContext = {
+  config,
+  resolveNoTests,
+  resolveQueryOpts,
+  formatSize,
+  outputResult: outputResult as CliContext['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: Command, def: CommandDefinition): Command {
+  const cmd = parent.command(def.name).description(def.description);
+
+  if (def.alias) cmd.alias(def.alias);
+
+  if (def.queryOpts) applyQueryOpts(cmd);
+
+  for (const opt of def.options || []) {
+    cmd.option(...(opt as Parameters<Command['option']>));
+  }
+
+  if (def.execute) {
+    const argCount = (def.name.match(/<[^>]+>|\[[^\]]+\]/g) || []).length;
+
+    cmd.action((...actionArgs: unknown[]) => {
+      const args = actionArgs.slice(0, argCount) as string[];
+      const opts = actionArgs[argCount] as CommandOpts;
+
+      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(): Promise<void> {
+  const commandsDir = path.join(__cliDir, 'commands');
+  const files = fs
+    .readdirSync(commandsDir)
+    .filter((f) => f.endsWith('.js') || f.endsWith('.ts'))
+    .filter((f) => !f.endsWith('.d.ts'))
+    .sort();
+
+  // Deduplicate: prefer .ts over .js when both exist
+  const fileSet = new Set(files);
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const file of files) {
+    const base = file.replace(/\.[jt]s$/, '');
+    if (!seen.has(base)) {
+      seen.add(base);
+      const tsVariant = `${base}.ts`;
+      deduped.push(fileSet.has(tsVariant) ? tsVariant : file);
+    }
+  }
+
+  for (const file of deduped) {
+    const mod = (await import(pathToFileURL(path.join(commandsDir, file)).href)) as {
+      command?: CommandDefinition;
+      commands?: CommandDefinition[];
+    };
+    if (mod.command) {
+      registerCommand(program, mod.command);
+    }
+    if (mod.commands) {
+      for (const def of mod.commands) {
+        registerCommand(program, def);
+      }
+    }
+  }
+}
+
+export async function run(): Promise<void> {
+  await discoverCommands();
+  await program.parseAsync();
+}
+
+export { ctx, program, registerCommand };

package/src/cli/shared/open-graph.ts

@@ -0,0 +1,13 @@
+import { openReadonlyOrFail } from '../../db/index.js';
+import type { BetterSqlite3Database } from '../../types.js';
+
+/**
+ * Open the graph database in readonly mode with a clean close() handle.
+ */
+export function openGraph(opts: { db?: string } = {}): {
+  db: BetterSqlite3Database;
+  close: () => void;
+} {
+  const db = openReadonlyOrFail(opts.db);
+  return { db, close: () => db.close() };
+}

package/src/cli/shared/options.ts

@@ -0,0 +1,69 @@
+import type { Command } from 'commander';
+import { loadConfig } from '../../infrastructure/config.js';
+import type { CodegraphConfig } from '../../types.js';
+import type { CommandOpts } from '../types.js';
+
+// Deferred so global --user-config / --no-user-config flags are parsed
+// before config is first accessed (Commander parses flags before any command
+// action runs, but module-level code executes at import time).
+let _config: CodegraphConfig | undefined;
+const config: CodegraphConfig = new Proxy({} as CodegraphConfig, {
+  get(_t, prop: string) {
+    if (_config === undefined) _config = loadConfig(process.cwd());
+    return _config[prop as keyof CodegraphConfig];
+  },
+}) as CodegraphConfig;
+
+/**
+ * Attach the common query options shared by most analysis commands.
+ */
+export function applyQueryOpts(cmd: Command): Command {
+  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('-n, --limit <number>', 'Max results to return')
+    .option('--offset <number>', 'Skip N results (default: 0)')
+    .option('--ndjson', 'Newline-delimited JSON output')
+    .option('--table', 'Output as aligned table')
+    .option('--csv', 'Output as CSV');
+}
+
+/**
+ * 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: CommandOpts): boolean {
+  if (opts.includeTests) return false;
+  if (opts.tests === false) return true;
+  return config.query?.excludeTests || false;
+}
+
+/**
+ * Extract the common query option fields shared by most analysis commands.
+ *
+ * Spreads cleanly into per-command option objects:
+ *   `{ ...resolveQueryOpts(opts), depth: parseInt(opts.depth, 10) }`
+ */
+export function resolveQueryOpts(opts: CommandOpts): CommandOpts {
+  return {
+    noTests: resolveNoTests(opts),
+    json: opts.json,
+    ndjson: opts.ndjson,
+    table: opts.table,
+    csv: opts.csv,
+    limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+    offset: opts.offset ? parseInt(opts.offset, 10) : undefined,
+  };
+}
+
+export function formatSize(bytes: number): string {
+  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.ts

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