@ingenioz-it/caits 0.6.0 → 0.8.0

package/bin/caits.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { commandOf, painterOf } from "../quality/terminal.mjs";
-import { defaultsVersions, DEFAULTS_FOLDER, EXAMPLE_SOURCE, init, install, otherVersions, SOURCE, update, VERSION } from "./init.js";
+import { defaultsVersions, DEFAULTS_FOLDER, EXAMPLE_SOURCE, init, install, missingPackages, otherVersions, SOURCE, update, VERSION } from "./init.js";
 
 const USAGE = `Usage: caits <command>
 
@@ -24,16 +24,17 @@ const USAGE = `Usage: caits <command>
   check <script>…      Runs the npm scripts of the checks at once. Shows the output of the checks that fail, and only theirs.
   architecture         Checks the rules of quality/architecture.mjs.
   e2e                  Runs the end-to-end tests on the production build.
-  mutation             Runs the mutation tests (Stryker), then gives the score of each file and the mutants that survived. Its exit
-                       code is that of Stryker, or 1 when a mutant was not tested (its unit tests did not run).
-  mutation-summary     Gives the mutation score of each file (--survivors: the mutants that survived, and those not tested).
-  mutation-suite       The unit tests, as Stryker runs them for each mutant.
+  mutation             Runs the mutation tests (Stryker), runs again with more time the mutants that the clock stopped, then gives
+                       the score of each file and the mutants that survived. Its exit code is that of Stryker, or 1 when a mutant
+                       is not judged (its tests ended in an error that is not a failed test), or when the second run puts the
+                       score under the threshold.
+  mutation-summary     Gives the mutation score of each file (--survivors: the mutants that survived, and those not judged).
 
   --help, -h           Shows this help, also after a command (caits init --help).
   --version            Shows the version of CAITS.`;
 
 /** The commands that run a tool of quality/: their code is in the folder quality/ of CAITS. */
-const TOOLS = new Set(["dev", "check", "architecture", "e2e", "mutation", "mutation-summary", "mutation-suite"]);
+const TOOLS = new Set(["dev", "check", "architecture", "e2e", "mutation", "mutation-summary"]);
 
 /** The options of `caits init`. */
 const INIT_OPTIONS = /** @type {const} */ ({ caits: { type: "string" }, example: { type: "boolean" }, "example-source": { type: "string" }, "no-install": { type: "boolean" } });
@@ -85,7 +86,7 @@ async function main(command, args) {
   if (command === "init") return runInit(args);
   if (command === "update") return runUpdate(args);
   if (TOOLS.has(command)) {
-    if (command !== "mutation-suite") warnOfOldDefaults(process.cwd());
+    warnOfOldDefaults(process.cwd());
     // The tools load Vite, Marko and the other packages of the project: only the command that runs imports its code.
     const tool = /** @type {{ run: (args: string[]) => Promise<number | void> }} */ (await importTool(command));
     return tool.run(args);
@@ -171,6 +172,7 @@ function runUpdate(args) {
   const written = update(process.cwd());
   console.log(paint("green", `CAITS ${VERSION}: wrote ${count(written.length, "file")} in ${DEFAULTS_FOLDER}/.`));
   printOtherVersions(process.cwd());
+  printMissingPackages(process.cwd());
   return 0;
 }
 
@@ -182,6 +184,17 @@ function printOtherVersions(root) {
   for (const { key, project, caits } of others) console.log(`  ${key}: ${JSON.stringify(project)} (CAITS suggests ${JSON.stringify(caits)})`);
 }
 
+/** @param {string} root */
+function printMissingPackages(root) {
+  const { dependencies, devDependencies } = missingPackages(root);
+  if (dependencies.length + devDependencies.length === 0) return;
+  console.log(paint("yellow", `CAITS ${VERSION} needs packages that package.json does not have. Add them:`));
+  /** @param {string[]} names */
+  const quoted = names => names.map(name => `"${name}"`).join(" ");
+  if (dependencies.length > 0) console.log(`  ${paint("cyan", `npm install ${quoted(dependencies)}`)}`);
+  if (devDependencies.length > 0) console.log(`  ${paint("cyan", `npm install --save-dev ${quoted(devDependencies)}`)}`);
+}
+
 /** @param {string} root */
 function warnOfOldDefaults(root) {
   const versions = defaultsVersions(root);

package/bin/init.js

@@ -111,7 +111,8 @@ const TOOLS = {
   dependencies: ["@marko/run", "marko"],
   devDependencies: [
     "@eslint/js", "@marko/compiler", "@marko/type-check", "@playwright/test", "@stryker-mutator/core", "@stryker-mutator/typescript-checker",
-    "@types/node", "@vitest/coverage-v8", "eslint", "happy-dom", "sass", "typescript", "typescript-eslint", "vite", "vitest"
+    "@stryker-mutator/vitest-runner", "@types/node", "@vitest/coverage-v8", "eslint", "happy-dom", "sass", "typescript", "typescript-eslint",
+    "vite", "vitest"
   ]
 };
 /** @param {string[]} names */
@@ -253,6 +254,20 @@ export function otherVersions(root) {
   }));
 }
 
+/**
+ * The packages that CAITS needs and that package.json does not have, in either section, as npm installs them: `name@version`. A new
+ * version of CAITS may need a package more: `caits update` tells which.
+ * @param {string} root
+ * @returns {{ dependencies: string[]; devDependencies: string[] }}
+ */
+export function missingPackages(root) {
+  const file = join(root, "package.json");
+  const project = existsSync(file) ? readPackage(file) : undefined;
+  /** @param {Record<string, string>} section */
+  const missing = section => project === undefined ? [] : Object.entries(section).filter(([name]) => dependencyOf(project, name) === undefined).map(([name, version]) => `${name}@${version}`);
+  return { dependencies: missing(SUGGESTED.dependencies), devDependencies: missing(SUGGESTED.devDependencies) };
+}
+
 /**
  * Installs the packages of package.json, then the browser of the end-to-end tests. Gives false when a command fails.
  * @param {string} root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingenioz-it/caits",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "CAITS (Clean Architecture In TypeScript): the technical base of a Marko project with a backend and a frontend.",
   "keywords": [
     "clean-architecture",
@@ -55,12 +55,14 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:mutation": "stryker run stryker.config.json",
+    "test:mutation": "node test/mutation.js",
     "test:template": "node test/template.js",
     "check": "npm run typecheck && npm run lint && npm run test:coverage"
   },
   "dependencies": {
-    "magic-string": "^0.30.21"
+    "compression": "^1.8.2",
+    "magic-string": "^0.30.21",
+    "serve-static": "^2.2.1"
   },
   "peerDependencies": {
     "@eslint/js": "^10.0.1",
@@ -100,8 +102,9 @@
     "@marko/run": "^0.11.13",
     "@marko/type-check": "^3.2.1",
     "@playwright/test": "^1.64.0",
-    "@stryker-mutator/core": "^10.0.0",
-    "@stryker-mutator/typescript-checker": "^10.0.0",
+    "@stryker-mutator/core": "^10.1.1",
+    "@stryker-mutator/typescript-checker": "^10.1.1",
+    "@stryker-mutator/vitest-runner": "^10.1.1",
     "@types/node": "^26.6.4",
     "@vitest/coverage-v8": "^5.0.3",
     "eslint": "^10.11.0",

package/quality/architecture/adapters/scss.mjs

@@ -50,8 +50,8 @@ export function readScss(path, text, paths) {
     return isIn(STYLE_FOLDER, specifier, paths) ? `/${posix.join(STYLE_FOLDER, specifier)}` : specifier;
   });
   return {
-    imports, imported: [], exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [], comments,
-    lines: { imports: found.map(({ line }) => line), constructed: [], objectTypes: [], tags: [], comments: commentLines }
+    imports, imported: [], exports: [], defaultArray: null, classes: [], constructed: [], typeReferences: [], calls: [], objectTypes: [], strings: [], tags: [], comments,
+    lines: { imports: found.map(({ line }) => line), constructed: [], typeReferences: [], objectTypes: [], tags: [], comments: commentLines }
   };
 }
 

package/quality/architecture/facts.mjs

@@ -10,7 +10,13 @@
 /** Each fact that a rule points at has the number of its line in the file, from 1. */
 /** @typedef {{ name: string | null; kind: string; line: number }} Export an exported name, its kind, and its line */
 /** @typedef {{ name: string | null; readonly: boolean; value: string | null; asConst: boolean; line: number }} Property a property of a class */
-/** @typedef {{ name: string | null; exported: boolean; extends: string | null; implements: string[]; properties: Property[]; line: number }} Class */
+/** @typedef {{ name: string | null; text: string }} TypeName a type that a signature names: its name when it is a name (`Note`), and its text */
+/**
+ * A method of a class, and what it returns: each type of its return type, out of `Promise<…>` and of the unions (`Promise<A | B>` names A
+ * and B), or null when it has no return type.
+ * @typedef {{ name: string | null; returns: TypeName[] | null; line: number }} Method
+ */
+/** @typedef {{ name: string | null; exported: boolean; extends: string | null; implements: string[]; properties: Property[]; methods: Method[]; line: number }} Class */
 /**
  * An item of `export default [ … ]`: the names that its chain calls, its text, the name that the first call takes first (`when(Event, …)`
  * takes Event), the class of each `new X(…)` in it, and its line.
@@ -25,13 +31,13 @@
 /**
  * The lines of the facts that are strings, in the same order: `lines.imports[2]` is the line of `imports[2]`. A tag that Marko finds
  * without an import counts as an import, at the line of the tag.
- * @typedef {{ imports: number[]; constructed: number[]; objectTypes: number[]; tags: number[]; comments: number[] }} Lines
+ * @typedef {{ imports: number[]; constructed: number[]; typeReferences: number[]; objectTypes: number[]; tags: number[]; comments: number[] }} Lines
  */
 /**
  * What the rules read in a file: see factsOf.
  * @typedef {{
  *   imports: string[]; imported: Imported[]; exports: Export[]; defaultArray: Item[] | null; classes: Class[]; constructed: (string | null)[];
- *   calls: Call[]; objectTypes: string[]; strings: string[]; tags: string[]; comments: string[]; lines: Lines
+ *   typeReferences: string[]; calls: Call[]; objectTypes: string[]; strings: string[]; tags: string[]; comments: string[]; lines: Lines
  * }} Facts
  */
 /** A comment that a parser gives apart from the tree: its text, and where it starts in the file. @typedef {{ value: string; start: number }} LooseComment */
@@ -75,6 +81,8 @@ const rootOf = node => {
   while (node?.type === "MemberExpression" || node?.type === "CallExpression") node = node.type === "MemberExpression" ? node.object : node.callee;
   return node?.type === "Identifier" ? node.name : null;
 };
+/** The name of a type, qualified or not: `Note`, `globalThis.Request`. @type {(node: Node) => string} */
+const typeNameOf = node => node.type === "TSQualifiedName" ? `${typeNameOf(node.left)}.${typeNameOf(node.right)}` : node.name;
 /** @type {(node: Node) => string | null} */
 const keyOf = node => node.key?.name ?? stringOf(node.key);
 
@@ -120,8 +128,17 @@ function exportsOf(node, lineOf) {
   return [{ name: declaration.id?.name, kind: DECLARATION_KINDS[declaration.type] ?? declaration.type, line }];
 }
 
-/** @type {(node: Node, exported: boolean, lineOf: (node: Node) => number) => Class} */
-const classOf = (node, exported, lineOf) => ({
+/** The types that a return type names: those of a union, and the type of a Promise. @type {(type: Node, text: string) => TypeName[]} */
+const typeNamesOf = (type, text) => {
+  if (type.type === "TSUnionType") return type.types.flatMap((/** @type {Node} */ member) => typeNamesOf(member, text));
+  const reference = type.type === "TSTypeReference" && type.typeName.type === "Identifier" ? type.typeName.name : null;
+  const [promised, ...others] = (type.typeArguments ?? type.typeParameters)?.params ?? [];
+  if (reference === "Promise" && promised && others.length === 0) return typeNamesOf(promised, text);
+  return [{ name: reference, text: text.slice(type.start, type.end) }];
+};
+
+/** @type {(node: Node, exported: boolean, lineOf: (node: Node) => number, text: string) => Class} */
+const classOf = (node, exported, lineOf, text) => ({
   name: node.id?.name ?? null,
   exported,
   extends: nameOf(node.superClass),
@@ -133,6 +150,11 @@ const classOf = (node, exported, lineOf) => ({
     asConst: member.value?.type === "TSAsExpression" && member.value.typeAnnotation?.typeName?.name === "const",
     line: lineOf(member)
   })),
+  methods: node.body.body.filter((/** @type {Node} */ member) => (member.type === "MethodDefinition" || member.type === "ClassMethod") && member.kind === "method" && !member.static && !member.computed)
+    .map((/** @type {Node} */ member) => {
+      const returnType = (member.value ?? member).returnType?.typeAnnotation;
+      return { name: keyOf(member), returns: returnType ? typeNamesOf(returnType, text) : null, line: lineOf(member) };
+    }),
   line: lineOf(node)
 });
 
@@ -142,14 +164,16 @@ const classOf = (node, exported, lineOf) => ({
  * - exports: each exported name, with its kind (class, interface, type, const, function, enum, specifier, default, all);
  * - defaultArray: the items of `export default [ … ]`, with the calls of each item (`bind(X).to(Y)` calls bind, to), the name that the first
  *   call takes first (X), and the classes that the item builds, or null;
- * - classes: the classes, with what they extend and implement, and their properties;
+ * - classes: the classes, with what they extend and implement, their properties, and the return types of their methods;
  * - constructed: the class of each `new X(…)`;
+ * - typeReferences: the name of each type that the file names (`Note`, `globalThis.Request`), its arguments too (`Map<string, Note>` names Map
+ *   and Note);
  * - calls: each call, with the value of its arguments that are strings (null for the others);
  * - objectTypes: the value of each `type: "…"` of an object literal;
  * - strings: every string of the code (comments and import paths aside);
  * - tags: the name of each Marko tag (Marko only);
  * - comments: the text of each comment: those that the parser gives, those that the tree holds, and the comments of a Marko template;
- * - lines: the line of each import, `new`, `type: "…"`, tag and comment. The facts that are objects have their own line.
+ * - lines: the line of each import, `new`, type that the file names, `type: "…"`, tag and comment. The facts that are objects have their own line.
  * A node of oxc has its offset in the text (start); a node of Babel has its line too (loc), which counts from the first line of the file.
  * @param {Node} program
  * @param {string} text
@@ -162,9 +186,9 @@ export function factsOf(program, text, comments = []) {
   const lineOf = node => node.loc?.start?.line ?? lineAt(node.start ?? 0);
   /** @type {Facts} */
   const facts = {
-    imports: [], imported: [], exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [],
-    comments: comments.map(({ value }) => value),
-    lines: { imports: [], constructed: [], objectTypes: [], tags: [], comments: comments.map(({ start }) => lineAt(start)) }
+    imports: [], imported: [], exports: [], defaultArray: null, classes: [], constructed: [], typeReferences: [], calls: [], objectTypes: [], strings: [],
+    tags: [], comments: comments.map(({ value }) => value),
+    lines: { imports: [], constructed: [], typeReferences: [], objectTypes: [], tags: [], comments: comments.map(({ start }) => lineAt(start)) }
   };
   /** @type {(source: string, node: Node) => void} */
   const addImport = (source, node) => {
@@ -209,12 +233,16 @@ export function factsOf(program, text, comments = []) {
         });
       }
     }
-    if (node.type === "ClassDeclaration") facts.classes.push(classOf(node, exportedClasses.has(node), lineOf));
+    if (node.type === "ClassDeclaration") facts.classes.push(classOf(node, exportedClasses.has(node), lineOf, text));
     if (node.type === "NewExpression") {
       facts.constructed.push(nameOf(node.callee));
       facts.lines.constructed.push(lineOf(node));
       for (const { node: element, item } of items) if (element.start <= node.start && node.end <= element.end) item.constructed.push(nameOf(node.callee));
     }
+    if (node.type === "TSTypeReference") {
+      facts.typeReferences.push(typeNameOf(node.typeName));
+      facts.lines.typeReferences.push(lineOf(node));
+    }
     if (node.type === "CallExpression") facts.calls.push({ name: nameOf(node.callee), root: rootOf(node.callee), args: node.arguments.map(stringOf), line: lineOf(node) });
     if (node.type === "ObjectExpression") {
       for (const property of node.properties) {

package/quality/architecture/project.mjs

@@ -190,16 +190,18 @@ export function portOf(path) {
 }
 
 /**
- * An adapter, or its test: {context}/infra/{folder}/{file}. It implements the port named after its folder.
+ * An adapter, or its test: {context}/infra/{folder}/{file}. Its port is in the folder of the same name in the domain, domain/port/{folder}/:
+ * the module of that folder that is not its contract, whatever its name. The module is null when the domain has no such port.
  * @param {string} path
- * @returns {{ folder: string; test: boolean; port: string; portModule: string } | null}
+ * @param {Set<string>} paths
+ * @returns {{ folder: string; test: boolean; portModule: string | null } | null}
  */
-export function adapterOf(path) {
+export function adapterOf(path, paths) {
   const match = /^(src\/(?:backend|frontend)\/[^/]+)\/infra\/([a-z0-9-]+)\/([^/]+)$/.exec(path);
   if (!match) return null;
   const [, context, folder, name] = match;
-  const port = pascal(folder);
-  return { folder, test: name.endsWith(".test.ts"), port, portModule: `${context}/domain/port/${folder}/${port}` };
+  const port = [...paths].sort().map(portOf).find(found => found !== null && !found.contract && found.module.startsWith(`${context}/domain/port/${folder}/`));
+  return { folder, test: name.endsWith(".test.ts"), portModule: port?.module ?? null };
 }
 
 /** The contexts whose frontend a file takes: `frontendOf($global, "notes")` takes the frontend of notes. @type {(file: File) => string[]} */
@@ -216,7 +218,7 @@ export const LISTS = { domain: "domain", application: "application", presentatio
 
 /**
  * Whether a list of quality/imports.mjs holds an import of a package: the package, the module or the Node API itself, or a folder of
- * modules that holds it (`@ingenioz-it/caits/messaging/*` holds `@ingenioz-it/caits/messaging/Input`).
+ * modules that holds it (`@ingenioz-it/caits/messaging/*` holds `@ingenioz-it/caits/messaging/EventPublisher`).
  * @param {string} specifier
  * @param {string[]} list
  */

