@ingenioz-it/caits 0.5.0 → 0.6.0

package/quality/architecture/project.mjs

@@ -1,30 +1,45 @@
-import { dirname, posix, relative, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, posix, relative, resolve } from "node:path";
 
 /** What the rules know of the project: where a file lives, what it imports, and how the parts are named. */
 
 /** @import { Facts } from "./facts.mjs" */
 /** @typedef {"backend" | "frontend"} Side */
 /**
- * Where a file lives: see locate. Only a layer has a context and a layer, and only a layer and the routes have a side.
- * @typedef {{ kind: "other" | "map" | "test-environment"; side?: undefined; context?: undefined; layer?: undefined }
- *   | { kind: "routes"; side: Side; context?: undefined; layer?: undefined }
- *   | { kind: "layer"; side: Side; context: string; layer: string }} Location
+ * Where a file lives: see locate. Only a layer has a context and a layer, and only a layer and the routes have a side. A file of a use
+ * case has its use case too: command/add-note.
+ * @typedef {{ kind: "other" | "test-environment"; side?: undefined; context?: undefined; layer?: undefined; useCase?: undefined }
+ *   | { kind: "routes"; side: Side; context?: undefined; layer?: undefined; useCase?: undefined }
+ *   | { kind: "layer"; side: Side; context: string; layer: string; useCase?: string }} Location
  */
 /** A file of the project: its path from the root of the project, and what the rules read in it. @typedef {Facts & { path: string }} File */
-/** The project: its root, its files, and their paths. @typedef {{ root: string; files: File[]; paths: Set<string> }} Project */
 /**
- * An import of the production code: its file, where the file and its target live, the specifier, and the target (a path from the root of
- * the project when the import is internal, else the specifier).
- * @typedef {{ file: File; from: Location; to: Location; specifier: string; internal: boolean; target: string }} Import
+ * The packages that each layer may import, by the key of its list (see LISTS): a package (`uuid`), a module (`@ingenioz-it/caits/Token`), a
+ * Node API (`node:crypto`), or a folder of modules (`@ingenioz-it/caits/messaging/*`). A layer without a list imports any package.
+ * @typedef {Partial<Record<"domain" | "application" | "presentation" | "infra" | "di" | "contextMap", string[]>>} Packages
+ */
+/**
+ * The project: its root, its files, their paths, and the packages that each layer may import (quality/imports.mjs).
+ * @typedef {{ root: string; files: File[]; paths: Set<string>; packages: Packages }} Project
+ */
+/**
+ * An import of the production code: its file, where the file and its target live, the specifier, the target (a path from the root of the
+ * project when the import is internal, else the specifier), and the line of the import.
+ * @typedef {{ file: File; from: Location; to: Location; specifier: string; internal: boolean; target: string; line: number }} Import
+ */
+/** A message, at a line of the file: the rule points at one construct (an import, a class, a call…). @typedef {{ line?: number; message: string }} Located */
+/**
+ * What a check gives: nothing, or false, when the rule holds; else a message, or a list of messages. A message is a text, or a text with
+ * its line. The message of a rule on the imports is at the line of the import, unless it gives another.
+ * @typedef {string | Located | (string | Located)[] | false | null | undefined | void} Messages
  */
-/** What a check gives: nothing, or false, when the rule holds; else a message, or a list of messages. @typedef {string | string[] | false | null | undefined | void} Messages */
 /**
  * A rule of the architecture: see the rules of CAITS (quality/caits/architecture.mjs). A rule can keep values of its own, which its check
  * reads with `this`: a project can change them.
  * @typedef {{ name: string; description: string; [value: string]: unknown } & (
- *   | { on: "import"; check(link: Import): Messages }
+ *   | { on: "import"; check(link: Import, project: Project): Messages }
  *   | { on: "file"; production?: boolean; check(file: File, project: Project): Messages }
- *   | { on: "project"; check(project: Project): { file: string; message: string }[] }
+ *   | { on: "project"; check(project: Project): { file: string; line?: number; message: string }[] }
  * )} Rule
  */
 
