@intentius/chant 0.124.41 → 0.124.43

package/src/pr-forge.ts

@@ -411,6 +411,117 @@ 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. `approvers` narrows
+   * who counts (#4337), and a refusal names each approver left out and why.
+   */
+  prApproved?(pr: number, head: string, approvers?: PrApproverFilter): 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. On
+   * Forgejo, which answers `mergeable: false` while it still checks, a false
+   * is pending too, so it counts as conflicts only once the reads run 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>;
+}
+
+/**
+ * Who counts as an approver for {@link PrForge.prApproved} (#4337). With
+ * none set, any reviewer other than the pull request's authors counts.
+ */
+export interface PrApproverFilter {
+  /**
+   * The forge's own rule for who may approve. GitHub: write access (admin,
+   * maintain or write), read per approver. Forgejo: the review is official,
+   * which Forgejo marks for someone with write access. GitLab: an access
+   * level of at least `minAccessLevel`, read per approver.
+   */
+  forgeRule?: boolean;
+  /** GitLab under `forgeRule`: the least access level that counts. Default 30, Developer. */
+  minAccessLevel?: number;
+  /** Logins whose approval never counts, compared case-insensitively, each with the reason a refusal gives if one is set. */
+  exclude?: readonly (string | PrExcludedApprover)[];
+}
+
+/** A login left out of the approvers, and the reason a refusal gives. */
+export interface PrExcludedApprover {
+  login: string;
+  reason: string;
+}
+
+/** Why `login`'s approval does not count under `filter`'s `exclude`, or undefined. */
+function excludedWhy(filter: PrApproverFilter | undefined, login: string): string | undefined {
+  for (const e of filter?.exclude ?? []) {
+    const who = typeof e === "string" ? e : e.login;
+    if (who.toLowerCase() === login.toLowerCase()) return typeof e === "string" ? `${login} is excluded` : e.reason;
+  }
+  return undefined;
+}
+
+/**
+ * The approvers who count, and why each other one did not: an author, then
+ * `exclude`, then the forge's rule (`rule` gives a reason or undefined).
+ */
+async function countApprovers(
+  approved: readonly string[],
+  authors: ReadonlySet<string>,
+  filter: PrApproverFilter | undefined,
+  rule: (login: string) => Promise<string | undefined>,
+): Promise<{ by: string[]; not: string[] }> {
+  const by: string[] = [];
+  const not: string[] = [];
+  for (const login of approved) {
+    const why = authors.has(login) ? `${login} is one of its authors` : (excludedWhy(filter, login) ?? (filter?.forgeRule ? await rule(login) : undefined));
+    if (why) not.push(why);
+    else by.push(login);
+  }
+  return { by, not };
+}
+
+/** A refusal for no approver counted, naming each one left out. */
+const noApprover = (line: string, not: readonly string[]): PrRequireResult => refuse(not.length > 0 ? `${line}: ${not.join("; ")}` : line);
+
+/** GitLab's access level for Developer, the least that may push. */
+const GITLAB_DEVELOPER = 30;
+
+/** GitHub's permissions that may approve under {@link PrApproverFilter.forgeRule}. */
+const GITHUB_WRITERS = new Set(["admin", "maintain", "write"]);
+
+/** 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 +735,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 +809,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 +863,100 @@ 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);
+    authors: authorsOf,
+    async prApproved(pr, head, approvers) {
+      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; official?: boolean }>();
+      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 } : {}), ...(typeof r.official === "boolean" ? { official: r.official } : {}) });
+      }
+      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 approved = [...standing].filter(([, r]) => r.state === "APPROVED" && r.commit === head).map(([l]) => l).sort();
+      const rule = async (login: string): Promise<string | undefined> => {
+        // Forgejo marks a review official when its author may write; terragucci read a missing flag as official too.
+        if (kind === "forgejo") return standing.get(login)?.official === false ? `${login}'s review is not official` : undefined;
+        let got: unknown;
+        try {
+          got = await api.call("GET", `${repo}/collaborators/${encodeURIComponent(login)}/permission`);
+        } catch (err) {
+          return `could not read ${login}'s access (${err instanceof Error ? err.message : String(err)})`;
+        }
+        const p = isObject(got) ? [str(got.permission), str(got.role_name)] : [];
+        return p.some((x) => x !== undefined && GITHUB_WRITERS.has(x)) ? undefined : `${login} has no write access`;
       };
-      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);
+      const { by, not } = await countApprovers(approved, authors, approvers, rule);
+      if (by.length === 0) return noApprover(`no reviewer other than its authors approved its head ${short(head)}`, not);
+      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;
+      // Forgejo answers mergeable false while it still checks for conflicts, and names no state that tells the two apart, so its false is asked again.
+      if (kind === "forgejo" && m.draft === true) return refuse("it is a draft");
+      if (kind === "forgejo" && m.mergeable === false) return refuse(`Forgejo reports conflicts with ${into ?? "its base"}, or is still checking for them`, true);
+      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);
+      }
+      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 [...logins].sort();
+      return checksVerdict(`pull request ${_pr}`, head, failing, waiting, count);
     },
     async pullRequestOpen(pr) {
       try {
@@ -817,18 +1041,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 +1211,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 +1258,90 @@ 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, approvers) {
+      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; id?: 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);
+        const id = isObject(n.author) ? num(n.author.id) : undefined;
+        if (!before || when >= before.at) said.set(who, { what, at: when, ...(id !== undefined ? { id } : {}) });
+      }
+      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 approved = [...said].filter(([, v]) => v.what === "approved" && v.at > since).map(([w]) => w).sort();
+      const least = approvers?.minAccessLevel ?? GITLAB_DEVELOPER;
+      const rule = async (login: string): Promise<string | undefined> => {
+        const id = said.get(login)?.id;
+        if (id === undefined) return `GitLab did not say who ${login} is`;
+        let member: unknown;
+        try {
+          member = await api.call("GET", `${project}/members/all/${id}`);
+        } catch (err) {
+          if (err instanceof ForgeApiError && err.status === 404) return `${login} is not a member`;
+          return `could not read ${login}'s access (${err instanceof Error ? err.message : String(err)})`;
+        }
+        const level = isObject(member) ? (num(member.access_level) ?? 0) : 0;
+        return level >= least ? undefined : `${login} has access level ${level}, under ${least}`;
+      };
+      const { by, not } = await countApprovers(approved, authors, approvers, rule);
+      if (by.length === 0) return noApprover(`no member other than its authors approved it after its latest push, ${short(head)}`, not);
+      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;