@intentius/chant 0.124.41 → 0.124.42

package/src/op/stage-hooks.ts

@@ -0,0 +1,251 @@
+/**
+ * The stage-hook runner (#4288): one moment's hooks, with the `targets`,
+ * `perRun`, `onFailure` and argv filling a wave job uses. Its own module so
+ * a product that runs hooks around its own stages (terragucci) bundles it
+ * without the wave loop, the gate or the ledger. `op-waves-run.ts` runs
+ * the same hooks inside a wave job.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { opWaveHookRuns, type OpWaveHook, type OpWaveHookMoment } from "./op-waves";
+
+/** What one moment's hooks came to, before any hold on another gate is settled. */
+export interface HookListOutcome {
+  /** Set when a hook with `onFailure: fail` failed; the hooks after it did not run. */
+  failed?: string;
+  /** The `onFailure: approve` hooks that failed. */
+  holds: string[];
+  outcomes: OpWaveHookOutcome[];
+  /** The hook calls that held the wave on another gate. */
+  otherGates: OtherGateHold[];
+}
+
+/** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
+export const OP_WAVE_PENDING_RESERVED = [
+  "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
+  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy",
+] as const;
+
+/** What a hook asks for when it holds a wave on another gate (#3821): it writes this to `CHANT_HOLD` and exits non-zero. */
+export interface OpWaveHoldRequest {
+  /** The op the gate is recorded under. Default: the spec's name. */
+  op?: string;
+  gate: string;
+  /** The digest an approval binds. */
+  digest: string;
+  description?: string;
+  /** Fields for the pending fact, as a plans file's `pending`. */
+  pending?: Record<string, unknown>;
+}
+
+/** One hook's run (#3762). */
+export interface OpWaveHookOutcome {
+  moment: OpWaveHookMoment;
+  name: string;
+  /** The run, for a `perRun` hook. */
+  target?: string;
+  exit: number;
+  outcome: "passed" | "failed" | "held" | "skipped";
+  /** Why the moment was skipped, for `skipped` (#3811). */
+  reason?: string;
+}
+
+/** One run as a hook sees it (#3804). */
+export interface OpWaveHookRun {
+  target: string;
+  op: string;
+  /** The run's plan file, once planned. */
+  plan?: string;
+}
+
+/** Runs one argv; returns its exit code. `env` is added to the job's environment. Injected so tests run no processes. */
+export type OpWaveExec = (argv: string[], cwd: string, env?: Record<string, string>) => number;
+
+export const spawnExec: OpWaveExec = (argv, cwd, env) => {
+  const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit", ...(env ? { env: { ...process.env, ...env } } : {}) });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+};
+
+/** Fill one argv template. A placeholder whose value is not given is left as it is. */
+export function opWaveArgv(
+  template: readonly string[],
+  values: { op: string; wave: string; target?: string; plan?: string; runs?: string; plans?: string },
+): string[] {
+  const pairs: Array<[string, string | undefined]> = [
+    ["{op}", values.op],
+    ["{target}", values.target],
+    ["{wave}", values.wave],
+    ["{plans}", values.plans],
+    ["{plan}", values.plan],
+    ["{runs}", values.runs],
+  ];
+  return template.map((part) => pairs.reduce((out, [key, value]) => (value === undefined ? out : out.replaceAll(key, value)), part));
+}
+
+/** A plans file's `pending` (#3821): an object whose keys chant does not write itself, `description` aside. Undefined when absent or empty. */
+export function pendingFields(value: unknown, where: string): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${where}: \`pending\` must be an object of fields for the pending fact`);
+  const reserved = Object.keys(value).filter((key) => (OP_WAVE_PENDING_RESERVED as readonly string[]).includes(key));
+  if (reserved.length > 0) throw new Error(`${where}: \`pending\` sets ${reserved.join(", ")}, which chant writes itself`);
+  if ("description" in value && typeof (value as { description?: unknown }).description !== "string") throw new Error(`${where}: pending.description must be a string`);
+  return Object.keys(value).length > 0 ? (value as Record<string, unknown>) : undefined;
+}
+
+/** A hook call that held the wave on another gate (#3821), kept so it can run again once that gate is approved. */
+export interface OtherGateHold {
+  label: string;
+  name: string;
+  moment: OpWaveHookMoment;
+  target?: string;
+  argv: string[];
+  env: Record<string, string>;
+  request: OpWaveHoldRequest;
+}
+
+/** Read the hold file a hook wrote (#3821), or undefined when it wrote none or one that names no gate and digest. */
+export function readHoldRequest(path: string, log: (line: string) => void, label: string): OpWaveHoldRequest | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const r = JSON.parse(readFileSync(path, "utf-8")) as Partial<OpWaveHoldRequest>;
+    if (typeof r.gate !== "string" || r.gate === "" || typeof r.digest !== "string" || r.digest === "") throw new Error("it names no gate and digest");
+    if (r.op !== undefined && (typeof r.op !== "string" || r.op === "")) throw new Error("its op is not a name");
+    return { gate: r.gate, digest: r.digest, ...(r.op ? { op: r.op } : {}), ...(typeof r.description === "string" ? { description: r.description } : {}), ...(r.pending ? { pending: pendingFields(r.pending, `the hold ${label} wrote`) ?? {} } : {}) };
+  } catch (err) {
+    log(`${label} wrote a hold file that cannot be read (${err instanceof Error ? err.message : String(err)}), so it holds the wave on its set digest`);
+    return undefined;
+  }
+}
+
+/** Where hooks run: the wave they belong to and the job's tools. */
+export interface HookPlace {
+  /** The spec's name and `op`. */
+  name: string;
+  op: string;
+  waveName: string;
+  k: number;
+  cwd: string;
+  exec: OpWaveExec;
+  log: (line: string) => void;
+  /** Where a hook writes a hold on another gate (`CHANT_HOLD`). Default: under the wave's directory. */
+  holdPath?: string;
+}
+
+/**
+ * Run one moment's hooks, in order: each once for the wave, or once per run
+ * for a `perRun` hook. A hook that fails stops the rest, unless its
+ * `onFailure` is `approve`: then it holds the wave and the hooks after it run.
+ */
+export function runHookList(
+  at: HookPlace,
+  moment: OpWaveHookMoment,
+  hooks: readonly OpWaveHook[] | undefined,
+  runs: readonly OpWaveHookRun[],
+  runsPath: string,
+  extraEnv: Record<string, string> = {},
+): HookListOutcome {
+  const out: HookListOutcome = { holds: [], outcomes: [], otherGates: [] };
+  if (!hooks || hooks.length === 0) return out;
+  const { name: specName, op, waveName, k, cwd, exec, log } = at;
+  // #3821: a hook that holds the wave on another gate names it in this file.
+  const holdPath = at.holdPath ?? `.chant/op-waves/${specName}/wave-${k}/hold.json`;
+  const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath, CHANT_HOLD: holdPath, ...extraEnv };
+  for (const hook of hooks) {
+    const name = hook.name ?? (hook.command.join(" ").length > 60 ? `${hook.command.join(" ").slice(0, 57)}...` : hook.command.join(" "));
+    // #4288: a hook with `targets` is for the runs they match. Once for the wave, it runs when one matches or no run is known yet.
+    const mine = opWaveHookRuns(hook, runs);
+    if (hook.targets && (hook.perRun ? mine.length === 0 : mine.length === 0 && runs.length > 0)) {
+      log(`${moment} hook ${name}: no run matches its targets (${hook.targets.join(", ")}), so it did not run`);
+      continue;
+    }
+    const calls = hook.perRun
+      ? mine.map((run) => ({
+          target: run.target as string | undefined,
+          argv: opWaveArgv(hook.command, { op: run.op, wave: waveName, target: run.target, runs: runsPath, ...(run.plan ? { plan: run.plan } : {}) }),
+          env: { ...env, CHANT_TARGET: run.target, ...(run.plan ? { CHANT_PLAN: run.plan } : {}) } as Record<string, string>,
+        }))
+      : [{ target: undefined, argv: opWaveArgv(hook.command, { op, wave: waveName, runs: runsPath }), env: env as Record<string, string> }];
+    for (const call of calls) {
+      const label = `${moment} hook ${name}${call.target ? ` (${call.target})` : ""}`;
+      let code: number;
+      rmSync(join(cwd, holdPath), { force: true });
+      try {
+        code = exec(call.argv, cwd, call.env);
+      } catch (err) {
+        log(`${label} did not run: ${err instanceof Error ? err.message : String(err)}`);
+        code = 127;
+      }
+      const base = { moment, name, ...(call.target ? { target: call.target } : {}), exit: code };
+      if (code === 0) {
+        out.outcomes.push({ ...base, outcome: "passed" });
+        continue;
+      }
+      if (hook.onFailure === "approve") {
+        out.outcomes.push({ ...base, outcome: "held" });
+        const request = readHoldRequest(join(cwd, holdPath), log, label);
+        if (request) {
+          out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
+          log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
+          continue;
+        }
+        out.holds.push(label);
+        log(`${label} exited ${code}, so wave ${k} (${waveName}) waits for an approval of its set digest`);
+        continue;
+      }
+      out.outcomes.push({ ...base, outcome: "failed" });
+      out.failed = `${label} exited ${code}`;
+      log(out.failed);
+      return out;
+    }
+  }
+  return out;
+}
+
+/** The options of {@link runStageHooks} (#4288). */
+export interface RunStageHooksOptions {
+  /** What the hooks belong to: `CHANT_OP_WAVES`, and the `{op}` of a hook that runs once. */
+  name: string;
+  op: string;
+  /** `{wave}` and `CHANT_WAVE`. */
+  wave: string;
+  /** `CHANT_WAVE_NUMBER`. Default 0. */
+  k?: number;
+  /** The runs a `perRun` hook runs for and `targets` match against. */
+  runs: readonly OpWaveHookRun[];
+  /** `{runs}` and `CHANT_RUNS`, relative to `cwd`; the caller writes it. */
+  runsFile: string;
+  /** `CHANT_HOLD`, relative to `cwd`. */
+  holdFile: string;
+  /** Added to every hook's environment. */
+  env?: Record<string, string>;
+  cwd?: string;
+  exec?: OpWaveExec;
+  log?: (line: string) => void;
+}
+
+/** What {@link runStageHooks} gave. */
+export interface StageHooksRun {
+  outcomes: OpWaveHookOutcome[];
+  /** Set when a hook with `onFailure: fail` failed; the hooks after it did not run. */
+  failed?: string;
+  /** The `onFailure: approve` hooks that failed. A hold on another gate counts as one here. */
+  holds: string[];
+}
+
+/**
+ * Run one moment's hooks outside an Op waves job (#4288): the pull-request
+ * jobs, or a product's own stage, with the same `targets`, `perRun`,
+ * `onFailure` and argv filling a wave job uses. A hook that holds on another
+ * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
+ * caller's.
+ */
+export function runStageHooks(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksOptions): StageHooksRun {
+  const cwd = options.cwd ?? process.cwd();
+  const log = options.log ?? ((line: string) => console.error(line));
+  const place: HookPlace = { name: options.name, op: options.op, waveName: options.wave, k: options.k ?? 0, cwd, exec: options.exec ?? spawnExec, log, holdPath: options.holdFile };
+  const out = runHookList(place, moment, hooks, options.runs, options.runsFile, options.env);
+  return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? options.name} / ${g.request.gate})`)] };
+}

package/src/pr-forge-bundle.test.ts

@@ -34,7 +34,7 @@ describe("the pr-forge bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual(["packages/core/src/pr-forge.ts"]);
-    // About 37 KB today, after the pull request authors (#4000) and pullRequestOpen for target locks (#4293).
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(40 * 1024);
+    // About 47 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293) and the four requires checks of an apply before merge (#4301).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(52 * 1024);
   });
 });

package/src/pr-forge.ts

@@ -411,6 +411,49 @@ export interface PrForge {
    * pipelines. Throws a {@link ForgeApiError} when the forge will not say.
    */
   scheduledRuns?(query: ScheduledRunsQuery): Promise<ScheduledRuns>;
+  /**
+   * The four checks an apply before merge requires (#4301, ws-106), each
+   * about pull request `pr` at `head`, the commit the job checked out. Each
+   * fails when the forge's head for `pr` is another commit. `approved`:
+   * someone other than the pull request's authors ({@link authors}) approved
+   * `head`, and no standing review asks for changes. On GitLab an approval
+   * counts when it came after the merge request's latest push, read from its
+   * system notes, and never from the token's own user.
+   */
+  prApproved?(pr: number, head: string): Promise<PrRequireResult>;
+  /** The forge says `pr` merges as it stands: no conflicts, and on GitHub no branch protection blocking it. Pending while the forge works it out. */
+  prMergeable?(pr: number, head: string): Promise<PrRequireResult>;
+  /** `head` contains the tip of the branch `pr` merges into. */
+  prUndiverged?(pr: number, head: string): Promise<PrRequireResult>;
+  /**
+   * Every status and check reported on `head` passed, and at least one did.
+   * Statuses named in `ignore` are left out, such as the apply's own.
+   * Pending while one still runs or none has reported.
+   */
+  prChecksPassed?(pr: number, head: string, ignore?: readonly string[]): Promise<PrRequireResult>;
+}
+
+/** What one of the requires checks (#4301) found. */
+export interface PrRequireResult {
+  passed: boolean;
+  /** Not settled yet: the forge is still working it out, or a check still runs. Asking again may pass. */
+  pending?: boolean;
+  /** One line for a person. */
+  reason: string;
+}
+
+const short = (sha: string | undefined): string => (sha ?? "nothing").slice(0, 8);
+const pass = (reason: string): PrRequireResult => ({ passed: true, reason });
+const refuse = (reason: string, pending = false): PrRequireResult => ({ passed: false, ...(pending ? { pending: true } : {}), reason });
+const moved = (what: string, head: string, now: string | undefined): PrRequireResult => refuse(`${what}'s head is ${short(now)}, not ${short(head)}, the commit this job checked out`);
+
+/** The verdict over statuses and checks: failing and still-running names, and how many reported. */
+function checksVerdict(what: string, head: string, failing: string[], waiting: string[], count: number): PrRequireResult {
+  const names = (l: string[]) => [...new Set(l)].sort().join(", ");
+  if (failing.length > 0) return refuse(`${names(failing)} failed on ${short(head)}`);
+  if (waiting.length > 0) return refuse(`${names(waiting)} still running on ${short(head)}`, true);
+  if (count === 0) return refuse(`no check has reported on ${what}'s head ${short(head)} yet`, true);
+  return pass(`${count} check${count === 1 ? "" : "s"} passed on ${short(head)}`);
 }
 
 /** Which scheduled Op job {@link PrForge.scheduledRuns} asks about. */
