next-leak 0.1.0 → 0.1.3

package/README.md

@@ -7,6 +7,8 @@
 
 > Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.
 
+<img src="https://raw.githubusercontent.com/xabierlameiro/next-leak/main/docs/demo.svg" alt="next-leak finding a real Next.js memory leak (43-second run, idle time compressed)" width="720">
+
 ```
 $ npx next-leak . --quick
 
@@ -35,10 +37,27 @@ holds it — without being told what to look for.
 | [#84884](https://github.com/vercel/next.js/issues/84884) | axios + `AbortSignal` in middleware | **Reproduced** · 32.8 → 369.9 MB |
 | [#94919](https://github.com/vercel/next.js/issues/94919) | RSC tree retained on client aborts | Not reproduced on standalone — [and it says why](#scope-and-limits-read-before-filing-issues) |
 
+The full causal chain, measured on that same issue: leak found (28.7 -> 138.9 MB
+across 8 cycles), the workaround from the thread applied (`clearTimeout(id)`
+inside the callback), same app re-measured with identical parameters:
+**27.8 -> 25.6 MB, flat**. That is what a diagnostic tool should prove - not
+that installing it saves memory, but that what it points at is the real cause.
+
 Across ~25 healthy routes on production applications (PPR, MDX, Auth.js,
 Sentry, i18n), it reported **zero false positives**.
 
-Your server's memory climbs and the container gets OOM-killed. Almost every report of this ends the same way: *"please provide heap snapshots taken after forced GC"* — which almost nobody produces correctly. `next-leak` runs that controlled measurement for you and answers with evidence a maintainer would accept.
+Your self-hosted Next.js server's memory climbs until Node gives up:
+
+```
+FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
+```
+
+Under Docker or Kubernetes you may not even get that: the process is `OOMKilled`,
+the container exits with **code 137**, and the restart wipes the evidence before
+you can look at it. Almost every report of this ends the same way — *"please
+provide heap snapshots taken after forced GC"* — which almost nobody produces
+correctly. `next-leak` runs that controlled measurement for you and answers with
+evidence a maintainer would accept.
 
 Three possible answers, all valuable:
 
@@ -107,6 +126,20 @@ Dynamic routes need sample params in `next-leak.config.json` in your app dir:
 
 Before measuring, the CLI prints a duration estimate — a 60-route app under defaults is **hours**; narrow with `--routes` for iteration.
 
+## What it tells apart
+
+"Memory leak" is one name for six different situations. The verdict machinery
+separates them, because each one has a different fix:
+
+| Looks like a leak | What next-leak reports | How it knows |
+|---|---|---|
+| One-time warm-up growth (JIT, lazy caches) | `stable` | The first cycle is excluded from the verdict; warm-up flattens, leaks keep climbing |
+| A route that is expensive, not leaky | `failed` under load it cannot sustain, flat once concurrency fits | Real leaks survive forced GC at any concurrency; saturation disappears when load drops |
+| Growth that pauses and resumes (stepwise) | `leak` | A healthy route gives back 20-30% of its growth; a stepwise leak gives back nothing |
+| Native/buffer memory with a flat JS heap | `leak (external)` or an explicit RSS note | Heap, `external` and RSS are sampled and judged separately |
+| A leak in your code vs a dependency vs Next itself | `culprit: src/app/x/page.tsx (your code)` — or the package, or framework internals | Retainer chains mapped through the build's source maps |
+| A run whose own evidence is weak | `low confidence` warnings, or the verdict is withdrawn | Every run audits itself: did the load land, did the heap settle, does one cycle carry the average |
+
 ## Reading the verdicts
 
 - **`stable`** — done, stop hunting. The report proves it. If the heap is flat

package/dist/attribution.d.ts

@@ -18,8 +18,6 @@ export type RouteAttribution = FindingAttribution & {
  * (Next 16.2 sectioned maps). Exported for direct unit testing.
  */
 export declare function classifySource(rawSource: string): FindingAttribution;
-/** Best-effort owner for chains the module registry cannot resolve. */
-export declare function classifyByChain(retainerChain: string): FindingAttribution | null;
 /**
  * Resolves a finding's harvested module ids against the registry. When a
  * chain crosses several modules (e.g. Next's page-template wrapper retaining

package/dist/bootstrap.js

@@ -1,5 +1,5 @@
 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 "./chunk-OSZ6ND6E.js";
+import "./chunk-6XYFBOL2.js";
 
 // src/bootstrap.ts
 import { mkdir, writeFile } from "fs/promises";

package/dist/chunk-2BQZCZ4Z.js

@@ -0,0 +1,129 @@
+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);
+
+// src/confidence.ts
+function effectiveVerdict(report) {
+  return report.confidence.supersededVerdict ?? report.trend.verdict;
+}
+var VERDICT_WEAKENING = /* @__PURE__ */ new Set([
+  "near-threshold",
+  "spiky-growth"
+]);
+function warrantsIssueDraft(report) {
+  return effectiveVerdict(report) === "leak" && !report.confidence.warnings.some((warning) => VERDICT_WEAKENING.has(warning.code));
+}
+var DEFAULT_MIN_GROWTH = 256 * 1024;
+var LOAD_COMPLETION_FLOOR = 0.99;
+var ABANDON_EFFECTIVE_FLOOR = 0.9;
+var MID_STREAM_FLOOR = 0.1;
+var SPIKE_RATIO = 4;
+var NOISE_FLOOR_MULTIPLE = 2;
+var mb = (bytes) => `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+var pct = (part, whole) => `${(part / whole * 100).toFixed(1)}%`;
+function settleWarnings(outcomes) {
+  const warnings = [];
+  const moving = outcomes.filter((outcome) => outcome.status === "moving");
+  if (moving.length > 0) {
+    warnings.push({
+      code: "unsettled",
+      detail: `the heap never held steady before sampling on ${moving.map((outcome) => outcome.phase).join(", ")} \u2014 raise --idle-ms so post-load transients finish draining`
+    });
+  }
+  const unverified = outcomes.filter((outcome) => outcome.status === "unknown");
+  if (unverified.length > 0) {
+    warnings.push({
+      code: "settle-unverified",
+      detail: `the idle budget was too short to check whether the heap had settled on ${unverified.map((outcome) => outcome.phase).join(", ")} \u2014 the samples may include post-load transients`
+    });
+  }
+  return warnings;
+}
+function abandonmentWarnings(outcome) {
+  const abandoned = outcome.abandoned ?? 0;
+  if (outcome.sent > 0 && abandoned < outcome.sent * ABANDON_EFFECTIVE_FLOOR) {
+    return [{
+      code: "abandon-ineffective",
+      detail: `${outcome.phase} disconnected early on only ${abandoned} of ${outcome.sent} requests (${pct(abandoned, outcome.sent)}) \u2014 the early-disconnect path was largely not exercised`
+    }];
+  }
+  const midStream = outcome.abandonedMidStream ?? 0;
+  if (abandoned > 0 && midStream < abandoned * MID_STREAM_FLOOR) {
+    return [{
+      code: "abandon-before-response",
+      detail: `${outcome.phase} cut ${abandoned} requests before the server sent anything (${midStream} mid-stream) \u2014 this tested pre-response disconnects, not mid-stream teardown; raise abandonAfterMs above the route's time-to-first-byte`
+    }];
+  }
+  return [];
+}
+function loadWarnings(outcomes, abandonAfterMs) {
+  const warnings = [];
+  for (const outcome of outcomes) {
+    if (abandonAfterMs !== void 0) {
+      warnings.push(...abandonmentWarnings(outcome));
+      continue;
+    }
+    const landed = outcome.ok2xx ?? 0;
+    if (outcome.sent > 0 && landed < outcome.sent * LOAD_COMPLETION_FLOOR) {
+      warnings.push({
+        code: "load-incomplete",
+        detail: `${outcome.phase} landed ${landed} of ${outcome.sent} requests (${pct(landed, outcome.sent)}) \u2014 the route saw less traffic than reported`
+      });
+    }
+  }
+  return warnings;
+}
+function growthShapeWarnings(trend) {
+  const judged = trend.verdict === "leak" || trend.verdict === "inconclusive";
+  if (!judged || trend.deltas.length < 2) {
+    return [];
+  }
+  const positive = trend.deltas.filter((delta) => delta > 0);
+  if (positive.length !== trend.deltas.length) {
+    return [];
+  }
+  const smallest = Math.min(...positive);
+  const largest = Math.max(...positive);
+  if (largest <= smallest * SPIKE_RATIO) {
+    return [];
+  }
+  return [{
+    code: "spiky-growth",
+    detail: `one cycle grew ${mb(largest)} and another ${mb(smallest)} \u2014 the mean of ${mb(trend.growthPerCycle)}/cycle summarizes an uneven series; measure more cycles before quoting it`
+  }];
+}
+function noiseFloorWarnings(trend, minGrowth) {
+  if (trend.verdict !== "leak" || trend.growthPerCycle >= minGrowth * NOISE_FLOOR_MULTIPLE) {
+    return [];
+  }
+  return [{
+    code: "near-threshold",
+    detail: `growth of ${mb(trend.growthPerCycle)}/cycle barely clears the ${mb(minGrowth)} threshold \u2014 raise --load-requests so the signal outgrows the noise`
+  }];
+}
+function isVerdictInvalid(input) {
+  if (input.trend.verdict !== "leak") {
+    return false;
+  }
+  const neverSettled = input.settleOutcomes.length > 0 && input.settleOutcomes.every((outcome) => outcome.status === "moving");
+  const abandonedNothing = input.abandonAfterMs !== void 0 && input.loadOutcomes.length > 0 && input.loadOutcomes.every((outcome) => (outcome.abandoned ?? 0) === 0);
+  return neverSettled || abandonedNothing;
+}
+function assessConfidence(input) {
+  const minGrowth = input.minGrowthPerCycle ?? DEFAULT_MIN_GROWTH;
+  const warnings = [
+    ...settleWarnings(input.settleOutcomes),
+    ...loadWarnings(input.loadOutcomes, input.abandonAfterMs),
+    ...growthShapeWarnings(input.trend),
+    ...noiseFloorWarnings(input.trend, minGrowth)
+  ];
+  return {
+    level: warnings.length === 0 ? "high" : "low",
+    warnings,
+    ...isVerdictInvalid(input) && { supersededVerdict: "inconclusive" }
+  };
+}
+
+export {
+  effectiveVerdict,
+  warrantsIssueDraft,
+  assessConfidence
+};

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

