@bluewombat/slots 0.9.0 → 0.11.0

package/gates/feature-tests.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  ownArgv,
+  parseOptions,
+  take,
+  textOption,
+} from "@bluewombat/slot-kit";
+import { parseJunit, scenarioOf } from "../lib/junit.mjs";
+import { createOutputTail } from "../lib/output-tail.mjs";
+
+// The tests of a Feature, run on the assembled Feature line: does the Feature do what the
+// operator agreed it should? Only the scenarios of this Feature run, not the Project's whole suite.
+//
+// Nothing here knows a stack. The Project supplies one command, run in the workspace through the
+// shell, and the Gate owns the rest: running, comparing.
+//
+// --run COMMAND (required): runs the tests of the Feature and writes a JUnit XML report. `{ids}`
+//   stands for the scenario ids of the manifest joined with "|" (a regular expression:
+//   `pnpm test --grep "{ids}"`), `{junit}` for the path the report must be written to.
+// --manifest PATH: the scenarios of the Feature. Default feature-tests/scenarios.json: a JSON
+//   array of ids, or { "scenarios": [ "S1" | { "id": "S1", "title": "…" } ] }.
+// --junit PATH: where --run writes its report. Default feature-tests/results/junit.xml. Removed
+//   before the run.
+// --max-run-ms N: the most the whole Gate may take. Default 600000 (10 minutes), and never more
+//   than the Gate's own ceiling.
+//
+// A scenario is a manifest id; each test carries its id in its name. The comparison is exact: an
+// id with no test, a test with no id, or a test the runner skipped is a failure.
+//
+// Verdicts: pass; fail-retryable for a red run (a wrong test is its author's to fix, a wrong
+// application the producer's: what the caller does with the report is its own rule); fail-blocking for what no change to the application fixes: a missing manifest,
+// a run that writes no report or outlives its ceiling.
+
+const cwd = process.cwd();
+const KEEP_BYTES = 12_000;
+const MARGIN_MS = 5_000;
+const MIN_PHASE_MS = 1_000;
+const REPORT_CHARS = 8_000;
+
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  {
+    "--run": {},
+    "--manifest": { fallback: "feature-tests/scenarios.json" },
+    "--junit": { fallback: "feature-tests/results/junit.xml" },
+    "--max-run-ms": { fallback: "600000" },
+  },
+  "feature-tests",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", parsed.reason);
+  process.exit(0);
+}
+const runTemplate = textOption(parsed.values, "run");
+if (runTemplate === undefined || runTemplate.trim().length === 0) {
+  emitVerdict(
+    "fail-blocking",
+    'feature-tests needs --run "<command>". The Project supplies the command that runs the tests.',
+  );
+  process.exit(0);
+}
+const maxRunMs = positive(textOption(parsed.values, "maxRunMs"));
+if (maxRunMs === undefined) {
+  emitVerdict("fail-blocking", "feature-tests: --max-run-ms takes a positive integer.");
+  process.exit(0);
+}
+const manifestPath = inWorkspace(textOption(parsed.values, "manifest") ?? "");
+const junitPath = inWorkspace(textOption(parsed.values, "junit") ?? "");
+
+const manifest = readManifest();
+if (typeof manifest === "string") {
+  emitVerdict("fail-blocking", manifest);
+  process.exit(0);
+}
+// Typed apart from the early exit above: the functions below are hoisted, and a narrowing does not reach them.
+/** @type {string[]} */
+const ids = manifest;
+
+const ceilingMs = Number(take(process.argv, "--timeout-ms"));
+const budgetMs =
+  Number.isFinite(ceilingMs) && ceilingMs > 0
+    ? Math.min(maxRunMs, Math.max(MIN_PHASE_MS, ceilingMs - MARGIN_MS))
+    : maxRunMs;
+
+const [verdict, report] = await judge();
+emitVerdict(/** @type {"pass" | "fail-retryable" | "fail-blocking"} */ (verdict), report);
+process.exit(0);
+
+/** @returns {Promise<[string, string]>} */
+async function judge() {
+  rmSync(junitPath, { force: true });
+  const command = runTemplate?.replaceAll("{ids}", ids.join("|")).replaceAll("{junit}", junitPath);
+  const run = await runShell(/** @type {string} */ (command), budgetMs);
+  if (run.timedOut) {
+    return ["fail-blocking", timeoutReport(run.output)];
+  }
+  const results = readResults();
+  if (typeof results === "string") {
+    return run.code === 0
+      ? ["fail-blocking", results]
+      : ["fail-retryable", `${results}\n${exitLine(run)} End of its output:\n${run.output}`];
+  }
+  const failing = failingOf(results);
+  if (failing.length > 0) {
+    return ["fail-retryable", redReport(results, failing)];
+  }
+  const foreign = results.cases.filter((c) => scenarioOf(c.name, ids) === undefined);
+  if (foreign.length > 0) {
+    return [
+      "fail-retryable",
+      [
+        `feature-tests: ${foreign.length} test(s) carry no scenario id of the manifest (${ids.join(", ")}): only the scenarios of the Feature run.`,
+        ...foreign.map((c) => `  ${c.name}`),
+        "Every test names its scenario id, and --run must run the ids of the manifest only ({ids}).",
+      ].join("\n"),
+    ];
+  }
+  return [
+    "pass",
+    `feature-tests: ${ids.length} scenario(s) of the feature ran and passed: ${ids.join(", ")}.`,
+  ];
+}
+
+/**
+ * @typedef {{ cases: import("../lib/junit.mjs").TestCase[] }} Result
+ */
+
+/** @returns {Result | string} */
+function readResults() {
+  if (!existsSync(junitPath)) {
+    return `The run wrote no JUnit report at ${junitPath}. --run must write one there ({junit}).`;
+  }
+  const cases = parseJunit(readFileSync(junitPath, "utf8"));
+  if (cases.length === 0) {
+    return `The JUnit report at ${junitPath} holds no test case.`;
+  }
+  return { cases };
+}
+
+/** The scenario ids that are not a pass: failed, skipped, or never run. */
+function failingOf(/** @type {Result} */ results) {
+  return ids.filter((id) => {
+    const mine = results.cases.filter((c) => scenarioOf(c.name, ids) === id);
+    return mine.length === 0 || mine.some((c) => c.status !== "passed");
+  });
+}
+
+function redReport(/** @type {Result} */ results, /** @type {string[]} */ failing) {
+  const lines = [
+    `feature-tests: ${failing.length} of ${ids.length} scenario(s) failed on the assembled feature: ${failing.join(", ")}.`,
+  ];
+  for (const id of failing) {
+    const mine = results.cases.filter((c) => scenarioOf(c.name, ids) === id);
+    if (mine.length === 0) {
+      lines.push(`${id} — no test ran for it.`);
+      continue;
+    }
+    for (const c of mine.filter((m) => m.status !== "passed")) {
+      lines.push(`${id} — ${c.name}`);
+      if (c.status === "skipped") {
+        lines.push("  skipped: a skipped scenario is not a passing one.");
+        continue;
+      }
+      lines.push(`  at: ${firstFrame(c.detail) ?? "(no step given)"}`);
+      lines.push(`  message: ${c.message.slice(0, 600)}`);
+    }
+  }
+  lines.push(`Report: ${junitPath}.`);
+  const text = lines.join("\n");
+  return text.length <= REPORT_CHARS ? text : `${text.slice(0, REPORT_CHARS)}\n…`;
+}
+
+/** The first stack line that is the test's own, where a step failed. */
+function firstFrame(/** @type {string} */ detail) {
+  return detail
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => /^at\s|\.(spec|test)\.[cm]?[jt]sx?:\d+/.test(line));
+}
+
+/**
+ * @param {string} command
+ * @param {number} limitMs
+ * @returns {Promise<{ code: number | null, signal: string | null, timedOut: boolean, output: string }>}
+ */
+function runShell(command, limitMs) {
+  return new Promise((done) => {
+    const child = spawn("sh", ["-c", command], {
+      cwd,
+      env: { ...process.env, CI: "true", NO_COLOR: "1", FORCE_COLOR: "0" },
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    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 = globalThis.setTimeout(
+      () => {
+        timedOut = true;
+        killGroup(child);
+      },
+      Math.max(MIN_PHASE_MS, limitMs),
+    );
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      done({ code: 127, signal: null, timedOut: false, output: `cannot start: ${error.message}` });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      done({ code, signal, timedOut, output: tail.text() });
+    });
+  });
+}
+
+/** @param {import("node:child_process").ChildProcess} child */
+function killGroup(child) {
+  try {
+    if (child.pid !== undefined) {
+      process.kill(-child.pid, "SIGKILL");
+    }
+  } catch {
+    child.kill("SIGKILL");
+  }
+}
+
+function timeoutReport(/** @type {string} */ output) {
+  return [
+    `The run did not finish within the ${Math.round(budgetMs / 1000)}s this Gate may take, and was stopped.`,
+    "A person decides: the tests hang.",
+    output.length > 0 ? `Last output:\n${output}` : "It printed nothing.",
+  ].join("\n");
+}
+
+function exitLine(/** @type {{ code: number | null, signal: string | null }} */ run) {
+  return run.signal === null ? `The run exited ${run.code}.` : `The run got ${run.signal}.`;
+}
+
+/** @returns {string[] | string} The ids, or why the manifest is not usable. */
+function readManifest() {
+  if (!existsSync(manifestPath)) {
+    return `The scenarios manifest ${manifestPath} does not exist. The feature-test Ticket writes it: one id per scenario.`;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    return `The scenarios manifest ${manifestPath} is not JSON: ${error instanceof Error ? error.message : error}`;
+  }
+  const list = Array.isArray(raw) ? raw : raw?.scenarios;
+  if (!Array.isArray(list)) {
+    return `The scenarios manifest ${manifestPath} must be an array of ids, or { "scenarios": [...] }.`;
+  }
+  const found = list.map((entry) => (typeof entry === "string" ? entry : entry?.id));
+  if (found.some((id) => typeof id !== "string" || id.trim().length === 0)) {
+    return `Every scenario of ${manifestPath} needs a non-empty id.`;
+  }
+  const unique = [...new Set(found.map((id) => id.trim()))];
+  if (unique.length !== found.length) {
+    return `The scenarios manifest ${manifestPath} lists an id twice.`;
+  }
+  if (unique.length === 0) {
+    return `The scenarios manifest ${manifestPath} lists no scenario: there is nothing to prove.`;
+  }
+  return unique;
+}
+
+function positive(/** @type {string | undefined} */ text) {
+  const value = Number(text);
+  return Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function inWorkspace(/** @type {string} */ path) {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}

package/gates/gitignore-leak.mjs

@@ -47,7 +47,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/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-only.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { emitVerdict, GATE_FLAGS, ownArgv, pathMatchesGlob } from "@bluewombat/slot-kit";
+
+// Fail-retryable when the workspace changed a path that matches none of the globs: the one place
+// the workspace may be written is what the globs name (the tests and their manifest). The other
+// side of `sensitive-path`, which names what may not be touched; a Project whose tests sit among its
+// code (`**/*.test.ts` in every package) cannot say "everything but" with globs that only deny.
+// Remaining argv after Implementer's flags are the globs.
+//
+// What counts is what a fold can carry: tracked paths that differ from HEAD (added, modified,
+// deleted, renamed) and new paths .gitignore does not exclude.
+
+const cwd = process.cwd();
+const globs = ownArgv(process.argv, GATE_FLAGS).filter((token) => token.length > 0);
+
+if (globs.length === 0) {
+  emitVerdict("fail-blocking", "tests-only needs at least one glob.");
+  process.exit(0);
+}
+
+const status = spawnSync(
+  "git",
+  ["-C", cwd, "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+  {
+    encoding: "utf8",
+  },
+);
+if (status.status !== 0) {
+  emitVerdict("fail-blocking", `tests-only needs a git workspace: ${status.stderr.trim()}`);
+  process.exit(0);
+}
+
+/** @type {Set<string>} */
+const changed = new Set();
+const fields = status.stdout.split("\0");
+for (let i = 0; i < fields.length; i++) {
+  const entry = fields[i] ?? "";
+  if (entry.length < 4) {
+    continue;
+  }
+  changed.add(entry.slice(3));
+  // A rename or a copy carries the old path in the next field.
+  if (entry[0] === "R" || entry[0] === "C") {
+    const old = fields[++i];
+    if (old !== undefined && old.length > 0) {
+      changed.add(old);
+    }
+  }
+}
+
+const outside = [...changed]
+  .map((path) => path.replaceAll("\\", "/"))
+  .filter((path) => !globs.some((glob) => pathMatchesGlob(path, glob)))
+  .sort();
+
+if (outside.length > 0) {
+  emitVerdict(
+    "fail-retryable",
+    `Paths changed that are not tests or their manifest (${globs.join(", ")}):\n${outside.join("\n")}`,
+  );
+  process.exit(0);
+}
+
+emitVerdict("pass");

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" });
+}