@ingenioz-it/caits 0.0.0-stage → 0.5.1

package/quality/check.mjs

@@ -0,0 +1,104 @@
+// `caits check <script>…`: runs the npm scripts of the checks at once, then tells which pass and which fail. It shows the output of the
+// checks that fail, and only theirs: a check that passes takes one line, for the developer and for an AI agent, who reads less.
+// 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.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { constants } from "node:os";
+import { join } from "node:path";
+
+export const OUT_DIRS = "node_modules/.caits/check";
+
+/** @type {(file: string) => unknown} */
+const readJson = file => JSON.parse(readFileSync(file, "utf8"));
+
+/** @param {number} milliseconds */
+const durationOf = milliseconds => {
+  const seconds = Math.round(milliseconds / 1000);
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
+};
+
+/** @param {string[]} args the npm scripts of the checks */
+export async function run(args) {
+  return check(process.cwd(), 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.
+ * @param {string} root
+ * @param {string[]} scripts
+ * @param {(line: string) => void} [print]
+ * @returns {Promise<number>}
+ */
+export async function check(root, scripts, print = line => console.log(line)) {
+  if (scripts.length === 0) {
+    print("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.
+  const manifest = join(root, "package.json");
+  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(", ")}.`);
+    return 1;
+  }
+  const width = Math.max(...scripts.map(script => script.length));
+  const started = Date.now();
+  print(`${scripts.length} checks at once: ${scripts.join(", ")}`);
+
+  const steps = scripts.map(script => start(root, script));
+  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]); };
+  process.once("SIGINT", interrupt);
+  process.once("SIGTERM", interrupt);
+  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)}`);
+      return { script: step.script, ...result };
+    }));
+    const failed = results.filter(result => !result.passed);
+    for (const { script, output } of failed) print(`\n── ${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(", ")}.`);
+    return failed.length === 0 ? 0 : 1;
+  } finally {
+    process.off("SIGINT", interrupt);
+    process.off("SIGTERM", interrupt);
+    stop();
+  }
+}
+
+/**
+ * Starts `npm run <script>`, with its build folder, and keeps its output.
+ * @param {string} root
+ * @param {string} script
+ */
+function start(root, script) {
+  const began = Date.now();
+  const env = { ...process.env, 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; });
+  child.stderr.on("data", chunk => { output += chunk; });
+  /** @type {Promise<{ passed: boolean; duration: number; output: string }>} */
+  const done = new Promise(resolve => {
+    child.on("error", error => resolve({ passed: false, duration: Date.now() - began, output: `${output}${error.message}\n` }));
+    child.on("close", code => resolve({ passed: code === 0, duration: Date.now() - began, output }));
+  });
+  const stop = () => {
+    try {
+      if (child.pid) process.kill(-child.pid);
+    } catch {
+      // The group stopped already.
+    }
+  };
+  return { script, done, stop };
+}

package/quality/dev.mjs

