next-leak 0.5.1 → 0.7.0

package/dist/confidence.d.ts

@@ -1,3 +1,4 @@
+import type { AbandonOrigin } from "./abandon-load.js";
 import type { HeapSample } from "./control-server.js";
 import type { LoadOutcome, SettleOutcome } from "./ritual.js";
 import { type TrendResult, type TrendVerdict } from "./trend.js";
@@ -15,8 +16,11 @@ import { type TrendResult, type TrendVerdict } from "./trend.js";
  * `thin-evidence`       — a leak called on too few cycles for its size
  * `near-heap-ceiling`   — the heap approached the cap the process ran under,
  *   so the curve was measured against a ceiling instead of running free
+ * `warm-up-baseline`    — the baseline sat far above the level the cycles
+ *   settled at, so it carries warm-up's own retention rather than the app's
+ *   resting size
  */
-export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "thin-evidence" | "near-heap-ceiling";
+export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "thin-evidence" | "near-heap-ceiling" | "warm-up-baseline";
 export type MeasurementWarning = {
     code: WarningCode;
     detail: string;
@@ -38,12 +42,16 @@ export type ConfidenceInput = {
     settleOutcomes: readonly SettleOutcome[];
     /** Set when the run asked for early disconnects. */
     abandonAfterMs?: number;
+    /** Which deadline origin those disconnects used. Defaults to `first-byte`. */
+    abandonFrom?: AbandonOrigin;
     /** Threshold the verdict used, for the noise-floor check. */
     minGrowthPerCycle?: number;
     /** Post-GC samples, for the heap-ceiling check. */
     memorySamples?: readonly HeapSample[];
     /** Old-space cap the measured process ran under (MB). */
     maxOldSpaceMb?: number;
+    /** Warm-up requests the run sent before the baseline, for the warm-up check. */
+    warmupRequests?: number;
 };
 /**
  * Cycles a re-measurement uses when a verdict came back `inconclusive` — the

package/dist/{html-report-X2LUOZRH.js → html-report-TN7PYVU4.js}

@@ -1,8 +1,8 @@
 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 {
   renderHtmlReport
-} from "./chunk-NNDGXIGQ.js";
-import "./chunk-2FZXZLZW.js";
+} from "./chunk-RS3AO7HB.js";
+import "./chunk-EJ26OBZI.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 export {

package/dist/index.js

@@ -39,13 +39,13 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-KJFYTJCF.js";
+} from "./chunk-BXDUPN6Z.js";
 import {
   renderHtmlReport
-} from "./chunk-NNDGXIGQ.js";
+} from "./chunk-RS3AO7HB.js";
 import {
   classifyTrend
-} from "./chunk-2FZXZLZW.js";
+} from "./chunk-EJ26OBZI.js";
 import {
   renderIssueMarkdown
 } from "./chunk-WXAFXVWS.js";

package/dist/isr.d.ts

@@ -0,0 +1,39 @@
+import type { PrerenderManifest } from "./manifests.js";
+/**
+ * The header Next accepts as an authentic revalidation request.
+ *
+ * Sent with the build's own `previewModeId`, it makes the server re-render the
+ * page instead of serving the cached one. Without it, load against an ISR route
+ * exercises the static cache and nothing else — measured on the
+ * vercel/next.js#96533 reproduction, the same app reports `leak` with this
+ * header and `stable` without it.
+ */
+export declare const REVALIDATE_HEADER = "x-prerender-revalidate";
+/**
+ * The revalidation period in force for a route, or null when it has none.
+ *
+ * Accepts either a concrete path (`/posts/post-1`) or a dynamic template
+ * (`/posts/[slug]`): the period lives on concrete entries, and a template
+ * inherits it from any entry whose `srcRoute` points back at it.
+ */
+export declare function revalidateSecondsFor(manifest: PrerenderManifest | undefined, route: string): number | null;
+/** Whether a route is served from the ISR cache and needs driving. */
+export declare function revalidates(manifest: PrerenderManifest | undefined, route: string): boolean;
+export type RevalidationPlan = {
+    kind: "not-isr";
+} | {
+    kind: "drive";
+    headers: Record<string, string>;
+}
+/** ISR, but the manifest cannot supply what an authentic request needs. */
+ | {
+    kind: "cannot-drive";
+    reason: string;
+};
+/**
+ * How to make a route re-render, given what the build tells us.
+ *
+ * A header the user set themselves wins untouched: someone driving a bespoke
+ * revalidation path knows more about it than the manifest does.
+ */
+export declare function planRevalidation(manifest: PrerenderManifest | undefined, route: string, userHeaders: Record<string, string> | undefined): RevalidationPlan;

package/dist/launcher.d.ts

@@ -1,3 +1,4 @@
+import { type ChildProcess } from "node:child_process";
 /**
  * Old-space cap for measured processes, when the caller does not pick one.
  *
@@ -40,6 +41,13 @@ export declare class LaunchError extends Error {
 }
 /** Interrupt safety: no measured-app process may outlive the CLI. */
 export declare function killActiveChildren(): void;
+/**
+ * Puts a process this tool spawned under the same interrupt safety as a
+ * measured app — a build launched by `next-leak build` must not outlive a
+ * Ctrl+C either.
+ */
+export declare function registerChild(child: ChildProcess): void;
+export declare function unregisterChild(child: ChildProcess): void;
 /**
  * Turns a stack dump into a sentence when the cause is recognisable. Seen in
  * the wild: a webpack `output: standalone` build that ships without

package/dist/manifests.d.ts

@@ -19,6 +19,26 @@ export declare const routesManifestSchema: z.ZodObject<{
     }, z.core.$loose>>;
 }, z.core.$loose>;
 export type RoutesManifest = z.infer<typeof routesManifestSchema>;
+/**
+ * `.next/prerender-manifest.json` — only the fields ISR handling relies on.
+ *
+ * `routes` holds concrete prerendered paths; a dynamic template's revalidation
+ * period lives on those entries, linked back by `srcRoute`, not on the
+ * `dynamicRoutes` entry for the template itself. On the vercel/next.js#96533
+ * reproduction, `/posts/[slug]` carries no period while its 200 concrete
+ * `/posts/post-N` entries each carry `initialRevalidateSeconds: 3600` with
+ * `srcRoute: "/posts/[slug]"`.
+ */
+export declare const prerenderManifestSchema: z.ZodObject<{
+    routes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        initialRevalidateSeconds: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<false>]>>;
+        srcRoute: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+    preview: z.ZodOptional<z.ZodObject<{
+        previewModeId: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type PrerenderManifest = z.infer<typeof prerenderManifestSchema>;
 export type RouteKind = "page" | "route-handler";
 export type DiscoveredRoute = {
     /** Request path, e.g. "/" or "/products/[id]". */

package/dist/process-tree.d.ts

@@ -0,0 +1,44 @@
+export type ProcessRow = {
+    pid: number;
+    ppid: number;
+    /** Resident set size in bytes. `ps` reports KB; converted once, here. */
+    rssBytes: number;
+    command: string;
+};
+/**
+ * Parses `ps -axo pid,ppid,rss,command` output.
+ *
+ * Columns are right-aligned to widths that vary with the values, and the
+ * command itself contains spaces — so the first three fields are split off and
+ * everything after them is the command. A line that does not start with three
+ * numbers is not a process row (the header, or a wrapped line) and is skipped
+ * rather than failing the sample.
+ */
+export declare function parseProcessTable(output: string): ProcessRow[];
+/**
+ * Every process below `rootPid`, at any depth, excluding the root itself.
+ *
+ * Walks generation by generation rather than recursing per row: a build tree is
+ * shallow but the machine's process table is not, and this visits each row once
+ * per generation instead of once per ancestor.
+ */
+export declare function descendantsOf(rows: readonly ProcessRow[], rootPid: number): ProcessRow[];
+/** Whether a row is one of the build's static-generation workers. */
+export declare function isStaticGenWorker(row: ProcessRow): boolean;
+export type ProcessTableSample = {
+    ok: true;
+    rows: ProcessRow[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * One sample of the whole process table.
+ *
+ * The failure is reported rather than swallowed. An empty table and an
+ * unreadable one look identical downstream — both yield no workers — and
+ * reporting "nothing to measure" when the truth is "could not look" is the
+ * silent false negative this tool exists to avoid. Seen for real: a sandbox
+ * that denies `ps` turned a leaking build into a clean run.
+ */
+export declare function sampleProcessTable(): Promise<ProcessTableSample>;

package/dist/report.d.ts

@@ -1,3 +1,2 @@
 import type { RunReport } from "./runner.js";
-/** Renders the terminal report. Pure: no I/O, no colors, stable output. */
 export declare function formatReport(report: RunReport): string;

package/dist/ritual.d.ts

@@ -1,6 +1,6 @@
 import type { HeapSample } from "./control-server.js";
 import { launchInstrumented } from "./launcher.js";
-import { runAbandonPhase } from "./abandon-load.js";
+import { runAbandonPhase, type AbandonOrigin } from "./abandon-load.js";
 import { runLoadPhase } from "./load.js";
 import { type TrendResult } from "./trend.js";
 export type RitualOptions = {
@@ -24,6 +24,8 @@ export type RitualOptions = {
     headers?: Record<string, string>;
     /** Emulate clients that disconnect before the response arrives. */
     abandonAfterMs?: number;
+    /** Where that deadline starts. Defaults to `first-byte`. */
+    abandonFrom?: AbandonOrigin;
 };
 export type PhaseTiming = {
     phase: string;
@@ -89,6 +91,21 @@ export type RitualResult = {
     memorySamples: HeapSample[];
     /** Highest memory seen during each load cycle, sampled without collecting. */
     peaks: PeakSample[];
+    /**
+     * One reading per cycle taken before any collection is forced — what the
+     * process is holding on its own.
+     *
+     * Every other number here is post-GC, which is what makes a verdict mean
+     * something and is also blind to a whole class of leak: memory a full GC
+     * would reclaim that a production process never runs one often enough to
+     * (vercel/next.js#96533). Absolute values overstate retention — this is
+     * taken seconds after load, not hours, so it includes garbage not yet
+     * collected — but a roughly constant offset across identical cycles cancels
+     * out of the deltas the trend is read from.
+     */
+    unreclaimedSamples: HeapSample[];
+    /** Trend over `unreclaimedSamples`. Reported, never the verdict. */
+    unreclaimedTrend: TrendResult;
     baselineSnapshot: string;
     afterSnapshot: string;
     trend: TrendResult;
@@ -110,6 +127,13 @@ export type RitualDeps = {
     /** GC-free read, polled while the app is under load. */
     readMemory: (port: number) => Promise<HeapSample>;
 };
+/**
+ * The pre-collection wait, taken *out of* the idle rather than added to it.
+ *
+ * Capped at a quarter of the idle so short profiles keep their settle budget:
+ * `--quick` idles for 8 s, and a flat 3 s would be nearly half of it.
+ */
+export declare function unreclaimedSettleFor(idleMs: number): number;
 /**
  * Single source of truth for ritual defaults — reports must echo them.
  *

package/dist/route-config.d.ts

@@ -1,15 +1,14 @@
 import { z } from "zod";
-/**
- * `next-leak.config.json` in the target app dir: sample values for dynamic
- * route params. `params` applies globally; `routes` overrides per route
- * template (keys as discovered, e.g. `/[lang]/candidate/[candidateId]`).
- */
 declare const routeConfigSchema: z.ZodObject<{
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     routes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     abandonAfterMs: z.ZodOptional<z.ZodNumber>;
+    abandonFrom: z.ZodOptional<z.ZodEnum<{
+        "first-byte": "first-byte";
+        request: "request";
+    }>>;
 }, z.core.$strict>;
 export type RouteConfig = z.infer<typeof routeConfigSchema>;
 export declare class RouteConfigError extends Error {
@@ -18,12 +17,31 @@ export declare class RouteConfigError extends Error {
 export declare const ROUTE_CONFIG_FILE = "next-leak.config.json";
 /** Missing file → empty config. Present but invalid → loud failure. */
 export declare function loadRouteConfig(appDir: string): Promise<RouteConfig>;
+export type DynamicSegment = {
+    name: string;
+    /** `[...slug]` — the value may span several path segments. */
+    catchAll: boolean;
+    /** `[[...slug]]` — the segment can be omitted entirely. */
+    optional: boolean;
+};
+/**
+ * The dynamic segments of a route template, in order.
+ *
+ * Exported so guidance and resolution read the same grammar: a skeleton that
+ * named parameters the resolver does not recognise would be worse than none.
+ */
+export declare function dynamicSegmentsOf(routeTemplate: string): DynamicSegment[];
 /**
  * Sample values may contain `{n}`, which the load phase replaces with a
  * per-request counter. Leaks keyed by URL (route caches, LRUs, bot traffic
  * with unique tails) are invisible when every request hits the same path.
  */
 export declare const UNIQUE_MARKER = "{n}";
+/** The bound in a sample value, or null when it carries none. */
+export declare function boundedMarkerOf(value: string): {
+    marker: string;
+    bound: number;
+} | null;
 /**
  * Substitutes sample values into a dynamic route template and returns a
  * URL-safe request path (or null when a param has no configured value;

package/dist/route-guidance.d.ts

@@ -0,0 +1,21 @@
+import type { PrerenderManifest } from "./manifests.js";
+/**
+ * Sample values lifted from paths the build actually prerendered.
+ *
+ * A skeleton full of placeholders still leaves the user guessing what a valid
+ * value looks like. The build already knows: `prerender-manifest.json` lists
+ * concrete paths, each pointing back at its template through `srcRoute`, so a
+ * template like `/posts/[slug]` can be filled with a real `post-0` that will
+ * resolve on the first try.
+ */
+export declare function sampleValuesFromManifest(manifest: PrerenderManifest | undefined, routeTemplate: string): Record<string, string> | null;
+/**
+ * The `next-leak.config.json` that would measure the routes a run had to skip.
+ *
+ * Printed rather than merely referenced: telling someone a config file exists
+ * and leaving them to work out its shape is the difference between a run they
+ * can fix in ten seconds and one they abandon.
+ */
+export declare function renderConfigSkeleton(routeTemplates: readonly string[], manifest?: PrerenderManifest | undefined): string | null;
+/** Whether a rendered skeleton still needs the user to fill anything in. */
+export declare function hasPlaceholders(skeleton: string): boolean;

package/dist/runner.d.ts

@@ -1,8 +1,10 @@
+import type { AbandonOrigin } from "./abandon-load.js";
 import { type AttributedDiff } from "./attribution.js";
 import { type ConfidenceReport } from "./confidence.js";
 import type { HeapSample } from "./control-server.js";
 import { type MeasurementEnvironment } from "./environment.js";
 import { diffSnapshotFiles, type HeapDiff } from "./heap-diff.js";
+import { type PrerenderManifest } from "./manifests.js";
 import { extractModuleRegistry } from "./module-registry.js";
 import { runRitual, type LoadOutcome, type PeakSample, type PhaseTiming, type SettleOutcome } from "./ritual.js";
 import { readNextVersion, type MatchedSignature } from "./signatures.js";
@@ -15,6 +17,17 @@ export type RouteReport = {
     route: string;
     status: "failed";
     reason: string;
+}
+/**
+ * The route was reachable, but the load could not have exercised the code
+ * path it represents — so no verdict is emitted. Measuring an ISR route
+ * without driving revalidation reports a flat curve about the static cache,
+ * which reads as health and is not.
+ */
+ | {
+    route: string;
+    status: "not-exercised";
+    reason: string;
 } | {
     route: string;
     status: "measured";
@@ -33,6 +46,40 @@ export type RouteReport = {
      * here is post-GC; this is the one a container limit is judged against.
      */
     peaks: PeakSample[];
+    /**
+     * One reading per cycle taken before any forced collection, and the
+     * trend over them. What a production process holds between full GCs is
+     * not what this tool's verdict measures — see `unreclaimed-retention`.
+     * Empty when a reading was lost: a hole would make every later delta
+     * span two cycles.
+     */
+    unreclaimedSamples: HeapSample[];
+    unreclaimedTrend: TrendResult;
+    /** Requests each cycle served — what the growth rates normalize by. */
+    requestsPerCycle: number;
+    /**
+     * The early-disconnect regime, when the route asked for one. Recorded
+     * because a curve measured with cuts landing mid-stream and one measured
+     * with cuts landing before the response are different experiments, and
+     * the counters alone do not say which was intended.
+     */
+    abandon?: {
+        afterMs: number;
+        from: AbandonOrigin;
+    };
+    /**
+     * Distinct keys the load cycled through, when the route asked for a
+     * bounded set. A verdict about a cache depends on how many keys it saw,
+     * so the number belongs on the record with the rest of the regime.
+     */
+    keyCardinality?: number;
+    /**
+     * Seconds of the ISR revalidation period this route was driven through,
+     * when it has one. Absent on routes not served from the ISR cache.
+     * Recorded because a curve measured against a cache and one measured
+     * against a re-render are different experiments.
+     */
+    revalidatedEverySeconds?: number;
     /** RSS growth per 1000 requests, computed like the heap figure. */
     rssPer1000Requests: number;
     /** Wall-clock per phase — explains where a long run spent its time. */
@@ -88,6 +135,8 @@ export type RunReport = {
     appDir: string;
     startedAt: string;
     workDir: string;
+    /** Carried so the report can suggest sample params the build already knows. */
+    prerender?: PrerenderManifest;
     environment: MeasurementEnvironment;
     parameters: RunParameters;
     routes: RouteReport[];

package/dist/target.d.ts

@@ -1,4 +1,4 @@
-import { type AppPathsManifest, type PagesManifest, type RoutesManifest } from "./manifests.js";
+import { type AppPathsManifest, type PagesManifest, type PrerenderManifest, type RoutesManifest } from "./manifests.js";
 export type TargetErrorCode = "NO_BUILD" | "NO_STANDALONE" | "BAD_MANIFEST";
 export declare class TargetError extends Error {
     readonly code: TargetErrorCode;
@@ -12,6 +12,11 @@ export type ValidatedTarget = {
     pages: PagesManifest;
     /** Absent on builds that do not emit it; nothing downstream reads it. */
     routes: RoutesManifest | undefined;
+    /**
+     * Absent on builds with nothing prerendered. Carries which routes revalidate
+     * and the `previewModeId` needed to make them re-render under load.
+     */
+    prerender: PrerenderManifest | undefined;
 };
 /**
  * Validates that `appDir` contains a production build with

package/dist/unreclaimed-retention.d.ts

@@ -0,0 +1,64 @@
+import type { HeapSample } from "./control-server.js";
+import type { TrendVerdict } from "./trend.js";
+/**
+ * Memory classes compared between the two series, least to most specific.
+ *
+ * `arrayBuffers` is a subset of `external`, so when both are equally out of
+ * proportion the later one wins the tie below — naming the narrower class says
+ * more about the mechanism.
+ */
+declare const CLASSES: readonly ["heap", "external", "arrayBuffers"];
+export type MemoryClass = (typeof CLASSES)[number];
+export type UnreclaimedRetention = {
+    /** Where holding-versus-retaining was most out of proportion. */
+    class: MemoryClass;
+    /** Largest per-cycle gap between what was held and what survived a GC. */
+    largestGapBytes: number;
+    /** What the route retained after collection, in that class. */
+    retainedBytes: number;
+    /** The gap as a multiple of what is retained. */
+    ratio: number;
+};
+export type UnreclaimedRetentionInput = {
+    /** One reading per cycle, taken before any forced collection. */
+    unreclaimedSamples: readonly HeapSample[];
+    /** Post-GC samples: baseline first, then one per cycle. */
+    memorySamples: readonly HeapSample[];
+    /** The route's own verdict, computed from the post-GC series. */
+    verdict: TrendVerdict;
+    /**
+     * Whether that `leak` verdict is one the evidence plainly supports — the same
+     * bar an issue draft has to clear.
+     *
+     * A weak `leak` must not silence this note. Measured on the #96533
+     * reproduction: the post-GC verdict is `leak` at +0.15 MB/1000 req carrying
+     * two low-confidence warnings, which is noise grazing the threshold, while
+     * the gap is 3.96 MB of arrayBuffers at 4x what the route retains. Silencing
+     * on any `leak` at all let the weaker finding hide the stronger one.
+     */
+    verdictIsWellSupported: boolean;
+};
+/**
+ * Whether a route holds materially more memory between collections than it
+ * retains after one.
+ *
+ * The shape of vercel/next.js#96533, where the reporter accumulated 1.16 GB of
+ * arrayBuffers over four days against a flat JS heap. Measured on that repro
+ * 2026-08-18, the signal is a *gap*, not a slope: arrayBuffers sat at 4–5 MB
+ * between collections against a flat 0.32 MB after one, while the series itself
+ * oscillated (+21.2, -3.0, -6.2, +14.2 MB) and classified as `inconclusive`. An
+ * earlier version keyed on that series climbing and reported nothing at all.
+ *
+ * Outside the verdict, like the peak-pressure note: those are statements about
+ * what survives collection, this is one about what precedes it. Silent when the
+ * route already leaks on evidence that supports it — but a marginal `leak` does
+ * not silence it, since on #96533 that weak verdict was hiding this finding.
+ */
+export declare function assessUnreclaimedRetention(input: UnreclaimedRetentionInput): UnreclaimedRetention | null;
+/**
+ * One line, phrased so it never contradicts the verdict beside it, and so it
+ * states its own limit: the reading is taken seconds after load, not the hours
+ * a production process runs between full collections.
+ */
+export declare function describeUnreclaimedRetention(retention: UnreclaimedRetention): string;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-leak",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",
@@ -49,7 +49,11 @@
     "overrides": {
       "uuid": ">=11.1.1",
       "esbuild": ">=0.28.1",
-      "qs": ">=6.15.2"
+      "qs": ">=6.15.2",
+      "js-yaml": ">=4.3.1 <5",
+      "fast-uri": ">=3.1.5 <4",
+      "ip-address": ">=10.3.1 <11",
+      "postcss": ">=8.5.23 <9"
     }
   },
   "devDependencies": {