@@ -39,7 +54,9 @@ export const kernelPathOf = specifier => specifier.startsWith(`${KERNEL.name}/`)
 
 /**
  * Where a file lives: a test environment (test.di.ts), the routes of one side, the context map, a layer of a context (its di.ts is a
- * layer too), or elsewhere.
+ * layer too), or elsewhere. The folders of a context say its layers: a use case, in command/ or query/, is of the application, but its
+ * controllers ({usecase}.{name}.controller.ts) and their tests ({usecase}.{name}.presentation.test.ts), which are of the presentation;
+ * the events of the frontend, in event/, are of the application.
  * @param {string} path
  * @returns {Location}
  */
@@ -47,11 +64,16 @@ export function locate(path) {
   const parts = path.split("/");
   if (parts[0] !== "src") return { kind: "other" };
   if (parts[1] === "routes") return { kind: "routes", side: parts[2] === "_frontend" ? "frontend" : "backend" };
-  if (parts[1] === "backend" && parts.length === 3) return { kind: "map" };
+
   if (/^test\.di\.(js|ts)$/.test(parts[parts.length - 1])) return { kind: "test-environment" };
-  if ((parts[1] === "backend" || parts[1] === "frontend") && parts.length === 4) return { kind: "layer", context: parts[2], side: parts[1], layer: "di" };
-  if (parts[1] === "backend" || parts[1] === "frontend") return { kind: "layer", context: parts[2], side: parts[1], layer: parts[3] };
-  return { kind: "other" };
+  if (parts[1] !== "backend" && parts[1] !== "frontend") return { kind: "other" };
+  const [, side, context, folder] = parts;
+  if (parts.length === 4) return { kind: "layer", context, side, layer: /^context-map(\.test)?\.(js|ts)$/.test(folder) ? "map" : "di" };
+  if ((folder === "command" || folder === "query") && parts.length === 6) {
+    const layer = /\.(controller|presentation\.test)\.(js|ts)$/.test(parts[5]) ? "presentation" : "application";
+    return { kind: "layer", context, side, layer, useCase: `${folder}/${parts[4]}` };
+  }
+  return { kind: "layer", context, side, layer: ["command", "query", "event"].includes(folder) ? "application" : folder };
 }
 
 /** The domain and the application: the code that holds no technology. @type {(where: Location) => boolean} */
@@ -62,13 +84,34 @@ export const isTestCode = path => /\.(test|contract)\.ts$|(^|\/)test\.di\.ts$/.t
 
 /**
  * The shortcuts of the imports, to the folders they lead to. #context leads to the context of the file: each context has a package.json
- * that says it. #shared leads to the backend context shared: tsconfig.json says it to TypeScript, and the kernel's plugin to Vite.
- * #backend and #frontend lead to the sides, for the routes: the package.json of the project says it.
+ * that says it. #shared leads to the backend context shared, and #frontend-shared to the frontend context shared: tsconfig.json says it
+ * to TypeScript, and the kernel's plugin to Vite. #backend and #frontend lead to the sides, for the routes: the package.json of the
+ * project says it.
  */
-const SHORTCUTS = new Map([["shared", "src/backend/shared"], ["backend", "src/backend"], ["frontend", "src/frontend"]]);
+const SHORTCUTS = new Map([
+  ["shared", "src/backend/shared"], ["frontend-shared", "src/frontend/shared"], ["backend", "src/backend"], ["frontend", "src/frontend"]
+]);
+
+/** The folder of the tags of the components of the frontend context shared, as the marko.json of the frontend gives it. */
+const SHARED_TAGS = "shared/presentation/component";
+
+/**
+ * Whether src/frontend/marko.json gives Marko the folder of the components of the frontend context shared as a folder of tags
+ * ("tags-dir": "./shared/presentation/component", alone or among others).
+ * @param {string} root
+ * @returns {boolean}
+ */
+export function givesSharedTags(root) {
+  const file = join(root, "src/frontend/marko.json");
+  if (!existsSync(file)) return false;
+  /** @type {unknown} */
+  const read = JSON.parse(readFileSync(file, "utf8"));
+  const taglib = /** @type {{ "tags-dir"?: string | string[] }} */ (read);
+  return [taglib["tags-dir"] ?? []].flat().some(folder => posix.normalize(folder).replace(/\/$/, "") === SHARED_TAGS);
+}
 
 /** The folder of the context that holds a file (src/backend/notes), or undefined. @type {(path: string) => string | undefined} */
