ucn 4.2.2 → 5.0.1

package/core/cache.js

@@ -7,12 +7,302 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
-const { expandGlob, detectProjectPattern, parseGitignore, DEFAULT_IGNORES } = require('./discovery');
+const {
+    expandGlob, detectProjectPattern, parseGitignore, gitTrackedPaths, DEFAULT_IGNORES,
+    classifyUnsupportedSourceFile,
+} = require('./discovery');
+const { codeUnitCompare } = require('./shared');
 
 // Read UCN version for cache invalidation
 const UCN_VERSION = require('../package.json').version;
 
+const CACHE_DIRECTORY_NAME = 'ucn';
+const CACHE_PROJECTS_DIRECTORY = 'projects';
+const LEGACY_CACHE_DIRECTORY = '.ucn-cache';
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const CACHE_PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+const CACHE_MAX_PROJECTS = 128;
+const CACHE_MAX_BYTES = 1024 * 1024 * 1024;
+
+function discoveryRulesHash(root) {
+    return crypto.createHash('md5').update(parseGitignore(root).join('\0')).digest('hex');
+}
+
+/**
+ * Resolve the per-user cache root without writing anything.
+ *
+ * UCN_CACHE_DIR is the explicit override. Otherwise follow the host cache
+ * convention: XDG_CACHE_HOME on Unix, Library/Caches on macOS, and
+ * LOCALAPPDATA on Windows. Every fallback remains below the user's home.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string} [options.platform]
+ * @param {string} [options.homeDir]
+ * @returns {string}
+ */
+function getUserCacheRoot({
+    env = process.env,
+    platform = process.platform,
+    homeDir = os.homedir(),
+} = {}) {
+    const resolveConfiguredPath = (configured) => {
+        const value = String(configured || '').trim();
+        if (!value) return null;
+        if (value === '~') return homeDir;
+        if (value.startsWith('~/') || value.startsWith('~\\')) {
+            return path.resolve(homeDir, value.slice(2));
+        }
+        return path.resolve(value);
+    };
+
+    const explicit = resolveConfiguredPath(env.UCN_CACHE_DIR);
+    if (explicit) return explicit;
+
+    const xdg = resolveConfiguredPath(env.XDG_CACHE_HOME);
+    if (xdg) return path.join(xdg, CACHE_DIRECTORY_NAME);
+
+    if (platform === 'darwin') {
+        return path.join(homeDir, 'Library', 'Caches', CACHE_DIRECTORY_NAME);
+    }
+    if (platform === 'win32') {
+        const localAppData = resolveConfiguredPath(env.LOCALAPPDATA);
+        return localAppData
+            ? path.join(localAppData, CACHE_DIRECTORY_NAME, 'cache')
+            : path.join(homeDir, 'AppData', 'Local', CACHE_DIRECTORY_NAME, 'cache');
+    }
+    return path.join(homeDir, '.cache', CACHE_DIRECTORY_NAME);
+}
+
+/**
+ * Canonicalize a project root for cache identity. Symlinked paths to the same
+ * checkout share one cache, while separate copies remain isolated.
+ *
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function canonicalProjectRoot(projectRoot) {
+    const resolved = path.resolve(projectRoot);
+    try {
+        const realpath = fs.realpathSync.native || fs.realpathSync;
+        return realpath(resolved);
+    } catch (_) {
+        return resolved;
+    }
+}
+
+/**
+ * Return the default cache directory for one project.
+ *
+ * The readable basename aids manual inspection; the canonical-path hash
+ * prevents collisions between unrelated projects with the same directory
+ * name without exposing the full checkout path.
+ *
+ * @param {string} projectRoot
+ * @param {object} [options] - Forwarded to getUserCacheRoot()
+ * @returns {string}
+ */
+function getProjectCacheDir(projectRoot, options) {
+    const canonicalRoot = canonicalProjectRoot(projectRoot);
+    const slug = (path.basename(canonicalRoot) || 'project')
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || 'project';
+    const identity = process.platform === 'win32'
+        ? canonicalRoot.toLowerCase()
+        : canonicalRoot;
+    const hash = crypto.createHash('sha256').update(identity).digest('hex').slice(0, 20);
+    return path.join(getUserCacheRoot(options), CACHE_PROJECTS_DIRECTORY, `${slug}-${hash}`);
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {object} [options]
+ * @returns {string}
+ */
+function getProjectCachePath(projectRoot, options) {
+    return path.join(getProjectCacheDir(projectRoot, options), 'index.json');
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function getLegacyProjectCacheDir(projectRoot) {
+    return path.join(path.resolve(projectRoot), LEGACY_CACHE_DIRECTORY);
+}
+
+/**
+ * Move a legacy project-local cache to the per-user location. Migration is
+ * best-effort because cache availability must never block an analysis query.
+ * Symlinks are left untouched to avoid following or deleting user-managed
+ * paths outside the project.
+ *
+ * @param {string} projectRoot
+ * @param {string} [targetDir]
+ * @returns {boolean} True when a legacy directory was removed or migrated.
+ */
+function migrateLegacyProjectCache(projectRoot, targetDir = getProjectCacheDir(projectRoot)) {
+    const legacyDir = getLegacyProjectCacheDir(projectRoot);
+    let legacyStat;
+    try {
+        legacyStat = fs.lstatSync(legacyDir);
+    } catch (_) {
+        return false;
+    }
+    if (!legacyStat.isDirectory() || legacyStat.isSymbolicLink()) return false;
+
+    try {
+        if (fs.existsSync(targetDir)) {
+            fs.rmSync(legacyDir, { recursive: true, force: true });
+            return true;
+        }
+
+        fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+        try {
+            fs.renameSync(legacyDir, targetDir);
+            return true;
+        } catch (error) {
+            if (error.code !== 'EXDEV') throw error;
+        }
+
+        const tempDir = `${targetDir}.migrating-${process.pid}-${Date.now()}`;
+        try {
+            fs.cpSync(legacyDir, tempDir, { recursive: true, errorOnExist: true });
+            fs.renameSync(tempDir, targetDir);
+            fs.rmSync(legacyDir, { recursive: true, force: true });
+            return true;
+        } catch (_) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+            return false;
+        }
+    } catch (_) {
+        return false;
+    }
+}
+
+/**
+ * Remove both the current per-user cache and the obsolete project-local cache
+ * for one project.
+ *
+ * @param {string} projectRoot
+ * @returns {string[]} Removed directories.
+ */
+function clearProjectCache(projectRoot) {
+    const removed = [];
+    for (const cacheDir of [
+        getProjectCacheDir(projectRoot),
+        getLegacyProjectCacheDir(projectRoot),
+    ]) {
+        try {
+            if (!fs.existsSync(cacheDir)) continue;
+            fs.rmSync(cacheDir, { recursive: true, force: true });
+            removed.push(cacheDir);
+        } catch (_) {
+            // Cache cleanup is best-effort; callers can rebuild regardless.
+        }
+    }
+    return removed;
+}
+
+function directorySize(root) {
+    let total = 0;
+    const pending = [root];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        let entries;
+        try { entries = fs.readdirSync(current, { withFileTypes: true }); }
+        catch (_) { continue; }
+        for (const entry of entries) {
+            const target = path.join(current, entry.name);
+            if (entry.isSymbolicLink()) continue;
+            if (entry.isDirectory()) pending.push(target);
+            else {
+                try { total += fs.statSync(target).size; } catch (_) { /* raced */ }
+            }
+        }
+    }
+    return total;
+}
+
+/** Bound the shared per-user cache by age, project count, and total bytes. */
+function pruneUserCache({ force = false, now = Date.now() } = {}) {
+    const cacheRoot = getUserCacheRoot();
+    const projectsRoot = path.join(cacheRoot, CACHE_PROJECTS_DIRECTORY);
+    const marker = path.join(cacheRoot, '.last-pruned');
+    try {
+        if (!force && fs.existsSync(marker) &&
+            now - fs.statSync(marker).mtimeMs < CACHE_PRUNE_INTERVAL_MS) {
+            return { removed: [], skipped: true };
+        }
+    } catch (_) { /* run maintenance */ }
+    if (!fs.existsSync(projectsRoot)) return { removed: [], skipped: false };
+
+    const removed = [];
+    const entries = [];
+    for (const dirent of fs.readdirSync(projectsRoot, { withFileTypes: true })) {
+        if (!dirent.isDirectory() || dirent.isSymbolicLink()) continue;
+        const dir = path.join(projectsRoot, dirent.name);
+        const indexFile = path.join(dir, 'index.json');
+        let root = null;
+        let touched = 0;
+        try {
+            const stat = fs.statSync(indexFile);
+            touched = stat.mtimeMs;
+            const data = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
+            root = data.root || null;
+            touched = Math.max(touched, Number(data.timestamp) || 0);
+        } catch (_) { /* malformed/incomplete cache expires below */ }
+        if (!root || !fs.existsSync(root) || now - touched > CACHE_TTL_MS) {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+                removed.push(dir);
+            } catch (_) { /* best effort */ }
+            continue;
+        }
+        entries.push({ dir, touched, bytes: null });
+    }
+
+    entries.sort((a, b) => a.touched - b.touched || codeUnitCompare(a.dir, b.dir));
+    while (entries.length > CACHE_MAX_PROJECTS) {
+        const victim = entries.shift();
+        try { fs.rmSync(victim.dir, { recursive: true, force: true }); removed.push(victim.dir); }
+        catch (_) { /* best effort */ }
+    }
+
+    let totalBytes = 0;
+    for (const entry of entries) {
+        entry.bytes = directorySize(entry.dir);
+        totalBytes += entry.bytes;
+    }
+    while (entries.length > 1 && totalBytes > CACHE_MAX_BYTES) {
+        const victim = entries.shift();
+        try {
+            fs.rmSync(victim.dir, { recursive: true, force: true });
+            removed.push(victim.dir);
+            totalBytes -= victim.bytes;
+        } catch (_) { /* best effort */ }
+    }
+    try {
+        fs.mkdirSync(cacheRoot, { recursive: true });
+        fs.writeFileSync(marker, String(now));
+    } catch (_) { /* maintenance must never block analysis */ }
+    return { removed, skipped: false, totalBytes, projects: entries.length };
+}
+
+function clearAllCaches() {
+    const cacheRoot = getUserCacheRoot();
+    try {
+        if (!fs.existsSync(cacheRoot)) return [];
+        fs.rmSync(cacheRoot, { recursive: true, force: true });
+        return [cacheRoot];
+    } catch (_) {
+        return [];
+    }
+}
+
 // Index/calls cache format version — bump when the persisted call-record or
 // symbol shape changes (saveCache writes it; loadCache rejects anything else).
 // v14: Go qualified composite literals (pkg.Foo{...}) record the package
