ttsc 0.16.12 → 0.17.1

package/lib/plugin/internal/buildSourcePlugin.js

@@ -5,8 +5,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSourcePlugin = buildSourcePlugin;
 exports.resolvePluginCacheRoot = resolvePluginCacheRoot;
-exports.resolveGlobalPluginCacheRoot = resolveGlobalPluginCacheRoot;
-exports.defaultPluginCacheCleanTargets = defaultPluginCacheCleanTargets;
+exports.resolveSourceBuildCachePaths = resolveSourceBuildCachePaths;
+exports.resolveCleanTargets = resolveCleanTargets;
+exports.legacyGlobalCacheTargets = legacyGlobalCacheTargets;
+exports.isPathWithin = isPathWithin;
 exports.computeCacheKey = computeCacheKey;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = __importDefault(require("node:crypto"));
@@ -106,15 +108,36 @@ const CONTRIB_DIRNAME = "contrib";
 // runtimeHooks.ts.
 const PLUGIN_BUILD_LOCK_STEAL_MS = 600_000;
 const PLUGIN_BUILD_LOCK_POLL_MS = 50;
-const GLOBAL_CACHE_DIRNAME = "ttsc";
+// The default cache lives INSIDE the workspace, at
+// `<workspaceRoot>/node_modules/.cache/ttsc`, so `rm -rf node_modules` (or
+// deleting the repo) reclaims every compiled plugin binary and Go object file.
+// This is the `find-cache-dir` convention (Babel, webpack, ESLint, Nuxt, …): a
+// disposable build cache under `node_modules/.cache/<tool>`. ttsc keeps NO
+// global (`~/.cache`) cache — a machine-wide cache silently grew to hundreds of
+// GB across tsgo/plugin version bumps, so it was removed outright. See
+// resolveSourceBuildCacheRoot for the (override → workspace-local) priority.
+const NODE_MODULES_DIRNAME = "node_modules";
+const LOCAL_CACHE_PARENT_DIRNAME = ".cache";
+const TTSC_CACHE_DIRNAME = "ttsc";
 const PLUGIN_CACHE_DIRNAME = "plugins";
+const GO_BUILD_CACHE_DIRNAME = "go-build";
+// Directories whose presence marks a monorepo/workspace root, so every package
+// in the workspace shares ONE cache and a plugin builds once, not once per
+// package. `package.json` with a `workspaces` field (yarn/npm/bun) is checked
+// separately in isWorkspaceRootDir.
+const WORKSPACE_ROOT_MARKER_FILES = ["pnpm-workspace.yaml"];
 const CACHE_LAST_USED_FILE = ".last-used";
 const CACHE_GC_MARKER_FILE = ".gc-last-run";
-const GLOBAL_CACHE_GC_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const GLOBAL_CACHE_ENTRY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
-const GLOBAL_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
-const GLOBAL_CACHE_TARGET_BYTES = Math.floor(GLOBAL_CACHE_MAX_BYTES * 0.8);
-const GLOBAL_CACHE_PROTECTED_AGE_MS = 60 * 60 * 1000;
+// The plugin binary cache is content-keyed, so a project that bumps tsgo/typia
+// many times leaves one stale entry per superseded key. An opportunistic GC
+// (once/day) evicts entries unused for 30 days and, past a 2 GB ceiling, the
+// least-recently-used down to 80%. It is scoped to the resolved cache root only
+// — ttsc never scans a shared or global location.
+const PLUGIN_CACHE_GC_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const PLUGIN_CACHE_ENTRY_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const PLUGIN_CACHE_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+const PLUGIN_CACHE_TARGET_BYTES = Math.floor(PLUGIN_CACHE_MAX_BYTES * 0.8);
+const PLUGIN_CACHE_PROTECTED_AGE_MS = 60 * 60 * 1000;
 /** Build one Go source plugin into a cached executable. */
 function buildSourcePlugin(opts) {
     const { dir, entry, source } = resolveSourceBuildTarget(opts);
@@ -131,8 +154,9 @@ function buildSourcePlugin(opts) {
         ttscVersion: opts.ttscVersion,
         tsgoVersion: opts.tsgoVersion,
     });
