@optave/codegraph 3.11.2 → 3.13.0

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`;
+}
+
+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('.');
+
+    // ── Init: scaffold global config ───────────────────────────────────
+
+    if (opts.init) {
+      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`,
+      );
+      return;
+    }
+
+    // ── Edit: open global config in $EDITOR ────────────────────────────
+
+    if (opts.edit) {
+      // 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);
+      }
+      return;
+    }
+
+    // ── Consent management ─────────────────────────────────────────────
+
+    if (opts.enableGlobal) {
+      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`,
+        );
+      }
+      return;
+    }
+
+    if (opts.disableGlobal) {
+      setUserConfigConsent(rootDir, 'disabled');
+      clearConfigCache();
+      process.stderr.write(`Consent recorded: "disabled" for ${rootDir}\n`);
+      return;
+    }
+
+    if (opts.listGlobal) {
+      const entries = listUserConfigConsent(REGISTRY_PATH);
+      if (opts.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`,
+        );
+      }
+      return;
+    }
+
+    // ── Explain mode ───────────────────────────────────────────────────
+
+    if (opts.explain) {
+      const { config, provenance, appliedGlobalPath, consentDecision } = loadConfigWithProvenance(
+        rootDir,
+        {
+          userConfig: ctx.program.opts().userConfig,
+        },
+      );
+      const globalPath = resolveUserConfigPath();
+      const consent = getUserConfigConsent(rootDir);
+
+      if (opts.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`);
+      }
+      return;
+    }
+
+    // ── Default: print effective config ────────────────────────────────
+
+    const globalPath = resolveUserConfigPath();
+    const consent = getUserConfigConsent(rootDir);
+
+    if (opts.json) {
+      const config = loadConfig(rootDir, { userConfig: ctx.program.opts().userConfig });
+      process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+    } else {
+      // Human-readable table: Key | Value | Source
+      const { config, provenance } = loadConfigWithProvenance(rootDir, {
+        userConfig: ctx.program.opts().userConfig,
+      });
+      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`,
+        );
+      }
+    }
+  },
+};

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;

package/src/db/migrations.ts

@@ -8,7 +8,7 @@ interface Migration {
   up: string;
 }
 
-// IMPORTANT: Migration DDL is mirrored in crates/codegraph-core/src/native_db.rs.
+// IMPORTANT: Migration DDL is mirrored in crates/codegraph-core/src/db/connection.rs.
 // Any changes here MUST be reflected there (and vice-versa).
 export const MIGRATIONS: Migration[] = [
   {
@@ -256,6 +256,13 @@ export const MIGRATIONS: Migration[] = [
       CREATE INDEX IF NOT EXISTS idx_edges_kind_source ON edges(kind, source_id);
     `,
   },
+  {
+    version: 17,
+    up: `
+      ALTER TABLE edges ADD COLUMN technique TEXT;
+      CREATE INDEX IF NOT EXISTS idx_edges_technique ON edges(technique);
+    `,
+  },
 ];
 
 interface PragmaColumnInfo {

package/src/domain/analysis/module-map.ts

@@ -163,6 +163,26 @@ function getEmbeddingsInfo(db: BetterSqlite3Database) {
   return null;
 }
 
+function countCallEdgesByTechnique(
+  db: BetterSqlite3Database,
+  testFilter: string,
+): Record<string, number> {
+  // testFilter uses n.file — join source node to apply the same file-scope as
+  // the rest of computeQualityMetrics so --no-tests is consistent.
+  const rows = db
+    .prepare(
+      `SELECT e.technique, COUNT(*) as c
+       FROM edges e
+       JOIN nodes n ON e.source_id = n.id
+       WHERE e.kind = 'calls' AND e.technique IS NOT NULL ${testFilter}
+       GROUP BY e.technique`,
+    )
+    .all() as Array<{ technique: string; c: number }>;
+  const byTechnique: Record<string, number> = {};
+  for (const r of rows) byTechnique[r.technique] = r.c;
+  return byTechnique;
+}
+
 function computeQualityMetrics(
   db: BetterSqlite3Database,
   testFilter: string,
@@ -205,13 +225,16 @@ function computeQualityMetrics(
   const falsePositiveRatio = totalCallEdges > 0 ? fpEdgeCount / totalCallEdges : 0;
 
   const score = computeQualityScore(callerCoverage, callConfidence, falsePositiveRatio);
+  const byTechnique = countCallEdgesByTechnique(db, testFilter);
 
   return {
     score,
     callerCoverage: {
       ratio: callerCoverage,
+      percentage: Math.round(callerCoverage * 100),
       covered: callableWithCallers,
       total: totalCallable,
+      byTechnique: Object.keys(byTechnique).length > 0 ? byTechnique : undefined,
     },
     callConfidence: {
       ratio: callConfidence,
@@ -388,6 +411,7 @@ function buildStatsFromNative(
   db: BetterSqlite3Database,
   nativeStats: NativeGraphStats,
   config: any,
+  noTests: boolean,
   jsSections: {
     files: ReturnType<typeof countFilesByLanguage>;
     fileCycles: unknown[];
@@ -413,6 +437,8 @@ function buildStatsFromNative(
   for (const fp of falsePositiveWarnings) fpEdgeCount += fp.callerCount;
   const falsePositiveRatio = s.quality.callEdges > 0 ? fpEdgeCount / s.quality.callEdges : 0;
   const score = computeQualityScore(callerCoverage, callConfidence, falsePositiveRatio);
+  const testFilter = testFilterSQL('n.file', noTests);
+  const byTechnique = countCallEdgesByTechnique(db, testFilter);
 
   return {
     nodes: { total: s.totalNodes, byKind: nodesByKind },
@@ -432,8 +458,10 @@ function buildStatsFromNative(
       score,
       callerCoverage: {
         ratio: callerCoverage,
+        percentage: Math.round(callerCoverage * 100),
         covered: s.quality.callableWithCallers,
         total: s.quality.callableTotal,
+        byTechnique: Object.keys(byTechnique).length > 0 ? byTechnique : undefined,
       },
       callConfidence: {
         ratio: callConfidence,
@@ -508,7 +536,7 @@ export function statsData(customDbPath: string, opts: { noTests?: boolean; confi
 
     const nativeStats = nativeDb?.getGraphStats?.(noTests);
     return nativeStats
-      ? buildStatsFromNative(db, nativeStats, config, jsSections)
+      ? buildStatsFromNative(db, nativeStats, config, noTests, jsSections)
       : buildStatsFromJs(db, noTests, config, jsSections);
   } finally {
     close();