@@ -3,11 +3,25 @@ import { createRequire as __nextLeakCreateRequire } from 'node:module';import {
 // src/issue-report.ts
 import path from "path";
 var MB = 1024 * 1024;
+function ownerLabel(attribution) {
+  if (attribution === void 0 || attribution.owner === "unattributed") {
+    return "unattributed";
+  }
+  const source = attribution.source ? ` \u2014 \`${attribution.source}\`` : "";
+  const packageName = attribution.packageName ? ` \u2014 ${attribution.packageName}` : "";
+  return `${attribution.owner}${source}${packageName}`;
+}
+function blamedParty(owner, culprit) {
+  if (owner === "app") {
+    return `**your own code** (\`${culprit?.source ?? "app code"}\`)`;
+  }
+  return `the dependency **${culprit?.packageName ?? "a dependency"}**`;
+}
 function evidenceRows(route) {
   const findings = [...route.diff?.grownNodes ?? [], ...route.diff?.newNodes ?? []];
   return findings.slice(0, 6).map((finding, index) => {
     const attribution = route.attribution?.findings[index];
-    const owner = attribution === void 0 || attribution.owner === "unattributed" ? "unattributed" : `${attribution.owner}${attribution.source ? ` \u2014 \`${attribution.source}\`` : ""}${attribution.packageName ? ` \u2014 ${attribution.packageName}` : ""}`;
+    const owner = ownerLabel(attribution);
     return `- **${finding.kind}** \`[${finding.nodeType}] ${finding.name}\` ${(finding.retainedBytes / MB).toFixed(2)} MB retained (${owner})
   - retainers: \`${finding.retainerChain || "(none)"}\``;
   }).join("\n");
@@ -18,7 +32,7 @@ function renderIssueMarkdown(route, run) {
   const owner = route.attribution?.route.owner ?? "unattributed";
   const culprit = route.attribution?.route;
   const preamble = owner === "app" || owner === "dependency" ? `> [!WARNING]
-> next-leak attributes this leak to ${owner === "app" ? `**your own code** (\`${culprit?.source ?? "app code"}\`)` : `the dependency **${culprit?.packageName ?? "a dependency"}**`}. Fix or report it there \u2014 do **not** file this against Next.js.
+> next-leak attributes this leak to ${blamedParty(owner, culprit)}. Fix or report it there \u2014 do **not** file this against Next.js.
 
 ` : "";
   const caveats = route.confidence.warnings.length === 0 ? "" : `

package/dist/{chunk-OSZ6ND6E.js → chunk-6XYFBOL2.js}

@@ -11,8 +11,24 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
 var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
 };
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
@@ -30,9 +46,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 export {
   __require,
+  __esm,
   __commonJS,
-  __toESM
+  __export,
+  __toESM,
+  __toCommonJS
 };

package/dist/{chunk-4BMPC45G.js → chunk-C3KH5Z2W.js}

@@ -1,13 +1,13 @@
 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-K5PZFVJH.js";
+} from "./chunk-2BQZCZ4Z.js";
 
 // src/html-report.ts
 var MB = 1024 * 1024;
 var VERDICT_COLOR = { leak: "#c0392b", stable: "#27ae60", inconclusive: "#e67e22" };
 function escapeHtml(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }
 function heapCurveSvg(samples, color) {
   const width = 320;
@@ -28,6 +28,14 @@ function heapCurveSvg(samples, color) {
     return `<circle cx="${x.toFixed(1)}" cy="${y.toFixed(1)}" r="2.5" fill="${color}"/>`;
   }).join("") + `</svg>`;
 }
