next-leak 0.10.1 → 0.11.0

package/README.md

@@ -115,6 +115,7 @@ Every report prints the gate it used.
 |---|---|---|
 | `--routes <list>` | all | Only measure these routes (comma-separated templates or prefixes) |
 | `--cycles <n>` | 4 | Load cycles per route (min 3). The first is dropped as warm-up, so the verdict sees `n − 1` deltas — at 3 it sees two |
+| `--repeat <n>` | 1 | Measure each route `n` times, each from a fresh server, and judge it on all of them (max 10). The run takes `n` times as long. Routes whose repetitions disagree are reported `inconclusive`, and the spread of growth rates is printed either way. More cycles watch one process for longer; repetitions watch different ones, which is where the variance lives — three runs of one Next build measured 602, 826 and 875 MB retained, and a fourth measured 39 MB |
 | `--requests <n>` | 5000 | Requests per cycle. Raises sensitivity as well as duration: the growth gate scales with it, down to a noise floor around 5000 |
 | `--connections <n>` | 100 | Concurrent connections |
 | `--idle <seconds>` | 30 | **Maximum** wait before each sample; the run continues as soon as the heap settles |

package/dist/{chunk-5ZBIS5WM.js → chunk-4FYSLLSX.js}

@@ -31,23 +31,32 @@ function isStepwiseGrowth(samples, deltas, growingCycles, mean, minGrowth) {
   }
   return maxDrawdown(samples) <= netGrowth * STEPWISE_MAX_DRAWDOWN_RATIO;
 }
