next-leak 0.4.0 → 0.4.2

package/README.md

@@ -104,6 +104,7 @@ Every report prints the gate it used.
 | `--idle <seconds>` | 30 | **Maximum** wait before each sample; the run continues as soon as the heap settles |
 | `--max-old-space <mb>` | 512 | Heap cap of each measured process. Raise it for apps whose legitimate working set is larger, or they die under measurement |
 | `--quick` | off | Fast preset (2000 requests × 4 cycles, 8s idle) — the exact profile the real-app validation ran with. Same cycle count as the default; what it trades away is traffic per cycle, so it sits on the noise floor and is less sensitive to slow leaks. Explicit flags override it |
+| `--no-resolve` | off | Skip the second pass on inconclusive routes |
 | `--diff-all` | off | Diff snapshots for stable routes too |
 | `--output <dir>` | `<app>/.next-leak` | Where runs are written |
 
@@ -168,7 +169,7 @@ separates them, because each one has a different fix:
   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`).
+- **`inconclusive`** — the evidence does not decide. The run does not stop there: any inconclusive route is **measured again automatically**, with twice the cycles, and the second pass is what you see (`resolved at 8 cycles` next to the verdict). On the reproduction for [#95094](https://github.com/vercel/next.js/issues/95094), `--quick` alone reports `inconclusive` on three deltas and then comes back with the leak. `--no-resolve` turns the second pass off; when even that is undecided, the re-run command is still printed.
 - **`failed`** — the route errored under load (auth redirects, POST-only endpoints). >1% non-2xx aborts measurement instead of measuring garbage. That's by design.
 
 ## Peak pressure: `stable` is not the same as safe

package/dist/{chunk-BDIPW6FU.js → chunk-2FZXZLZW.js}

@@ -68,12 +68,14 @@ function classifyMemoryTrend(heapSamples, externalSamples, options = {}) {
 }
 
 // src/confidence.ts
+var resolveCycles = (cycles) => Math.max(cycles * 2, 6);
 function effectiveVerdict(report) {
   return report.confidence.supersededVerdict ?? report.trend.verdict;
 }
 var VERDICT_WEAKENING = /* @__PURE__ */ new Set([
   "near-threshold",
-  "spiky-growth"
+  "spiky-growth",
+  "thin-evidence"
 ]);
 function warrantsIssueDraft(report) {
   return effectiveVerdict(report) === "leak" && !report.confidence.warnings.some((warning) => VERDICT_WEAKENING.has(warning.code));
@@ -182,13 +184,36 @@ function heapCeilingWarnings(input) {
     detail: `the heap peaked at ${mb(peak)} against a ${capMb} MB cap (${pct(peak, capBytes)}) \u2014 the curve may have been clipped by the ceiling rather than by the app; re-run with a larger --max-old-space`
   }];
 }
+var THIN_EVIDENCE_MIN_DELTAS = 5;
+var THIN_EVIDENCE_MIN_DELTA_RATIO = 4;
+function isThinEvidence(trend, minGrowth) {
+  if (trend.deltas.length >= THIN_EVIDENCE_MIN_DELTAS || trend.deltas.length === 0) {
+    return false;
+  }
+  const smallest = Math.min(...trend.deltas);
+  return smallest < minGrowth * THIN_EVIDENCE_MIN_DELTA_RATIO;
+}
+function thinEvidenceWarnings(trend, minGrowth) {
+  if (trend.verdict !== "leak" || !isThinEvidence(trend, minGrowth)) {
+    return [];
+  }
+  const smallest = Math.min(...trend.deltas);
+  return [{
+    code: "thin-evidence",
+    detail: `judged on ${trend.deltas.length} cycles, and its weakest grew ${mb(smallest)} against a ${mb(minGrowth)} gate \u2014 on that few cycles ordinary oscillation reaches that, and a repeat run often disagrees; measure more cycles to resolve it`
+  }];
+}
 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;
+  const thinEvidence = isThinEvidence(
+    input.trend,
+    input.minGrowthPerCycle ?? MIN_GROWTH_NOISE_FLOOR
+  );
+  return neverSettled || abandonedNothing || thinEvidence;
 }
 function assessConfidence(input) {
   const minGrowth = input.minGrowthPerCycle ?? MIN_GROWTH_NOISE_FLOOR;
@@ -197,6 +222,7 @@ function assessConfidence(input) {
     ...loadWarnings(input.loadOutcomes, input.abandonAfterMs),
     ...growthShapeWarnings(input.trend),
     ...noiseFloorWarnings(input.trend, minGrowth),
+    ...thinEvidenceWarnings(input.trend, minGrowth),
     ...heapCeilingWarnings(input)
   ];
   return {
@@ -210,6 +236,7 @@ export {
   minGrowthFor,
   classifyTrend,
   classifyMemoryTrend,
+  resolveCycles,
   effectiveVerdict,
   warrantsIssueDraft,
   assessConfidence

package/dist/{chunk-NYWCWKS6.js → chunk-NNDGXIGQ.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-BDIPW6FU.js";
+} from "./chunk-2FZXZLZW.js";
 import {
   assessPeakPressure,
   describePeakPressure

package/dist/{chunk-USNLL625.js → chunk-YDMJVVWG.js}

@@ -5,8 +5,9 @@ import {
   classifyTrend,
   effectiveVerdict,
   minGrowthFor,
+  resolveCycles,
   warrantsIssueDraft
-} from "./chunk-BDIPW6FU.js";
+} from "./chunk-2FZXZLZW.js";
 import {
   assessPeakPressure,
   describePeakPressure
@@ -91992,6 +91993,11 @@ var FLAGS = [
     help: "Fast preset: 2000 requests x 4 cycles, 8s idle \u2014 same cycle count as the default, less traffic per cycle"
   },
   { flag: "--diff-all", value: "none", help: "Diff snapshots for stable routes too (slow)" },
+  {
+    flag: "--no-resolve",
+    value: "none",
+    help: "Do not re-measure inconclusive routes with more cycles (default: re-measure once)"
+  },
   { flag: "--output", value: "string", argName: "<dir>", help: "Where to write runs (default <app-dir>/.next-leak)" },
   { flag: "--help", alias: "-h", value: "none", help: "Show this help" },
   { flag: "--version", alias: "-v", value: "none", help: "Print the version" }
@@ -92087,6 +92093,9 @@ function applyFlag(spec, value, options) {
     case "--diff-all":
       options.diffAll = true;
       return FLAG_OK;
+    case "--no-resolve":
+      options.noResolve = true;
+      return FLAG_OK;
     case "--output":
       options.output = value;
       return FLAG_OK;
@@ -92137,6 +92146,7 @@ function parseCliArgs(argv) {
     idleSeconds: null,
     maxOldSpaceMb: null,
     quick: false,
+    noResolve: false,
     diffAll: false,
     output: null
   };
@@ -92441,10 +92451,11 @@ function routeLines(route, parameters) {
   }
   const verdict = effectiveVerdict(route);
   const curve = route.samples.map(formatMb).join(" \u2192 ");
+  const resolved = route.resolvedWithCycles === void 0 ? "" : `  (resolved at ${route.resolvedWithCycles} cycles)`;
   return [
     `  ${VERDICT_ICON[verdict]} ${route.route}  ${verdict}  (${formatGrowth(
       route.growthPer1000Requests
-    )})  heap ${curve}`,
+    )})  heap ${curve}${resolved}`,
     ...confidenceLines(route),
     ...memorySourceLines(route, verdict),
     ...peakPressureLines(route, parameters),
