@optave/codegraph 3.9.3 → 3.9.5

package/src/extractors/javascript.ts

@@ -274,14 +274,17 @@ function dispatchQueryMatch(
       name: c.callfn_name!.text,
       line: c.callfn_node.startPosition.row + 1,
     });
+    calls.push(...extractCallbackReferenceCalls(c.callfn_node));
   } else if (c.callmem_node) {
     const callInfo = extractCallInfo(c.callmem_fn!, c.callmem_node);
     if (callInfo) calls.push(callInfo);
     const cbDef = extractCallbackDefinition(c.callmem_node, c.callmem_fn);
     if (cbDef) definitions.push(cbDef);
+    calls.push(...extractCallbackReferenceCalls(c.callmem_node));
   } else if (c.callsub_node) {
     const callInfo = extractCallInfo(c.callsub_fn!, c.callsub_node);
     if (callInfo) calls.push(callInfo);
+    calls.push(...extractCallbackReferenceCalls(c.callsub_node));
   } else if (c.newfn_node) {
     calls.push({
       name: c.newfn_name!.text,
@@ -321,6 +324,9 @@ function extractSymbolsQuery(tree: TreeSitterTree, query: TreeSitterQuery): Extr
   // Extract typeMap from type annotations and new expressions
   extractTypeMapWalk(tree.rootNode, typeMap);
 
+  // Extract definitions from destructured bindings (query patterns don't match object_pattern)
+  extractDestructuredBindingsWalk(tree.rootNode, definitions);
+
   return { definitions, calls, imports, classes, exports: exps, typeMap };
 }
 
@@ -334,6 +340,20 @@ const FUNCTION_SCOPE_TYPES = new Set([
   'generator_function',
 ]);
 
+/**
+ * Return true when `node` has an ancestor whose type is in FUNCTION_SCOPE_TYPES.
+ * Used by the walk path to skip declarations inside function bodies, matching
+ * the query path's top-down FUNCTION_SCOPE_TYPES filter.
+ */
+function hasFunctionScopeAncestor(node: TreeSitterNode): boolean {
+  let p: TreeSitterNode | null = node.parent ?? null;
+  while (p) {
+    if (FUNCTION_SCOPE_TYPES.has(p.type)) return true;
+    p = p.parent ?? null;
+  }
+  return false;
+}
+
 /**
  * Recursively walk the AST to extract `const x = <literal>` as constants.
  * Skips nodes inside function scopes so only file-level / block-level constants
@@ -363,6 +383,48 @@ function extractConstantsWalk(node: TreeSitterNode, definitions: Definition[]):
   }
 }
 
+/**
+ * Walk the AST to find destructured const bindings (query patterns don't match object_pattern).
+ * e.g. `const { handleToken, checkPermissions } = initAuth(config)`
+ */
+function extractDestructuredBindingsWalk(node: TreeSitterNode, definitions: Definition[]): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (FUNCTION_SCOPE_TYPES.has(child.type)) continue;
+
+    let declNode = child;
+    if (child.type === 'export_statement') {
+      const inner = child.childForFieldName('declaration');
+      if (inner) declNode = inner;
+    }
+
+    const t = declNode.type;
+    if (
+      (t === 'lexical_declaration' || t === 'variable_declaration') &&
+      declNode.text.startsWith('const ')
+    ) {
+      for (let j = 0; j < declNode.childCount; j++) {
+        const declarator = declNode.child(j);
+        if (!declarator || declarator.type !== 'variable_declarator') continue;
+        const nameN = declarator.childForFieldName('name');
+        if (nameN && nameN.type === 'object_pattern') {
+          extractDestructuredBindings(
+            nameN,
+            declNode.startPosition.row + 1,
+            nodeEndLine(declNode),
+            definitions,
+          );
+        }
+      }
+    }
+
+    if (child.type !== 'export_statement') {
+      extractDestructuredBindingsWalk(child, definitions);
+    }
+  }
+}
+
 /** Extract constant definitions from a `const` declaration node. */
 function extractConstDeclarators(declNode: TreeSitterNode, definitions: Definition[]): void {
   const t = declNode.type;
@@ -637,6 +699,39 @@ function handleTypeAliasDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
   }
 }
 