package/quality/dev.mjs

@@ -4,13 +4,15 @@
 // answer, so `marko-run dev` never starts. This command gives both ports, so @marko/run does not check them: PORT, and HMR_PORT
 // (24678 when not set). Two projects can run their servers at the same time, each with its two ports.
 // If a port is already in use, the server stops with EADDRINUSE.
-// It uses the Vite configuration of the project, quality/vite.config.ts: Marko, and the plugin of CAITS.
+// It uses the Vite configuration of the project, quality/vite.config.ts: Marko, and the plugin of CAITS. The server is that of the adapter
+// of CAITS: it boots the backend, boots it again when its code changes, and stops it, and the command, on SIGTERM or SIGINT (Ctrl+C).
 // @marko/run writes the entry files of the server in the build folder. `npm run build` (`npm run check` runs it) empties dist/: the
 // server writes them in a folder of its own, else it fails at the next change of a file. @marko/vite refuses an entry file whose path
 // starts with a dot: the folder is in node_modules/, as the cache of Vite.
 import { existsSync } from "node:fs";
-import adapter from "@marko/run/adapter";
 import { loadConfigFromFile } from "vite";
+import { adapter } from "../src/adapter.js";
+import { stopOnSignals } from "../src/server/serve.js";
 import { painterOf } from "./terminal.mjs";
 
 export const VITE_CONFIG = "quality/vite.config.ts";
