@bluewombat/slots 0.10.0 → 0.11.1

package/builders/{e2e.mjs → feature-test.mjs}

@@ -15,29 +15,38 @@ import {
 } from "@bluewombat/slot-kit";
 import { attemptOf } from "../lib/fill.mjs";
 
-// The Ticket that holds a Feature's e2e acceptance suite. One command for its first pass and for
-// a pass a Gate refused: the suite is written once from the scenarios of the task, and a refusal
-// is about its form, so there is no second command to tell apart. `{{report}}` and
-// `{{refused_by}}` are empty on a first pass; `{{refusal}}` is a ready-made paragraph about them.
+// The Ticket that holds a Feature's tests. One command for its first pass and for a pass a Gate
+// refused: the tests are written once from the scenarios of the task, and a refusal is about their
+// form, so there is no second command to tell apart. `{{report}}` and `{{refused_by}}` are empty
+// on a first pass; `{{refusal}}` is a ready-made paragraph about them.
 
-const NAME = "builder e2e";
+const NAME = "builder feature-test";
 
 const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
 
-You write the acceptance suite of a feature. The task below lists its scenarios, agreed with the
-operator before development, each with an id (E1, E2, ...).
+You write the tests of a feature. The task below lists its scenarios, agreed with the operator
+before development, each with an id (S1, S2, ...). The feature is built: this checkout holds every
+other Ticket of it.
 
 Task:
 {{task}}
 
