next-leak 0.1.0

package/dist/module-registry.d.ts

@@ -0,0 +1,24 @@
+import { type LineMapping } from "./vlq.js";
+/** Bundler module id → source path (e.g. `[project]/src/app/leaky/page.tsx`). */
+export type ModuleRegistry = ReadonlyMap<number, string>;
+export type NormalizedSourceMap = {
+    sources: string[];
+    lines: LineMapping[];
+};
+/** Accepts flat or sectioned sourcemaps; null when it is neither. */
+export declare function normalizeSourceMap(raw: unknown): NormalizedSourceMap | null;
+/**
+ * Extracts `[id, factory, ...]` pairs from a Turbopack CJS chunk by walking
+ * the sourcemap instead of lexing JavaScript: each factory is a contiguous
+ * region mapped to one source, so a change of source index marks a factory
+ * boundary, and the module id is the last integer literal in the unmapped
+ * gap right before it. Non-Turbopack chunks contribute nothing.
+ */
+export declare function extractChunkModules(code: string, rawMap: unknown): Map<number, string>;
+/**
+ * Builds the module registry by scanning every server chunk that has an
+ * adjacent sourcemap. Missing maps, unparseable chunks, or non-Turbopack
+ * builds simply contribute nothing: an empty registry means every finding
+ * degrades to `unattributed`.
+ */
+export declare function extractModuleRegistry(nextServerDir: string): Promise<ModuleRegistry>;

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,95 @@
+import type { HeapSample } from "./control-server.js";
+import { launchInstrumented } from "./launcher.js";
+import { runLoadPhase } from "./load.js";
+import { type TrendResult } from "./trend.js";
+export type RitualOptions = {
+    /** Absolute path to the standalone server.js. */
+    serverPath: string;
+    /** Concrete request path (dynamic params already resolved), e.g. "/products/42". */
+    route: string;
+    /** Directory for this route's snapshots and control file. */
+    workDir: string;
+    /** Built bootstrap module for `--import`. */
+    bootstrapPath: string;
+    appPort: number;
+    warmupRequests?: number;
+    loadRequests?: number;
+    connections?: number;
+    cycles?: number;
+    idleMs?: number;
+    /** Headers sent with every request during warm-up and load. */
+    headers?: Record<string, string>;
+    /** Emulate clients that disconnect before the response arrives. */
+    abandonAfterMs?: number;
+};
+export type PhaseTiming = {
+    phase: string;
+    seconds: number;
+};
+/** What each load phase actually did — auditable after the fact. */
+export type LoadOutcome = {
+    phase: string;
+    sent: number;
+    ok2xx?: number;
+    non2xx?: number;
+    errors?: number;
+    timeouts?: number;
+    abandoned?: number;
+    /** Abandonments where the response had already started — the mid-stream path. */
+    abandonedMidStream?: number;
+};
+/**
+ * Whether the heap actually held still before each sample was taken.
+ *
+ * `unknown` is not a softer `moving`: with fewer than two GC readings there is
+ * nothing to compare, so the run never learned whether the heap was steady.
+ * Conflating the two made every short-idle run look like a moving heap.
+ */
+export type SettleStatus = "settled" | "moving" | "unknown";
+export type SettleOutcome = {
+    phase: string;
+    status: SettleStatus;
+    /** GC polls taken before converging or giving up. */
+    polls: number;
+};
+export type RitualResult = {
+    route: string;
+    /** Wall-clock per phase, so slow runs can be explained instead of guessed. */
+    timings: PhaseTiming[];
+    /** Per-phase request outcomes; without these a run cannot be audited. */
+    loadOutcomes: LoadOutcome[];
+    /** Per-cycle settle results: a sample taken while the heap moved is suspect. */
+    settleOutcomes: SettleOutcome[];
+    /** Post-GC heapUsed per phase: baseline first, then one per cycle. */
+    samples: number[];
+    /** Full memory samples in the same order. */
+    memorySamples: HeapSample[];
+    baselineSnapshot: string;
+    afterSnapshot: string;
+    trend: TrendResult;
+    requestsPerCycle: number;
+};
+/** Injectable seams for unit tests; production uses the real implementations. */
+export type RitualDeps = {
+    launch: typeof launchInstrumented;
+    load: typeof runLoadPhase;
+    sleep: (ms: number) => Promise<void>;
+};
+/** Single source of truth for ritual defaults — reports must echo them. */
+export declare const RITUAL_DEFAULTS: {
+    readonly warmupRequests: 200;
+    readonly loadRequests: 5000;
+    readonly connections: 100;
+    readonly cycles: 3;
+    readonly idleMs: 30000;
+};
+/**
+ * Runs the validated phase-0 ritual against one route in a fresh process:
+ *
+ *   warm-up → GC → baseline snapshot
+ *   → [load → idle → GC → sample] × cycles (last cycle snapshots)
+ *
+ * Warm-up before the baseline and idle+GC before every sample are what
+ * separate a real measurement from the classic false positive.
+ */
+export declare function runRitual(options: RitualOptions, deps?: RitualDeps): Promise<RitualResult>;

