next-leak 0.7.0 → 0.8.0

package/README.md

@@ -368,6 +368,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;