-const contextFolderOf = path => /^src\/(backend|frontend)\/[^/]+(?=\/)/.exec(path)?.[0];
+export const contextFolderOf = path => /^src\/(backend|frontend)\/[^/]+(?=\/)/.exec(path)?.[0];
 
 /**
  * An import names a package (the kernel is one), or a file of the project: its target is then the path from the root of the project.
@@ -95,6 +138,38 @@ export const importedModules = (file, root) => file.imports
   .filter(({ internal }) => internal)
   .map(({ target }) => target.replace(/\.(js|ts)$/, ""));
 
+/** A class that a file names: its name, and its module (the file of the project without its extension, or the specifier of a package). @typedef {{ name: string; module: string }} Named */
+/**
+ * A line of a context map: whether it shares (share) or hears (when), the event that starts it, the classes that it builds, as the
+ * file imports them, and its line in the file. A name that the file does not import has no module: the line names a class of its own file.
+ * @typedef {{ shares: boolean; source: string; event: Named | null; gives: Named[]; line: number }} MapLine
+ */
+
+/**
+ * The lines of a context map, `export default [when(Event, …), share(Event, …)]`, in their order. Its other items are left aside.
+ * @param {File} file
+ * @param {string} root
+ * @returns {MapLine[]}
+ */
+export function linesOf(file, root) {
+  /** @type {(name: string | null) => Named | null} */
+  const named = name => {
+    const imported = file.imported.find(entry => entry.name === name);
+    if (!name || !imported) return null;
+    const { internal, target } = resolveImport(file.path, imported.from, root);
+    return { name, module: internal ? target.replace(/\.(js|ts)$/, "") : target };
+  };
+  return (file.defaultArray ?? [])
+    .filter(({ chain }) => chain.length === 1 && (chain[0] === "when" || chain[0] === "share"))
+    .map(({ chain: [call], source, subject, constructed, line }) => ({
+      shares: call === "share",
+      source,
+      event: named(subject),
+      gives: constructed.map(named).filter(/** @returns {given is Named} */ given => given !== null),
+      line
+    }));
+}
+
 /** @type {(specifier: string, ...names: string[]) => boolean} */
 export const isPackage = (specifier, ...names) => names.some(name => specifier === name || specifier.startsWith(`${name}/`));
 /** @type {(specifier: string) => boolean} */
@@ -128,7 +203,24 @@ export function adapterOf(path) {
 }
 
 /** The contexts whose frontend a file takes: `frontendOf($global, "notes")` takes the frontend of notes. @type {(file: File) => string[]} */
-export const frontendsOf = file => file.calls.flatMap(({ name, args: [, context] }) => name === "frontendOf" && typeof context === "string" ? [context] : []);
+export const frontendsOf = file => frontendCallsOf(file).map(({ context }) => context);
+/** Each call of a file that takes a frontend: its context, and its line. @type {(file: File) => { context: string; line: number }[]} */
+export const frontendCallsOf = file => file.calls.flatMap(({ name, args: [, context], line }) => name === "frontendOf" && typeof context === "string" ? [{ context, line }] : []);
+
+/**
+ * The key of the list of each layer in quality/imports.mjs. The layers of a context have one each; the routes and the files out of the
+ * contexts have none.
+ * @type {Record<string, keyof Packages>}
+ */
+export const LISTS = { domain: "domain", application: "application", presentation: "presentation", infra: "infra", di: "di", map: "contextMap" };
+
+/**
+ * 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`).
+ * @param {string} specifier
+ * @param {string[]} list
+ */
+export const isListed = (specifier, list) => list.some(entry => entry.endsWith("/*") ? specifier.startsWith(entry.slice(0, -1)) : specifier === entry);
 
 /** @type {(name: string) => string} */
 export const kebab = name => name.replace(/(?<!^)([A-Z])/g, "-$1").toLowerCase();

package/quality/architecture.mjs

@@ -4,67 +4,76 @@ import { pathToFileURL } from "node:url";
 import { readMarko } from "./architecture/adapters/marko.mjs";
 import { readScss } from "./architecture/adapters/scss.mjs";
 import { readTypeScript } from "./architecture/adapters/typescript.mjs";
