@bluewombat/slots 0.8.0 → 0.10.0

package/gates/project-checks.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  ownArgv,
+  parseOptions,
+  take,
+  textOption,
+} from "@bluewombat/slot-kit";
+import { createOutputTail } from "../lib/output-tail.mjs";
+
+// Runs one command of the Project's own — a typecheck, a test suite, a linter,
+// a build — in the workspace, and answers on its exit code.
+//
+// --cmd COMMAND (required): run through the shell, so "pnpm test" and
+// "pnpm --filter web typecheck" are written as the Project writes them. One
+// command per Gate: the report then says which check failed, and the first red
+// one stops the sequence before a slower one starts. Give each check its own
+// entry, and its own timeoutMs.
+//
+// Nothing here knows a stack. The command is the Project's; the Gate only owns
+// what comes back: 0 passes, a red check is the producer's to fix
+// (fail-retryable, with the end of its output, where the error is), and what a
+// producer cannot fix is a person's (fail-blocking): a command the shell cannot
+// start, or a run that outlived its ceiling.
+//
+// It runs at both stages. At assembly it is the local answer on the assembled
+// ticket, so a Project without a CI of its own is still checked by a machine.
+
+const cwd = process.cwd();
+const KEEP_BYTES = 12_000;
+// Leave the Gate time to answer before Implementer's own clock reads the silence
+// as a refusal with nothing to fix.
+const MARGIN_MS = 5_000;
+const MIN_RUN_MS = 1_000;
+
+const parsed = parseOptions(ownArgv(process.argv, GATE_FLAGS), { "--cmd": {} }, "project-checks");
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", `${parsed.reason} Use --cmd "<command>".`);
+  process.exit(0);
+}
+const command = textOption(parsed.values, "cmd");
+if (command === undefined || command.trim().length === 0) {
+  emitVerdict("fail-blocking", 'project-checks needs --cmd "<command>": the check to run.');
+  process.exit(0);
+}
+
+const ceilingMs = Number(take(process.argv, "--timeout-ms"));
+const limitMs =
+  Number.isFinite(ceilingMs) && ceilingMs > 0
+    ? Math.max(MIN_RUN_MS, ceilingMs - MARGIN_MS)
+    : undefined;
+
+const child = spawn("sh", ["-c", command], {
+  cwd,
+  detached: true,
+  stdio: ["ignore", "pipe", "pipe"],
+  // CI=true keeps watchers (vitest, jest) from waiting on a terminal that is not there.
+  env: { ...process.env, CI: "true", NO_COLOR: "1", FORCE_COLOR: "0" },
+});
+
+// Cleaned as it arrives (progress redraws dropped), so they cannot push the error out of the tail.
+const tail = createOutputTail(KEEP_BYTES);
+child.stdout.on("data", (chunk) => tail.push("stdout", chunk));
+child.stderr.on("data", (chunk) => tail.push("stderr", chunk));
+
+let timedOut = false;
+const timer =
+  limitMs === undefined
+    ? undefined
+    : setTimeout(() => {
+        timedOut = true;
+        killGroup();
+      }, limitMs);
+
+child.on("error", (error) => {
+  clearTimeout(timer);
+  emitVerdict("fail-blocking", `project-checks cannot start "${command}": ${error.message}`);
+  process.exit(0);
+});
+
+child.on("close", (code, signal) => {
+  clearTimeout(timer);
+  const output = tail.text();
+  if (timedOut) {
+    emitVerdict(
+      "fail-blocking",
+      [
+        `"${command}" did not finish in ${Math.round((limitMs ?? 0) / 1000)}s and was stopped.`,
+        "A person decides: the check is hung, or this Gate's timeoutMs is too short for it.",
+        output.length > 0 ? `Last output:\n${output}` : "It printed nothing.",
+      ].join("\n"),
+    );
+    return;
+  }
+  if (code === 0) {
+    emitVerdict("pass");
+    return;
+  }
+  // 126 and 127: the shell found the command but could not run it, or did not
+  // find it. No change to the work fixes that.
+  if (code === 126 || code === 127) {
+    emitVerdict(
+      "fail-blocking",
+      `"${command}" could not be run here (exit ${code}): ${output || "no output"}`,
+    );
+    return;
+  }
+  emitVerdict(
+    "fail-retryable",
+    [
+      `"${command}" failed (${signal === null ? `exit ${code}` : `signal ${signal}`}). End of its output:`,
+      output.length > 0 ? output : "(it printed nothing)",
+    ].join("\n"),
+  );
+});
+
+function killGroup() {
+  // The shell's whole group: a test runner leaves workers that outlive their parent.
+  try {
+    if (child.pid !== undefined) {
+      process.kill(-child.pid, "SIGKILL");
+    }
+  } catch {
+    child.kill("SIGKILL");
+  }
+}

