@intentius/chant 0.124.41 → 0.124.43

package/src/pr-requires.test.ts

@@ -0,0 +1,248 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the four
+ * PrForge methods on GitHub, Forgejo and GitLab, driven through a recording
+ * fake forge, and checkPrRequires over them.
+ */
+
+import { describe, expect, test } from "vitest";
+import { forgejoForge, githubForge, gitlabForge, type ForgeFetch, type PrForge } from "./pr-forge";
+import { checkPrRequires, PR_APPLY_REQUIRES, unmetRequires } from "./pr-requires";
+
+/** A fake forge: `routes` maps `METHOD path-without-query` to a body, a status, or a function of the query. */
+function fakeFetch(routes: Record<string, unknown | ((q: URLSearchParams) => unknown)>): ForgeFetch {
+  return async (url, init) => {
+    const u = new URL(url);
+    let found = routes[`${init.method} ${u.pathname}`];
+    if (typeof found === "function") found = (found as (q: URLSearchParams) => unknown)(u.searchParams);
+    if (found === undefined) return { ok: false, status: 404, text: async () => '{"message":"Not Found"}' };
+    if (typeof found === "number") return { ok: false, status: found, text: async () => "" };
+    return { ok: true, status: 200, text: async () => JSON.stringify(found) };
+  };
+}
+
+const HEAD = "a".repeat(40);
+const TIP = "b".repeat(40);
+const OTHER = "c".repeat(40);
+
+describe("github", () => {
+  const repo = "/repos/acme/infra";
+  const pull = (over: Record<string, unknown> = {}) => ({ number: 7, state: "open", user: { login: "alice" }, head: { ref: "f", sha: HEAD }, base: { ref: "main" }, mergeable: true, mergeable_state: "clean", ...over });
+  const forge = (routes: Record<string, unknown>) =>
+    githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t", fetch: fakeFetch({ [`GET ${repo}/pulls/7`]: pull(), [`GET ${repo}/pulls/7/commits`]: [{ author: { login: "alice" }, committer: { login: "alice" } }], ...routes }) });
+
+  test("approved: a reviewer other than the authors approved this head", async () => {
+    const f = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }] });
+    expect(await f.prApproved!(7, HEAD)).toEqual({ passed: true, reason: "approved at aaaaaaaa by bob" });
+  });
+
+  test("approved: an approval of an older head, the author's own, or a request for changes does not pass", async () => {
+    const older = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: OTHER }, { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD }] });
+    expect((await older.prApproved!(7, HEAD)).passed).toBe(false);
+    const changes = forge({ [`GET ${repo}/pulls/7/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }, { user: { login: "carol" }, state: "CHANGES_REQUESTED", commit_id: HEAD }] });
+    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);
+    expect(r.passed).toBe(false);
+    expect(r.reason).toContain("head is cccccccc, not aaaaaaaa");
+  });
+
+  test("mergeable: conflicts and branch protection refuse, an unknown answer is pending", async () => {
+    expect((await forge({}).prMergeable!(7, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable: false, mergeable_state: "dirty" }) }).prMergeable!(7, HEAD)).reason).toContain("conflicts with main");
+    expect((await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable_state: "blocked" }) }).prMergeable!(7, HEAD)).reason).toContain("branch protection");
+    expect(await forge({ [`GET ${repo}/pulls/7`]: pull({ mergeable: null }) }).prMergeable!(7, HEAD)).toMatchObject({ passed: false, pending: true });
+  });
+
+  test("undiverged: reads behind_by from the compare of the base branch with the head", async () => {
+    expect((await forge({ [`GET ${repo}/compare/main...${HEAD}`]: { behind_by: 0 } }).prUndiverged!(7, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${repo}/compare/main...${HEAD}`]: { behind_by: 2 } }).prUndiverged!(7, HEAD)).reason).toBe("aaaaaaaa is 2 commits behind main");
+  });
+
+  test("checks: statuses and check runs, the apply's own left out", async () => {
+    const statuses = (state: string) => ({ statuses: [{ context: "ci/test", state }, { context: "chant/apply", state: "failure" }] });
+    const runs = (conclusion: string | null, status = "completed") => ({ check_runs: [{ name: "lint", status, conclusion }] });
+    const f = (state: string, run: unknown) => forge({ [`GET ${repo}/commits/${HEAD}/status`]: statuses(state), [`GET ${repo}/commits/${HEAD}/check-runs`]: run });
+    expect(await f("success", runs("success")).prChecksPassed!(7, HEAD, ["chant/apply"])).toEqual({ passed: true, reason: "2 checks passed on aaaaaaaa" });
+    expect((await f("success", runs("success")).prChecksPassed!(7, HEAD)).reason).toBe("chant/apply failed on aaaaaaaa");
+    expect(await f("pending", runs("success")).prChecksPassed!(7, HEAD, ["chant/apply"])).toMatchObject({ passed: false, pending: true });
+    expect((await f("success", runs(null, "in_progress")).prChecksPassed!(7, HEAD, ["chant/apply"])).pending).toBe(true);
+    expect((await f("success", runs("failure")).prChecksPassed!(7, HEAD, ["chant/apply"])).reason).toBe("lint failed on aaaaaaaa");
+  });
+
+  test("checks: nothing reported is pending", async () => {
+    const f = forge({ [`GET ${repo}/commits/${HEAD}/status`]: { statuses: [] }, [`GET ${repo}/commits/${HEAD}/check-runs`]: { check_runs: [] } });
+    expect(await f.prChecksPassed!(7, HEAD)).toMatchObject({ passed: false, pending: true });
+  });
+});
+
+describe("forgejo", () => {
+  const repo = "/api/v1/repos/acme/infra";
+  const pull = (over: Record<string, unknown> = {}) => ({ number: 4, user: { login: "alice" }, head: { ref: "f", sha: HEAD }, base: { ref: "main" }, mergeable: true, merge_base: TIP, ...over });
+  const forge = (routes: Record<string, unknown>) =>
+    forgejoForge({ apiBase: "https://code.example/api/v1", repo: "acme/infra", host: "code.example", token: "t", fetch: fakeFetch({ [`GET ${repo}/pulls/4`]: pull(), [`GET ${repo}/pulls/4/commits`]: [], [`GET ${repo}/branches/main`]: { commit: { id: TIP } }, ...routes }) });
+
+  test("approved: Forgejo's REQUEST_CHANGES state refuses", async () => {
+    const f = forge({ [`GET ${repo}/pulls/4/reviews`]: [{ user: { login: "bob" }, state: "APPROVED", commit_id: HEAD }, { user: { login: "dave" }, state: "REQUEST_CHANGES" }] });
+    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" }] } });
+    expect(await f.prChecksPassed!(4, HEAD)).toEqual({ passed: true, reason: "1 check passed on aaaaaaaa" });
+  });
+});
+
+describe("gitlab", () => {
+  const project = "/api/v4/projects/9";
+  const mr = (over: Record<string, unknown> = {}) => ({ iid: 3, sha: HEAD, author: { username: "alice" }, target_branch: "main", detailed_merge_status: "mergeable", diverged_commits_count: 0, ...over });
+  const note = (who: string, body: string, at: string) => ({ system: true, author: { username: who }, body, created_at: at });
+  const forge = (routes: Record<string, unknown>) =>
+    gitlabForge({
+      apiBase: "https://gitlab.example/api/v4",
+      project: "9",
+      token: "t",
+      host: "gitlab.example",
+      fetch: fakeFetch({
+        [`GET ${project}/merge_requests/3`]: mr(),
+        [`GET ${project}/merge_requests/3/commits`]: [],
+        "GET /api/v4/user": { id: 1, username: "chant-bot" },
+        [`GET ${project}/merge_requests/3/versions`]: [{ created_at: "2026-10-01T10:00:00Z" }],
+        ...routes,
+      }),
+    });
+
+  test("approved: an approval after the latest push, not the token user's or the author's", async () => {
+    const f = forge({
+      [`GET ${project}/merge_requests/3/notes`]: [
+        note("erin", "approved this merge request", "2026-10-01T09:00:00Z"),
+        note("chant-bot", "approved this merge request", "2026-10-01T11:00:00Z"),
+        note("alice", "approved this merge request", "2026-10-01T11:00:00Z"),
+      ],
+    });
+    expect((await f.prApproved!(3, HEAD)).passed).toBe(false);
+    const g = forge({ [`GET ${project}/merge_requests/3/notes`]: [note("bob", "approved this merge request", "2026-10-01T11:00:00Z")] });
+    expect(await g.prApproved!(3, HEAD)).toEqual({ passed: true, reason: "approved after aaaaaaaa by bob" });
+    const h = forge({ [`GET ${project}/merge_requests/3/notes`]: [note("bob", "approved this merge request", "2026-10-01T11:00:00Z"), note("carol", "requested changes", "2026-10-01T12:00:00Z")] });
+    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 });
+    expect((await forge({ [`GET ${project}/merge_requests/3`]: mr({ has_conflicts: true, detailed_merge_status: "conflict" }) }).prMergeable!(3, HEAD)).reason).toContain("conflicts");
+    expect((await forge({}).prUndiverged!(3, HEAD)).passed).toBe(true);
+    expect((await forge({ [`GET ${project}/merge_requests/3`]: mr({ diverged_commits_count: 1 }) }).prUndiverged!(3, HEAD)).reason).toBe("aaaaaaaa is 1 commit behind main");
+  });
+
+  test("checks: each name's newest status, a job allowed to fail holding nothing back", async () => {
+    const f = forge({
+      [`GET ${project}/repository/commits/${HEAD}/statuses`]: [
+        { id: 1, name: "test", status: "failed" },
+        { id: 2, name: "test", status: "success" },
+        { id: 3, name: "flaky", status: "failed", allow_failure: true },
+        { id: 4, name: "apply", status: "running" },
+      ],
+    });
+    expect(await f.prChecksPassed!(3, HEAD, ["apply"])).toEqual({ passed: true, reason: "2 checks passed on aaaaaaaa" });
+    expect((await f.prChecksPassed!(3, HEAD)).pending).toBe(true);
+  });
+});
+
+describe("checkPrRequires", () => {
+  const ok = { passed: true, reason: "ok" };
+  test("asks each check once in order, and a pending one again until it settles", async () => {
+    let reads = 0;
+    const forge = {
+      kind: "github",
+      prApproved: async () => ok,
+      prMergeable: async () => (++reads < 3 ? { passed: false, pending: true, reason: "working it out" } : ok),
+      prUndiverged: async () => ok,
+      prChecksPassed: async (_pr: number, _head: string, ignore?: readonly string[]) => ({ passed: true, reason: `ignored ${ignore?.join(",")}` }),
+    } as unknown as PrForge;
+    const out = await checkPrRequires(forge, 7, HEAD, { ignore: ["chant/apply"], wait: async () => {} });
+    expect(out.map((o) => o.name)).toEqual([...PR_APPLY_REQUIRES]);
+    expect(reads).toBe(3);
+    expect(out[3]!.reason).toBe("ignored chant/apply");
+    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 });
+    expect(out.every((o) => !o.passed)).toBe(true);
+    expect(unmetRequires(out)).toBe("approved: could not ask gitlab: 401; mergeable: this gitlab client cannot say; undiverged: this gitlab client cannot say; checks: this gitlab client cannot say");
+  });
+});