@@ -30,7 +32,7 @@ export async function run(args) {
   const port = Number(process.env.PORT ?? 3000);
   const hmrPort = Number(process.env.HMR_PORT ?? 24678);
   const marko = adapter();
-  // The adapter of Node, which @marko/run gives, has the two methods.
+  // The adapter of CAITS has the two methods.
   const getEntryFile = marko.getEntryFile?.bind(marko);
   const startDev = marko.startDev?.bind(marko);
   if (!getEntryFile || !startDev) throw new Error(`The adapter ${marko.name} of @marko/run cannot start a development server.`);
@@ -88,6 +90,7 @@ export async function run(args) {
   };
 
   await start();
+  stopOnSignals(async () => { await running.close(); });
 }
 
 /** Whether the Vite configuration of the project loads. When it does not, says why. */

package/quality/mutation-summary.mjs

@@ -1,8 +1,7 @@
 // `caits mutation-summary`: the mutation score of each file, from the report of Stryker. With --survivors, the mutants that survived.
 // In a terminal: the score in green when every mutant is killed, else in red; the score of each file the same way, and its path in cyan;
-// for each survivor, its line dim, its status in red, its mutator in yellow.
+// for each survivor, its line dim, its status in red, its mutator in yellow, and why a mutant is not judged, dim.
 import { existsSync, readFileSync } from "node:fs";