package/gates/tests-frozen.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  listOption,
+  ownArgv,
+  parseOptions,
+  pathMatchesGlob,
+  textOption,
+} from "@bluewombat/slot-kit";
+
+// The tests written first are not the producer's to change.
+//
+// The pass that writes the tests ends with a checkpoint: its work is committed, with a
+// subject that starts with "Tests: ". From then on the producer leaves its own work
+// uncommitted, so whatever differs from HEAD is the producer's. This Gate looks at the test
+// files that checkpoint holds and fails when one was modified, deleted or renamed: a test
+// edited until it passes proves nothing.
+//
+// Adding a new test file is allowed. Where HEAD is not a checkpoint of the tests pass (a
+// Project that runs none), nothing is frozen and the Gate passes.
+//
+// --test-glob GLOB (repeatable): which paths are test files. Default: **/*.test.*,
+//   **/*.spec.*, **/__tests__/**
+// --subject-prefix TEXT: how the checkpoint's subject starts. Default: "Tests: "
+
+const cwd = process.cwd();
+const DEFAULT_GLOBS = ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"];
+
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  { "--test-glob": { many: true }, "--subject-prefix": {} },
+  "tests-frozen",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", parsed.reason);
+  process.exit(0);
+}
+const globs = listOption(parsed.values, "testGlob");
+const testGlobs = globs.length > 0 ? globs : DEFAULT_GLOBS;
+const prefix = textOption(parsed.values, "subjectPrefix") ?? "Tests: ";
+
+if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "tests-frozen needs a git workspace.");
+  process.exit(0);
+}
+
+const subject = git(["log", "-1", "--format=%s"]);
+if (subject.status !== 0 || !subject.stdout.trim().startsWith(prefix)) {
+  emitVerdict("pass");
+  process.exit(0);
+}
+
+// The test files the checkpoint holds: those it added or changed in its own commit.
+const held = git(["show", "--name-only", "--diff-filter=AM", "--format=", "HEAD"])
+  .stdout.split("\n")
+  .map((line) => line.trim())
+  .filter((path) => path.length > 0 && testGlobs.some((glob) => pathMatchesGlob(path, glob)));
+if (held.length === 0) {
+  emitVerdict("pass");
+  process.exit(0);
+}
+
+// The working files against HEAD, whatever the index says; a new file is not in the diff.
+const diff = git(["diff", "--no-renames", "--name-status", "-z", "HEAD", "--", ...held]);
+if (diff.status !== 0) {
+  emitVerdict("fail-blocking", `tests-frozen cannot read git diff: ${diff.stderr.trim()}`);
+  process.exit(0);
+}
+const touched = [];
+const parts = diff.stdout.split("\0").filter(Boolean);
+for (let i = 0; i < parts.length; i += 2) {
+  const path = parts[i + 1];
+  if (path !== undefined) {
+    touched.push(path);
+  }
+}
+
+if (touched.length === 0) {
+  emitVerdict("pass");
+  process.exit(0);
+}
+emitVerdict(
+  "fail-retryable",
+  [
+    "These tests were written first, from the task's cases, and are not yours to change:",
+    ...touched,
+    `Restore them (git checkout HEAD -- ${touched.join(" ")}) and make the code pass them as they are. If a test is wrong, say so in your final message instead of editing it.`,
+  ].join("\n"),
+);
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}