package/src/pr-requires.ts

@@ -0,0 +1,93 @@
+/**
+ * The requires checks of an apply before merge (#4301, ws-106): the pull
+ * request is approved, mergeable, undiverged and its checks passed, each
+ * asked of the forge through its {@link PrForge} method. All four must pass.
+ *
+ * The checks are terragucci's `apply.requires` (comment-apply.ts:781-860 at
+ * INTENTIUS/terragucci e6cb431). A product may leave one out with `only`
+ * (#4336); chant's own `pr-apply --before-merge` passes no `only`, so it asks
+ * all four, as ws-106 requires. A check the
+ * forge has not settled, such as GitHub working out whether a pull request
+ * can merge, is asked again a few times before it counts as unmet.
+ *
+ * Like ./pr-forge.ts this imports nothing beyond it, so a product bundles it
+ * without the TypeScript toolchain.
+ */
+import type { PrApproverFilter, PrForge, PrRequireResult } from "./pr-forge";
+
+/** The four checks, in the order they run and the report lists them. */
+export const PR_APPLY_REQUIRES = ["approved", "mergeable", "undiverged", "checks"] as const;
+
+export type PrApplyRequire = (typeof PR_APPLY_REQUIRES)[number];
+
+/** One check as the pull-request report's `beforeMerge.requires` holds it. */
+export interface PrRequireOutcome extends PrRequireResult {
+  name: PrApplyRequire;
+}
+
+export interface PrRequiresOptions {
+  /**
+   * The checks to ask (#4336). One left out passes with the reason "not
+   * required" and makes no forge call. Default: all four.
+   */
+  only?: readonly PrApplyRequire[];
+  /** Who counts as an approver for `approved` (#4337). Default: anyone other than the authors. */
+  approvers?: PrApproverFilter;
+  /** Status names the `checks` require leaves out: the apply's own. */
+  ignore?: readonly string[];
+  /** How many times a pending check is asked in all. Default 5. */
+  reads?: number;
+  /** The wait between reads. Default 3 seconds. */
+  wait?: (ms: number) => Promise<void>;
+}
+
+const READS = 5;
+const WAIT_MS = 3000;
+
+/**
+ * Ask `forge` each of the four checks for pull request `pr` at `head`. A
+ * forge client without a method, or a call that throws, gives an unmet
+ * check with the reason, so nothing applies on a check nobody made.
+ */
+export async function checkPrRequires(forge: PrForge, pr: number, head: string, opts: PrRequiresOptions = {}): Promise<PrRequireOutcome[]> {
+  const wait = opts.wait ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const reads = Math.max(1, opts.reads ?? READS);
+  const ask: Record<PrApplyRequire, (() => Promise<PrRequireResult>) | undefined> = {
+    approved: forge.prApproved ? () => forge.prApproved!(pr, head, opts.approvers) : undefined,
+    mergeable: forge.prMergeable ? () => forge.prMergeable!(pr, head) : undefined,
+    undiverged: forge.prUndiverged ? () => forge.prUndiverged!(pr, head) : undefined,
+    checks: forge.prChecksPassed ? () => forge.prChecksPassed!(pr, head, opts.ignore ?? []) : undefined,
+  };
+  const out: PrRequireOutcome[] = [];
+  const asked = new Set<PrApplyRequire>(opts.only ?? PR_APPLY_REQUIRES);
+  for (const name of PR_APPLY_REQUIRES) {
+    if (!asked.has(name)) {
+      out.push({ name, passed: true, reason: "not required" });
+      continue;
+    }
+    const call = ask[name];
+    if (!call) {
+      out.push({ name, passed: false, reason: `this ${forge.kind} client cannot say` });
+      continue;
+    }
+    let result: PrRequireResult;
+    for (let read = 1; ; read++) {
+      try {
+        result = await call();
+      } catch (err) {
+        result = { passed: false, reason: `could not ask ${forge.kind}: ${err instanceof Error ? err.message : String(err)}` };
+      }
+      if (result.passed || !result.pending || read >= reads) break;
+      await wait(WAIT_MS);
+    }
+    out.push({ name, ...result });
+  }
+  return out;
+}
+
+/** The unmet checks as one line, or null when all four passed. */
+export function unmetRequires(outcomes: readonly PrRequireOutcome[]): string | null {
+  const unmet = outcomes.filter((o) => !o.passed);
+  if (unmet.length === 0) return null;
+  return unmet.map((o) => `${o.name}: ${o.reason}`).join("; ");
+}