@@ -92457,9 +92468,17 @@ function formatReport(report) {
     lines.push(...routeLines(route, report.parameters));
   }
   const { minGrowthPerCycle, loadRequests, cycles, maxOldSpaceMb } = report.parameters;
+  const resolvedCycles = [
+    ...new Set(
+      report.routes.flatMap(
+        (route) => route.status === "measured" && route.resolvedWithCycles !== void 0 ? [route.resolvedWithCycles] : []
+      )
+    )
+  ].sort((a, b) => a - b);
+  const cyclesLabel = resolvedCycles.length === 0 ? `${cycles} cycles` : `${cycles} cycles (${resolvedCycles.join(", ")} where resolved)`;
   lines.push(
     "",
-    `judged over ${cycles} cycles \xD7 ${loadRequests} requests, growth gate ${(minGrowthPerCycle / 1024).toFixed(0)} KiB/cycle (${formatGrowth(minGrowthPerCycle / loadRequests * 1e3)}), heap cap ${maxOldSpaceMb} MB`,
+    `judged over ${cyclesLabel} \xD7 ${loadRequests} requests, growth gate ${(minGrowthPerCycle / 1024).toFixed(0)} KiB/cycle (${formatGrowth(minGrowthPerCycle / loadRequests * 1e3)}), heap cap ${maxOldSpaceMb} MB`,
     `snapshots and run.json: ${report.workDir}`,
     `report: ${report.bundle.htmlReport}`,
     ...report.bundle.issues.map((issue) => `issue draft (${issue.route}): ${issue.file}`)
@@ -92469,7 +92488,7 @@ function formatReport(report) {
   );
   if (inconclusive.length > 0) {
     const routeList = inconclusive.map((route) => route.route).join(",");
-    const moreCycles = Math.max(report.parameters.cycles * 2, 6);
+    const moreCycles = resolveCycles(report.parameters.cycles);
     lines.push(
       "",
       "hint: inconclusive means sustained sub-threshold growth \u2014 measure longer to resolve it:",
@@ -93236,7 +93255,14 @@ var ControlError = class extends Error {
   }
 };
 async function request(port, pathname) {
-  const response = await fetch(`http://127.0.0.1:${port}${pathname}`);
+  let response;
+  try {
+    response = await fetch(`http://127.0.0.1:${port}${pathname}`);
+  } catch (cause) {
+    throw new ControlError(
+      `control channel ${pathname} on port ${port} did not answer (${cause instanceof Error ? cause.message : String(cause)}) \u2014 the measured process is gone or its event loop is blocked`
+    );
+  }
   if (!response.ok) {
     throw new ControlError(`control channel ${pathname} responded ${response.status}`);
   }
@@ -93851,18 +93877,21 @@ function skipReason(route, requestPath) {
   }
   return null;
 }
-async function measureRoute(context, route, requestPath, index) {
+async function measureRoute(context, route, requestPath, index, pass = void 0) {
   const { deps, options, target, workDir, routeConfig, registry, nextVersion, progress } = context;
   const result = await deps.ritual({
     serverPath: target.standaloneServer,
     route: requestPath,
-    workDir: path6.join(workDir, `${String(index + 1).padStart(2, "0")}-${routeSlug(route.path)}`),
+    workDir: path6.join(
+      workDir,
+      `${String(index + 1).padStart(2, "0")}-${routeSlug(route.path)}${pass?.dirSuffix ?? ""}`
+    ),
     bootstrapPath: options.bootstrapPath,
     appPort: await deps.freePort(),
     ...options.warmupRequests !== void 0 && { warmupRequests: options.warmupRequests },
     ...options.loadRequests !== void 0 && { loadRequests: options.loadRequests },
     ...options.connections !== void 0 && { connections: options.connections },
-    ...options.cycles !== void 0 && { cycles: options.cycles },
+    ...pass !== void 0 ? { cycles: pass.cycles } : options.cycles !== void 0 && { cycles: options.cycles },
     ...options.idleMs !== void 0 && { idleMs: options.idleMs },
     ...options.maxOldSpaceMb !== void 0 && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...routeConfig.headers !== void 0 && { headers: routeConfig.headers },
@@ -93896,6 +93925,7 @@ async function measureRoute(context, route, requestPath, index) {
     route: route.path,
     status: "measured",
     requestPath,
+    ...pass !== void 0 && { resolvedWithCycles: pass.cycles },
     samples: result.samples,
     memorySamples: result.memorySamples,
     peaks: result.peaks,
@@ -93914,7 +93944,7 @@ async function measureRoute(context, route, requestPath, index) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-VW7VQOCH.js");
+  const { renderHtmlReport } = await import("./html-report-X2LUOZRH.js");
   const { renderIssueMarkdown } = await import("./issue-report-HKA26WNV.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
@@ -93937,7 +93967,26 @@ async function routeReportFor(context, route, index, total) {
   try {
     const asPath = requestPath === route.path ? "" : ` as ${requestPath}`;
     progress(`measuring ${label}${asPath}`);
-    return await measureRoute(context, route, requestPath, index);
+    const first = await measureRoute(context, route, requestPath, index);
+    if (first.status !== "measured" || context.options.resolveInconclusive === false || effectiveVerdict(first) !== "inconclusive") {
+      return first;
+    }
+    if (context.options.signal?.aborted === true) {
+      return first;
+    }
+    const cycles = resolveCycles(context.options.cycles ?? RITUAL_DEFAULTS.cycles);
+    progress(`re-measuring ${route.path} with ${cycles} cycles: the first pass could not call it`);
+    try {
+      return await measureRoute(context, route, requestPath, index, {
+        cycles,
+        dirSuffix: "-resolve"
+      });
+    } catch (cause) {
+      progress(
+        `re-measurement of ${route.path} failed (${cause instanceof Error ? cause.message : String(cause)}) \u2014 keeping the first pass`
+      );
+      return first;
+    }
   } catch (cause) {
     const failure = cause instanceof Error ? cause.message : String(cause);
     progress(`failed ${label}: ${failure}`);
@@ -93972,7 +94021,7 @@ async function planRun(options, target, deps, progress) {
   ).length;
   const estimate = estimateRun(measurable, parameters);
   progress(
-    `${routes.length} routes discovered` + (measurable === routes.length ? "" : ` \xB7 ${measurable} measurable`) + ` \xB7 estimated ${formatEstimate(estimate)}` + // Long default runs are where first-time users give up; point at the two
+    `${routes.length} routes discovered` + (measurable === routes.length ? "" : ` \xB7 ${measurable} measurable`) + ` \xB7 estimated ${formatEstimate(estimate)}` + (options.resolveInconclusive === false ? "" : " (inconclusive routes are measured again)") + // Long default runs are where first-time users give up; point at the two
     // ways out. Suppressed once load parameters were tuned by hand (or by
     // --quick, which arrives here as explicit loadRequests/idleMs).
     (estimate.slowSeconds > 15 * 60 && options.loadRequests === void 0 && options.idleMs === void 0 ? " \u2014 use --quick for the fast validated preset, or narrow with --routes" : "")

package/dist/cli-args.d.ts

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

package/dist/cli.js

@@ -9,8 +9,8 @@ import {
   killActiveChildren,
   parseCliArgs,
   runMeasurement
-} from "./chunk-USNLL625.js";
-import "./chunk-BDIPW6FU.js";
+} from "./chunk-YDMJVVWG.js";
+import "./chunk-2FZXZLZW.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 
@@ -100,6 +100,7 @@ async function main() {
     ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },
     ...options.maxOldSpaceMb !== null && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...options.diffAll && { diffAll: true },
+    ...options.noResolve && { resolveInconclusive: false },
     ...options.output !== null && { outputDir: options.output },
     onProgress: (message) => console.error(`\xB7 ${message}`)
   });

package/dist/confidence.d.ts

@@ -12,10 +12,11 @@ import { type TrendResult, type 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
+ * `thin-evidence`       — a leak called on too few cycles for its size
  * `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" | "near-heap-ceiling";
+export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "thin-evidence" | "near-heap-ceiling";
 export type MeasurementWarning = {
     code: WarningCode;
     detail: string;
@@ -44,6 +45,12 @@ export type ConfidenceInput = {
     /** Old-space cap the measured process ran under (MB). */
     maxOldSpaceMb?: number;
 };
+/**
+ * Cycles a re-measurement uses when a verdict came back `inconclusive` — the
+ * same figure the report's manual re-run hint prints. One definition, imported
+ * by both, so the tool can never recommend one number and use another.
+ */
+export declare const resolveCycles: (cycles: number) => number;
 /**
  * The verdict a route's evidence actually supports.
  *

package/dist/{html-report-VW7VQOCH.js → html-report-X2LUOZRH.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-NYWCWKS6.js";
-import "./chunk-BDIPW6FU.js";
+} from "./chunk-NNDGXIGQ.js";
+import "./chunk-2FZXZLZW.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 export {

package/dist/index.js

@@ -39,13 +39,13 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-USNLL625.js";
+} from "./chunk-YDMJVVWG.js";
 import {
   renderHtmlReport
-} from "./chunk-NYWCWKS6.js";
+} from "./chunk-NNDGXIGQ.js";
 import {
   classifyTrend
-} from "./chunk-BDIPW6FU.js";
+} from "./chunk-2FZXZLZW.js";
 import {
   renderIssueMarkdown
 } from "./chunk-WXAFXVWS.js";

package/dist/runner.d.ts

@@ -56,6 +56,11 @@ export type RouteReport = {
     /** Null when there is no diff or no module registry. */
     attribution: AttributedDiff | null;
     signatures: MatchedSignature[];
+    /**
+     * Cycles used by the second pass, when the first came back
+     * `inconclusive` and the run went back for more evidence.
+     */
+    resolvedWithCycles?: number;
 };
 export type MeasuredRoute = Extract<RouteReport, {
     status: "measured";
@@ -111,6 +116,11 @@ export type RunOptions = {
     diffAll?: boolean;
     /** Only measure routes matching these templates or prefixes. */
     routeFilter?: string[];
+    /**
+     * Measure a route again, with more cycles, when the first pass could not
+     * call it. Default true: the run should answer the question it was asked.
+     */
+    resolveInconclusive?: boolean;
     /** Abort between phases; remaining routes are reported as interrupted. */
     signal?: AbortSignal;
     onProgress?: (message: string) => void;

package/package.json

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