@@ -0,0 +1,110 @@
+// `caits dev`: starts the development server, as `marko-run dev` does, on the port PORT (3000 when not set).
+// Before it starts, `marko-run dev` connects to the port of the server and to the port of HMR to find out whether they are free, and
+// it waits for an answer with no time limit. With WSL `networkingMode=mirrored`, a connection to a closed port of 127.0.0.1 gets no
+// 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.
+// @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";
+
+export const VITE_CONFIG = "quality/vite.config.ts";
+export const OUT_DIR = "node_modules/.caits/dev";
+
+/**
+ * When a file of its configuration changes (quality/vite.config.ts, an .env file…), Vite restarts its server: it makes a new one, and
+ * keeps only the middlewares of Vite. @marko/run adds the middleware of the pages after Vite makes the server: the new server answered
+ * 404 to each page. Thus Vite asks `caits dev` for the restart, and `caits dev` closes the server of @marko/run, then starts a new one:
+ * - when the configuration does not load (an error in the file), the server that runs stays: Vite asks again at the next change;
+ * - a change that comes during a restart makes one more restart, after it: the new server reads the configuration after the change;
+ * - when the new server cannot start, the command stops, and tells why.
+ * @param {string[]} args the arguments of the server
+ */
+export async function run(args) {
+  if (!existsSync(VITE_CONFIG)) throw new Error(`${VITE_CONFIG} is missing: it gives the configuration of Vite. Run \`npx caits init .\` to write it.`);
+  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.
+  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.`);
+  const entry = await getEntryFile();
+  /** @type {import("@marko/run/adapter").SpawnedServer} the server of @marko/run */
+  let running;
+  /** @type {import("vite").ViteDevServer} its Vite server */
+  let vite;
+  /** @type {Promise<void> | undefined} */
+  let restarting;
+  let changedAgain = false;
+
+  const start = async () => {
+    running = await startDev({
+      entry,
+      config: {
+        root: process.cwd(),
+        configFile: VITE_CONFIG,
+        build: { outDir: OUT_DIR },
+        server: { hmr: { port: hmrPort } },
+        plugins: [restartsTakenBy(server => {
+          vite = server;
+          server.restart = restart;
+        })]
+      },
+      options: { cwd: process.cwd(), args, port }
+    });
+  };
+
+  const restartOnce = async () => {
+    if (!(await configurationLoads())) return;
+    await running.close();
+    // @marko/run waits half a second for the close of Vite. The new server needs the port of HMR: it waits for the end of the close.
+    await vite.close();
+    await start();
+  };
+
+  const restart = () => {
+    if (restarting) {
+      changedAgain = true;
+      return restarting;
+    }
+    restarting = (async () => {
+      do {
+        changedAgain = false;
+        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`);
+      process.exit(1);
+    }).finally(() => {
+      restarting = undefined;
+    });
+    return restarting;
+  };
+
+  await start();
+}
+
+/** Whether the Vite configuration of the project loads. When it does not, says why. */
+async function configurationLoads() {
+  try {
+    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)}`);
+    return false;
+  }
+}
+
+/**
+ * A plugin that gives the Vite server to `caits dev`, which takes its restarts (see run).
+ * @param {(server: import("vite").ViteDevServer) => void} take
+ * @returns {import("vite").Plugin}
+ */
+function restartsTakenBy(take) {
+  return { name: "caits-dev-restart", apply: "serve", configureServer: take };
+}

package/quality/e2e.mjs

@@ -0,0 +1,125 @@
+// `caits e2e`: runs the end-to-end tests of quality/playwright.config.ts on the production build.
+// Playwright can start the servers itself (webServer), but it first connects to its address to find out whether a server runs there.
+// With WSL `networkingMode=mirrored`, a connection to a closed port of 127.0.0.1 gets no answer, so Playwright waits forever. This
+// command starts each server of webServer itself, waits with a time limit until it answers, then lets Playwright use them.
+import { spawn } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { constants } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const PLAYWRIGHT_CONFIG = "quality/playwright.config.ts";
+
+/** How long a server has to answer, when its webServer gives no timeout, in milliseconds. */
+const DEFAULT_TIMEOUT = 120_000;
+
+/** @typedef {{ command: string; url: string; cwd?: string; env?: Record<string, string>; timeout: number }} WebServer */
+
+/** @type {(file: string) => Promise<unknown>} */
+const importFile = file => import(pathToFileURL(file).href);
+
+/**
+ * Stops a process that runs in a group of processes of its own, and the processes that it started.
+ * @param {import("node:child_process").ChildProcess} child
+ */
+function stopGroup(child) {
+  try {
+    if (child.pid) process.kill(-child.pid);
+  } catch {
+    // The group stopped already.
+  }
+}
+
+/**
+ * Starts the servers, empties the folder of the data of each (DATA_DIR) first, then runs Playwright. The end of the command stops the
+ * servers, also when Ctrl+C (SIGINT) or `caits check` (SIGTERM) stops it: the exit code then tells the signal, 130 or 143.
+ * @param {string[]} args the arguments of Playwright
+ * @returns {Promise<number>}
+ */
+export async function run(args) {
+  const file = join(process.cwd(), PLAYWRIGHT_CONFIG);
+  if (!existsSync(file)) throw new Error(`${PLAYWRIGHT_CONFIG} is missing: it gives the end-to-end tests and their server. Run \`npx caits init .\` to write it.`);
+  const { default: config } = /** @type {{ default: { webServer?: Partial<WebServer> | Partial<WebServer>[] } }} */ (await importFile(file));
+  const webServers = [config.webServer ?? []].flat();
+
+  /** @type {{ stop: () => void }[]} */
+  const servers = [];
+  /** @type {import("node:child_process").ChildProcess | undefined} */
+  let playwright;
+  const stop = () => {
+    if (playwright) stopGroup(playwright);
+    for (const server of servers) server.stop();
+  };
+  /** @param {NodeJS.Signals} signal */
+  const interrupt = signal => {
+    stop();
+    process.exit(128 + constants.signals[signal]);
+  };
+  process.once("SIGINT", interrupt);
+  process.once("SIGTERM", interrupt);
+  try {
+    for (const { command, url, cwd, env = {}, timeout = DEFAULT_TIMEOUT } of webServers) {
+      if (!command || !url) throw new Error(`each webServer of ${PLAYWRIGHT_CONFIG} must give a command and a url`);
+      if (env.DATA_DIR) rmSync(env.DATA_DIR, { recursive: true, force: true });
+      servers.push(await startServer({ command, url, cwd, env, timeout }));
+    }
+    // Playwright runs in a group of processes of its own too, with its browsers: `stop` stops them all. It reads nothing from the terminal.
+    const env = { ...process.env, E2E_REUSE_SERVER: "1" };
+    const started = spawn("npx", ["playwright", "test", "--config", PLAYWRIGHT_CONFIG, ...args], { stdio: ["ignore", "inherit", "inherit"], detached: true, env });
+    playwright = started;
+    return await new Promise(resolve => {
+      started.on("error", () => resolve(1));
+      started.on("close", code => resolve(code ?? 1));
+    });
+  } finally {
+    process.off("SIGINT", interrupt);
+    process.off("SIGTERM", interrupt);
+    stop();
+  }
+}
+
+/**
+ * Runs the command of a server in a group of processes of its own, so that `stop` also stops the processes that it starts, then waits
+ * until the server answers at its URL, for `timeout` milliseconds at most. The port of the URL must be free: else the tests would run on
+ * the server that uses it, with the build of another project, or of an older run.
+ * @param {WebServer} webServer
+ * @returns {Promise<{ stop: () => void }>}
+ */
+export async function startServer({ command, url, cwd, env = {}, timeout }) {
+  const { hostname, port, protocol } = new URL(url);
+  const portNumber = Number(port) || (protocol === "https:" ? 443 : 80);
+  if (!(await isFree(hostname.replace(/^\[|\]$/g, ""), portNumber))) {
+    throw new Error(`Port ${portNumber} is in use: a server runs at ${url} already. Stop it, then run the end-to-end tests again.`);
+  }
+  const server = spawn(command, { cwd, shell: true, stdio: "inherit", detached: true, env: { ...process.env, ...env } });
+  const stop = () => stopGroup(server);
+  process.on("exit", stop);
+  for (const end = Date.now() + timeout; Date.now() < end;) {
+    if (server.exitCode !== null) throw new Error(`The server stopped (${command})`);
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(500) });
+      if (response.ok) return { stop };
+    } catch {
+      // The server does not answer yet.
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  stop();
+  throw new Error(`The server did not answer at ${url} in ${timeout / 1000} s (${command})`);
+}
+
+/**
+ * Whether a server can listen on a port. A listen fails at once when the port is in use: a connection to a closed port can wait forever
+ * (see above). Another error (a port that only the system can use) does not tell that a server runs there.
+ * @param {string} hostname
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function isFree(hostname, port) {
+  return new Promise(resolve => {
+    const probe = createServer();
+    probe.once("error", (/** @type {NodeJS.ErrnoException} */ error) => resolve(error.code !== "EADDRINUSE"));
+    probe.listen(port, hostname, () => probe.close(() => resolve(true)));
+  });
+}