package/src/review-agent-bundle.test.ts

@@ -0,0 +1,35 @@
+/**
+ * The review agent bundles alone (#4299): a product such as terragucci
+ * imports `@intentius/chant/op/activities/review-agent` into one bundled
+ * file, so it must not reach predict-behaviour's estate code. This bundles
+ * the module and reads esbuild's list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the review-agent bundle", () => {
+  test("holds the review agent, the note it posts through and nothing else", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "activities", "review-agent.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/op/activities/forge-pull-request.ts",
+      "packages/core/src/op/activities/gh-host.ts",
+      "packages/core/src/op/activities/pr-refs.ts",
+      "packages/core/src/op/activities/reconcile.ts",
+      "packages/core/src/op/activities/review-agent.ts",
+      "packages/core/src/pr-forge.ts",
+    ]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(96 * 1024);
+  });
+});

package/src/stage-hooks-bundle.test.ts

@@ -0,0 +1,38 @@
+/**
+ * The stage-hook runner bundles alone (#4288): a product that runs
+ * `ci.hooks` around its own stages imports
+ * `@intentius/chant/op/stage-hooks` into one bundled file, without the wave
+ * loop, the gate or the ledger. This bundles the module and reads esbuild's
+ * list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the stage-hooks bundle", () => {
+  test("holds the hook runner and the Op waves spec, and no wave loop, gate or ledger", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "stage-hooks.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/lifecycle/gate-seal.ts",
+      "packages/core/src/notify-verify.ts",
+      "packages/core/src/notify.ts",
+      "packages/core/src/op/gate-point.ts",
+      "packages/core/src/op/gate-quorum.ts",
+      "packages/core/src/op/op-waves.ts",
+      "packages/core/src/op/stage-hooks.ts",
+      "packages/core/src/wave-layout.ts",
+    ]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(48 * 1024);
+  });
+});

package/src/workspace/checks/ci-workflow.test.ts

@@ -120,6 +120,15 @@ describe("ci.workflow (WSP151)", () => {
     expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": noRecord })))).toEqual([["ci-workflow-pipeline-missing", null]]);
   });
 
+  test("apply-before-merge needs a job that applies before merge, and the other workflows refuse one (#4301)", async () => {
+    const early = `${PIPELINE}  apply:\n    steps:\n      - run: chant ci run apply --in-place --base "$BASE_SHA" --pr "$PR_NUMBER" --apply-before-merge --env prod --gate pr-apply --forge github\n`;
+    const decl = declaration({ ci: { workflow: "apply-before-merge", green: green() } });
+    expect(await found(repo(complete({ "chant.workspace.json": decl })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": early })))).toEqual([]);
+    expect(await found(repo(complete({ ".github/workflows/chant-pr.yml": early })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    expect(workflowOf({ ci: { green: null, reportUrl: null, workflow: "apply-before-merge" } } as never, null)).toBe("apply-before-merge");
+  });
+
   test("a member's own workflow wins, and a top-level workflow skips members that don't build with chant", async () => {
     const root = repo({
       ...complete(),

package/src/workspace/checks/ci-workflow.ts

@@ -14,7 +14,7 @@
 
 import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
 import type { CiWorkflow, Member } from "../declaration";
-import { appliesOnMerge, STUB_MARKER, workflowOf, type CiWorkflowCode } from "../ci-workflow";
+import { appliesBeforeMerge, appliesOnMerge, STUB_MARKER, workflowOf, type CiWorkflowCode } from "../ci-workflow";
 import { matchesCheckRun } from "../ci-green";
 import { staticPromotionOrder } from "../promotion-order";
 import { joinPath } from "../tree";
@@ -27,6 +27,8 @@ const memberDir = (dir: string) => (dir === "." ? "" : dir);
 const PLAN = /\bci\s+run\s+plan\b|\bcomponents\s+pr-plan\b/;
 const RECORD = /\bci\s+run\s+record\b|\bcomponents\s+pr-record\b/;
 const APPLY = /\bci\s+run\s+apply\b|\bcomponents\s+pr-apply\b/;
+/** An apply before merge (#4301): `pr-apply --before-merge`, or `ci run apply --apply-before-merge`. */
+const BEFORE_MERGE = /--(?:apply-)?before-merge\b/;
 const TICK = /\bci\s+tick\b/;
 const PUBLISH = /\brelease\s+publish\b/;
 
