@bluewombat/slots 0.9.0 → 0.11.0

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.");
@@ -88,7 +97,26 @@ for (;;) {
     // yet, and an empty list then says nothing. Ask again, until the wait
     // runs out: a commit no check ever picks up is not a refusal of the work.
     if (Date.now() >= stopAt) {
-      stopWaiting(pull, "no check has appeared");
+      stopWaiting(pull, "no check has appeared", true);
+    }
+    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;
@@ -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
@@ -128,23 +190,32 @@ function stopTime(from, raw) {
  * could change: blocking, so a person reads it instead of an agent being sent
  * to repair what was never judged.
  *
- * @param {{ number: number; sha: string }} pr
+ * When no check ever appeared, the cause is on the repository's side, and the
+ * message says the three it can be: no CI at all, a CI that does not run on pull
+ * requests into this branch, or a CI that is late.
+ *
+ * @param {{ number: number; sha: string; base?: string }} pr
  * @param {string} what
+ * @param {boolean} [never]
  * @returns {never}
  */
-function stopWaiting(pr, what) {
+function stopWaiting(pr, what, never = false) {
   const seconds = Math.round((Date.now() - startedAt) / 1000);
   const lasted = seconds >= 120 ? `${Math.round(seconds / 60)} min` : `${seconds} s`;
+  const into = pr.base === undefined ? "this branch" : `"${pr.base}"`;
+  const hint = never
+    ? ` Either this repository has no CI (then take ci-green out of the Gate list), or its workflows do not run on pull requests into ${into}, or the CI was removed or is late.`
+    : "";
   emitVerdict(
     "fail-blocking",
-    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.`,
+    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.${hint}`,
   );
   process.exit(0);
 }
 
 /**
  * @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";
@@ -152,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") {
@@ -167,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") {
@@ -186,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 };
 }
 
 /**
@@ -221,7 +296,7 @@ function repoFrom(url) {
 
 /**
  * @param {string} head
- * @returns {Promise<{ number: number; sha: string } | undefined>}
+ * @returns {Promise<{ number: number; sha: string; base?: string } | undefined>}
  */
 async function openPullFor(head) {
   const listed = await api(
@@ -232,8 +307,10 @@ async function openPullFor(head) {
   if (first === undefined || headOf === undefined) {
     return undefined;
   }
+  const baseOf = record(first.base);
+  const base = typeof baseOf?.ref === "string" ? baseOf.ref : undefined;
   return typeof first.number === "number" && typeof headOf.sha === "string"
-    ? { number: first.number, sha: headOf.sha }
+    ? { number: first.number, sha: headOf.sha, ...(base === undefined ? {} : { base }) }
     : undefined;
 }
 
@@ -258,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" ||
@@ -282,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;
@@ -299,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 };
 }
 
 /**