+/**
+ * Extract definitions from destructured object bindings.
+ * `const { handleToken, checkPermissions } = initAuth(...)` creates definitions
+ * for handleToken and checkPermissions so they can be resolved as call targets.
+ */
+function extractDestructuredBindings(
+  pattern: TreeSitterNode,
+  line: number,
+  endLine: number,
+  definitions: Definition[],
+): void {
+  for (let i = 0; i < pattern.childCount; i++) {
+    const child = pattern.child(i);
+    if (!child) continue;
+    if (
+      child.type === 'shorthand_property_identifier_pattern' ||
+      child.type === 'shorthand_property_identifier'
+    ) {
+      // { handleToken } — shorthand binding
+      definitions.push({ name: child.text, kind: 'function', line, endLine });
+    } else if (child.type === 'pair_pattern' || child.type === 'pair') {
+      // { original: renamed } — renamed binding, use the local alias
+      const value = child.childForFieldName('value');
+      if (
+        value &&
+        (value.type === 'identifier' || value.type === 'shorthand_property_identifier_pattern')
+      ) {
+        definitions.push({ name: value.text, kind: 'function', line, endLine });
+      }
+    }
+  }
+}
+
 function handleVariableDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
   const isConst = node.text.startsWith('const ');
   for (let i = 0; i < node.childCount; i++) {
@@ -667,6 +762,20 @@ function handleVariableDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
             line: node.startPosition.row + 1,
             endLine: nodeEndLine(node),
           });
+        } else if (isConst && nameN.type === 'object_pattern' && !hasFunctionScopeAncestor(node)) {
+          // Destructured bindings: const { handleToken, checkPermissions } = initAuth(...)
+          // Each destructured property becomes a function definition so it can be
+          // resolved when passed as a callback (e.g. router.use(handleToken)).
+          // Restricted to const to avoid creating spurious definitions for
+          // transient let/var destructuring (e.g. let { userId } = parseRequest(req)).
+          // Scope guard mirrors extractDestructuredBindingsWalk (query path) and
+          // handle_var_decl (Rust path) — skips bindings inside function bodies.
+          extractDestructuredBindings(
+            nameN,
+            node.startPosition.row + 1,
+            nodeEndLine(node),
+            ctx.definitions,
+          );
         }
       }
     }
@@ -715,6 +824,7 @@ function handleCallExpr(node: TreeSitterNode, ctx: ExtractorOutput): void {
       const cbDef = extractCallbackDefinition(node, fn);
       if (cbDef) ctx.definitions.push(cbDef);
     }
+    ctx.calls.push(...extractCallbackReferenceCalls(node));
   }
 }
 