-import { NOT_RUN } from "./mutation-suite.mjs";
 import { painterOf } from "./terminal.mjs";
 
 /** The report that Stryker writes in JSON (quality/caits/stryker.mjs). */
@@ -13,46 +12,57 @@ export const REPORT = "reports/mutation/mutation.json";
 /** @type {(file: string) => unknown} */
 const readJson = file => JSON.parse(readFileSync(file, "utf8"));
 
-/** Stryker counts a suite that stopped before its tests as a kill: the mutant is not tested (`caits mutation-suite`). @type {(m: Mutant) => boolean} */
-const notTested = m => m.status === "Killed" && Boolean(m.statusReason?.includes(NOT_RUN));
+/**
+ * Stryker leaves out of the score a mutant whose tests ended in an error that is not a failed test: an error outside the tests, or a test
+ * runner that stopped. Nothing tells whether a test sees the mutant: it is not judged. `caits mutation` kills a mutant whose test files
+ * failed to load, and nothing else. @type {(m: Mutant) => boolean}
+ */
+const notJudged = m => m.status === "RuntimeError";
 
 /** @type {(m: Mutant) => string} */
-const tag = m => (m.status === "NoCoverage" ? "[no cov]" : m.status === "Survived" ? "[survived]" : "[not tested]");
+const tag = m => (m.status === "NoCoverage" ? "[no cov]" : m.status === "Survived" ? "[survived]" : "[not judged]");
 
 /**
  * @param {string[]} args
- * @returns {number} 1 when a mutant is not tested
+ * @param {{ breakAt?: number | null }} [options] `breakAt`: the score under which the run fails, the threshold `break` of Stryker
+ * @returns {number} 1 when a mutant is not judged, or when the score is under `breakAt`
  */
