next-leak 0.5.0 → 0.6.0

package/dist/cli-args.d.ts

@@ -5,15 +5,24 @@ export type CliRunOptions = {
     requests: number | null;
     connections: number | null;
     idleSeconds: number | null;
+    warmupRequests: number | null;
     maxOldSpaceMb: number | null;
     quick: boolean;
     noResolve: boolean;
     diffAll: boolean;
+    writeConfig: boolean;
+    output: string | null;
+};
+export type CliBuildOptions = {
+    appDir: string;
     output: string | null;
 };
 export type ParsedCli = {
     kind: "run";
     options: CliRunOptions;
+} | {
+    kind: "build";
+    options: CliBuildOptions;
 } | {
     kind: "help";
 } | {

package/dist/cli.js

@@ -4,20 +4,467 @@ import {
   RouteConfigError,
   TargetError,
   checkRuntime,
+  discoverPagesRoutes,
+  discoverRoutes,
   formatReport,
+  hasPlaceholders,
   helpText,
   killActiveChildren,
   parseCliArgs,
-  runMeasurement
-} from "./chunk-IDSNTUKC.js";
-import "./chunk-2FZXZLZW.js";
+  registerChild,
+  renderConfigSkeleton,
+  runMeasurement,
+  unregisterChild,
+  validateTarget
+} from "./chunk-AMSDGT3Y.js";
+import {
+  classifyTrend
+} from "./chunk-22PBLCGO.js";
 import "./chunk-XHPUAMJG.js";
 import "./chunk-6XYFBOL2.js";
 
 // src/cli.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
+import { writeFile } from "fs/promises";
 import { createRequire } from "module";
+import path3 from "path";
 import { fileURLToPath } from "url";