-    const root = resolvePluginCacheRoot(opts.baseDir, opts.cacheDir);
-    const cacheDir = node_path_1.default.join(root, key);
+    const paths = resolveSourceBuildCachePaths(opts.baseDir, opts.cacheDir);
+    maybePrunePluginCache(paths, opts.cacheDir);
+    const cacheDir = node_path_1.default.join(paths.pluginRoot, key);
     const binaryName = process.platform === "win32" ? "plugin.exe" : "plugin";
     const binaryPath = node_path_1.default.join(cacheDir, binaryName);
     if (node_fs_1.default.existsSync(binaryPath)) {
@@ -149,6 +173,7 @@ function buildSourcePlugin(opts) {
         goBinary,
         key,
         label: opts.label ?? "source plugin",
+        goBuildCacheRoot: paths.goBuildRoot,
         overlayDirs,
         pluginName: opts.pluginName,
         quiet: opts.quiet === true,
@@ -180,7 +205,7 @@ function compileSourcePlugin(opts) {
         }
         writeGoWork(scratchDir, opts.overlayDirs, opts.goBinary, opts.pluginName);
         const scratchBinaryName = process.platform === "win32" ? ".ttsc-plugin.exe" : ".ttsc-plugin";
-        runGoBuild(scratchDir, opts.entry, scratchBinaryName, opts.pluginName, opts.goBinary);
+        runGoBuild(scratchDir, opts.entry, scratchBinaryName, opts.pluginName, opts.goBinary, opts.goBuildCacheRoot);
         const builtBinary = node_path_1.default.join(scratchDir, scratchBinaryName);
         publishBuiltBinary(builtBinary, opts.binaryPath);
         touchCacheEntry(opts.cacheDir);
@@ -525,7 +550,7 @@ function readGoModInfo(dir, goBinary, pluginName) {
     if (!node_fs_1.default.existsSync(node_path_1.default.join(dir, "go.mod"))) {
         return emptyGoModInfo();
     }
-    const result = (0, node_child_process_1.spawnSync)(goBinary, ["mod", "edit", "-json"], {
+    const result = spawnGoTool(goBinary, ["mod", "edit", "-json"], {
         cwd: dir,
         encoding: "utf8",
         env: goBuildEnv(goBinary),
@@ -585,12 +610,12 @@ function isTtscManagedModulePath(modulePath) {
         modulePath === TSGO_GO_MODULE_PATH ||
         modulePath.startsWith("github.com/microsoft/typescript-go/shim/"));
 }
-function runGoBuild(cwd, entry, binaryName, pluginName, goBinary) {
+function runGoBuild(cwd, entry, binaryName, pluginName, goBinary, goBuildCacheRoot) {
     ensureExecutableGoToolchain(goBinary);
-    const result = (0, node_child_process_1.spawnSync)(goBinary, ["build", "-o", binaryName, entry], {
+    const result = spawnGoTool(goBinary, ["build", "-o", binaryName, entry], {
         cwd,
         encoding: "utf8",
-        env: goBuildEnv(goBinary),
+        env: goBuildEnv(goBinary, goBuildCacheRoot),
         maxBuffer: 1024 * 1024 * 64,
         windowsHide: true,
     });
@@ -609,9 +634,30 @@ function goToolchainNotFoundMessage(pluginName) {
         `Reinstall ttsc with optional dependencies so the bundled Go compiler is present, ` +
         `or set TTSC_GO_BINARY to an absolute path.`);
 }
-function goBuildEnv(goBinary) {
+function spawnGoTool(goBinary, args, options) {
+    const shell = shouldSpawnGoToolThroughShell(goBinary);
+    // Under shell:true (a Windows .cmd/.bat wrapper) Node does not quote the
+    // command, so a wrapper at a path containing a space would be split by cmd.
+    // Quote it here; the go arguments ttsc passes never contain spaces, and
+    // quoting a space-free path is harmless.
+    return (0, node_child_process_1.spawnSync)(shell ? `"${goBinary}"` : goBinary, [...args], {
+        ...options,
+        shell,
+    });
+}
+function shouldSpawnGoToolThroughShell(goBinary) {
+    return process.platform === "win32" && /\.(?:bat|cmd)$/i.test(goBinary);
+}
+function goBuildEnv(goBinary, goBuildCacheRoot) {
     const env = { ...process.env };
     env.GOWORK = "auto";
+    // Only the actual `go build` needs ttsc's GOCACHE; read-only metadata spawns
+    // (`go mod edit`, `go env`, `go version`) call goBuildEnv with no cache root
+    // and inherit the ambient GOCACHE, which they never write to anyway. GOCACHE
+    // is not part of the plugin cache key, so this cannot affect it.
+    if (goBuildCacheRoot) {
+        env.GOCACHE = goBuildCacheRoot;
+    }
     const goRoot = inferGoRoot(goBinary);
     if (goRoot && !env.GOROOT) {
         env.GOROOT = goRoot;
@@ -712,77 +758,225 @@ function walkForGoMod(dir, out) {
 /**
  * Resolve the directory where compiled plugin binaries are cached.
  *
- * Priority order:
+ * Delegates to {@link resolveSourceBuildCachePaths}; kept as a thin accessor for
+ * callers (and tests) that only need the plugin-binary root. Triggers the
+ * opportunistic project-cache GC as a side effect for the default location.
+ */
+function resolvePluginCacheRoot(projectRoot, cacheDir) {
+    const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir);
+    maybePrunePluginCache(paths, cacheDir);
+    return paths.pluginRoot;
+}
+/**
+ * Resolve all source-plugin build cache directories for one invocation.
+ *
+ * `pluginRoot` stores compiled plugin binaries; `goBuildRoot` is the Go object
+ * cache passed as `GOCACHE` while ttsc builds those binaries. Both live under a
+ * single `root`, so persisting one directory covers the whole source-build
+ * cache without depending on ttsc internals.
+ */
+function resolveSourceBuildCachePaths(projectRoot, cacheDir, env = process.env) {
+    const root = resolveSourceBuildCacheRoot(projectRoot, cacheDir, env);
+    const goBuild = resolveGoBuildCacheRoot(root, projectRoot, env);
+    return {
+        root,
+        pluginRoot: node_path_1.default.join(root, PLUGIN_CACHE_DIRNAME),
+        goBuildRoot: goBuild.root,
+        goBuildRootSource: goBuild.source,
+    };
+}
+/**
+ * Resolve the cache root for one invocation.
+ *
+ * Priority:
  *
- * 1. `cacheDir` option (resolved relative to `projectRoot`).
- * 2. `TTSC_CACHE_DIR` environment variable.
- * 3. Platform-specific global user cache (XDG / AppData / Library/Caches).
+ * 1. Explicit `cacheDir` option (resolved relative to `projectRoot`);
+ * 2. `TTSC_CACHE_DIR` environment variable (resolved absolute);
+ * 3. `<workspaceRoot>/node_modules/.cache/ttsc` — project-local by default.
  *
- * When falling back to the global cache, a GC pass is triggered
- * opportunistically to evict old or oversized entries before the cache is
- * used.
+ * There is deliberately NO global (`~/.cache`) fallback: the cache is scoped to
+ * the workspace so it can never accumulate machine-wide, and `rm -rf
+ * node_modules` reclaims it.
  */
-function resolvePluginCacheRoot(projectRoot, cacheDir) {
+function resolveSourceBuildCacheRoot(projectRoot, cacheDir, env) {
     if (cacheDir) {
-        return node_path_1.default.resolve(projectRoot, cacheDir, PLUGIN_CACHE_DIRNAME);
+        return node_path_1.default.resolve(projectRoot, cacheDir);
     }
-    if (process.env.TTSC_CACHE_DIR) {
-        return node_path_1.default.resolve(process.env.TTSC_CACHE_DIR, PLUGIN_CACHE_DIRNAME);
+    if (env.TTSC_CACHE_DIR) {
+        // Anchor a relative TTSC_CACHE_DIR to the project root (not the process
+        // cwd) so a programmatic host whose cwd differs from the project still
+        // resolves — and later cleans — the same cache. Absolute values pass
+        // through path.resolve unchanged.
+        return node_path_1.default.resolve(projectRoot, env.TTSC_CACHE_DIR);
     }
-    const root = resolveGlobalPluginCacheRoot();
-    maybePruneGlobalPluginCache(root);
-    return root;
+    return node_path_1.default.join(resolveWorkspaceRoot(projectRoot), NODE_MODULES_DIRNAME, LOCAL_CACHE_PARENT_DIRNAME, TTSC_CACHE_DIRNAME);
 }
 /**
- * Return the absolute path to the global plugin binary cache root.
+ * Resolve the monorepo/workspace root for `projectRoot` so every package shares
+ * one cache and a plugin builds once per workspace, not once per package.
  *
- * The path follows platform conventions (XDG on Linux, AppData on Windows,
- * Library/Caches on macOS) and does not depend on project-local config. Used by
- * `ttsc cache clean` to enumerate cache locations.
+ * Walks up from `projectRoot` and returns, in order of preference: the NEAREST
+ * ancestor that is a workspace root (holds `pnpm-workspace.yaml`, or a
+ * `package.json` with a `workspaces` field); else the nearest ancestor that
+ * already contains a `node_modules` directory; else `projectRoot` itself.
+ *
+ * Nearest (not highest) so an unrelated ancestor that happens to declare
+ * `workspaces` — for example a `package.json` in the user's home directory —
+ * cannot pull the cache above the project's real monorepo root.
  */
-function resolveGlobalPluginCacheRoot() {
-    return node_path_1.default.join(resolveUserCacheRoot(), GLOBAL_CACHE_DIRNAME, PLUGIN_CACHE_DIRNAME);
+function resolveWorkspaceRoot(projectRoot) {
+    let dir = node_path_1.default.resolve(projectRoot);
+    let nearestNodeModulesOwner = null;
+    for (;;) {
+        if (isWorkspaceRootDir(dir)) {
+            return dir;
+        }
+        if (nearestNodeModulesOwner === null &&
+            node_fs_1.default.existsSync(node_path_1.default.join(dir, NODE_MODULES_DIRNAME))) {
+            nearestNodeModulesOwner = dir;
+        }
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return nearestNodeModulesOwner ?? node_path_1.default.resolve(projectRoot);
+}
+function isWorkspaceRootDir(dir) {
+    for (const marker of WORKSPACE_ROOT_MARKER_FILES) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, marker))) {
+            return true;
+        }
+    }
+    return packageJsonDeclaresWorkspaces(node_path_1.default.join(dir, "package.json"));
+}
+function packageJsonDeclaresWorkspaces(packageJsonPath) {
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(packageJsonPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const workspaces = JSON.parse(text)
+            .workspaces;
+        // A real workspace root declares a NON-EMPTY package list (an array, or an
+        // object with a `packages` array). Ignore `false`, `[]`, `null`, or `{}` so
+        // a disabled or empty declaration on an unrelated ancestor cannot hijack
+        // the cache location.
+        if (Array.isArray(workspaces)) {
+            return workspaces.length > 0;
+        }
+        if (workspaces !== null && typeof workspaces === "object") {
+            const packages = workspaces.packages;
+            return Array.isArray(packages) && packages.length > 0;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveGoBuildCacheRoot(root, projectRoot, env) {
+    if (env.TTSC_GO_CACHE_DIR) {
+        // Anchor a relative TTSC_GO_CACHE_DIR to the project root, matching
+        // TTSC_CACHE_DIR, so the build and a later `clean` from a different cwd
+        // agree on the directory. Absolute values pass through unchanged.
+        return {
+            root: node_path_1.default.resolve(projectRoot, env.TTSC_GO_CACHE_DIR),
+            source: "TTSC_GO_CACHE_DIR",
+        };
+    }
+    if (env.GOCACHE && env.GOCACHE.length > 0) {
+        return {
+            root: env.GOCACHE,
+            source: "GOCACHE",
+        };
+    }
+    return {
+        root: node_path_1.default.join(root, GO_BUILD_CACHE_DIRNAME),
+        source: "ttsc-cache",
+    };
+}
+function maybePrunePluginCache(paths, cacheDir) {
+    // GC only the default (workspace-local) location. When the user pins an
+    // explicit `cacheDir`/`TTSC_CACHE_DIR`, they own its lifetime, so ttsc must
+    // not delete entries out from under them.
+    if (!cacheDir && !process.env.TTSC_CACHE_DIR) {
+        prunePluginCacheRoot(paths.pluginRoot);
+    }
 }
 /**
- * Return all directories that `ttsc cache clean` should wipe for a project.
+ * Return every directory `ttsc clean` should remove for `projectRoot`.
  *
- * Covers three locations where plugin binaries may accumulate: the global user
- * cache, the project-local `node_modules/.ttsc` cache (legacy), and the
- * project-local `.ttsc` cache.
+ * Covers the resolved cache root (which holds `plugins/` and, when ttsc-owned,
+ * `go-build/`), a ttsc-owned Go build cache that lives OUTSIDE that root
+ * (`TTSC_GO_CACHE_DIR`), and the two legacy project-local caches. A
+ * user-provided `GOCACHE` is never removed. Pure over `env`, so the CLI passes
+ * `process.env` and a programmatic caller can pass an injected environment.
  */
-function defaultPluginCacheCleanTargets(projectRoot) {
-    return [
-        resolveGlobalPluginCacheRoot(),
-        node_path_1.default.join(projectRoot, "node_modules", ".ttsc"),
-        node_path_1.default.join(projectRoot, ".ttsc"),
-    ];
+function resolveCleanTargets(projectRoot, cacheDir, env = process.env) {
+    const paths = resolveSourceBuildCachePaths(projectRoot, cacheDir, env);
+    // Remove ttsc-OWNED directories only, never the parent cache root.
+    const targets = [paths.pluginRoot];
+    // ttsc's nested `<root>/go-build` is only safe to delete when we are certain
+    // the root belongs to ttsc: the default `node_modules/.cache/ttsc`, or a root
+    // the user explicitly named `ttsc`. Under a shared root (e.g.
+    // `TTSC_CACHE_DIR=~/.cache`) a bare `<root>/go-build` could be the user's
+    // machine-wide GOCACHE, so it must never be removed by name.
+    const isTtscOwnedRoot = (!cacheDir && !env.TTSC_CACHE_DIR) ||
+        node_path_1.default.basename(paths.root) === TTSC_CACHE_DIRNAME;
+    if (isTtscOwnedRoot) {
+        targets.push(node_path_1.default.join(paths.root, GO_BUILD_CACHE_DIRNAME));
+    }
+    // An explicit TTSC_GO_CACHE_DIR is a ttsc-dedicated external cache; a
+    // user-provided GOCACHE (source "GOCACHE") is never removed.
+    if (paths.goBuildRootSource === "TTSC_GO_CACHE_DIR") {
+        targets.push(paths.goBuildRoot);
+    }
+    targets.push(node_path_1.default.join(projectRoot, NODE_MODULES_DIRNAME, ".ttsc"));
+    targets.push(node_path_1.default.join(projectRoot, ".ttsc"));
+    return targets;
 }
-function resolveUserCacheRoot() {
+/**
+ * Machine-global cache directories created by pre-0.17 ttsc releases (XDG /
+ * AppData / Library / `~/.cache`). ttsc no longer writes to any of these, but
+ * an upgraded machine can still hold a multi-GB orphaned cache here, so `ttsc
+ * clean` offers them for removal to reclaim that disk. Each entry is the whole
+ * `<userCacheRoot>/ttsc` directory (both its `plugins` and `go-build`), which
+ * was entirely ttsc-owned in those releases and is safe to remove.
+ */
+function legacyGlobalCacheTargets() {
+    const roots = new Set();
+    const home = node_os_1.default.homedir();
     const xdg = process.env.XDG_CACHE_HOME;
     if (xdg && node_path_1.default.isAbsolute(xdg)) {
-        return xdg;
+        roots.add(node_path_1.default.join(xdg, TTSC_CACHE_DIRNAME));
     }
     if (process.platform === "win32") {
         const local = process.env.LOCALAPPDATA;
         if (local && node_path_1.default.isAbsolute(local)) {
-            return local;
+            roots.add(node_path_1.default.join(local, TTSC_CACHE_DIRNAME));
         }
-        const home = node_os_1.default.homedir();
         if (home) {
-            return node_path_1.default.join(home, "AppData", "Local");
+            roots.add(node_path_1.default.join(home, "AppData", "Local", TTSC_CACHE_DIRNAME));
         }
     }
-    if (process.platform === "darwin") {
-        const home = node_os_1.default.homedir();
-        if (home) {
-            return node_path_1.default.join(home, "Library", "Caches");
-        }
+    else if (process.platform === "darwin" && home) {
+        roots.add(node_path_1.default.join(home, "Library", "Caches", TTSC_CACHE_DIRNAME));
     }
-    const home = node_os_1.default.homedir();
     if (home) {
-        return node_path_1.default.join(home, ".cache");
+        roots.add(node_path_1.default.join(home, ".cache", TTSC_CACHE_DIRNAME));
     }
-    return node_path_1.default.join(node_os_1.default.tmpdir(), "ttsc-cache");
+    return [...roots];
+}
+/** Report whether `child` equals `parent` or is nested beneath it. */
+function isPathWithin(child, parent) {
+    const rel = node_path_1.default.relative(parent, child);
+    return (rel === "" ||
+        (rel !== ".." && !rel.startsWith(`..${node_path_1.default.sep}`) && !node_path_1.default.isAbsolute(rel)));
 }
 function resolveGoCompiler() {
     const explicit = process.env.TTSC_GO_BINARY;
@@ -942,7 +1136,7 @@ function computeGoCompilerIdentity(goBinary, resolved) {
     if (!node_fs_1.default.existsSync(resolved)) {
         return "missing";
     }
-    const version = (0, node_child_process_1.spawnSync)(goBinary, ["version"], {
+    const version = spawnGoTool(goBinary, ["version"], {
         encoding: "utf8",
         windowsHide: true,
     });
@@ -967,14 +1161,28 @@ function resolveExecutableIdentityPath(binary) {
             return resolveRealPath(candidate);
         }
         if (process.platform === "win32") {
-            const executable = `${candidate}.exe`;
-            if (node_fs_1.default.existsSync(executable)) {
-                return resolveRealPath(executable);
+            // Probe every PATHEXT extension, not just `.exe`, so a compiler backed by
+            // a `.cmd`/`.bat` wrapper resolves to its real file and is hashed into the
+            // cache key. Otherwise the wrapper reads as "missing" and a change to it
+            // would not invalidate the cached plugin binary.
+            for (const ext of windowsExecutableExtensions()) {
+                const executable = `${candidate}${ext}`;
+                if (node_fs_1.default.existsSync(executable)) {
+                    return resolveRealPath(executable);
+                }
             }
         }
     }
     return binary;
 }
+function windowsExecutableExtensions() {
+    const pathext = process.env.PATHEXT;
+    const raw = pathext && pathext.length > 0 ? pathext : ".COM;.EXE;.BAT;.CMD";
+    return raw
+        .split(";")
+        .map((ext) => ext.trim().toLowerCase())
+        .filter((ext) => ext.length > 0);
+}
 function readPathEnvironment() {
     return process.env.PATH ?? process.env.Path ?? "";
 }
@@ -1003,7 +1211,7 @@ function hashGoBuildEnvironment(hash, goBinary, cwd) {
 function resolveGoBuildEnvironment(goBinary, cwd) {
     const values = new Map();
     if (goBinary !== undefined) {
-        const result = (0, node_child_process_1.spawnSync)(goBinary, ["env", "-json", ...GO_BUILD_ENV_KEYS], {
+        const result = spawnGoTool(goBinary, ["env", "-json", ...GO_BUILD_ENV_KEYS], {
             cwd,
             encoding: "utf8",
             env: goBuildEnv(goBinary),
@@ -1169,47 +1377,47 @@ function touchCacheEntry(cacheDir) {
         // Cache hits must not fail because metadata touch failed.
     }
 }
-function maybePruneGlobalPluginCache(root) {
+function prunePluginCacheRoot(root) {
     try {
         node_fs_1.default.mkdirSync(root, { recursive: true });
         const marker = node_path_1.default.join(root, CACHE_GC_MARKER_FILE);
         const now = Date.now();
         const lastRun = readTimestamp(marker);
-        if (lastRun !== null && now - lastRun < GLOBAL_CACHE_GC_INTERVAL_MS) {
+        if (lastRun !== null && now - lastRun < PLUGIN_CACHE_GC_INTERVAL_MS) {
             return;
         }
         node_fs_1.default.writeFileSync(marker, `${now}\n`);
-        pruneGlobalPluginCache(root, now);
+        prunePluginCacheEntries(root, now);
     }
     catch {
-        // Global cache GC is opportunistic; builds still proceed when it fails.
+        // Plugin-cache GC is opportunistic; builds still proceed when it fails.
     }
 }
-function pruneGlobalPluginCache(root, now) {
-    const entries = collectGlobalCacheEntries(root, now);
+function prunePluginCacheEntries(root, now) {
+    const entries = collectPluginCacheEntries(root, now);
     for (const entry of entries) {
-        if (now - entry.lastUsedAt <= GLOBAL_CACHE_ENTRY_MAX_AGE_MS) {
+        if (now - entry.lastUsedAt <= PLUGIN_CACHE_ENTRY_MAX_AGE_MS) {
             continue;
         }
         removeCacheEntry(entry);
     }
-    const remaining = collectGlobalCacheEntries(root, now);
+    const remaining = collectPluginCacheEntries(root, now);
     let total = remaining.reduce((sum, entry) => sum + entry.size, 0);
-    if (total <= GLOBAL_CACHE_MAX_BYTES) {
+    if (total <= PLUGIN_CACHE_MAX_BYTES) {
         return;
     }
     for (const entry of remaining.sort((a, b) => a.lastUsedAt - b.lastUsedAt)) {
-        if (total <= GLOBAL_CACHE_TARGET_BYTES) {
+        if (total <= PLUGIN_CACHE_TARGET_BYTES) {
             return;
         }
-        if (now - entry.lastUsedAt <= GLOBAL_CACHE_PROTECTED_AGE_MS) {
+        if (now - entry.lastUsedAt <= PLUGIN_CACHE_PROTECTED_AGE_MS) {
             continue;
         }
         removeCacheEntry(entry);
         total -= entry.size;
     }
 }
-function collectGlobalCacheEntries(root, now) {
+function collectPluginCacheEntries(root, now) {
     const entries = [];
     let dirents;
     try {