@@ -164,7 +454,152 @@ const UCN_VERSION = require('../package.json').version;
 // (`m.get_many::<T>()`); v64 caches misclassified them as references.
 // v66: Rust call records preserve receiverFlowInvalidated after a non-call
 // lexical rebinding, preventing stale return types from excluding true calls.
-const CACHE_FORMAT_VERSION = 66;
+// v67: JS/TS constructor calls preserve lexical-shadow evidence, and method
+// calls on fresh constructions preserve the exact constructed receiver type.
+// Both fields affect caller identity and must not be read from older shards.
+// v68: unaliased dotted Python imports persist separate package and submodule
+// ownership edges (`import pkg.sub` binds pkg and loads pkg.sub).
+// v69: CommonJS simple-require bindings preserve defaultLike so callable
+// module.exports values resolve exactly across caller and callee queries.
+// v70: Python receiver records preserve exact constructor provenance and
+// context-manager result bindings for conservative dispatch tiering.
+// v71: structural method records preserve untyped local-receiver ownership;
+// single-owner spelling alone cannot confirm a parameter/assigned value.
+// v72: Rust type symbols preserve the compiler-declared Deref Target so
+// wrapper receiver method lookup reaches the target type without guessing.
+// v73: JS/TS call records preserve qualified-constructor provenance and bound
+// local receivers; conditional reassignments no longer persist a definite
+// inferred constructor type past a branch.
+// v74: JS/TS CommonJS object-spread barrels persist `module.exports = {
+// ...require('./source') }` as source-bearing re-export-all records. Namespace
+// calls can therefore establish exact name ownership through the facade.
+// Java nested type symbols preserve their enclosing type for exact constructor
+// ownership across same-named top-level and inner classes, and cast receivers
+// retain their compiler-declared type. Rust tuple fields are indexed by numeric
+// position so `self.0.method()` participates in declared-field resolution.
+// v75: v5's shared IR path persists lexical-owner ranges and C/C++/C# symbol
+// metadata; JS/TS call records preserve inline CommonJS module ownership,
+// explicit builtin-member reassignment, and the richer C-family receiver/flow
+// evidence used by caller resolution.
+// v76: Java member symbols retain their nested enclosing type so overload and
+// owner identity cannot conflate same-named inner classes.
+// v77: Java call records retain explicit type-qualified receivers and nested
+// type qualifiers for receiver-owner routing before overload selection.
+// v78: Java argument kinds retain qualified producer ownership, same-class
+// helper calls, and generic collection value types for exact overload routing.
+// v79: Java chained-call records retain their full producer type path for
+// platform collection/receiver ownership.
+// v80: Rust chained-call records retain exact producer byte offsets so
+// same-line nested constructors cannot collide in the fold.
+// v81: Rust producer identities include the complete byte span, separating
+// repeated same-name hops whose nested call expressions share a start offset.
+// v82: Rust macro symbols persist conservative transcriber return contracts;
+// macro invocations and token-tree calls retain complete producer spans and
+// path ownership for exact builder-chain folding.
+// v83: Rust callable symbols persist callback parameter type contracts and
+// calls inside closures retain their enclosing call/argument identity.
+// v84: Rust token-tree call records retain their containing macro identity so
+// code-generation templates (`quote!`) can use their own trust policy.
+// v85: Rust callable symbols persist declared iterator Item types for exact
+// closure and loop receiver inference.
+// v86: JS/TS package self-references can resolve a source entry when exported
+// build artifacts are absent, changing persisted module ownership graphs.
+// v87: JS/TS and Rust call records retain their lexical function-scope chain
+// so return-flow assignments remain visible inside nested closures.
+// v88: JS/TS callable symbols persist a unanimous concrete constructor return
+// for runtime dispatch through interface-typed factory annotations.
+// v89: JS/TS call records retain exact producer byte spans for same-line
+// return-flow assignments and chained-call identity.
+// v90: TypeScript object type aliases persist their declared field/method
+// members so structural field-hop resolution can use their type contracts;
+// explicit Type.prototype method bindings retain their type owner.
+// v91: Python call records retain complete attribute receiver paths and their
+// annotated root type for multi-hop declared-field resolution.
+// v92: Python calls retain isinstance-refined receiver types.
+// v93: Python calls retain receiver types derived from annotated iterable
+// tuple destructuring in loops and comprehensions.
+// v94: Python variadic parameter receivers retain their container type
+// (**kwargs is dict, *args is tuple).
+// v95: Python static generic aliases normalize to their runtime identity;
+// calls retain receiver types from same-file callable iterable returns and
+// collection-protocol conditional normalization.
+// v96: Python explicit instance-field type comments type receivers yielded
+// by loops and comprehensions over those fields.
+// v97: Python receiver records preserve compiler-declared variable types
+// through later assignments and unwrap parenthesized chained receivers.
+// v98: Python calls retain declared attribute paths that supply loop and
+// comprehension receiver values.
+// v99: Python context-manager producer calls retain their `as` target so
+// Iterator/ContextManager return contracts type the bound receiver.
+// v100: builtin open() context bindings retain their IO receiver type.
+// v101: Python generator yield assignments retain the declared send type.
+// v102: Python subscript receivers retain exact value types from local
+// string-keyed dictionary literals.
+// v103: Python pickle round-trip receivers retain the serialized value's
+// type plus the stdlib provenance needed to validate that contract.
+// v104: Python self-referential assignment calls retain the receiver's
+// pre-assignment type.
+// v105: Python calls persist nested lexical ownership, returned-constructor
+// contracts, and runtime instance-field assignments used by exact receiver
+// flow.
+// v106: Go calls persist package-scope typed receivers and exact wrapper-call
+// ownership used by the nominal dispatch path.
+// v107: Rust imports persist fully flattened grouped-use leaves; call records
+// retain iterator/collection contracts, match-payload provenance, multi-hop
+// field paths, tuple/match assignment producers, and primitive slice roots.
+// v108: JavaScript/TypeScript call records retain unresolved deep-member
+// receiver provenance so name bindings cannot impersonate receiver identity.
+// v109: Python call records retain positive receiver-exact hasattr capability
+// guards so uncertainty can name the runtime dispatch boundary.
+// v110: Rust untyped closure parameters block same-named outer receiver
+// annotations instead of persisting a stale, unrelated receiver type.
+// v111: Java call IR preserves lexical nested-type owners and uses declared
+// field types for overload argument shapes.
+// v112: Java argument kinds retain class-qualified field identity so the
+// field declaration's static value type participates in overload selection.
+// v113: persist common unsupported source files so cached repo/health output
+// cannot silently lose the grep handoff discovered during a full scan.
+// v114: Rust impl owners normalize nested generics and reference impls to the
+// same concrete identity used by receiver-flow analysis.
+// v115: C# callable symbols persist extension-method identity and their
+// receiver parameter marker; string/char literal receiver typing changes the
+// call evidence consumed from cached indexes.
+// v116: C# call records persist overload argument kinds and callable-scoped
+// receiver types; enum members are indexed as typed fields for exact overload
+// selection.
+// v117: nullable GetValueOrDefault argument shapes retain their underlying
+// value type for C# inherited-overload selection.
+// v118: C# declarations nested under preprocessor nodes and recovered
+// namespace-level method siblings remain attached to their lexical class.
+// v125: C/C++ multiline typedef/class symbols persist the declaration
+// identifier's nameLine so compiler-selected handles survive caching.
+// v126: C/C++ parser recovery recognizes calling-convention/export macros
+// between a builtin return type and a function name.
+// v127: ambiguous .h files use the repository translation-unit convention
+// when no compilation database or same-directory source sibling is present.
+// v128: C++ using-alias symbols are indexed and template-qualified
+// out-of-line methods close with their in-class declarations.
+// v150: C/C++ call records persist source spans and chained-receiver producer
+// links so the nominal return-type fold can resolve call().member() identity.
+// v151: inheritance graphs normalize compiler-owned qualified nominal bases
+// (for example `detail::buffer<T>`) to their indexed type identity.
+// v152: C/C++ callable signatures persist anonymous C-style variadic tails.
+// v153: C++ callable symbols persist explicit C-language linkage identity.
+// v154: C/C++ calls parsed from preprocessor replacement lists persist their
+// macro-body and macro-parameter provenance.
+// v155: C# method symbols persist explicit-interface ownership so ordinary
+// member overload resolution cannot select an interface-only implementation.
+// v156: C# calls persist cast receiver types and multi-hop/null-forgiving
+// declared-field paths used for compiler-grade member ownership.
+// v157: C# cast receivers distinguish `((IFace)this).M()` from an arbitrary
+// interface-typed variable so explicit implementations are never overclaimed.
+// v159: importBindings persist source lines so rename plans can edit aliased
+// CJS/Python imports without relying on usage-kind heuristics.
+// v160: C# file entries persist project-wide `global using` modules.
+// v166: C++ nested aliases persist their lexical owner ranges, and `auto`
+// return functions persist a unanimously inferred local concrete type. v165
+// was used during prerelease development before both fields were complete.
+const CACHE_FORMAT_VERSION = 166;
 
 /**
  * Save index to cache file
@@ -173,9 +608,12 @@ const CACHE_FORMAT_VERSION = 66;
  * @returns {string} - Path to cache file
  */
 function saveCache(index, cachePath) {
+    if (!cachePath) {
+        migrateLegacyProjectCache(index.root);
+    }
     const cacheDir = cachePath
         ? path.dirname(cachePath)
-        : path.join(index.root, '.ucn-cache');
+        : getProjectCacheDir(index.root);
 
     if (!fs.existsSync(cacheDir)) {
         fs.mkdirSync(cacheDir, { recursive: true });
@@ -197,6 +635,7 @@ function saveCache(index, cachePath) {
     // Hash config to detect when graph rebuild is needed on load
     const configHash = crypto.createHash('md5')
         .update(JSON.stringify(index.config || {})).digest('hex');
+    const discoveryHash = discoveryRulesHash(index.root);
 
     // Strip redundant fields from symbols and file entries to reduce cache size.
     // v6: All paths stored as relative paths (saves ~60% on large codebases).
@@ -274,6 +713,7 @@ function saveCache(index, cachePath) {
         version: CACHE_FORMAT_VERSION,
         ucnVersion: UCN_VERSION,  // Invalidate cache when UCN is updated
         configHash,
+        discoveryHash,
         root,
         // PERF-2: refresh buildTime on each save so partial rebuilds report
         // accurate stats. Falls back to original on first save.
@@ -289,10 +729,21 @@ function saveCache(index, cachePath) {
         failedFiles: index.failedFiles
             ? Array.from(index.failedFiles).map(f => path.relative(root, f))
             : [],
+        unsupportedFiles: Array.isArray(index.unsupportedFiles)
+            ? index.unsupportedFiles
+            : [],
+        discoveryIssues: Array.isArray(index.discoveryIssues)
+            ? index.discoveryIssues
+            : [],
+        truncated: index.truncated || null,
         ...(reachableSymbolsRel !== undefined && {
             reachableSymbols: reachableSymbolsRel,
             reachableFingerprint,
         }),
+        ...(index._computedDispatchBlindspots instanceof Map && {
+            computedDispatchBlindspots: [...index._computedDispatchBlindspots]
+                .map(([filePath, sites]) => [path.relative(root, filePath), sites]),
+        }),
     };
 
     // PERF-3: atomic write — tmp file + rename so concurrent readers/writers
@@ -307,6 +758,7 @@ function saveCache(index, cachePath) {
     if (index.reachabilityDirty) {
         index.reachabilityDirty = false;
     }
+    index.computedDispatchDirty = false;
 
     // Save callsCache sharded by directory for lazy loading.
     // Write to a temp directory first, then atomic swap to avoid data loss on crash.
@@ -354,6 +806,7 @@ function saveCache(index, cachePath) {
         }
     }
 
+    if (!cachePath) pruneUserCache();
     return cacheFile;
 }
 
@@ -364,7 +817,10 @@ function saveCache(index, cachePath) {
  * @returns {boolean} - True if loaded successfully
  */
 function loadCache(index, cachePath) {
-    const cacheFile = cachePath || path.join(index.root, '.ucn-cache', 'index.json');
+    if (!cachePath) {
+        migrateLegacyProjectCache(index.root);
+    }
+    const cacheFile = cachePath || getProjectCachePath(index.root);
 
     if (!fs.existsSync(cacheFile)) {
         return false;
@@ -412,6 +868,10 @@ function loadCache(index, cachePath) {
             ? (relPath) => rootPrefix + relPath
             : (relPath) => rootPrefix + relPath.replace(/\//g, path.sep);
 
+        // Loading into a previously-used ProjectIndex replaces its indexed
+        // contents, so no parsed tree from the old state may survive.
+        index._clearParsedTreeCache?.();
+
         // Reconstruct files Map: relative key → absolute key, restore path and relativePath
         // Initialize symbols/bindings arrays (will be populated from top-level symbols)
         index.files = new Map();
@@ -494,6 +954,24 @@ function loadCache(index, cachePath) {
                 cacheData.failedFiles.map(f => path.isAbsolute(f) ? f : toAbs(f))
             );
         }
+        index.unsupportedFiles = Array.isArray(cacheData.unsupportedFiles)
+            ? cacheData.unsupportedFiles
+            : [];
+        index.discoveryIssues = Array.isArray(cacheData.discoveryIssues)
+            ? cacheData.discoveryIssues
+            : [];
+        index.truncated = cacheData.truncated || null;
+        index._loadedConfigHash = cacheData.configHash || null;
+        index._loadedDiscoveryHash = cacheData.discoveryHash || null;
+        if (Array.isArray(cacheData.computedDispatchBlindspots)) {
+            index._computedDispatchBlindspots = new Map(
+                cacheData.computedDispatchBlindspots.map(([relPath, sites]) => [
+                    path.isAbsolute(relPath) ? relPath : toAbs(relPath),
+                    Array.isArray(sites) ? sites : [],
+                ]),
+            );
+            index.computedDispatchDirty = false;
+        }
 
         // Restore calleeIndex if persisted (v7 caches only; v8+ rebuilds lazily)
         if (Array.isArray(cacheData.calleeIndex)) {
@@ -549,6 +1027,15 @@ function loadCache(index, cachePath) {
  * @returns {boolean} - True if cache needs rebuilding
  */
 function isCacheStale(index) {
+    const currentConfigHash = crypto.createHash('md5')
+        .update(JSON.stringify(index.config || {})).digest('hex');
+    if (index._loadedConfigHash && currentConfigHash !== index._loadedConfigHash) {
+        return true;
+    }
+    if (index._loadedDiscoveryHash &&
+        discoveryRulesHash(index.root) !== index._loadedDiscoveryHash) {
+        return true;
+    }
     // Modified/deleted detection (stat sweep) runs UNCONDITIONALLY — agents
     // edit a file and re-query through MCP within seconds, and a stale answer
     // presented as fresh is the worst trust failure the tool can produce.
@@ -594,20 +1081,52 @@ function isCacheStale(index) {
     // Slow path: glob the project to detect new files added since last build.
     // Only reached when all cached files are unchanged.
     const pattern = detectProjectPattern(index.root);
-    const globOpts = { root: index.root };
+    const currentUnsupported = [];
+    const globOpts = {
+        root: index.root,
+        onSkippedFile: (filePath) => {
+            const kind = classifyUnsupportedSourceFile(filePath);
+            if (!kind) return;
+            currentUnsupported.push({
+                relativePath: path.relative(index.root, filePath),
+                ...kind,
+            });
+        },
+    };
     const gitignorePatterns = parseGitignore(index.root);
+    globOpts.gitignorePatterns = gitignorePatterns;
+    globOpts.trackedPaths = gitTrackedPaths(index.root);
     const configExclude = index.config.exclude || [];
-    if (gitignorePatterns.length > 0 || configExclude.length > 0) {
-        globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
+    if (configExclude.length > 0) {
+        globOpts.ignores = [...DEFAULT_IGNORES, ...configExclude];
     }
     const currentFiles = expandGlob(pattern, globOpts);
     const cachedPaths = new Set(index.files.keys());
+    const currentPaths = new Set(currentFiles);
+
+    // A cached file can still exist on disk while becoming excluded by a new
+    // .gitignore/.ucn.json rule. Treat that set contraction as stale too;
+    // otherwise ignored code remains queryable until an unrelated edit forces
+    // a rebuild.
+    for (const file of cachedPaths) {
+        if (!currentPaths.has(file)) return true;
+    }
 
     for (const file of currentFiles) {
         if (!cachedPaths.has(file) && !(index.failedFiles && index.failedFiles.has(file))) {
             return true; // New file found
         }
     }
+    const cachedUnsupported = (index.unsupportedFiles || [])
+        .map(f => `${f.relativePath}\0${f.language}`)
+        .sort();
+    const discoveredUnsupported = currentUnsupported
+        .map(f => `${f.relativePath}\0${f.language}`)
+        .sort();
+    if (cachedUnsupported.length !== discoveredUnsupported.length ||
+        cachedUnsupported.some((value, i) => value !== discoveredUnsupported[i])) {
+        return true;
+    }
 
     // Record when we last confirmed the cache is fresh (enables 2s skip on burst calls)
     index._lastFreshAt = Date.now();
@@ -624,11 +1143,11 @@ function _prepareCallsCache(index, cacheFile) {
     if (index._callsCacheLoaded) return;
     // Shards live beside the selected index.json. A custom cachePath must be
     // a complete portable cache, not an index file that silently looks for
-    // call shards under <project>/.ucn-cache. The latter caused cache-loaded
+    // call shards under the default project cache. The latter caused cache-loaded
     // semantic queries to reparse source (or consume unrelated stale shards).
     const cacheDir = cacheFile
         ? path.dirname(cacheFile)
-        : path.join(index.root, '.ucn-cache');
+        : getProjectCacheDir(index.root);
     index._callsCacheDir = cacheDir;
     const manifestFile = path.join(cacheDir, 'calls', 'manifest.json');
     if (fs.existsSync(manifestFile)) {
@@ -674,7 +1193,7 @@ function loadCallsCache(index) {
 
     // Legacy format: single calls-cache.json
     const callsCacheFile = index._callsCacheLegacyFile ||
-        path.join(index._callsCacheDir || path.join(index.root, '.ucn-cache'), 'calls-cache.json');
+        path.join(index._callsCacheDir || getProjectCacheDir(index.root), 'calls-cache.json');
     if (!fs.existsSync(callsCacheFile)) return index.callsCache.size > 0;
 
     try {
@@ -713,7 +1232,7 @@ function ensureCallsCacheLoaded(index) {
  */
 function _loadCallsShard(index, hash) {
     const shardFile = path.join(
-        index._callsCacheDir || path.join(index.root, '.ucn-cache'),
+        index._callsCacheDir || getProjectCacheDir(index.root),
         'calls', `${hash}.json`);
     try {
         const data = JSON.parse(fs.readFileSync(shardFile, 'utf-8'));
@@ -769,5 +1288,8 @@ function _computeReachabilityFingerprint(index) {
 
 module.exports = {
     saveCache, loadCache, loadCallsCache, isCacheStale, ensureCallsCacheLoaded,
+    getUserCacheRoot, getProjectCacheDir, getProjectCachePath,
+    getLegacyProjectCacheDir, migrateLegacyProjectCache, clearProjectCache,
+    clearAllCaches, pruneUserCache,
     _computeReachabilityFingerprint, CACHE_FORMAT_VERSION,
 };