package/quality/mutation-suite.mjs

@@ -0,0 +1,31 @@
+// `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.
+import { spawn } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { constants, tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ENTRIES = ["src", "test", "quality", "dist", ".marko-run", "package.json", "tsconfig.json"];
+
+/** @param {string[]} args the options of Vitest, which Stryker gives */
+export async function run(args) {
+  const sandbox = process.cwd();
+  const copy = mkdtempSync(join(tmpdir(), "caits-mutation-"));
+  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 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.
+  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)));
+  remove();
+  return status;
+}

package/quality/mutation-summary.mjs

@@ -0,0 +1,41 @@
+// `caits mutation-summary`: the mutation score of each file, from the report of Stryker. With --survivors, the mutants that survived.
+import { existsSync, readFileSync } from "node:fs";
+
+/** The report that Stryker writes in JSON (quality/caits/stryker.mjs). */
+export const REPORT = "reports/mutation/mutation.json";
+
+/** @typedef {{ status: string; mutatorName: string; replacement?: string; location: { start: { line: number } } }} Mutant */
+
+/** @type {(file: string) => unknown} */
+const readJson = file => JSON.parse(readFileSync(file, "utf8"));
+
+/**
+ * @param {string[]} args
+ * @returns {number}
+ */
+export function run(args) {
+  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;
+  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 killed = count("Killed") + count("Timeout");
+    const survived = count("Survived");
+    const noCoverage = count("NoCoverage");
+    const valid = killed + survived + noCoverage;
+    killedTotal += killed; validTotal += valid;
+    rows.push({ file, killed, survived, noCoverage, score: valid ? (100 * killed) / valid : 100, survivors: data.mutants.filter(m => m.status === "Survived" || m.status === "NoCoverage"), source: data.source.split("\n") });
+  }
+  rows.sort((a, b) => a.score - b.score);
+  const verbose = args.includes("--survivors");
+  console.log(`Mutation score: ${(validTotal ? (100 * killedTotal) / validTotal : 100).toFixed(1)}%  (${killedTotal} killed of ${validTotal} valid mutants)\n`);
+  for (const row of rows) {
+    console.log(`${row.score.toFixed(0).padStart(4)}%  ${row.file}  (killed ${row.killed}, survived ${row.survived}, no coverage ${row.noCoverage})`);
+    if (verbose && row.survivors.length) {
+      for (const m of row.survivors) console.log(`        L${m.location.start.line} ${m.status === "NoCoverage" ? "[no cov]" : "[survived]"} ${m.mutatorName}: ${(row.source[m.location.start.line - 1] ?? "").trim().slice(0, 90)}  →  ${String(m.replacement ?? "").slice(0, 60)}`);
+    }
+  }
+  return 0;
+}

