@optave/codegraph 3.12.0 → 3.15.0

package/src/ast-analysis/visitors/dataflow-visitor.ts

@@ -287,6 +287,28 @@ function handleAssignment(
   }
 }
 
+/** Unwrap argument wrapper and spread nodes to get the core argument node. */
+function unwrapArg(
+  arg: TreeSitterNode,
+  rules: AnyRules,
+): { unwrapped: TreeSitterNode; raw: TreeSitterNode } {
+  let raw = arg;
+  if (rules.argumentWrapperType && arg.type === rules.argumentWrapperType) {
+    raw = arg.namedChildren[0] || arg;
+  }
+  const unwrapped =
+    rules.spreadType && raw.type === rules.spreadType ? raw.namedChildren[0] || raw : raw;
+  return { unwrapped, raw };
+}
+
+/** Resolve the tracked name for a call argument (identifier or member receiver). */
+function resolveArgTrackedName(node: TreeSitterNode, rules: AnyRules): string | null {
+  const argName = isIdent(node.type, rules) ? node.text : null;
+  const argMember =
+    rules.memberNode && node.type === rules.memberNode ? memberReceiver(node, rules) : null;
+  return argName || argMember;
+}
+
 function handleCallExpr(
   node: TreeSitterNode,
   rules: AnyRules,
@@ -299,24 +321,14 @@ function handleCallExpr(
   if (!callee || !argsNode || !scope?.funcName) return;
 
   let argIndex = 0;
-  for (let arg of argsNode.namedChildren) {
-    if (rules.argumentWrapperType && arg.type === rules.argumentWrapperType) {
-      arg = arg.namedChildren[0] || arg;
-    }
-    const unwrapped =
-      rules.spreadType && arg.type === rules.spreadType ? arg.namedChildren[0] || arg : arg;
+  for (const arg of argsNode.namedChildren) {
+    const { unwrapped, raw } = unwrapArg(arg, rules);
     if (!unwrapped) {
       argIndex++;
       continue;
     }
 
-    const argName = isIdent(unwrapped.type, rules) ? unwrapped.text : null;
-    const argMember =
-      rules.memberNode && unwrapped.type === rules.memberNode
-        ? memberReceiver(unwrapped, rules)
-        : null;
-    const trackedName = argName || argMember;
-
+    const trackedName = resolveArgTrackedName(unwrapped, rules);
     if (trackedName) {
       const binding = findBinding(trackedName, scopeStack);
       if (binding) {
@@ -327,7 +339,7 @@ function handleCallExpr(
           argName: trackedName,
           binding,
           confidence: bindingConfidence(binding),
-          expression: truncate(arg.text),
+          expression: truncate(raw.text),
           line: node.startPosition.row + 1,
         });
       }
@@ -336,17 +348,11 @@ function handleCallExpr(
   }
 }
 
-function handleExprStmtMutation(
-  node: TreeSitterNode,
+/** Resolve the method name and receiver from a call expression node. */
+function resolveMutationCallParts(
+  expr: TreeSitterNode,
   rules: AnyRules,
-  scopeStack: ScopeEntry[],
-  mutations: DataflowMutation[],
-  isCallNode: (t: string) => boolean,
-): void {
-  if (rules.mutatingMethods.size === 0) return;
-  const expr = node.namedChildren[0];
-  if (!expr || !isCall(expr, isCallNode)) return;
-
+): { methodName: string | null; receiver: string | null } {
   let methodName: string | null = null;
   let receiver: string | null = null;
 
@@ -366,6 +372,21 @@ function handleExprStmtMutation(
     }
   }
 
+  return { methodName, receiver };
+}
+
+function handleExprStmtMutation(
+  node: TreeSitterNode,
+  rules: AnyRules,
+  scopeStack: ScopeEntry[],
+  mutations: DataflowMutation[],
+  isCallNode: (t: string) => boolean,
+): void {
+  if (rules.mutatingMethods.size === 0) return;
+  const expr = node.namedChildren[0];
+  if (!expr || !isCall(expr, isCallNode)) return;
+
+  const { methodName, receiver } = resolveMutationCallParts(expr, rules);
   if (!methodName || !rules.mutatingMethods.has(methodName)) return;
 
   const scope = currentScope(scopeStack);
@@ -405,15 +426,27 @@ function handleReturn(
   }
 }
 
-/** Collect parameter entries for a function and push a new scope onto the stack. */
+/**
+ * Collect parameter entries for a function and push a new scope onto the stack.
+ *
+ * Returns `true` if a scope was pushed, `false` if the node was skipped (i.e.
+ * `nameExtractor` rejected it). Callers must pop the stack only when this
+ * returns `true` to keep push/pop symmetric.
+ */
 function enterFunctionScope(
   funcNode: TreeSitterNode,
   rules: AnyRules,
   scopeStack: ScopeEntry[],
   parameters: DataflowParam[],
-): void {
+): boolean {
+  // When nameExtractor is set it acts as a gate: null means this node is not a function
+  // definition. Needed for languages (Elixir, Clojure) where functionNodes includes generic
+  // node types (call/list_lit) that are only sometimes function definitions.
+  if (rules.nameExtractor && !rules.nameExtractor(funcNode)) return false;
   const name = functionName(funcNode, rules);
-  const paramsNode = funcNode.childForFieldName(rules.paramListField);
+  const paramsNode = rules.getParamListNode
+    ? rules.getParamListNode(funcNode)
+    : funcNode.childForFieldName(rules.paramListField);
   const paramList = extractParams(paramsNode, rules);
   const paramMap = new Map<string, number>();
   for (const p of paramList) {
@@ -428,6 +461,7 @@ function enterFunctionScope(
     }
   }
   scopeStack.push({ funcName: name, funcNode, params: paramMap, locals: new Map() });
+  return true;
 }
 
 interface DataflowDispatchCtx {
@@ -489,6 +523,11 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
   const argFlows: DataflowArgFlow[] = [];
   const mutations: DataflowMutation[] = [];
   const scopeStack: ScopeEntry[] = [];
+  // Parallel stack that records whether each enterFunction call actually pushed a
+  // scope frame.  exitFunction pops scopeStack only when the matching entry is true,
+  // keeping push/pop symmetric even for languages (Elixir, Clojure) where
+  // enterFunctionScope may return early without pushing.
+  const pushRecord: boolean[] = [];
 
   const dispatchCtx: DataflowDispatchCtx = {
     rules,
@@ -509,7 +548,7 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
       _funcName: string | null,
       _context: VisitorContext,
     ): void {
-      enterFunctionScope(funcNode, rules, scopeStack, parameters);
+      pushRecord.push(enterFunctionScope(funcNode, rules, scopeStack, parameters));
     },
 
     exitFunction(
@@ -517,7 +556,7 @@ export function createDataflowVisitor(rules: AnyRules): Visitor {
       _funcName: string | null,
       _context: VisitorContext,
     ): void {
-      scopeStack.pop();
+      if (pushRecord.pop()) scopeStack.pop();
     },
 
     enterNode(node: TreeSitterNode, _context: VisitorContext): EnterNodeResult | undefined {

package/src/cli/commands/audit.ts

@@ -7,7 +7,8 @@ import type { CommandDefinition } from '../types.js';
 
 export const command: CommandDefinition = {
   name: 'audit <target>',
-  description: 'Composite report: explain + impact + health metrics per function',
+  alias: 'explain',
+  description: 'Composite report: explain + impact + health metrics per function (alias: explain)',
   options: [
     ['-d, --db <path>', 'Path to graph.db'],
     ['--quick', 'Structural summary only (skip impact analysis and health metrics)'],

package/src/cli/commands/batch.ts

@@ -18,6 +18,7 @@ export const command: CommandDefinition = {
     ['-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', 'Accepted for script compatibility (batch always outputs JSON)'],
   ],
   validate([_command, _targets], opts) {
     if (opts.kind && !(EVERY_SYMBOL_KIND as readonly string[]).includes(opts.kind)) {

package/src/cli/commands/build.ts

@@ -16,7 +16,10 @@ export const command: CommandDefinition = {
   ],
   async execute([dir], opts, ctx) {
     const root = path.resolve(dir || '.');
-    const engine = ctx.program.opts().engine;
+    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,
@@ -25,6 +28,8 @@ export const command: CommandDefinition = {
       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/config.ts

@@ -0,0 +1,353 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  clearConfigCache,
+  DEFAULTS,
+  getDefaultUserConfigPath,
+  loadConfig,
+  loadConfigWithProvenance,
+  resolveUserConfigPath,
+} from '../../infrastructure/config.js';
+import {
+  getUserConfigConsent,
+  listUserConfigConsent,
+  REGISTRY_PATH,
+  setUserConfigConsent,
+} from '../../infrastructure/registry.js';
+import { formatTable } from '../../presentation/table.js';
+import type { ConfigSource } from '../../types.js';
+import type { CommandDefinition } from '../types.js';
+
+/**
+ * Recursively flatten a nested config object to dot-notation key/value pairs.
+ * Arrays and null values are serialised to strings.
+ */
+function flattenConfig(
+  obj: Record<string, unknown>,
+  prefix = '',
+): Array<{ key: string; value: string }> {
+  const out: Array<{ key: string; value: string }> = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(...flattenConfig(v as Record<string, unknown>, fullKey));
+    } else if (Array.isArray(v)) {
+      out.push({ key: fullKey, value: v.length === 0 ? '[]' : JSON.stringify(v) });
+    } else {
+      out.push({ key: fullKey, value: v === null ? 'null' : String(v) });
+    }
+  }
+  return out;
+}
+
+/**
+ * Expand a top-level provenance map (e.g. { build: 'project' }) to cover every
+ * flattened dot-notation key (e.g. 'build.incremental' → 'project').
+ */
+function expandProvenance(
+  flatEntries: Array<{ key: string; value: string }>,
+  provenance: Record<string, ConfigSource>,
+): Map<string, ConfigSource> {
+  const map = new Map<string, ConfigSource>();
+  for (const { key } of flatEntries) {
+    // Provenance is keyed by top-level section (e.g. 'build', 'llm'), so
+    // extract the first segment to find the governing provenance entry.
+    const topLevel = key.split('.')[0] ?? key;
+    map.set(key, provenance[topLevel] ?? 'default');
+  }
+  return map;
+}
+
+/**
+ * Render the effective config as a human-readable Key/Value/Source table.
+ * All rows are shown, sorted so non-default overrides appear first, then
+ * remaining defaults alphabetically.
+ */
+function renderConfigTable(
+  config: Record<string, unknown>,
+  provenance: Record<string, ConfigSource>,
+): string {
+  const flat = flattenConfig(config);
+  const sourceMap = expandProvenance(flat, provenance);
+
+  // Show all entries — sorting non-defaults first, then alphabetically
+  const rows = flat
+    .slice()
+    .sort((a, b) => {
+      const sa = sourceMap.get(a.key) ?? 'default';
+      const sb = sourceMap.get(b.key) ?? 'default';
+      // Non-defaults first
+      if (sa !== 'default' && sb === 'default') return -1;
+      if (sa === 'default' && sb !== 'default') return 1;
+      return a.key.localeCompare(b.key);
+    })
+    .map(({ key, value }) => [key, value, sourceMap.get(key) ?? 'default']);
+
+  const keyWidth = Math.max(3, ...rows.map((r) => r[0]!.length));
+  const valWidth = Math.max(5, ...rows.map((r) => r[1]!.length));
+  // Source column is always short ('default', 'user', 'project', 'env')
+  const srcWidth = 7;
+
+  return `${formatTable({
+    columns: [
+      { header: 'Key', width: keyWidth },
+      { header: 'Value', width: valWidth },
+      { header: 'Source', width: srcWidth },
+    ],
+    rows: rows as string[][],
+    indent: 0,
+  })}\n`;
+}
+
+/**
+ * Build a scaffolded global config JSON file.
+ * Produces valid JSON with common sections pre-populated at their defaults.
+ * Uses DEFAULTS so the values always reflect the current schema.
+ *
+ * All keys are optional — users can delete sections they don't need.
+ */
+function buildInitTemplate(): string {
+  // Build a plain object — no comments in JSON, but keep it self-explanatory.
+  // Unknown top-level keys are silently ignored by mergeConfig.
+  const template: Record<string, unknown> = {
+    // LLM provider for AI features (codegraph explain, context, etc.)
+    // Use apiKeyCommand to pull the key from a secret manager at runtime.
+    // Scope to specific repos with:
+    //   { "appliesTo": ["~/projects/*"], "config": { ... } }
+    llm: {
+      provider: DEFAULTS.llm.provider,
+      model: DEFAULTS.llm.model,
+      baseUrl: DEFAULTS.llm.baseUrl,
+      apiKey: DEFAULTS.llm.apiKey,
+      apiKeyCommand: DEFAULTS.llm.apiKeyCommand,
+    },
+
+    query: {
+      defaultDepth: DEFAULTS.query.defaultDepth,
+      defaultLimit: DEFAULTS.query.defaultLimit,
+      excludeTests: DEFAULTS.query.excludeTests,
+    },
+
+    build: {
+      incremental: DEFAULTS.build.incremental,
+      typescriptResolver: DEFAULTS.build.typescriptResolver,
+    },
+
+    ci: {
+      failOnCycles: DEFAULTS.ci.failOnCycles,
+      impactThreshold: DEFAULTS.ci.impactThreshold,
+    },
+
+    search: {
+      defaultMinScore: DEFAULTS.search.defaultMinScore,
+      topK: DEFAULTS.search.topK,
+    },
+  };
+
+  return `${JSON.stringify(template, null, 2)}\n`;
+}
+
+// ─── Subcommand handlers ───────────────────────────────────────────────
+
+function handleInit(): void {
+  const targetPath = getDefaultUserConfigPath();
+  if (fs.existsSync(targetPath)) {
+    process.stderr.write(
+      `Global config already exists at ${targetPath}\n` +
+        `Run \`codegraph config --edit\` to open it, or delete it and re-run --init.\n`,
+    );
+    process.exit(1);
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, buildInitTemplate(), 'utf-8');
+  process.stdout.write(`Created global config at ${targetPath}\n`);
+  process.stdout.write(
+    `Next steps:\n` +
+      `  1. Edit the file: codegraph config --edit\n` +
+      `  2. Enable it for this repo: codegraph config --enable-global\n`,
+  );
+}
+
+function handleEdit(): void {
+  // Prefer the existing file; fall back to the default path so the user
+  // can create-and-edit in one step even before running --init.
+  const filePath = resolveUserConfigPath() ?? getDefaultUserConfigPath();
+
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) {
+    process.stdout.write(`${filePath}\n`);
+    process.stderr.write(
+      `$EDITOR is not set. Set it in your shell profile (e.g. export EDITOR=nano)\n` +
+        `or open the file manually at the path printed above.\n`,
+    );
+    return;
+  }
+
+  // Ensure the directory exists so the editor can create the file
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const result = spawnSync(editor, [filePath], { stdio: 'inherit' });
+  if (result.error) {
+    process.stderr.write(`Failed to launch editor "${editor}": ${result.error.message}\n`);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function handleEnableGlobal(rootDir: string): void {
+  setUserConfigConsent(rootDir, 'enabled');
+  clearConfigCache();
+  const globalPath = resolveUserConfigPath();
+  if (!globalPath) {
+    process.stderr.write(
+      `Consent recorded: "enabled" for ${rootDir}\n` +
+        `Note: no global config file found. Create one at ~/.config/codegraph/config.json\n`,
+    );
+  } else {
+    process.stderr.write(
+      `Consent recorded: "enabled" for ${rootDir}\n` + `Global config: ${globalPath}\n`,
+    );
+  }
+}
+
+function handleDisableGlobal(rootDir: string): void {
+  setUserConfigConsent(rootDir, 'disabled');
+  clearConfigCache();
+  process.stderr.write(`Consent recorded: "disabled" for ${rootDir}\n`);
+}
+
+function handleListGlobal(json: boolean): void {
+  const entries = listUserConfigConsent(REGISTRY_PATH);
+  if (json) {
+    process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+    return;
+  }
+  if (entries.length === 0) {
+    process.stdout.write('No repos have a recorded global-config consent decision.\n');
+    return;
+  }
+  process.stdout.write('Global config consent decisions:\n\n');
+  for (const { path: p, decision } of entries) {
+    process.stdout.write(`  ${decision === 'enabled' ? '✔' : '✘'} ${decision.padEnd(8)} ${p}\n`);
+  }
+}
+
+function handleExplain(
+  rootDir: string,
+  json: boolean,
+  userConfigOverride: string | undefined,
+): void {
+  const { config, provenance, appliedGlobalPath, consentDecision } = loadConfigWithProvenance(
+    rootDir,
+    { userConfig: userConfigOverride },
+  );
+  const globalPath = resolveUserConfigPath();
+  const consent = getUserConfigConsent(rootDir);
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          config,
+          provenance,
+          appliedGlobalPath,
+          globalFilePath: globalPath,
+          consentDecision: consentDecision ?? consent ?? 'undecided',
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+
+  // Human-readable explain output
+  process.stdout.write('=== Codegraph config provenance ===\n\n');
+
+  const consentStr = consentDecision ?? consent ?? 'undecided';
+  process.stdout.write(`Global config file : ${globalPath ?? '(none found)'}\n`);
+  process.stdout.write(`Applied this run   : ${appliedGlobalPath ? 'yes' : 'no'}\n`);
+  process.stdout.write(`Consent for repo   : ${consentStr}\n`);
+  process.stdout.write(
+    `  (change with \`codegraph config --enable-global\` or \`--disable-global\`)\n`,
+  );
+
+  if (!globalPath) {
+    process.stdout.write(
+      `\nDiscovery hint: create a global config at ~/.config/codegraph/config.json\n` +
+        `then run \`codegraph config --enable-global\` in repos where you want it applied.\n`,
+    );
+  } else if (!appliedGlobalPath) {
+    process.stdout.write(
+      `\nDiscovery hint: global config exists but is not applied to this repo.\n` +
+        `Run \`codegraph config --enable-global\` to enable it here.\n`,
+    );
+  }
+
+  process.stdout.write('\n--- Per-key provenance ---\n\n');
+  const provenanceEntries = Object.entries(provenance).sort(([a], [b]) => a.localeCompare(b));
+  for (const [key, source] of provenanceEntries) {
+    process.stdout.write(`  ${source.padEnd(8)} ${key}\n`);
+  }
+}
+
+function handleShowConfig(
+  rootDir: string,
+  json: boolean,
+  userConfigOverride: string | undefined,
+): void {
+  const globalPath = resolveUserConfigPath();
+  const consent = getUserConfigConsent(rootDir);
+
+  if (json) {
+    const config = loadConfig(rootDir, { userConfig: userConfigOverride });
+    process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+    return;
+  }
+
+  // Human-readable table: Key | Value | Source
+  const { config, provenance } = loadConfigWithProvenance(rootDir, {
+    userConfig: userConfigOverride,
+  });
+  process.stdout.write(renderConfigTable(config as unknown as Record<string, unknown>, provenance));
+
+  if (globalPath && !consent) {
+    process.stderr.write(
+      `\nℹ Global config found at ${globalPath} — not applied to this repo.\n` +
+        `  Run \`codegraph config --enable-global\` to opt in, or\n` +
+        `  \`codegraph config --disable-global\` to dismiss this notice.\n`,
+    );
+  }
+}
+
+export const command: CommandDefinition = {
+  name: 'config',
+  description: 'Show or manage codegraph configuration (project + user-level global config)',
+  options: [
+    ['-j, --json', 'Output as JSON'],
+    ['--explain', 'Show per-key provenance (default / user / project / env)'],
+    ['--enable-global', 'Record consent to apply the global config to this repo'],
+    ['--disable-global', 'Record consent to skip the global config for this repo'],
+    ['--list-global', 'List all repos with a recorded consent decision'],
+    [
+      '--init',
+      'Scaffold a global config file at the default XDG location with all sections pre-populated',
+    ],
+    ['--edit', 'Open the global config file in $EDITOR (prints the path if $EDITOR is unset)'],
+  ],
+  execute(_args, opts, ctx) {
+    const rootDir = path.resolve('.');
+    const userConfigOverride = ctx.program.opts().userConfig as string | undefined;
+
+    if (opts.init) return handleInit();
+    if (opts.edit) return handleEdit();
+    if (opts.enableGlobal) return handleEnableGlobal(rootDir);
+    if (opts.disableGlobal) return handleDisableGlobal(rootDir);
+    if (opts.listGlobal) return handleListGlobal(opts.json);
+    if (opts.explain) return handleExplain(rootDir, opts.json, userConfigOverride);
+    return handleShowConfig(rootDir, opts.json, userConfigOverride);
+  },
+};

package/src/cli/commands/roles.ts

@@ -1,6 +1,6 @@
 import { collectFile } from '../../db/query-builder.js';
 import { VALID_ROLES } from '../../domain/queries.js';
-import { roles } from '../../presentation/queries-cli.js';
+import { dynamicCalls, roles } from '../../presentation/queries-cli.js';
 import type { CommandDefinition } from '../types.js';
 
 export const command: CommandDefinition = {
@@ -17,6 +17,7 @@ export const command: CommandDefinition = {
     ['-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)) {
@@ -24,6 +25,10 @@ export const command: CommandDefinition = {
     }
   },
   execute(_args, opts, ctx) {
+    if (opts.dynamic) {
+      dynamicCalls(opts.db, ctx.resolveQueryOpts(opts));
+      return;
+    }
     roles(opts.db, {
       role: opts.role,
       file: opts.file,

package/src/cli/commands/triage.ts

@@ -31,7 +31,7 @@ async function runHotspots(opts: CommandOpts, ctx: CliContext): Promise<void> {
     offset: opts.offset ? parseInt(opts.offset as string, 10) : undefined,
     noTests: ctx.resolveNoTests(opts),
   });
-  if (!ctx.outputResult(data, 'hotspots', opts)) {
+  if (!ctx.outputResult(data, 'items', opts)) {
     console.log(formatHotspots(data));
   }
 }

package/src/cli/index.ts

@@ -2,6 +2,7 @@ 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';
@@ -25,9 +26,16 @@ program
   .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();
@@ -67,6 +75,8 @@ const ctx: CliContext = {
 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 || []) {

package/src/cli/shared/options.ts

@@ -1,8 +1,18 @@
 import type { Command } from 'commander';
 import { loadConfig } from '../../infrastructure/config.js';
+import type { CodegraphConfig } from '../../types.js';
 import type { CommandOpts } from '../types.js';
 
-const config = loadConfig(process.cwd());
+// 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.

package/src/cli/types.ts

@@ -25,6 +25,8 @@ export interface CliContext {
 export interface CommandDefinition {
   name: string;
   description: string;
+  /** Optional Commander.js alias (e.g. 'explain' for the 'audit' command). */
+  alias?: string;
   queryOpts?: boolean;
   options?: Array<[string, string, ...unknown[]]>;
   validate?(args: string[], opts: CommandOpts, ctx: CliContext): string | undefined;