@optave/codegraph 3.12.0 → 3.13.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,aAAa,EACb,SAAS,EACT,SAAS,EACT,SAAS,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,GACX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,OAAO,EACP,WAAW,EACX,UAAU,EACV,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,aAAa,EACb,SAAS,EACT,SAAS,EACT,SAAS,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,UAAU,GACX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,UAAU,EACV,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,OAAO,EACP,WAAW,EACX,UAAU,EACV,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/infrastructure/config.d.ts

@@ -12,7 +12,7 @@ export declare const DEFAULTS: {
         dbPath: string;
         driftThreshold: number;
         smallFilesThreshold: number;
-        typescriptResolver: false;
+        typescriptResolver: true;
     };
     query: {
         defaultDepth: number;
@@ -114,7 +114,7 @@ export declare const DEFAULTS: {
          * Maximum fixed-point iterations for the Phase 8.3 points-to solver.
          * @reserved — currently not wired to either the WASM solver
          * (`MAX_SOLVER_ITERATIONS` in `points-to.ts`) or the native Rust solver
-         * (`MAX_SOLVER_ITERATIONS` in `edge_builder.rs`), both of which use the
+         * (`MAX_SOLVER_ITERATIONS` in `stages/build_edges.rs`), both of which use the
          * same hardcoded value of 50.  See the TODO comment above.
          */
         pointsToMaxIterations: number;
@@ -177,17 +177,90 @@ export declare const DEFAULTS: {
         disabledTools: string[];
     };
 };
+/**
+ * Set the per-run user-config override from CLI flags.
+ * Called by the CLI preAction hook before any command executes.
+ * - false  → --no-user-config
+ * - string → --user-config <path>
+ * - true   → --user-config (bare, use default global file)
+ * - undefined → clear override, revert to consent-based resolution
+ */
+export declare function setUserConfigOverride(v: string | boolean | undefined): void;
+/**
+ * Return the canonical path where a new global config file should be written.
+ *
+ * Uses the same priority logic as resolveUserConfigPath() but always returns a
+ * path — it does not check whether the file exists. Used by `--init` to know
+ * where to scaffold the file.
+ *
+ * Priority:
+ * 1. CODEGRAPH_USER_CONFIG env var (used as-is)
+ * 2. $XDG_CONFIG_HOME/codegraph/config.json
+ *    %APPDATA%\codegraph\config.json  (Windows)
+ *    fallback: ~/.config/codegraph/config.json
+ */
+export declare function getDefaultUserConfigPath(): string;
+/**
+ * Resolve the absolute path to the user-level global config file.
+ *
+ * Priority:
+ * 1. CODEGRAPH_USER_CONFIG env var (location override only — not forced-on)
+ * 2. $XDG_CONFIG_HOME/codegraph/config.json  (Unix/macOS)
+ *    %APPDATA%\codegraph\config.json          (Windows)
+ *    fallback: ~/.config/codegraph/config.json
+ * 3. ~/.codegraph/config.json  (legacy, next to registry.json)
+ *
+ * Returns the path of the first existing file, or null if none exist.
+ */
+export declare function resolveUserConfigPath(): string | null;
+export declare function getLastAppliedGlobalPath(): string | null;
+export declare function getLastAppliedGlobalConfig(): Record<string, unknown> | null;
+/**
+ * Compute a short stable hash of the build-relevant config subset.
+ * Used by the pipeline to detect config changes that require a full rebuild.
+ */
+export declare function computeConfigHash(config: CodegraphConfig): string;
+/**
+ * When called from the build command, check whether we should prompt the user
+ * for global-config consent and, if so, prompt and persist the answer.
+ *
+ * Only fires when ALL of:
+ *   - A global config file exists
+ *   - The repo is undecided (no recorded consent)
+ *   - Not matched by appliesTo globs
+ *   - process.stdin.isTTY && process.stdout.isTTY
+ *   - CI env is not set
+ *   - No per-run --user-config / --no-user-config flag is active
+ */
+export declare function promptForConsentIfNeeded(rootDir: string, registryPath?: string): Promise<void>;
+/** Options for loadConfig. */
+export interface LoadConfigOpts {
+    /** Per-run user-config override (from CLI flags or programmatic call). */
+    userConfig?: string | boolean;
+    /** Registry path override (mainly for tests). */
+    registryPath?: string;
+}
 /**
  * Load project configuration from a .codegraphrc.json or similar file.
- * Returns merged config with defaults. Results are cached per cwd.
+ * Returns merged config with defaults: defaults → global (if applied) → project → env → secrets.
+ * Results are cached per cwd + applied global path.
  */
-export declare function loadConfig(cwd?: string): CodegraphConfig;
+export declare function loadConfig(cwd?: string, opts?: LoadConfigOpts): CodegraphConfig;
 /**
  * Clear the config cache. Intended for long-running processes that need to
  * pick up on-disk config changes, and for test isolation when tests share
  * the same cwd.
  */
 export declare function clearConfigCache(): void;
+/**
+ * Load config and return it together with per-key provenance information.
+ * Used by `codegraph config --explain`.
+ *
+ * Calls loadConfig first so _lastAppliedGlobalConfig is populated, then uses
+ * that cached data for the global-layer provenance — avoiding a second disk
+ * read and eliminating the TOCTOU window between the two reads.
+ */
+export declare function loadConfigWithProvenance(cwd?: string, opts?: LoadConfigOpts): import('../types.js').ConfigWithProvenance;
 export declare function applyEnvOverrides(config: CodegraphConfig): CodegraphConfig;
 export declare function resolveSecrets(config: CodegraphConfig): CodegraphConfig;
 interface WorkspaceEntry {

package/dist/infrastructure/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/infrastructure/config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAIzC,CAAC;AAEF,eAAO,MAAM,QAAQ;aACJ,MAAM,EAAE;aACR,MAAM,EAAE;gBACL,MAAM,EAAE;gBACR,MAAM,EAAE;aACX,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;eAaR,MAAM,GAAG,IAAI;qBAAuB,MAAM,GAAG,IAAI;;;kBAE1D,MAAM,GAAG,IAAI;eAChB,MAAM,GAAG,IAAI;iBACX,MAAM,GAAG,IAAI;gBACd,MAAM,GAAG,IAAI;uBACN,MAAM,GAAG,IAAI;;;;;;;;;;yBAGc,MAAM,GAAG,IAAI;;;;;;;;;;;;;;;sBAMb,MAAM,GAAG,IAAI;;;sBAChC,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;sBAC1C,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;sBAC5C,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;sBAC9C,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;sBACzC,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;sBACxC,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;sBACxC,MAAM,GAAG,IAAI;sBAAgB,MAAM,GAAG,IAAI;;;oBAEpD,OAAO;;;;qBAIN,MAAM,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;QA2BlC;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;qBAgCE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAsCN,MAAM,EAAE;;CAEN,CAAC;AAM5B;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,CA6BxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAQD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAQ1E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA6BvE;AAwCD,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AA4HD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAc7E;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/infrastructure/config.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/config.js

@@ -1,8 +1,12 @@
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { ConfigError, toErrorMessage } from '../shared/errors.js';
+import { compileGlobs, matchesAny } from '../shared/globs.js';
 import { debug, warn } from './logger.js';
+import { getUserConfigConsent, REGISTRY_PATH, setUserConfigConsent } from './registry.js';
 export const CONFIG_FILES = [
     '.codegraphrc.json',
     '.codegraphrc',
@@ -19,7 +23,7 @@ export const DEFAULTS = {
         dbPath: '.codegraph/graph.db',
         driftThreshold: 0.2,
         smallFilesThreshold: 5,
-        typescriptResolver: false,
+        typescriptResolver: true,
     },
     query: {
         defaultDepth: 3,
@@ -85,7 +89,7 @@ export const DEFAULTS = {
          * Maximum fixed-point iterations for the Phase 8.3 points-to solver.
          * @reserved — currently not wired to either the WASM solver
          * (`MAX_SOLVER_ITERATIONS` in `points-to.ts`) or the native Rust solver
-         * (`MAX_SOLVER_ITERATIONS` in `edge_builder.rs`), both of which use the
+         * (`MAX_SOLVER_ITERATIONS` in `stages/build_edges.rs`), both of which use the
          * same hardcoded value of 50.  See the TODO comment above.
          */
         pointsToMaxIterations: 50,
@@ -160,33 +164,352 @@ export const DEFAULTS = {
         disabledTools: [],
     },
 };
+// ── Per-process user-config override (set by CLI flags) ────────────────
+// Set once by the preAction hook before any command runs; cleared when changed.
+let _userConfigOverride;
+/**
+ * Set the per-run user-config override from CLI flags.
+ * Called by the CLI preAction hook before any command executes.
+ * - false  → --no-user-config
+ * - string → --user-config <path>
+ * - true   → --user-config (bare, use default global file)
+ * - undefined → clear override, revert to consent-based resolution
+ */
+export function setUserConfigOverride(v) {
+    _userConfigOverride = v;
+    _configCache.clear();
+    _globalConfigCache.clear();
+}
 // Per-cwd config cache — avoids re-reading the config file on every query call.
-// The config file rarely changes within a single process lifetime.
+// Key includes the applied global path so toggled flags/consent are reflected.
 const _configCache = new Map();
+// Parallel cache for the sanitized global layer — needed so loadConfigWithProvenance
+// can correctly attribute global-layer keys even on a _configCache hit.
+const _globalConfigCache = new Map();
+// ── Global config file location ─────────────────────────────────────────
+/**
+ * Return the canonical path where a new global config file should be written.
+ *
+ * Uses the same priority logic as resolveUserConfigPath() but always returns a
+ * path — it does not check whether the file exists. Used by `--init` to know
+ * where to scaffold the file.
+ *
+ * Priority:
+ * 1. CODEGRAPH_USER_CONFIG env var (used as-is)
+ * 2. $XDG_CONFIG_HOME/codegraph/config.json
+ *    %APPDATA%\codegraph\config.json  (Windows)
+ *    fallback: ~/.config/codegraph/config.json
+ */
+export function getDefaultUserConfigPath() {
+    const envPath = process.env.CODEGRAPH_USER_CONFIG;
+    if (envPath)
+        return envPath;
+    const home = os.homedir();
+    const xdgConfig = process.env.XDG_CONFIG_HOME;
+    if (xdgConfig)
+        return path.join(xdgConfig, 'codegraph', 'config.json');
+    if (process.platform === 'win32') {
+        const appdata = process.env.APPDATA;
+        return appdata
+            ? path.join(appdata, 'codegraph', 'config.json')
+            : path.join(home, '.config', 'codegraph', 'config.json');
+    }
+    return path.join(home, '.config', 'codegraph', 'config.json');
+}
+/**
+ * Resolve the absolute path to the user-level global config file.
+ *
+ * Priority:
+ * 1. CODEGRAPH_USER_CONFIG env var (location override only — not forced-on)
+ * 2. $XDG_CONFIG_HOME/codegraph/config.json  (Unix/macOS)
+ *    %APPDATA%\codegraph\config.json          (Windows)
+ *    fallback: ~/.config/codegraph/config.json
+ * 3. ~/.codegraph/config.json  (legacy, next to registry.json)
+ *
+ * Returns the path of the first existing file, or null if none exist.
+ */
+export function resolveUserConfigPath() {
+    const envPath = process.env.CODEGRAPH_USER_CONFIG;
+    if (envPath) {
+        if (fs.existsSync(envPath))
+            return envPath;
+        debug(`CODEGRAPH_USER_CONFIG points to missing file: ${envPath}`);
+        return null;
+    }
+    const home = os.homedir();
+    // XDG_CONFIG_HOME takes priority on all platforms when explicitly set.
+    // Falls back to %APPDATA% on Windows, or ~/.config on Unix/macOS.
+    let platformDefault;
+    const xdgConfig = process.env.XDG_CONFIG_HOME;
+    if (xdgConfig) {
+        platformDefault = path.join(xdgConfig, 'codegraph', 'config.json');
+    }
+    else if (process.platform === 'win32') {
+        const appdata = process.env.APPDATA;
+        platformDefault = appdata
+            ? path.join(appdata, 'codegraph', 'config.json')
+            : path.join(home, '.config', 'codegraph', 'config.json');
+    }
+    else {
+        platformDefault = path.join(home, '.config', 'codegraph', 'config.json');
+    }
+    if (fs.existsSync(platformDefault))
+        return platformDefault;
+    const legacyPath = path.join(home, '.codegraph', 'config.json');
+    if (fs.existsSync(legacyPath))
+        return legacyPath;
+    return null;
+}
+/**
+ * Read and parse a user-level global config file.
+ * Handles both plain-config and appliesTo-wrapper formats.
+ * Returns null on missing or malformed files (never throws).
+ */
+function loadUserConfigFile(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // Wrapper format: { appliesTo: [...], config: {...} }
+        if ('appliesTo' in parsed && typeof parsed.config === 'object' && parsed.config !== null) {
+            const globs = Array.isArray(parsed.appliesTo)
+                ? parsed.appliesTo.filter((g) => typeof g === 'string')
+                : [];
+            return { globalConfig: parsed.config, appliesToGlobs: globs };
+        }
+        // Plain config (no appliesTo wrapper)
+        return { globalConfig: parsed, appliesToGlobs: [] };
+    }
+    catch (err) {
+        debug(`Failed to load user config at ${filePath}: ${toErrorMessage(err)}`);
+        return null;
+    }
+}
+// ── Safety sanitisation ─────────────────────────────────────────────────
+/**
+ * Drop any unsafe keys from the global layer before merging.
+ * Currently: absolute build.dbPath (would make all repos share one DB).
+ * Relative dbPaths resolve per-repo and are allowed through unchanged.
+ */
+function sanitizeUserLayer(raw) {
+    const build = raw.build;
+    if (build && typeof build.dbPath === 'string' && path.isAbsolute(build.dbPath)) {
+        warn(`User config: build.dbPath "${build.dbPath}" is absolute and was ignored ` +
+            '(an absolute dbPath would share one database across all repos).');
+        const sanitizedBuild = { ...build };
+        delete sanitizedBuild.dbPath;
+        return { ...raw, build: sanitizedBuild };
+    }
+    return raw;
+}
+// ── excludeTests shorthand (per-layer) ─────────────────────────────────
+/**
+ * Hoist a top-level `excludeTests` key from a raw layer into `query.excludeTests`.
+ * If the layer already has `query.excludeTests`, that value wins (no-op).
+ * Also removes any stale `excludeTests` key that may have leaked into `merged`.
+ */
+function applyExcludeTestsShorthand(merged, rawLayer) {
+    if ('excludeTests' in rawLayer) {
+        // Only hoist if this layer doesn't also set query.excludeTests
+        if (!(rawLayer.query && 'excludeTests' in rawLayer.query)) {
+            merged.query.excludeTests = Boolean(rawLayer.excludeTests);
+        }
+        const result = { ...merged };
+        delete result.excludeTests;
+        return result;
+    }
+    if ('excludeTests' in merged) {
+        const result = { ...merged };
+        delete result.excludeTests;
+        return result;
+    }
+    return merged;
+}
+/**
+ * Resolve whether the global user config should be applied for a given repo.
+ * Implements the §4.1/§4.2 precedence chain from the spec.
+ *
+ * @param rootDir  Absolute repo root.
+ * @param override Per-run override from CLI flags (_userConfigOverride).
+ * @param registryPath  Optional registry path (for tests).
+ */
+function resolveConsent(rootDir, override, registryPath = REGISTRY_PATH) {
+    // §4.1 step 1: --no-user-config
+    if (override === false) {
+        return { applied: false, globalPath: null, consentDecision: undefined };
+    }
+    // §4.1 steps 2–3: explicit path or bare --user-config
+    if (override !== undefined) {
+        const explicitPath = typeof override === 'string' ? override : resolveUserConfigPath();
+        if (explicitPath && fs.existsSync(explicitPath)) {
+            return { applied: true, globalPath: explicitPath, consentDecision: undefined };
+        }
+        if (typeof override === 'string') {
+            warn(`--user-config path "${override}" does not exist; skipping global layer.`);
+        }
+        return { applied: false, globalPath: null, consentDecision: undefined };
+    }
+    // §4.1 step 4: resolve global file — if none, NOT applied
+    const globalPath = resolveUserConfigPath();
+    if (!globalPath) {
+        return { applied: false, globalPath: null, consentDecision: undefined };
+    }
+    // §4.2: check per-repo decision
+    const consentDecision = getUserConfigConsent(rootDir, registryPath);
+    // §4.2 step 1: recorded disabled
+    if (consentDecision === 'disabled') {
+        return { applied: false, globalPath, consentDecision };
+    }
+    // §4.2 step 2: recorded enabled
+    if (consentDecision === 'enabled') {
+        return { applied: true, globalPath, consentDecision };
+    }
+    // §4.2 step 3: appliesTo glob match (dynamic, never persisted)
+    const parsed = loadUserConfigFile(globalPath);
+    if (parsed?.appliesToGlobs.length) {
+        const expanded = parsed.appliesToGlobs.map((g) => g.startsWith('~') ? path.join(os.homedir(), g.slice(1)) : g);
+        const regexes = compileGlobs(expanded);
+        const absRoot = path.resolve(rootDir);
+        if (matchesAny(regexes, absRoot)) {
+            return { applied: true, globalPath, consentDecision: undefined };
+        }
+    }
+    // §4.2 steps 4–5: undecided — caller decides whether to prompt
+    return { applied: false, globalPath, consentDecision: undefined };
+}
+// Last applied global path and parsed data — exposed so pipeline.ts and
+// loadConfigWithProvenance can reuse the already-parsed file contents without a
+// second disk read (eliminating the TOCTOU window between loadConfig and callers).
+let _lastAppliedGlobalPath = null;
+let _lastAppliedGlobalConfig = null;
+export function getLastAppliedGlobalPath() {
+    return _lastAppliedGlobalPath;
+}
+export function getLastAppliedGlobalConfig() {
+    return _lastAppliedGlobalConfig;
+}
+// ── Build-relevant config hash ──────────────────────────────────────────
+const BUILD_HASH_KEYS = [
+    'include',
+    'exclude',
+    'ignoreDirs',
+    'extensions',
+    'aliases',
+    'build',
+];
+/**
+ * Compute a short stable hash of the build-relevant config subset.
+ * Used by the pipeline to detect config changes that require a full rebuild.
+ */
+export function computeConfigHash(config) {
+    const subset = {};
+    for (const k of BUILD_HASH_KEYS) {
+        subset[k] = config[k];
+    }
+    return createHash('sha256').update(JSON.stringify(subset)).digest('hex').slice(0, 16);
+}
+// ── Interactive consent prompt ──────────────────────────────────────────
+/**
+ * When called from the build command, check whether we should prompt the user
+ * for global-config consent and, if so, prompt and persist the answer.
+ *
+ * Only fires when ALL of:
+ *   - A global config file exists
+ *   - The repo is undecided (no recorded consent)
+ *   - Not matched by appliesTo globs
+ *   - process.stdin.isTTY && process.stdout.isTTY
+ *   - CI env is not set
+ *   - No per-run --user-config / --no-user-config flag is active
+ */
+export async function promptForConsentIfNeeded(rootDir, registryPath = REGISTRY_PATH) {
+    // No-op if per-run override is active
+    if (_userConfigOverride !== undefined)
+        return;
+    const globalPath = resolveUserConfigPath();
+    if (!globalPath)
+        return;
+    const consentDecision = getUserConfigConsent(rootDir, registryPath);
+    if (consentDecision !== undefined)
+        return; // already decided
+    // Check appliesTo globs (dynamic consent — no prompt needed)
+    const parsed = loadUserConfigFile(globalPath);
+    if (parsed?.appliesToGlobs.length) {
+        const expanded = parsed.appliesToGlobs.map((g) => g.startsWith('~') ? path.join(os.homedir(), g.slice(1)) : g);
+        const regexes = compileGlobs(expanded);
+        const absRoot = path.resolve(rootDir);
+        if (matchesAny(regexes, absRoot))
+            return; // covered by appliesTo
+    }
+    // Only prompt in fully interactive sessions
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return;
+    if (process.env.CI)
+        return;
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.question(`\nA global codegraph config was found at ${globalPath}.\n` +
+            `Apply settings not explicitly configured in this repo to ${path.resolve(rootDir)}? [y/N]\n` +
+            `(remembered per-repo; change later with \`codegraph config --enable-global|--disable-global\`)\n` +
+            `> `, (ans) => {
+            rl.close();
+            resolve(ans.trim().toLowerCase());
+        });
+    });
+    const decided = answer === 'y' || answer === 'yes' ? 'enabled' : 'disabled';
+    setUserConfigConsent(rootDir, decided, registryPath);
+    process.stderr.write(`Global config consent recorded: ${decided}\n`);
+}
 /**
  * Load project configuration from a .codegraphrc.json or similar file.
- * Returns merged config with defaults. Results are cached per cwd.
+ * Returns merged config with defaults: defaults → global (if applied) → project → env → secrets.
+ * Results are cached per cwd + applied global path.
  */
-export function loadConfig(cwd) {
-    cwd = cwd || process.cwd();
-    const cached = _configCache.get(cwd);
-    if (cached)
+export function loadConfig(cwd, opts) {
+    cwd = path.resolve(cwd || process.cwd());
+    // Determine effective override: explicit opts win over module-level variable
+    const override = opts?.userConfig !== undefined ? opts.userConfig : _userConfigOverride;
+    // Resolve consent and global path
+    const { applied, globalPath } = resolveConsent(cwd, override, opts?.registryPath);
+    // Cache key includes applied global path and override flag so toggled consent is reflected
+    const cacheKey = `${cwd}::${applied ? (globalPath ?? 'default') : 'none'}`;
+    // Always update _lastAppliedGlobalPath/_lastAppliedGlobalConfig before returning —
+    // on a cache hit the previous call may have been for a different repo or different
+    // opts, so stale values here would misbehave for programmatic callers making
+    // multiple buildGraph calls in the same process.
+    _lastAppliedGlobalPath = applied ? globalPath : null;
+    _lastAppliedGlobalConfig = null; // updated below if a global file is loaded
+    const cached = _configCache.get(cacheKey);
+    if (cached) {
+        // Restore global config so loadConfigWithProvenance gets correct provenance on cache hits.
+        _lastAppliedGlobalConfig = _globalConfigCache.get(cacheKey) ?? null;
         return structuredClone(cached);
+    }
+    // ── Layer 0: DEFAULTS ─────────────────────────────────────────────
+    let merged = DEFAULTS;
+    // ── Layer 1: global (if applied) ──────────────────────────────────
+    if (applied && globalPath) {
+        const userFileData = loadUserConfigFile(globalPath);
+        if (userFileData) {
+            debug(`Applying global user config from ${globalPath}`);
+            const sanitized = sanitizeUserLayer(userFileData.globalConfig);
+            // Cache the sanitized global data so pipeline.ts and loadConfigWithProvenance
+            // can use it without a second disk read (eliminates TOCTOU window).
+            _lastAppliedGlobalConfig = sanitized;
+            merged = mergeConfig(merged, sanitized);
+            merged = applyExcludeTestsShorthand(merged, sanitized);
+        }
+    }
+    // ── Layer 2: project ──────────────────────────────────────────────
     for (const name of CONFIG_FILES) {
         const filePath = path.join(cwd, name);
         if (fs.existsSync(filePath)) {
             try {
                 const raw = fs.readFileSync(filePath, 'utf-8');
-                const config = JSON.parse(raw);
-                debug(`Loaded config from ${filePath}`);
-                const merged = mergeConfig(DEFAULTS, config);
-                if ('excludeTests' in config && !(config.query && 'excludeTests' in config.query)) {
-                    merged.query.excludeTests = Boolean(config.excludeTests);
-                }
-                delete merged.excludeTests;
-                const result = resolveSecrets(applyEnvOverrides(merged));
-                _configCache.set(cwd, structuredClone(result));
-                return result;
+                const projectConfig = JSON.parse(raw);
+                debug(`Loaded project config from ${filePath}`);
+                merged = mergeConfig(merged, projectConfig);
+                merged = applyExcludeTestsShorthand(merged, projectConfig);
+                break;
             }
             catch (err) {
                 if (err instanceof ConfigError)
@@ -195,9 +518,11 @@ export function loadConfig(cwd) {
             }
         }
     }
-    const defaults = resolveSecrets(applyEnvOverrides({ ...DEFAULTS }));
-    _configCache.set(cwd, structuredClone(defaults));
-    return defaults;
+    // ── Layers 3–4: env overrides + secret resolution ─────────────────
+    const result = resolveSecrets(applyEnvOverrides(merged));
+    _configCache.set(cacheKey, structuredClone(result));
+    _globalConfigCache.set(cacheKey, _lastAppliedGlobalConfig);
+    return result;
 }
 /**
  * Clear the config cache. Intended for long-running processes that need to
@@ -206,6 +531,55 @@ export function loadConfig(cwd) {
  */
 export function clearConfigCache() {
     _configCache.clear();
+    _globalConfigCache.clear();
+}
+/**
+ * Load config and return it together with per-key provenance information.
+ * Used by `codegraph config --explain`.
+ *
+ * Calls loadConfig first so _lastAppliedGlobalConfig is populated, then uses
+ * that cached data for the global-layer provenance — avoiding a second disk
+ * read and eliminating the TOCTOU window between the two reads.
+ */
+export function loadConfigWithProvenance(cwd, opts) {
+    cwd = path.resolve(cwd || process.cwd());
+    const override = opts?.userConfig !== undefined ? opts.userConfig : _userConfigOverride;
+    const { applied, globalPath, consentDecision } = resolveConsent(cwd, override, opts?.registryPath);
+    // Load (or return from cache) the merged config first — this also populates
+    // _lastAppliedGlobalConfig with the already-parsed and sanitized global layer.
+    const config = loadConfig(cwd, opts);
+    // Build provenance by tracking which layer supplies each top-level key
+    const provenance = {};
+    // Layer 0: defaults — everything starts as 'default'
+    for (const k of Object.keys(DEFAULTS))
+        provenance[k] = 'default';
+    // Layer 1: global — reuse the data loadConfig already parsed (no second disk read)
+    const globalRaw = applied && globalPath ? _lastAppliedGlobalConfig : null;
+    if (globalRaw) {
+        for (const k of Object.keys(globalRaw))
+            provenance[k] = 'user';
+    }
+    // Layer 2: project
+    for (const name of CONFIG_FILES) {
+        const filePath = path.join(cwd, name);
+        if (fs.existsSync(filePath)) {
+            try {
+                const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+                for (const k of Object.keys(raw))
+                    provenance[k] = 'project';
+                break;
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    // Layer 3+: env overrides (LLM keys)
+    const ENV_LLM_KEYS = ['CODEGRAPH_LLM_PROVIDER', 'CODEGRAPH_LLM_API_KEY', 'CODEGRAPH_LLM_MODEL'];
+    if (ENV_LLM_KEYS.some((k) => process.env[k] !== undefined)) {
+        provenance.llm = 'env';
+    }
+    return { config, provenance, appliedGlobalPath: applied ? globalPath : null, consentDecision };
 }
 const ENV_LLM_MAP = {
     CODEGRAPH_LLM_PROVIDER: 'provider',