package/dist/route-config.d.ts

@@ -0,0 +1,36 @@
+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]`).
+ */
+export 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>;
+}, z.core.$strict>;
+export type RouteConfig = z.infer<typeof routeConfigSchema>;
+export declare class RouteConfigError extends Error {
+    constructor(message: string);
+}
+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>;
+/**
+ * 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}";
+/**
+ * Substitutes sample values into a dynamic route template and returns a
+ * URL-safe request path (or null when a param has no configured value;
+ * optional catch-alls without a value are dropped instead).
+ *
+ * Percent-encoding is not cosmetic: an unencoded `#` silently truncated the
+ * path (a different route got measured) and unencoded non-ASCII produced
+ * requests that never completed — both verified against a real server.
+ */
+export declare function resolveRoutePath(routeTemplate: string, config: RouteConfig): string | null;

package/dist/run-report.fixture.d.ts

@@ -0,0 +1,3 @@
+import type { RunReport } from "./runner.js";
+/** Canonical report fixture shared by report/html/issue renderer tests. */
+export declare function makeRunReport(): RunReport;

package/dist/runner.d.ts

@@ -0,0 +1,127 @@
+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 { extractModuleRegistry } from "./module-registry.js";
+import { runRitual, type LoadOutcome, type PhaseTiming, type SettleOutcome } from "./ritual.js";
+import { readNextVersion, type MatchedSignature } from "./signatures.js";
+import type { TrendResult } from "./trend.js";
+export type RouteReport = {
+    route: string;
+    status: "skipped";
+    reason: string;
+} | {
+    route: string;
+    status: "failed";
+    reason: string;
+} | {
+    route: string;
+    status: "measured";
+    /** Concrete path requested (differs from `route` for dynamic templates). */
+    requestPath: string;
+    samples: number[];
+    /**
+     * Full post-GC memory samples. RSS matters as much as the heap: a
+     * process can hold gigabytes of RSS with a flat JS heap (allocator
+     * behaviour, external buffers), which is a different diagnosis and a
+     * different fix than a heap leak.
+     */
+    memorySamples: HeapSample[];
+    /** RSS growth per 1000 requests, computed like the heap figure. */
+    rssPer1000Requests: number;
+    /** Wall-clock per phase — explains where a long run spent its time. */
+    timings: PhaseTiming[];
+    /** What each load phase actually did (sent, 2xx, abandoned…). */
+    loadOutcomes: LoadOutcome[];
+    /** Whether the heap held still before each sample. */
+    settleOutcomes: SettleOutcome[];
+    /**
+     * Audit of the measurement against its own evidence. `trend` stays as
+     * measured; when the evidence does not support it, `confidence`
+     * carries the verdict that does — see `effectiveVerdict`.
+     */
+    confidence: ConfidenceReport;
+    trend: TrendResult;
+    growthPer1000Requests: number;
+    baselineSnapshot: string;
+    afterSnapshot: string;
+    /** Null when the verdict is stable and diffAll was not requested. */
+    diff: HeapDiff | null;
+    /** Null when there is no diff or no module registry. */
+    attribution: AttributedDiff | null;
+    signatures: MatchedSignature[];
+};
+export type MeasuredRoute = Extract<RouteReport, {
+    status: "measured";
+}>;
+export type RunParameters = {
+    warmupRequests: number;
+    loadRequests: number;
+    connections: number;
+    cycles: number;
+    idleMs: number;
+};
+export type RunReport = {
+    appDir: string;
+    startedAt: string;
+    workDir: string;
+    environment: MeasurementEnvironment;
+    parameters: RunParameters;
+    routes: RouteReport[];
+    bundle: {
+        htmlReport: string;
+        issues: Array<{
+            route: string;
+            file: string;
+        }>;
+    };
+};
+export type RunOptions = {
+    appDir: string;
+    /** Built bootstrap module for `--import` into measured processes. */
+    bootstrapPath: string;
+    /** Parent output directory. Default: `<appDir>/.next-leak`. */
+    outputDir?: string;
+    warmupRequests?: number;
+    loadRequests?: number;
+    connections?: number;
+    cycles?: number;
+    idleMs?: number;
+    /** Also diff routes with a stable verdict. Default false: diffs are slow. */
+    diffAll?: boolean;
+    /** Only measure routes matching these templates or prefixes. */
+    routeFilter?: string[];
+    /** Abort between phases; remaining routes are reported as interrupted. */
+    signal?: AbortSignal;
+    onProgress?: (message: string) => void;
+};
+export declare function estimateRunSeconds(routeCount: number, parameters: RunParameters): number;
+export declare function formatDuration(seconds: number): string;
+export type RunnerDeps = {
+    ritual: typeof runRitual;
+    diff: typeof diffSnapshotFiles;
+    freePort: () => Promise<number>;
+    registry: typeof extractModuleRegistry;
+    nextVersion: typeof readNextVersion;
+};
+export declare function freePort(): Promise<number>;
+/**
+ * Filesystem-safe label for a route. Distinct routes MUST get distinct slugs:
+ * `/a/b` and `/a_b` used to collapse onto the same `ISSUE-a_b.md`, and any
+ * all-non-ASCII path (`/ñ`) became "root", colliding with `/`. A short digest
+ * disambiguates whenever the sanitized form loses information.
+ */
+/**
+ * Mean RSS growth per cycle, excluding the warm-up cycle exactly like the
+ * heap verdict does. Reported alongside the heap so a flat heap with growing
+ * RSS is visible instead of invisible.
+ */
+export declare function rssTrend(memorySamples: readonly HeapSample[]): number;
+export declare function routeSlug(route: string): string;
+/**
+ * Full measurement run: validate the target, discover routes, run the ritual
+ * per route in a fresh process, diff snapshots for non-stable verdicts, and
+ * persist `run.json` plus raw snapshots under the work directory.
+ */
+export declare function runMeasurement(options: RunOptions, deps?: RunnerDeps): Promise<RunReport>;

