next-leak 0.1.2 → 0.2.0

package/dist/{chunk-5ZYZW2BL.js → chunk-MYYPTZJW.js}

@@ -60,7 +60,7 @@ OS: ${environment.platform} ${environment.arch}${environment.cpuModel ? ` (${env
 Memory: ${(environment.totalMemoryBytes / (1024 * MB)).toFixed(0)} GB
 Next.js: ${environment.nextVersion ?? "unknown"}
 next-leak: ${environment.nextLeakVersion}
-Deployment: output "standalone", node --expose-gc --max-old-space-size=512
+Deployment: output "standalone", node --expose-gc --max-old-space-size=${parameters.maxOldSpaceMb}
 \`\`\`
 
 ### To Reproduce
@@ -72,6 +72,8 @@ Deployment: output "standalone", node --expose-gc --max-old-space-size=512
 2. next-leak boots \`.next/standalone/server.js\` in a fresh process per route and runs, against \`${route.requestPath}\`:
    warm-up ${parameters.warmupRequests} requests \u2192 forced GC \u2192 baseline heap snapshot \u2192
    ${parameters.cycles} \xD7 [${parameters.loadRequests} requests at ${parameters.connections} connections \u2192 ${(parameters.idleMs / 1e3).toFixed(0)}s idle \u2192 forced GC \u2192 post-GC sample] \u2192 final snapshot.
+3. A cycle counts as growing when it retains at least ${(parameters.minGrowthPerCycle / 1024).toFixed(0)} KiB
+   (the gate for this run's ${parameters.loadRequests} requests per cycle); the warm-up cycle is excluded.
 
 ### Current vs. Expected behavior
 

package/dist/{chunk-C3KH5Z2W.js → chunk-SKAPGI62.js}

@@ -1,7 +1,7 @@
 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 {
   effectiveVerdict
-} from "./chunk-2BQZCZ4Z.js";
+} from "./chunk-E5ZKAANQ.js";
 
 // src/html-report.ts
 var MB = 1024 * 1024;
@@ -77,6 +77,7 @@ code{background:#f4f4f4;padding:0 4px;border-radius:3px}
   )} \xB7 ${escapeHtml(environment.platform)}/${escapeHtml(environment.arch)} \xB7 next ${escapeHtml(
     environment.nextVersion ?? "unknown"
   )} \xB7 next-leak ${escapeHtml(environment.nextLeakVersion)}</p>
+<p class="meta">${run.parameters.cycles} cycles \xD7 ${run.parameters.loadRequests} requests \xB7 heap cap ${run.parameters.maxOldSpaceMb} MB \xB7 growth gate ${(run.parameters.minGrowthPerCycle / 1024).toFixed(0)} KiB/cycle</p>
 ${measured.map(measuredSection).join("\n")}
 ${skipped.length === 0 ? "" : `<h2>Skipped</h2><ul>${skipped.map((route) => `<li><code>${escapeHtml(route.route)}</code> \u2014 ${escapeHtml(route.status === "skipped" ? route.reason : "")}</li>`).join("")}</ul>`}
 ${failed.length === 0 ? "" : `<h2>Failed</h2><ul>${failed.map((route) => `<li><code>${escapeHtml(route.route)}</code> \u2014 ${escapeHtml(route.status === "failed" ? route.reason : "")}</li>`).join("")}</ul>`}

package/dist/cli-args.d.ts

@@ -5,6 +5,7 @@ export type CliRunOptions = {
     requests: number | null;
     connections: number | null;
     idleSeconds: number | null;
+    maxOldSpaceMb: number | null;
     quick: boolean;
     diffAll: boolean;
     output: string | null;

package/dist/cli.js

@@ -9,9 +9,9 @@ import {
   killActiveChildren,
   parseCliArgs,
   runMeasurement
-} from "./chunk-WHC6S57X.js";
-import "./chunk-2BQZCZ4Z.js";
-import "./chunk-PF7KYD5N.js";
+} from "./chunk-HAKKAIHN.js";
+import "./chunk-E5ZKAANQ.js";
+import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts
 import { spawn } from "child_process";
@@ -97,6 +97,7 @@ async function main() {
     ...options.requests !== null && { loadRequests: options.requests },
     ...options.connections !== null && { connections: options.connections },
     ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },
+    ...options.maxOldSpaceMb !== null && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...options.diffAll && { diffAll: true },
     ...options.output !== null && { outputDir: options.output },
     onProgress: (message) => console.error(`\xB7 ${message}`)

package/dist/confidence.d.ts

@@ -1,5 +1,6 @@
+import type { HeapSample } from "./control-server.js";
 import type { LoadOutcome, SettleOutcome } from "./ritual.js";
-import type { TrendResult, TrendVerdict } from "./trend.js";
+import { type TrendResult, type TrendVerdict } from "./trend.js";
 /**
  * Why a measurement may not support its own verdict.
  *
@@ -11,8 +12,10 @@ import type { TrendResult, TrendVerdict } from "./trend.js";
  *   mid-stream teardown path was never reached
  * `spiky-growth`        — one cycle dominates, so the mean describes little
  * `near-threshold`      — growth barely clears the noise floor
+ * `near-heap-ceiling`   — the heap approached the cap the process ran under,
+ *   so the curve was measured against a ceiling instead of running free
  */
-export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold";
+export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "near-heap-ceiling";
 export type MeasurementWarning = {
     code: WarningCode;
     detail: string;
@@ -36,6 +39,10 @@ export type ConfidenceInput = {
     abandonAfterMs?: number;
     /** 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;
 };
 /**
  * The verdict a route's evidence actually supports.

package/dist/{html-report-I4PNSLKY.js → html-report-2SOTNXDG.js}

@@ -1,9 +1,9 @@
 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-C3KH5Z2W.js";
-import "./chunk-2BQZCZ4Z.js";
-import "./chunk-PF7KYD5N.js";
+} from "./chunk-SKAPGI62.js";
+import "./chunk-E5ZKAANQ.js";
+import "./chunk-6XYFBOL2.js";
 export {
   renderHtmlReport
 };

package/dist/index.js

@@ -13,7 +13,6 @@ import {
   captureEnvironment,
   checkRuntime,
   classifySource,
-  classifyTrend,
   decodeMappings,
   decodeVlqLine,
   diffAgainstBaseline,
@@ -40,15 +39,17 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-WHC6S57X.js";
+} from "./chunk-HAKKAIHN.js";
 import {
   renderHtmlReport
-} from "./chunk-C3KH5Z2W.js";
-import "./chunk-2BQZCZ4Z.js";
+} from "./chunk-SKAPGI62.js";
+import {
+  classifyTrend
+} from "./chunk-E5ZKAANQ.js";
 import {
   renderIssueMarkdown
-} from "./chunk-5ZYZW2BL.js";
-import "./chunk-PF7KYD5N.js";
+} from "./chunk-MYYPTZJW.js";
+import "./chunk-6XYFBOL2.js";
 export {
   LaunchError,
   LoadError,

package/dist/{issue-report-VQEUXP2E.js → issue-report-X5JYAVN5.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 {
   renderIssueMarkdown
-} from "./chunk-5ZYZW2BL.js";
-import "./chunk-PF7KYD5N.js";
+} from "./chunk-MYYPTZJW.js";
+import "./chunk-6XYFBOL2.js";
 export {
   renderIssueMarkdown
 };

package/dist/launcher.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Old-space cap for measured processes, when the caller does not pick one.
+ *
+ * Small on purpose: a leak that would take a production container an hour to
+ * kill reaches a 512 MB ceiling in minutes. It is a default, not a constant —
+ * an app whose legitimate working set is larger cannot be measured under it,
+ * so `--max-old-space` exists and the chosen value is recorded in `run.json`.
+ */
+export declare const DEFAULT_MAX_OLD_SPACE_MB = 512;
 export type LaunchOptions = {
     /** Absolute path to the standalone `server.js` (or any PORT/HOSTNAME-honoring server). */
     serverPath: string;

package/dist/ritual.d.ts

@@ -17,6 +17,8 @@ export type RitualOptions = {
     connections?: number;
     cycles?: number;
     idleMs?: number;
+    /** Old-space cap for the measured process (MB). Default: 512. */
+    maxOldSpaceMb?: number;
     /** Headers sent with every request during warm-up and load. */
     headers?: Record<string, string>;
     /** Emulate clients that disconnect before the response arrives. */
@@ -68,6 +70,12 @@ export type RitualResult = {
     afterSnapshot: string;
     trend: TrendResult;
     requestsPerCycle: number;
+    /**
+     * The gate (bytes per cycle) this verdict was judged against. Travels with
+     * the result so the confidence audit grades against the same number the
+     * verdict used, and so the report can print what it measured against.
+     */
+    minGrowthPerCycle: number;
 };
 /** Injectable seams for unit tests; production uses the real implementations. */
 export type RitualDeps = {
@@ -75,12 +83,23 @@ export type RitualDeps = {
     load: typeof runLoadPhase;
     sleep: (ms: number) => Promise<void>;
 };
-/** Single source of truth for ritual defaults — reports must echo them. */
+/**
+ * Single source of truth for ritual defaults — reports must echo them.
+ *
+ * `cycles` is 4 rather than the minimum 3 because of how much the verdict
+ * actually sees: the sample array is `[baseline, ...cycles]` and
+ * `classifyTrend` drops the warm-up delta, leaving `cycles - 1` numbers. At 3
+ * cycles that is **two** deltas, and `anyFlatOrDown` needs only one of the two
+ * to be non-positive to call a route stable — one noisy cycle flips the
+ * verdict. Four cycles give three deltas, which is what the real-app
+ * validation ran with. The 3-cycle minimum stays available for users who want
+ * a faster, weaker read.
+ */
 export declare const RITUAL_DEFAULTS: {
     readonly warmupRequests: 200;
     readonly loadRequests: 5000;
     readonly connections: 100;
-    readonly cycles: 3;
+    readonly cycles: 4;
     readonly idleMs: 30000;
 };
 /**

package/dist/runner.d.ts

@@ -6,7 +6,7 @@ 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";
+import { type TrendResult } from "./trend.js";
 export type RouteReport = {
     route: string;
     status: "skipped";
@@ -61,6 +61,18 @@ export type RunParameters = {
     connections: number;
     cycles: number;
     idleMs: number;
+    /**
+     * Old-space cap of each measured process (MB). Part of the measurement
+     * regime: a run near its ceiling is not the same experiment as one with
+     * headroom, so it belongs on the record.
+     */
+    maxOldSpaceMb: number;
+    /**
+     * Per-cycle growth gate the verdicts were judged against (bytes). Derived
+     * from `loadRequests`; recorded because a verdict whose threshold is not
+     * printed cannot be audited or reproduced.
+     */
+    minGrowthPerCycle: number;
 };
 export type RunReport = {
     appDir: string;
@@ -88,6 +100,8 @@ export type RunOptions = {
     connections?: number;
     cycles?: number;
     idleMs?: number;
+    /** Old-space cap for each measured process (MB). Default 512. */
+    maxOldSpaceMb?: number;
     /** Also diff routes with a stable verdict. Default false: diffs are slow. */
     diffAll?: boolean;
     /** Only measure routes matching these templates or prefixes. */
@@ -96,7 +110,24 @@ export type RunOptions = {
     signal?: AbortSignal;
     onProgress?: (message: string) => void;
 };
-export declare function estimateRunSeconds(routeCount: number, parameters: RunParameters): number;
+export type RunEstimate = {
+    /**
+     * Costs no run avoids: process launch, GC, snapshots and the minimum
+     * settle. Request-serving time is left out on purpose — throughput is the
+     * one term that swings 10x between a hello-world route and a real one, so a
+     * floor that guessed at it would not be a floor.
+     */
+    fastSeconds: number;
+    /** Full idle window every cycle, at the lowest throughput ever measured. */
+    slowSeconds: number;
+};
+export declare function estimateRun(routeCount: number, parameters: RunParameters): RunEstimate;
+/**
+ * A point estimate cannot be right across app weights: the adaptive idle ends
+ * as soon as the heap holds still, which on a small app is almost at once. A
+ * range says that out loud instead of quoting the worst case as the price.
+ */
+export declare function formatEstimate(estimate: RunEstimate): string;
 export declare function formatDuration(seconds: number): string;
 export type RunnerDeps = {
     ritual: typeof runRitual;

package/dist/trend.d.ts

@@ -16,9 +16,44 @@ export type TrendResult = {
     source?: "heap" | "external";
 };
 export type TrendOptions = {
-    /** Minimum per-cycle growth (bytes) considered leak-like. Default: 256 KiB. */
+    /**
+     * Minimum per-cycle growth (bytes) considered leak-like. Defaults to the
+     * noise floor alone — callers that know how much traffic ran should pass
+     * `minGrowthFor(requestsPerCycle)` instead.
+     */
     minGrowthPerCycle?: number;
 };
+/**
+ * Smallest per-cycle growth distinguishable from measurement noise.
+ *
+ * This is a property of the *instrument*, not of the leak: post-GC samples
+ * jitter by roughly this much regardless of how much traffic ran, so no amount
+ * of load makes growth below it meaningful.
+ */
+export declare const MIN_GROWTH_NOISE_FLOOR: number;
+/**
+ * Growth rate that counts as leak-like, per 1000 requests.
+ *
+ * This is a property of the *leak*: a route that retains memory per request
+ * grows in proportion to the traffic it served, so the gate has to scale with
+ * it. 51.2 KiB is the rate that leaves the default profile (5000 requests per
+ * cycle) on exactly the 256 KiB gate this tool was validated against.
+ */
+export declare const MIN_GROWTH_PER_1000_REQUESTS: number;
+/**
+ * The gate a per-cycle delta must clear to count as growth.
+ *
+ * `max` rather than a sum, because the two terms bound different things: the
+ * floor is what the instrument can resolve, the rate is what the leak should
+ * produce. Below ~5000 requests per cycle the floor dominates and the run is
+ * noise-limited — which is a real limit of measuring less traffic, not a
+ * threshold that can be lowered.
+ *
+ * Without this, the verdict silently depended on `--requests`: the same route
+ * leaking 100 KiB per 1000 requests printed the same headline in every mode
+ * but came out `stable` at 2000 requests per cycle and `leak` at 5000.
+ */
+export declare function minGrowthFor(requestsPerCycle: number): number;
 /**
  * Classifies a series of post-GC retained-heap samples — baseline first, then
  * one sample per load cycle — as leaking or stable.

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "next-leak",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",
+    "next.js",
     "memory-leak",
+    "memory",
+    "oom",
+    "oomkilled",
+    "heap",
     "heap-snapshot",
+    "profiling",
+    "performance",
+    "nodejs",
     "diagnostics",
+    "debugging",
     "cli"
   ],
   "license": "MIT",
@@ -18,14 +27,15 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
     "node": ">=22"
   },
   "packageManager": "pnpm@10.20.0",
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/generate-notices.mjs && node scripts/check-bundle.mjs",
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -37,7 +47,9 @@
   },
   "pnpm": {
     "overrides": {
-      "uuid": ">=11.1.1"
+      "uuid": ">=11.1.1",
+      "esbuild": ">=0.28.1",
+      "qs": ">=6.15.2"
     }
   },
   "devDependencies": {