-import { isTestCode, locate, resolveImport } from "./architecture/project.mjs";
+import { isTestCode, LISTS, locate, resolveImport } from "./architecture/project.mjs";
+import { painterOf } from "./terminal.mjs";
 
 /** What a rule knows of the project. The rules of CAITS use it, and the rules of a project can use it too. */
 export * from "./architecture/project.mjs";
 
-/** @import { File, Import, Messages, Rule } from "./architecture/project.mjs" */
-/** @typedef {{ rule: string; file: string; message: string; subject?: string }} Violation */
+/** @import { File, Import, Located, Messages, Packages, Rule } from "./architecture/project.mjs" */
+/** A rule that a file breaks: the rule, the file, the message, and the line of the construct that breaks it, if the rule points at one. @typedef {{ rule: string; file: string; message: string; line?: number }} Violation */
 
 /** The file of a project that gives its rules: its default export is the list of the rules. */
 export const RULES_FILE = "quality/architecture.mjs";
+/** The file of a project that gives the packages that each layer may import: its default export. Without it, those of CAITS apply. */
+export const PACKAGES_FILE = "quality/imports.mjs";
+/** The packages that each layer may import in CAITS (`caits update` writes them): their export `allowed`. */
+export const DEFAULT_PACKAGES_FILE = "quality/caits/imports.mjs";
 
 /**
- * Checks the rules on the files of a project. Each source is a file: its path from the root of the project, and its text.
- * Gives the production files, the test files, and each violation: its rule, its file, its message, and the import that breaks it.
+ * Checks the rules on the files of a project. Each source is a file: its path from the root of the project, and its text. The packages
+ * are those that each layer may import: the rules read them in the project.
+ * Gives the production files, the test files, and each violation: its rule, its file, its message, and its line.
  * @param {string} root
  * @param {{ path: string; text: string }[]} sources
  * @param {Rule[]} rules
+ * @param {Packages} [packages]
  * @returns {{ production: number; tests: number; violations: Violation[] }}
  */