package/gates/tests-red.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  listOption,
+  ownArgv,
+  parseOptions,
+  pathMatchesGlob,
+  take,
+  textOption,
+} from "@bluewombat/slot-kit";
+import { createOutputTail } from "../lib/output-tail.mjs";
+
+// The tests that were just written must FAIL, and for the right reason.
+//
+// A test that passes before the behaviour exists tests nothing, and one that fails on a
+// missing import or a syntax error says nothing about the behaviour either. This Gate
+// finds the test files the pass added or changed, runs the Project's own test command on
+// them, and answers:
+//
+//   - no test file added or changed      -> fail-retryable: the pass wrote no test
+//   - the tests pass                     -> fail-retryable: they test nothing that is missing
+//   - they fail on a wrong reason        -> fail-retryable: fix imports, syntax, stubs
+//   - they fail on something else        -> pass: red, as a test written first should be
+//   - the command cannot run, or hangs   -> fail-blocking: no change to the tests fixes it
+//
+// --cmd COMMAND (required): run through the shell. `{files}` is replaced by the test files
+//   of the pass, quoted, so "pnpm vitest run {files}" runs only those. Without `{files}`
+//   the whole command runs as written.
+// --test-glob GLOB (repeatable): which paths are test files. Default: **/*.test.*,
+//   **/*.spec.*, **/__tests__/**
+// --not-red-when REGEX (repeatable, case-insensitive): output that means the tests are red
+//   for the wrong reason. Default: a module that cannot be found or resolved, a syntax
+//   error, a TypeScript error. Naming any replaces the defaults.
+
+const cwd = process.cwd();
+const KEEP_BYTES = 12_000;
+const MARGIN_MS = 5_000;
+const MIN_RUN_MS = 1_000;
+const DEFAULT_GLOBS = ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"];
+const DEFAULT_WRONG_REASONS = [
+  "Cannot find module",
+  "Failed to resolve (import|entry)",
+  "ERR_MODULE_NOT_FOUND",
+  "SyntaxError",
+  "error TS\\d+",
+  "Cannot find name",
+];
+
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  { "--cmd": {}, "--test-glob": { many: true }, "--not-red-when": { many: true } },
+  "tests-red",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", `${parsed.reason} Use --cmd "<command>".`);
+  process.exit(0);
+}
+const template = textOption(parsed.values, "cmd");
+if (template === undefined || template.trim().length === 0) {
+  emitVerdict("fail-blocking", 'tests-red needs --cmd "<command>": the Project\'s test command.');
+  process.exit(0);
+}
+const globs = listOption(parsed.values, "testGlob");
+const testGlobs = globs.length > 0 ? globs : DEFAULT_GLOBS;
+const reasons = listOption(parsed.values, "notRedWhen");
+let wrongReasons;
+try {
+  wrongReasons = (reasons.length > 0 ? reasons : DEFAULT_WRONG_REASONS).map(
+    (source) => new RegExp(source, "i"),
+  );
+} catch (error) {
+  emitVerdict(
+    "fail-blocking",
+    `tests-red: --not-red-when is not a pattern: ${error instanceof Error ? error.message : error}`,
+  );
+  process.exit(0);
+}
+
+if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "tests-red needs a git workspace.");
+  process.exit(0);
+}
+
+const files = testFilesOfThePass();
+if (files.length === 0) {
+  emitVerdict(
+    "fail-retryable",
+    `No test file was added or changed (test files match: ${testGlobs.join(", ")}). This pass writes the tests of the task, in the files its "Tests" section names.`,
+  );
+  process.exit(0);
+}
+
+const command = template.replaceAll("{files}", files.map(quote).join(" "));
+const ceilingMs = Number(take(process.argv, "--timeout-ms"));
+const limitMs =
+  Number.isFinite(ceilingMs) && ceilingMs > 0
+    ? Math.max(MIN_RUN_MS, ceilingMs - MARGIN_MS)
+    : undefined;
+
+const child = spawn("sh", ["-c", command], {
+  cwd,
+  detached: true,
+  stdio: ["ignore", "pipe", "pipe"],
+  env: { ...process.env, CI: "true", NO_COLOR: "1", FORCE_COLOR: "0" },
+});
+const tail = createOutputTail(KEEP_BYTES * 2);
+child.stdout.on("data", (chunk) => tail.push("stdout", chunk));
+child.stderr.on("data", (chunk) => tail.push("stderr", chunk));
+
+let timedOut = false;
+const timer =
+  limitMs === undefined
+    ? undefined
+    : setTimeout(() => {
+        timedOut = true;
+        killGroup();
+      }, limitMs);
+
+child.on("error", (error) => {
+  clearTimeout(timer);
+  emitVerdict("fail-blocking", `tests-red cannot start "${command}": ${error.message}`);
+  process.exit(0);
+});
+
+child.on("close", (code) => {
+  clearTimeout(timer);
+  const output = tail.text();
+  const shown = endOf(output);
+  if (timedOut) {
+    emitVerdict(
+      "fail-blocking",
+      `"${command}" did not finish in ${Math.round((limitMs ?? 0) / 1000)}s and was stopped. A person decides: the tests hang, or this Gate's timeoutMs is too short.`,
+    );
+    return;
+  }
+  if (code === 126 || code === 127) {
+    emitVerdict(
+      "fail-blocking",
+      `"${command}" could not be run here (exit ${code}): ${shown || "no output"}`,
+    );
+    return;
+  }
+  if (code === 0) {
+    emitVerdict(
+      "fail-retryable",
+      [
+        `These tests pass before the behaviour exists (${files.join(", ")}), so they test nothing that is missing.`,
+        "Make each case assert the behaviour the task asks for and the code does not have yet.",
+      ].join("\n"),
+    );
+    return;
+  }
+  const wrong = wrongReasons.find((pattern) => pattern.test(output));
+  if (wrong !== undefined) {
+    const line =
+      output
+        .split("\n")
+        .find((one) => wrong.test(one))
+        ?.trim() ?? wrong.source;
+    emitVerdict(
+      "fail-retryable",
+      [
+        `The tests fail, but not on the missing behaviour: ${line}`,
+        "Make them compile and run: fix the import or the syntax, and give the interface under test a minimal stub (right name and signature, no behaviour), so they fail on what they check. End of the output:",
+        shown,
+      ].join("\n"),
+    );
+    return;
+  }
+  emitVerdict("pass");
+});
+
+function killGroup() {
+  try {
+    if (child.pid !== undefined) {
+      process.kill(-child.pid, "SIGKILL");
+    }
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+/** The test files this pass added or changed, and that are still there. */
+function testFilesOfThePass() {
+  const status = git(["status", "--porcelain", "-z", "-uall"]);
+  if (status.status !== 0) {
+    return [];
+  }
+  const found = [];
+  const entries = status.stdout.split("\0").filter(Boolean);
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i] ?? "";
+    const path = entry.slice(3);
+    if (entry[0] === "R" || entry[1] === "R") {
+      i += 1;
+    }
+    const deleted = entry[0] === "D" || entry[1] === "D";
+    if (
+      !deleted &&
+      existsSync(join(cwd, path)) &&
+      testGlobs.some((glob) => pathMatchesGlob(path, glob))
+    ) {
+      found.push(path);
+    }
+  }
+  return found;
+}
+
+/** @param {string} path */
+function quote(path) {
+  return `'${path.replaceAll("'", "'\\''")}'`;
+}
+
+/** The end of the output, where the error is, cut on a line boundary. */
+function endOf(/** @type {string} */ text) {
+  const cut = text.length > KEEP_BYTES ? text.slice(text.length - KEEP_BYTES) : text;
+  return (text.length > KEEP_BYTES ? cut.slice(cut.indexOf("\n") + 1) : cut).trim();
+}
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}