-- Write one test per scenario, in the end-to-end framework this project already uses, and
-  start the name of each test with its scenario id ("E1 …"). Follow the scenario's steps and
-  expected result as written; do not add, merge or drop one.
-- List the ids in the manifest \`e2e/scenarios.json\`, a JSON array: ["E1", "E2"].
-- Write only inside the suite folder (\`e2e/\`). Touch no file of the application, and add no
+- Write one test per scenario, in the test framework this project already uses, at the level the
+  scenario describes (through the feature's public interfaces: routes, services, pages), and start
+  the name of each test with its scenario id ("S1 …"). Follow the scenario's steps and expected
+  result as written; do not add, merge, drop or weaken one. If a scenario changes a behaviour that
+  existing tests describe, update those tests to the new behaviour, and only those.
+- List the ids of the scenarios in the manifest \`feature-tests/scenarios.json\`, a JSON array:
+  ["S1", "S2"]. Only the scenarios of this feature, never the project's other tests.
+- Write only tests, their helpers and the manifest. Touch no file of the application, and add no
   dependency it does not already have.
-- The feature is not finished here and the application is not started: do not run the suite. Check
-  only that it compiles, with the project's own typecheck or build command.
+- A Gate runs your tests against the built feature after every attempt and gives you its report
+  (the refusal below). Read it: a test that fails for its own reasons (a wrong selector or wait, a
+  wrong data setup, a misread expectation) is yours to fix. Check only that your tests compile
+  before you finish, with the project's own typecheck or build command.
+- If a test stays red because the feature does not do what the scenario says, do not change the
+  application and do not weaken the test: that is a finding. Change nothing more and end with
+  MASON_BLOCKED, naming the scenario, what the feature does instead and where.
 
 {{refusal}}
 
@@ -45,9 +54,10 @@ Task:
 
 ## When you cannot act
 
-If what you were given is not enough to act on (a scenario is ambiguous, the framework is missing,
-the cause is outside this directory), do not invent a change. Change nothing and end your final
-message with exactly one line:
+If what you were given is not enough to act on (a scenario is ambiguous, cannot be written without
+changing the application or without a weaker result than asked, the framework is missing, the
+feature is wrong, the cause is outside this directory), do not invent a change and do not lower
+the scenario. Change nothing and end your final message with exactly one line:
 
 MASON_BLOCKED: <what is missing, in one line>
 

package/gates/base-diff.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  emitVerdict,
+  GATE_FLAGS,
+  listOption,
+  ownArgv,
+  parseOptions,
+  pathMatchesGlob,
+  stageOf,
+  take,
+  textOption,
+} from "@bluewombat/slot-kit";
+
+// What the work changed since the line it is offered to, judged by path.
+//
+// The base is the work line the workspace was cut from. Without --base it is the
+// branch checked out in the main worktree of the repository the workspace belongs
+// to: Isolation makes every workspace a worktree of the work line's copy, and Host
+// keeps that copy on the line the work lands on (a Feature's own line while a
+// Feature is open), so the answer follows the line. A branch named by hand
+// (`--base main`) is the copy's local branch and is only as fresh as the last
+// time something moved it; Host moves the Feature's line, not `main`.
+//
+// The changed set is what differs between the base and the workspace: the commits
+// since the workspace left it (`BASE...HEAD`) and whatever is on disk and not yet
+// committed (a fold can carry it out, so it counts; an ignored path does not).
+// Unlike a Gate that compares the disk to the last commit, it still sees the work
+// once it is committed, so it answers at the unit, the ticket and the recheck
+// after the align (`--stage assembly`).
+//
+// At `--stage feature` there is no base to derive: the Feature's workspace is its
+// line with the target merged in, so the line would show the target's work. Name
+// the target with --base there.
+//
+//   --base REF       optional. The ref to compare with, instead of the main
+//                    worktree's branch.
+//
+// Two ways to use the changed set, alone or together:
+//
+//   --deny GLOB      repeatable. fail-retryable when a changed path matches:
+//                    "this must not be touched".
+//   --when GLOB      repeatable, with --run. When a changed path matches, run
+//                    CMD with project-checks (shell, output cleaned, the Gate's
+//                    ceiling honoured) and answer as it does: "if this changed,
+//                    this must hold". When nothing matches, pass without running it.
+//   --run CMD        MASON_BASE holds the base; MASON_CHANGED_FILES holds the
+//                    changed paths, one per line, so CMD can narrow itself to them.
+//
+// `*` is one path segment, `**` any depth.
+
+const cwd = process.cwd();
+const projectChecks = join(dirname(fileURLToPath(import.meta.url)), "project-checks.mjs");
+
+const parsed = parseOptions(
+  ownArgv(process.argv, GATE_FLAGS),
+  { "--base": {}, "--deny": { many: true }, "--when": { many: true }, "--run": {} },
+  "base-diff",
+);
+if (!parsed.ok) {
+  emitVerdict("fail-blocking", parsed.reason);
+  process.exit(0);
+}
+const explicitBase = textOption(parsed.values, "base");
+const deny = listOption(parsed.values, "deny");
+const when = listOption(parsed.values, "when");
+const command = textOption(parsed.values, "run");
+
+if (explicitBase?.startsWith("-")) {
+  emitVerdict("fail-blocking", `base-diff cannot take "${explicitBase}" as a base.`);
+  process.exit(0);
+}
+if (deny.length === 0 && when.length === 0 && command === undefined) {
+  emitVerdict(
+    "fail-blocking",
+    "base-diff needs at least one --deny GLOB, or --when GLOB with --run CMD.",
+  );
+  process.exit(0);
+}
+if (when.length > 0 !== (command !== undefined)) {
+  emitVerdict(
+    "fail-blocking",
+    "base-diff takes --when and --run together: a condition, and what to run on it.",
+  );
+  process.exit(0);
+}
+
+if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
+  emitVerdict("fail-blocking", "base-diff needs a git workspace.");
+  process.exit(0);
+}
+
+const base = explicitBase ?? deriveBase();
+if (base === undefined) {
+  process.exit(0);
+}
+if (git(["rev-parse", "--verify", "--quiet", `${base}^{commit}`]).status !== 0) {
+  emitVerdict("fail-blocking", `base-diff cannot find the base "${base}" in this workspace.`);
+  process.exit(0);
+}
+
+const changed = changedPaths();
+if (changed === undefined) {
+  process.exit(0);
+}
+
+if (deny.length > 0) {
+  const hit = changed.filter((path) => matchesAny(path, deny));
+  if (hit.length > 0) {
+    emitVerdict(
+      "fail-retryable",
+      `Paths changed since ${base} that this work may not touch (${deny.join(", ")}):\n${hit.join("\n")}`,
+    );
+    process.exit(0);
+  }
+}
+
+if (command !== undefined && changed.some((path) => matchesAny(path, when))) {
+  runCondition(command);
+} else {
+  emitVerdict("pass");
+}
+
+/**
+ * The branch checked out in the main worktree: the line this workspace's work
+ * lands on. Nothing when there is none to name; the verdict is then already out.
+ * @returns {string | undefined}
+ */
+function deriveBase() {
+  if (stageOf(process.argv) === "feature") {
+    emitVerdict(
+      "fail-blocking",
+      "base-diff cannot derive a base at the feature stage: the Feature's workspace is its line with the target merged in, so the line would show the target's work, not the Feature's. Name the target with --base.",
+    );
+    return undefined;
+  }
+  const listed = git(["worktree", "list", "--porcelain"]);
+  if (listed.status !== 0) {
+    emitVerdict("fail-blocking", `base-diff cannot list the worktrees: ${listed.stderr.trim()}`);
+    return undefined;
+  }
+  // The first entry is the main worktree.
+  const main = listed.stdout.split("\n\n")[0] ?? "";
+  const mainPath = /^worktree (.+)$/m.exec(main)?.[1];
+  const branch = /^branch refs\/heads\/(.+)$/m.exec(main)?.[1];
+  const top = git(["rev-parse", "--show-toplevel"]).stdout.trim();
+  if (mainPath === undefined || top.length === 0) {
+    emitVerdict(
+      "fail-blocking",
+      "base-diff cannot tell which worktree is the main one. Name the base with --base.",
+    );
+    return undefined;
+  }
+  if (sameDirectory(mainPath, top)) {
+    emitVerdict(
+      "fail-blocking",
+      "base-diff has no base to derive: this workspace is the main worktree itself, not a worktree of a work line. Name the base with --base.",
+    );
+    return undefined;
+  }
+  if (branch === undefined) {
+    emitVerdict(
+      "fail-blocking",
+      `base-diff has no base to derive: the main worktree (${mainPath}) has no branch checked out. Name the base with --base.`,
+    );
+    return undefined;
+  }
+  return `refs/heads/${branch}`;
+}
+
+/**
+ * Runs the --run command through project-checks, so it is cleaned, bounded and
+ * classified the way every command of the Project is, and relays its verdict.
+ * @param {string} cmd
+ */
+function runCondition(cmd) {
+  const flags = ["--cmd", cmd];
+  const ceiling = take(process.argv, "--timeout-ms");
+  if (ceiling !== undefined) {
+    flags.push("--timeout-ms", ceiling);
+  }
+  const result = spawnSync(process.execPath, [projectChecks, ...flags], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    env: { ...process.env, MASON_BASE: base, MASON_CHANGED_FILES: (changed ?? []).join("\n") },
+  });
+  const line = (result.stdout ?? "").trim().split("\n").filter(Boolean).at(-1);
+  /** @type {{ verdict?: string; report?: string } | undefined} */
+  let answer;
+  try {
+    answer = line === undefined ? undefined : JSON.parse(line);
+  } catch {
+    answer = undefined;
+  }
+  if (answer?.verdict === "pass") {
+    emitVerdict("pass");
+    return;
+  }
+  if (answer?.verdict === "fail-retryable" || answer?.verdict === "fail-blocking") {
+    const lead = `Paths matching ${when.join(", ")} changed since ${base}. `;
+    emitVerdict(answer.verdict, `${lead}${answer.report ?? ""}`.trim());
+    return;
+  }
+  emitVerdict(
+    "fail-blocking",
+    `base-diff could not read the answer of "${cmd}": ${(result.stderr ?? "").trim().slice(-2_000) || "no output"}`,
+  );
+}
+
+/**
+ * Every path that differs from the base, committed or not, sorted. Nothing when
+ * git could not say: the verdict is already out.
+ * @returns {string[] | undefined}
+ */
+function changedPaths() {
+  // --no-renames: a move is a removal and an addition, so the old path counts too.
+  const committed = git(["diff", "--name-only", "--no-renames", "-z", `${base}...HEAD`]);
+  if (committed.status !== 0) {
+    emitVerdict(
+      "fail-blocking",
+      `base-diff cannot diff HEAD against "${base}": ${committed.stderr.trim()}`,
+    );
+    return undefined;
+  }
+  const status = git(["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  if (status.status !== 0) {
+    emitVerdict("fail-blocking", `base-diff cannot read the workspace: ${status.stderr.trim()}`);
+    return undefined;
+  }
+  const paths = new Set(committed.stdout.split("\0").filter(Boolean));
+  const fields = status.stdout.split("\0");
+  for (let i = 0; i < fields.length; i++) {
+    const entry = fields[i] ?? "";
+    if (entry.length < 4) {
+      continue;
+    }
+    paths.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) {
+        paths.add(old);
+      }
+    }
+  }
+  return [...paths].map((path) => path.replaceAll("\\", "/")).sort();
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ */
+function sameDirectory(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+}
+
+/**
+ * @param {string} path
+ * @param {readonly string[]} patterns
+ */
+function matchesAny(path, patterns) {
+  return patterns.some((pattern) => pathMatchesGlob(path, pattern));
+}
+
+/** @param {string[]} args */
+function git(args) {
+  return spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
+}

package/gates/ci-green.mjs

@@ -20,6 +20,14 @@ import { emitVerdict, GATE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
 //                        to it failed only at the first assembly of a real run
 //   --require-checks     wait for a check to appear; without it, a commit with no
 //                        check at all passes
+//   --require-check NAME repeatable. The check run (or status context) called
+//                        exactly NAME must exist and have succeeded. A `skipped` or
+//                        `neutral` one is not a pass, which is what the general
+//                        rule lets through (a job skipped for want of its secrets
+//                        would let the line go green): it is refused. One not
+//                        there yet is waited for like --require-checks, and at the
+//                        ceiling the CI did not answer. A matrix is one check per
+//                        cell, named as GitHub names it ("e2e (chrome)"): list each one.
 //
 // It also receives `--timeout-ms` from Implementer: the ceiling it will be
 // killed at. A Gate that waits on a CI it does not run must not wait to be cut
@@ -38,6 +46,7 @@ if (!options.ok) {
   process.exit(0);
 }
 const apiBase = options.apiBase;
+const requireCheck = options.requireCheck;
 
 if (git(["rev-parse", "--is-inside-work-tree"]).stdout.trim() !== "true") {
   emitVerdict("fail-blocking", "ci-green needs a git workspace.");
@@ -93,6 +102,25 @@ for (;;) {
     await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
     continue;
   }
+  const required = judgeRequired(checks.named);
+  if (required.refused.length > 0) {
+    // A check that settled without running says nothing of the work, and nothing
+    // the work could change (a job skipped for want of its secrets): a person's,
+    // not an agent's to repair.
+    emitVerdict(
+      "fail-blocking",
+      `${required.refused.join("\n")}\nThis is not a refusal of the work: the CI did not run a check the Project requires, and no change to the work makes it run.`,
+    );
+    process.exit(0);
+  }
+  if (required.missing.length > 0) {
+    // Same window as above, for a check the Project named.
+    if (Date.now() >= stopAt) {
+      stopWaiting(pull, `required check ${quoted(required.missing)} has not appeared`, true);
+    }
+    await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
+    continue;
+  }
   if (checks.running === 0) {
     emitVerdict("pass");
     process.exit(0);
@@ -106,6 +134,40 @@ for (;;) {
   await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
 }
 
+/**
+ * What `--require-check` asks of the checks read: each name must have a
+ * success. A name not there yet is `missing` (the CI may still create it); one
+ * still running is waited for with the rest; one that settled without success
+ * (`skipped`, `neutral`) is `refused`: nothing will turn it green, and no change
+ * to the work can, so it goes to a person.
+ *
+ * @param {Map<string, string[]>} named every check by name, with its outcome:
+ *   `success`, `pending`, or the conclusion it settled on
+ * @returns {{ missing: string[]; refused: string[] }}
+ */
+function judgeRequired(named) {
+  /** @type {string[]} */
+  const missing = [];
+  /** @type {string[]} */
+  const refused = [];
+  for (const name of requireCheck) {
+    const outcomes = named.get(name);
+    if (outcomes === undefined) {
+      missing.push(name);
+    } else if (!outcomes.includes("success") && !outcomes.includes("pending")) {
+      refused.push(
+        `${name}: ${outcomes[0]}. It is required to succeed, and a check that did not run is not a pass.`,
+      );
+    }
+  }
+  return { missing, refused };
+}
+
+/** @param {readonly string[]} names */
+function quoted(names) {
+  return names.map((name) => `"${name}"`).join(", ");
+}
+
 /**
  * The moment to stop waiting: a margin before Implementer's ceiling (5 %, between
  * 2 and 30 seconds, and at most half of it), so the verdict is out before the
@@ -153,7 +215,7 @@ function stopWaiting(pr, what, never = false) {
 
 /**
  * @param {readonly string[]} tokens
- * @returns {{ ok: true; remote: string; apiBase: string; pollMs: number; tokenEnv: string; requireChecks: boolean } | { ok: false; reason: string }}
+ * @returns {{ ok: true; remote: string; apiBase: string; pollMs: number; tokenEnv: string; requireChecks: boolean; requireCheck: string[] } | { ok: false; reason: string }}
  */
 function parseOwnArgv(tokens) {
   let remote = "origin";
@@ -161,6 +223,8 @@ function parseOwnArgv(tokens) {
   let pollMs = 15_000;
   let tokenEnv;
   let requireChecks = false;
+  /** @type {string[]} */
+  const requireCheck = [];
   for (let i = 0; i < tokens.length; i++) {
     const token = tokens[i];
     if (token === "--require-checks") {
@@ -176,6 +240,8 @@ function parseOwnArgv(tokens) {
       remote = value;
     } else if (token === "--api-base") {
       apiBase = value.replace(/\/+$/, "");
+    } else if (token === "--require-check") {
+      requireCheck.push(value);
     } else if (token === "--token-env") {
       tokenEnv = value;
     } else if (token === "--poll-ms") {
@@ -195,7 +261,7 @@ function parseOwnArgv(tokens) {
         "ci-green needs --token-env NAME: the environment variable holding a token that can read the checks (the same one @bluewombat/manager-github's tokenEnv names, never GITHUB_TOKEN).",
     };
   }
-  return { ok: true, remote, apiBase, pollMs, tokenEnv, requireChecks };
+  return { ok: true, remote, apiBase, pollMs, tokenEnv, requireChecks, requireCheck };
 }
 
 /**
@@ -269,12 +335,25 @@ async function readChecks(sha) {
   // on the same commit: same name, same log. Said once.
   const seen = new Set();
   let running = 0;
+  /** @type {Map<string, string[]>} */
+  const named = new Map();
+  /**
+   * @param {unknown} name
+   * @param {string} outcome
+   */
+  const note = (name, outcome) => {
+    if (typeof name === "string") {
+      named.set(name, [...(named.get(name) ?? []), outcome]);
+    }
+  };
   for (const entry of checkRuns) {
     const run = record(entry) ?? {};
     if (run.status !== "completed") {
       running += 1;
+      note(run.name, "pending");
       continue;
     }
+    note(run.name, String(run.conclusion));
     if (
       run.conclusion === "success" ||
       run.conclusion === "neutral" ||
@@ -293,6 +372,7 @@ async function readChecks(sha) {
   // and where it said more is all there is.
   for (const entry of statuses) {
     const status = record(entry) ?? {};
+    note(status.context, status.state === "pending" ? "pending" : String(status.state));
     if (status.state === "pending") {
       running += 1;
       continue;
@@ -310,7 +390,7 @@ async function readChecks(sha) {
     );
     failed.push([heading, ...more].join("\n"));
   }
-  return { total: checkRuns.length + statuses.length, running, failed };
+  return { total: checkRuns.length + statuses.length, running, failed, named };
 }
 
 /**