next-leak 0.12.1 → 0.12.2

package/dist/build-attribution.d.ts

@@ -15,6 +15,26 @@ export type BuildAttribution = {
     baselineFile: string;
     afterFile: string;
 };
+/**
+ * Why a run that asked for attribution came back without one.
+ *
+ * An absent section and a failed diff read the same in a report, and they are
+ * opposite findings: one says nobody asked what the worker retained, the other
+ * says the question was asked and the evidence could not be read. The build
+ * path fails this way hardest on the builds worth measuring — a snapshot past
+ * roughly a gigabyte of worker rss cannot be parsed back, so the bigger the
+ * build grew, the likelier the report says nothing about what grew.
+ */
+export type BuildAttributionGap = {
+    /**
+     * `capture-missed`: the run was told to capture and never got a usable pair.
+     * `snapshot-unreadable`: the pair exists and the diff refused it.
+     */
+    reason: "capture-missed" | "snapshot-unreadable";
+    detail: string;
+};
+/** Narrows the outcome of `attributeBuildCapture`. */
+export declare function isAttributionGap(outcome: BuildAttribution | BuildAttributionGap | null): outcome is BuildAttributionGap;
 export type BuildAttributionDeps = {
     diff: typeof diffSnapshotFiles;
     registry: typeof extractModuleRegistry;
@@ -22,12 +42,14 @@ export type BuildAttributionDeps = {
 /**
  * Names what a build's worker retained, from the pair the run captured.
  *
- * Returns null rather than throwing on every failure path. A build measurement
- * stands on its curve and its verdict; this is an addition to the report, and
- * an addition that can fail must not be able to take the report with it.
+ * Never throws on a failure path. A build measurement stands on its curve and
+ * its verdict; this is an addition to the report, and an addition that can
+ * fail must not be able to take the report with it. It returns a gap instead,
+ * so the report can tell a question nobody asked from one it could not answer.
+ * Null is reserved for the run that never asked.
  *
  * The registry is read from `.next/server` *after* the build, never during it:
  * a half-written chunk can resolve a module id to the wrong source, and naming
  * the wrong owner confidently is worse than naming none.
  */
-export declare function attributeBuildCapture(result: BuildRunResult, appDir: string, onProgress?: (message: string) => void, deps?: BuildAttributionDeps): Promise<BuildAttribution | null>;
+export declare function attributeBuildCapture(result: BuildRunResult, appDir: string, onProgress?: (message: string) => void, deps?: BuildAttributionDeps): Promise<BuildAttribution | BuildAttributionGap | null>;

package/dist/build-report.d.ts

@@ -1,4 +1,4 @@
-import type { BuildAttribution } from "./build-attribution.js";
+import { type BuildAttribution, type BuildAttributionGap } from "./build-attribution.js";
 import type { BuildRunResult } from "./build-run.js";
 /**
  * Renders the build report.
@@ -9,4 +9,4 @@ import type { BuildRunResult } from "./build-run.js";
  * still the honest axis here — it is what a CI runner's limit is enforced
  * against and what the OOM killer reads.
  */
-export declare function formatBuildReport(result: BuildRunResult, attribution?: BuildAttribution | null): string;
+export declare function formatBuildReport(result: BuildRunResult, attribution?: BuildAttribution | BuildAttributionGap | null): string;

package/dist/build-run.d.ts

@@ -51,6 +51,15 @@ export type BuildRunResult = {
      * produced whether or not capture worked.
      */
     capture: BuildCapture | null;
+    /**
+     * Whether this run was asked to capture at all. Without it a null `capture`
+     * is ambiguous — nobody asked, or it was asked and missed — and the report
+     * has to choose between staying silent on a lost measurement and nagging
+     * every run that never wanted one.
+     */
+    captureRequested: boolean;
+    /** How far capture got before giving up, when it was requested and missed. */
+    captureFailure: string | null;
     strippedCapWarning: string | null;
     exitCode: number | null;
     output: string;

package/dist/{chunk-L5KWU2RU.js → chunk-HDCOHSBY.js}

@@ -8,7 +8,7 @@ import {
   resolveCycles,
   warrantsIssueDraft,
   withdrawnByDisagreement
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import {
   assessPeakPressure,
   assessPressureVerdict,
@@ -93182,15 +93182,15 @@ async function jsFilesUnder(dir) {
 async function extractModuleRegistry(nextServerDir) {
   const registry = /* @__PURE__ */ new Map();
   for (const file of await jsFilesUnder(nextServerDir)) {
-    let code;
-    let map;
+    let modules;
     try {
-      code = await readFile(file, "utf8");
-      map = JSON.parse(await readFile(`${file}.map`, "utf8"));
+      const code = await readFile(file, "utf8");
+      const map = JSON.parse(await readFile(`${file}.map`, "utf8"));
+      modules = extractChunkModules(code, map);
     } catch {
       continue;
     }
-    for (const [id, source] of extractChunkModules(code, map)) {
+    for (const [id, source] of modules) {
       if (!registry.has(id)) {
         registry.set(id, source);
       }
@@ -94812,7 +94812,7 @@ async function runSelfCheck(options, deps = defaultDeps2) {
       passed,
       verdict: result.trend.verdict,
       growthPer1000Requests,
-      summary: passed ? `harness verified: the planted leak was detected at ${rate}` : `harness NOT verified: a leak of ${PLANTED_LEAK_BYTES_PER_REQUEST} bytes per request came back ${result.trend.verdict} at ${rate}. Verdicts measured in this environment cannot be trusted \u2014 a flat curve here means the measurement is not working, not that nothing leaks`
+      summary: passed ? `harness detected the planted leak at ${rate} \u2014 it responds to retention in this environment; the routes' own figures are not checked by this` : `harness NOT verified: a leak of ${PLANTED_LEAK_BYTES_PER_REQUEST} bytes per request came back ${result.trend.verdict} at ${rate}. Verdicts measured in this environment cannot be trusted \u2014 a flat curve here means the measurement is not working, not that nothing leaks`
     };
   } finally {
     await rm(dir, { recursive: true, force: true });
@@ -95187,7 +95187,9 @@ function harnessLine(report) {
   const measured = report.routes.filter((route) => route.status === "measured");
   if (report.harness.verified) {
     const rate = formatGrowth(report.harness.growthPer1000Requests);
-    return [`harness verified this session: a planted leak measured ${rate}`];
+    return [
+      `harness detected a planted leak this session at ${rate} \u2014 it can see retention here; that is not a check on the figures above`
+    ];
   }
   const allStable = measured.length > 0 && measured.every((route) => effectiveVerdict(route) === "stable");
   if (!allStable) {
@@ -95622,8 +95624,8 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-DLKFB3IU.js");
-  const { renderIssueMarkdown } = await import("./issue-report-OALZZLVR.js");
+  const { renderHtmlReport } = await import("./html-report-MSEC3ZI4.js");
+  const { renderIssueMarkdown } = await import("./issue-report-JXVLP7CV.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
       const file = path9.join(workDir, `ISSUE-${routeSlug(route.route)}.md`);

package/dist/{chunk-UU4RXOZO.js → chunk-QUFL2FXU.js}

@@ -40,7 +40,7 @@ function isSaturating(deltas, minGrowth) {
   if (first === void 0 || last === void 0 || first < minGrowth) {
     return false;
   }
-  if (!deltas.every((delta) => delta > 0)) {
+  if (!hasArrivedWithoutResuming(deltas, minGrowth)) {
     return false;
   }
   if (last > first * SATURATION_MAX_FINAL_RATIO) {
@@ -48,6 +48,17 @@ function isSaturating(deltas, minGrowth) {
   }
   return isHeadingDown(deltas);
 }
+function hasArrivedWithoutResuming(deltas, minGrowth) {
+  const stop = deltas.findIndex((delta) => delta <= 0);
+  if (stop === -1) {
+    return true;
+  }
+  const approach = deltas[stop - 1];
+  if (approach === void 0 || approach >= minGrowth) {
+    return false;
+  }
+  return deltas.slice(stop).every((delta) => delta < minGrowth);
+}
 function isHeadingDown(deltas) {
   const midpoint = Math.floor(deltas.length / 2);
   const head = deltas.slice(0, midpoint);

package/dist/{chunk-YPVBX3QA.js → chunk-ULTMNWRX.js}

@@ -8,27 +8,46 @@ import {
 // src/issue-report.ts
 import path from "path";
 var MB = 1024 * 1024;
+function codeSpan(text) {
+  const flat = text.replaceAll(/[\r\n]+/g, " ");
+  const longestRun = Math.max(0, ...[...flat.matchAll(/`+/g)].map((run) => run[0].length));
+  const fence = "`".repeat(longestRun + 1);
+  const padding = flat.startsWith("`") || flat.endsWith("`") ? " " : "";
+  return `${fence}${padding}${flat}${padding}${fence}`;
+}
+function publicWorkDir(run) {
+  const relative = path.relative(run.appDir, run.workDir);
+  return relative.startsWith("..") || path.isAbsolute(relative) ? path.basename(run.workDir) : relative;
+}
 function ownerLabel(attribution) {
   if (attribution === void 0 || attribution.owner === "unattributed") {
     return "unattributed";
   }
-  const source = attribution.source ? ` \u2014 \`${attribution.source}\`` : "";
+  const source = attribution.source ? ` \u2014 ${codeSpan(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 `**your own code** (${codeSpan(culprit?.source ?? "app code")})`;
   }
   return `the dependency **${culprit?.packageName ?? "a dependency"}**`;
 }
+function missingEvidence(route) {
+  if (route.attributionGap === void 0) {
+    return "- (no findings above thresholds)";
+  }
+  const cause = route.attributionGap.reason === "snapshot-unavailable" ? "the final heap snapshot was never taken" : "the heap snapshots could not be read";
+  return `- **Attribution unavailable** \u2014 ${cause}, so this run cannot name what retains the memory. This is not a finding that nothing grew: the diff was never computed. The growth figure above is unaffected.
+  - ${route.attributionGap.detail}`;
+}
 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 = ownerLabel(attribution);
-    return `- **${finding.kind}** \`[${finding.nodeType}] ${finding.name}\` ${(finding.retainedBytes / MB).toFixed(2)} MB retained (${owner})
-  - retainers: \`${finding.retainerChain || "(none)"}\``;
+    return `- **${finding.kind}** ${codeSpan(`[${finding.nodeType}] ${finding.name}`)} ${(finding.retainedBytes / MB).toFixed(2)} MB retained (${owner})
+  - retainers: ${codeSpan(finding.retainerChain || "(none)")}`;
   }).join("\n");
 }
 function renderIssueMarkdown(route, run) {
@@ -71,7 +90,7 @@ Sampled during the load phases, without forcing collection: ${describePeakPressu
   const signatures = route.signatures.map(
     (signature) => `- ${signature.historical ? "(historical) " : ""}${signature.title} \u2014 ${signature.issue}`
   ).join("\n");
-  return `${preamble}${cacheDisclosure}# Memory leak on route \`${route.route}\`
+  return `${preamble}${cacheDisclosure}# Memory leak on route ${codeSpan(route.route)}
 
 Report generated by \`next-leak\` \u2014 every number below is reproducible from
 the raw heap snapshots referenced at the bottom.
@@ -93,7 +112,7 @@ Deployment: output "standalone", node --expose-gc --max-old-space-size=${paramet
    \`\`\`
    npx next-leak <app-dir>
    \`\`\`
-2. next-leak boots \`.next/standalone/server.js\` in a fresh process per route and runs, against \`${route.requestPath}\`:
+2. next-leak boots \`.next/standalone/server.js\` in a fresh process per route and runs, against ${codeSpan(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
@@ -109,7 +128,7 @@ The first cycle is excluded from the verdict (engine warm-up).
 
 ### Heap evidence
 
-${evidenceRows(route) || "- (no findings above thresholds)"}
+${evidenceRows(route) || missingEvidence(route)}
 ${signatures === "" ? "" : `
 **Matched known causes:**
 ${signatures}
@@ -118,7 +137,7 @@ ${signatures}
 
 Raw snapshots (Chrome DevTools \u2192 Memory \u2192 Load, compare baseline vs after):
 
-- \`${path.basename(route.baselineSnapshot)}\` / \`${path.basename(route.afterSnapshot)}\` in \`${run.workDir}\`
+- ${codeSpan(path.basename(route.baselineSnapshot))} / ${codeSpan(path.basename(route.afterSnapshot))} in ${codeSpan(publicWorkDir(run))}
 - machine-readable data: \`run.json\`, curves: \`report.html\`
 `;
 }

package/dist/{chunk-G2777DKL.js → chunk-VKPGB5MG.js}

@@ -2,7 +2,7 @@ import { createRequire as __nextLeakCreateRequire } from 'node:module';import {
 import {
   effectiveVerdict,
   withdrawnByDisagreement
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import {
   assessPeakPressure,
   describePeakPressure,
@@ -69,6 +69,13 @@ function peakBlock(route, parameters) {
   const note = pressure === null ? "" : `<p class="warn">Peak pressure: ${escapeHtml(describePeakPressure(pressure))}</p>`;
   return note + `<table><tr><th>peak during</th><th>heap</th><th>external</th><th>arrayBuffers</th><th>rss</th></tr>${peakRows}</table>`;
 }
+function attributionGapBlock(route) {
+  if (route.status !== "measured" || route.attributionGap === void 0) {
+    return "";
+  }
+  const cause = route.attributionGap.reason === "snapshot-unavailable" ? "the final heap snapshot was never taken" : "the heap snapshots could not be read";
+  return `<p class="warn">No attribution: ${cause}, so this run cannot name what retains the memory. The curve above is unaffected. ${escapeHtml(route.attributionGap.detail)}</p>`;
+}
 function measuredSection(route, parameters) {
   if (route.status !== "measured") {
     return "";
@@ -84,7 +91,7 @@ function measuredSection(route, parameters) {
     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 + peakBlock(route, parameters) + (findingRows === "" ? "" : `<table><tr><th>kind</th><th>type</th><th>node</th><th>retained</th><th>owner</th></tr>${findingRows}</table>`) + `</section>`;
+  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 + peakBlock(route, parameters) + (findingRows === "" ? attributionGapBlock(route) : `<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");

package/dist/cli.js

@@ -22,10 +22,10 @@ import {
   runSelfCheck,
   unregisterChild,
   validateTarget
-} from "./chunk-L5KWU2RU.js";
+} from "./chunk-HDCOHSBY.js";
 import {
   classifyTrend
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 
@@ -151,6 +151,9 @@ function discardPendingSnapshotsSync() {
 }
 
 // src/build-attribution.ts
+function isAttributionGap(outcome) {
+  return outcome !== null && "reason" in outcome;
+}
 var defaultDeps = {
   diff: diffSnapshotFiles,
   registry: extractModuleRegistry
@@ -159,17 +162,19 @@ async function attributeBuildCapture(result, appDir, onProgress = () => {
 }, deps = defaultDeps) {
   const capture = result.capture;
   if (capture === null) {
-    return null;
+    return result.captureRequested ? {
+      reason: "capture-missed",
+      detail: result.captureFailure ?? "the run never captured a usable snapshot pair from the worker"
+    } : null;
   }
   onProgress(`diffing what worker ${capture.pid} retained`);
   let diff;
   try {
     diff = await deps.diff(capture.files.baselineFile, capture.files.afterFile);
   } catch (cause) {
-    onProgress(
-      cause instanceof SnapshotError ? `no attribution: ${cause.message}` : `no attribution: the snapshot pair could not be diffed`
-    );
-    return null;
+    const detail = cause instanceof SnapshotError ? cause.message : "the snapshot pair could not be diffed";
+    onProgress(`no attribution: ${detail}`);
+    return { reason: "snapshot-unreadable", detail };
   }
   const registry = await deps.registry(path2.join(appDir, ".next", "server"));
   return {
@@ -212,6 +217,13 @@ function attributionLines(attribution) {
   if (attribution === null) {
     return [];
   }
+  if (isAttributionGap(attribution)) {
+    return [
+      "",
+      `  no attribution: ${attribution.detail}.`,
+      `  This does not say nothing grew \u2014 the comparison was never made.`
+    ];
+  }
   const { diff, attributed, bracketed } = attribution;
   const findings = [...diff.grownNodes, ...diff.newNodes];
   if (findings.length === 0) {
@@ -566,6 +578,24 @@ function recordSample(rows, rootPid, atMs, workers, parentSamples) {
     workers.set(row.pid, series);
   }
 }
+function describeCaptureFailure(stage, pid, mismatchedWorker) {
+  if (mismatchedWorker) {
+    return "the snapshot pair belongs to a worker other than the one judged";
+  }
+  if (pid === null) {
+    return "no static-generation worker was seen to capture from";
+  }
+  switch (stage) {
+    case "waiting":
+      return `worker ${pid} never grew enough to snapshot`;
+    case "baseline-taken":
+      return `worker ${pid} was snapshotted once and never reached a second point`;
+    case "missed":
+      return `capture gave up on worker ${pid} before it had a pair`;
+    case "pair-taken":
+      return `the pair captured from worker ${pid} could not be collected from disk`;
+  }
+}
 async function collectCapture(options) {
   const { appDir, workDir, pid, stage, baselineRssBytes, afterRssBytes } = options;
   if (workDir === void 0 || pid === null) {
@@ -716,6 +746,8 @@ async function runBuildMeasurement(options, deps = defaultDeps2) {
       retentionPerPageBytes: null,
       heapExhausted,
       capture: workerCapture,
+      captureRequested: capturing,
+      captureFailure: workerCapture === null ? describeCaptureFailure(captureStage, capturePid, false) : null,
       strippedCapWarning,
       exitCode,
       output
@@ -747,6 +779,12 @@ async function runBuildMeasurement(options, deps = defaultDeps2) {
     // A pair belonging to a worker other than the one judged supports no claim
     // about the verdict above, so it is dropped rather than reported next to it.
     capture: workerCapture !== null && workerCapture.pid === worst?.pid ? workerCapture : null,
+    captureRequested: capturing,
+    captureFailure: workerCapture !== null && workerCapture.pid === worst?.pid ? null : describeCaptureFailure(
+      captureStage,
+      capturePid,
+      workerCapture !== null && workerCapture.pid !== worst?.pid
+    ),
     strippedCapWarning,
     exitCode,
     output

package/dist/{html-report-DLKFB3IU.js → html-report-MSEC3ZI4.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 {
   renderHtmlReport
-} from "./chunk-G2777DKL.js";
-import "./chunk-UU4RXOZO.js";
+} from "./chunk-VKPGB5MG.js";
+import "./chunk-QUFL2FXU.js";
 import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 export {

package/dist/index.js

@@ -41,16 +41,16 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-L5KWU2RU.js";
+} from "./chunk-HDCOHSBY.js";
 import {
   renderHtmlReport
-} from "./chunk-G2777DKL.js";
+} from "./chunk-VKPGB5MG.js";
 import {
   classifyTrend
-} from "./chunk-UU4RXOZO.js";
+} from "./chunk-QUFL2FXU.js";
 import {
   renderIssueMarkdown
-} from "./chunk-YPVBX3QA.js";
+} from "./chunk-ULTMNWRX.js";
 import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 export {

package/dist/{issue-report-OALZZLVR.js → issue-report-JXVLP7CV.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 {
   renderIssueMarkdown
-} from "./chunk-YPVBX3QA.js";
+} from "./chunk-ULTMNWRX.js";
 import "./chunk-E464SO7G.js";
 import "./chunk-6XYFBOL2.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-leak",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Find out whether your Next.js app actually leaks memory — how much, on which route, and whose fault it is.",
   "keywords": [
     "nextjs",