@@ -1072,7 +1182,11 @@ function handleVarDeclaratorTypeMap(
       const obj = fn.childForFieldName('object');
       if (obj && obj.type === 'identifier') {
         const objName = obj.text;
-        if (objName[0]! !== objName[0]!.toLowerCase() && !BUILTIN_GLOBALS.has(objName)) {
+        if (
+          objName[0] &&
+          objName[0] !== objName[0].toLowerCase() &&
+          !BUILTIN_GLOBALS.has(objName)
+        ) {
           setTypeMapEntry(typeMap, nameN.text, objName, 0.7);
         }
       }
@@ -1167,6 +1281,181 @@ function extractSubscriptCallInfo(fn: TreeSitterNode, callNode: TreeSitterNode):
   return null;
 }
 
+/**
+ * Callee names that idiomatically accept callback references. Used to gate
+ * member_expression args in {@link extractCallbackReferenceCalls}: arguments
+ * like `user.id` are only emitted as dynamic callback calls when the callee
+ * is a known callback-accepting API (router/middleware, promises, array
+ * methods, event emitters, scheduling APIs). This avoids false positives
+ * from plain property reads passed as data, e.g. `store.set(user.id, user)`.
+ *
+ * Identifier args (e.g. `router.use(handleToken)`) are always emitted — the
+ * collateral damage of dropping them is larger than the FP risk, since plain
+ * identifier data args rarely collide with real function names.
+ */
+const CALLBACK_ACCEPTING_CALLEES: ReadonlySet<string> = new Set([
+  // Express / router / middleware
+  'use',
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'options',
+  'head',
+  'all',
+  // Promises
+  'then',
+  'catch',
+  'finally',
+  // Array iteration / reduction
+  'map',
+  'filter',
+  'forEach',
+  'find',
+  'findIndex',
+  'findLast',
+  'findLastIndex',
+  'some',
+  'every',
+  'reduce',
+  'reduceRight',
+  'flatMap',
+  'sort',
+  // Event emitters / DOM
+  'on',
+  'once',
+  'off',
+  'addListener',
+  'removeListener',
+  'addEventListener',
+  'removeEventListener',
+  'subscribe',
+  'unsubscribe',
+  // Scheduling / plain function callbacks
+  'setTimeout',
+  'setInterval',
+  'setImmediate',
+  'queueMicrotask',
+  'requestAnimationFrame',
+  'requestIdleCallback',
+  'nextTick',
+  // Commander / yargs / hooks
+  'action',
+  'command',
+]);
+
+/**
+ * HTTP-verb callees that double as Map/cache/repository method names (`get`,
+ * `post`, `put`, `delete`, `patch`, `options`, `head`, `all`). Express/router
+ * invocations always take a string-literal route path as the first argument
+ * (`app.get('/path', handler)`), whereas Map-like APIs pass values/keys
+ * (`cache.get(user.id)`). Requiring a string-literal first arg keeps real
+ * route handlers covered while dropping the Map/cache false-positive surface.
+ *
+ * `use` and `all` without a path are legitimate middleware registrations, so
+ * `use` is intentionally excluded here — it stays in the general allowlist.
+ */
+const HTTP_VERB_CALLEES: ReadonlySet<string> = new Set([
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'options',
+  'head',
+  'all',
+]);
+
+/**
+ * Extract the callee's final name (function identifier or member expression
+ * property) for callback-eligibility filtering. Returns null if the callee
+ * shape is not analyzable (e.g. computed subscripts, IIFEs).
+ *
+ * Optional-chaining (`obj?.method(...)`) is handled transparently: in both
+ * tree-sitter-javascript and tree-sitter-typescript grammars `obj?.method` is
+ * still a `member_expression` (the `?.` appears as an `optional_chain` child),
+ * so the property extraction below returns `method` as expected.
+ */
+function extractCalleeName(callNode: TreeSitterNode): string | null {
+  const fn = callNode.childForFieldName('function');
+  if (!fn) return null;
+  if (fn.type === 'identifier') return fn.text;
+  if (fn.type === 'member_expression') {
+    const prop = fn.childForFieldName('property');
+    return prop ? prop.text : null;
+  }
+  return null;
+}
+
+/**
+ * True iff the first argument of an arguments node is a string literal.
+ * Used to distinguish Express/router route handlers (`app.get('/path', h)`)
+ * from Map/cache APIs that reuse the same verb names (`cache.get(user.id)`).
+ */
+function firstArgIsStringLiteral(argsNode: TreeSitterNode): boolean {
+  for (let i = 0; i < argsNode.childCount; i++) {
+    const child = argsNode.child(i);
+    if (!child) continue;
+    // Skip parens and commas; the first non-punctuation child is the first arg.
+    if (child.type === '(' || child.type === ',' || child.type === ')') continue;
+    return child.type === 'string' || child.type === 'template_string';
+  }
+  return false;
+}
+
+/**
+ * Extract Call entries for named function references passed as arguments.
+ * e.g. `router.use(handleToken, checkAuth)` yields calls to handleToken and checkAuth.
+ * `app.use(auth.validate)` yields a call to validate with receiver auth.
+ * Skips literals, objects, arrays, anonymous functions, and call expressions (already handled).
+ *
+ * To avoid false positives where plain property reads are passed as data
+ * (e.g. `store.set(user.id, user)` — `user.id` is a value, not a callback),
+ * member_expression args are only emitted when the callee is in
+ * {@link CALLBACK_ACCEPTING_CALLEES}. Identifier args are always emitted.
+ *
+ * HTTP-verb callees (`get`, `post`, `put`, `delete`, `patch`, `options`,
+ * `head`, `all`) double as Map/cache/repository method names, so their
+ * member-expr args are only emitted when the first argument is a string
+ * literal route path — matching Express/router shape and skipping
+ * `cache.get(user.id)`-style calls.
+ */
+function extractCallbackReferenceCalls(callNode: TreeSitterNode): Call[] {
+  const args = callNode.childForFieldName('arguments') || findChild(callNode, 'arguments');
+  if (!args) return [];
+
+  const calleeName = extractCalleeName(callNode);
+  let memberExprArgsAllowed = calleeName !== null && CALLBACK_ACCEPTING_CALLEES.has(calleeName);
+  if (memberExprArgsAllowed && calleeName !== null && HTTP_VERB_CALLEES.has(calleeName)) {
+    // HTTP verbs require a string-literal route path to be treated as a
+    // callback-accepting API; otherwise `cache.get(user.id)` etc. would
+    // still emit `id` as a dynamic call.
+    memberExprArgsAllowed = firstArgIsStringLiteral(args);
+  }
+
+  const result: Call[] = [];
+  const callLine = callNode.startPosition.row + 1;
+
+  for (let i = 0; i < args.childCount; i++) {
+    const child = args.child(i);
+    if (!child) continue;
+
+    if (child.type === 'identifier') {
+      result.push({ name: child.text, line: callLine, dynamic: true });
+    } else if (child.type === 'member_expression' && memberExprArgsAllowed) {
+      const prop = child.childForFieldName('property');
+      const obj = child.childForFieldName('object');
+      if (prop) {
+        const receiver = extractReceiverName(obj);
+        result.push({ name: prop.text, line: callLine, dynamic: true, receiver });
+      }
+    }
+  }
+
+  return result;
+}
+
 function findAnonymousCallback(argsNode: TreeSitterNode): TreeSitterNode | null {
   for (let i = 0; i < argsNode.childCount; i++) {
     const child = argsNode.child(i);

package/src/features/boundaries.ts

@@ -1,34 +1,9 @@
 import { isTestFile } from '../infrastructure/test-filter.js';
 import { BoundaryError } from '../shared/errors.js';
+import { globToRegex } from '../shared/globs.js';
 import type { BetterSqlite3Database } from '../types.js';
 
-// ─── Glob-to-Regex ───────────────────────────────────────────────────
-
-export function globToRegex(pattern: string): RegExp {
-  let re = '';
-  let i = 0;
-  while (i < pattern.length) {
-    const ch = pattern[i] as string;
-    if (ch === '*' && pattern[i + 1] === '*') {
-      re += '.*';
-      i += 2;
-      if (pattern[i] === '/') i++;
-    } else if (ch === '*') {
-      re += '[^/]*';
-      i++;
-    } else if (ch === '?') {
-      re += '[^/]';
-      i++;
-    } else if (/[.+^${}()|[\]\\]/.test(ch)) {
-      re += `\\${ch}`;
-      i++;
-    } else {
-      re += ch;
-      i++;
-    }
-  }
-  return new RegExp(`^${re}$`);
-}
+export { globToRegex };
 
 // ─── Presets ─────────────────────────────────────────────────────────
 

package/src/features/snapshot.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getDatabase } from '../db/better-sqlite3.js';
@@ -37,24 +38,77 @@ export function snapshotSave(
   const dir = snapshotsDir(dbPath);
   const dest = path.join(dir, `${name}.db`);
 
-  if (fs.existsSync(dest)) {
-    if (!options.force) {
-      throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
-    }
-    fs.unlinkSync(dest);
-    debug(`Deleted existing snapshot: ${dest}`);
+  // Cheap fail-fast for the common non-force case; the authoritative check
+  // below uses an atomic linkSync that closes the TOCTOU window.
+  if (!options.force && fs.existsSync(dest)) {
+    throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
   }
 
   fs.mkdirSync(dir, { recursive: true });
 
+  // VACUUM INTO a unique temp path on the same filesystem, then atomically
+  // place it at the destination. This closes the TOCTOU window between
+  // existsSync/unlinkSync/VACUUM INTO where two concurrent saves could
+  // observe a missing file or interleave their VACUUM writes.
+  //
+  // Unique temp name: process.pid is shared across worker_threads in the
+  // same process, so we add random bytes to keep concurrent callers in any
+  // thread from colliding on the temp path.
+  const tmp = path.join(
+    dir,
+    `.${name}.db.tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`,
+  );
+  try {
+    fs.unlinkSync(tmp);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+
   const Database = getDatabase();
   const db = new Database(dbPath, { readonly: true });
   try {
-    db.exec(`VACUUM INTO '${dest.replace(/'/g, "''")}'`);
+    db.exec(`VACUUM INTO '${tmp.replace(/'/g, "''")}'`);
   } finally {
     db.close();
   }
 
+  try {
+    if (options.force) {
+      // renameSync overwrites atomically — the correct semantics for --force.
+      fs.renameSync(tmp, dest);
+    } else {
+      // Non-force path: linkSync fails atomically with EEXIST if dest exists,
+      // closing the TOCTOU window between existsSync above and the final
+      // placement. We then unlink the temp file; on POSIX and NTFS, link
+      // creates a second reference so tmp can safely be removed.
+      try {
+        fs.linkSync(tmp, dest);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+          throw new ConfigError(`Snapshot "${name}" already exists. Use --force to overwrite.`);
+        }
+        throw err;
+      }
+      try {
+        fs.unlinkSync(tmp);
+      } catch (cleanupErr) {
+        // Best-effort — dest is already in place, so a leftover tmp file is
+        // harmless. Log at debug so repeated failures surface during
+        // troubleshooting without noising up normal operation.
+        debug(`snapshotSave: failed to remove temp file ${tmp}: ${cleanupErr}`);
+      }
+    }
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if ((cleanupErr as NodeJS.ErrnoException).code !== 'ENOENT') {
+        debug(`snapshotSave: failed to remove temp file ${tmp}: ${cleanupErr}`);
+      }
+    }
+    throw err;
+  }
+
   const stat = fs.statSync(dest);
   debug(`Snapshot saved: ${dest} (${stat.size} bytes)`);
   return { name, path: dest, size: stat.size };
@@ -74,16 +128,38 @@ export function snapshotRestore(name: string, options: SnapshotDbPathOptions = {
     throw new DbError(`Snapshot "${name}" not found at ${src}`, { file: src });
   }
 
-  // Remove WAL/SHM sidecar files for a clean restore
+  // Remove WAL/SHM sidecars first so the old journal can't be replayed over
+  // the restored DB. unlink then check ENOENT — avoids the existsSync/unlinkSync
+  // race another process could wedge into.
   for (const suffix of ['-wal', '-shm']) {
     const sidecar = dbPath + suffix;
-    if (fs.existsSync(sidecar)) {
+    try {
       fs.unlinkSync(sidecar);
       debug(`Removed sidecar: ${sidecar}`);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+  }
+
+  // Copy to a temp path next to the DB, then rename atomically. Readers that
+  // open dbPath during restore see either the pre-restore or post-restore
+  // file, never a partially-written one.
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const tmp = `${dbPath}.restore-tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`;
+  try {
+    fs.copyFileSync(src, tmp);
+    fs.renameSync(tmp, dbPath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (cleanupErr) {
+      if ((cleanupErr as NodeJS.ErrnoException).code !== 'ENOENT') {
+        debug(`snapshotRestore: failed to remove temp file ${tmp}: ${cleanupErr}`);
+      }
     }
+    throw err;
   }
 
-  fs.copyFileSync(src, dbPath);
   debug(`Restored snapshot "${name}" → ${dbPath}`);
 }
 
@@ -122,10 +198,13 @@ export function snapshotDelete(name: string, options: SnapshotDbPathOptions = {}
   const dir = snapshotsDir(dbPath);
   const target = path.join(dir, `${name}.db`);
 
-  if (!fs.existsSync(target)) {
-    throw new DbError(`Snapshot "${name}" not found at ${target}`, { file: target });
+  try {
+    fs.unlinkSync(target);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new DbError(`Snapshot "${name}" not found at ${target}`, { file: target });
+    }
+    throw err;
   }
-
-  fs.unlinkSync(target);
   debug(`Deleted snapshot: ${target}`);
 }

package/src/features/structure.ts

@@ -166,6 +166,22 @@ function computeFileMetrics(
   fanOutMap: Map<string, number>,
 ): void {
   db.transaction(() => {
+    // Batch-load import counts per file (distinct imported files,
+    // matching the fast-path semantics in updateChangedFileMetrics).
+    // Runs inside the transaction for parity with the Rust path.
+    const importCountMap = new Map<string, number>();
+    for (const row of db
+      .prepare(
+        `SELECT n1.file AS src, COUNT(DISTINCT n2.file) AS cnt FROM edges e
+         JOIN nodes n1 ON e.source_id = n1.id
+         JOIN nodes n2 ON e.target_id = n2.id
+         WHERE e.kind = 'imports'
+         GROUP BY n1.file`,
+      )
+      .all() as { src: string; cnt: number }[]) {
+      importCountMap.set(row.src, row.cnt);
+    }
+
     for (const [relPath, symbols] of fileSymbols) {
       const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
       if (!fileRow) continue;
@@ -180,7 +196,7 @@ function computeFileMetrics(
           symbolCount++;
         }
       }
-      const importCount = symbols.imports.length;
+      const importCount = importCountMap.get(relPath) || 0;
       const exportCount = symbols.exports.length;
       const fanIn = fanInMap.get(relPath) || 0;
       const fanOut = fanOutMap.get(relPath) || 0;

package/src/graph/algorithms/louvain.ts

@@ -6,7 +6,7 @@
  * JS fallback: Leiden algorithm via `detectClusters` (always undirected, `directed: false`).
  */
 
-import { warn } from '../../infrastructure/logger.js';
+import { debug } from '../../infrastructure/logger.js';
 import { loadNative } from '../../infrastructure/native.js';
 import type { CodeGraph } from '../model.js';
 import type { DetectClustersResult } from './leiden/index.js';
@@ -36,10 +36,8 @@ export function louvainCommunities(graph: CodeGraph, opts: LouvainOptions = {}):
 
   const native = loadNative();
   if (native?.louvainCommunities) {
-    // maxLevels, maxLocalPasses, and refinementTheta are Leiden-specific tuning knobs
-    // not supported by the Rust Louvain implementation. Warn callers who set them.
     if (opts.maxLevels != null || opts.maxLocalPasses != null || opts.refinementTheta != null) {
-      warn(
+      debug(
         'louvainCommunities: maxLevels/maxLocalPasses/refinementTheta are ignored by the native Rust path',
       );
     }

package/src/infrastructure/config.ts

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { toErrorMessage } from '../shared/errors.js';
+import { ConfigError, toErrorMessage } from '../shared/errors.js';
 import type { CodegraphConfig } from '../types.js';
 import { debug, warn } from './logger.js';
 
@@ -179,6 +179,7 @@ export function loadConfig(cwd?: string): CodegraphConfig {
         _configCache.set(cwd, structuredClone(result));
         return result;
       } catch (err: unknown) {
+        if (err instanceof ConfigError) throw err;
         debug(`Failed to parse config ${filePath}: ${toErrorMessage(err)}`);
       }
     }
@@ -215,7 +216,16 @@ export function applyEnvOverrides(config: CodegraphConfig): CodegraphConfig {
 
 export function resolveSecrets(config: CodegraphConfig): CodegraphConfig {
   const cmd = config.llm.apiKeyCommand;
-  if (typeof cmd !== 'string' || cmd.trim() === '') return config;
+  if (cmd == null) return config;
+  if (typeof cmd !== 'string') {
+    const actual = Array.isArray(cmd) ? 'array' : typeof cmd;
+    throw new ConfigError(
+      `llm.apiKeyCommand must be a string (received ${actual}). ` +
+        'The command is split on whitespace and executed without a shell. ' +
+        'Example: "apiKeyCommand": "op read op://vault/openai/api-key"',
+    );
+  }
+  if (cmd.trim() === '') return config;
 
   const parts = cmd.trim().split(/\s+/);
   const [executable, ...args] = parts;