perf(test): coordinate source require cache misses

Signed-off-by: Ho Lim <subhoya@gmail.com>

Author: HOYALIM

test/helpers/register-source-require.ts

@@ -5,6 +5,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import Module from "node:module";
 import path from "node:path";
+import { performance } from "node:perf_hooks";
 import ts from "typescript";
 
 type CommonJsModule = NodeModule & {
@@ -62,6 +63,221 @@ const compilerOptions: ts.CompilerOptions = {
 const cacheDir = path.join(repoRoot, "node_modules", ".cache", "nemoclaw-source-require");
 const compilerFingerprint = JSON.stringify({ compilerOptions, typescript: ts.version });
 fs.mkdirSync(cacheDir, { recursive: true });
+const cacheWaitMs = envInt("NEMOCLAW_SOURCE_REQUIRE_CACHE_WAIT_MS", 5_000);
+const cachePollMs = envInt("NEMOCLAW_SOURCE_REQUIRE_CACHE_POLL_MS", 25);
+const cacheLockStaleMs = envInt("NEMOCLAW_SOURCE_REQUIRE_CACHE_LOCK_STALE_MS", 30_000);
+const statsPath = process.env.NEMOCLAW_SOURCE_REQUIRE_STATS;
+
+const stats = {
+  cacheHits: 0,
+  cacheMisses: 0,
+  compileMs: 0,
+  duplicateFallbacks: 0,
+  files: 0,
+  lockWaits: 0,
+  readCacheMs: 0,
+  staleLocks: 0,
+  transforms: 0,
+  transformMs: 0,
+  waitMs: 0,
+};
+
+function envInt(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function nowMs(): number {
+  return performance.now();
+}
+
+const sleepBuffer = new SharedArrayBuffer(4);
+const sleepArray = new Int32Array(sleepBuffer);
+
+function sleepSync(ms: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(sleepArray, 0, 0, ms);
+}
+
+function readCachedOutput(cachePath: string): string | null {
+  const start = nowMs();
+  try {
+    const output = fs.readFileSync(cachePath, "utf8");
+    stats.readCacheMs += nowMs() - start;
+    return output;
+  } catch (error) {
+    stats.readCacheMs += nowMs() - start;
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return null;
+  }
+}
+
+function writeAtomic(cachePath: string, outputText: string): void {
+  const temporaryPath = `${cachePath}.${process.pid}.${crypto.randomUUID()}`;
+  fs.writeFileSync(temporaryPath, outputText, { flag: "wx", mode: 0o600 });
+  try {
+    fs.renameSync(temporaryPath, cachePath);
+  } catch (error) {
+    fs.rmSync(temporaryPath, { force: true });
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+}
+
+function parseLockOwner(lockPath: string): { pid?: number } {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    return typeof parsed?.pid === "number" && Number.isInteger(parsed.pid) && parsed.pid > 0
+      ? { pid: parsed.pid }
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function processIsRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+function tryAcquireLock(lockPath: string, filename: string): boolean {
+  try {
+    fs.writeFileSync(
+      lockPath,
+      `${JSON.stringify({
+        filename,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        startedAtMs: Date.now(),
+      })}\n`,
+      { flag: "wx", mode: 0o600 },
+    );
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    return false;
+  }
+}
+
+function reclaimStaleLock(lockPath: string): boolean {
+  if (cacheLockStaleMs <= 0) return false;
+  let ageMs: number;
+  try {
+    ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+  if (ageMs < cacheLockStaleMs) return false;
+  const { pid } = parseLockOwner(lockPath);
+  if (pid !== undefined && processIsRunning(pid)) return false;
+  try {
+    fs.rmSync(lockPath, { force: true });
+    stats.staleLocks += 1;
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function transpileSource(source: string, filename: string): string {
+  const start = nowMs();
+  const result = ts.transpileModule(source, {
+    compilerOptions,
+    fileName: filename,
+    reportDiagnostics: true,
+  });
+  stats.transformMs += nowMs() - start;
+  stats.transforms += 1;
+  const errors = result.diagnostics?.filter(
+    (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+  );
+  if (errors && errors.length > 0) {
+    throw new Error(
+      errors
+        .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
+        .join("\n"),
+    );
+  }
+  return result.outputText;
+}
+
+function waitForCache(cachePath: string): string | null {
+  if (cacheWaitMs <= 0) return null;
+  const start = nowMs();
+  const deadline = start + cacheWaitMs;
+  stats.lockWaits += 1;
+
+  while (nowMs() < deadline) {
+    const output = readCachedOutput(cachePath);
+    if (output !== null) {
+      stats.waitMs += nowMs() - start;
+      return output;
+    }
+    sleepSync(Math.min(cachePollMs, Math.max(0, deadline - nowMs())));
+  }
+  stats.waitMs += nowMs() - start;
+  return null;
+}
+
+function compileWithCache(filename: string, source: string, cachePath: string): string {
+  const cached = readCachedOutput(cachePath);
+  if (cached !== null) {
+    stats.cacheHits += 1;
+    return cached;
+  }
+  stats.cacheMisses += 1;
+
+  const lockPath = `${cachePath}.lock`;
+  let ownsLock = tryAcquireLock(lockPath, filename);
+  if (!ownsLock && reclaimStaleLock(lockPath)) {
+    const cachedAfterReclaim = readCachedOutput(cachePath);
+    if (cachedAfterReclaim !== null) {
+      stats.cacheHits += 1;
+      return cachedAfterReclaim;
+    }
+    ownsLock = tryAcquireLock(lockPath, filename);
+  }
+
+  if (!ownsLock) {
+    const waited = waitForCache(cachePath);
+    if (waited !== null) {
+      stats.cacheHits += 1;
+      return waited;
+    }
+    stats.duplicateFallbacks += 1;
+    return transpileSource(source, filename);
+  }
+
+  try {
+    const outputText = transpileSource(source, filename);
+    writeAtomic(cachePath, outputText);
+    return outputText;
+  } finally {
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+if (statsPath) {
+  process.once("exit", () => {
+    if (stats.files === 0) return;
+    const row = {
+      ...stats,
+      cacheDir,
+      label: process.env.NEMOCLAW_SOURCE_REQUIRE_STATS_LABEL ?? null,
+      pid: process.pid,
+      rssMb: Math.round((process.memoryUsage().rss / 1024 / 1024) * 10) / 10,
+    };
+    fs.mkdirSync(path.dirname(statsPath), { recursive: true });
+    fs.appendFileSync(statsPath, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+  });
+}
 
 const resolveFilename = moduleRuntime._resolveFilename;
 moduleRuntime._resolveFilename = function resolveSourceFilename(request, parent, isMain, options) {
@@ -82,6 +298,8 @@ moduleRuntime._resolveFilename = function resolveSourceFilename(request, parent,
 };
 
 moduleRuntime._extensions[".ts"] = (module, filename) => {
+  const compileStart = nowMs();
+  stats.files += 1;
   const source = fs.readFileSync(filename, "utf8");
   const cacheKey = crypto
     .createHash("sha256")
@@ -92,36 +310,7 @@ moduleRuntime._extensions[".ts"] = (module, filename) => {
     .update(compilerFingerprint)
     .digest("hex");
   const cachePath = path.join(cacheDir, `${cacheKey}.cjs`);
-  let outputText: string;
-
-  try {
-    outputText = fs.readFileSync(cachePath, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-    const result = ts.transpileModule(source, {
-      compilerOptions,
-      fileName: filename,
-      reportDiagnostics: true,
-    });
-    const errors = result.diagnostics?.filter(
-      (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
-    );
-    if (errors && errors.length > 0) {
-      throw new Error(
-        errors
-          .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
-          .join("\n"),
-      );
-    }
-    outputText = result.outputText;
-    const temporaryPath = `${cachePath}.${process.pid}.${crypto.randomUUID()}`;
-    fs.writeFileSync(temporaryPath, outputText, { flag: "wx", mode: 0o600 });
-    try {
-      fs.renameSync(temporaryPath, cachePath);
-    } catch (error) {
-      fs.rmSync(temporaryPath, { force: true });
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-    }
-  }
+  const outputText = compileWithCache(filename, source, cachePath);
+  stats.compileMs += nowMs() - compileStart;
   module._compile(outputText, filename);
 };