package/gates/workspace-changed.mjs

@@ -25,7 +25,8 @@ if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
   process.exit(0);
 }
 
-if (stageOf(process.argv) === "assembly") {
+const stage = stageOf(process.argv);
+if (stage === "ticket" || stage === "feature") {
   emitVerdict("pass");
   process.exit(0);
 }

package/gates/workspace-unchanged.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  listOption,
+  ownArgv,
+  parseOptions,
+  pathMatchesGlob,
+} from "@bluewombat/slot-kit";
+
+// Fail-blocking when the workspace holds any change at all: a modified file, a
+// deleted one, a new one that .gitignore does not exclude.
+//
+// For a pass that must not write — `assembly.validate`, a read-only review. Its
+// other Gates look at parts (`sensitive-path` at some globs, `parent-clean` at the
+// Parent), so a reviewer that edits a file nobody named goes unseen. This one
+// watches all of them.
+//
+// Run it where the workspace is committed and clean: after the align, every
+// change of the ticket is in a commit, so whatever `git status` shows was
+// written since. A check run before it can leave files of its own (a coverage
+// report, a build directory) when the Project does not ignore them; name those
+// with --allow GLOB (repeatable) instead of loosening the Gate.
+//
+// Blocking, not retryable: the review is not something another round repairs,
+// and what it wrote would be committed by the next align. A person looks.
+
+const cwd = process.cwd();
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  { "--allow": { many: true } },
+  "workspace-unchanged",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", `${parsed.reason} Use --allow GLOB for a path that may change.`);
+  process.exit(0);
+}
+const allowed = listOption(parsed.values, "allow");
+
+if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "workspace-unchanged needs a git workspace.");
+  process.exit(0);
+}
+
+const status = git(["status", "--porcelain", "-z", "-uall"]);
+if (status.status !== 0) {
+  emitVerdict(
+    "fail-blocking",
+    `workspace-unchanged cannot read git status: ${status.stderr.trim()}`,
+  );
+  process.exit(0);
+}
+
+// `XY path`, NUL-separated; a rename carries its origin as one more entry.
+const changed = [];
+const entries = status.stdout.split("\0").filter(Boolean);
+for (let i = 0; i < entries.length; i++) {
+  const entry = entries[i] ?? "";
+  const path = entry.slice(3);
+  if (entry[0] === "R" || entry[1] === "R") {
+    i += 1;
+  }
+  if (!allowed.some((glob) => pathMatchesGlob(path, glob))) {
+    changed.push(path);
+  }
+}
+
+if (changed.length === 0) {
+  emitVerdict("pass");
+  process.exit(0);
+}
+
+const shown = changed.slice(0, 50);
+const rest = changed.length - shown.length;
+emitVerdict(
+  "fail-blocking",
+  [
+    "This pass is read-only and it changed the workspace. What it wrote would be",
+    "committed by the next align, so nothing is repaired automatically:",
+    ...shown,
+    ...(rest > 0 ? [`… and ${rest} more`] : []),
+    "Look at the changes (git status, git diff), undo them, and run the ticket again.",
+  ].join("\n"),
+);
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}