package/quality/mutation.mjs

@@ -0,0 +1,30 @@
+// `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.
+import { spawn } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import { REPORT, run as summary } from "./mutation-summary.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";
+
+/**
+ * @param {string[]} args the options of Stryker
+ * @returns {Promise<number>} the exit code of Stryker
+ */
+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.`);
+  // 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));
+  });
+  if (existsSync(REPORT)) {
+    console.log("");
+    summary(["--survivors"]);
+  }
+  return status;
+}

package/quality/route-types.mjs

@@ -0,0 +1,40 @@
+// The types of the routes: @marko/run writes them in .marko-run/routes.d.ts each time it reads the routes (a build, a start of Vitest or
+// of the development server). The lint reads them: they give the global `Run` of the handlers. Git ignores .marko-run/, so a new project
+// or a new clone has no types until one of these commands runs: the ESLint configuration of CAITS (quality/caits/eslint.js) writes them
+// first, with this function.
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { createServer } from "vite";
+
+export const VITE_CONFIG = "quality/vite.config.ts";
+
+/**
+ * @marko/run writes the entry files of the routes in the build folder: each run has one of its own, as `caits dev` has, which it removes
+ * at its end. Two lints can run at once: one in the editor, one in the terminal.
+ */
+export const OUT_DIR = "node_modules/.caits/route-types";
+
+/**
+ * Writes the types of the routes of the project of `root`: starts Vite with the configuration of the project, without a server, a
+ * watcher or HMR, and loads the router of @marko/run, which writes them. It takes less than a second.
+ * @param {string} root
+ * @returns {Promise<void>}
+ */
+export async function writeRouteTypes(root) {
+  const outDir = join(OUT_DIR, String(process.pid));
+  const vite = await createServer({
+    root,
+    configFile: join(root, VITE_CONFIG),
+    logLevel: "error",
+    appType: "custom",
+    build: { outDir },
+    server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+    optimizeDeps: { noDiscovery: true }
+  });
+  try {
+    await vite.environments.ssr.transformRequest("@marko/run/router");
+  } finally {
+    await vite.close();
+    rmSync(join(root, outDir), { recursive: true, force: true });
+  }
+}