next-leak 0.5.1 → 0.7.0

package/README.md

@@ -23,19 +23,33 @@ $ npx next-leak . --quick
 ```
 
 That first line is a real run against the reproduction for
-[vercel/next.js#95094](https://github.com/vercel/next.js/issues/95094), an open
-Next.js issue: the sandbox's `TimeoutsManager` never releases timeout ids from
-middleware. next-leak found the growth, the retaining object and the chain that
-holds it — without being told what to look for.
-
-**Verified against real, open Next.js issues**, not synthetic fixtures:
-
-| Issue | What it is | Result |
-|---|---|---|
-| [#95094](https://github.com/vercel/next.js/issues/95094) | Middleware `setTimeout` ids retained by the sandbox | **Reproduced** · mechanism named · 112 MB retained |
-| [#94890](https://github.com/vercel/next.js/issues/94890) | Router LRU cache doesn't count its keys | **Reproduced** · 26.7 → 71.9 MB |
-| [#84884](https://github.com/vercel/next.js/issues/84884) | axios + `AbortSignal` in middleware | **Reproduced** · 32.8 → 369.9 MB |
-| [#94919](https://github.com/vercel/next.js/issues/94919) | RSC tree retained on client aborts | **Reproduced** · 39 → 139 MB · [with a caveat](#scope-and-limits-read-before-filing-issues) |
+[vercel/next.js#95094](https://github.com/vercel/next.js/issues/95094): the
+sandbox's `TimeoutsManager` never released timeout ids from middleware.
+next-leak found the growth, the retaining object and the chain that holds it —
+without being told what to look for. Next.js 16.3.0 has since fixed it.
+
+**Verified against real Next.js issues**, not synthetic fixtures. Issue states
+checked 2026-08-18:
+
+| Issue | What it is | Measured | State today |
+|---|---|---|---|
+| [#96533](https://github.com/vercel/next.js/issues/96533) | ISR revalidation holds RSC buffers between collections | 4–5 MB of `arrayBuffers` held vs 0.32 MB retained | **open** |
+| [#97464](https://github.com/vercel/next.js/issues/97464) | Static-gen worker retains per prerendered page | worker rss 1.07 → 2.96 GB, then OOM | **open** |
+| [#92287](https://github.com/vercel/next.js/issues/92287) | Cache Components: unbounded `arrayBuffers` under load | 37.5 MB of arrayBuffers held between collections, 37x what it retains (16.3.1) | **open** |
+| [#84884](https://github.com/vercel/next.js/issues/84884) | axios + `AbortSignal` in middleware | 32.8 → 369.9 MB | **open** |
+| [#89091](https://github.com/vercel/next.js/issues/89091) | zlib retention on mid-stream aborts | +42.5 MB/1000 aborted req on 16.1.5; **+0.03 on 16.3.1** | open, no longer reproduces |
+| [#95094](https://github.com/vercel/next.js/issues/95094) | Middleware `setTimeout` ids retained by the sandbox | 112 MB retained; flat after the fix | fixed in 16.3.0 |
+| [#94890](https://github.com/vercel/next.js/issues/94890) | Router LRU cache doesn't count its keys | 26.7 → 71.9 MB | fixed in 16.3.0 |
+| [#94919](https://github.com/vercel/next.js/issues/94919) | Retention on client aborts | 39 → 139 MB · [with a caveat](#scope-and-limits-read-before-filing-issues) | fixed in 16.3.0 |
+
+The three fixed ones are kept deliberately: a tool that only lists open bugs
+looks impressive until the bugs close, and what those rows show is that the
+measurements matched what the fixes turned out to be. #94919 is the sharpest —
+the PR that closed it discarded the RSC-WeakMap hypothesis in the title and
+attributed the leak to native zlib retention instead, which is the same
+mechanism the #89091 measurement had already isolated — and re-measuring #89091
+on 16.3.1 (2026-08-18) shows it gone, from +42.5 MB per 1000 aborted requests
+down to +0.03, which is the same fix arriving from the other direction.
 
 The full causal chain, measured on that same issue: leak found (28.7 -> 138.9 MB
 across 8 cycles), the workaround from the thread applied (`clearTimeout(id)`
@@ -102,11 +116,26 @@ Every report prints the gate it used.
 | `--requests <n>` | 5000 | Requests per cycle. Raises sensitivity as well as duration: the growth gate scales with it, down to a noise floor around 5000 |
 | `--connections <n>` | 100 | Concurrent connections |
 | `--idle <seconds>` | 30 | **Maximum** wait before each sample; the run continues as soon as the heap settles |
+| `--warmup <n>` | 200 | Requests before the baseline snapshot. Lower it on apps that cache per request: warm-up fills those caches and the baseline then measures the warm-up, not the app. The run says so when it happens |
 | `--max-old-space <mb>` | 512 | Heap cap of each measured process. Raise it for apps whose legitimate working set is larger, or they die under measurement |
 | `--quick` | off | Fast preset (2000 requests × 4 cycles, 8s idle) — the exact profile the real-app validation ran with. Same cycle count as the default; what it trades away is traffic per cycle, so it sits on the noise floor and is less sensitive to slow leaks. Explicit flags override it |
 | `--no-resolve` | off | Skip the second pass on inconclusive routes |
 | `--diff-all` | off | Diff snapshots for stable routes too |
 | `--output <dir>` | `<app>/.next-leak` | Where runs are written |
+| `--write-config` | off | Write `next-leak.config.json` for the routes that need sample params, then exit. Never overwrites an existing file |
+
+There is a second command for the other half of the problem:
+
+```bash
+# Measure the build itself, not a built server
+npx next-leak build .
+```
+
+A large site can run out of heap while prerendering, before any server exists to
+measure ([#97464](https://github.com/vercel/next.js/issues/97464)). That command
+runs your build unmodified and samples the resident memory of each
+static-generation worker. It needs neither a previous build nor standalone
+output, and takes `--output` only.
 
 Dynamic routes need sample params in `next-leak.config.json` in your app dir:
 
@@ -118,6 +147,13 @@ Dynamic routes need sample params in `next-leak.config.json` in your app dir:
 }
 ```
 