-export function checkArchitecture(root, sources, rules) {
+export function checkArchitecture(root, sources, rules, packages = {}) {
   checkRules(rules);
+  checkPackages(packages);
   const paths = new Set(sources.map(({ path }) => path));
   /** @type {(path: string, text: string) => import("./architecture/facts.mjs").Facts} */
   const read = (path, text) => {
-    if (path.endsWith(".marko")) return readMarko(join(root, path), text);
+    if (path.endsWith(".marko")) return readMarko(join(root, path), text, root);
     return path.endsWith(".scss") ? readScss(path, text, paths) : readTypeScript(path, text);
   };
   /** @type {File[]} */
   const files = sources.map(({ path, text }) => ({ path, ...read(path, text) }));
   const production = files.filter(file => !isTestCode(file.path));
-  const project = { root, files, paths };
+  const project = { root, files, paths, packages };
 
   /** @type {Violation[]} */
   const violations = [];
-  /** @type {(rule: Rule, file: string, message: string, subject?: string) => void} */
-  const report = (rule, file, message, subject) => { violations.push({ rule: rule.name, file, message, subject }); };
-  /** @type {(result: Messages) => string[]} */
-  const messagesOf = result => !result ? [] : Array.isArray(result) ? result : [result];
+  /** @type {(rule: Rule, file: string, located: Located) => void} */
+  const report = (rule, file, { line, message }) => { violations.push({ rule: rule.name, file, message, ...(line === undefined ? {} : { line }) }); };
+  /** The messages of a check, each with its line, or the line of the import for a rule on the imports. @type {(result: Messages, line?: number) => Located[]} */
+  const messagesOf = (result, line) => (!result ? [] : Array.isArray(result) ? result : [result])
+    .map(message => typeof message === "string" ? { line, message } : { ...message, line: message.line ?? line });
 
   for (const rule of rules) {
     if (rule.on === "file") {
       for (const file of rule.production ? production : files) {
-        for (const message of messagesOf(rule.check(file, project))) report(rule, file.path, message);
+        for (const located of messagesOf(rule.check(file, project))) report(rule, file.path, located);
       }
     }
     if (rule.on === "project") {
-      for (const { file, message } of rule.check(project)) report(rule, file, message);
+      for (const { file, ...located } of rule.check(project)) report(rule, file, located);
     }
   }
 
   const importRules = rules.filter(/** @returns {rule is Extract<Rule, { on: "import" }>} */ rule => rule.on === "import");
   for (const file of production) {
     const from = locate(file.path);
-    for (const specifier of file.imports) {
+    file.imports.forEach((specifier, index) => {
       const { internal, target } = resolveImport(file.path, specifier, root);
       /** @type {Import} */
-      const link = { file, from, to: internal ? locate(target) : { kind: "other" }, specifier, internal, target };
+      const link = { file, from, to: internal ? locate(target) : { kind: "other" }, specifier, internal, target, line: file.lines.imports[index] };
       for (const rule of importRules) {
-        for (const message of messagesOf(rule.check(link))) report(rule, file.path, message, target);
+        for (const located of messagesOf(rule.check(link, project), link.line)) report(rule, file.path, located);
       }
-    }
+    });
   }
 
   return { production: production.length, tests: files.length - production.length, violations };
@@ -88,9 +97,35 @@ function checkRules(rules) {
   }
 }
 
+/**
+ * Each list of packages has the key of a layer (see LISTS), and holds names of packages.
+ * @param {unknown} packages
+ * @returns {asserts packages is Packages}
+ */
+function checkPackages(packages) {
+  const keys = new Set(Object.values(LISTS));
+  const lists = packages !== null && typeof packages === "object" && !Array.isArray(packages) ? Object.entries(packages) : null;
+  const wrong = lists?.find(([key, list]) => !keys.has(/** @type {keyof Packages} */ (key)) || !Array.isArray(list) || list.some(entry => typeof entry !== "string"));
+  if (!lists || wrong) {
+    throw new Error(`${PACKAGES_FILE} must export the packages that each layer may import, as lists of names: { ${[...keys].map(key => `${key}: […]`).join(", ")} }${wrong ? ` (${wrong[0]})` : ""}`);
+  }
+}
+
 /** @type {(file: string) => Promise<unknown>} */
 const importFile = file => import(pathToFileURL(file).href);
 
+/**
+ * The packages that each layer of a project may import: those of its quality/imports.mjs, else those of CAITS (quality/caits/imports.mjs),
+ * else none: then every layer imports any package.
+ * @param {string} root
+ * @returns {Promise<unknown>}
+ */
+async function packagesOf(root) {
+  if (existsSync(join(root, PACKAGES_FILE))) return /** @type {{ default: unknown }} */ (await importFile(join(root, PACKAGES_FILE))).default;
+  if (existsSync(join(root, DEFAULT_PACKAGES_FILE))) return /** @type {{ allowed: unknown }} */ (await importFile(join(root, DEFAULT_PACKAGES_FILE))).allowed;
+  return {};
+}
+
 /** `caits architecture`: checks the rules of quality/architecture.mjs on the files of src/ and test/: the code, and the stylesheets (SCSS). */
 export async function run() {
   const root = process.cwd();
@@ -104,13 +139,24 @@ export async function run() {
   const sources = [...walk(join(root, "src")), ...walk(join(root, "test"))]
     .filter(path => /\.(ts|marko|scss)$/.test(path))
     .map(absolute => ({ path: relative(root, absolute).replaceAll("\\", "/"), text: readFileSync(absolute, "utf8") }));
-  const { production, tests, violations } = checkArchitecture(root, sources, rules);
+  const packages = /** @type {Packages} */ (await packagesOf(root));
+  const { production, tests, violations } = checkArchitecture(root, sources, rules, packages);
 
   if (violations.length === 0) {
-    console.log(`Architecture: ${production} production files and ${tests} test files respect the ${rules.length} rules.`);
+    console.log(painterOf(process.stdout)("green", `Architecture: ${production} production files and ${tests} test files respect the ${rules.length} rules.`));
     return 0;
   }
-  for (const { rule, file, message, subject } of violations) console.error(`${file}${subject ? ` → ${subject}` : ""}: ${message} (${rule})`);
-  console.error(`\n${violations.length} architecture ${violations.length === 1 ? "violation" : "violations"}.`);
+  const paint = painterOf(process.stderr);
+  for (const violation of violations) console.error(lineOf(violation, paint));
+  console.error(`\n${paint(["red", "bold"], `${violations.length} architecture ${violations.length === 1 ? "violation" : "violations"}.`)}`);
   return 1;
 }
+
+/**
+ * The line of a violation: the file and its line in cyan, the rule dim, then the message.
+ * @param {Violation} violation
+ * @param {import("./terminal.mjs").Paint} paint
+ */
+export function lineOf({ rule, file, message, line }, paint) {
+  return `${paint("cyan", `${file}${line ? `:${line}` : ""}`)} ${paint("dim", `[${rule}]`)} ${message}`;
+}

package/quality/check.mjs

@@ -3,10 +3,13 @@
 // The builds of Marko and the starts of Vitest write their files in the build folder: the checks that run at once would empty the
 // folder of each other. Each check gets a folder of its own in CAITS_OUT_DIR, which quality/caits/vite.ts reads. The end-to-end tests
 // build in dist/ all the same: `npm start` runs dist/index.mjs.
+// In a terminal, the report has colors, and so has the output of a check that fails: the checks run with FORCE_COLOR. In a pipe (an AI
+// agent, a log), the report and the checks have none: they run with NO_COLOR.
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { constants } from "node:os";
 import { join } from "node:path";
+import { colors, painterOf } from "./terminal.mjs";
 
 export const OUT_DIRS = "node_modules/.caits/check";
 
@@ -26,16 +29,17 @@ export async function run(args) {
 
 /**
  * Runs each npm script of `scripts` in the project of `root`, all at once, each in a group of processes of its own: the end of the
- * command, or Ctrl+C, stops the servers and the workers that a check starts. `print` gets each line of the report. Gives the exit code:
- * 0 when all the checks pass.
+ * command, or Ctrl+C, stops the servers and the workers that a check starts. `print` gets each line of the report, and `paint` colors
+ * its parts. Gives the exit code: 0 when all the checks pass.
  * @param {string} root
  * @param {string[]} scripts
  * @param {(line: string) => void} [print]
+ * @param {import("./terminal.mjs").Paint} [paint]
  * @returns {Promise<number>}
  */
-export async function check(root, scripts, print = line => console.log(line)) {
+export async function check(root, scripts, print = line => console.log(line), paint = painterOf(process.stdout)) {
   if (scripts.length === 0) {
-    print("Give the npm scripts of the checks: caits check typecheck lint test");
+    print(paint("red", "Give the npm scripts of the checks: caits check typecheck lint test"));
     return 1;
   }
   // npm says nothing of a missing script when it runs silent: the command names them, and runs nothing.
@@ -43,14 +47,14 @@ export async function check(root, scripts, print = line => console.log(line)) {
   const known = existsSync(manifest) ? /** @type {{ scripts?: Record<string, string> }} */ (readJson(manifest)).scripts ?? {} : {};
   const missing = scripts.filter(script => !Object.hasOwn(known, script));
   if (missing.length > 0) {
-    print(`package.json has no script ${missing.join(", ")}.`);
+    print(paint("red", `package.json has no script ${missing.join(", ")}.`));
     return 1;
   }
   const width = Math.max(...scripts.map(script => script.length));
   const started = Date.now();
-  print(`${scripts.length} checks at once: ${scripts.join(", ")}`);
+  print(paint("dim", `${scripts.length} checks at once: ${scripts.join(", ")}`));
 
-  const steps = scripts.map(script => start(root, script));
+  const steps = scripts.map(script => start(root, script, colors(paint)));
   const stop = () => { for (const step of steps) step.stop(); };
   /** @param {NodeJS.Signals} signal Ctrl+C (SIGINT) exits with 130, SIGTERM with 143, as a shell tells a command that a signal stops. */
   const interrupt = signal => { stop(); process.exit(128 + constants.signals[signal]); };
@@ -59,15 +63,15 @@ export async function check(root, scripts, print = line => console.log(line)) {
   try {
     const results = await Promise.all(steps.map(async step => {
       const result = await step.done;
-      print(`${result.passed ? "✓" : "✗"} ${step.script.padEnd(width)}  ${durationOf(result.duration)}`);
+      print(`${result.passed ? paint("green", "✓") : paint("red", "✗")} ${step.script.padEnd(width)}  ${paint("dim", durationOf(result.duration))}`);
       return { script: step.script, ...result };
     }));
     const failed = results.filter(result => !result.passed);
-    for (const { script, output } of failed) print(`\n── ${script} ──\n${output.trimEnd()}`);
+    for (const { script, output } of failed) print(`\n${paint("bold", `── ${script} ──`)}\n${output.trimEnd()}`);
     const total = durationOf(Date.now() - started);
     print(failed.length === 0
-      ? `\nAll ${results.length} checks passed in ${total}.`
-      : `\n${failed.length} of ${results.length} checks failed: ${failed.map(({ script }) => script).join(", ")}.`);
+      ? `\n${paint(["green", "bold"], `All ${results.length} checks passed in ${total}.`)}`
+      : `\n${paint(["red", "bold"], `${failed.length} of ${results.length} checks failed: ${failed.map(({ script }) => script).join(", ")}.`)}`);
     return failed.length === 0 ? 0 : 1;
   } finally {
     process.off("SIGINT", interrupt);
@@ -77,13 +81,15 @@ export async function check(root, scripts, print = line => console.log(line)) {
 }
 
 /**
- * Starts `npm run <script>`, with its build folder, and keeps its output.
+ * Starts `npm run <script>`, with its build folder, and keeps its output: with the colors of its tool when the report has colors.
  * @param {string} root
  * @param {string} script
+ * @param {boolean} colored
  */
-function start(root, script) {
+function start(root, script, colored) {
   const began = Date.now();
-  const env = { ...process.env, CAITS_OUT_DIR: join(OUT_DIRS, script.replaceAll(":", "-")) };
+  const { FORCE_COLOR: _force, NO_COLOR: _no, ...rest } = process.env;
+  const env = { ...rest, ...(colored ? { FORCE_COLOR: "1" } : { NO_COLOR: "1" }), CAITS_OUT_DIR: join(OUT_DIRS, script.replaceAll(":", "-")) };
   const child = spawn("npm", ["run", "--silent", script], { cwd: root, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
   let output = "";
   child.stdout.on("data", chunk => { output += chunk; });

package/quality/dev.mjs

@@ -11,6 +11,7 @@
 import { existsSync } from "node:fs";
 import adapter from "@marko/run/adapter";
 import { loadConfigFromFile } from "vite";
+import { painterOf } from "./terminal.mjs";
 
 export const VITE_CONFIG = "quality/vite.config.ts";
 export const OUT_DIR = "node_modules/.caits/dev";
@@ -78,7 +79,7 @@ export async function run(args) {
         await restartOnce();
       } while (changedAgain);
     })().catch(error => {
-      console.error(`\nThe development server stopped: ${error instanceof Error ? error.message : error}\nCorrect the error, then start the server again: npm run dev`);
+      console.error(`\n${painterOf(process.stderr)("red", `The development server stopped: ${String(error instanceof Error ? error.message : error)}\nCorrect the error, then start the server again: npm run dev`)}`);
       process.exit(1);
     }).finally(() => {
       restarting = undefined;
@@ -95,7 +96,7 @@ async function configurationLoads() {
     await loadConfigFromFile({ command: "serve", mode: "development" }, VITE_CONFIG, process.cwd(), "silent");
     return true;
   } catch (error) {
-    console.error(`\n${VITE_CONFIG} does not load: the server keeps the configuration that it has.\n${error instanceof Error ? error.message : String(error)}`);
+    console.error(`\n${painterOf(process.stderr)("red", `${VITE_CONFIG} does not load: the server keeps the configuration that it has.\n${error instanceof Error ? error.message : String(error)}`)}`);
     return false;
   }
 }

package/quality/mutation-suite.mjs

@@ -1,31 +1,82 @@
 // `caits mutation-suite`: the command that Stryker runs for each mutant. It runs the unit tests from a private copy of the sandbox.
 // Stryker runs many suites at once in a single sandbox, and every Vitest start rewrites the files that the Marko plugin generates
 // (dist/, .marko-run/): suites that run at the same time would fail at random, and a failed run counts as a killed mutant.
+// The copy shares the packages of the sandbox, not the caches that the tools keep beside them (node_modules/.vite/, .vitest-cache/…): the
+// cache of Vite depends on the folder of the project, so each suite would write it again while the others read it.
 import { spawn } from "node:child_process";
-import { cpSync, existsSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from "node:fs";
 import { constants, tmpdir } from "node:os";
 import { join } from "node:path";
+import { painterOf } from "./terminal.mjs";
 
 const ENTRIES = ["src", "test", "quality", "dist", ".marko-run", "package.json", "tsconfig.json"];
 
+/** The report of Vitest, in the copy: Vitest writes it once the tests ran, also when one fails. */
+const REPORT = "vitest-report.json";
+
+/**
+ * What the suite prints when the unit tests did not run. Stryker counts the mutant as killed, as for any exit code but 0:
+ * `caits mutation-summary` finds these words in the report of Stryker, and does not.
+ */
+export const NOT_RUN = "The unit tests did not run";
+
+/** The copies, in the temporary folder: `caits-mutation-<pid of their suite>-<random>`. */
+const COPY = /^caits-mutation-(\d+)-/;
+
 /** @param {string[]} args the options of Vitest, which Stryker gives */
 export async function run(args) {
+  removeOrphans();
   const sandbox = process.cwd();
-  const copy = mkdtempSync(join(tmpdir(), "caits-mutation-"));
+  const copy = mkdtempSync(join(tmpdir(), `caits-mutation-${process.pid}-`));
   const remove = () => rmSync(copy, { recursive: true, force: true });
   for (const entry of ENTRIES) {
     if (existsSync(join(sandbox, entry))) cpSync(join(sandbox, entry), join(copy, entry), { recursive: true });
   }
-  symlinkSync(join(sandbox, "node_modules"), join(copy, "node_modules"));
+  // The packages and their commands (.bin/). The other entries that start with a dot are the caches and the files of the tools.
+  mkdirSync(join(copy, "node_modules"));
+  for (const entry of readdirSync(join(sandbox, "node_modules"))) {
+    if (!entry.startsWith(".") || entry === ".bin") symlinkSync(join(sandbox, "node_modules", entry), join(copy, "node_modules", entry));
+  }
 
   // The suite builds in the dist/ of its copy: the build folder that `caits check` gives (CAITS_OUT_DIR) is in node_modules/, which the
   // suites share.
   const { CAITS_OUT_DIR: _, ...env } = process.env;
-  const suite = spawn("npx", ["vitest", "run", "--config", "quality/vite.config.ts", "--reporter=dot", ...args], { cwd: copy, env, stdio: "inherit" });
-  // Stryker stops a suite that takes too long: the copy goes away with it. The exit code tells the signal: 130 for SIGINT, 143 for SIGTERM.
+  const vitest = ["vitest", "run", "--config", "quality/vite.config.ts", "--reporter=dot", "--reporter=json", `--outputFile.json=${REPORT}`, ...args];
+  const suite = spawn("npx", vitest, { cwd: copy, env, stdio: "inherit" });
+  // Ctrl+C and `caits check` stop the suite: the copy goes away with it. The exit code tells the signal: 130 for SIGINT, 143 for SIGTERM.
   for (const signal of /** @type {const} */ (["SIGINT", "SIGTERM"])) process.on(signal, () => { suite.kill(signal); remove(); process.exit(128 + constants.signals[signal]); });
   /** @type {number} */
   const status = await new Promise(resolve => suite.on("close", code => resolve(code ?? 1)));
+  const ran = existsSync(join(copy, REPORT));
   remove();
+  // Vitest stopped before the tests, on an error of its own or of the system: no test failed, and the mutant is not tested.
+  if (status !== 0 && !ran) console.error(painterOf(process.stderr)("red", `${NOT_RUN}: Vitest stopped before them (exit ${status}). The mutant is not tested.`));
   return status;
 }
+
+/**
+ * Stryker stops a suite that takes too long with SIGKILL, which no code can follow: its copy stays. Each suite removes the copies whose
+ * suite no longer runs.
+ */
+function removeOrphans() {
+  for (const entry of readdirSync(tmpdir())) {
+    const pid = COPY.exec(entry)?.[1];
+    if (pid === undefined || runs(Number(pid))) continue;
+    try {
+      rmSync(join(tmpdir(), entry), { recursive: true, force: true });
+    } catch {
+      // The copy 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";
+  }
+}