@jskit-ai/jskit-catalog 0.2.32 → 0.2.34

package/scripts/test-command.mjs

@@ -1,19 +1,36 @@
 import { spawn } from "node:child_process";
-import { globSync, readFileSync } from "node:fs";
+import { globSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import { pathToFileURL } from "node:url";
 import { toPosixPath } from "./files.mjs";
 import { BUDGET_VARIABLE, testConcurrency } from "./test-budget.mjs";
+import { DATABASES_OPTION, testDatabaseRunFor } from "./test-databases.mjs";
+import { STOPS_VARIABLE } from "./test-file-stop.mjs";
+import { reportTestTimes, writeFileStops } from "./test-time-report.mjs";
 
 // `jskit test [node options] [files or globs]`: node --test, running test files in parallel within the machine's test
 // budget (test-budget.mjs). Its arguments go to node --test unchanged. A file that truly must run alone says why on its
-// first line, `// jskit-test: alone - <reason>`, and runs after the others, one such file at a time.
+// first line, `// jskit-test: alone - <reason>`, and runs after the others, one such file at a time. That second run
+// writes a reporter's file destination beside the first run's (`<name>.alone<ext>`) instead of over it, and with
+// --test-shard=<index>/<total> it runs only its shard's alone files, picked the way node --test picks a shard's files.
+// Every run also reports to test-time-report.mjs, which times the command's files against coarse bounds, and preloads
+// test-file-stop.mjs, which stops a file still running at a generous multiple of its time.
 
 // node --test's own default (Node 26) when it is given no files.
 const DEFAULT_PATTERN = "**/{test,test/**/*,test-*,*[._-]test}.{js,mjs,cjs,ts,mts,cts}";
 const MARKER = /^\s*\/\/\s*jskit-test:(.*)$/u;
 const ALONE = /^\s*alone\s+-\s+(\S.*)$/u;
+const SHARD = "--test-shard";
+const REPORTER = "--test-reporter";
+const DESTINATION = "--test-reporter-destination";
+const TIME_REPORTER = new URL("./test-time-report.mjs", import.meta.url).href;
+const FILE_STOP = new URL("./test-file-stop.mjs", import.meta.url).href;
+// Every test file's process compiles the same modules; Node's compile cache keeps them for the next process and run.
+// A cache the environment names, or NODE_DISABLE_COMPILE_CACHE=1, wins.
+const COMPILE_CACHE = path.join("node_modules", ".cache", "jskit-node-compile-cache");
+const STREAM_DESTINATIONS = new Set(["stdout", "stderr"]);
 
 function findTestFiles(patterns, cwd) {
   const entries = globSync(patterns, { cwd, withFileTypes: true, exclude: (entry) => entry.name === "node_modules" });
@@ -46,6 +63,41 @@ function readAloneFiles(files, cwd) {
   return { alone, problems };
 }
 
+/** A reporter's file destination for the alone run, beside the parallel run's: `<name>.alone<ext>`; streams stay. */
+function aloneDestination(destination) {
+  if (STREAM_DESTINATIONS.has(destination)) return destination;
+  const { dir, name, ext } = path.parse(destination);
+  return path.join(dir, `${name}.alone${ext}`);
+}
+
+/**
+ * The alone run's options: the parallel run's, with each file destination moved beside it and without the shard, which
+ * `aloneShard` has already applied to the alone files.
+ * @param {string[]} options
+ */
+function aloneRunOptions(options) {
+  const result = [];
+  for (let index = 0; index < options.length; index += 1) {
+    const option = options[index];
+    if (option === SHARD) index += 1;
+    else if (option.startsWith(`${SHARD}=`)) continue;
+    else if (option === DESTINATION && index + 1 < options.length) {
+      result.push(option, aloneDestination(options[index + 1]));
+      index += 1;
+    } else if (option.startsWith(`${DESTINATION}=`)) result.push(`${DESTINATION}=${aloneDestination(option.slice(DESTINATION.length + 1))}`);
+    else result.push(option);
+  }
+  return result;
+}
+
+/** The alone files of this run's shard (`--test-shard=<index>/<total>`), as node --test picks a shard's files. */
+function aloneShard(files, options) {
+  const at = options.findIndex((option) => option === SHARD || option.startsWith(`${SHARD}=`));
+  if (at < 0) return files;
+  const [index, total] = (options[at] === SHARD ? options[at + 1] : options[at].slice(SHARD.length + 1)).split("/").map(Number);
+  return files.filter((_, position) => position % total === index - 1);
+}
+
 /**
  * The node --test runs for these arguments: one in parallel within the budget, then the files that must run alone.
  * @param {string[]} args the arguments after `jskit test`
@@ -56,32 +108,55 @@ function planTestRuns(args, { cwd = process.cwd(), concurrency = testConcurrency
     throw new Error("jskit test takes the test concurrency from the machine's budget; remove --test-concurrency.");
   }
   const candidates = args.filter((argument) => !argument.startsWith("-"));
-  // An argument that matches no file is an option's value (--test-reporter spec) or a typo node reports itself.
+  // An argument that matches no file is an option's value (--test-reporter spec) or a typo node reports itself; with
+  // none that matches, the run is node's default files.
   const matched = new Map(candidates.map((candidate) => [candidate, findTestFiles([candidate], cwd)]));
-  const files = candidates.length > 0
-    ? [...new Set([...matched.values()].flat())].sort()
-    : findTestFiles([DEFAULT_PATTERN], cwd);
+  const named = [...new Set([...matched.values()].flat())].sort();
+  const files = named.length > 0 ? named : findTestFiles([DEFAULT_PATTERN], cwd);
   const { alone, problems } = readAloneFiles(files, cwd);
   if (problems.length > 0) throw new Error(`jskit test:\n- ${problems.join("\n- ")}`);
   const parallel = ["--test", `--test-concurrency=${concurrency}`];
-  if (alone.length < 1) return { concurrency, alone, runs: [[...parallel, ...args]] };
+  if (alone.length < 1) return { concurrency, files: files.length, paths: files, alone, runs: [[...parallel, ...args]] };
 
   const options = args.filter((argument) => !(matched.get(argument)?.length > 0));
   const aloneFiles = new Set(alone.map((entry) => entry.file));
   const others = files.filter((file) => !aloneFiles.has(file));
+  const shardAlone = aloneShard([...aloneFiles], options);
   return {
     concurrency,
+    files: others.length,
+    paths: files,
     alone,
     runs: [
       ...(others.length > 0 ? [[...parallel, ...options, ...others]] : []),
-      ["--test", "--test-concurrency=1", ...options, ...aloneFiles]
+      ...(shardAlone.length > 0 ? [["--test", "--test-concurrency=1", ...aloneRunOptions(options), ...shardAlone]] : [])
     ]
   };
 }
 
-function runNode(args) {
+/**
+ * The run with the time reporter added before its own options (node takes the arguments after a file as files), writing
+ * to `destination`. Node pairs reporters and destinations by position, and gives a run with no reporter `spec` on
+ * stdout, and a lone reporter with no destination stdout; the run keeps those.
+ * @param {string[]} run ["--test", "--test-concurrency=<n>", ...its options and files]
+ */
+function withTimeReporter(run, destination) {
+  const count = (option) => run.filter((argument) => argument === option || argument.startsWith(`${option}=`)).length;
+  const reporters = count(REPORTER);
+  const destinations = count(DESTINATION);
+  return [
+    ...run.slice(0, 2),
+    ...(reporters === 0 && destinations === 0 ? [`${REPORTER}=spec`, `${DESTINATION}=stdout`] : []),
+    `${REPORTER}=${TIME_REPORTER}`,
+    `${DESTINATION}=${destination}`,
+    ...(reporters === 1 && destinations === 0 ? [`${DESTINATION}=stdout`] : []),
+    ...run.slice(2)
+  ];
+}
+
+function runNode(args, env) {
   return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, args, { stdio: "inherit" });
+    const child = spawn(process.execPath, args, { stdio: "inherit", env: { ...process.env, ...env } });
     const forward = (signal) => child.kill(signal);
     process.on("SIGINT", forward);
     process.on("SIGTERM", forward);
@@ -95,22 +170,54 @@ function runNode(args) {
 }
 
 /**
- * Runs `jskit test` and resolves to its exit code: the first failing run's, or 0.
+ * Runs `jskit test` and resolves to its exit code: the first failing run's, or 0. With `--databases`, each file running
+ * at once has a test database of its own (test-databases.mjs), and the run's concurrency is how many there are.
  * @param {string[]} args
  */
 async function runTests(args) {
-  const plan = planTestRuns(args);
+  const nodeArgs = args.filter((argument) => argument !== DATABASES_OPTION);
+  let plan = planTestRuns(nodeArgs);
   const source = process.env[BUDGET_VARIABLE] ? BUDGET_VARIABLE : "half of this machine";
-  process.stderr.write(`jskit test: ${plan.concurrency} test file(s) at a time (${source}).\n`);
+  // A database for each file that can run at once: a focused run of one file prepares one.
+  const databases = nodeArgs.length < args.length
+    ? await testDatabaseRunFor(Math.max(1, Math.min(plan.concurrency, plan.files)))
+    : null;
+  if (databases) {
+    process.stderr.write(`jskit test: ${databases.summary}.\n`);
+    plan = planTestRuns(nodeArgs, { concurrency: databases.concurrency });
+  }
+  process.stderr.write(`jskit test: ${plan.concurrency} test file(s) at a time (${databases ? "test databases" : source}).\n`);
   for (const { file, reason } of plan.alone) process.stderr.write(`jskit test: ${file} runs alone: ${reason}\n`);
+  const preload = [...(databases?.preload ? ["--import", pathToFileURL(databases.preload).href] : []), "--import", FILE_STOP];
+  const timesDirectory = mkdtempSync(path.join(os.tmpdir(), "jskit-test-times-"));
+  const stops = writeFileStops({ cwd: process.cwd(), files: plan.paths, directory: timesDirectory });
+  const collected = plan.runs.map((_run, index) => path.join(timesDirectory, `run-${index}.json`));
+  const started = performance.now();
   let exitCode = 0;
-  for (const run of plan.runs) {
-    const { code, signal } = await runNode(run);
-    if (exitCode === 0) exitCode = code;
-    // An interrupted run ends the whole command.
-    if (signal) break;
+  let interrupted = false;
+  try {
+    for (const [index, run] of plan.runs.entries()) {
+      const env = {
+        NODE_COMPILE_CACHE: process.env.NODE_COMPILE_CACHE || path.resolve(COMPILE_CACHE),
+        [STOPS_VARIABLE]: stops,
+        ...databases?.env
+      };
+      const { code, signal } = await runNode([...preload, ...withTimeReporter(run, collected[index])], env);
+      if (exitCode === 0) exitCode = code;
+      // An interrupted run ends the whole command.
+      interrupted = Boolean(signal);
+      if (interrupted) break;
+    }
+    const times = interrupted
+      ? null
+      : reportTestTimes({ cwd: process.cwd(), collected, directory: timesDirectory, wallMs: performance.now() - started });
+    if (times) process.stderr.write(times.report);
+    if (times?.overruns.length > 0 && exitCode === 0) exitCode = 1;
+  } finally {
+    databases?.cleanup();
+    rmSync(timesDirectory, { recursive: true, force: true });
   }
   return exitCode;
 }
 
-export { planTestRuns, runTests };
+export { planTestRuns, runTests, withTimeReporter };

package/scripts/test-databases.mjs

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+// `jskit test --databases`: each test file running at once gets a database of its own, a copy of TEST_DB_NAME restored
+// from a schema snapshot, from the application's installed @jskit-ai/database-runtime and its knexfile.js, which loads
+// .env and fixes the dialect. JSKIT's catalog itself depends on no database package. What the knexfile loads into the
+// environment is read for the databases only: the test files get the environment `jskit test` was given, plus their
+// own database and its connection (DB_NAME, TEST_DB_NAME, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD). A knexfile whose
+// schema the migrations alone do not build also exports `testDatabaseSchema` ({ files, build }, see testDatabases.js).
+const OPTION = "--databases";
+const KNEXFILES = Object.freeze(["knexfile.js", "knexfile.mjs", "knexfile.cjs"]);
+const TEST_DATABASES = "@jskit-ai/database-runtime/server/testDatabases";
+
+/** Runs `load` and puts process.env back as it was, returning what `load` returned and the environment it saw. */
+async function withOwnEnvironment(load) {
+  const before = { ...process.env };
+  try {
+    const result = await load();
+    return { result, environment: { ...process.env } };
+  } finally {
+    for (const name of Object.keys(process.env)) if (!Object.hasOwn(before, name)) delete process.env[name];
+    Object.assign(process.env, before);
+  }
+}
+
+/**
+ * The run's databases for `count` files at once, or one file at a time on the connected database.
+ * @param {number} count at most the run's test budget, and no more than its test files
+ * @param {string} [cwd]
+ * @returns {Promise<{ concurrency: number, env: Record<string, string>, preload: string, summary: string, cleanup(): void }>}
+ */
+async function testDatabaseRunFor(count, cwd = process.cwd()) {
+  const knexfile = KNEXFILES.map((name) => path.join(cwd, name)).find((file) => existsSync(file));
+  if (!knexfile) throw new Error(`jskit test ${OPTION} reads the application's knexfile.js, and ${cwd} has none.`);
+  let testDatabases;
+  try {
+    testDatabases = createRequire(path.join(cwd, "package.json")).resolve(TEST_DATABASES);
+  } catch {
+    throw new Error(`jskit test ${OPTION} needs ${TEST_DATABASES}; install the application's JSKIT database driver.`);
+  }
+  const { result: { default: knexConfig, testDatabaseSchema: schema }, environment } = await withOwnEnvironment(async () =>
+    import(pathToFileURL(knexfile).href));
+  const { testDatabaseRun } = await import(pathToFileURL(testDatabases).href);
+  return testDatabaseRun({ knexConfig, environment, count, schema, appRoot: cwd });
+}
+
+export { OPTION as DATABASES_OPTION, testDatabaseRunFor };

package/scripts/test-file-stop.mjs

@@ -0,0 +1,32 @@
+// Preloaded (`--import`) by `jskit test` into every process of its node --test runs. In a test file's own process
+// (node --test starts one per file, with NODE_TEST_CONTEXT set), it stops the file at the time `jskit test` gave it
+// (fileStop in test-time-report.mjs): a file that never finishes, because a test has no timeout or a server, child
+// process, timer or socket was left open, then fails by name and the rest of the run still finishes and reports. The
+// runner's own process, worker threads and the processes a test starts do nothing.
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { isMainThread } from "node:worker_threads";
+
+const STOPS_VARIABLE = "JSKIT_TEST_FILE_STOPS";
+const STOPPED_PREFIX = "stopped-";
+
+const stopsFile = process.env[STOPS_VARIABLE];
+const runsTestFiles = process.execArgv.some((argument) => argument === "--test" || argument.startsWith("--test="));
+if (stopsFile && isMainThread && process.env.NODE_TEST_CONTEXT && !runsTestFiles) {
+  // A process this file starts is not one of the run's files.
+  delete process.env[STOPS_VARIABLE];
+  const stop = JSON.parse(readFileSync(stopsFile, "utf8"))[path.resolve(process.argv[1] || "")];
+  if (stop) {
+    const started = performance.now();
+    // Unreferenced: a file that finishes exits as it would have.
+    setTimeout(() => {
+      const stopped = { ...stop, ms: Math.round(performance.now() - started) };
+      writeFileSync(path.join(path.dirname(stopsFile), `${STOPPED_PREFIX}${process.pid}.json`), JSON.stringify(stopped));
+      writeFileSync(2, `\njskit test: stopped ${stopped.file} after ${(stopped.ms / 1000).toFixed(1)} s, ${stopped.reason}.\n`);
+      process.exit(1);
+    }, stop.ms).unref();
+  }
+}
+
+export { STOPPED_PREFIX, STOPS_VARIABLE };

package/scripts/test-runs.mjs

@@ -6,9 +6,16 @@ import { fileExists, toPosixPath } from "./files.mjs";
 // file at a time nor overwhelms the machine. A package script runs node's test runner through `jskit test`, passes no
 // fixed worker count, and the Playwright and Vitest configs its scripts use set their workers from testConcurrency().
 // The one exception is a test file's own first line, `// jskit-test: alone - <reason>`, which `jskit test` honours.
+// A Playwright config those scripts use bounds its whole run (globalTimeout) and, when it starts the app (webServer),
+// does so through browserTestConfig(): the production build, and a server, port and database for each worker.
 
 const GUIDE = "https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features#test-files-run-in-parallel";
 const BUDGET_MODULE = "@jskit-ai/jskit-catalog/test-budget";
+const BROWSER_TESTS_MODULE = "@jskit-ai/jskit-catalog/browser-tests";
+// `npm run develop`, `npm run dev[:surface]`, `node ./bin/develop.js`, `vite` and `vite dev`/`vite serve`: not
+// `vite build` or `vite preview`.
+const DEVELOPMENT_SERVER = /\bnpm\s+run\s+(?:develop|dev(?::[\w-]+)?)(?:\s|$)|\bbin\/develop\.js\b|(?:^|[\s/])vite(?:\s+(?:dev|serve)\b|\s+-|\s*$)/u;
+const PINNED_BUDGET = /^(?:V64_TEST_CONCURRENCY|PLAYWRIGHT_WORKERS)=/u;
 const CONFIG_EXTENSIONS = Object.freeze(["ts", "mts", "cts", "js", "mjs", "cjs"]);
 const SCRIPT_FILE = /\.(?:[cm]?[jt]s|jsx|tsx)$/u;
 const FIXED_PLAYWRIGHT_WORKERS = /^(?:--workers(?:=.*)?|-j.*)$/u;
@@ -79,6 +86,43 @@ const RUNNERS = Object.freeze({
   }
 });
 
+// The browser-test harness: one production-build server, port and database per Playwright worker, its workers from the
+// budget and a globalTimeout.
+const usesBrowserHarness = (source) => source.includes(BROWSER_TESTS_MODULE) && /\bbrowserTestConfig\s*\(/u.test(source);
+
+// A webServer command that runs the development server instead of the production build.
+function developmentServerCommand(source) {
+  for (const [, , command] of String(source).matchAll(/\bcommand\s*:\s*(["'`])(.*?)\1/gu)) {
+    if (DEVELOPMENT_SERVER.test(command)) return command;
+  }
+  return "";
+}
+
+// A Playwright config tests the production build, gives each worker its own server and data, and bounds the whole run.
+function checkPlaywrightIsolation({ file, source, report }) {
+  const harness = `use browserTestConfig() from ${BROWSER_TESTS_MODULE}`;
+  const command = developmentServerCommand(source);
+  if (command) {
+    report({ file, line: lineOf(source, command), rule: "test/playwright-dev-server",
+      message: `webServer runs the development server (${command}); ${harness}, which serves the production build.` });
+  }
+  if (usesBrowserHarness(source)) {
+    if (/\bglobalTimeout\s*:\s*0\b/u.test(source)) {
+      report({ file, line: lineOf(source, "globalTimeout"), rule: "test/playwright-global-timeout",
+        message: "globalTimeout: 0 lets a run go on for hours; keep the harness's bound." });
+    }
+    return;
+  }
+  if (/\bwebServer\b/u.test(source) && !/\bworkers\s*:\s*1\b/u.test(source)) {
+    report({ file, line: lineOf(source, "webServer"), rule: "test/playwright-isolation",
+      message: `Playwright workers share one webServer and its database; ${harness}, which gives each worker its own.` });
+  }
+  if (!/\bglobalTimeout\s*:\s*[1-9]/u.test(source)) {
+    report({ file, line: lineOf(source, "globalTimeout"), rule: "test/playwright-global-timeout",
+      message: `nothing bounds the whole run; ${harness}, or set a globalTimeout.` });
+  }
+}
+
 // A config sets the runner's workers from the budget, and Vitest's never turns file parallelism off.
 async function checkRunnerConfig({ root, configPath, directory, runner, report }) {
   const { rule, setting, configNames } = RUNNERS[runner];
@@ -91,9 +135,16 @@ async function checkRunnerConfig({ root, configPath, directory, runner, report }
   }
   const file = toPosixPath(path.relative(root, configPath));
   const source = await readFile(configPath, "utf8");
-  if (!source.includes(BUDGET_MODULE) || !new RegExp(`\\b${setting}\\s*:\\s*testConcurrency\\(\\s*\\)`, "u").test(source)) {
+  if (runner === "playwright" && usesBrowserHarness(source)) {
+    // The harness takes its workers from the budget; a config that sets them itself overrides it.
+    if (/\bworkers\s*:/u.test(source)) {
+      report({ file, line: lineOf(source, "workers:"), rule,
+        message: "playwright's workers are set over browserTestConfig()'s; drop them, so the machine's test budget sets them." });
+    }
+  } else if (!source.includes(BUDGET_MODULE) || !new RegExp(`\\b${setting}\\s*:\\s*testConcurrency\\(\\s*\\)`, "u").test(source)) {
     report({ file, line: lineOf(source, `${setting}:`), rule, message: `${runner} runs at a fixed or default worker count; ${wanted}.` });
   }
+  if (runner === "playwright") checkPlaywrightIsolation({ file, source, report });
   if (runner === "vitest" && /\bfileParallelism\s*:\s*false\b/u.test(source)) {
     report({ file, line: lineOf(source, "fileParallelism"), rule,
       message: "Vitest runs one file at a time; remove fileParallelism: false and isolate the files instead." });
@@ -119,6 +170,10 @@ async function checkTestRuns({ projectRoot, manifests }) {
         if (tokens.some((token) => /^--test-concurrency(?:=|$)/u.test(token))) {
           at("test/fixed-concurrency", "sets --test-concurrency; drop it, so `jskit test` takes the concurrency from the machine's test budget.");
         }
+        const pinned = tokens.find((token) => PINNED_BUDGET.test(token));
+        if (pinned) {
+          at("test/fixed-concurrency", `pins ${pinned.split("=")[0]}; drop it, so the test runner or the machine sets the budget.`);
+        }
         for (const runner of Object.keys(RUNNERS)) {
           const args = runnerArguments(tokens, runner);
           if (!args) continue;

package/scripts/test-time-report.mjs

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { toPosixPath } from "./files.mjs";
+import { STOPPED_PREFIX } from "./test-file-stop.mjs";
+
+// How long `jskit test` took, file by file. The node --test reporter below runs beside a run's own reporters and writes
+// the run's file and top-level test durations to the file `jskit test` names. After its last run, `jskit test` lists the
+// ten slowest files and tests, records each file's time in node_modules/.cache/jskit-test/file-times.json, and fails
+// when a file or the whole command went past a coarse bound that only a clearly broken suite reaches: a file waiting
+// out its timeouts, a suite that would run for hours. An application whose measured suite needs more writes its own
+// bounds in test-time-bounds.json, `{ "runMs": ..., "fileMs": ..., "files": { "<path>": ... } }`, with the measurement.
+// A file that has not finished by a generous multiple of its time is stopped while it runs (test-file-stop.mjs), so
+// one file that never ends fails by name instead of holding up the whole run until a runner's own ceiling ends it.
+const SHOWN = 10;
+// Stops a file at twice its bound (at least two seconds, well past any file's start-up), or at ten times its recorded
+// time (at least two minutes, more than a cold compile cache or a loaded machine needs), whichever comes first. A file
+// with its own bound in test-time-bounds.json is stopped at twice that bound.
+const STOP_BOUND_TIMES = 2;
+const STOP_BOUND_MIN_MS = 2000;
+const STOP_RECORDED_TIMES = 10;
+const STOP_RECORDED_MIN_MS = 2 * 60_000;
+const BOUNDS_FILE = "test-time-bounds.json";
+const DEFAULT_BOUNDS = Object.freeze({ runMs: 45 * 60_000, fileMs: 10 * 60_000, files: Object.freeze({}) });
+const FILE_TIMES = path.join("node_modules", ".cache", "jskit-test", "file-times.json");
+
+const seconds = (ms) => (ms >= 60_000 ? `${(ms / 60_000).toFixed(1)} min` : `${(ms / 1000).toFixed(1)} s`);
+
+/** @param {AsyncIterable<{ type: string, data: any }>} source node --test's events */
+export default async function* collectTestTimes(source) {
+  const relative = (file) => toPosixPath(path.relative(process.cwd(), file));
+  const files = {};
+  const tests = [];
+  // Files that skipped a test: their time says little about how long they take when every test runs.
+  const skipped = new Set();
+  for await (const event of source) {
+    if (event.type === "test:summary" && event.data.file) {
+      files[relative(event.data.file)] = event.data.duration_ms;
+    } else if ((event.type === "test:pass" || event.type === "test:fail") && event.data.file) {
+      if (event.data.skip != null && event.data.skip !== false) skipped.add(relative(event.data.file));
+      if (event.data.nesting === 0) {
+        tests.push({ file: relative(event.data.file), name: event.data.name, ms: event.data.details?.duration_ms ?? 0 });
+      }
+    }
+  }
+  yield `${JSON.stringify({ files, tests, skipped: [...skipped] })}\n`;
+}
+
+/** The application's bounds over JSKIT's defaults; each must be a positive number of milliseconds. */
+function readTestTimeBounds(cwd) {
+  const file = path.join(cwd, BOUNDS_FILE);
+  if (!existsSync(file)) return DEFAULT_BOUNDS;
+  const own = JSON.parse(readFileSync(file, "utf8"));
+  const bounds = { ...DEFAULT_BOUNDS, ...own, files: { ...own.files } };
+  for (const [name, ms] of [["runMs", bounds.runMs], ["fileMs", bounds.fileMs], ...Object.entries(bounds.files)]) {
+    if (!(Number.isFinite(ms) && ms > 0)) throw new Error(`${BOUNDS_FILE}: ${name} must be a positive number of milliseconds.`);
+  }
+  return bounds;
+}
+
+/**
+ * When a file still running is stopped, and why: twice its bound, or ten times its recorded time when that comes first.
+ * @param {{ bound: number, recorded?: number }} times milliseconds; `recorded` is the file's last time, if any
+ * @returns {{ ms: number, reason: string }}
+ */
+function fileStop({ bound, recorded }) {
+  const byBound = Math.max(STOP_BOUND_MIN_MS, STOP_BOUND_TIMES * bound);
+  const byRecorded = recorded > 0 ? Math.max(STOP_RECORDED_MIN_MS, STOP_RECORDED_TIMES * recorded) : Infinity;
+  return byRecorded < byBound
+    ? { ms: byRecorded, reason: `past ten times its last time of ${seconds(recorded)}` }
+    : { ms: byBound, reason: `past twice its ${seconds(bound)} bound` };
+}
+
+/**
+ * Writes when each of the run's files is stopped, keyed by its absolute path, for test-file-stop.mjs; returns the file.
+ * @param {{ cwd: string, files: string[], directory: string }} options `files`: the run's test files, relative to cwd
+ */
+function writeFileStops({ cwd, files, directory }) {
+  const bounds = readTestTimeBounds(cwd);
+  const record = path.join(cwd, FILE_TIMES);
+  const recorded = existsSync(record) ? JSON.parse(readFileSync(record, "utf8")) : {};
+  const stops = Object.fromEntries(files.map((file) => [
+    path.resolve(cwd, file),
+    // A file's own bound is the application's measured statement of its time, so it alone sets the stop.
+    { file, ...fileStop(file in bounds.files ? { bound: bounds.files[file] } : { bound: bounds.fileMs, recorded: recorded[file] }) }
+  ]));
+  const stopsFile = path.join(directory, "file-stops.json");
+  writeFileSync(stopsFile, JSON.stringify(stops));
+  return stopsFile;
+}
+
+/**
+ * The slowest files and tests of a `jskit test` command against its bounds, and the bounds it went past.
+ * @param {{ bounds: { runMs: number, fileMs: number, files: Record<string, number> }, files: Record<string, number>,
+ *   tests: Array<{ file: string, name: string, ms: number }>, wallMs: number,
+ *   stopped?: Array<{ file: string, ms: number, reason: string }> }} times `stopped`: the files stopped while running
+ */
+function checkTestTimes({ bounds, files, tests, wallMs, stopped = [] }) {
+  const rows = Object.entries(files).map(([name, ms]) => ({ name, ms, bound: bounds.files[name] ?? bounds.fileMs }));
+  const overruns = [
+    ...stopped.map((stop) => `${stop.file} was stopped after ${seconds(stop.ms)}, ${stop.reason}: it did not finish.`),
+    ...rows.filter((row) => row.ms > row.bound && !stopped.some((stop) => stop.file === row.name))
+      .map((row) => `${row.name} took ${seconds(row.ms)}, past its ${seconds(row.bound)} bound.`)
+  ];
+  if (wallMs > bounds.runMs) overruns.push(`The run took ${seconds(wallMs)}, past its ${seconds(bounds.runMs)} bound.`);
+  const lines = [
+    `jskit test: ${rows.length} test file(s) in ${seconds(wallMs)} (bound ${seconds(bounds.runMs)}); the slowest, time / bound:`,
+    ...rows.sort((a, b) => b.ms - a.ms).slice(0, SHOWN).map((row) => `  ${seconds(row.ms)} / ${seconds(row.bound)}  ${row.name}`),
+    "jskit test: the slowest tests:",
+    ...[...tests].sort((a, b) => b.ms - a.ms).slice(0, SHOWN)
+      .map((entry) => `  ${seconds(entry.ms)}  ${entry.file}: ${entry.name.slice(0, 120)}`)
+  ];
+  if (overruns.length > 0) {
+    lines.push(
+      "jskit test: past a time bound, so something is clearly broken:",
+      ...overruns.map((overrun) => `  ${overrun}`),
+      `Find what got slow and fix it; raise a bound in ${BOUNDS_FILE} only when the work itself grew, with the measurement.`
+    );
+  }
+  return { overruns, report: `${lines.join("\n")}\n` };
+}
+
+/**
+ * Reads what the runs' reporters wrote and which files test-file-stop.mjs stopped, records each finished file's time
+ * for the next command (a stopped file, or one that skipped a test, keeps the time it last finished all its tests in,
+ * since the next stop is reckoned from it), and checks the times. A run whose
+ * reporters were replaced (inside another node --test run) wrote nothing, and has no report unless a file was stopped.
+ * @param {{ cwd: string, collected: string[], directory: string, wallMs: number }} options `collected`: the reporters'
+ *   destination files; `directory`: where the stopped files are written
+ * @returns {{ overruns: string[], report: string } | null}
+ */
+function reportTestTimes({ cwd, collected, directory, wallMs }) {
+  const runs = collected.filter((file) => existsSync(file) && readFileSync(file, "utf8").trim())
+    .map((file) => JSON.parse(readFileSync(file, "utf8")));
+  const stopped = readdirSync(directory).filter((name) => name.startsWith(STOPPED_PREFIX)).sort()
+    .map((name) => JSON.parse(readFileSync(path.join(directory, name), "utf8")));
+  const files = Object.assign({}, ...runs.map((run) => run.files));
+  if (Object.keys(files).length === 0 && stopped.length === 0) return null;
+  const unrepresentative = new Set([...stopped.map((stop) => stop.file), ...runs.flatMap((run) => run.skipped ?? [])]);
+  const finished = Object.fromEntries(Object.entries(files).filter(([name]) => !unrepresentative.has(name)));
+  const record = path.join(cwd, FILE_TIMES);
+  const recorded = existsSync(record) ? JSON.parse(readFileSync(record, "utf8")) : {};
+  mkdirSync(path.dirname(record), { recursive: true });
+  // Written whole, then renamed, so a command beside this one never reads half a file.
+  writeFileSync(`${record}.${process.pid}`, `${JSON.stringify({ ...recorded, ...finished }, null, 2)}\n`);
+  renameSync(`${record}.${process.pid}`, record);
+  return checkTestTimes({ bounds: readTestTimeBounds(cwd), files, tests: runs.flatMap((run) => run.tests), wallMs, stopped });
+}
+
+export { BOUNDS_FILE, FILE_TIMES, checkTestTimes, fileStop, reportTestTimes, writeFileStops };