@@ -113,16 +115,28 @@ export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
       if (missing.length > 0) {
         finding("ci-workflow-pipeline-missing", `no pipeline file runs ${missing.join(", ")}; generate them with chant build --components --generate <forge> --pr-loop and chant ci workflow`);
       }
+      // #4301: an apply before merge is its own job, allowed only under apply-before-merge.
+      const beforeMerge = under.some((u) => appliesBeforeMerge(u.workflow)) || appliesBeforeMerge(d.ci?.workflow ?? null);
+      const earlyLines = commandLines(ctx, APPLY).filter((c) => BEFORE_MERGE.test(c.text));
+      if (!beforeMerge) {
+        for (const l of earlyLines) {
+          finding("ci-workflow-pipeline-differs", `${l.path} applies before merge, and no member's workflow is apply-before-merge; regenerate without --apply-before-merge, or set ci.workflow to apply-before-merge`, { treeFile: l.path, line: l.line });
+        }
+      } else if (earlyLines.length === 0 && has(PLAN)) {
+        const l = commandLines(ctx, PLAN)[0]!;
+        finding("ci-workflow-pipeline-differs", `${l.path} has no job that applies before merge, and the workflow is apply-before-merge; regenerate with --apply-before-merge`, { treeFile: l.path, line: l.line });
+      }
+      const mergeApply = (l: { text: string }) => !BEFORE_MERGE.test(l.text);
       if (!applyOnMerge) {
-        for (const l of commandLines(ctx, APPLY)) {
+        for (const l of commandLines(ctx, APPLY).filter(mergeApply)) {
           finding("ci-workflow-pipeline-differs", `${l.path} applies on merge, and the workflow is trunk-curated, where a merge records the plan and deploys nothing; regenerate without --apply-on-merge, or set ci.workflow to trunk-curated+apply-on-merge`, { treeFile: l.path, line: l.line });
         }
-      } else if (!has(APPLY) && has(RECORD)) {
+      } else if (!commandLines(ctx, APPLY).some(mergeApply) && has(RECORD)) {
         const l = commandLines(ctx, RECORD)[0]!;
         finding("ci-workflow-pipeline-differs", `${l.path} records on merge, and the workflow is trunk-curated+apply-on-merge; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
       } else {
         // #4168 step 9: an apply measured from a push's base applies each merge; the workflow applies green commits.
-        for (const l of commandLines(ctx, APPLY).filter((c) => /--base\b/.test(c.text) || (/\bcomponents\s+pr-apply\b/.test(c.text) && !/--green\b/.test(c.text)))) {
+        for (const l of commandLines(ctx, APPLY).filter(mergeApply).filter((c) => /--base\b/.test(c.text) || (/\bcomponents\s+pr-apply\b/.test(c.text) && !/--green\b/.test(c.text)))) {
           finding("ci-workflow-pipeline-differs", `${l.path} applies each merge, and under trunk-curated+apply-on-merge the apply applies the newest green commit; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
         }
       }

package/src/workspace/ci-init.ts

@@ -37,7 +37,7 @@ import { formatError, formatSuccess } from "../cli/format";
 import { parseYAMLDocument } from "../yaml";
 import { CI_WORKFLOW_CHECKS } from "./checks/ci-workflow";
 import type { WorkspaceDiagnostic } from "./checks";
-import { CI_WORKFLOWS, STUB_MARKER, appliesOnMerge } from "./ci-workflow";
+import { CI_WORKFLOWS, STUB_MARKER, appliesBeforeMerge, appliesOnMerge } from "./ci-workflow";
 
 export { STUB_MARKER };
 import { CI_GREEN_WORKFLOW_FILE, jobCheckRuns, readWorkflowSources, workflowsHolding } from "./ci-green-workflow";
@@ -48,7 +48,7 @@ import { SECURITY_GROUPS, type SecurityGroup } from "./security";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { RELEASE_WORKFLOW_FORGES, type ReleaseWorkflowForge } from "./release-workflow";
 
-const USAGE = "chant ci init --workflow trunk-curated|trunk-curated+apply-on-merge [--forge github|gitlab|forgejo] [--security <group>]... [--yes]";
+const USAGE = "chant ci init --workflow trunk-curated|trunk-curated+apply-on-merge|apply-before-merge [--forge github|gitlab|forgejo] [--security <group>]... [--yes]";
 
 
 /** The environments a config with none is given. */
@@ -280,11 +280,12 @@ export function proposeCiInit(root: string, options: CiInitOptions): CiInitPropo
     if (reported("ci-workflow-pipeline-missing") || reported("ci-workflow-pipeline-differs")) {
       for (const m of releasing) {
         const env = firstEnv.get(m.name);
+        const workflow = m.ciWorkflow ?? proposed.ci!.workflow!;
         commands.push({
           cwd: memberDir(m.dir) || ".",
           // The root member builds alone: at a workspace root, chant build refuses without --root-only (WSP000).
-          args: ["build", "--components", "--generate", forge, "--pr-loop", ...(m.dir === "." ? ["--root-only"] : []), ...(env ? ["--env", env] : []), ...(appliesOnMerge(m.ciWorkflow ?? proposed.ci!.workflow!) ? ["--apply-on-merge"] : [])],
-          why: `the pull-request pipeline for ${m.name}: plan on a pull request, ${appliesOnMerge(m.ciWorkflow ?? proposed.ci!.workflow!) ? "apply" : "record"} on merge`,
+          args: ["build", "--components", "--generate", forge, "--pr-loop", ...(m.dir === "." ? ["--root-only"] : []), ...(env ? ["--env", env] : []), ...(appliesOnMerge(workflow) ? ["--apply-on-merge"] : []), ...(appliesBeforeMerge(workflow) ? ["--apply-before-merge"] : [])],
+          why: `the pull-request pipeline for ${m.name}: plan on a pull request, ${appliesBeforeMerge(workflow) ? "apply on request before merge, record" : appliesOnMerge(workflow) ? "apply" : "record"} on merge`,
         });
       }
       if (forge === "github") {

package/src/workspace/ci-run.ts

@@ -1040,13 +1040,14 @@ export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptio
     ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
     ...(args.waveGate ? { waveGate: args.waveGate } : {}),
     ...(args.requireReview === true ? { requireReview: true } : {}),
+    ...(args.applyBeforeMerge ? { applyBeforeMerge: true } : {}),
   };
 }
 
 const USAGE =
   "chant ci run plan|record|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
   "[--gate <name>] [--wave-gate <name>] [--wave <k>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
-  "[--pr-build] [--pr-build-command <line>] [--require-review] [--no-status] [--status-url <url template>] " +
+  "[--pr-build] [--pr-build-command <line>] [--require-review] [--apply-before-merge] [--no-status] [--status-url <url template>] " +
   "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --at <sha> | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/src/workspace/ci-workflow-at.ts

@@ -0,0 +1,23 @@
+/**
+ * `ci.workflow` read at base (#4301, ws-106), as `ci.locks` is
+ * (./ci-locks.ts): the target branch's tip, so a pull request that sets
+ * `apply-before-merge` in its own copy of the declaration gets nothing from it.
+ */
+import type { CiWorkflow } from "./declaration";
+import { workflowOf } from "./ci-workflow";
+import { memberAtCwd } from "./security";
+import { scopeSource } from "./write-scope";
+
+/**
+ * The workflow the member holding `cwd` follows, or `member` when given:
+ * its own `ci.workflow`, else the top level's, read at `at` when given, else
+ * at base, else from the working tree. Null outside a workspace and when
+ * neither sets one.
+ */
+export function ciWorkflowAt(cwd: string, at?: string, member?: string): CiWorkflow | null {
+  const source = scopeSource(cwd, at);
+  const d = source.declaration;
+  if (!d) return null;
+  const name = member ?? memberAtCwd(source, cwd);
+  return workflowOf(d, d.members.find((m) => m.name === name) ?? null);
+}

package/src/workspace/ci-workflow.ts

@@ -7,6 +7,8 @@
  * from a green commit and promoted through the member's environments, gated
  * in the last (4.2). `trunk-curated+apply-on-merge` is the same, and each
  * newest green commit is also applied (section 5, step 9).
+ * `apply-before-merge` (#4301, ws-106) is `trunk-curated`, and a person may
+ * also apply an open pull request's plan from its head before it merges.
  *
  * A workflow requires no security group: those are opt-in on their own
  * (./security.ts). `chant workspace check` reports what a member under a
@@ -19,13 +21,22 @@ import type { CiWorkflow, Declaration, Member } from "./declaration";
 /** The marker a component stub `chant ci init` writes carries until someone fills it in. WSP151 reports a member whose only components carry it. */
 export const STUB_MARKER = "TODO(chant ci init)";
 
-export const CI_WORKFLOWS = ["trunk-curated", "trunk-curated+apply-on-merge"] as const satisfies readonly CiWorkflow[];
+export const CI_WORKFLOWS = ["trunk-curated", "trunk-curated+apply-on-merge", "apply-before-merge"] as const satisfies readonly CiWorkflow[];
 
 /** Whether `workflow` turns the apply on merge back on. */
 export function appliesOnMerge(workflow: CiWorkflow): boolean {
   return workflow === "trunk-curated+apply-on-merge";
 }
 
+/**
+ * Whether `workflow` lets an open pull request's plan apply from its head
+ * before it merges (#4301, ws-106). Only `apply-before-merge` does, so with
+ * no workflow or either trunk-curated one nothing applies before merge.
+ */
+export function appliesBeforeMerge(workflow: CiWorkflow | null): boolean {
+  return workflow === "apply-before-merge";
+}
+
 /** The workflow `member` follows: its own `ci.workflow`, else the top level's, else null. */
 export function workflowOf(declaration: Pick<Declaration, "ci">, member: Pick<Member, "ciWorkflow"> | null): CiWorkflow | null {
   return member?.ciWorkflow ?? declaration.ci?.workflow ?? null;
@@ -56,7 +67,7 @@ export const CI_WORKFLOW_REQUIREMENTS = [
   { code: "ci-workflow-no-environments", requirement: "the member's `chant.config.ts` declares `environments`, the promotion order", fix: "`environments` in `chant.config.ts`", perMember: true },
   { code: "ci-workflow-ungated-env", requirement: "each component has a gate, so a promote to the last environment waits on an approval", fix: "a `gate()` step in the component", perMember: true },
   { code: "ci-workflow-pipeline-missing", requirement: "a pipeline file runs the plan job, the record job (`ci run record`) and `chant ci tick`", fix: "`chant build --components --generate <forge> --pr-loop` and `chant ci workflow`", perMember: false },
-  { code: "ci-workflow-pipeline-differs", requirement: "the pipeline matches the workflow: no apply job under `trunk-curated`, and under `trunk-curated+apply-on-merge` an apply job that applies the newest green commit, not each merge", fix: "regenerate the pull-request pipeline, with `--apply-on-merge` only under apply on merge", perMember: false },
+  { code: "ci-workflow-pipeline-differs", requirement: "the pipeline matches the workflow: no apply job under `trunk-curated`, and under `trunk-curated+apply-on-merge` an apply job that applies the newest green commit, not each merge; a job that applies before merge only, and always, under `apply-before-merge`", fix: "regenerate the pull-request pipeline, with `--apply-on-merge` only under apply on merge and `--apply-before-merge` only under apply before merge", perMember: false },
   { code: "ci-workflow-publish-missing", requirement: "a pipeline file runs `chant release publish`", fix: "`chant release workflow`", perMember: false },
 ] as const satisfies readonly CiWorkflowRequirement[];
 

package/src/workspace/declaration.schema.json

@@ -1718,8 +1718,8 @@
       "additionalProperties": false
     },
     "ciWorkflow": {
-      "enum": ["trunk-curated", "trunk-curated+apply-on-merge"],
-      "description": "A prescribed delivery workflow (#4168). trunk-curated: a merge records the plan and deploys nothing; releases are cut from green commits and promoted through each member's environments, gated in the last. trunk-curated+apply-on-merge: the same, with the apply on merge turned back on. chant workspace check reports what a member under one still lacks (WSP151), and chant ci init writes it. At the top level for every member, or on a member, which wins. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer."
+      "enum": ["trunk-curated", "trunk-curated+apply-on-merge", "apply-before-merge"],
+      "description": "A prescribed delivery workflow (#4168). trunk-curated: a merge records the plan and deploys nothing; releases are cut from green commits and promoted through each member's environments, gated in the last. trunk-curated+apply-on-merge: the same, with the apply on merge turned back on. apply-before-merge (#4301, ws-106): the same as trunk-curated, and a person may also apply an open pull request's plan from its head under its gate, once it is approved, mergeable, undiverged and its checks passed (chant components pr-apply --before-merge); added by chant 0.124.42, so a declaration that uses it sets minReader to 0.124.42 or newer. chant workspace check reports what a member under one still lacks (WSP151), and chant ci init writes it. At the top level for every member, or on a member, which wins. Added in schema 1 by chant 0.124.34, so a declaration that uses it sets minReader to 0.124.34 or newer."
     },
     "ciHooks": {
       "type": "object",