+`--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.
+
+```json
+```
+
 - **`headers`** are sent with every request. Real traffic is not header-less:
   compression, sessions and auth change which code paths run, and some leaks
   only live on those paths.
@@ -131,10 +167,19 @@ Dynamic routes need sample params in `next-leak.config.json` in your app dir:
   load-balancer timeouts and bots do. Some leaks only exist on that path
   (`ServerResponse` retained after an early disconnect; the RSC tee branch in
   [#94919](https://github.com/vercel/next.js/issues/94919)). The clock starts
-  at the **first byte of the response**, not at the request — under load a
-  request-relative window cuts before the stream begins and tests a different
-  path. Small values are the point: `4` means "read the first chunk, then
-  vanish". Requests abandoned on purpose are not counted as failures.
+  at the **first byte of the response**, so the cut lands mid-stream however
+  long the route takes to answer. Small values are the point: `4` means "read
+  the first chunk, then vanish". Requests abandoned on purpose are not counted
+  as failures.
+- **`abandonFrom`** moves that clock to the request itself
+  (`"abandonFrom": "request"`). Use it for the opposite experiment: a client
+  that is already gone before the server produces anything. On a route slower
+  than the deadline the default never cuts early — against the reproduction
+  for [#84648](https://github.com/vercel/next.js/issues/84648), whose upstream
+  answers in 400 ms while its load generator cuts at 60 ms, first-byte reached
+  7% of requests and `request` reached all of them. It stays opt-in because a
+  deadline armed on connect loses the race to the first byte on fast routes,
+  which measures the wrong path silently.
 
 `run.json` records what every load phase actually did — requests sent,
 2xx, abandoned — so a run can be audited instead of trusted.
@@ -168,7 +213,7 @@ separates them, because each one has a different fix:
   with the traffic, so the longer run decides the same thing. If the heap is
   flat but RSS keeps climbing, the report says so explicitly: that is an
   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; if the leak is app-owned, the draft tells you **not** to file it upstream.
+- **`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.
 