-function isSaturating(deltas) {
+function isSaturating(deltas, minGrowth) {
   if (deltas.length < SATURATION_MIN_CYCLES) {
     return false;
   }
   const first = deltas[0];
   const last = deltas[deltas.length - 1];
-  if (first === void 0 || last === void 0 || first <= 0) {
+  if (first === void 0 || last === void 0 || first < minGrowth) {
     return false;
   }
-  for (let i = 1; i < deltas.length; i += 1) {
-    const current = deltas[i];
-    const previous = deltas[i - 1];
-    if (current === void 0 || previous === void 0 || current >= previous) {
-      return false;
-    }
+  if (!deltas.every((delta) => delta > 0)) {
+    return false;
   }
-  return last <= first * SATURATION_MAX_FINAL_RATIO;
+  if (last > first * SATURATION_MAX_FINAL_RATIO) {
+    return false;
+  }
+  return isHeadingDown(deltas);
+}
+function isHeadingDown(deltas) {
+  const midpoint = Math.floor(deltas.length / 2);
+  const head = deltas.slice(0, midpoint);
+  const tail = deltas.slice(midpoint);
+  if (head.length === 0 || tail.length === 0) {
+    return false;
+  }
+  const mean = (values) => values.reduce((sum, value) => sum + value, 0) / values.length;
+  return mean(tail) < mean(head);
 }
 function isTooLargeToAcquit(deltas, mean, minGrowth) {
   const netGrowth = deltas.reduce((sum, delta) => sum + delta, 0);
@@ -71,10 +80,10 @@ function classifyShape(samples, options) {
   const allGrow = deltas.every((d) => d >= minGrowth);
   const anyFlatOrDown = deltas.some((d) => d <= 0);
   const growingCycles = deltas.filter((d) => d >= minGrowth).length;
+  if (isSaturating(deltas, minGrowth)) {
+    return { verdict: "saturating", growthPerCycle: mean, deltas, source: "heap" };
+  }
   if (allGrow) {
-    if (isSaturating(deltas)) {
-      return { verdict: "saturating", growthPerCycle: mean, deltas, source: "heap" };
-    }
     return { verdict: "leak", growthPerCycle: mean, deltas, source: "heap" };
   }
   if (isStepwiseGrowth(samples, deltas, growingCycles, mean, minGrowth)) {
@@ -115,7 +124,8 @@ function effectiveVerdict(report) {
 var VERDICT_WEAKENING = /* @__PURE__ */ new Set([
   "near-threshold",
   "spiky-growth",
-  "thin-evidence"
+  "thin-evidence",
+  "repetitions-disagree"
 ]);
 function warrantsIssueDraft(report) {
   return effectiveVerdict(report) === "leak" && !report.confidence.warnings.some((warning) => VERDICT_WEAKENING.has(warning.code));

package/dist/{chunk-OIJE43WX.js → chunk-JHOE2RCM.js}

@@ -7,7 +7,7 @@ import {
   minGrowthFor,
   resolveCycles,
   warrantsIssueDraft
-} from "./chunk-5ZBIS5WM.js";
+} from "./chunk-4FYSLLSX.js";
 import {
   assessPeakPressure,
   describePeakPressure
@@ -92939,6 +92939,7 @@ var BUILD_COMMAND = "build";
 var RUN_ONLY_FLAGS = [
   ["routes", "--routes"],
   ["cycles", "--cycles"],
+  ["repeat", "--repeat"],
   ["requests", "--requests"],
   ["connections", "--connections"],
   ["idleSeconds", "--idle"],
@@ -92967,6 +92968,12 @@ var FLAGS = [
     help: "Only measure these routes \u2014 comma-separated templates or prefixes (e.g. /api,/dashboard)"
   },
   { flag: "--cycles", value: "int", argName: "<n>", help: "Load cycles per route (default 4, minimum 3)" },
+  {
+    flag: "--repeat",
+    value: "int",
+    argName: "<n>",
+    help: "Measure each route n times from a fresh server (default 1) \u2014 the run takes n times as long, and routes whose repetitions disagree are reported inconclusive"
+  },
   { flag: "--requests", value: "int", argName: "<n>", help: "Requests per cycle (default 5000)" },
   { flag: "--connections", value: "int", argName: "<n>", help: "Concurrent connections (default 100)" },
   { flag: "--idle", value: "int", argName: "<seconds>", help: "Idle seconds before each sample (default 30)" },
@@ -93048,6 +93055,7 @@ interrupted, 1 on errors.
 }
 var LIMITS = {
   "--cycles": 100,
+  "--repeat": 10,
   "--requests": 1e6,
   "--connections": 1e4,
   "--idle": 3600,
@@ -93088,6 +93096,7 @@ function applyNumericFlag(flag, value, options) {
     );
   }
   if (flag === "--cycles") options.cycles = parsed;
+  if (flag === "--repeat") options.repeat = parsed;
   if (flag === "--requests") options.requests = parsed;
   if (flag === "--connections") options.connections = parsed;
   if (flag === "--idle") options.idleSeconds = parsed;
@@ -93100,6 +93109,7 @@ function applyFlag(spec, value, options) {
     case "--routes":
       return applyRoutesFlag(value, options);
     case "--cycles":
+    case "--repeat":
     case "--requests":
     case "--connections":
     case "--idle":
@@ -93171,6 +93181,7 @@ function parseCliArgs(argv) {
     appDir: "",
     routes: null,
     cycles: null,
+    repeat: null,
     requests: null,
     connections: null,
     idleSeconds: null,
@@ -94242,6 +94253,19 @@ function revalidationLines(route) {
     `      driven through ISR revalidation (revalidates every ${route.revalidatedEverySeconds}s; without it the load would serve the cache)`
   ];
 }
+function repetitionLines(route) {
+  const repetitions = route.repetitions;
+  if (repetitions === void 0 || repetitions.length < 2) {
+    return [];
+  }
+  const rates = repetitions.map((entry) => entry.growthPer1000Requests);
+  const low = Math.min(...rates);
+  const high = Math.max(...rates);
+  const verdicts = [...new Set(repetitions.map((entry) => entry.verdict))];
+  const agreement = verdicts.length === 1 ? `all ${repetitions.length} agreed on ${verdicts[0]}` : `they disagreed (${verdicts.join(", ")}), so no single verdict is reported`;
+  const range = `${low >= 0 ? "+" : ""}${(low / MB2).toFixed(2)} to ${formatGrowth(high)}`;
+  return [`      across ${repetitions.length} repetitions: ${range} \u2014 ${agreement}`];
+}
 function cacheLines(route) {
   const lines = [];
   if (route.trend.verdict === "saturating") {
@@ -94363,6 +94387,7 @@ function routeLines(route, parameters) {
     `  ${VERDICT_ICON[verdict]} ${route.route}  ${verdict}  (${formatGrowth(
       route.growthPer1000Requests
     )})  heap ${curve}${resolved}`,
+    ...repetitionLines(route),
     ...revalidationLines(route),
     ...cacheLines(route),
     ...abandonLines(route),
@@ -94752,7 +94777,7 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
     ...options.warmupRequests !== void 0 && { warmupRequests: options.warmupRequests },
     ...options.loadRequests !== void 0 && { loadRequests: options.loadRequests },
     ...options.connections !== void 0 && { connections: options.connections },
-    ...pass !== void 0 ? { cycles: pass.cycles } : options.cycles !== void 0 && { cycles: options.cycles },
+    ...pass?.cycles !== 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 },
     ...headers !== void 0 && { headers },
@@ -94810,7 +94835,7 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
     route: route.path,
     status: "measured",
     requestPath,
-    ...pass !== void 0 && { resolvedWithCycles: pass.cycles },
+    ...pass?.cycles !== void 0 && { resolvedWithCycles: pass.cycles },
     samples: result.samples,
     memorySamples: result.memorySamples,
     peaks: result.peaks,
@@ -94841,7 +94866,7 @@ async function measureRoute(context, route, requestPath, index, pass = void 0) {
   };
 }
 async function writeEvidenceBundle(report, workDir) {
-  const { renderHtmlReport } = await import("./html-report-YWIK5EDQ.js");
+  const { renderHtmlReport } = await import("./html-report-O7ILFOF5.js");
   const { renderIssueMarkdown } = await import("./issue-report-FPVOZ6HU.js");
   for (const route of report.routes) {
     if (route.status === "measured" && warrantsIssueDraft(route)) {
@@ -94879,7 +94904,7 @@ async function routeReportFor(context, route, index, total) {
     progress(`not measuring ${label}: ${plan.reason}`);
     return { route: route.path, status: "not-exercised", reason: plan.reason };
   }
-  return measureWithResolution(context, route, requestPath, index, label);
+  return measureRepeatedly(context, route, requestPath, index, label);
 }
 function reasonToResolve(verdict) {
   switch (verdict) {
@@ -94892,12 +94917,74 @@ function reasonToResolve(verdict) {
       return null;
   }
 }
-async function measureWithResolution(context, route, requestPath, index, label) {
+async function measureRepeatedly(context, route, requestPath, index, label) {
+  const repeat = context.options.repeat ?? 1;
+  if (repeat <= 1) {
+    return measureWithResolution(context, route, requestPath, index, label);
+  }
+  const passes = [];
+  for (let attempt = 1; attempt <= repeat; attempt += 1) {
+    context.progress(`repetition ${attempt}/${repeat} of ${label}`);
+    passes.push(
+      await measureWithResolution(context, route, requestPath, index, label, `-rep${attempt}`)
+    );
+    if (context.options.signal?.aborted === true) {
+      break;
+    }
+  }
+  return aggregateRepetitions(passes);
+}
+function aggregateRepetitions(passes) {
+  const first = passes[0];
+  if (first === void 0) {
+    return { route: "", status: "failed", reason: "no repetition produced a result" };
+  }
+  const measured = passes.filter((pass) => pass.status === "measured");
+  if (measured.length !== passes.length || measured.length === 0) {
+    return passes.find((pass) => pass.status !== "measured") ?? first;
+  }
+  const repetitions = measured.map((pass) => ({
+    verdict: pass.trend.verdict,
+    growthPer1000Requests: pass.trend.growthPerCycle / pass.requestsPerCycle * 1e3
+  }));
+  const verdicts = [...new Set(repetitions.map((entry) => entry.verdict))];
+  const winner = measured[0];
+  if (winner === void 0) {
+    return first;
+  }
+  if (verdicts.length === 1) {
+    return { ...winner, repetitions };
+  }
+  const observed = verdicts.join(", ");
+  return {
+    ...winner,
+    repetitions,
+    confidence: {
+      ...winner.confidence,
+      level: "low",
+      warnings: [
+        ...winner.confidence.warnings,
+        {
+          code: "repetitions-disagree",
+          detail: `${repetitions.length} repetitions of this route disagreed (${observed}) \u2014 the measurement did not settle, so no single verdict is reported`
+        }
+      ],
+      supersededVerdict: "inconclusive"
+    }
+  };
+}
+async function measureWithResolution(context, route, requestPath, index, label, repetitionSuffix = "") {
   const { progress } = context;
   try {
     const asPath = requestPath === route.path ? "" : ` as ${requestPath}`;
     progress(`measuring ${label}${asPath}`);
-    const first = await measureRoute(context, route, requestPath, index);
+    const first = await measureRoute(
+      context,
+      route,
+      requestPath,
+      index,
+      repetitionSuffix === "" ? void 0 : { dirSuffix: repetitionSuffix }
+    );
     const reason = first.status === "measured" ? reasonToResolve(effectiveVerdict(first)) : null;
     if (first.status !== "measured" || context.options.resolveInconclusive === false || reason === null) {
       return first;
@@ -94910,7 +94997,7 @@ async function measureWithResolution(context, route, requestPath, index, label)
     try {
       return await measureRoute(context, route, requestPath, index, {
         cycles,
-        dirSuffix: "-resolve"
+        dirSuffix: `${repetitionSuffix}-resolve`
       });
     } catch (cause) {
       progress(

package/dist/{chunk-SV47LIER.js → chunk-YLHE4N5G.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-5ZBIS5WM.js";
+} from "./chunk-4FYSLLSX.js";
 import {
   assessPeakPressure,
   describePeakPressure

package/dist/cli-args.d.ts

@@ -2,6 +2,15 @@ export type CliRunOptions = {
     appDir: string;
     routes: string[] | null;
     cycles: number | null;
+    /**
+     * How many times to measure each route, from a fresh server each time.
+     *
+     * More cycles watch one process for longer; repetitions watch different
+     * processes. The spreads that make a verdict unpublishable live between
+     * processes: vercel/next.js#84648 gave 602, 826 and 875 MB on three runs of
+     * one build and 39 MB on a fourth.
+     */
+    repeat: number | null;
     requests: number | null;
     connections: number | null;
     idleSeconds: number | null;

package/dist/cli.js

@@ -22,10 +22,10 @@ import {
   runSelfCheck,
   unregisterChild,
   validateTarget
-} from "./chunk-OIJE43WX.js";
+} from "./chunk-JHOE2RCM.js";
 import {
   classifyTrend
-} from "./chunk-5ZBIS5WM.js";
+} from "./chunk-4FYSLLSX.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 
@@ -927,6 +927,7 @@ async function main() {
     ...quickPreset,
     ...options.routes !== null && { routeFilter: options.routes },
     ...options.cycles !== null && { cycles: options.cycles },
+    ...options.repeat !== null && { repeat: options.repeat },
     ...options.requests !== null && { loadRequests: options.requests },
     ...options.connections !== null && { connections: options.connections },
     ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },

package/dist/confidence.d.ts

@@ -20,7 +20,16 @@ import { type TrendResult, type TrendVerdict } from "./trend.js";
  *   settled at, so it carries warm-up's own retention rather than the app's
  *   resting size
  */
-export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "thin-evidence" | "near-heap-ceiling" | "warm-up-baseline";
+export type WarningCode = "unsettled" | "settle-unverified" | "load-incomplete" | "abandon-ineffective" | "abandon-before-response" | "spiky-growth" | "near-threshold" | "thin-evidence" | "near-heap-ceiling" | "warm-up-baseline"
+/**
+ * Repeated measurements of the same route did not agree.
+ *
+ * More cycles watch one process for longer; repetitions watch different
+ * ones, and that is where the spread lives — vercel/next.js#84648 gave 602,
+ * 826 and 875 MB on three runs of one build and 39 MB on a fourth. A verdict
+ * a second run contradicts is not a verdict.
+ */
+ | "repetitions-disagree";
 export type MeasurementWarning = {
     code: WarningCode;
     detail: string;

package/dist/{html-report-YWIK5EDQ.js → html-report-O7ILFOF5.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-SV47LIER.js";
-import "./chunk-5ZBIS5WM.js";
+} from "./chunk-YLHE4N5G.js";
+import "./chunk-4FYSLLSX.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 export {

package/dist/index.js

@@ -41,13 +41,13 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-OIJE43WX.js";
+} from "./chunk-JHOE2RCM.js";
 import {
   renderHtmlReport
-} from "./chunk-SV47LIER.js";
+} from "./chunk-YLHE4N5G.js";
 import {
   classifyTrend
-} from "./chunk-5ZBIS5WM.js";
+} from "./chunk-4FYSLLSX.js";
 import {
   renderIssueMarkdown
 } from "./chunk-AUUMRTZZ.js";

package/dist/runner.d.ts

@@ -8,7 +8,13 @@ import { type PrerenderManifest } from "./manifests.js";
 import { extractModuleRegistry } from "./module-registry.js";
 import { runRitual, type LoadOutcome, type PeakSample, type PhaseTiming, type SettleOutcome } from "./ritual.js";
 import { readNextVersion, type MatchedSignature } from "./signatures.js";
-import { type TrendResult } from "./trend.js";
+import { type TrendResult, type TrendVerdict } from "./trend.js";
+/** What one repetition of a route concluded, for disclosing the spread. */
+export type RepetitionSummary = {
+    verdict: TrendVerdict;
+    /** Growth normalized by traffic, so repetitions stay comparable. */
+    growthPer1000Requests: number;
+};
 export type RouteReport = {
     route: string;
     status: "skipped";
@@ -79,6 +85,12 @@ export type RouteReport = {
     unreclaimedTrend: TrendResult;
     /** Requests each cycle served — what the growth rates normalize by. */
     requestsPerCycle: number;
+    /**
+     * One entry per repetition when `repeat` was greater than 1, in the
+     * order they ran. Absent for a single measurement, so `run.json` keeps
+     * its existing shape unless repetition was asked for.
+     */
+    repetitions?: RepetitionSummary[];
     /**
      * The early-disconnect regime, when the route asked for one. Recorded
      * because a curve measured with cuts landing mid-stream and one measured
@@ -227,6 +239,13 @@ export type RunOptions = {
      * call it. Default true: the run should answer the question it was asked.
      */
     resolveInconclusive?: boolean;
+    /**
+     * How many times to measure each route, each from a fresh server. Default 1.
+     *
+     * Distinct from `cycles`, which watches a single process for longer. The
+     * variance that makes a number unpublishable is between processes.
+     */
+    repeat?: number;
     /**
      * Growth the self-check measured on its planted leak, when one ran before
      * this measurement. Its presence is what lets the report say a `stable`
@@ -265,6 +284,17 @@ export type RunnerDeps = {
 };
 export declare function freePort(): Promise<number>;
 export declare function routeSlug(route: string): string;
+/**
+ * Combines repeated measurements of one route into the verdict it earned.
+ *
+ * Unanimity or nothing. Taking the most severe would let one noisy repetition
+ * in five accuse a healthy route, and a false accusation is the expensive
+ * error; taking the majority would discard exactly the disagreement the
+ * repetitions were run to find. When they disagree the honest report is that
+ * the measurement did not settle, which is what `inconclusive` means and what
+ * already routes to re-measurement and away from issue drafts.
+ */
+export declare function aggregateRepetitions(passes: readonly RouteReport[]): RouteReport;
 /**
  * Full measurement run: validate the target, discover routes, run the ritual
  * per route in a fresh process, diff snapshots for non-stable verdicts, and

package/package.json

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