@@ -624,6 +667,11 @@ export interface GithubForgeOptions {
   fetch?: ForgeFetch;
 }
 
+/** GitLab's merge statuses while it works out whether a merge request can merge (#4301). */
+const GITLAB_CHECKING = new Set(["checking", "unchecked", "preparing", "approvals_syncing", "cannot_be_merged_recheck"]);
+/** GitLab's commit statuses still running. */
+const GITLAB_RUNNING = new Set(["created", "waiting_for_resource", "preparing", "pending", "running", "scheduled"]);
+
 /** GitHub keeps a status description to 140 characters; Forgejo follows. */
 const GITHUB_DESCRIPTION = 140;
 /** GitLab keeps a status description to 255 characters. */
@@ -693,6 +741,33 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       ...(url ? { target_url: url } : {}),
     });
   };
+  const authorsOf = async (pr: number): Promise<string[]> => {
+    const logins = new Set<string>();
+    const add = (v: unknown) => {
+      if (isObject(v) && typeof v.login === "string" && v.login !== "") logins.add(v.login);
+    };
+    const opened = await api.call("GET", `${repo}/pulls/${pr}`);
+    if (isObject(opened)) add(opened.user);
+    for (const c of await api.list(`${repo}/pulls/${pr}/commits`, pageParams, pageSize)) {
+      if (!isObject(c)) continue;
+      add(c.author);
+      add(c.committer);
+    }
+    return [...logins].sort();
+  };
+  const branchTip = async (branch: string): Promise<string | undefined> => {
+    let b: unknown;
+    try {
+      b = await api.call("GET", `${repo}/branches/${branch.split("/").map(encodeURIComponent).join("/")}`);
+    } catch (err) {
+      if (err instanceof ForgeApiError && err.status === 404) return undefined;
+      throw err;
+    }
+    // GitHub names the commit `sha`, Forgejo `id`.
+    const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
+    return commit ? str(commit.sha) ?? str(commit.id) : undefined;
+  };
+  const headOf = (v: unknown): string | undefined => (isObject(v) && isObject(v.head) ? str(v.head.sha) : undefined);
   return {
     kind,
     host,
@@ -720,19 +795,84 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       }
       return [...standing].filter(([, state]) => state === "APPROVED").map(([login]) => login).sort();
     },
