perf(core): propagate V8 compile cache to oxlint batch subprocesses (#893)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rayhanadev

.changeset/propagate-compile-cache-oxlint-children.md

@@ -0,0 +1,5 @@
+---
+"@react-doctor/core": patch
+---
+
+Propagate the V8 compile cache (`NODE_COMPILE_CACHE`) to oxlint batch subprocesses so later batches reuse warm bytecode. Measured ~2% of the lint phase on large multi-batch scans; no benefit for single-batch (`--diff`/`--staged`) scans. The dominant per-child cost is plugin eval/registration, which the compile cache does not address — this is a small internal speedup, not a headline. Opt out with `NODE_DISABLE_COMPILE_CACHE=1`.

packages/core/src/constants.ts

@@ -268,6 +268,11 @@ export const OXLINT_OUTPUT_MAX_BYTES = 50 * 1024 * 1024;
 // binding is markedly slower than on a developer laptop.
 export const OXLINT_SPAWN_TIMEOUT_MS = 60_000;
 
+// Directory name appended to os.tmpdir() to form the shared base for the V8
+// compile cache. Matches the base Node's own module.enableCompileCache() uses,
+// so the bin (parent) and the spawned oxlint batches (children) share one tree.
+export const NODE_COMPILE_CACHE_DIR_NAME = "node-compile-cache";
+
 export const DEAD_CODE_WORKER_TIMEOUT_MS = 120_000;
 
 // deslop's semantic pass builds a full TypeScript program and walks

packages/core/src/runners/oxlint/spawn-oxlint.ts

@@ -5,21 +5,9 @@ import {
   OXLINT_SPAWN_TIMEOUT_MS as DEFAULT_OXLINT_SPAWN_TIMEOUT_MS,
 } from "../../constants.js";
 import { OxlintBatchExceeded, OxlintSpawnFailed, ReactDoctorError } from "../../errors.js";
+import { buildOxlintChildEnv } from "../../utils/build-oxlint-child-env.js";
 
-// HACK: Sanitize child env so a developer's NODE_OPTIONS=--inspect (or
-// --max-old-space-size=128, etc.) doesn't leak into oxlint and either spawn a
-// debugger port or starve it of memory. We also drop npm_config_* lifecycle
-// vars to keep oxlint from picking up package-manager state. PATH, HOME,
-// NODE_ENV, NODE_PATH, etc. pass through unchanged.
-const SANITIZED_ENV: NodeJS.ProcessEnv = (() => {
-  const sanitized: NodeJS.ProcessEnv = {};
-  for (const [name, value] of Object.entries(process.env)) {
-    if (name === "NODE_OPTIONS" || name === "NODE_DEBUG") continue;
-    if (name.startsWith("npm_config_")) continue;
-    sanitized[name] = value;
-  }
-  return sanitized;
-})();
+const SANITIZED_ENV: NodeJS.ProcessEnv = buildOxlintChildEnv(process.env);
 
 /**
  * Spawn one oxlint subprocess with hard ceilings on wall time and

packages/core/src/utils/build-oxlint-child-env.ts

@@ -0,0 +1,34 @@
+import os from "node:os";
+import * as path from "node:path";
+import { NODE_COMPILE_CACHE_DIR_NAME } from "../constants.js";
+
+// Sanitize the child env so a developer's NODE_OPTIONS=--inspect (or
+// --max-old-space-size=128, etc.) doesn't leak into oxlint and either spawn a
+// debugger port or starve it of memory; drop npm_config_* lifecycle vars so
+// oxlint can't pick up package-manager state. PATH, HOME, NODE_ENV, NODE_PATH
+// pass through unchanged.
+//
+// oxlint batches are fresh `node` children that re-parse oxlint + plugin JS
+// per spawn. The bin enables the V8 compile cache for the parent only, so
+// propagate NODE_COMPILE_CACHE to the children that do the repeated work.
+// Set the shared BASE dir (not the parent's version-specific getCompileCacheDir),
+// because the child may run a different node (the nvm fallback in
+// resolveNodeForOxlint): Node nests each node version under its own subdir of
+// the base, so there is no cross-version cache poisoning, and a same-version
+// child transparently reads what the parent warmed.
+export const buildOxlintChildEnv = (sourceEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv => {
+  const childEnv: NodeJS.ProcessEnv = {};
+  for (const [name, value] of Object.entries(sourceEnv)) {
+    if (name === "NODE_OPTIONS" || name === "NODE_DEBUG") continue;
+    if (name.startsWith("npm_config_")) continue;
+    childEnv[name] = value;
+  }
+
+  const isCompileCacheDisabled = Boolean(sourceEnv.NODE_DISABLE_COMPILE_CACHE);
+  const isCompileCacheAlreadySet = childEnv.NODE_COMPILE_CACHE !== undefined;
+  if (!isCompileCacheDisabled && !isCompileCacheAlreadySet) {
+    childEnv.NODE_COMPILE_CACHE = path.join(os.tmpdir(), NODE_COMPILE_CACHE_DIR_NAME);
+  }
+
+  return childEnv;
+};

packages/core/tests/build-oxlint-child-env.test.ts

@@ -0,0 +1,51 @@
+import os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vite-plus/test";
+import { NODE_COMPILE_CACHE_DIR_NAME } from "../src/constants.js";
+import { buildOxlintChildEnv } from "../src/utils/build-oxlint-child-env.js";
+
+const SHARED_COMPILE_CACHE_BASE = path.join(os.tmpdir(), NODE_COMPILE_CACHE_DIR_NAME);
+
+describe("buildOxlintChildEnv", () => {
+  it("sets NODE_COMPILE_CACHE to the shared tmp base dir by default", () => {
+    const childEnv = buildOxlintChildEnv({ PATH: "/usr/bin" });
+    expect(childEnv.NODE_COMPILE_CACHE).toBe(SHARED_COMPILE_CACHE_BASE);
+  });
+
+  it("respects NODE_DISABLE_COMPILE_CACHE and leaves NODE_COMPILE_CACHE unset", () => {
+    const childEnv = buildOxlintChildEnv({ PATH: "/usr/bin", NODE_DISABLE_COMPILE_CACHE: "1" });
+    expect(childEnv.NODE_COMPILE_CACHE).toBeUndefined();
+  });
+
+  it("does not clobber an inherited NODE_COMPILE_CACHE value", () => {
+    const childEnv = buildOxlintChildEnv({ PATH: "/usr/bin", NODE_COMPILE_CACHE: "/custom/dir" });
+    expect(childEnv.NODE_COMPILE_CACHE).toBe("/custom/dir");
+  });
+
+  it("preserves an inherited empty-string NODE_COMPILE_CACHE (the guard is !== undefined)", () => {
+    const childEnv = buildOxlintChildEnv({ PATH: "/usr/bin", NODE_COMPILE_CACHE: "" });
+    expect(childEnv.NODE_COMPILE_CACHE).toBe("");
+  });
+
+  it("treats the disable and inherited guards independently", () => {
+    const childEnv = buildOxlintChildEnv({
+      PATH: "/usr/bin",
+      NODE_DISABLE_COMPILE_CACHE: "1",
+      NODE_COMPILE_CACHE: "/custom/dir",
+    });
+    expect(childEnv.NODE_COMPILE_CACHE).toBe("/custom/dir");
+  });
+
+  it("still strips NODE_OPTIONS, NODE_DEBUG, and npm_config_* while passing PATH through", () => {
+    const childEnv = buildOxlintChildEnv({
+      PATH: "/usr/bin",
+      NODE_OPTIONS: "--inspect",
+      NODE_DEBUG: "module",
+      npm_config_foo: "bar",
+    });
+    expect(childEnv.NODE_OPTIONS).toBeUndefined();
+    expect(childEnv.NODE_DEBUG).toBeUndefined();
+    expect(childEnv.npm_config_foo).toBeUndefined();
+    expect(childEnv.PATH).toBe("/usr/bin");
+  });
+});

packages/core/tests/spawn-oxlint-compile-cache.test.ts

@@ -0,0 +1,29 @@
+import os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vite-plus/test";
+import { NODE_COMPILE_CACHE_DIR_NAME } from "../src/constants.js";
+import { spawnOxlint } from "../src/runners/oxlint/spawn-oxlint.js";
+
+// spawn-oxlint.ts captures SANITIZED_ENV from the live process.env at module
+// load, so this default-case assertion only holds when the test process itself
+// has neither opted out (NODE_DISABLE_COMPILE_CACHE) nor pre-set
+// NODE_COMPILE_CACHE — the same two guards buildOxlintChildEnv honors. Skip
+// rather than fail spuriously for a developer running with the documented
+// opt-out exported; that path is covered by the pure-helper unit test.
+const isCompileCacheEnvOverridden =
+  Boolean(process.env.NODE_DISABLE_COMPILE_CACHE) || process.env.NODE_COMPILE_CACHE !== undefined;
+
+describe("spawnOxlint propagates the V8 compile cache to children", () => {
+  it.skipIf(isCompileCacheEnvOverridden)(
+    "child sees NODE_COMPILE_CACHE set to the shared tmp base dir",
+    async () => {
+      const stdout = await spawnOxlint(
+        ["-e", "process.stdout.write(process.env.NODE_COMPILE_CACHE ?? 'unset')"],
+        process.cwd(),
+        process.execPath,
+        5_000,
+      );
+      expect(stdout).toBe(path.join(os.tmpdir(), NODE_COMPILE_CACHE_DIR_NAME));
+    },
+  );
+});