@jskit-ai/jskit-catalog 0.2.31 → 0.2.33

package/scripts/package-routes.mjs

@@ -0,0 +1,93 @@
+// The pages an app's own packages give the router, for the navigation rules: each package.json route in
+// jskit.metadata.ui.routes with the component its client entry's routeComponents names.
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_IMPORT, balancedFrom, blankJsComments, enclosingObject, localComponent } from "./material3-source.mjs";
+
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const ROUTE_COMPONENTS = /\brouteComponents\s*=\s*(?:Object\s*\.\s*freeze\s*\(\s*)?(?=\{)/u;
+// One routeComponents entry: `key: () => import("./page.vue")` or `"key": ImportedPage`.
+const ROUTE_COMPONENT = /(?<=[{,]\s*)(?:(["'])([^"']+)\1|([A-Za-z_$][\w$]*))\s*:\s*(?:\(\s*\)\s*=>\s*import\s*\(\s*(["'])([^"']+)\4\s*\)|([A-Za-z_$][\w$]*))(?=\s*[,}])/gu;
+
+// The file a package's "./client" export names, relative to the app: packages/shelves/src/client/index.js.
+function clientEntryOf(manifest, directory) {
+  const target = manifest?.exports?.["./client"];
+  const entry = typeof target === "string" ? target : target?.import || target?.default;
+  return typeof entry === "string" ? path.posix.join(directory, entry) : "";
+}
+
+// The app's .vue file of each routeComponents key in a client entry, from its literal map: an entry another module
+// builds, or one naming a file outside the app, has none.
+function readRouteComponents(entry, code, known) {
+  const components = new Map();
+  const start = ROUTE_COMPONENTS.exec(code);
+  const map = start ? balancedFrom(code, start.index + start[0].length)?.text || "" : "";
+  const imports = new Map([...code.matchAll(DEFAULT_IMPORT)].map(([, name, specifier]) => [name, specifier]));
+  for (const match of map.matchAll(ROUTE_COMPONENT)) {
+    const specifier = match[5] ?? imports.get(match[6]);
+    const file = specifier ? localComponent(entry, specifier, known) : null;
+    if (file) components.set(match[2] ?? match[3], file);
+  }
+  return components;
+}
+
+/**
+ * The pages an app's own packages give the router: each packages/<name>/package.json's jskit.metadata.ui.routes entry
+ * the kernel registers (not autoRegister: false), with the component its client entry's literal routeComponents map
+ * names for componentKey. The kernel adds each at the top level, so no layout renders it: it is under the shell's top
+ * app bar only when its component (or App.vue) draws the bar. Its parent and surface are its meta.jskit, as declared.
+ * @param {string} root
+ * @param {Set<string>} known The app's files; a package whose client entry or component is not among them is skipped.
+ */
+async function readPackageRoutes(root, known) {
+  let directories = [];
+  try {
+    directories = (await readdir(path.join(root, "packages"), { withFileTypes: true })).filter((entry) => entry.isDirectory());
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const pages = [];
+  for (const directory of directories.map((entry) => `packages/${entry.name}`).sort()) {
+    const manifestFile = `${directory}/package.json`;
+    let manifestSource;
+    let manifest;
+    try {
+      manifestSource = await readFile(path.join(root, manifestFile), "utf8");
+      manifest = JSON.parse(manifestSource);
+    } catch (error) {
+      if (error?.code === "ENOENT" || error instanceof SyntaxError) continue;
+      throw error;
+    }
+    const routes = manifest?.jskit?.metadata?.ui?.routes;
+    const entry = clientEntryOf(manifest, directory);
+    if (!Array.isArray(routes) || !known.has(entry)) continue;
+    const components = readRouteComponents(entry, blankJsComments(await readFile(path.join(root, entry), "utf8")), known);
+    for (const route of routes) {
+      const file = isRecord(route) && route.autoRegister !== false ? components.get(String(route.componentKey || "").trim()) : null;
+      if (!file) continue;
+      const id = String(route.id || "").trim();
+      const jskit = isRecord(route.meta?.jskit) ? route.meta.jskit : {};
+      const parent = typeof jskit.parent === "string" ? jskit.parent.trim() : isRecord(jskit.parent) ? jskit.parent : "";
+      // Where package.json declares the route, and its parent, for findings.
+      const declared = new RegExp(String.raw`"id"\s*:\s*${JSON.stringify(id).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}`, "u").exec(manifestSource);
+      const object = declared ? enclosingObject(manifestSource, declared.index) : null;
+      const parentKey = object ? /"parent"\s*:/u.exec(object.text) : null;
+      pages.push({
+        file,
+        manifest: manifestFile,
+        source: manifestSource,
+        id,
+        path: String(route.path || "").trim(),
+        scope: String(route.scope || "surface").trim().toLowerCase() === "global" ? "global" : "surface",
+        surface: String(route.surface || "").trim().toLowerCase(),
+        parent,
+        surfaceRoot: Boolean(jskit.surface),
+        offset: declared?.index ?? 0,
+        parentOffset: parentKey ? object.start + parentKey.index : declared?.index ?? 0
+      });
+    }
+  }
+  return pages;
+}
+
+export { readPackageRoutes };

package/scripts/test-budget.mjs

@@ -0,0 +1,19 @@
+import os from "node:os";
+import process from "node:process";
+
+// The machine's test budget: how many test files (node --test), Playwright workers or Vitest workers a run may use at
+// once. A test runner that hands out slots exports V64_TEST_CONCURRENCY for each run; anywhere else a run takes half
+// of the machine, so a test suite neither runs one file at a time nor overwhelms the machine (a 2-vCPU VPS stays at 1).
+const BUDGET_VARIABLE = "V64_TEST_CONCURRENCY";
+
+/**
+ * @param {{ env?: Record<string, string | undefined>, parallelism?: number }} [options]
+ * @returns {number} a whole number of at least 1
+ */
+function testConcurrency({ env = process.env, parallelism = os.availableParallelism() } = {}) {
+  const configured = String(env[BUDGET_VARIABLE] ?? "").trim();
+  if (/^[1-9]\d*$/u.test(configured)) return Number(configured);
+  return Math.max(1, Math.floor(parallelism / 2));
+}
+
+export { BUDGET_VARIABLE, testConcurrency };

package/scripts/test-command.mjs

@@ -0,0 +1,223 @@
+import { spawn } from "node:child_process";
+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. 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" });
+  const files = entries
+    .filter((entry) => entry.isFile() || entry.isSymbolicLink())
+    .map((entry) => toPosixPath(path.relative(cwd, path.join(entry.parentPath, entry.name))));
+  return [...new Set(files)].sort();
+}
+
+/**
+ * The files of a run that must run alone, from their first line. A marker that is malformed or not on the first line
+ * (after a shebang) is an error, so a file never runs in parallel because its marker was missed.
+ * @returns {{ alone: Array<{ file: string, reason: string }>, problems: string[] }}
+ */
+function readAloneFiles(files, cwd) {
+  const alone = [];
+  const problems = [];
+  for (const file of files) {
+    const lines = readFileSync(path.resolve(cwd, file), "utf8").split("\n");
+    const top = lines[0]?.startsWith("#!") ? 1 : 0;
+    lines.forEach((line, index) => {
+      const marker = MARKER.exec(line);
+      if (!marker) return;
+      const reason = ALONE.exec(marker[1])?.[1]?.trim();
+      if (index !== top) problems.push(`${file}:${index + 1}: a jskit-test marker belongs on the file's first line.`);
+      else if (!reason) problems.push(`${file}:${index + 1}: write it as \`// jskit-test: alone - <why this file cannot run beside others>\`.`);
+      else alone.push({ file, reason });
+    });
+  }
+  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`
+ * @param {{ cwd?: string, concurrency?: number }} [options]
+ */
+function planTestRuns(args, { cwd = process.cwd(), concurrency = testConcurrency() } = {}) {
+  if (args.some((argument) => /^--test-concurrency(?:=|$)/u.test(argument))) {
+    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; with
+  // none that matches, the run is node's default files.
+  const matched = new Map(candidates.map((candidate) => [candidate, findTestFiles([candidate], 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, 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]] : []),
+      ...(shardAlone.length > 0 ? [["--test", "--test-concurrency=1", ...aloneRunOptions(options), ...shardAlone]] : [])
+    ]
+  };
+}
+
+/**
+ * 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", env: { ...process.env, ...env } });
+    const forward = (signal) => child.kill(signal);
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      process.off("SIGINT", forward);
+      process.off("SIGTERM", forward);
+      resolve({ code: code ?? 128 + (os.constants.signals[signal] ?? 0), signal });
+    });
+  });
+}
+
+/**
+ * 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 nodeArgs = args.filter((argument) => argument !== DATABASES_OPTION);
+  let plan = planTestRuns(nodeArgs);
+  const source = process.env[BUDGET_VARIABLE] ? BUDGET_VARIABLE : "half of this machine";
+  // 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;
+  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, 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

@@ -0,0 +1,203 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileExists, toPosixPath } from "./files.mjs";
+
+// The test-run part of plain `jskit check`: every test run uses the machine's test budget, so a suite neither runs one
+// 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;
+const FIXED_VITEST_WORKERS = /^--(?:max-?[wW]orkers|min-?[wW]orkers|no-file-?[pP]arallelism|file-?[pP]arallelism)(?:=.*)?$/u;
+
+function commandsOf(script) {
+  return String(script || "")
+    .split(/&&|\|\||[;|\n]/u)
+    .map((command) => command.trim().split(/\s+/u).map((token) => token.replace(/^['"(]+|['")]+$/gu, "")).filter(Boolean))
+    .filter((tokens) => tokens.length > 0);
+}
+
+const isProgram = (token, name) => token === name || token.endsWith(`/${name}`);
+
+// node's own options come before its script; --test among them runs the test runner.
+function runsNodeTest(tokens) {
+  return tokens.some((token, index) => {
+    if (!isProgram(token, "node")) return false;
+    for (const option of tokens.slice(index + 1)) {
+      if (option === "--test") return true;
+      if (SCRIPT_FILE.test(option)) return false;
+    }
+    return false;
+  });
+}
+
+function runnerArguments(tokens, runner) {
+  const index = tokens.findIndex((token, position) => isProgram(token, runner) &&
+    (runner !== "playwright" || tokens[position + 1] === "test"));
+  return index < 0 ? null : tokens.slice(index + 1);
+}
+
+function configOption(args) {
+  const index = args.findIndex((token) => token === "--config" || token === "-c" || token.startsWith("--config="));
+  if (index < 0) return "";
+  return args[index].startsWith("--config=") ? args[index].slice("--config=".length) : args[index + 1] || "";
+}
+
+function lineOf(contents, needle, after = "") {
+  const text = String(contents);
+  const offset = text.indexOf(needle, after ? Math.max(0, text.indexOf(after)) : 0);
+  return offset < 0 ? 1 : text.slice(0, offset).split("\n").length;
+}
+
+async function findConfig(directory, explicit, names) {
+  if (explicit) return path.resolve(directory, explicit);
+  for (const name of names) {
+    for (const extension of CONFIG_EXTENSIONS) {
+      const candidate = path.join(directory, `${name}.config.${extension}`);
+      if (await fileExists(candidate)) return candidate;
+    }
+  }
+  return "";
+}
+
+const RUNNERS = Object.freeze({
+  playwright: {
+    rule: "test/playwright-workers",
+    configNames: ["playwright"],
+    setting: "workers",
+    fixedArgument: FIXED_PLAYWRIGHT_WORKERS
+  },
+  vitest: {
+    rule: "test/vitest-workers",
+    configNames: ["vitest", "vite"],
+    setting: "maxWorkers",
+    fixedArgument: FIXED_VITEST_WORKERS
+  }
+});
+
+// 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];
+  const wanted = `set \`${setting}: testConcurrency()\` from ${BUDGET_MODULE}`;
+  if (!configPath || !(await fileExists(configPath))) {
+    const missing = configPath || path.join(directory, `${configNames[0]}.config.*`);
+    report({ file: toPosixPath(path.relative(root, missing)), line: 1, rule,
+      message: `A script runs ${runner} without this config: add it and ${wanted}.` });
+    return;
+  }
+  const file = toPosixPath(path.relative(root, configPath));
+  const source = await readFile(configPath, "utf8");
+  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." });
+  }
+}
+
+/**
+ * @param {{ projectRoot: string, manifests: ReadonlyArray<{ absolutePath: string, contents: string, value: object }> }} input
+ */
+async function checkTestRuns({ projectRoot, manifests }) {
+  const root = path.resolve(projectRoot);
+  const findings = [];
+  const report = (finding) => findings.push(finding);
+  const configs = new Map();
+  for (const manifest of manifests) {
+    const file = toPosixPath(path.relative(root, manifest.absolutePath)) || "package.json";
+    const directory = path.dirname(manifest.absolutePath);
+    for (const [name, script] of Object.entries(manifest.value?.scripts || {})) {
+      const line = lineOf(manifest.contents, `"${name}"`, '"scripts"');
+      const at = (rule, message) => report({ file, line, rule, message: `scripts.${name} ${message}` });
+      for (const tokens of commandsOf(script)) {
+        if (runsNodeTest(tokens)) at("test/node-test", "runs node --test directly; use `jskit test`, which runs test files in parallel within the machine's test budget.");
+        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;
+          if (args.some((token) => RUNNERS[runner].fixedArgument.test(token))) {
+            at(RUNNERS[runner].rule, `passes ${runner} a fixed worker count; drop it, so the config's testConcurrency() sets it.`);
+          }
+          const configPath = await findConfig(directory, configOption(args), RUNNERS[runner].configNames);
+          configs.set(`${runner}\0${configPath || directory}`, { runner, configPath, directory });
+        }
+      }
+    }
+  }
+  for (const config of configs.values()) await checkRunnerConfig({ root, report, ...config });
+  findings.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line);
+  return { ok: findings.length < 1, findings, manifests: manifests.length };
+}
+
+function formatTestRunsReport(result) {
+  const lines = result.findings.flatMap(({ file, line, rule, message }) => [`${file}:${line}  ${rule}  ${message}`, `  ${GUIDE}`]);
+  lines.push(result.ok
+    ? `JSKIT test runs use the machine's test budget in ${result.manifests} manifest(s).`
+    : `JSKIT test runs: ${result.findings.length} error(s). Each test run takes its concurrency from the machine's test budget; ` +
+      "a file that must run alone says why on its first line (`// jskit-test: alone - <reason>`).");
+  return lines.join("\n");
+}
+
+export { checkTestRuns, formatTestRunsReport };