@intentius/chant 0.124.42 → 0.124.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.42",
+  "version": "0.124.43",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/pr.ts

@@ -1076,6 +1076,7 @@ async function beforeMergeChecks(ctx: CommandContext): Promise<PrBeforeMerge | n
   }
   // The apply's own statuses never hold it back: chant ci run's, and the report's.
   const ignore = [`chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member)];
+  // No `only`: ws-106 gives the declaration no way to leave a check out, so all four are asked (#4336).
   const requires = await checkPrRequires(forge, args.pr, head, { ignore });
   for (const r of requires) console.error(formatInfo(`${r.name}: ${r.passed ? "passed" : r.pending ? "pending" : "unmet"}, ${r.reason}`));
   const unmet = unmetRequires(requires);

package/src/op/index.ts

@@ -75,6 +75,8 @@ export {
   OP_WAVE_MAX_REPLANS,
   opWaveHooksAtBase,
   runStageHooks,
+  runStageHooksAsync,
+  spawnExecAsync,
   opWaveNeedsApproval,
   opWavePlansPath,
   opWaveRunsPath,
@@ -91,6 +93,7 @@ export type {
   OpWaveDecision,
   OpWaveApplyHooksRun,
   OpWaveApplyOutcome,
+  OpWaveAsyncExec,
   OpWaveExec,
   OpWaveHeldOn,
   OpWaveHoldRequest,
@@ -106,6 +109,7 @@ export type {
   OpWaveShowAtBase,
   RecordHeadPlansOptions,
   RunOpWaveApplyHooksOptions,
+  RunStageHooksAsyncOptions,
   RunStageHooksOptions,
   StageHooksRun,
   RunOpWaveOptions,

package/src/op/op-waves-run.ts

@@ -112,19 +112,23 @@ import {
   readHoldRequest,
   runHookList,
   runStageHooks,
+  runStageHooksAsync,
   spawnExec,
+  spawnExecAsync,
   type HookPlace,
+  type OpWaveAsyncExec,
   type OpWaveExec,
   type OpWaveHoldRequest,
   type OpWaveHookOutcome,
   type OpWaveHookRun,
   type OtherGateHold,
+  type RunStageHooksAsyncOptions,
   type RunStageHooksOptions,
   type StageHooksRun,
 } from "./stage-hooks";
 
-export { OP_WAVE_PENDING_RESERVED, opWaveArgv, runStageHooks };
-export type { OpWaveExec, OpWaveHoldRequest, OpWaveHookOutcome, OpWaveHookRun, RunStageHooksOptions, StageHooksRun };
+export { OP_WAVE_PENDING_RESERVED, opWaveArgv, runStageHooks, runStageHooksAsync, spawnExecAsync };
+export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldRequest, OpWaveHookOutcome, OpWaveHookRun, RunStageHooksAsyncOptions, RunStageHooksOptions, StageHooksRun };
 
 /** What a run's plan command writes to `{plan}`. */
 export interface OpWavePlanFile {

package/src/op/stage-hooks-async.test.ts

@@ -0,0 +1,79 @@
+/**
+ * runStageHooksAsync (#4334): the async stage runner gives what the sync one
+ * gives for the same hooks, and two calls run side by side.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { OpWaveHook } from "./op-waves";
+import { runStageHooks, runStageHooksAsync, spawnExecAsync, type OpWaveAsyncExec, type OpWaveExec } from "./stage-hooks";
+
+const hooks: OpWaveHook[] = [
+  { name: "each", command: ["hook", "each", "{target}", "{op}"], perRun: true, targets: ["api"] },
+  { name: "gate", command: ["hook", "gate", "{wave}"], onFailure: "approve" },
+  { name: "other", command: ["hook", "other"], onFailure: "approve" },
+  { name: "lost", command: ["hook", "lost"] },
+  { name: "stop", command: ["hook", "stop"] },
+  { name: "after", command: ["hook", "after"] },
+];
+const runs = [{ target: "api", op: "pr-7" }, { target: "web", op: "pr-7" }];
+
+/** Exit codes by the hook's second word; `other` writes a hold on another gate and `lost` cannot start. */
+function codeOf(argv: string[], cwd: string, env?: Record<string, string>): number {
+  if (argv[1] === "other") writeFileSync(join(cwd, env!.CHANT_HOLD!), JSON.stringify({ gate: "dba", digest: "sha256:abc" }));
+  if (argv[1] === "lost") throw new Error("spawn hook ENOENT");
+  return argv[1] === "gate" || argv[1] === "other" || argv[1] === "stop" ? 1 : 0;
+}
+
+describe("runStageHooksAsync (#4334)", () => {
+  test("gives the outcomes, holds and failure the sync runner gives", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-async-"));
+    const options = { name: "pr-7", op: "pr-7", wave: "prod", runs, runsFile: "runs.json", holdFile: "hold.json", cwd };
+    const syncCalls: string[] = [];
+    const syncLog: string[] = [];
+    const exec: OpWaveExec = (argv, at, env) => (syncCalls.push(argv.join(" ")), codeOf(argv, at, env));
+    const sync = runStageHooks("before-plan", hooks, { ...options, exec, log: (l) => syncLog.push(l) });
+    const asyncCalls: string[] = [];
+    const asyncLog: string[] = [];
+    const asyncExec: OpWaveAsyncExec = async (argv, at, env) => (asyncCalls.push(argv.join(" ")), codeOf(argv, at, env));
+    const ran = await runStageHooksAsync("before-plan", hooks, { ...options, exec: asyncExec, log: (l) => asyncLog.push(l) });
+    expect(ran).toEqual(sync);
+    expect(asyncCalls).toEqual(syncCalls);
+    expect(asyncLog).toEqual(syncLog);
+    expect(asyncCalls).toEqual(["hook each api pr-7", "hook gate prod", "hook other", "hook lost"]);
+    expect(ran.failed).toBe("before-plan hook lost exited 127");
+    expect(ran.holds).toEqual(["before-plan hook gate", "before-plan hook other (on pr-7 / dba)"]);
+    expect(ran.outcomes.map((o) => o.outcome)).toEqual(["passed", "held", "held", "failed"]);
+    expect(asyncLog).toContain("before-plan hook lost did not run: spawn hook ENOENT");
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("two calls run side by side", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-async-"));
+    const started: string[] = [];
+    let release!: () => void;
+    const both = new Promise<void>((resolve) => (release = resolve));
+    const exec: OpWaveAsyncExec = async (argv) => {
+      started.push(argv[1]!);
+      if (started.length === 2) release();
+      await both;
+      return 0;
+    };
+    const one = (name: string) =>
+      runStageHooksAsync("before-plan", [{ command: ["hook", name] }], { name, op: name, wave: "prod", runs: [], runsFile: `${name}/runs.json`, holdFile: `${name}/hold.json`, cwd, exec, log: () => {} });
+    const [a, b] = await Promise.all([one("a"), one("b")]);
+    expect(started.sort()).toEqual(["a", "b"]);
+    expect([a.outcomes[0]!.outcome, b.outcomes[0]!.outcome]).toEqual(["passed", "passed"]);
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("the default exec spawns the hook, gives its exit code and rejects a command that cannot start", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-async-"));
+    expect(await spawnExecAsync([process.execPath, "-e", "process.exit(process.env.CODE === '3' ? 3 : 0)"], cwd, { CODE: "3" })).toBe(3);
+    await expect(spawnExecAsync(["./no-such-hook"], cwd)).rejects.toThrow(/ENOENT/);
+    const ran = await runStageHooksAsync("after-apply", [{ name: "ok", command: [process.execPath, "-e", "process.exit(0)"] }], { name: "s", op: "s", wave: "w", runs: [], runsFile: "runs.json", holdFile: "hold.json", cwd, log: () => {} });
+    expect(ran).toEqual({ outcomes: [{ moment: "after-apply", name: "ok", exit: 0, outcome: "passed" }], holds: [] });
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});

package/src/op/stage-hooks.ts

@@ -6,7 +6,7 @@
  * the same hooks inside a wave job.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, 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";
@@ -69,6 +69,17 @@ export const spawnExec: OpWaveExec = (argv, cwd, env) => {
   return result.status ?? 1;
 };
 
+/** {@link OpWaveExec} for {@link runStageHooksAsync} (#4334): the exit code comes back as a promise, so the event loop runs while a hook does. */
+export type OpWaveAsyncExec = (argv: string[], cwd: string, env?: Record<string, string>) => Promise<number>;
+
+/** {@link spawnExec} on `spawn`: it rejects when the command cannot start. */
+export const spawnExecAsync: OpWaveAsyncExec = (argv, cwd, env) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(argv[0]!, argv.slice(1), { cwd, stdio: "inherit", ...(env ? { env: { ...process.env, ...env } } : {}) });
+    child.once("error", reject);
+    child.once("close", (code) => resolve(code ?? 1));
+  });
+
 /** Fill one argv template. A placeholder whose value is not given is left as it is. */
 export function opWaveArgv(
   template: readonly string[],
@@ -134,22 +145,30 @@ export interface HookPlace {
   holdPath?: string;
 }
 
+/** One hook call {@link hookListSteps} asks its driver to run. The driver sends back the exit code. */
+interface HookCall {
+  label: string;
+  argv: string[];
+  cwd: string;
+  env: Record<string, 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.
+ * The hook list as steps (#4334): it yields each call and takes its exit
+ * code back, so the sync and async runners share the targets, hold, outcome
+ * and other-gate handling and differ only in how they wait for a call.
  */
-export function runHookList(
-  at: HookPlace,
+function* hookListSteps(
+  at: Omit<HookPlace, "exec">,
   moment: OpWaveHookMoment,
   hooks: readonly OpWaveHook[] | undefined,
   runs: readonly OpWaveHookRun[],
   runsPath: string,
-  extraEnv: Record<string, string> = {},
-): HookListOutcome {
+  extraEnv: Record<string, string>,
+): Generator<HookCall, HookListOutcome, number> {
   const out: HookListOutcome = { holds: [], outcomes: [], otherGates: [] };
   if (!hooks || hooks.length === 0) return out;
-  const { name: specName, op, waveName, k, cwd, exec, log } = at;
+  const { name: specName, op, waveName, k, cwd, 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 };
@@ -170,14 +189,8 @@ export function runHookList(
       : [{ 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 code = yield { label, argv: call.argv, cwd, env: call.env };
       const base = { moment, name, ...(call.target ? { target: call.target } : {}), exit: code };
       if (code === 0) {
         out.outcomes.push({ ...base, outcome: "passed" });
@@ -204,6 +217,64 @@ export function runHookList(
   return out;
 }
 
+/** The exit code a call that did not start counts as, after its error is logged. */
+function didNotRun(call: HookCall, err: unknown, log: (line: string) => void): number {
+  log(`${call.label} did not run: ${err instanceof Error ? err.message : String(err)}`);
+  return 127;
+}
+
+/**
+ * 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 steps = hookListSteps(at, moment, hooks, runs, runsPath, extraEnv);
+  let step = steps.next();
+  while (!step.done) {
+    const call = step.value;
+    let code: number;
+    try {
+      code = at.exec(call.argv, call.cwd, call.env);
+    } catch (err) {
+      code = didNotRun(call, err, at.log);
+    }
+    step = steps.next(code);
+  }
+  return step.value;
+}
+
+/** {@link runHookList} with an exec that returns a promise (#4334). */
+export async function runHookListAsync(
+  at: Omit<HookPlace, "exec"> & { exec: OpWaveAsyncExec },
+  moment: OpWaveHookMoment,
+  hooks: readonly OpWaveHook[] | undefined,
+  runs: readonly OpWaveHookRun[],
+  runsPath: string,
+  extraEnv: Record<string, string> = {},
+): Promise<HookListOutcome> {
+  const steps = hookListSteps(at, moment, hooks, runs, runsPath, extraEnv);
+  let step = steps.next();
+  while (!step.done) {
+    const call = step.value;
+    let code: number;
+    try {
+      code = await at.exec(call.argv, call.cwd, call.env);
+    } catch (err) {
+      code = didNotRun(call, err, at.log);
+    }
+    step = steps.next(code);
+  }
+  return step.value;
+}
+
 /** 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. */
@@ -235,6 +306,22 @@ export interface StageHooksRun {
   holds: string[];
 }
 
+/** {@link RunStageHooksOptions} for {@link runStageHooksAsync} (#4334). */
+export interface RunStageHooksAsyncOptions extends Omit<RunStageHooksOptions, "exec"> {
+  /** Default: {@link spawnExecAsync}. */
+  exec?: OpWaveAsyncExec;
+}
+
+/** Where a stage runner's hooks run, without the exec. */
+function stagePlace(options: Omit<RunStageHooksOptions, "exec">): Omit<HookPlace, "exec"> {
+  return { name: options.name, op: options.op, waveName: options.wave, k: options.k ?? 0, cwd: options.cwd ?? process.cwd(), log: options.log ?? ((line: string) => console.error(line)), holdPath: options.holdFile };
+}
+
+/** A stage run's result: a hold on another gate counts as a plain hold. */
+function stageRun(out: HookListOutcome, name: string): StageHooksRun {
+  return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? name} / ${g.request.gate})`)] };
+}
+
 /**
  * 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`,
@@ -243,9 +330,17 @@ export interface StageHooksRun {
  * 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})`)] };
+  const place = { ...stagePlace(options), exec: options.exec ?? spawnExec };
+  return stageRun(runHookList(place, moment, hooks, options.runs, options.runsFile, options.env), options.name);
+}
+
+/**
+ * {@link runStageHooks} with an exec that returns a promise (#4334), so a
+ * product can run several stages' hooks side by side. The hooks of one call
+ * still run one after another. Give each concurrent call its own `holdFile`
+ * and `runsFile`.
+ */
+export async function runStageHooksAsync(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksAsyncOptions): Promise<StageHooksRun> {
+  const place = { ...stagePlace(options), exec: options.exec ?? spawnExecAsync };
+  return stageRun(await runHookListAsync(place, moment, hooks, options.runs, options.runsFile, options.env), options.name);
 }

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 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).
+    // About 50 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) and the approver filter (#4337).
     expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(52 * 1024);
   });
 });

