@jskit-ai/jskit-catalog 0.2.30 → 0.2.32

package/scripts/test-command.mjs

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { globSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { toPosixPath } from "./files.mjs";
+import { BUDGET_VARIABLE, testConcurrency } from "./test-budget.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.
+
+// 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;
+
+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 };
+}
+
+/**
+ * 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.
+  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 { 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]] };
+
+  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));
+  return {
+    concurrency,
+    alone,
+    runs: [
+      ...(others.length > 0 ? [[...parallel, ...options, ...others]] : []),
+      ["--test", "--test-concurrency=1", ...options, ...aloneFiles]
+    ]
+  };
+}
+
+function runNode(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, { stdio: "inherit" });
+    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.
+ * @param {string[]} args
+ */
+async function runTests(args) {
+  const plan = planTestRuns(args);
+  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`);
+  for (const { file, reason } of plan.alone) process.stderr.write(`jskit test: ${file} runs alone: ${reason}\n`);
+  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;
+  }
+  return exitCode;
+}
+
+export { planTestRuns, runTests };

package/scripts/test-runs.mjs

@@ -0,0 +1,148 @@
+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.
+
+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 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
+  }
+});
+
+// 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 (!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 === "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.");
+        }
+        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 };

package/scripts/verify-packages.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { globSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -8,6 +9,8 @@ import {
   discoverPackagePatterns
 } from "./pattern-assets.mjs";
 import { collectSingletonPackageIds, discoverFrameworkPackages } from "./framework-packages.mjs";
+import { discoverProjectManifests, readJsonRecord } from "./project-manifests.mjs";
+import { checkTestRuns, formatTestRunsReport } from "./test-runs.mjs";
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(SCRIPT_PATH), "../../..");
@@ -352,6 +355,23 @@ function validateSingletonPeerDependencies(packages) {
   }
 }
 
+// JSKIT's own package scripts and every pattern example an application copies run tests within the test budget.
+async function verifyTestRuns() {
+  const examples = globSync("packages/*/patterns/*/example/**/package.json", {
+    cwd: REPO_ROOT,
+    exclude: (name) => path.basename(name) === "node_modules"
+  });
+  const manifests = [
+    ...await discoverProjectManifests(REPO_ROOT),
+    ...await Promise.all(examples.sort().map((file) => readJsonRecord(path.join(REPO_ROOT, file))))
+  ];
+  const result = await checkTestRuns({ projectRoot: REPO_ROOT, manifests });
+  if (!result.ok) {
+    throw new Error(formatTestRunsReport(result));
+  }
+  return result.manifests;
+}
+
 async function main() {
   const packages = await discoverFrameworkPackages(PACKAGES_ROOT);
   const localVersions = new Map(packages.map(({ packageJson }) => [packageJson.name, packageJson.version]));
@@ -366,9 +386,11 @@ async function main() {
     serverProviderCount += packageResult.serverProviderCount;
   }
   assertUniquePatternIds(patterns);
+  const testManifests = await verifyTestRuns();
   process.stdout.write(
     `Verified ${packages.length} JSKIT runtime packages, ${serverProviderCount} loadable server providers, ` +
-    `${patterns.length} patterns, and ${migrationOwners.size} loadable package migrations.\n`
+    `${patterns.length} patterns, ${migrationOwners.size} loadable package migrations, and the test runs of ` +
+    `${testManifests} manifests.\n`
   );
 }