next-leak 0.7.0 → 0.9.0

package/README.md

@@ -142,14 +142,20 @@ Dynamic routes need sample params in `next-leak.config.json` in your app dir:
 ```json
 {
   "params": { "lang": "en" },
-  "routes": { "/products/[id]": { "id": "42" } },
+  "routes": { "/products/[id]": { "id": "42-{n}" } },
   "headers": { "accept-encoding": "gzip, br", "cookie": "session=..." }
 }
 ```
 
-`--write-config` generates that file for you, filling in values from paths your
-build already prerendered where it knows them, so it usually resolves on the
-first try. When a run skips a route it prints the same fragment.
+`--write-config` generates that file for you. It takes the *shape* of each value
+from paths your build already prerendered, and makes the value itself move:
+`post-0` becomes `post-{n}`. A value the build prerendered is the one value
+guaranteed not to measure anything — every request hits the same warm cache
+entry, so the route reads as flat whatever it retains, and that false negative
+lands on exactly the leaks being reported now (`use cache`, `cacheComponents`
+and ISR all key on the params). If your app answers 404 for params it never
+prerendered, the run says so through its non-2xx count; drop the marker then.
+When a run skips a route it prints the same fragment.
 
 ```json
 ```
@@ -215,7 +221,7 @@ separates them, because each one has a different fix:
   allocator, external-buffer or fragmentation problem, not a JS-heap leak.
 - **`leak`** — the report names the culprit when attribution resolves: your file (`culprit: src/app/x/page.tsx (your code)`), a dependency (package name), or framework internals. An `ISSUE-<route>.md` draft is generated **when the evidence plainly supports the verdict** — a `leak` carrying low-confidence warnings (growth barely over the threshold, one cycle dominating the mean, too few cycles for its size) gets the verdict but no draft, because a draft is written to be pasted into someone else's tracker. If the leak is app-owned, the draft tells you **not** to file it upstream.
 - **`inconclusive`** — the evidence does not decide. The run does not stop there: any inconclusive route is **measured again automatically**, with twice the cycles, and the second pass is what you see (`resolved at 8 cycles` next to the verdict). On the reproduction for [#95094](https://github.com/vercel/next.js/issues/95094), `--quick` alone reports `inconclusive` on three deltas and then comes back with the leak. `--no-resolve` turns the second pass off; when even that is undecided, the re-run command is still printed.
-- **`failed`** — the route errored under load (auth redirects, POST-only endpoints). >1% non-2xx aborts measurement instead of measuring garbage. That's by design.
+- **`failed`** — the route errored under load (auth redirects, POST-only endpoints). >1% non-2xx aborts measurement instead of measuring garbage. That's by design. A process that died of **heap exhaustion** is not one of these: it reports `leak`, because a route that could not survive its own load did not fail to be measured — it was measured right up to the point where it stopped fitting. The verdict comes from that outcome, not from the shape of the truncated curve, which is the same rule `next-leak build` applies to a static-generation worker that dies. The run prints the cycles it survived and the growth up to the death, and exits 0 with a finding rather than 1 with an error.
 
 ## Peak pressure: `stable` is not the same as safe
 
@@ -368,6 +374,17 @@ through the build's source maps.
   to projects using `experimental.workerThreads: true`: a worker thread has no
   resident memory of its own to sample, and the run says so instead of
   reporting a number that would be measuring the parent.
+- **`next-leak build <dir> --attribute`** additionally names *what* the worker
+  retained, by signalling it for a pair of heap snapshots. **Opt-in, and slow
+  by nature:** the signal makes the worker write its whole heap to disk, which
+  on the #97464 reproduction has stalled a build for minutes at a time and
+  once for an hour and a half. Use it on a reproduction you are investigating,
+  not on a build you need to finish. It also covers only a low slice of the
+  curve, and says which: a snapshot weighs roughly 0.4x to 0.8x the worker's
+  resident size, so past about a gigabyte it exceeds the 512 MB a V8 string can
+  hold and cannot be read back — both captures happen below that, and the
+  report states what share of the observed growth they span (19% on that
+  reproduction, whose worker peaks near 4 GB).
 - **Architectures:** verified on **arm64 and x64** (linux/amd64 in Docker) — same app, same parameters, same verdicts.
 - **Attribution** (naming the file) needs a Turbopack build with server sourcemaps — the Next 15+ default. On webpack builds the registry is empty by design and findings degrade to `unattributed` with raw retainer chains; measurement itself does not depend on it. Note that `output: "standalone"` + `--webpack` produced a bundle that could not start at all on `16.3.0-canary.90` (missing `@swc/helpers`), independently of this tool.
 - Empirically validated on Next **15.5.4, 16.0.x, 16.1.5, 16.2.x, 16.3.0/16.3.1 and 16.3-canary** (incl. Sentry, OpenTelemetry, PPR and i18n apps), against the public reproductions attached to real issues (open and since-fixed). Most recent measurements, 2026-08-17/18: the runtime path on 16.2.12 and 16.3.1-canary.18, the build path on 16.2.12 and 16.3.1. The contracts it relies on are stable since Next 13–14, but older versions are untested.

package/dist/build-attribution.d.ts

@@ -0,0 +1,33 @@
+import { type AttributedDiff } from "./attribution.js";
+import type { BuildRunResult } from "./build-run.js";
+import { diffSnapshotFiles, type HeapDiff } from "./heap-diff.js";
+import { extractModuleRegistry } from "./module-registry.js";
+export type BuildAttribution = {
+    diff: HeapDiff;
+    attributed: AttributedDiff;
+    /** Modules the registry resolved. Zero means every finding stays unattributed. */
+    registrySize: number;
+    /** Share of the worker's observed growth the snapshot pair spans, 0 to 1. */
+    bracketed: number;
+    baselineRssBytes: number;
+    afterRssBytes: number;
+    /** Where the pair was stored, so the finding can be checked by hand. */
+    baselineFile: string;
+    afterFile: string;
+};
+export type BuildAttributionDeps = {
+    diff: typeof diffSnapshotFiles;
+    registry: typeof extractModuleRegistry;
+};
+/**
+ * Names what a build's worker retained, from the pair the run captured.
+ *
+ * Returns null rather than throwing on every failure path. A build measurement
+ * stands on its curve and its verdict; this is an addition to the report, and
+ * an addition that can fail must not be able to take the report with it.
+ *
+ * The registry is read from `.next/server` *after* the build, never during it:
+ * a half-written chunk can resolve a module id to the wrong source, and naming
+ * the wrong owner confidently is worse than naming none.
+ */
+export declare function attributeBuildCapture(result: BuildRunResult, appDir: string, onProgress?: (message: string) => void, deps?: BuildAttributionDeps): Promise<BuildAttribution | null>;

package/dist/build-report.d.ts

@@ -1,3 +1,4 @@
+import type { BuildAttribution } from "./build-attribution.js";
 import type { BuildRunResult } from "./build-run.js";
 /**
  * Renders the build report.
@@ -8,4 +9,4 @@ import type { BuildRunResult } from "./build-run.js";
  * still the honest axis here — it is what a CI runner's limit is enforced
  * against and what the OOM killer reads.
  */
-export declare function formatBuildReport(result: BuildRunResult): string;
+export declare function formatBuildReport(result: BuildRunResult, attribution?: BuildAttribution | null): string;

package/dist/build-run.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from "node:child_process";
+import { type CollectedPair } from "./build-snapshot.js";
 import { type BuildSample } from "./build-verdict.js";
 import { type ProcessTableSample } from "./process-tree.js";
 import type { TrendResult } from "./trend.js";
@@ -6,6 +7,19 @@ export type WorkerSeries = {
     pid: number;
     samples: BuildSample[];
 };
+export type BuildCapture = {
+    pid: number;
+    files: CollectedPair;
+    baselineRssBytes: number;
+    afterRssBytes: number;
+    /**
+     * Peak resident memory of *this* worker, not of the build. The share of
+     * growth the pair covers is quoted against the curve the findings came
+     * from, and on a multi-worker build the highest peak can belong to a worker
+     * nothing was captured from.
+     */
+    peakRssBytes: number;
+};
 export type BuildRunResult = {
     appDir: string;
     /**
@@ -31,12 +45,20 @@ export type BuildRunResult = {
     retentionPerPageBytes: number | null;
     /** True when a worker hit the V8 heap limit — the finding, not a failure. */
     heapExhausted: boolean;
+    /**
+     * The snapshot pair captured from a worker, when one was. Attribution is an
+     * addition to this report, never a precondition for it: every field above is
+     * produced whether or not capture worked.
+     */
+    capture: BuildCapture | null;
     strippedCapWarning: string | null;
     exitCode: number | null;
     output: string;
 };
 export type BuildRunOptions = {
     appDir: string;
+    /** Where a captured snapshot pair is moved to. Capture is skipped without it. */
+    workDir?: string;
     signal?: AbortSignal;
     onProgress?: (message: string) => void;
     /** Overrides `process.env` for the build. */
@@ -44,6 +66,7 @@ export type BuildRunOptions = {
 };
 export type BuildRunDeps = {
     spawnBuild: (appDir: string, env: NodeJS.ProcessEnv) => ChildProcess;
+    signalWorker: (pid: number) => void;
     sampleTable: () => Promise<ProcessTableSample>;
     now: () => number;
     sleep: (ms: number) => Promise<void>;

package/dist/build-snapshot.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Worker resident memory above which its heap snapshot stops being parseable.
+ *
+ * Measured on 2026-08-19 against the vercel/next.js#97464 reproduction, three
+ * points: a worker at 802 MB wrote 310 MB, at 1201 MB wrote 563 MB, and at
+ * 3010 MB wrote 2388 MB. The ratio is not flat — 0.39x, 0.47x, 0.79x — so the
+ * 512 MB a V8 string can hold is crossed somewhere just past 1 GB of RSS.
+ * A snapshot taken above this is written, costs the disk, and then cannot be
+ * read (see `assertReadableSnapshot`), which is the worst of both.
+ */
+export declare const PARSEABLE_WORKER_RSS_BYTES: number;
+export type CaptureStage = "waiting" | "baseline-taken" | "pair-taken" | "missed";
+export type CaptureDecision = "wait" | "take-baseline" | "take-after" | "give-up";
+/**
+ * Decides what to do with a worker at this resident size.
+ *
+ * Both snapshots have to happen low on the curve, which is not where the
+ * interesting memory is. That is forced by the parse limit above and is the
+ * central compromise of build-time attribution: the pair samples the start of
+ * the growth rather than bracketing it, so the report has to say how much of
+ * the curve it actually covers.
+ */
+export declare function decideCapture(rssBytes: number, stage: CaptureStage, baselineRssBytes?: number | null): CaptureDecision;
+export declare function snapshotsWrittenBy(pid: number, filenames: readonly string[]): string[];
+export type CollectedPair = {
+    baselineFile: string;
+    afterFile: string;
+};
+/**
+ * Moves a worker's two snapshots out of the project and into the run's own
+ * directory. They are the user's source tree's problem otherwise: V8 chose
+ * where to put them, and leaving half a gigabyte of them behind in a repo
+ * would be a poor trade for a measurement.
+ */
+export declare function collectSnapshotPair(appDir: string, outDir: string, pid: number): Promise<CollectedPair | null>;
+/**
+ * Deletes snapshots a run wrote and cannot use — a give-up after the baseline,
+ * or a worker whose pair never completed. Without this a failed capture leaves
+ * hundreds of megabytes in the user's project with no report referring to them.
+ */
+export declare function discardSnapshots(appDir: string, pid: number): Promise<void>;
+/**
+ * What share of the worker's observed growth the pair actually spans.
+ *
+ * Reported rather than hidden because the parse limit forces the pair low: on
+ * the #97464 reproduction the worker peaks near 3.3 GB and the pair cannot
+ * reach past 1 GB, so the attributed bytes explain a minority of the curve. A
+ * reader comparing the two numbers without this would conclude the rest went
+ * unexplained.
+ */
+export declare function bracketedShare(baselineRssBytes: number, afterRssBytes: number, peakRssBytes: number): number;
+export declare function registerPendingCapture(appDir: string, pid: number): void;
+export declare function clearPendingCapture(): void;
+/** Best effort, synchronous, and never throws: it runs on the way out. */
+export declare function discardPendingSnapshotsSync(): void;

package/dist/{chunk-RS3AO7HB.js → chunk-T7LM4Z33.js}

@@ -80,6 +80,7 @@ function renderHtmlReport(run) {
   const measured = run.routes.filter((route) => route.status === "measured");
   const skipped = run.routes.filter((route) => route.status === "skipped");
   const failed = run.routes.filter((route) => route.status === "failed");
+  const exhausted = run.routes.filter((route) => route.status === "died-of-heap");
   const environment = run.environment;
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8">
@@ -102,6 +103,13 @@ code{background:#f4f4f4;padding:0 4px;border-radius:3px}
   )} \xB7 next-leak ${escapeHtml(environment.nextLeakVersion)}</p>
 <p class="meta">${run.parameters.cycles} cycles \xD7 ${run.parameters.loadRequests} requests \xB7 heap cap ${run.parameters.maxOldSpaceMb} MB \xB7 growth gate ${(run.parameters.minGrowthPerCycle / 1024).toFixed(0)} KiB/cycle</p>
 ${measured.map((route) => measuredSection(route, run.parameters)).join("\n")}
+${exhausted.map(
+    (route) => route.status !== "died-of-heap" ? "" : `<h2><span class="badge" style="background:#c0392b">leak</span> <code>${escapeHtml(
+      route.route
+    )}</code></h2>
+<p class="curve">Ran out of heap after ${route.cyclesCompleted} of ${route.cyclesRequested} cycles \xD7 ${route.requestsPerCycle} requests. Post-GC heap up to the death: ${route.memorySamples.map((sample) => `${(sample.heapUsed / MB).toFixed(1)} MB`).join(" \u2192 ")}</p>
+<p class="warn">${escapeHtml(route.reason)}</p>`
+  ).join("\n")}
 ${skipped.length === 0 ? "" : `<h2>Skipped</h2><ul>${skipped.map((route) => `<li><code>${escapeHtml(route.route)}</code> \u2014 ${escapeHtml(route.status === "skipped" ? route.reason : "")}</li>`).join("")}</ul>`}
 ${failed.length === 0 ? "" : `<h2>Failed</h2><ul>${failed.map((route) => `<li><code>${escapeHtml(route.route)}</code> \u2014 ${escapeHtml(route.status === "failed" ? route.reason : "")}</li>`).join("")}</ul>`}
 <p class="meta">Raw snapshots and run.json live next to this file \u2014 verify in Chrome DevTools \u2192 Memory \u2192 Load.</p>