package/src/pr-forge.ts

@@ -418,10 +418,16 @@ export interface PrForge {
    * 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.
+   * 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.
    */
-  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>;
@@ -433,6 +439,68 @@ export interface PrForge {
   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;
@@ -796,25 +864,38 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       return [...standing].filter(([, state]) => state === "APPROVED").map(([login]) => login).sort();
     },
     authors: authorsOf,
-    async prApproved(pr, head) {
+    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 }>();
+      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 } : {}) });
+        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 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)}`);
+      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 { 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) {
@@ -823,6 +904,9 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       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`);
@@ -1175,7 +1259,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       return [...new Set(logins)].sort();
     },
     authors: authorsOf,
-    async prApproved(mr, head) {
+    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);
@@ -1186,7 +1270,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       // 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 }>();
+      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);
@@ -1195,13 +1279,29 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         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 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 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)}`);
+      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) {

package/src/pr-requires.test.ts

@@ -42,6 +42,25 @@ describe("github", () => {
     expect(await changes.prApproved!(7, HEAD)).toEqual({ passed: false, reason: "carol asked for changes" });
   });
 
+  test("approved: forgeRule counts only writers, exclude leaves a login out, and the refusal says why (#4337)", async () => {
+    const reviews = [
+      { user: { login: "bob" }, state: "APPROVED", commit_id: HEAD },
+      { user: { login: "Carol" }, state: "APPROVED", commit_id: HEAD },
+      { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD },
+    ];
+    const f = forge({
+      [`GET ${repo}/pulls/7/reviews`]: reviews,
+      [`GET ${repo}/collaborators/bob/permission`]: { permission: "read", role_name: "triage" },
+      [`GET ${repo}/collaborators/Carol/permission`]: { permission: "write", role_name: "maintain" },
+    });
+    expect(await f.prApproved!(7, HEAD, { forgeRule: true })).toEqual({ passed: true, reason: "approved at aaaaaaaa by Carol" });
+    expect(await f.prApproved!(7, HEAD, { forgeRule: true, exclude: [{ login: "carol", reason: "carol asked for aaaaaaa" }] })).toEqual({
+      passed: false,
+      reason: "no reviewer other than its authors approved its head aaaaaaaa: carol asked for aaaaaaa; alice is one of its authors; bob has no write access",
+    });
+    expect((await f.prApproved!(7, HEAD, { exclude: ["bob"] })).reason).toBe("approved at aaaaaaaa by Carol");
+  });
+
   test("every check fails when the forge's head is another commit", async () => {
     const f = forge({ [`GET ${repo}/pulls/7`]: pull({ head: { ref: "f", sha: OTHER } }) });
     const r = await f.prMergeable!(7, HEAD);
@@ -89,11 +108,27 @@ describe("forgejo", () => {
     expect((await f.prApproved!(4, HEAD)).reason).toBe("dave asked for changes");
   });
 
+  test("approved: forgeRule counts an official review only, through checkPrRequires' approvers (#4337)", async () => {
+    const f = forge({ [`GET ${repo}/pulls/4/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD, official: false }, { user: { login: "erin" }, state: "APPROVED", commit_id: HEAD, official: true }] });
+    expect((await f.prApproved!(4, HEAD, { forgeRule: true })).reason).toBe("approved at aaaaaaaa by erin");
+    const out = await checkPrRequires(f, 4, HEAD, { only: ["approved"], approvers: { forgeRule: true, exclude: ["erin"] } });
+    expect(out[0]!.reason).toBe("no reviewer other than its authors approved its head aaaaaaaa: bob's review is not official; erin is excluded");
+  });
+
   test("undiverged: the pull request's merge base is the base branch's tip", async () => {
     expect((await forge({}).prUndiverged!(4, HEAD)).passed).toBe(true);
     expect((await forge({ [`GET ${repo}/pulls/4`]: pull({ merge_base: OTHER }) }).prUndiverged!(4, HEAD)).reason).toBe("aaaaaaaa does not contain main at bbbbbbbb");
   });
 
