next-leak 0.7.0 → 0.8.0

package/dist/cli-args.d.ts

@@ -10,12 +10,15 @@ export type CliRunOptions = {
     quick: boolean;
     noResolve: boolean;
     diffAll: boolean;
+    attributeBuild: boolean;
     writeConfig: boolean;
     output: string | null;
 };
 export type CliBuildOptions = {
     appDir: string;
     output: string | null;
+    /** Opt-in: signal the worker for snapshots and name what it retains. */
+    attributeBuild: boolean;
 };
 export type ParsedCli = {
     kind: "run";

package/dist/cli.js

@@ -2,10 +2,14 @@
 import { createRequire as __nextLeakCreateRequire } from 'node:module';import { fileURLToPath as __nextLeakFileURLToPath } from 'node:url';import { dirname as __nextLeakDirname } from 'node:path';const require = __nextLeakCreateRequire(import.meta.url);const __filename = __nextLeakFileURLToPath(import.meta.url);const __dirname = __nextLeakDirname(__filename);
 import {
   RouteConfigError,
+  SnapshotError,
   TargetError,
+  attributeDiff,
   checkRuntime,
+  diffSnapshotFiles,
   discoverPagesRoutes,
   discoverRoutes,
+  extractModuleRegistry,
   formatReport,
   hasPlaceholders,
   helpText,
@@ -16,7 +20,7 @@ import {
   runMeasurement,
   unregisterChild,
   validateTarget
-} from "./chunk-BXDUPN6Z.js";
+} from "./chunk-LFGWGM5Z.js";
 import {
   classifyTrend
 } from "./chunk-EJ26OBZI.js";
@@ -25,11 +29,166 @@ import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts
 import { spawn as spawn2 } from "child_process";
-import { writeFile } from "fs/promises";
+import { mkdir, writeFile } from "fs/promises";
 import { createRequire } from "module";
-import path3 from "path";
+import path5 from "path";
 import { fileURLToPath } from "url";
 
+// src/build-attribution.ts
+import path2 from "path";
+
+// src/build-snapshot.ts
+import { readdirSync, unlinkSync } from "fs";
+import { readdir, rename, unlink } from "fs/promises";
+import path from "path";
+var PARSEABLE_WORKER_RSS_BYTES = 1024 * 1024 * 1024;
+var START_UP_FLOOR_BYTES = 128 * 1024 * 1024;
+var MIN_PAIR_GROWTH_BYTES = 128 * 1024 * 1024;
+var AFTER_TARGET_RSS_BYTES = Math.floor(PARSEABLE_WORKER_RSS_BYTES * 0.9);
+function decideCapture(rssBytes, stage, baselineRssBytes = null) {
+  if (stage === "pair-taken" || stage === "missed") {
+    return "wait";
+  }
+  if (stage === "waiting") {
+    if (rssBytes > PARSEABLE_WORKER_RSS_BYTES) {
+      return "give-up";
+    }
+    return rssBytes >= START_UP_FLOOR_BYTES ? "take-baseline" : "wait";
+  }
+  const grown = rssBytes - (baselineRssBytes ?? 0);
+  if (rssBytes > PARSEABLE_WORKER_RSS_BYTES) {
+    return "give-up";
+  }
+  if (rssBytes < AFTER_TARGET_RSS_BYTES) {
+    return "wait";
+  }
+  return grown >= MIN_PAIR_GROWTH_BYTES ? "take-after" : "wait";
+}
+var SNAPSHOT_NAME = /^Heap\.\d{8}\.\d{6}\.(\d+)\.\d+\.(\d+)\.heapsnapshot$/;
+var byCodeUnit = (left, right) => {
+  if (left === right) {
+    return 0;
+  }
+  return left < right ? -1 : 1;
+};
+function snapshotsWrittenBy(pid, filenames) {
+  return filenames.filter((name) => {
+    const match = SNAPSHOT_NAME.exec(name);
+    return match !== null && Number(match[1]) === pid;
+  }).sort(byCodeUnit);
+}
+async function collectSnapshotPair(appDir, outDir, pid) {
+  let entries;
+  try {
+    entries = await readdir(appDir);
+  } catch {
+    return null;
+  }
+  const written = snapshotsWrittenBy(pid, entries);
+  const [baseline, after] = written;
+  if (baseline === void 0 || after === void 0) {
+    return null;
+  }
+  const baselineFile = path.join(outDir, `worker-${pid}-baseline.heapsnapshot`);
+  const afterFile = path.join(outDir, `worker-${pid}-after.heapsnapshot`);
+  try {
+    await rename(path.join(appDir, baseline), baselineFile);
+    await rename(path.join(appDir, after), afterFile);
+  } catch {
+    await unlink(baselineFile).catch(() => {
+    });
+    await unlink(afterFile).catch(() => {
+    });
+    return null;
+  }
+  return { baselineFile, afterFile };
+}
+async function discardSnapshots(appDir, pid) {
+  let entries;
+  try {
+    entries = await readdir(appDir);
+  } catch {
+    return;
+  }
+  for (const name of snapshotsWrittenBy(pid, entries)) {
+    try {
+      await unlink(path.join(appDir, name));
+    } catch {
+    }
+  }
+}
+function bracketedShare(baselineRssBytes, afterRssBytes, peakRssBytes) {
+  const total = peakRssBytes - baselineRssBytes;
+  if (total <= 0) {
+    return 1;
+  }
+  return Math.min(1, Math.max(0, (afterRssBytes - baselineRssBytes) / total));
+}
+var pendingCapture = null;
+function registerPendingCapture(appDir, pid) {
+  pendingCapture = { appDir, pid };
+}
+function clearPendingCapture() {
+  pendingCapture = null;
+}
+function discardPendingSnapshotsSync() {
+  if (pendingCapture === null) {
+    return;
+  }
+  const { appDir, pid } = pendingCapture;
+  pendingCapture = null;
+  try {
+    for (const name of snapshotsWrittenBy(pid, readdirSync(appDir))) {
+      try {
+        unlinkSync(path.join(appDir, name));
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+
+// src/build-attribution.ts
+var defaultDeps = {
+  diff: diffSnapshotFiles,
+  registry: extractModuleRegistry
+};
+async function attributeBuildCapture(result, appDir, onProgress = () => {
+}, deps = defaultDeps) {
+  const capture = result.capture;
+  if (capture === null) {
+    return null;
+  }
+  onProgress(`diffing what worker ${capture.pid} retained`);
+  let diff;
+  try {
+    diff = await deps.diff(capture.files.baselineFile, capture.files.afterFile);
+  } catch (cause) {
+    onProgress(
+      cause instanceof SnapshotError ? `no attribution: ${cause.message}` : `no attribution: the snapshot pair could not be diffed`
+    );
+    return null;
+  }
+  const registry = await deps.registry(path2.join(appDir, ".next", "server"));
+  return {
+    diff,
+    attributed: attributeDiff(diff, registry),
+    registrySize: registry.size,
+    // Against the captured worker's own peak. `result.peakWorkerRssBytes` is
+    // the highest of every worker, which on a multi-worker build can belong to
+    // a process these findings say nothing about.
+    bracketed: bracketedShare(
+      capture.baselineRssBytes,
+      capture.afterRssBytes,
+      capture.peakRssBytes
+    ),
+    baselineRssBytes: capture.baselineRssBytes,
+    afterRssBytes: capture.afterRssBytes,
+    baselineFile: capture.files.baselineFile,
+    afterFile: capture.files.afterFile
+  };
+}
+
 // src/build-report.ts
 var MB = 1024 * 1024;
 var mb = (bytes) => `${(bytes / MB).toFixed(1)} MB`;
@@ -46,7 +205,42 @@ function growthLine(result) {
   const perPage = result.retentionPerPageBytes === null ? "" : `  (${mbPrecise(result.retentionPerPageBytes)}/page over ${result.pagesGenerated} pages)`;
   return `      grew ${mb(result.netGrowthBytes)} across the generation phase${perPage}`;
 }
-function formatBuildReport(result) {
+var MAX_REPORTED_FINDINGS = 3;
+function attributionLines(attribution) {
+  if (attribution === null) {
+    return [];
+  }
+  const { diff, attributed, bracketed } = attribution;
+  const findings = [...diff.grownNodes, ...diff.newNodes];
+  if (findings.length === 0) {
+    return ["", `  nothing grew between the two snapshots`];
+  }
+  const lines = [
+    "",
+    `  what it retained, between ${mb(attribution.baselineRssBytes)} and ${mb(attribution.afterRssBytes)} of worker rss \u2014`,
+    `  ${(bracketed * 100).toFixed(0)}% of the growth this run observed. The rest is not`,
+    `  attributed: a snapshot taken higher up cannot be parsed back.`
+  ];
+  if (attribution.registrySize === 0) {
+    lines.push(
+      `      no module registry resolved, so no owner is named below \u2014 only`,
+      `      where the bytes hang`
+    );
+  }
+  lines.push(
+    `      snapshots: ${attribution.baselineFile} / ${attribution.afterFile}`
+  );
+  for (const [index, finding] of findings.slice(0, MAX_REPORTED_FINDINGS).entries()) {
+    const owner = attributed.findings[index];
+    const name = owner?.source ?? owner?.packageName ?? owner?.owner ?? "unattributed";
+    lines.push(
+      `      \u21B3 ${finding.name === "" ? "(anonymous)" : finding.name} ${mb(finding.retainedBytes)} \xB7 ${name}`,
+      `          ${finding.retainerChain}`
+    );
+  }
+  return lines;
+}
+function formatBuildReport(result, attribution = null) {
   const lines = [`next-leak build \xB7 ${result.appDir}`, ""];
   if (result.strippedCapWarning !== null) {
     lines.push(`  \u25B2 ${result.strippedCapWarning}`, "");
@@ -101,6 +295,7 @@ function formatBuildReport(result) {
     lines.push(`      ${result.workers.length} workers ran; the verdict is the worst of them`);
   }
   lines.push(
+    ...attributionLines(attribution),
     "",
     `  peak worker rss ${mb(result.peakWorkerRssBytes)} \xB7 sampled from the process tree, so a`,
     `  spike shorter than the polling interval is not observed`
@@ -110,11 +305,11 @@ function formatBuildReport(result) {
 
 // src/build-run.ts
 import { spawn } from "child_process";
-import path2 from "path";
+import path4 from "path";
 
 // src/build-target.ts
-import { access, readFile, readdir } from "fs/promises";
-import path from "path";
+import { access, readFile, readdir as readdir2 } from "fs/promises";
+import path3 from "path";
 var CONFIG_NAMES = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
 async function exists(file) {
   try {
@@ -126,14 +321,14 @@ async function exists(file) {
 }
 async function readPackageJson(appDir) {
   try {
-    return JSON.parse(await readFile(path.join(appDir, "package.json"), "utf8"));
+    return JSON.parse(await readFile(path3.join(appDir, "package.json"), "utf8"));
   } catch {
     return null;
   }
 }
 async function usesWorkerThreads(appDir) {
   for (const name of CONFIG_NAMES) {
-    const file = path.join(appDir, name);
+    const file = path3.join(appDir, name);
     if (!await exists(file)) {
       continue;
     }
@@ -145,10 +340,10 @@ async function usesWorkerThreads(appDir) {
   return false;
 }
 async function validateBuildTarget(appDir) {
-  const resolved = path.resolve(appDir);
+  const resolved = path3.resolve(appDir);
   let entries;
   try {
-    entries = await readdir(resolved);
+    entries = await readdir2(resolved);
   } catch {
     throw new TargetError("NO_BUILD", `Cannot read ${resolved}.`);
   }
@@ -319,15 +514,22 @@ async function sampleProcessTable() {
 // src/build-run.ts
 var POLL_MS = 500;
 function spawnNextBuild(appDir, env) {
-  const nextBin = path2.join(appDir, "node_modules", "next", "dist", "bin", "next");
+  const nextBin = path4.join(appDir, "node_modules", "next", "dist", "bin", "next");
   return spawn(process.execPath, [nextBin, "build"], {
     cwd: appDir,
     env,
     stdio: ["ignore", "pipe", "pipe"]
   });
 }
-var defaultDeps = {
+var signalWorker = (pid) => {
+  try {
+    process.kill(pid, "SIGUSR2");
+  } catch {
+  }
+};
+var defaultDeps2 = {
   spawnBuild: spawnNextBuild,
+  signalWorker,
   sampleTable: sampleProcessTable,
   now: () => Date.now(),
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
@@ -346,6 +548,22 @@ function recordSample(rows, rootPid, atMs, workers, parentSamples) {
     workers.set(row.pid, series);
   }
 }
+async function collectCapture(options) {
+  const { appDir, workDir, pid, stage, baselineRssBytes, afterRssBytes } = options;
+  if (workDir === void 0 || pid === null) {
+    return null;
+  }
+  if (stage !== "pair-taken" || baselineRssBytes === null || afterRssBytes === null) {
+    await discardSnapshots(appDir, pid);
+    return null;
+  }
+  const files = await collectSnapshotPair(appDir, workDir, pid);
+  if (files === null) {
+    await discardSnapshots(appDir, pid);
+    return null;
+  }
+  return { pid, files, baselineRssBytes, afterRssBytes, peakRssBytes: options.peakRssBytes };
+}
 function worstWorker(workers) {
   let worst = null;
   let worstGrowth = -Infinity;
@@ -359,7 +577,7 @@ function worstWorker(workers) {
   return worst;
 }
 var peakOf = (samples) => samples.reduce((highest, sample) => Math.max(highest, sample.rssBytes), 0);
-async function runBuildMeasurement(options, deps = defaultDeps) {
+async function runBuildMeasurement(options, deps = defaultDeps2) {
   const target = await validateBuildTarget(options.appDir);
   const progress = options.onProgress ?? (() => {
   });
@@ -368,8 +586,13 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
   if (strippedCapWarning !== null) {
     progress(strippedCapWarning);
   }
+  const capturing = options.workDir !== void 0;
+  const buildEnv = capturing ? {
+    ...env,
+    NODE_OPTIONS: `${env["NODE_OPTIONS"] ?? ""} --heapsnapshot-signal=SIGUSR2`.trim()
+  } : env;
   progress(`building ${target.appDir}`);
-  const child = deps.spawnBuild(target.appDir, env);
+  const child = deps.spawnBuild(target.appDir, buildEnv);
   registerChild(child);
   let output = "";
   const capture = (chunk) => {
@@ -392,6 +615,36 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
   };
   options.signal?.addEventListener("abort", abort, { once: true });
   let samplingFailure = null;
+  let capturePid = null;
+  let captureStage = "waiting";
+  let captureBaselineRss = null;
+  let captureAfterRss = null;
+  const stepCapture = (rows, rootPid) => {
+    const descendants = descendantsOf(rows, rootPid);
+    const followed = capturePid === null ? descendants.find(isStaticGenWorker) : descendants.find((row) => row.pid === capturePid);
+    if (followed === void 0) {
+      return;
+    }
+    capturePid ??= followed.pid;
+    switch (decideCapture(followed.rssBytes, captureStage, captureBaselineRss)) {
+      case "take-baseline":
+        deps.signalWorker(followed.pid);
+        captureStage = "baseline-taken";
+        captureBaselineRss = followed.rssBytes;
+        registerPendingCapture(target.appDir, followed.pid);
+        return;
+      case "take-after":
+        deps.signalWorker(followed.pid);
+        captureStage = "pair-taken";
+        captureAfterRss = followed.rssBytes;
+        return;
+      case "give-up":
+        captureStage = "missed";
+        return;
+      case "wait":
+        return;
+    }
+  };
   const polling = (async () => {
     while (!finished) {
       await deps.sleep(POLL_MS);
@@ -404,6 +657,9 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
         return;
       }
       recordSample(sample.rows, child.pid, deps.now() - startedAt, workerSamples, parentSamples);
+      if (capturing) {
+        stepCapture(sample.rows, child.pid);
+      }
     }
   })();
   const exitCode = await exit;
@@ -412,6 +668,17 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
   unregisterChild(child);
   const workers = [...workerSamples].map(([pid, samples]) => ({ pid, samples }));
   const heapExhausted = diedOfHeapExhaustion(output);
+  const capturedSamples = capturePid === null ? void 0 : workerSamples.get(capturePid);
+  const workerCapture = await collectCapture({
+    appDir: target.appDir,
+    workDir: options.workDir,
+    pid: capturePid,
+    stage: captureStage,
+    baselineRssBytes: captureBaselineRss,
+    afterRssBytes: captureAfterRss,
+    peakRssBytes: capturedSamples === void 0 ? 0 : peakOf(capturedSamples)
+  });
+  clearPendingCapture();
   const pagesGenerated = pagesGeneratedFrom(output);
   if (workers.length === 0) {
     return {
@@ -430,6 +697,7 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
       pagesGenerated,
       retentionPerPageBytes: null,
       heapExhausted,
+      capture: workerCapture,
       strippedCapWarning,
       exitCode,
       output
@@ -458,6 +726,9 @@ async function runBuildMeasurement(options, deps = defaultDeps) {
     pagesGenerated,
     retentionPerPageBytes: measured && growthBytes > 0 && pagesGenerated !== null && pagesGenerated > 0 ? growthBytes / pagesGenerated : null,
     heapExhausted,
+    // A pair belonging to a worker other than the one judged supports no claim
+    // about the verdict above, so it is dropped rather than reported next to it.
+    capture: workerCapture !== null && workerCapture.pid === worst?.pid ? workerCapture : null,
     strippedCapWarning,
     exitCode,
     output
@@ -491,6 +762,7 @@ function installInterruptHandlers() {
     process.on(signalName, () => {
       interrupts += 1;
       if (interrupts > 1) {
+        discardPendingSnapshotsSync();
         process.exit(130);
       }
       console.error("\n\xB7 interrupted \u2014 stopping the measured process and writing a partial run.json");
@@ -523,14 +795,31 @@ function handleNonRunCommand(parsed) {
   }
   return false;
 }
-async function runBuildCommand(appDir) {
+async function runBuildCommand(appDir, outputDir, attribute) {
   const aborter = installInterruptHandlers();
+  const workDir = path5.join(
+    outputDir ?? path5.join(appDir, ".next-leak"),
+    (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")
+  );
+  await mkdir(workDir, { recursive: true });
   const result = await runBuildMeasurement({
     appDir,
+    // Capture is opt-in because signalling a worker for a heap snapshot can
+    // stall the build it is measuring. Observed on the #97464 reproduction:
+    // the second signal landed and the worker sat frozen for fourteen minutes
+    // with an empty snapshot file on disk, and on an earlier run for ninety.
+    // A curve and a verdict are what this command promises; naming the objects
+    // is worth asking for, not worth risking every run for.
+    ...attribute && { workDir },
     signal: aborter.signal,
     onProgress: (message) => console.error(`\xB7 ${message}`)
   });
-  console.log(formatBuildReport(result));
+  const attribution = await attributeBuildCapture(
+    result,
+    appDir,
+    (message) => console.error(`\xB7 ${message}`)
+  );
+  console.log(formatBuildReport(result, attribution));
   if (aborter.signal.aborted) {
     process.exitCode = 130;
   }
@@ -543,7 +832,7 @@ async function writeConfigSkeleton(appDir) {
     console.log("no route needs sample params \u2014 nothing to write");
     return;
   }
-  const file = path3.join(target.appDir, "next-leak.config.json");
+  const file = path5.join(target.appDir, "next-leak.config.json");
   try {
     await writeFile(file, `${skeleton}
 `, { flag: "wx" });
@@ -567,7 +856,11 @@ async function main() {
     return;
   }
   if (parsed.kind === "build") {
-    await runBuildCommand(parsed.options.appDir);
+    await runBuildCommand(
+      parsed.options.appDir,
+      parsed.options.output,
+      parsed.options.attributeBuild
+    );
     return;
   }
   if (parsed.kind !== "run") {

package/dist/index.js

@@ -39,7 +39,7 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-BXDUPN6Z.js";
+} from "./chunk-LFGWGM5Z.js";
 import {
   renderHtmlReport
 } from "./chunk-RS3AO7HB.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-leak",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",