next-leak 0.5.0 → 0.6.0

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

@@ -89,6 +89,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 +125,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,9 +1,4 @@
 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>>>;
@@ -18,12 +13,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

@@ -3,6 +3,7 @@ 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 +16,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 +45,30 @@ 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;
+    /**
+     * 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 +124,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.0",
+  "version": "0.6.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",