next-leak 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xabier Lameiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# next-leak
+
+[![npm](https://img.shields.io/npm/v/next-leak.svg)](https://www.npmjs.com/package/next-leak)
+[![CI](https://github.com/xabierlameiro/next-leak/actions/workflows/ci.yml/badge.svg)](https://github.com/xabierlameiro/next-leak/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/next-leak.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/next-leak.svg)](./LICENSE)
+
+> Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.
+
+```
+$ npx next-leak . --quick
+
+  ✖ /api/heap  leak  (+4.70 MB/1000 req)
+    heap 28.7 → 40.3 → 59.0 → 75.8 → 75.9 → 101.2 → 101.2 → 139.0 → 139.0 MB
+      ↳ grown [object] Array 112.5 MB — TimeoutsManager#object[.resources]
+        <- system / Context#object[.timeoutsManager] <- destroy#closure[.context]
+        <- ResourceManager#object[.properties] <- IntervalsManager#object[.map]
+
+  ✔ /            stable  (+0.02 MB/1000 req)  heap 40.9 → 35.3 → 35.3 → 35.4 MB
+  ✔ /convenio    stable  (+0.02 MB/1000 req)  heap 36.3 → 37.0 → 37.1 → 37.1 MB
+```
+
+That first line is a real run against the reproduction for
+[vercel/next.js#95094](https://github.com/vercel/next.js/issues/95094), an open
+Next.js issue: the sandbox's `TimeoutsManager` never releases timeout ids from
+middleware. next-leak found the growth, the retaining object and the chain that
+holds it — without being told what to look for.
+
+**Verified against real, open Next.js issues**, not synthetic fixtures:
+
+| Issue | What it is | Result |
+|---|---|---|
+| [#95094](https://github.com/vercel/next.js/issues/95094) | Middleware `setTimeout` ids retained by the sandbox | **Reproduced** · mechanism named · 112 MB retained |
+| [#94890](https://github.com/vercel/next.js/issues/94890) | Router LRU cache doesn't count its keys | **Reproduced** · 26.7 → 71.9 MB |
+| [#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) |
+
+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.
+
+Three possible answers, all valuable:
+
+1. **You don't have a leak** — the spike is transient and drains during idle (the most common case).
+2. **The leak is in your code (or a dependency)** — named down to the source file when possible.
+3. **It looks like framework internals** — with a ready-to-file issue draft.
+
+## Quickstart
+
+```bash
+# 1. Your app must build with standalone output — in next.config:
+#      output: "standalone"
+next build
+
+# 2. Measure it
+npx next-leak .
+```
+
+For each discovered route, in a fresh process, it runs the validated ritual:
+
+```
+warm-up → forced GC → baseline snapshot → [load → idle → GC → sample] ×3 → snapshot
+```
+
+The verdict comes from the **shape of the post-GC curve**: retained heap that keeps growing every cycle is a leak; growth that flattens is warm-up. Absolute sizes are noise; shapes are robust.
+
+## Options
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--routes <list>` | all | Only measure these routes (comma-separated templates or prefixes) |
+| `--cycles <n>` | 3 | Load cycles per route (min 3) |
+| `--requests <n>` | 5000 | Requests per cycle |
+| `--connections <n>` | 100 | Concurrent connections |
+| `--idle <seconds>` | 30 | **Maximum** wait before each sample; the run continues as soon as the heap settles |
+| `--quick` | off | Fast preset (2000 requests × 4 cycles, 8s idle) — the exact profile the real-app validation ran with. Explicit flags override it |
+| `--diff-all` | off | Diff snapshots for stable routes too |
+| `--output <dir>` | `<app>/.next-leak` | Where runs are written |
+
+Dynamic routes need sample params in `next-leak.config.json` in your app dir:
+
+```json
+{
+  "params": { "lang": "en" },
+  "routes": { "/products/[id]": { "id": "42" } },
+  "headers": { "accept-encoding": "gzip, br", "cookie": "session=..." }
+}
+```
+
+- **`headers`** are sent with every request. Real traffic is not header-less:
+  compression, sessions and auth change which code paths run, and some leaks
+  only live on those paths.
+- **`{n}` inside a param value** makes every request use a *unique* URL
+  (`{ "id": "item-{n}" }` → `/logs/item-1`, `/logs/item-2`, …). Leaks keyed by
+  URL — route caches, LRUs, bot traffic with varied tails — are invisible
+  without it.
+- **`query`** appends a query string per route template
+  (`{ "/api/payload/[slug]": "weightKb=2048" }`).
+- **`abandonAfterMs`** makes clients hang up before the response arrives, the
+  way closed tabs, load-balancer timeouts and bots do. Some leaks only exist
+  on that path (`ServerResponse` retained after an early disconnect). Requests
+  abandoned on purpose are not counted as failures.
+
+`run.json` records what every load phase actually did — requests sent,
+2xx, abandoned — so a run can be audited instead of trusted.
+
+Before measuring, the CLI prints a duration estimate — a 60-route app under defaults is **hours**; narrow with `--routes` for iteration.
+
+## Reading the verdicts
+
+- **`stable`** — done, stop hunting. The report proves it. If the heap is flat
+  but RSS keeps climbing, the report says so explicitly: that is an allocator,
+  external-buffer or fragmentation problem, not a JS-heap leak.
+- **`leak`** — the report names the culprit when attribution resolves: your file (`culprit: src/app/x/page.tsx (your code)`), a dependency (package name), or framework internals. An `ISSUE-<route>.md` draft is generated; if the leak is app-owned, the draft tells you **not** to file it upstream.
+- **`inconclusive`** — sustained sub-threshold growth: measure longer. The CLI prints the exact re-run command (`--routes <those> --cycles 6`).
+- **`failed`** — the route errored under load (auth redirects, POST-only endpoints). >1% non-2xx aborts measurement instead of measuring garbage. That's by design.
+
+## The tool grades its own measurement
+
+A leak detector is an instrument, and a miscalibrated instrument doesn't fail
+loudly — it reports confident, wrong numbers. So every run is audited against
+its own evidence, and anything that undermines a verdict is printed next to it:
+
+```
+✖ /api/items  leak  (+3.10 MB/1000 req)  heap 28.4 MB → 41.9 MB → …
+    ⚠ low confidence: cycle 2 landed 4310 of 5000 requests (86.2%) — the route
+      saw less traffic than reported
+```
+
+What gets checked: whether the heap actually held still before each sample,
+whether the requests you asked for really landed, whether an early-disconnect
+run disconnected anything, whether one cycle dominates the average, and
+whether the growth barely clears the noise floor.
+
+When the run didn't observe what a `leak` verdict requires — the heap never
+settled, or an abandonment run abandoned nothing — the verdict is **withdrawn**
+and reported as `inconclusive`, with what was measured still on the record. A
+withdrawn verdict produces no `ISSUE-*.md` draft: only a verdict the evidence
+supports is worth pasting into someone else's tracker. Caveats that don't
+overturn a verdict still travel with the draft, under *Measurement caveats*.
+
+Stable verdicts are never withdrawn. Quietly missing a leak costs you less
+than a false accusation, and the warnings are on the report either way.
+
+## Every run leaves evidence
+
+```
+.next-leak/<timestamp>/
+├── report.html        # heap curves per route — self-contained, opens offline
+├── ISSUE-<route>.md   # issue draft per leaking route (Next.js bug-template shape)
+├── run.json           # everything, machine-readable: environment, per-phase
+│                     # timings, heap AND RSS samples per cycle, what each
+│                     # load phase actually did, and the confidence audit
+└── <nn>-<route>/      # raw baseline/after .heapsnapshot per route
+```
+
+Snapshots are the ground truth: load them in Chrome DevTools (Memory → Load → Comparison) and check every claim yourself. Runs accumulate — each keeps its snapshots (tens of MB per route); delete old timestamp folders when done.
+
+## Why not just use…
+
+| | What it gives you | Where it stops |
+|---|---|---|
+| **Chrome DevTools** | The ground truth: two snapshots and a comparison view | You reproduce the load, force the GC, pick the moments and read the retainers yourself. Doing it *correctly* is the hard part |
+| **[memlab](https://github.com/facebook/memlab)** | A superb heap-analysis engine — next-leak **uses it** to parse snapshots | It is built around browser scenarios you script. It does not drive HTTP load against your routes, and it knows nothing about Next.js route manifests or your bundle's source maps |
+| **[clinic.js](https://github.com/clinicjs/node-clinic)** | Broad Node performance profiling | [Its own README](https://github.com/clinicjs/node-clinic#readme) states it is no longer actively maintained |
+| **`--inspect` + manual snapshots** | Full control | Same as DevTools, plus you must keep the process, the load and the snapshots in sync by hand |
+
+What next-leak adds is not analysis — it is **the controlled experiment around
+it**: a fresh process per route, warm-up before the baseline, forced GC and an
+adaptive idle before every sample, an audit of whether the load it claims to
+have sent actually landed, and a verdict from the curve's shape rather than
+absolute sizes. Then it maps the retaining objects back to *your* source files
+through the build's source maps.
+
+## Scope and limits (read before filing issues)
+
+- **Supported:** App Router · `output: "standalone"` · Node ≥ 22 · Linux/macOS. Pages Router, non-standalone, and Windows are rejected with a clear message.
+- **Architectures:** verified on **arm64 and x64** (linux/amd64 in Docker) — same app, same parameters, same verdicts.
+- **Attribution** (naming the file) needs a Turbopack build with server sourcemaps — the Next 15+ default. On webpack builds the registry is empty by design and findings degrade to `unattributed` with raw retainer chains; measurement itself does not depend on it. Note that `output: "standalone"` + `--webpack` produced a bundle that could not start at all on `16.3.0-canary.90` (missing `@swc/helpers`), independently of this tool.
+- Empirically validated on Next **15.5.4, 16.0.x, 16.1.5, 16.2.x and 16.3-canary** (incl. Sentry, OpenTelemetry, PPR and i18n apps), against real reproductions from open issues. The contracts it relies on are stable since Next 13–14, but older versions are untested.
+- Borderline routes can flip between `stable`/`leak` across runs — more cycles resolves this.
+- The measured app runs with its real environment: routes that call external services will call them under load. Scope with `--routes` and moderate `--requests` accordingly.
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck && pnpm test && pnpm build
+pnpm pack:smoke      # release gate: installs the real tarball and measures the fixture app
+pnpm test:mutation   # Stryker — slow; run before releases, weekly in CI
+```
+
+CI runs typecheck, tests, build, `pnpm audit --prod` and the pack smoke on
+Node 22 and 24; mutation testing runs weekly and uploads its report.
+
+## License
+
+MIT

package/dist/abandon-load.d.ts

@@ -0,0 +1,33 @@
+export type AbandonPhaseOptions = {
+    url: string;
+    amount: number;
+    connections: number;
+    /** Destroy the socket this many ms after sending the request. */
+    abandonAfterMs: number;
+    headers?: Record<string, string>;
+};
+export type AbandonPhaseResult = {
+    sent: number;
+    abandoned: number;
+    /**
+     * Abandonments where the server had already started responding. Only these
+     * exercise mid-stream teardown; cutting before the first byte tests a
+     * different path (the server may never have begun rendering).
+     */
+    abandonedMidStream: number;
+    completed: number;
+    errors: number;
+};
+/**
+ * Sends requests and hangs up before the response arrives.
+ *
+ * autocannon cannot express this: its `timeout` is in whole seconds, so
+ * against a route answering in milliseconds nothing is ever abandoned. Yet
+ * several real leaks live exactly on that path — vercel/next.js#89091 traces
+ * `ServerResponse` retention to an early disconnect, which only happens when
+ * a client goes away mid-flight (closed tabs, load-balancer timeouts, bots).
+ *
+ * Raw sockets keep this honest: write the request, wait `abandonAfterMs`,
+ * destroy the socket. No response is read.
+ */
+export declare function runAbandonPhase(options: AbandonPhaseOptions): Promise<AbandonPhaseResult>;

package/dist/attribution.d.ts

@@ -0,0 +1,40 @@
+import type { HeapDiff, NodeFinding } from "./heap-diff.js";
+import type { ModuleRegistry } from "./module-registry.js";
+export type Owner = "app" | "dependency" | "framework" | "unattributed";
+export type FindingAttribution = {
+    owner: Owner;
+    /** Display path relative to the project (e.g. `src/app/leaky/page.tsx`). */
+    source: string | null;
+    packageName: string | null;
+};
+export type RouteAttribution = FindingAttribution & {
+    /** Share of attributed retained bytes held by the winning owner+source. */
+    dominance: number;
+};
+/**
+ * Classifies one bundler source path. Handles both real-world dialects seen
+ * in Turbopack builds: `[project]/…` prefixes (Next 16.0) and URL-encoded
+ * relative paths like `../../../node_modules/.pnpm/%40scope%2Bpkg@1/…`
+ * (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
+ * the user's page module), the most user-actionable owner wins: app over
+ * dependency over framework. Ties keep chain order (closest to the leak).
+ */
+export declare function attributeFinding(finding: Pick<NodeFinding, "moduleIds" | "retainerChain">, registry: ModuleRegistry): FindingAttribution;
+export type AttributedDiff = {
+    /** Aligned with `[...diff.grownNodes, ...diff.newNodes]`. */
+    findings: FindingAttribution[];
+    route: RouteAttribution;
+};
+/**
+ * Attributes every finding and derives the route-level verdict: the
+ * owner+source group holding the most attributed retained bytes wins;
+ * with nothing attributed the route stays `unattributed`.
+ */
+export declare function attributeDiff(diff: HeapDiff, registry: ModuleRegistry): AttributedDiff;

package/dist/bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap.js

@@ -0,0 +1,100 @@
+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";
+
+// src/bootstrap.ts
+import { mkdir, writeFile } from "fs/promises";
+import path2 from "path";
+
+// src/control-server.ts
+import http from "http";
+import path from "path";
+import { writeHeapSnapshot } from "v8";
+var g = globalThis;
+var tick = () => new Promise((resolve) => setImmediate(resolve));
+async function forceGc(passes = 3) {
+  if (typeof g.gc !== "function") {
+    return false;
+  }
+  for (let i = 0; i < passes; i += 1) {
+    g.gc();
+    await tick();
+  }
+  return true;
+}
+function sampleMemory(gcExposed) {
+  const usage = process.memoryUsage();
+  return {
+    gcExposed,
+    heapUsed: usage.heapUsed,
+    rss: usage.rss,
+    external: usage.external,
+    arrayBuffers: usage.arrayBuffers
+  };
+}
+async function startControlServer(options) {
+  const write = options.writeSnapshot ?? writeHeapSnapshot;
+  const server = http.createServer((request, response) => {
+    void handle(request, response);
+  });
+  async function handle(request, response) {
+    const url = new URL(request.url ?? "/", "http://control.local");
+    const respond = (status, body) => {
+      response.writeHead(status, { "content-type": "application/json" });
+      response.end(JSON.stringify(body));
+    };
+    try {
+      if (url.pathname === "/gc") {
+        const gcExposed = await forceGc();
+        respond(200, sampleMemory(gcExposed));
+        return;
+      }
+      if (url.pathname === "/snapshot") {
+        const name = url.searchParams.get("name");
+        if (name === null || name === "") {
+          respond(400, { error: "missing ?name=<label>" });
+          return;
+        }
+        const gcExposed = await forceGc();
+        const sample = sampleMemory(gcExposed);
+        const file = write(
+          path.join(options.snapshotDir, `${path.basename(name)}.heapsnapshot`)
+        );
+        respond(200, { file, sample });
+        return;
+      }
+      respond(404, { error: `unknown path ${url.pathname}` });
+    } catch (cause) {
+      respond(500, { error: cause instanceof Error ? cause.message : String(cause) });
+    }
+  }
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  server.unref();
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("control server has no bound port");
+  }
+  return {
+    port: address.port,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+    })
+  };
+}
+
+// src/bootstrap.ts
+var workDir = process.env["NEXT_LEAK_DIR"];
+if (workDir !== void 0 && workDir !== "") {
+  try {
+    await mkdir(workDir, { recursive: true });
+    const server = await startControlServer({ snapshotDir: workDir });
+    await writeFile(
+      path2.join(workDir, `control-${process.pid}.json`),
+      JSON.stringify({ port: server.port, pid: process.pid })
+    );
+  } catch (cause) {
+    console.error(`[next-leak] control channel failed to start: ${String(cause)}`);
+  }
+}

package/dist/chunk-4BMPC45G.js

@@ -0,0 +1,81 @@
+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";
+
+// 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;");
+}
+function heapCurveSvg(samples, color) {
+  const width = 320;
+  const height = 96;
+  const pad = 8;
+  const min = Math.min(...samples);
+  const max = Math.max(...samples);
+  const span = Math.max(max - min, 1);
+  const points = samples.map((sample, index) => {
+    const x = pad + index * (width - 2 * pad) / Math.max(samples.length - 1, 1);
+    const y = height - pad - (sample - min) * (height - 2 * pad) / span;
+    return `${x.toFixed(1)},${y.toFixed(1)}`;
+  }).join(" ");
+  const labels = `<text x="${pad}" y="10" class="axis">${(max / MB).toFixed(1)} MB</text><text x="${pad}" y="${height - 1}" class="axis">${(min / MB).toFixed(1)} MB</text>`;
+  return `<svg viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img">${labels}<polyline points="${points}" fill="none" stroke="${color}" stroke-width="2"/>` + samples.map((sample, index) => {
+    const x = pad + index * (width - 2 * pad) / Math.max(samples.length - 1, 1);
+    const y = height - pad - (sample - min) * (height - 2 * pad) / span;
+    return `<circle cx="${x.toFixed(1)}" cy="${y.toFixed(1)}" r="2.5" fill="${color}"/>`;
+  }).join("") + `</svg>`;
+}
+function measuredSection(route) {
+  if (route.status !== "measured") {
+    return "";
+  }
+  const verdict = effectiveVerdict(route);
+  const color = VERDICT_COLOR[verdict];
+  const withdrawn = route.confidence.supersededVerdict === void 0 ? "" : `<p class="warn">Measured <strong>${route.trend.verdict}</strong>, withdrawn: the run did not observe what that verdict needs.</p>`;
+  const warnings = route.confidence.warnings.length === 0 ? "" : `<ul class="warn">${route.confidence.warnings.map((warning) => `<li>${escapeHtml(warning.detail)}</li>`).join("")}</ul>`;
+  const curve = route.samples.map((sample) => (sample / MB).toFixed(1)).join(" \u2192 ");
+  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)})` : ""}`;
+    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>`;
+}
+function renderHtmlReport(run) {
+  const measured = run.routes.filter((route) => route.status === "measured");
+  const skipped = run.routes.filter((route) => route.status === "skipped");
+  const failed = run.routes.filter((route) => route.status === "failed");
+  const environment = run.environment;
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>next-leak \u2014 ${escapeHtml(run.appDir)}</title>
+<style>
+body{font:14px/1.5 system-ui,sans-serif;max-width:760px;margin:2rem auto;padding:0 1rem;color:#222}
+h1{font-size:1.3rem} h2{font-size:1rem;margin:1.5rem 0 .3rem}
+.badge{color:#fff;border-radius:4px;padding:1px 8px;font-size:.8rem}
+table{border-collapse:collapse;font-size:.85rem;margin:.5rem 0}
+td,th{border:1px solid #ddd;padding:2px 8px;text-align:left}
+.curve,.meta{color:#555;font-size:.85rem} .axis{font-size:9px;fill:#888}
+.warn{color:#8a5a00;background:#fff8e6;border-left:3px solid #e67e22;padding:.4rem .7rem;font-size:.85rem}
+code{background:#f4f4f4;padding:0 4px;border-radius:3px}
+</style></head><body>
+<h1>next-leak report</h1>
+<p class="meta">${escapeHtml(run.appDir)} \xB7 ${escapeHtml(run.startedAt)} \xB7 node ${escapeHtml(
+    environment.nodeVersion
+  )} \xB7 ${escapeHtml(environment.platform)}/${escapeHtml(environment.arch)} \xB7 next ${escapeHtml(
+    environment.nextVersion ?? "unknown"
+  )} \xB7 next-leak ${escapeHtml(environment.nextLeakVersion)}</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>`}
+<p class="meta">Raw snapshots and run.json live next to this file \u2014 verify in Chrome DevTools \u2192 Memory \u2192 Load.</p>
+</body></html>`;
+}
+
+export {
+  renderHtmlReport
+};

package/dist/chunk-5K4WEMIS.js

@@ -0,0 +1,88 @@
+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/issue-report.ts
+import path from "path";
+var MB = 1024 * 1024;
+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}` : ""}`;
+    return `- **${finding.kind}** \`[${finding.nodeType}] ${finding.name}\` ${(finding.retainedBytes / MB).toFixed(2)} MB retained (${owner})
+  - retainers: \`${finding.retainerChain || "(none)"}\``;
+  }).join("\n");
+}
+function renderIssueMarkdown(route, run) {
+  const environment = run.environment;
+  const parameters = run.parameters;
+  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.
+
+` : "";
+  const caveats = route.confidence.warnings.length === 0 ? "" : `
+### Measurement caveats
+
+next-leak audits its own run and reports these limits. They do not overturn the verdict above, but they bound how much weight it carries:
+
+` + route.confidence.warnings.map((warning) => `- ${warning.detail}`).join("\n") + `
+`;
+  const curve = route.samples.map((sample) => (sample / MB).toFixed(1)).join(" \u2192 ");
+  const deltas = route.trend.deltas.map((delta) => `+${(delta / MB).toFixed(2)}`).join(", ");
+  const signatures = route.signatures.map(
+    (signature) => `- ${signature.historical ? "(historical) " : ""}${signature.title} \u2014 ${signature.issue}`
+  ).join("\n");
+  return `${preamble}# Memory leak on route \`${route.route}\`
+
+Report generated by \`next-leak\` \u2014 every number below is reproducible from
+the raw heap snapshots referenced at the bottom.
+
+### Provide environment information
+
+\`\`\`
+Node.js: ${environment.nodeVersion}
+OS: ${environment.platform} ${environment.arch}${environment.cpuModel ? ` (${environment.cpuModel})` : ""}
+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
+\`\`\`
+
+### To Reproduce
+
+1. Build the app with \`output: "standalone"\` and run:
+   \`\`\`
+   npx next-leak <app-dir>
+   \`\`\`
+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.
+
+### Current vs. Expected behavior
+
+**Current:** retained heap after forced GC keeps growing every cycle \u2014
+${curve} MB (per-cycle deltas ${deltas} MB), \u2248 **${(route.growthPer1000Requests / MB).toFixed(2)} MB per 1000 requests**.
+The first cycle is excluded from the verdict (engine warm-up).
+
+**Expected:** retained heap flattens after warm-up (plateau), as measured on this app's healthy routes.
+
+### Heap evidence
+
+${evidenceRows(route) || "- (no findings above thresholds)"}
+${signatures === "" ? "" : `
+**Matched known causes:**
+${signatures}
+`}${caveats}
+### Verify it yourself
+
+Raw snapshots (Chrome DevTools \u2192 Memory \u2192 Load, compare baseline vs after):
+
+- \`${path.basename(route.baselineSnapshot)}\` / \`${path.basename(route.afterSnapshot)}\` in \`${run.workDir}\`
+- machine-readable data: \`run.json\`, curves: \`report.html\`
+`;
+}
+
+export {
+  renderIssueMarkdown
+};