-export function run(args) {
+export function run(args, { breakAt = null } = {}) {
   if (!existsSync(REPORT)) throw new Error(`${REPORT} is missing: run the mutation tests first (npm run test:mutation).`);
   const report = /** @type {{ files: Record<string, { source: string; mutants: Mutant[] }> }} */ (readJson(REPORT));
   const rows = [];
-  let killedTotal = 0, validTotal = 0, notTestedTotal = 0;
+  let killedTotal = 0, validTotal = 0, notJudgedTotal = 0;
   for (const [file, data] of Object.entries(report.files)) {
     /** @type {(status: string) => number} */
     const count = status => data.mutants.filter(m => m.status === status).length;
-    const untested = data.mutants.filter(notTested).length;
-    const killed = count("Killed") - untested + count("Timeout");
+    const unjudged = data.mutants.filter(notJudged).length;
+    const killed = count("Killed") + count("Timeout");
     const survived = count("Survived");
     const noCoverage = count("NoCoverage");
-    const valid = killed + survived + noCoverage + untested;
-    killedTotal += killed; validTotal += valid; notTestedTotal += untested;
-    rows.push({ file, killed, survived, noCoverage, untested, score: valid ? (100 * killed) / valid : 100, survivors: data.mutants.filter(m => m.status === "Survived" || m.status === "NoCoverage" || notTested(m)), source: data.source.split("\n") });
+    const valid = killed + survived + noCoverage + unjudged;
+    killedTotal += killed; validTotal += valid; notJudgedTotal += unjudged;
+    rows.push({ file, killed, survived, noCoverage, unjudged, score: valid ? (100 * killed) / valid : 100, survivors: data.mutants.filter(m => m.status === "Survived" || m.status === "NoCoverage" || notJudged(m)), source: data.source.split("\n") });
   }
   rows.sort((a, b) => a.score - b.score);
   const verbose = args.includes("--survivors");
   const paint = painterOf(process.stdout);
   /** @type {(killed: number, valid: number) => "green" | "red"} */
   const colorOf = (killed, valid) => killed === valid ? "green" : "red";
-  console.log(`${paint([colorOf(killedTotal, validTotal), "bold"], `Mutation score: ${(validTotal ? (100 * killedTotal) / validTotal : 100).toFixed(1)}%  (${killedTotal} killed of ${validTotal} valid mutants)`)}\n`);
+  const score = validTotal ? (100 * killedTotal) / validTotal : 100;
+  console.log(`${paint([colorOf(killedTotal, validTotal), "bold"], `Mutation score: ${score.toFixed(1)}%  (${killedTotal} killed of ${validTotal} valid mutants)`)}\n`);
   for (const row of rows) {
-    const valid = row.killed + row.survived + row.noCoverage + row.untested;
-    console.log(`${paint(colorOf(row.killed, valid), `${row.score.toFixed(0).padStart(4)}%`)}  ${paint("cyan", row.file)}  (killed ${row.killed}, survived ${row.survived}, no coverage ${row.noCoverage}${row.untested ? `, not tested ${row.untested}` : ""})`);
+    const valid = row.killed + row.survived + row.noCoverage + row.unjudged;
+    console.log(`${paint(colorOf(row.killed, valid), `${row.score.toFixed(0).padStart(4)}%`)}  ${paint("cyan", row.file)}  (killed ${row.killed}, survived ${row.survived}, no coverage ${row.noCoverage}${row.unjudged ? `, not judged ${row.unjudged}` : ""})`);
     if (verbose && row.survivors.length) {
-      for (const m of row.survivors) console.log(`        ${paint("dim", `L${m.location.start.line}`)} ${paint("red", tag(m))} ${paint("yellow", m.mutatorName)}: ${(row.source[m.location.start.line - 1] ?? "").trim().slice(0, 90)}  ${paint("dim", "→")}  ${String(m.replacement ?? "").slice(0, 60)}`);
+      for (const m of row.survivors) {
+        console.log(`        ${paint("dim", `L${m.location.start.line}`)} ${paint("red", tag(m))} ${paint("yellow", m.mutatorName)}: ${(row.source[m.location.start.line - 1] ?? "").trim().slice(0, 90)}  ${paint("dim", "→")}  ${String(m.replacement ?? "").slice(0, 60)}`);
+        if (notJudged(m) && m.statusReason) console.log(`          ${paint("dim", m.statusReason.split("\n")[0].slice(0, 120))}`);
+      }
     }
   }
-  if (!notTestedTotal) return 0;
-  console.log(`\n${paint("red", `${notTestedTotal} ${notTestedTotal === 1 ? "mutant is" : "mutants are"} not tested: the unit tests did not run, and Stryker counts ${notTestedTotal === 1 ? "it" : "them"} as killed. Run the mutation tests again. Why they did not run: reports/mutation/index.html.`)}`);
-  return 1;
+  if (notJudgedTotal) {
+    const one = notJudgedTotal === 1;
+    console.log(`\n${paint("red", `${notJudgedTotal} ${one ? "mutant is" : "mutants are"} not judged: ${one ? "its" : "their"} tests ended in an error that is not a failed test, and Stryker leaves ${one ? "it" : "them"} out of the score. Run the mutation tests again; when ${one ? "it" : "one"} comes back, write a test that sees what it changes.`)}`);
+  }
+  return notJudgedTotal > 0 || (breakAt !== null && score < breakAt) ? 1 : 0;
 }

package/quality/mutation.mjs

@@ -1,29 +1,185 @@
 // `caits mutation`: the mutation tests (Stryker, with quality/stryker.config.mjs), then the score of each file and the mutants that
 // survived, whether Stryker passed or not. Stryker alone ends with its threshold when the score is too low: the survivors say what to fix.
-// The run fails also when a mutant is not tested, which Stryker counts as killed (`caits mutation-summary`).
+// Stryker stops the tests of a mutant that run too long, and counts the mutant as killed: the mutant may make the code loop without end.
+// Its counter stops most of these loops, as it counts the runs of the code of the mutant, whatever the load of the machine. The clock
+// stops the rest, but the load slows a mutant that survives, which runs the most tests, past its time: the mutants that the clock stopped
+// run again, with more time and fewer tests at once, and their second result counts. A mutant whose test files failed to load is killed:
+// its code throws as soon as a test imports it, every time, as a failed test does, where Stryker counts an error outside the tests. The
+// run fails when a mutant is not judged (`caits mutation-summary`).
 import { spawn } from "node:child_process";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { REPORT, run as summary } from "./mutation-summary.mjs";
+import { painterOf } from "./terminal.mjs";
 
 /** The configuration of Stryker in a project: it imports the defaults of CAITS (quality/caits/stryker.mjs). */
 export const STRYKER_CONFIG = "quality/stryker.config.mjs";
 
+/** The page of the report, which Stryker writes with the report in a line of its script (quality/caits/stryker.mjs). */
+const PAGE = "reports/mutation/index.html";
+
+/** The line of the page that holds the report. */
+const PAGE_REPORT = /^( *app\.report = ).*;$/m;
+
+/** The second run of the mutants that the clock stopped: more time for each, fewer at once, and the report in JSON only. */
+const SECOND_RUN = ["--concurrency", "4", "--timeoutFactor", "3", "--reporters", "json"];
+
+/** How Stryker starts the reason of an error outside the tests: then come the test files that failed to load, then the other errors. */
+const OUTSIDE = "An error occurred outside of a test run: ";
+
+/** A test file that failed to load, as Stryker gives it on a line of its own: `<its path>: <the message>`. */
+const LOAD_FAILURE = /^\/.*\.(?:test|spec)\.[cm]?[jt]sx?: /;
+
+/** The temporary folders of the runs, in the temporary folder of the system: `caits-mutation-<pid of their run>-<random>`. */
+const TEMPORARY = /^caits-mutation-(\d+)-/;
+
+/** @typedef {{ status: string; statusReason?: string; mutatorName: string; replacement?: string; location: { start: { line: number; column: number }; end: { line: number; column: number } } }} Mutant */
+/** @typedef {{ files: Record<string, { mutants: Mutant[] }> }} Report */
+
 /**
  * @param {string[]} args the options of Stryker
- * @returns {Promise<number>} the exit code of Stryker, or 1 when a mutant is not tested
+ * @param {string} [config] the configuration of Stryker: a module, or JSON
+ * @returns {Promise<number>} the exit code of Stryker, or 1 when a mutant is not judged, or when the score is under the threshold after
+ * the second run
  */
-export async function run(args) {
-  if (!existsSync(STRYKER_CONFIG)) throw new Error(`${STRYKER_CONFIG} is missing: it gives the configuration of the mutation tests. Run \`npx caits init .\` to write it.`);
+export async function run(args, config = STRYKER_CONFIG) {
+  if (!existsSync(config)) throw new Error(`${config} is missing: it gives the configuration of the mutation tests. Run \`npx caits init .\` to write it.`);
   // A run that stops before its report must not show the summary of the run before.
   rmSync(REPORT, { force: true });
-  // Ctrl+C and `caits check` stop the whole group of processes: Stryker and its test runners stop with this command.
-  const stryker = spawn("npx", ["stryker", "run", STRYKER_CONFIG, ...args], { stdio: "inherit" });
-  /** @type {number} */
-  const status = await new Promise(resolve => {
-    stryker.on("error", () => resolve(1));
-    stryker.on("close", code => resolve(code ?? 1));
+  removeOrphans();
+  // The tests write their temporary files in a folder of this run: a test that Stryker stops cannot remove them. In WSL, the temporary
+  // folder of the system is in memory.
+  const temporary = mkdtempSync(join(tmpdir(), `caits-mutation-${process.pid}-`));
+  try {
+    const status = await stryker([config, ...args], temporary);
+    if (!existsSync(REPORT)) return status;
+    const first = readReport();
+    let report = first;
+    const late = Object.entries(first.files).flatMap(([file, { mutants }]) => mutants.filter(stoppedByTheClock).map(mutant => ({ file, mutant })));
+    if (late.length > 0) {
+      const one = late.length === 1;
+      console.log(`\n${late.length} ${one ? "mutant" : "mutants"} ran out of time on the clock, which the load of the machine slows: ${one ? "it runs" : "they run"} again, with more time and fewer tests at once.\n`);
+      rmSync(REPORT);
+      const ranges = [...new Set(late.map(({ file, mutant }) => `${file}:${mutant.location.start.line}-${mutant.location.end.line}`))];
+      await stryker([config, ...args, "--mutate", ranges.join(","), ...SECOND_RUN], temporary);
+      if (!existsSync(REPORT)) {
+        writeFileSync(REPORT, JSON.stringify(first));
+        console.log("");
+        summary(["--survivors"]);
+        console.log(`\n${painterOf(process.stdout)("red", "The second run stopped before its report: the mutants that the clock stopped count as killed, as Stryker counts them. Run the mutation tests again.")}`);
+        return 1;
+      }
+      report = withSecondResults(first, readReport());
+    }
+    report = withLoadFailuresKilled(report);
+    writeFileSync(REPORT, JSON.stringify(report));
+    // The page shows the report too: Stryker breaks each < apart, so that no text of the report ends the script.
+    if (existsSync(PAGE)) writeFileSync(PAGE, readFileSync(PAGE, "utf8").replace(PAGE_REPORT, (_, start) => `${start}${JSON.stringify(report).replaceAll("<", '<"+"')};`));
+    console.log("");
+    return summary(["--survivors"], { breakAt: await breakOf(config) }) || status;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Runs Stryker. Ctrl+C and `caits check` stop the whole group of processes: Stryker and its test runners stop with this command.
+ * @param {string[]} args
+ * @param {string} temporary the temporary folder of the tests
+ * @returns {Promise<number>}
+ */
+function stryker(args, temporary) {
+  const running = spawn("npx", ["stryker", "run", ...args], { stdio: "inherit", env: { ...process.env, TMPDIR: temporary } });
+  return new Promise(resolve => {
+    running.on("error", () => resolve(1));
+    running.on("close", code => resolve(code ?? 1));
   });
-  if (!existsSync(REPORT)) return status;
-  console.log("");
-  return summary(["--survivors"]) || status;
+}
+
+/** @type {(file: string) => unknown} */
+const readJson = file => JSON.parse(readFileSync(file, "utf8"));
+
+/** @returns {Report} */
+const readReport = () => /** @type {Report} */ (readJson(REPORT));
+
+/** The clock stopped the mutant: Stryker gives a reason only when its counter stops it. @type {(mutant: Mutant) => boolean} */
+const stoppedByTheClock = mutant => mutant.status === "Timeout" && !mutant.statusReason?.startsWith("Hit limit reached");
+
+/** @type {(file: string, mutant: Mutant) => string} */
+const keyOf = (file, { mutatorName, replacement, location: { start, end } }) => [file, start.line, start.column, end.line, end.column, mutatorName, replacement].join(" ");
+
+/**
+ * The first report, with the results of the second run for the mutants that the clock stopped. The second run tests the whole lines of
+ * these mutants: its other mutants keep their first result.
+ * @param {Report} first
+ * @param {Report} second
+ * @returns {Report}
+ */
+function withSecondResults(first, second) {
+  const again = new Map(Object.entries(second.files).flatMap(([file, { mutants }]) => mutants.map(mutant => [keyOf(file, mutant), mutant])));
+  const files = Object.fromEntries(Object.entries(first.files).map(([file, data]) => [file, {
+    ...data,
+    mutants: data.mutants.map(mutant => {
+      const result = stoppedByTheClock(mutant) ? again.get(keyOf(file, mutant)) : undefined;
+      return result === undefined ? mutant : { ...mutant, status: result.status, statusReason: result.statusReason };
+    })
+  }]));
+  return { ...first, files };
+}
+
+/**
+ * The test files of the mutant failed to load, and nothing else: each line of its reason is a test file that failed to load. An error
+ * after the tests, or a message on more than one line, has a line that is not one, and the mutant stays not judged.
+ * @type {(mutant: Mutant) => boolean}
+ */
+const failedToLoad = ({ status, statusReason }) => status === "RuntimeError" && typeof statusReason === "string" && statusReason.startsWith(OUTSIDE)
+  && statusReason.slice(OUTSIDE.length).split("\n").every(line => LOAD_FAILURE.test(line));
+
+/**
+ * The report, where a mutant whose test files failed to load is killed.
+ * @param {Report} report
+ * @returns {Report}
+ */
+function withLoadFailuresKilled(report) {
+  const files = Object.fromEntries(Object.entries(report.files).map(([file, data]) => [file, {
+    ...data,
+    mutants: data.mutants.map(mutant => failedToLoad(mutant) ? { ...mutant, status: "Killed", statusReason: `The test files that import its code failed to load. ${mutant.statusReason}` } : mutant)
+  }]));
+  return { ...report, files };
+}
+
+/**
+ * The threshold `break` of the configuration: the score under which Stryker fails, none by default.
+ * @param {string} config
+ * @returns {Promise<number | null>}
+ */
+async function breakOf(config) {
+  const module = config.endsWith(".json") ? { default: readJson(config) } : /** @type {{ default: unknown }} */ (await import(pathToFileURL(resolve(config)).href));
+  return /** @type {{ thresholds?: { break?: number | null } }} */ (module.default).thresholds?.break ?? null;
+}
+
+/** Removes the temporary folders whose run no longer runs: Ctrl+C and `caits check` stop a run before its end. */
+function removeOrphans() {
+  for (const entry of readdirSync(tmpdir())) {
+    const pid = TEMPORARY.exec(entry)?.[1];
+    if (pid === undefined || runs(Number(pid))) continue;
+    try {
+      rmSync(join(tmpdir(), entry), { recursive: true, force: true });
+    } catch {
+      // The folder of another user.
+    }
+  }
+}
+
+/** @param {number} pid */
+function runs(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process runs, but belongs to another user.
+    return /** @type {NodeJS.ErrnoException} */ (error).code === "EPERM";
+  }
 }