@@ -188,8 +233,10 @@ the verdict:
 ```
 
 That is a real measurement of the reproduction in
-[vercel/next.js#92287](https://github.com/vercel/next.js/issues/92287): no
-retention, and 3 GB reached. The note fires when the peak heap comes within
+[vercel/next.js#92287](https://github.com/vercel/next.js/issues/92287) on
+16.2.2: no retention, and 3 GB reached under its own sustained load. The same
+app on 16.3.1 under a shorter profile still reaches 544 MB against 33.8 MB
+retained, so the shape has not gone anywhere. The note fires when the peak heap comes within
 75% of `--max-old-space`, or when peak RSS is at least 8× the retained heap
 and above 512 MB. It never changes the verdict — retention and peak are
 different questions, and only one of them is a leak. A peak is the highest
@@ -199,6 +246,49 @@ If the measured process dies at the limit instead of merely approaching it,
 the route fails saying exactly that, with the limit in force and how to raise
 it.
 
+### Memory a GC reclaims that production never reclaims
+
+There is a third question again, and it is the shape of most of the leaks
+reported in August: memory the process *holds between collections*, which a
+forced GC takes back and a long-running server may never run one to take back.
+Every verdict above is post-GC, so that class is invisible to it by
+construction.
+
+Each cycle is therefore read twice — once before any forced collection, once
+after — and the gap between them is reported when it is large:
+
+```
+✖ /posts/[slug]  leak  (+0.16 MB/1000 req)  heap 27.1 → 26.3 → … → 27.9 MB
+    driven through ISR revalidation (revalidates every 3600s; without it the load
+    would serve the cache)
+    ▲ unreclaimed: held 4.72 MB of arrayBuffers between collections that a GC took
+      back (4.7x what it retains) — a forced GC reclaims this, a long-running
+      process may not run one often enough to
+```
+
+A real measurement of the reproduction in
+[#96533](https://github.com/vercel/next.js/issues/96533), whose reporter
+accumulated 1.16 GB of `arrayBuffers` over four days against a flat JS heap.
+The note fires on the **gap**, not on a trend: that pre-collection series
+oscillates rather than climbs, and a rule keyed on it climbing reported nothing
+at all. It needs both a floor (2 MB) and a ratio (0.35× what the route retains),
+because the absolute size alone does not separate this from an ordinary leak.
+
+Its limit, stated on the line itself: the reading is taken seconds after load,
+not the hours a production process runs between full collections, so it
+includes memory that had not been collected yet. It never changes the verdict.
+
+### ISR routes are driven, not served from cache
+
+A route with a revalidation period serves its cache unless the request carries
+the build's own `x-prerender-revalidate` header. Measured on that same app: the
+identical run reports `leak` with the header and `stable` without it. next-leak
+reads `previewModeId` from `.next/prerender-manifest.json` and drives those
+routes itself; a header you set in `next-leak.config.json` wins untouched. When
+the manifest cannot supply one, the route is reported `not exercised` with no
+verdict, because a flat curve measured against a static cache says nothing about
+the app.
+
 ## The tool grades its own measurement
 
 A leak detector is an instrument, and a miscalibrated instrument doesn't fail
@@ -260,10 +350,27 @@ through the build's source maps.
 
 ## Scope and limits (read before filing issues)
 
-- **Supported:** App Router · `output: "standalone"` · Node ≥ 22 · Linux/macOS. Pages Router, non-standalone, and Windows are rejected with a clear message.
+- **Supported (default command):** App Router · `output: "standalone"` · Node ≥ 22 · Linux/macOS. Pages Router, non-standalone, and Windows are rejected with a clear message.
+- **Sample values can vary per request.** `"slug": "post-{n}"` gives every
+  request its own URL — the shape of bot traffic and of a cache that never
+  repeats a key. `"slug": "post-{n%200}"` cycles through exactly 200 distinct
+  values, revisiting them across cycles, which is the shape the reported leaks
+  actually have ([#96533](https://github.com/vercel/next.js/issues/96533)
+  revalidates a fixed set of posts;
+  [#92287](https://github.com/vercel/next.js/issues/92287) turns on how many
+  keys a cache holds at once). A value carrying both markers is rejected before
+  the run starts.
+- **`next-leak build <dir>`** measures the build instead of the server, and needs
+  neither a previous build nor standalone output — it runs `next build` and
+  samples the resident memory of each static-generation worker, which is where
+  large sites run out of heap while prerendering
+  ([#97464](https://github.com/vercel/next.js/issues/97464)). It does not apply
+  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.
 - **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 and 16.3-canary** (incl. Sentry, OpenTelemetry, PPR and i18n apps), against real reproductions from open issues. The contracts it relies on are stable since Next 13–14, but older versions are untested.
+- 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.
 - **Each measured process runs under a 512 MB heap cap** by default, so a leak
   reaches a ceiling in minutes instead of the hours a production container
   takes. An app whose legitimate working set is larger needs

package/dist/abandon-load.d.ts

@@ -1,9 +1,17 @@
+/**
+ * Where the abandon deadline starts. `first-byte` puts the cut mid-stream
+ * whatever the route's latency; `request` puts it before the response exists,
+ * which is a different leak path and not reachable from the other origin.
+ */
+export type AbandonOrigin = "first-byte" | "request";
 export type AbandonPhaseOptions = {
     url: string;
     amount: number;
     connections: number;
-    /** Destroy the socket this many ms after the first byte of the response. */
+    /** Destroy the socket this many ms after the origin below. */
     abandonAfterMs: number;
+    /** Defaults to `first-byte`. */
+    abandonFrom?: AbandonOrigin;
     headers?: Record<string, string>;
 };
 export type AbandonPhaseResult = {
@@ -30,6 +38,8 @@ export type AbandonPhaseResult = {
  * a client goes away mid-flight (closed tabs, load-balancer timeouts, bots).
  *
  * Raw sockets keep this honest: write the request, wait for the response to
- * start, then wait `abandonAfterMs` and destroy the socket mid-stream.
+ * start, then wait `abandonAfterMs` and destroy the socket mid-stream. With
+ * `abandonFrom: "request"` the wait starts at the write instead, which is the
+ * only way to cut a route that has not begun answering yet.
  */
 export declare function runAbandonPhase(options: AbandonPhaseOptions): Promise<AbandonPhaseResult>;

package/dist/build-report.d.ts

@@ -0,0 +1,11 @@
+import type { BuildRunResult } from "./build-run.js";
+/**
+ * Renders the build report.
+ *
+ * Says "worker rss" everywhere rather than "heap" or "retained": these samples
+ * are resident memory with no forced collection behind them, and calling them
+ * retention would borrow a precision the measurement does not have. RSS is
+ * 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;

package/dist/build-run.d.ts

@@ -0,0 +1,58 @@
+import { type ChildProcess } from "node:child_process";
+import { type BuildSample } from "./build-verdict.js";
+import { type ProcessTableSample } from "./process-tree.js";
+import type { TrendResult } from "./trend.js";
+export type WorkerSeries = {
+    pid: number;
+    samples: BuildSample[];
+};
+export type BuildRunResult = {
+    appDir: string;
+    /**
+     * `measured` carries a verdict. `build-failed` means the build broke for a
+     * reason that is not memory, and makes no memory claim. `nothing-to-measure`
+     * means no static-generation worker ever ran. `cannot-sample` means the
+     * process table could not be read, which is not the same as finding nothing
+     * in it.
+     */
+    status: "measured" | "build-failed" | "nothing-to-measure" | "cannot-sample";
+    /** Why sampling stopped, when it did. */
+    samplingFailure: string | null;
+    verdict: TrendResult["verdict"] | null;
+    trend: TrendResult | null;
+    /** Segmented levels the verdict was read from, in bytes. */
+    levels: number[];
+    workers: WorkerSeries[];
+    /** The build's own process, reported but never judged: it sheds while workers climb. */
+    parentSamples: BuildSample[];
+    peakWorkerRssBytes: number;
+    netGrowthBytes: number;
+    pagesGenerated: number | null;
+    retentionPerPageBytes: number | null;
+    /** True when a worker hit the V8 heap limit — the finding, not a failure. */
+    heapExhausted: boolean;
+    strippedCapWarning: string | null;
+    exitCode: number | null;
+    output: string;
+};
+export type BuildRunOptions = {
+    appDir: string;
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+    /** Overrides `process.env` for the build. */
+    env?: NodeJS.ProcessEnv;
+};
+export type BuildRunDeps = {
+    spawnBuild: (appDir: string, env: NodeJS.ProcessEnv) => ChildProcess;
+    sampleTable: () => Promise<ProcessTableSample>;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+};
+/**
+ * Measures the memory of a `next build`'s static-generation workers.
+ *
+ * The build runs unmodified — nothing is injected into it. Workers are child
+ * processes with their own resident memory, so the whole measurement is made
+ * from outside by watching the process tree.
+ */
+export declare function runBuildMeasurement(options: BuildRunOptions, deps?: BuildRunDeps): Promise<BuildRunResult>;

package/dist/build-target.d.ts

@@ -0,0 +1,13 @@
+export type ValidatedBuildTarget = {
+    appDir: string;
+    /** The package script to run, when one of the usual names exists. */
+    buildScript: string | null;
+};
+/**
+ * Validates a target for a *build* measurement.
+ *
+ * Deliberately weaker than `validateTarget`: this command measures the build
+ * itself, so demanding `.next` or a standalone bundle would reject exactly the
+ * projects it exists to help — a build that OOMs never produces either.
+ */
+export declare function validateBuildTarget(appDir: string): Promise<ValidatedBuildTarget>;

package/dist/build-verdict.d.ts

@@ -0,0 +1,80 @@
+import { type TrendResult } from "./trend.js";
+export type BuildSample = {
+    /** Milliseconds since the build started. */
+    atMs: number;
+    rssBytes: number;
+};
+/**
+ * Segments the sampling window into equal slices and takes each slice's last
+ * reading.
+ *
+ * A build has no cycles. Its only natural unit of work is a page, and pages are
+ * not observable from outside the worker — so the window is divided by time
+ * instead, which yields a series with the shape semantics the trend classifier
+ * already reads: one level per unit of work. Taking the last sample of each
+ * slice rather than the mean keeps a climb a climb; averaging would flatten the
+ * end of every segment into its start.
+ */
+export declare function segmentSamples(samples: readonly BuildSample[], segments: number): number[];
+/**
+ * Segments a build needs before its curve can be judged.
+ *
+ * The classifier drops the first delta as warm-up and wants at least three
+ * more, and a worker's first segment is genuinely warm-up: module loading and
+ * JIT, the same reason the runtime ritual discards its baseline delta.
+ */
+export declare const BUILD_SEGMENTS = 6;
+export type BuildTrend = {
+    trend: TrendResult;
+    /** The segmented levels the verdict was read from. */
+    levels: number[];
+};
+/**
+ * Per-segment growth a build worker must clear to count as retaining.
+ *
+ * Not the runtime gate. That one is the noise floor of a *post-GC heap* sample,
+ * 256 KiB, and it does not describe RSS: a build worker doing legitimate work
+ * moves tens of megabytes between readings through allocator behaviour alone,
+ * with nothing retained.
+ *
+ * Anchored on two builds of the same project, same heap cap, 2026-08-17:
+ * 16.2.12 stayed flat (428 → 530 MB, largest segment delta 17 MB) while 16.3.1
+ * climbed 1070 → 2960 MB and then OOMed, ~315 MB per segment. 32 MB is roughly
+ * twice the largest healthy delta and an order of magnitude below the leaking
+ * one. The consequence to be honest about: a build retaining less than this per
+ * segment reads as stable — and one retaining less than this does not OOM.
+ */
+export declare const BUILD_GROWTH_GATE_BYTES: number;
+/** Classifies a worker's resident-memory curve. */
+export declare function classifyBuildSamples(samples: readonly BuildSample[]): BuildTrend;
+/** Growth across the analyzed window, in bytes. */
+export declare function netGrowthOf(levels: readonly number[]): number;
+/**
+ * Retention per page generated.
+ *
+ * Null when the page count is unknown: a growth figure with an invented
+ * denominator is worse than no figure, and this is the number people quote.
+ */
+export declare function retentionPerPage(levels: readonly number[], pagesGenerated: number | null): number | null;
+/**
+ * The heap cap Next removes from the worker's environment.
+ *
+ * `lib/worker.js` deletes `max-old-space-size` and `max_old_space_size` from
+ * `NODE_OPTIONS` when it spawns an isolated-memory worker, so the flag every
+ * OOM guide recommends never reaches the process that runs out of memory.
+ * Verified by measurement on the #97464 reproduction: a build capped at 50 MB
+ * with `--max-old-space-size` completes, while `--max-heap-size=50` kills it in
+ * 374 ms.
+ */
+export declare function strippedHeapCap(nodeOptions: string | undefined): string | null;
+/** Whether build output carries a V8 heap-limit fatal error. */
+export declare function diedOfHeapExhaustion(output: string): boolean;
+/**
+ * How many pages the build generated, read from its own progress line.
+ *
+ * Next prints `Generating static pages (1234/2504)`; the largest first number
+ * seen is how far it got, which is the useful figure whether it finished or
+ * died. Null when the build never printed one — an invented denominator would
+ * turn an unknown into a wrong number.
+ */
+export declare function pagesGeneratedFrom(output: string): number | null;