package/lib/fill.mjs

@@ -4,12 +4,6 @@
  */
 import { take } from "@bluewombat/slot-kit";
 
-/** @param {string | undefined} raw */
-export function doneWhen(raw) {
-  const done = (raw ?? "").trim();
-  return done.length > 0 ? `Done when:\n${done}` : "";
-}
-
 /** @param {readonly string[]} argv */
 export function attemptOf(argv) {
   const parsed = Number.parseInt(take(argv, "--attempt") ?? "", 10);

package/lib/junit.mjs

@@ -0,0 +1,122 @@
+// A JUnit XML report, reduced to what a Gate needs: one entry per test case, what happened to
+// it, and the words of its failure. Playwright, Vitest, Jest, pytest and the JVM runners all
+// write this shape; none of them is asked for more than `testcase` with an optional `failure`,
+// `error` or `skipped` child.
+//
+// Not a general XML parser: it reads the elements above, decodes the five predefined entities and
+// CDATA, and leaves the rest alone.
+
+/**
+ * @typedef {object} TestCase
+ * @property {string} name
+ * @property {string} suite The `classname`, or the enclosing suite's name.
+ * @property {"passed" | "failed" | "skipped"} status
+ * @property {string} message The first line of what went wrong, when it did.
+ * @property {string} detail The failure's own text: the step and the stack.
+ * @property {string[]} attachments Paths the runner says it saved for this case (traces, shots).
+ */
+
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+/** @param {string} text */
+function decode(text) {
+  return text
+    .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, inner) => inner)
+    .replace(/&(#x[0-9a-fA-F]+|#[0-9]+|amp|lt|gt|quot|apos);/g, (whole, code) => {
+      if (code.startsWith("#x")) {
+        return String.fromCodePoint(Number.parseInt(code.slice(2), 16));
+      }
+      if (code.startsWith("#")) {
+        return String.fromCodePoint(Number.parseInt(code.slice(1), 10));
+      }
+      return ENTITIES[/** @type {keyof typeof ENTITIES} */ (code)] ?? whole;
+    });
+}
+
+/** @param {string} tag the opening tag text, `<testcase a="b" …>` */
+function attributesOf(tag) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const match of tag.matchAll(/([\w:.-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)) {
+    out[match[1] ?? ""] = decode(match[3] ?? match[4] ?? "");
+  }
+  return out;
+}
+
+/**
+ * @param {string} xml
+ * @returns {TestCase[]}
+ */
+export function parseJunit(xml) {
+  /** @type {TestCase[]} */
+  const cases = [];
+  // The enclosing suite names, to give a case a home when it has no classname.
+  const events = xml.matchAll(
+    /<testsuite\b[^>]*>|<\/testsuite>|<testcase\b[^>]*\/>|<testcase\b[^>]*>[\s\S]*?<\/testcase>/g,
+  );
+  /** @type {string[]} */
+  const suites = [];
+  for (const event of events) {
+    const text = event[0];
+    if (text.startsWith("</testsuite")) {
+      suites.pop();
+      continue;
+    }
+    if (text.startsWith("<testsuite")) {
+      if (!text.endsWith("/>")) {
+        suites.push(attributesOf(text).name ?? "");
+      }
+      continue;
+    }
+    const open = text.match(/^<testcase\b[^>]*>/)?.[0] ?? text;
+    const attributes = attributesOf(open);
+    const body = text.endsWith("/>") && open === text ? "" : text.slice(open.length);
+    cases.push(caseOf(attributes, body, suites.at(-1) ?? ""));
+  }
+  return cases;
+}
+
+/**
+ * @param {Record<string, string>} attributes
+ * @param {string} body
+ * @param {string} suite
+ * @returns {TestCase}
+ */
+function caseOf(attributes, body, suite) {
+  const failure = body.match(/<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/);
+  const skipped = /<skipped\b/.test(body);
+  const detail = failure === null ? "" : decode(failure[3] ?? "").trim();
+  const said = failure === null ? "" : (attributesOf(`<x ${failure[2] ?? ""}>`).message ?? "");
+  const message = (said.length > 0 ? said : (detail.split("\n")[0] ?? "")).trim();
+  /** @type {string[]} */
+  const attachments = [];
+  for (const match of body.matchAll(/\[\[ATTACHMENT\|([^\]]+)\]\]/g)) {
+    attachments.push((match[1] ?? "").trim());
+  }
+  return {
+    name: attributes.name ?? "",
+    suite: attributes.classname ?? suite,
+    status: failure !== null ? "failed" : skipped ? "skipped" : "passed",
+    message,
+    detail,
+    attachments,
+  };
+}
+
+/**
+ * Which of the manifest's scenario ids a test case name carries. An id is found as a whole
+ * token, so `E1` is not in `E10 …`.
+ *
+ * @param {string} name
+ * @param {readonly string[]} ids
+ * @returns {string | undefined}
+ */
+export function scenarioOf(name, ids) {
+  for (const id of ids) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(`(^|[^A-Za-z0-9_])${escaped}($|[^A-Za-z0-9_])`).test(name)) {
+      return id;
+    }
+  }
+  return undefined;
+}