+function ownerCell(attribution) {
+  if (attribution === void 0 || attribution.owner === "unattributed") {
+    return "\u2014";
+  }
+  const source = attribution.source ? `: ${escapeHtml(attribution.source)}` : "";
+  const packageName = attribution.packageName ? ` (${escapeHtml(attribution.packageName)})` : "";
+  return `${attribution.owner}${source}${packageName}`;
+}
 function measuredSection(route) {
   if (route.status !== "measured") {
     return "";
@@ -40,7 +48,7 @@ function measuredSection(route) {
   const findings = [...route.diff?.grownNodes ?? [], ...route.diff?.newNodes ?? []];
   const findingRows = findings.slice(0, 6).map((finding, index) => {
     const attribution = route.attribution?.findings[index];
-    const owner = attribution === void 0 || attribution.owner === "unattributed" ? "\u2014" : `${attribution.owner}${attribution.source ? `: ${escapeHtml(attribution.source)}` : ""}${attribution.packageName ? ` (${escapeHtml(attribution.packageName)})` : ""}`;
+    const owner = ownerCell(attribution);
     return `<tr><td>${finding.kind}</td><td>${escapeHtml(finding.nodeType)}</td><td>${escapeHtml(finding.name)}</td><td>${(finding.retainedBytes / MB).toFixed(2)} MB</td><td>${owner}</td></tr>`;
   }).join("");
   return `<section><h2><span class="badge" style="background:${color}">${verdict}</span> <code>${escapeHtml(route.route)}</code></h2>` + heapCurveSvg(route.samples, color) + `<p class="curve">heap ${curve} MB \xB7 ${(route.growthPer1000Requests / MB).toFixed(2)} MB/1000 req</p>` + withdrawn + warnings + (findingRows === "" ? "" : `<table><tr><th>kind</th><th>type</th><th>node</th><th>retained</th><th>owner</th></tr>${findingRows}</table>`) + `</section>`;