@optave/codegraph 3.9.4 → 3.9.6

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/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;

package/src/shared/globs.ts

@@ -0,0 +1,121 @@
+/**
+ * Glob → RegExp conversion utilities.
+ *
+ * Shared by boundary rules (`features/boundaries.ts`) and the file-collection
+ * include/exclude filters (`domain/graph/builder/helpers.ts`). Keeping a single
+ * implementation ensures users get consistent glob semantics everywhere.
+ *
+ * Supported syntax:
+ *   - `**` matches any sequence of characters including `/`
+ *   - `*`  matches any sequence of characters except `/`
+ *   - `?`  matches a single non-slash character
+ *   - other regex metacharacters are escaped literally
+ *
+ * Paths must use forward slashes (callers normalize before testing).
+ */
+
+/**
+ * Compile a glob pattern into a `RegExp` anchored with `^…$`.
+ */
+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] === '*') {
+      i += 2;
+      if (pattern[i] === '/') {
+        // `**/` matches zero or more full path segments, preserving the
+        // directory boundary before the next segment. Without this, patterns
+        // like `**/foo.ts` would compile to `^.*foo\.ts$` and match
+        // `barfoo.ts`, diverging from Rust `globset` semantics.
+        re += '(?:[^/]+/)*';
+        i++;
+      } else {
+        // Bare `**` (e.g. `dir/**`, or trailing) matches anything.
+        re += '.*';
+      }
+    } 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}$`);
+}
+
+const EMPTY_REGEX_LIST: readonly RegExp[] = Object.freeze([]) as readonly RegExp[];
+
+// Compile results are cached by pattern content so a long-running host
+// (watch mode, MCP server) doesn't recompile on every buildGraph call.
+// Capped to avoid unbounded growth when callers pass many distinct lists.
+const COMPILE_CACHE_MAX = 32;
+const compileCache = new Map<string, readonly RegExp[]>();
+
+function buildCacheKey(patterns: readonly string[]): string {
+  // JSON.stringify avoids ambiguity when patterns legitimately contain any
+  // single character (including control characters or separators a caller
+  // might choose): ["a", "bc"] → '["a","bc"]' vs ["ab", "c"] → '["ab","c"]'.
+  return JSON.stringify(patterns);
+}
+
+/**
+ * Compile a list of glob patterns. Invalid / empty patterns are skipped.
+ *
+ * Results are memoized per pattern-content so repeated `buildGraph` calls
+ * with the same include/exclude lists reuse the compiled regexes. The
+ * returned array is shared across callers and must not be mutated.
+ */
+export function compileGlobs(patterns: readonly string[] | undefined): readonly RegExp[] {
+  if (!patterns || patterns.length === 0) return EMPTY_REGEX_LIST;
+  const key = buildCacheKey(patterns);
+  const cached = compileCache.get(key);
+  if (cached) return cached;
+  const out: RegExp[] = [];
+  for (const p of patterns) {
+    if (typeof p !== 'string' || p.length === 0) continue;
+    try {
+      out.push(globToRegex(p));
+    } catch {
+      // Ignore malformed patterns rather than failing the whole build.
+    }
+  }
+  const frozen = Object.freeze(out) as readonly RegExp[];
+  if (compileCache.size >= COMPILE_CACHE_MAX) {
+    // FIFO eviction — Map iterates insertion order. Config pattern sets
+    // are small and stable, so a simple cap is sufficient.
+    const first = compileCache.keys().next().value;
+    if (first !== undefined) compileCache.delete(first);
+  }
+  compileCache.set(key, frozen);
+  return frozen;
+}
+
+/**
+ * Clear the compiled-glob cache. Intended for long-running hosts that
+ * need to reload config (e.g. watch mode after `.codegraphrc.json` edits)
+ * and for test isolation.
+ */
+export function clearGlobCache(): void {
+  compileCache.clear();
+}
+
+/**
+ * `true` when at least one compiled pattern matches the given path.
+ *
+ * The path must already be normalized to forward slashes.
+ */
+export function matchesAny(regexes: readonly RegExp[], path: string): boolean {
+  for (const re of regexes) {
+    if (re.test(path)) return true;
+  }
+  return false;
+}

package/src/types.ts

@@ -1033,7 +1033,23 @@ export interface PipelineContext {
   lineCountMap: Map<string, number>;
 
   // Phase timing
-  timing: Record<string, number>;
+  timing: {
+    setupMs?: number;
+    collectMs?: number;
+    detectMs?: number;
+    parseMs?: number;
+    insertMs?: number;
+    resolveMs?: number;
+    edgesMs?: number;
+    structureMs?: number;
+    rolesMs?: number;
+    astMs?: number;
+    complexityMs?: number;
+    cfgMs?: number;
+    dataflowMs?: number;
+    finalizeMs?: number;
+    [key: string]: number | undefined;
+  };
   buildStart: number;
 }
 
@@ -1053,6 +1069,8 @@ export interface BuildGraphOpts {
 export interface BuildResult {
   phases: {
     setupMs: number;
+    collectMs: number;
+    detectMs: number;
     parseMs: number;
     insertMs: number;
     resolveMs: number;
@@ -1104,6 +1122,13 @@ export interface CodegraphConfig {
     model: string | null;
     baseUrl: string | null;
     apiKey: string | null;
+    /**
+     * Command that prints the API key to stdout. Must be a single string —
+     * it is split on whitespace and executed via `execFileSync` with no shell,
+     * so shell features like `$(...)`, pipes, globs, or variable expansion are
+     * not supported. Example: `"op read op://vault/openai/api-key"`. Non-string
+     * values are rejected with a `ConfigError` at load time.
+     */
     apiKeyCommand: string | null;
   };