package/dist/signatures.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { HeapDiff } from "./heap-diff.js";
+declare const signatureSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    nextRange: z.ZodString;
+    cause: z.ZodString;
+    issue: z.ZodURL;
+    historical: z.ZodBoolean;
+    match: z.ZodObject<{
+        chainIncludes: z.ZodOptional<z.ZodString>;
+        typeDeltaAbove: z.ZodOptional<z.ZodObject<{
+            type: z.ZodString;
+            bytes: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type Signature = z.infer<typeof signatureSchema>;
+export declare function loadSignatures(raw?: unknown[]): Signature[];
+export type MatchedSignature = Pick<Signature, "id" | "title" | "cause" | "issue" | "historical">;
+/**
+ * Matches signatures against a diff, gated by the measured app's Next.js
+ * version. Unknown version or no matching range → no annotations, no errors.
+ */
+export declare function matchSignatures(diff: HeapDiff, nextVersion: string | null, signatures?: Signature[]): MatchedSignature[];
+/** Reads the measured app's Next.js version from its standalone bundle. */
+export declare function readNextVersion(appDir: string): Promise<string | null>;
+export {};

package/dist/target.d.ts

@@ -0,0 +1,21 @@
+import { type AppPathsManifest, type PagesManifest, type RoutesManifest } from "./manifests.js";
+export type TargetErrorCode = "NO_BUILD" | "NO_STANDALONE" | "BAD_MANIFEST";
+export declare class TargetError extends Error {
+    readonly code: TargetErrorCode;
+    constructor(code: TargetErrorCode, message: string);
+}
+export type ValidatedTarget = {
+    appDir: string;
+    /** Absolute path to `.next/standalone/server.js`. */
+    standaloneServer: string;
+    appPaths: AppPathsManifest;
+    pages: PagesManifest;
+    /** Absent on builds that do not emit it; nothing downstream reads it. */
+    routes: RoutesManifest | undefined;
+};
+/**
+ * Validates that `appDir` contains a production build with
+ * `output: "standalone"` and readable route manifests. Fails fast with an
+ * actionable message otherwise.
+ */
+export declare function validateTarget(appDir: string): Promise<ValidatedTarget>;

package/dist/trend.d.ts

@@ -0,0 +1,38 @@
+export type TrendVerdict = "leak" | "stable" | "inconclusive";
+export type TrendResult = {
+    verdict: TrendVerdict;
+    /** Mean retained-heap growth per cycle (bytes) over the analyzed window. */
+    growthPerCycle: number;
+    /** Per-cycle deltas (bytes) after dropping the warm-up cycle. */
+    deltas: number[];
+    /**
+     * Which memory produced the verdict. A Node process can leak in three
+     * places and only one of them is the JS heap: `external`/`arrayBuffers`
+     * hold fetch bodies, streams and Buffers, and can OOM a process while the
+     * heap stays flat (vercel/next.js#92287 reports 4.3 GB of arrayBuffers
+     * against a healthy heap). Reporting the heap alone would call that
+     * "stable".
+     */
+    source?: "heap" | "external";
+};
+export type TrendOptions = {
+    /** Minimum per-cycle growth (bytes) considered leak-like. Default: 256 KiB. */
+    minGrowthPerCycle?: number;
+};
+/**
+ * Classifies a series of post-GC retained-heap samples — baseline first, then
+ * one sample per load cycle — as leaking or stable.
+ *
+ * The baseline→cycle-1 delta is excluded from the verdict: measurements on
+ * healthy routes show it is dominated by one-time engine warm-up (JIT code,
+ * lazy caches) even after an HTTP-level warm-up phase. A leak must keep
+ * growing across the remaining cycles; warm-up flattens out.
+ */
+export declare function classifyTrend(samples: readonly number[], options?: TrendOptions): TrendResult;
+/**
+ * Verdict over both the JS heap and external memory, taking the worse of the
+ * two. External memory (`external`, which includes `arrayBuffers`) holds
+ * fetch bodies, streams and Buffers; a process can be killed by OOM with a
+ * perfectly flat heap, so judging the heap alone answers the wrong question.
+ */
+export declare function classifyMemoryTrend(heapSamples: readonly number[], externalSamples: readonly number[], options?: TrendOptions): TrendResult;

package/dist/vlq.d.ts

@@ -0,0 +1,16 @@
+/** Decodes one line of base64-VLQ segments from a sourcemap `mappings` string. */
+export declare function decodeVlqLine(line: string): number[][];
+export type LineMapping = {
+    /** Generated column → source index, sorted by column. */
+    entries: Array<{
+        column: number;
+        sourceIndex: number;
+    }>;
+};
+/**
+ * Decodes a sourcemap `mappings` string into per-line column → source-index
+ * tables. Only the fields attribution needs; name/line positions are dropped.
+ */
+export declare function decodeMappings(mappings: string): LineMapping[];
+/** Returns the source index active at (line, column), or undefined. */
+export declare function sourceIndexAt(lines: LineMapping[], line: number, column: number): number | undefined;

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "next-leak",
+  "version": "0.1.0",
+  "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
+  "keywords": [
+    "nextjs",
+    "memory-leak",
+    "heap-snapshot",
+    "diagnostics",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Xabier Lameiro <xabier.lameiro@gmail.com>",
+  "type": "module",
+  "bin": {
+    "next-leak": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.20.0",
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "test:mutation": "stryker run",
+    "prepare": "husky >/dev/null 2>&1 || true",
+    "release": "release-it"
+  },
+  "pnpm": {
+    "overrides": {
+      "uuid": ">=11.1.1"
+    }
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@memlab/core": "^2.0.4",
+    "@memlab/heap-analysis": "^2.0.4",
+    "@release-it/conventional-changelog": "^11.0.1",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@types/autocannon": "^7.12.7",
+    "@types/node": "^26.1.1",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "husky": "^9.1.7",
+    "release-it": "^20.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "autocannon": "^8.0.0",
+    "semver": "^7.8.5",
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xabierlameiro/next-leak.git"
+  },
+  "homepage": "https://github.com/xabierlameiro/next-leak#readme",
+  "bugs": {
+    "url": "https://github.com/xabierlameiro/next-leak/issues"
+  }
+}