+  test("mergeable: a false while Forgejo still checks is pending, and passes once it settles (#4335)", async () => {
+    expect(await forge({ [`GET ${repo}/pulls/4`]: pull({ mergeable: false }) }).prMergeable!(4, HEAD)).toMatchObject({ passed: false, pending: true });
+    expect(await forge({ [`GET ${repo}/pulls/4`]: pull({ mergeable: false, draft: true }) }).prMergeable!(4, HEAD)).toEqual({ passed: false, reason: "it is a draft" });
+    let reads = 0;
+    const flips = forge({ [`GET ${repo}/pulls/4`]: () => pull({ mergeable: ++reads > 2 }), [`GET ${repo}/pulls/4/reviews`]: [], [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [{ context: "ci/test", status: "success" }] } });
+    const out = await checkPrRequires(flips, 4, HEAD, { wait: async () => {} });
+    expect(out.find((o) => o.name === "mergeable")).toEqual({ name: "mergeable", passed: true, reason: "it merges into main as it stands" });
+  });
+
   test("mergeable: no branch protection reading, and checks from the combined status alone", async () => {
     expect((await forge({ [`GET ${repo}/pulls/4`]: pull({ mergeable_state: "blocked" }) }).prMergeable!(4, HEAD)).passed).toBe(true);
     const f = forge({ [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [{ context: "ci/test", status: "success" }] } });
@@ -135,6 +170,23 @@ describe("gitlab", () => {
     expect((await h.prApproved!(3, HEAD)).reason).toBe("carol requested changes");
   });
 
+  test("approved: forgeRule reads each approver's access level, Developer by default (#4337)", async () => {
+    const at = "2026-10-01T11:00:00Z";
+    const f = forge({
+      [`GET ${project}/merge_requests/3/notes`]: [
+        { ...note("bob", "approved this merge request", at), author: { username: "bob", id: 5 } },
+        { ...note("dan", "approved this merge request", at), author: { username: "dan", id: 6 } },
+        { ...note("eve", "approved this merge request", at), author: { username: "eve", id: 7 } },
+      ],
+      [`GET ${project}/members/all/5`]: { access_level: 20 },
+      [`GET ${project}/members/all/6`]: { access_level: 40 },
+    });
+    expect((await f.prApproved!(3, HEAD, { forgeRule: true })).reason).toBe("approved after aaaaaaaa by dan");
+    expect((await f.prApproved!(3, HEAD, { forgeRule: true, minAccessLevel: 50 })).reason).toBe(
+      "no member other than its authors approved it after its latest push, aaaaaaaa: bob has access level 20, under 50; dan has access level 40, under 50; eve is not a member",
+    );
+  });
+
   test("mergeable and undiverged read the merge request", async () => {
     expect((await forge({}).prMergeable!(3, HEAD)).passed).toBe(true);
     expect(await forge({ [`GET ${project}/merge_requests/3`]: mr({ detailed_merge_status: "checking" }) }).prMergeable!(3, HEAD)).toMatchObject({ passed: false, pending: true });
@@ -175,6 +227,18 @@ describe("checkPrRequires", () => {
     expect(unmetRequires(out)).toBeNull();
   });
 
+  test("only: a check left out passes as not required and asks the forge nothing (#4336)", async () => {
+    const calls: string[] = [];
+    const ask = (name: string) => async () => (calls.push(name), { passed: false, reason: `${name} unmet` });
+    const forge = { kind: "github", prApproved: ask("approved"), prMergeable: ask("mergeable"), prUndiverged: ask("undiverged"), prChecksPassed: ask("checks") } as unknown as PrForge;
+    const out = await checkPrRequires(forge, 7, HEAD, { only: ["approved", "checks"], reads: 1 });
+    expect(calls).toEqual(["approved", "checks"]);
+    expect(out.map((o) => o.name)).toEqual([...PR_APPLY_REQUIRES]);
+    expect(out[1]).toEqual({ name: "mergeable", passed: true, reason: "not required" });
+    expect(unmetRequires(out)).toBe("approved: approved unmet; checks: checks unmet");
+    expect(unmetRequires(await checkPrRequires(forge, 7, HEAD, { only: [] }))).toBeNull();
+  });
+
   test("a client without a method, or a call that throws, is unmet", async () => {
     const forge = { kind: "gitlab", prApproved: async () => { throw new Error("401"); } } as unknown as PrForge;
     const out = await checkPrRequires(forge, 3, HEAD, { reads: 1 });