optave-codegraph 3.13.0

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

@@ -0,0 +1,27 @@
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'branch-compare <base> <target>',
+  description: 'Compare code structure between two branches/refs',
+  options: [
+    ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['-f, --format <format>', 'Output format: text, mermaid, json', 'text'],
+  ],
+  async execute([base, target], opts, ctx) {
+    const { branchCompare } = await import('../../presentation/branch-compare.js');
+    const path = await import('node:path');
+    const repoRoot = opts.db ? path.resolve(path.dirname(opts.db as string), '..') : undefined;
+    await branchCompare(base!, target!, {
+      engine: ctx.program.opts().engine,
+      depth: parseInt(opts.depth as string, 10),
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      format: opts.format,
+      repoRoot,
+    });
+  },
+};

package/src/cli/commands/brief.ts

@@ -0,0 +1,13 @@
+import { brief } from '../../presentation/brief.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'brief <file>',
+  description: 'Token-efficient file summary: symbols with roles, caller counts, risk tier',
+  queryOpts: true,
+  execute([file], opts, ctx) {
+    brief(file!, opts.db, {
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/build.ts

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { buildGraph } from '../../domain/graph/builder.js';
+import type { EngineMode } from '../../types.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'build [dir]',
+  description: 'Parse repo and build graph in .codegraph/graph.db',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db (default: <dir>/.codegraph/graph.db)'],
+    ['--no-incremental', 'Force full rebuild (ignore file hashes)'],
+    ['--no-ast', 'Skip AST node extraction (calls, new, string, regex, throw, await)'],
+    ['--no-complexity', 'Skip complexity metrics computation'],
+    ['--no-dataflow', 'Skip data flow edge extraction'],
+    ['--no-cfg', 'Skip control flow graph building'],
+  ],
+  async execute([dir], opts, ctx) {
+    const root = path.resolve(dir || '.');
+    const globalOpts = ctx.program.opts();
+    const engine = globalOpts.engine;
+    // Prompt for global-config consent on interactive TTY builds (§4.3).
+    const promptForConsent = !process.env.CI && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    await buildGraph(root, {
+      incremental: opts.incremental as boolean,
+      ast: opts.ast as boolean,
+      complexity: opts.complexity as boolean,
+      engine: engine as EngineMode,
+      dataflow: opts.dataflow as boolean,
+      cfg: opts.cfg as boolean,
+      dbPath: opts.db ? path.resolve(opts.db as string) : undefined,
+      userConfig: globalOpts.userConfig as string | boolean | undefined,
+      promptForConsent,
+    });
+  },
+};

package/src/cli/commands/cfg.ts

@@ -0,0 +1,28 @@
+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: 'cfg <name>',
+  description: 'Show control flow graph for a function',
+  queryOpts: true,
+  options: [
+    ['--format <fmt>', 'Output format: text, dot, mermaid', 'text'],
+    ['-f, --file <path>', 'Scope to file (partial match, 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 { cfg } = await import('../../presentation/cfg.js');
+    cfg(name!, opts.db, {
+      format: opts.format,
+      file: opts.file,
+      kind: opts.kind,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/check.ts

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

package/src/cli/commands/children.ts

@@ -0,0 +1,34 @@
+import { collectFile } from '../../db/query-builder.js';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { children } from '../../presentation/queries-cli.js';
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'children <name>',
+  description: 'List parameters, properties, and constants of a symbol',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    [
+      '-f, --file <path>',
+      'Scope search to symbols in this file (partial match, repeatable)',
+      collectFile,
+    ],
+    ['-k, --kind <kind>', 'Filter to a specific symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['-j, --json', 'Output as JSON'],
+    ['-n, --limit <number>', 'Max results to return'],
+    ['--offset <number>', 'Skip N results (default: 0)'],
+  ],
+  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(', ')}`;
+    }
+  },
+  execute([name], opts, ctx) {
+    children(name!, opts.db, {
+      file: opts.file,
+      kind: opts.kind,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

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

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

package/src/cli/commands/communities.ts

@@ -0,0 +1,21 @@
+import type { CommandDefinition } from '../types.js';
+
+export const command: CommandDefinition = {
+  name: 'communities',
+  description: 'Detect natural module boundaries using Louvain community detection',
+  queryOpts: true,
+  options: [
+    ['--functions', 'Function-level instead of file-level'],
+    ['--resolution <n>', 'Louvain resolution parameter (default 1.0)', '1.0'],
+    ['--drift', 'Show only drift analysis'],
+  ],
+  async execute(_args, opts, ctx) {
+    const { communities } = await import('../../presentation/communities.js');
+    communities(opts.db, {
+      functions: opts.functions,
+      resolution: parseFloat(opts.resolution as string),
+      drift: opts.drift,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/complexity.ts

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