-    async authors(pr) {
-      const logins = new Set<string>();
-      const add = (v: unknown) => {
-        if (isObject(v) && typeof v.login === "string" && v.login !== "") logins.add(v.login);
-      };
-      const opened = await api.call("GET", `${repo}/pulls/${pr}`);
-      if (isObject(opened)) add(opened.user);
-      for (const c of await api.list(`${repo}/pulls/${pr}/commits`, pageParams, pageSize)) {
-        if (!isObject(c)) continue;
-        add(c.author);
-        add(c.committer);
+    authors: authorsOf,
+    async prApproved(pr, head) {
+      const got = await api.call("GET", `${repo}/pulls/${pr}`);
+      const at = headOf(got);
+      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      // A reviewer's newest deciding review stands, as in approvers; an approval counts only of this head.
+      const standing = new Map<string, { state: string; commit?: string }>();
+      for (const r of await api.list(`${repo}/pulls/${pr}/reviews`, pageParams, pageSize)) {
+        const login = loginOf(r);
+        if (!login || !isObject(r) || typeof r.state !== "string") continue;
+        const state = r.dismissed === true ? "DISMISSED" : r.state.toUpperCase();
+        if (state === "COMMENTED" || state === "COMMENT" || state === "PENDING") continue;
+        const commit = str(r.commit_id);
+        standing.set(login, { state, ...(commit ? { commit } : {}) });
+      }
+      const changes = [...standing].filter(([, r]) => r.state === "CHANGES_REQUESTED" || r.state === "REQUEST_CHANGES").map(([l]) => l).sort();
+      if (changes.length > 0) return refuse(`${changes.join(", ")} asked for changes`);
+      const authors = new Set(await authorsOf(pr));
+      const by = [...standing].filter(([l, r]) => r.state === "APPROVED" && r.commit === head && !authors.has(l)).map(([l]) => l).sort();
+      if (by.length === 0) return refuse(`no reviewer other than its authors approved its head ${short(head)}`);
+      return pass(`approved at ${short(head)} by ${by.join(", ")}`);
+    },
+    async prMergeable(pr, head) {
+      const got = await api.call("GET", `${repo}/pulls/${pr}`);
+      const at = headOf(got);
+      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      const m = isObject(got) ? got : {};
+      const into = isObject(m.base) ? str(m.base.ref) : undefined;
+      if (m.mergeable === false || m.mergeable_state === "dirty") return refuse(`the forge reports conflicts with ${into ?? "its base"}`);
+      if (m.mergeable !== true) return refuse("the forge has not worked out yet whether it can merge", true);
+      if (kind === "github" && m.mergeable_state === "blocked") return refuse(`branch protection on ${into ?? "its base"} blocks its merge`);
+      return pass(`it merges into ${into ?? "its base"} as it stands`);
+    },
+    async prUndiverged(pr, head) {
+      const got = await api.call("GET", `${repo}/pulls/${pr}`);
+      const at = headOf(got);
+      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      const into = isObject(got) && isObject(got.base) ? str(got.base.ref) : undefined;
+      if (!into) return refuse(`the forge names no branch pull request ${pr} merges into`);
+      if (kind === "github") {
+        // behind_by: the commits on the base branch that the head does not contain.
+        const cmp = await api.call("GET", `${repo}/compare/${encodeURIComponent(into)}...${head}`);
+        const behind = isObject(cmp) ? num(cmp.behind_by) : undefined;
+        if (behind === undefined) return refuse(`the forge did not say how far ${short(head)} is behind ${into}`);
+        return behind === 0 ? pass(`${short(head)} contains ${into}`) : refuse(`${short(head)} is ${behind} commit${behind === 1 ? "" : "s"} behind ${into}`);
+      }
+      // Forgejo: the pull request's merge base is the base branch's tip exactly when the head contains it.
+      const tip = await branchTip(into);
+      const base = isObject(got) ? str(got.merge_base) : undefined;
+      if (!tip || !base) return refuse(`the forge did not say where ${into} is or where ${short(head)} left it`);
+      return base === tip ? pass(`${short(head)} contains ${into} at ${short(tip)}`) : refuse(`${short(head)} does not contain ${into} at ${short(tip)}`);
+    },
+    async prChecksPassed(_pr, head, ignore = []) {
+      const skip = new Set(ignore);
+      const failing: string[] = [];
+      const waiting: string[] = [];
+      let count = 0;
+      // The combined status holds each context's newest status.
+      const combined = await api.call("GET", `${repo}/commits/${head}/status`);
+      for (const st of isObject(combined) && Array.isArray(combined.statuses) ? combined.statuses : []) {
+        const context = isObject(st) ? str(st.context) : undefined;
+        if (!context || skip.has(context)) continue;
+        const state = str(st.state) ?? str(st.status) ?? "";
+        count++;
+        if (state === "failure" || state === "error" || state === "failed") failing.push(context);
+        else if (state === "pending" || state === "running" || state === "") waiting.push(context);
       }
-      return [...logins].sort();
+      if (kind === "github") {
+        const runs = await api.call("GET", `${repo}/commits/${head}/check-runs?per_page=100`);
+        for (const run of isObject(runs) && Array.isArray(runs.check_runs) ? runs.check_runs : []) {
+          const name = (isObject(run) ? str(run.name) : undefined) ?? "a check";
+          if (skip.has(name) || !isObject(run)) continue;
+          count++;
+          if (run.status !== "completed") waiting.push(name);
+          else if (!["success", "neutral", "skipped"].includes(String(run.conclusion))) failing.push(name);
+        }
+      }
+      return checksVerdict(`pull request ${_pr}`, head, failing, waiting, count);
     },
     async pullRequestOpen(pr) {
       try {
@@ -817,18 +957,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       }
       return out.sort((a, b) => a.number - b.number);
     },
-    async branchHead(branch) {
-      let b: unknown;
-      try {
-        b = await api.call("GET", `${repo}/branches/${branch.split("/").map(encodeURIComponent).join("/")}`);
-      } catch (err) {
-        if (err instanceof ForgeApiError && err.status === 404) return undefined;
-        throw err;
-      }
-      // GitHub names the commit `sha`, Forgejo `id`.
-      const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
-      return commit ? str(commit.sha) ?? str(commit.id) : undefined;
-    },
+    branchHead: branchTip,
     async scheduledRuns(q) {
       const file = encodeURIComponent(q.workflow);
       if (kind === "github") {
@@ -998,6 +1127,22 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       await api.call("PUT", `${project}/issues/${n}`, { state_event: "close" });
     },
   };
+  const authorsOf = async (mr: number): Promise<string[]> => {
+    const logins = new Set<string>();
+    const merge = await api.call("GET", `${notes}/${mr}`);
+    const author = isObject(merge) ? authorOf(merge) : undefined;
+    if (author) logins.add(author);
+    const emails = new Set<string>();
+    for (const c of await api.list(`${notes}/${mr}/commits`, pageParams, 100)) {
+      if (!isObject(c)) continue;
+      for (const email of [str(c.author_email), str(c.committer_email)]) if (email) emails.add(email.toLowerCase());
+    }
+    for (const email of [...emails].sort()) {
+      const users = await api.call("GET", `/users?search=${encodeURIComponent(email)}`);
+      for (const u of Array.isArray(users) ? users : []) if (isObject(u) && typeof u.username === "string") logins.add(u.username);
+    }
+    return [...logins].sort();
+  };
   return {
     kind: "gitlab",
     host,
@@ -1029,21 +1174,74 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         .filter((l): l is string => l !== undefined);
       return [...new Set(logins)].sort();
     },
-    async authors(mr) {
-      const logins = new Set<string>();
-      const merge = await api.call("GET", `${notes}/${mr}`);
-      const author = isObject(merge) ? authorOf(merge) : undefined;
-      if (author) logins.add(author);
-      const emails = new Set<string>();
-      for (const c of await api.list(`${notes}/${mr}/commits`, pageParams, 100)) {
-        if (!isObject(c)) continue;
-        for (const email of [str(c.author_email), str(c.committer_email)]) if (email) emails.add(email.toLowerCase());
+    authors: authorsOf,
+    async prApproved(mr, head) {
+      const got = await api.call("GET", `${notes}/${mr}`);
+      const at = isObject(got) ? str(got.sha) : undefined;
+      if (at !== head) return moved(`merge request !${mr}`, head, at);
+      // The token's own user approves for the pipeline, never as a reviewer.
+      const me = await api.call("GET", "/user");
+      const self = isObject(me) ? str(me.username) : undefined;
+      if (!self) return refuse("GitLab did not say which user the job's token acts as, so no approval counts");
+      // An approval counts once it came after the latest push: the newest version of the diff.
+      const versions = await api.call("GET", `${notes}/${mr}/versions`);
+      const since = Math.max(-Infinity, ...(Array.isArray(versions) ? versions : []).map((v) => Date.parse((isObject(v) ? str(v.created_at) : undefined) ?? "")).filter(Number.isFinite));
+      const said = new Map<string, { what: string; at: number }>();
+      for (const n of await api.list(`${notes}/${mr}/notes?sort=asc&order_by=created_at`, pageParams, 100)) {
+        if (!isObject(n) || n.system !== true) continue;
+        const who = authorOf(n);
+        const body = (str(n.body) ?? "").trim();
+        const what = /^approved this merge request/.test(body) ? "approved" : /^unapproved this merge request/.test(body) ? "unapproved" : /^requested changes/.test(body) ? "changes" : undefined;
+        const when = Date.parse(str(n.created_at) ?? "");
+        if (!who || who === self || !what || !Number.isFinite(when)) continue;
+        const before = said.get(who);
+        if (!before || when >= before.at) said.set(who, { what, at: when });
+      }
+      const changes = [...said].filter(([, v]) => v.what === "changes").map(([w]) => w).sort();
+      if (changes.length > 0) return refuse(`${changes.join(", ")} requested changes`);
+      const authors = new Set(await authorsOf(mr));
+      const by = [...said].filter(([w, v]) => v.what === "approved" && v.at > since && !authors.has(w)).map(([w]) => w).sort();
+      if (by.length === 0) return refuse(`no member other than its authors approved it after its latest push, ${short(head)}`);
+      return pass(`approved after ${short(head)} by ${by.join(", ")}`);
+    },
+    async prMergeable(mr, head) {
+      const got = await api.call("GET", `${notes}/${mr}`);
+      const m = isObject(got) ? got : {};
+      if (str(m.sha) !== head) return moved(`merge request !${mr}`, head, str(m.sha));
+      const status = str(m.detailed_merge_status) ?? (m.merge_status === "can_be_merged" ? "mergeable" : (str(m.merge_status) ?? ""));
+      const into = str(m.target_branch) ?? "its target branch";
+      if (status === "conflict" || m.has_conflicts === true) return refuse(`GitLab reports conflicts with ${into}`);
+      if (GITLAB_CHECKING.has(status)) return refuse("GitLab has not worked out yet whether it can merge", true);
+      if (status !== "mergeable") return refuse(`GitLab says ${status || "nothing"} about merging it`);
+      return pass(`it merges into ${into} as it stands`);
+    },
+    async prUndiverged(mr, head) {
+      const got = await api.call("GET", `${notes}/${mr}?include_diverged_commits_count=true`);
+      const m = isObject(got) ? got : {};
+      if (str(m.sha) !== head) return moved(`merge request !${mr}`, head, str(m.sha));
+      const into = str(m.target_branch) ?? "its target branch";
+      const behind = num(m.diverged_commits_count);
+      if (behind === undefined) return refuse(`GitLab did not say how far ${short(head)} is behind ${into}`);
+      return behind === 0 ? pass(`${short(head)} contains ${into}`) : refuse(`${short(head)} is ${behind} commit${behind === 1 ? "" : "s"} behind ${into}`);
+    },
+    async prChecksPassed(mr, head, ignore = []) {
+      const skip = new Set(ignore);
+      // Each name's newest status; a job allowed to fail holds nothing back.
+      const newest = new Map<string, Record<string, unknown>>();
+      for (const st of await api.list(`${project}/repository/commits/${head}/statuses?all=true`, pageParams, 100)) {
+        const name = isObject(st) ? str(st.name) : undefined;
+        if (!name || skip.has(name) || !isObject(st)) continue;
+        const had = newest.get(name);
+        if (!had || (num(st.id) ?? 0) > (num(had.id) ?? 0)) newest.set(name, st);
       }
-      for (const email of [...emails].sort()) {
-        const users = await api.call("GET", `/users?search=${encodeURIComponent(email)}`);
-        for (const u of Array.isArray(users) ? users : []) if (isObject(u) && typeof u.username === "string") logins.add(u.username);
+      const failing: string[] = [];
+      const waiting: string[] = [];
+      for (const [name, st] of newest) {
+        const state = str(st.status) ?? "";
+        if ((state === "failed" || state === "canceled") && st.allow_failure !== true) failing.push(name);
+        else if (GITLAB_RUNNING.has(state)) waiting.push(name);
       }
-      return [...logins].sort();
+      return checksVerdict(`merge request !${mr}`, head, failing, waiting, newest.size);
     },
     async pullRequestOpen(mr) {
       try {

package/src/pr-loop-bundle.test.ts

@@ -41,7 +41,7 @@ describe("the pull-request loop bundle", () => {
       "packages/core/src/pr-forge.ts",
       "packages/core/src/pr-loop.ts",
     ]);
-    // About 76 KB today, after the hooks line (#4288), the blocked set (#4291) and the scheduled-run reads (#4289).
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(80 * 1024);
+    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) and the requires checks (#4301).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(96 * 1024);
   });
 });

package/src/pr-loop.ts

@@ -48,6 +48,7 @@
  */
 
 import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
+import type { PrRequireOutcome } from "./pr-requires";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary";
 
 /** The schema a pull-request report names in `$schema`. */
@@ -80,6 +81,9 @@ export const PR_REPORT_OVERDUE_FLOOR = "0.124.41";
 /** The first chant whose report can carry `policy` and the `policy-denied` and `policy-error` refusals (#4294). */
 export const PR_REPORT_POLICY_FLOOR = "0.124.41";
 
+/** The first chant whose apply report can carry `beforeMerge` and the `requires-unmet` and `before-merge-off` refusals (#4301, ws-106). */
+export const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -275,7 +279,16 @@ export type PrRefusal =
   /** `ci.policy` at base denied the plan (#4294), and no override of it counts. */
   | "policy-denied"
   /** `ci.policy` at base could not be run, or gave no answer chant can read (#4294). */
-  | "policy-error";
+  | "policy-error"
+  /** `pr-apply --before-merge` (#4301): the pull request is not approved, mergeable, undiverged or green; `beforeMerge` says which. */
+  | "requires-unmet"
+  /** `pr-apply --before-merge`: the declaration at base does not set `ci.workflow` to `apply-before-merge` for the member. */
+  | "before-merge-off";
+
+/** An apply before merge (#4301, ws-106): the requires checks the forge answered, in order. */
+export interface PrBeforeMerge {
+  requires: PrRequireOutcome[];
+}
 
 /**
  * One wave of an apply with `--wave-gate` (#4003): what it planned, where it
@@ -445,6 +458,12 @@ export interface PrReport {
    * within contract 1 by chant {@link PR_REPORT_POLICY_FLOOR}.
    */
   policy?: PrPolicyReport;
+  /**
+   * `pr-apply --before-merge` (#4301): the requires checks. Absent on every
+   * other stage. Added within contract 1 by chant
+   * {@link PR_REPORT_BEFORE_MERGE_FLOOR}.
+   */
+  beforeMerge?: PrBeforeMerge;
 }
 
 /** The counts a member's entries add up to. */
@@ -771,6 +790,11 @@ export function prStatusDescription(report: PrReport): string {
         text = "refused: an earlier wave has not applied";
         break;
       }
+      if (report.refusal === "requires-unmet" || report.refusal === "before-merge-off") {
+        const unmet = (report.beforeMerge?.requires ?? []).filter((r) => !r.passed).map((r) => r.name);
+        text = report.refusal === "before-merge-off" ? "refused: this workspace does not apply before merge" : `refused: ${unmet.join(", ") || "a require"} unmet for an apply before merge`;
+        break;
+      }
       if (report.refusal === "policy-denied" || report.refusal === "policy-error") {
         text = report.refusal === "policy-denied" ? `refused: the policy denied the plan (${(report.policy?.rules ?? []).join(", ")})` : "refused: the policy could not be checked";
         break;