+
+// src/build-report.ts
+var MB = 1024 * 1024;
+var mb = (bytes) => `${(bytes / MB).toFixed(1)} MB`;
+var mbPrecise = (bytes) => `${(bytes / MB).toFixed(2)} MB`;
+var VERDICT_ICON = {
+  leak: "\u2716",
+  stable: "\u2714",
+  inconclusive: "?"
+};
+function curveLine(levels) {
+  return levels.map((level) => mb(level)).join(" \u2192 ");
+}
+function growthLine(result) {
+  const perPage = result.retentionPerPageBytes === null ? "" : `  (${mbPrecise(result.retentionPerPageBytes)}/page over ${result.pagesGenerated} pages)`;
+  return `      grew ${mb(result.netGrowthBytes)} across the generation phase${perPage}`;
+}
+function formatBuildReport(result) {
+  const lines = [`next-leak build \xB7 ${result.appDir}`, ""];
+  if (result.strippedCapWarning !== null) {
+    lines.push(`  \u25B2 ${result.strippedCapWarning}`, "");
+  }
+  if (result.status === "build-failed") {
+    lines.push(
+      `  \u2716 the build failed for a reason that is not memory (exit ${result.exitCode ?? "?"})`,
+      `      no memory claim is made; the build's own output follows`,
+      "",
+      ...result.output.trimEnd().split("\n").slice(-20).map((line) => `      ${line}`)
+    );
+    return lines.join("\n");
+  }
+  if (result.status === "cannot-sample") {
+    lines.push(
+      `  \u2716 could not read the process table, so the build was not measured`,
+      `      ${result.samplingFailure ?? "unknown reason"}`,
+      `      this is not a clean run: an unreadable table and a build with no`,
+      `      workers look identical from here, and only one of them is good news`
+    );
+    return lines.join("\n");
+  }
+  if (result.status === "nothing-to-measure") {
+    lines.push(
+      `  \u2013 no static-generation worker ran, so there was nothing to measure`,
+      `      a build with no prerendered pages does not exercise this path`
+    );
+    return lines.join("\n");
+  }
+  const verdict = result.verdict ?? "inconclusive";
+  const icon = VERDICT_ICON[verdict] ?? "?";
+  lines.push(`  ${icon} static-generation worker  ${verdict}`);
+  if (result.levels.length > 0) {
+    lines.push(`      worker rss ${curveLine(result.levels)}`);
+  }
+  if (result.netGrowthBytes > 0) {
+    lines.push(growthLine(result));
+  }
+  if (verdict === "inconclusive" && result.levels.length === 0) {
+    lines.push(`      the build was too short to judge \u2014 not a sign of health`);
+  }
+  if (result.heapExhausted) {
+    lines.push(
+      `      the worker ran out of heap and the build died with it after ${result.pagesGenerated ?? "?"} pages, reaching ${mb(result.peakWorkerRssBytes)}`,
+      `      no per-page figure for a crashed build: the curve is truncated where`,
+      `      the worker died, so any denominator would be guesswork`,
+      `      that outcome is the verdict here, whatever shape the curve above has:`,
+      `      raising the cap moves the wall; it does not remove it`
+    );
+  }
+  if (result.workers.length > 1) {
+    lines.push(`      ${result.workers.length} workers ran; the verdict is the worst of them`);
+  }
+  lines.push(
+    "",
+    `  peak worker rss ${mb(result.peakWorkerRssBytes)} \xB7 sampled from the process tree, so a`,
+    `  spike shorter than the polling interval is not observed`
+  );
+  return lines.join("\n");
+}
+
+// src/build-run.ts
+import { spawn } from "child_process";
+import path2 from "path";
+
+// src/build-target.ts
+import { access, readFile, readdir } from "fs/promises";
+import path from "path";
+var CONFIG_NAMES = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readPackageJson(appDir) {
+  try {
+    return JSON.parse(await readFile(path.join(appDir, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function usesWorkerThreads(appDir) {
+  for (const name of CONFIG_NAMES) {
+    const file = path.join(appDir, name);
+    if (!await exists(file)) {
+      continue;
+    }
+    const source = await readFile(file, "utf8");
+    if (/workerThreads\s*:\s*true/.test(source)) {
+      return true;
+    }
+  }
+  return false;
+}
+async function validateBuildTarget(appDir) {
+  const resolved = path.resolve(appDir);
+  let entries;
+  try {
+    entries = await readdir(resolved);
+  } catch {
+    throw new TargetError("NO_BUILD", `Cannot read ${resolved}.`);
+  }
+  const packageJson = await readPackageJson(resolved);
+  const dependencies = {
+    ...packageJson?.dependencies ?? {},
+    ...packageJson?.devDependencies ?? {}
+  };
+  const hasNext = "next" in dependencies || entries.some((entry) => CONFIG_NAMES.includes(entry));
+  if (!hasNext) {
+    throw new TargetError(
+      "NO_BUILD",
+      `${resolved} is not a Next.js project: no "next" dependency in package.json and no next.config.
+next-leak build measures a Next.js build. Point it at the directory holding your package.json.`
+    );
+  }
+  if (await usesWorkerThreads(resolved)) {
+    throw new TargetError(
+      "NO_BUILD",
+      `This project sets experimental.workerThreads: true.
+next-leak build measures the resident memory of each static-generation worker, and a
+worker thread has none of its own \u2014 it shares the parent's. Remove the flag (Next's
+default) to make the build measurable.`
+    );
+  }
+  const scripts = packageJson?.scripts ?? {};
+  const buildScript = "build" in scripts ? "build" : null;
+  return { appDir: resolved, buildScript };
+}
+
+// src/build-verdict.ts
+function segmentSamples(samples, segments) {
+  if (segments <= 0 || samples.length < segments) {
+    return [];
+  }
+  const first = samples[0];
+  const last = samples[samples.length - 1];
+  if (first === void 0 || last === void 0) {
+    return [];
+  }
+  const span = last.atMs - first.atMs;
+  if (span <= 0) {
+    return [];
+  }
+  const levels = [];
+  for (let segment = 1; segment <= segments; segment += 1) {
+    const until = first.atMs + span * segment / segments;
+    let level;
+    for (const sample of samples) {
+      if (sample.atMs <= until) {
+        level = sample.rssBytes;
+      }
+    }
+    if (level !== void 0) {
+      levels.push(level);
+    }
+  }
+  return levels;
+}
+var BUILD_SEGMENTS = 6;
+var BUILD_GROWTH_GATE_BYTES = 32 * 1024 * 1024;
+function classifyBuildSamples(samples) {
+  const levels = segmentSamples(samples, BUILD_SEGMENTS);
+  return {
+    trend: classifyTrend(levels, { minGrowthPerCycle: BUILD_GROWTH_GATE_BYTES }),
+    levels
+  };
+}
+function netGrowthOf(levels) {
+  const first = levels[1] ?? levels[0];
+  const last = levels[levels.length - 1];
+  if (first === void 0 || last === void 0) {
+    return 0;
+  }
+  return last - first;
+}
+function strippedHeapCap(nodeOptions) {
+  if (nodeOptions === void 0) {
+    return null;
+  }
+  const match = /--max[-_]old[-_]space[-_]size[= ]\s*(\d+)/.exec(nodeOptions);
+  if (match === null) {
+    return null;
+  }
+  const value = match[1] ?? "";
+  return `NODE_OPTIONS sets --max-old-space-size=${value}, which Next strips from the static-generation worker's environment \u2014 the worker never sees it. Use --max-heap-size=${value} instead, which survives.`;
+}
+var HEAP_DEATH_MARKERS = [
+  "JavaScript heap out of memory",
+  "Reached heap limit",
+  "Ineffective mark-compacts near heap limit"
+];
+function diedOfHeapExhaustion(output) {
+  return HEAP_DEATH_MARKERS.some((marker) => output.includes(marker));
+}
+function pagesGeneratedFrom(output) {
+  let furthest = null;
+  for (const line of output.split("\n")) {
+    if (!line.includes("static pages")) {
+      continue;
+    }
+    for (const match of line.matchAll(/\((\d+)\/(\d+)\)/g)) {
+      const done = Number(match[1]);
+      if (Number.isFinite(done) && (furthest === null || done > furthest)) {
+        furthest = done;
+      }
+    }
+  }
+  return furthest;
+}
+
+// src/process-tree.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var run = promisify(execFile);
+var STATIC_WORKER_MARKER = "jest-worker/processChild";
+var KB = 1024;
+function parseProcessTable(output) {
+  const rows = [];
+  for (const line of output.split("\n")) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+    if (match === null) {
+      continue;
+    }
+    const [, pid, ppid, rssKb, command] = match;
+    if (pid === void 0 || ppid === void 0 || rssKb === void 0 || command === void 0) {
+      continue;
+    }
+    rows.push({
+      pid: Number(pid),
+      ppid: Number(ppid),
+      rssBytes: Number(rssKb) * KB,
+      command
+    });
+  }
+  return rows;
+}
+function descendantsOf(rows, rootPid) {
+  const found = /* @__PURE__ */ new Map();
+  let frontier = /* @__PURE__ */ new Set([rootPid]);
+  while (frontier.size > 0) {
+    const next = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      if (!frontier.has(row.ppid) || found.has(row.pid) || row.pid === rootPid) {
+        continue;
+      }
+      found.set(row.pid, row);
+      next.add(row.pid);
+    }
+    frontier = next;
+  }
+  return [...found.values()];
+}
+function isStaticGenWorker(row) {
+  return row.command.includes(STATIC_WORKER_MARKER);
+}
+async function sampleProcessTable() {
+  try {
+    const { stdout } = await run("ps", ["-axo", "pid,ppid,rss,command"], {
+      maxBuffer: 8 * 1024 * 1024
+    });
+    return { ok: true, rows: parseProcessTable(stdout) };
+  } catch (cause) {
+    return { ok: false, reason: cause instanceof Error ? cause.message : String(cause) };
+  }
+}
+
+// src/build-run.ts
+var POLL_MS = 500;
+function spawnNextBuild(appDir, env) {
+  const nextBin = path2.join(appDir, "node_modules", "next", "dist", "bin", "next");
+  return spawn(process.execPath, [nextBin, "build"], {
+    cwd: appDir,
+    env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+}
+var defaultDeps = {
+  spawnBuild: spawnNextBuild,
+  sampleTable: sampleProcessTable,
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+function recordSample(rows, rootPid, atMs, workers, parentSamples) {
+  const root = rows.find((row) => row.pid === rootPid);
+  if (root !== void 0) {
+    parentSamples.push({ atMs, rssBytes: root.rssBytes });
+  }
+  for (const row of descendantsOf(rows, rootPid)) {
+    if (!isStaticGenWorker(row)) {
+      continue;
+    }
+    const series = workers.get(row.pid) ?? [];
+    series.push({ atMs, rssBytes: row.rssBytes });
+    workers.set(row.pid, series);
+  }
+}
+function worstWorker(workers) {
+  let worst = null;
+  let worstGrowth = -Infinity;
+  for (const worker of workers) {
+    const growth = netGrowthOf(classifyBuildSamples(worker.samples).levels);
+    if (growth > worstGrowth) {
+      worstGrowth = growth;
+      worst = worker;
+    }
+  }
+  return worst;
+}
+var peakOf = (samples) => samples.reduce((highest, sample) => Math.max(highest, sample.rssBytes), 0);
+async function runBuildMeasurement(options, deps = defaultDeps) {
+  const target = await validateBuildTarget(options.appDir);
+  const progress = options.onProgress ?? (() => {
+  });
+  const env = options.env ?? process.env;
+  const strippedCapWarning = strippedHeapCap(env["NODE_OPTIONS"]);
+  if (strippedCapWarning !== null) {
+    progress(strippedCapWarning);
+  }
+  progress(`building ${target.appDir}`);
+  const child = deps.spawnBuild(target.appDir, env);
+  registerChild(child);
+  let output = "";
+  const capture = (chunk) => {
+    output += String(chunk);
+  };
+  child.stdout?.on("data", capture);
+  child.stderr?.on("data", capture);
+  const startedAt = deps.now();
+  const workerSamples = /* @__PURE__ */ new Map();
+  const parentSamples = [];
+  let finished = false;
+  const exit = new Promise((resolve) => {
+    child.once("exit", (code) => {
+      finished = true;
+      resolve(code);
+    });
+  });
+  const abort = () => {
+    child.kill("SIGTERM");
+  };
+  options.signal?.addEventListener("abort", abort, { once: true });
+  let samplingFailure = null;
+  const polling = (async () => {
+    while (!finished) {
+      await deps.sleep(POLL_MS);
+      if (finished || child.pid === void 0) {
+        return;
+      }
+      const sample = await deps.sampleTable();
+      if (!sample.ok) {
+        samplingFailure = sample.reason;
+        return;
+      }
+      recordSample(sample.rows, child.pid, deps.now() - startedAt, workerSamples, parentSamples);
+    }
+  })();
+  const exitCode = await exit;
+  await polling;
+  options.signal?.removeEventListener("abort", abort);
+  unregisterChild(child);
+  const workers = [...workerSamples].map(([pid, samples]) => ({ pid, samples }));
+  const heapExhausted = diedOfHeapExhaustion(output);
+  const pagesGenerated = pagesGeneratedFrom(output);
+  if (workers.length === 0) {
+    return {
+      appDir: target.appDir,
+      // "Could not look" is not "nothing was there". A build that broke before
+      // generating anything is a failed build, not a measurement of nothing.
+      status: samplingFailure !== null ? "cannot-sample" : exitCode === 0 ? "nothing-to-measure" : "build-failed",
+      samplingFailure,
+      verdict: null,
+      trend: null,
+      levels: [],
+      workers,
+      parentSamples,
+      peakWorkerRssBytes: 0,
+      netGrowthBytes: 0,
+      pagesGenerated,
+      retentionPerPageBytes: null,
+      heapExhausted,
+      strippedCapWarning,
+      exitCode,
+      output
+    };
+  }
+  const worst = worstWorker(workers);
+  const { trend, levels } = classifyBuildSamples(worst?.samples ?? []);
+  const peakWorkerRssBytes = workers.reduce(
+    (highest, worker) => Math.max(highest, peakOf(worker.samples)),
+    0
+  );
+  const measured = exitCode === 0 || heapExhausted;
+  const verdict = heapExhausted ? "leak" : trend.verdict;
+  const growthBytes = heapExhausted ? 0 : netGrowthOf(levels);
+  return {
+    appDir: target.appDir,
+    status: measured ? "measured" : "build-failed",
+    samplingFailure,
+    verdict: measured ? verdict : null,
+    trend: measured ? trend : null,
+    levels: measured ? levels : [],
+    workers,
+    parentSamples,
+    peakWorkerRssBytes,
+    netGrowthBytes: measured ? growthBytes : 0,
+    pagesGenerated,
+    retentionPerPageBytes: measured && growthBytes > 0 && pagesGenerated !== null && pagesGenerated > 0 ? growthBytes / pagesGenerated : null,
+    heapExhausted,
+    strippedCapWarning,
+    exitCode,
+    output
+  };
+}
+
+// src/cli.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 var HEADROOM_SENTINEL = "NEXT_LEAK_WITH_HEADROOM";
@@ -26,7 +473,7 @@ function hasHeapHeadroom() {
   return process.execArgv.some((argument) => argument.includes("--max-old-space-size")) || (process.env.NODE_OPTIONS ?? "").includes("--max-old-space-size") || process.env[HEADROOM_SENTINEL] === "1";
 }
 function reexecWithHeadroom() {
-  const child = spawn(process.execPath, [`--max-old-space-size=${HEADROOM_MB}`, ...process.argv.slice(1)], {
+  const child = spawn2(process.execPath, [`--max-old-space-size=${HEADROOM_MB}`, ...process.argv.slice(1)], {
     stdio: "inherit",
     env: { ...process.env, [HEADROOM_SENTINEL]: "1" }
   });
@@ -76,9 +523,58 @@ function handleNonRunCommand(parsed) {
   }
   return false;
 }
+async function runBuildCommand(appDir) {
+  const aborter = installInterruptHandlers();
+  const result = await runBuildMeasurement({
+    appDir,
+    signal: aborter.signal,
+    onProgress: (message) => console.error(`\xB7 ${message}`)
+  });
+  console.log(formatBuildReport(result));
+  if (aborter.signal.aborted) {
+    process.exitCode = 130;
+  }
+}
+async function writeConfigSkeleton(appDir) {
+  const target = await validateTarget(appDir);
+  const routes = [...discoverRoutes(target.appPaths), ...discoverPagesRoutes(target.pages)].filter((route) => route.dynamic && route.unaddressableReason === void 0).map((route) => route.path);
+  const skeleton = renderConfigSkeleton(routes, target.prerender);
+  if (skeleton === null) {
+    console.log("no route needs sample params \u2014 nothing to write");
+    return;
+  }
+  const file = path3.join(target.appDir, "next-leak.config.json");
+  try {
+    await writeFile(file, `${skeleton}
+`, { flag: "wx" });
+  } catch {
+    console.error(
+      `error: ${file} already exists \u2014 not overwriting. The fragment that would measure the skipped routes:
+
+${skeleton}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`wrote ${file}`);
+  if (hasPlaceholders(skeleton)) {
+    console.log("replace each REPLACE-ME with a value that exists in your app");
+  }
+}
 async function main() {
   const parsed = parseCliArgs(process.argv.slice(2));
-  if (handleNonRunCommand(parsed) || parsed.kind !== "run") {
+  if (handleNonRunCommand(parsed)) {
+    return;
+  }
+  if (parsed.kind === "build") {
+    await runBuildCommand(parsed.options.appDir);
+    return;
+  }
+  if (parsed.kind !== "run") {
+    return;
+  }
+  if (parsed.options.writeConfig) {
+    await writeConfigSkeleton(parsed.options.appDir);
     return;
   }
   if (!hasHeapHeadroom()) {
@@ -98,6 +594,7 @@ async function main() {
     ...options.requests !== null && { loadRequests: options.requests },
     ...options.connections !== null && { connections: options.connections },
     ...options.idleSeconds !== null && { idleMs: options.idleSeconds * 1e3 },
+    ...options.warmupRequests !== null && { warmupRequests: options.warmupRequests },
     ...options.maxOldSpaceMb !== null && { maxOldSpaceMb: options.maxOldSpaceMb },
     ...options.diffAll && { diffAll: true },
     ...options.noResolve && { resolveInconclusive: false },
@@ -107,6 +604,11 @@ async function main() {
   console.log(formatReport(report));
   if (aborter.signal.aborted) {
     process.exitCode = 130;
+    return;
+  }
+  if (!report.routes.some((route) => route.status === "measured")) {
+    console.error("error: no route was measured \u2014 nothing above is a verdict about your app");
+    process.exitCode = 1;
   }
 }
 try {

package/dist/confidence.d.ts

@@ -15,8 +15,11 @@ import { type TrendResult, type TrendVerdict } from "./trend.js";
  * `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
+ * `warm-up-baseline`    — the baseline sat far above the level the cycles
+ *   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";
+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 MeasurementWarning = {
     code: WarningCode;
     detail: string;
@@ -44,6 +47,8 @@ export type ConfidenceInput = {
     memorySamples?: readonly HeapSample[];
     /** Old-space cap the measured process ran under (MB). */
     maxOldSpaceMb?: number;
+    /** Warm-up requests the run sent before the baseline, for the warm-up check. */
+    warmupRequests?: number;
 };
 /**
  * Cycles a re-measurement uses when a verdict came back `inconclusive` — the

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

package/dist/index.js

@@ -39,13 +39,13 @@ import {
   sourceIndexAt,
   summarizeBaseline,
   validateTarget
-} from "./chunk-IDSNTUKC.js";
+} from "./chunk-AMSDGT3Y.js";
 import {
   renderHtmlReport
-} from "./chunk-NNDGXIGQ.js";
+} from "./chunk-6CJU5TVV.js";
 import {
   classifyTrend
-} from "./chunk-2FZXZLZW.js";
+} from "./chunk-22PBLCGO.js";
 import {
   renderIssueMarkdown
 } from "./chunk-WXAFXVWS.js";

package/dist/isr.d.ts

@@ -0,0 +1,39 @@
+import type { PrerenderManifest } from "./manifests.js";
+/**
+ * The header Next accepts as an authentic revalidation request.
+ *
+ * Sent with the build's own `previewModeId`, it makes the server re-render the
+ * page instead of serving the cached one. Without it, load against an ISR route
+ * exercises the static cache and nothing else — measured on the
+ * vercel/next.js#96533 reproduction, the same app reports `leak` with this
+ * header and `stable` without it.
+ */
+export declare const REVALIDATE_HEADER = "x-prerender-revalidate";
+/**
+ * The revalidation period in force for a route, or null when it has none.
+ *
+ * Accepts either a concrete path (`/posts/post-1`) or a dynamic template
+ * (`/posts/[slug]`): the period lives on concrete entries, and a template
+ * inherits it from any entry whose `srcRoute` points back at it.
+ */
+export declare function revalidateSecondsFor(manifest: PrerenderManifest | undefined, route: string): number | null;
+/** Whether a route is served from the ISR cache and needs driving. */
+export declare function revalidates(manifest: PrerenderManifest | undefined, route: string): boolean;
+export type RevalidationPlan = {
+    kind: "not-isr";
+} | {
+    kind: "drive";
+    headers: Record<string, string>;
+}
+/** ISR, but the manifest cannot supply what an authentic request needs. */
+ | {
+    kind: "cannot-drive";
+    reason: string;
+};
+/**
+ * How to make a route re-render, given what the build tells us.
+ *
+ * A header the user set themselves wins untouched: someone driving a bespoke
+ * revalidation path knows more about it than the manifest does.
+ */
+export declare function planRevalidation(manifest: PrerenderManifest | undefined, route: string, userHeaders: Record<string, string> | undefined): RevalidationPlan;

package/dist/launcher.d.ts

@@ -1,3 +1,4 @@
+import { type ChildProcess } from "node:child_process";
 /**
  * Old-space cap for measured processes, when the caller does not pick one.
  *
@@ -40,6 +41,13 @@ export declare class LaunchError extends Error {
 }
 /** Interrupt safety: no measured-app process may outlive the CLI. */
 export declare function killActiveChildren(): void;
+/**
+ * Puts a process this tool spawned under the same interrupt safety as a
+ * measured app — a build launched by `next-leak build` must not outlive a
+ * Ctrl+C either.
+ */
+export declare function registerChild(child: ChildProcess): void;
+export declare function unregisterChild(child: ChildProcess): void;
 /**
  * Turns a stack dump into a sentence when the cause is recognisable. Seen in
  * the wild: a webpack `output: standalone` build that ships without