ucn 5.3.3 → 5.3.4

package/.claude/skills/ucn/SKILL.md

@@ -39,7 +39,7 @@ answer, a notice stating the full size and limit, and the accounting/contract
 lines needed to interpret what remains; the requested limit includes all
 three. The text block is the whole response on every surface.
 
-Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use.
+Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use. Concurrent invocations on a cold cache share one build: the first process takes a build lock, the others wait for its cache (`Waiting for another ucn process building the index...` on stderr) instead of rebuilding; a lock left by a dead process is broken automatically.
 
 Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ uses `compile_commands.json` when available to classify headers and resolve include paths. Recoverable preprocessor branches contribute AST-proven source facts, so a single selected configuration does not silently erase definitions or calls; disagreeing conditional macro identities stay visible as unverified. C++ resolution uses namespace ownership, static overload shape (including arrays), and macro-parameter requalification. C# resolution uses declared property/field receiver types plus overload and hiding discipline. This is portable AST analysis, not a compiler build; macros, templates, generated code, reflection, and external dependency semantics can remain unverified.
 

package/cli/index.js

@@ -766,8 +766,18 @@ function runProjectCommand(rootDir, command, arg) {
     // If cache was loaded but stale, force rebuild to avoid duplicates
     let needsCacheSave = false;
     if (!usedCache) {
-        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers });
-        needsCacheSave = flags.cache;
+        const buildOpts = { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers };
+        if (flags.cache && !flags.maxFiles) {
+            // Cross-process build lock (fix #354): concurrent cold-cache
+            // invocations share one build instead of each rebuilding.
+            index.buildCached(buildOpts, {
+                onWait: () => { if (!flags.quiet) console.error('Waiting for another ucn process building the index...'); },
+            });
+            needsCacheSave = false; // buildCached saved (or loaded the other process's cache)
+        } else {
+            index.build(null, buildOpts);
+            needsCacheSave = flags.cache;
+        }
     }
 
     try {
@@ -986,13 +996,10 @@ function runInteractive(rootDir) {
     if (flags.cache) {
         const loaded = !flags.clearCache && index.loadCache();
         iCacheFresh = loaded && !index.isCacheStale();
-        if (!iCacheFresh && loaded) {
-            index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
-        } else if (!iCacheFresh) {
-            index.build(null, { quiet: true, workers: flags.workers });
-        }
         if (!iCacheFresh) {
-            try { index.saveCache(); } catch (_) { /* best-effort */ }
+            index.buildCached({ quiet: true, forceRebuild: !!loaded, workers: flags.workers }, {
+                onWait: () => console.log('Waiting for another ucn process building the index...'),
+            });
         }
     } else {
         index.build(null, { quiet: true, workers: flags.workers });
@@ -1113,15 +1120,19 @@ Flags can be added per-command: show myFunc --sections=source,callers
             // appeared in neighbouring answers (UCN5-044).
             if (index.isCacheStale()) {
                 console.log('Source changed; rebuilding index...');
-                index.build(null, {
+                const rebuildOpts = {
                     quiet: true,
                     forceRebuild: true,
                     followSymlinks: flags.followSymlinks,
                     maxFiles: flags.maxFiles,
                     workers: flags.workers,
-                });
-                if (flags.cache) {
-                    try { index.saveCache(); } catch (_) { /* best-effort */ }
+                };
+                if (flags.cache && !flags.maxFiles) {
+                    index.buildCached(rebuildOpts, {
+                        onWait: () => console.log('Waiting for another ucn process building the index...'),
+                    });
+                } else {
+                    index.build(null, rebuildOpts);
                 }
                 console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
             }

package/core/cache.js

@@ -256,6 +256,14 @@ function pruneUserCache({ force = false, now = Date.now() } = {}) {
             root = data.root || null;
             touched = Math.max(touched, Number(data.timestamp) || 0);
         } catch (_) { /* malformed/incomplete cache expires below */ }
+        // fix #354: a project whose FIRST build is in progress has no
+        // index.json yet, only a live build.lock — another process's prune
+        // must not delete the lock (or the dir) out from under the builder.
+        const lockPath = path.join(dir, BUILD_LOCK_FILE);
+        if (!root && fs.existsSync(lockPath) && !_lockIsStale(lockPath)) {
+            entries.push({ dir, touched: now, bytes: null });
+            continue;
+        }
         if (!root || !fs.existsSync(root) || now - touched > CACHE_TTL_MS) {
             try {
                 fs.rmSync(dir, { recursive: true, force: true });
@@ -1494,7 +1502,101 @@ function _computeReachabilityFingerprint(index) {
     return `${fileCount}:${symbolCount}:${sample}`;
 }
 
+const BUILD_LOCK_FILE = 'build.lock';
+const BUILD_LOCK_STALE_MS = 15 * 60 * 1000;
+const BUILD_LOCK_WAIT_MS = 15 * 60 * 1000;
+const BUILD_LOCK_POLL_MS = 150;
+
+function _sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function _pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+function _readLock(lockPath) {
+    try { return JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch (_) { return null; }
+}
+
+function _lockIsStale(lockPath) {
+    const info = _readLock(lockPath);
+    if (!info) {
+        // Unreadable or half-written: judge by mtime alone
+        try { return Date.now() - fs.statSync(lockPath).mtimeMs > BUILD_LOCK_STALE_MS; } catch (_) { return true; }
+    }
+    if (info.pid && !_pidAlive(info.pid)) return true;
+    return Date.now() - (info.startedAt || 0) > BUILD_LOCK_STALE_MS;
+}
+
+/**
+ * Cross-process build lock (fix #354): N concurrent cold-cache invocations
+ * used to rebuild the whole index N times at once (6 processes on a 474k-line
+ * repo: 9s each alone, 363s each together — the stampede fires after every
+ * version bump, because the bump invalidates every cache). One process takes
+ * the lock and builds; the others wait, then load the cache it saved. A lock
+ * whose holder is dead, or older than 15 minutes, is broken. Waiters give up
+ * after 15 minutes and build themselves (a wedged holder must never make the
+ * tool hang forever).
+ *
+ * @returns {{ built: boolean, waited: boolean }}
+ */
+function buildWithLock(index, buildOpts = {}, options = {}) {
+    const cacheDir = getProjectCacheDir(index.root);
+    const lockPath = path.join(cacheDir, BUILD_LOCK_FILE);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const deadline = Date.now() + BUILD_LOCK_WAIT_MS;
+    let announced = false;
+    for (;;) {
+        let fd = null;
+        try {
+            fd = fs.openSync(lockPath, 'wx');
+        } catch (e) {
+            if (e.code !== 'EEXIST') throw e;
+        }
+        if (fd !== null) {
+            try {
+                fs.writeSync(fd, JSON.stringify({ pid: process.pid, startedAt: Date.now() }));
+                fs.closeSync(fd);
+                index.build(null, buildOpts);
+                if (options.save !== false) {
+                    try { saveCache(index); } catch (_) { /* best-effort */ }
+                }
+                return { built: true, waited: announced };
+            } finally {
+                try { fs.unlinkSync(lockPath); } catch (_) { /* already gone */ }
+            }
+        }
+        if (_lockIsStale(lockPath)) {
+            try { fs.unlinkSync(lockPath); } catch (_) { /* raced */ }
+            continue;
+        }
+        if (Date.now() > deadline) {
+            index.build(null, buildOpts);
+            if (options.save !== false) {
+                try { saveCache(index); } catch (_) { /* best-effort */ }
+            }
+            return { built: true, waited: true };
+        }
+        if (!announced) {
+            announced = true;
+            if (typeof options.onWait === 'function') options.onWait(_readLock(lockPath));
+        }
+        _sleepSync(BUILD_LOCK_POLL_MS);
+        if (!fs.existsSync(lockPath)) {
+            // The holder finished: its cache is the answer unless it is
+            // already stale again (or it never saved one)
+            if (options.reload !== false && loadCache(index) && !isCacheStale(index)) {
+                return { built: false, waited: true };
+            }
+            // fall through: take the lock ourselves
+        }
+    }
+}
+
 module.exports = {
+    buildWithLock,
     saveCache, saveUsageCache, loadCache, loadCallsCache, isCacheStale, ensureCallsCacheLoaded,
     getUserCacheRoot, getProjectCacheDir, getProjectCachePath,
     getLegacyProjectCacheDir, migrateLegacyProjectCache, clearProjectCache,

package/core/project.js

@@ -2529,6 +2529,15 @@ class ProjectIndex {
     saveCache(cachePath) { return indexCache.saveCache(this, cachePath); }
 
     /** Load index from cache file */
+    /**
+     * Build under the cross-process build lock (fix #354) and save the cache.
+     * Returns { built, waited }; when another process built meanwhile and its
+     * cache is fresh, that cache is loaded instead of rebuilding.
+     */
+    buildCached(buildOpts = {}, options = {}) {
+        return indexCache.buildWithLock(this, buildOpts, options);
+    }
+
     loadCache(cachePath) { return indexCache.loadCache(this, cachePath); }
 
     /** Persist the bounded, content-hash-keyed usage-query cache. */

package/mcp/server.js

@@ -71,8 +71,13 @@ function getIndex(projectDir, options) {
         // Disk cache is fresh (skip when maxFiles is set — cached index may have different file count)
     } else {
         buildOpts.forceRebuild = !!loaded;
-        index.build(null, buildOpts);
-        if (!maxFiles) index.saveCache(); // Don't pollute disk cache with partial indexes
+        if (maxFiles) {
+            index.build(null, buildOpts); // Don't pollute disk cache with partial indexes
+        } else {
+            // Cross-process build lock (fix #354): a CLI or another MCP
+            // server building the same repo at the same moment shares one build
+            index.buildCached(buildOpts);
+        }
     }
 
     // LRU eviction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.3.3",
+  "version": "5.3.4",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Auditable AST code intelligence for AI agents: 18 task-oriented commands through one MCP tool, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java, C, C++, C#, and HTML.",
   "main": "index.js",