@optave/codegraph 3.1.3 → 3.1.5

package/src/cli/index.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+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';
+
+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, resolveQueryOpts, 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/open-graph.js

@@ -0,0 +1,13 @@
+import { openReadonlyOrFail } from '../../db/index.js';
+
+/**
+ * Open the graph database in readonly mode with a clean close() handle.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.db] - Custom path to graph.db
+ * @returns {{ db: import('better-sqlite3').Database, close: () => void }}
+ */
+export function openGraph(opts = {}) {
+  const db = openReadonlyOrFail(opts.db);
+  return { db, close: () => db.close() };
+}

package/src/cli/shared/options.js

@@ -0,0 +1,59 @@
+import { loadConfig } from '../../infrastructure/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')
+    .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) {
+  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) {
+  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) {
+  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';