@intentius/chant 0.124.7 → 0.124.9

package/src/op/op-waves.ts

@@ -53,9 +53,21 @@
  * apply; like the policy they are read from the spec at the base commit, and
  * one whose `onFailure` is `approve` holds the wave for an approval whatever
  * its policy says.
+ *
+ * ## A gate that asks a decision point (#3836)
+ *
+ * With `point` (on the spec, or on a wave, whose own wins), read at base like
+ * the policy, a wave that needs an approval asks that workspace decision
+ * point instead of reading the ledger for a `chant approve`, the way an Op
+ * gate with a `point` does (#3170): `gate.planDigest` is the wave's set
+ * digest, so each plan is its own question. An open question waits (exit 3,
+ * the pending fact cites it), an answer the gate passes on records the
+ * resolution that cites it and the wave goes on, and any other answer refuses
+ * the wave (exit 8). See `./op-waves-run.ts`.
  */
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
+import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 
 /**
@@ -92,6 +104,40 @@ export const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[] = ["ledger", "
 /** What a failing hook does: fail the wave, or hold it for an approval of its set digest. */
 export type OpWaveHookFailure = "fail" | "approve";
 
+/**
+ * The decision point a wave's gate asks (#3836): a point's name, or `{ name,
+ * inputs?, pass?, store?, timeout? }` as an Op gate's `point` takes, plus the
+ * pending fact's `timeout` (default 48h). The point must declare the input
+ * `gate.planDigest`, which is the wave's set digest.
+ */
+export type OpWavePoint = GatePoint & {
+  /** How long the pending fact that cites an open question stands, such as `"48h"`. */
+  timeout?: string;
+};
+
+/** A wave's or a spec's `point` as an {@link OpWavePoint}, or undefined when it names none. */
+export function opWavePointOf(point: string | OpWavePoint | undefined): OpWavePoint | undefined {
+  if (point === undefined) return undefined;
+  return typeof point === "string" ? { name: point } : point;
+}
+
+/** What is wrong with a wave's `point`, empty when nothing is (#3836). */
+export function opWavePointProblems(point: unknown): string[] {
+  if (point !== null && typeof point === "object" && !Array.isArray(point) && "timeout" in point) {
+    const { timeout, ...rest } = point as Record<string, unknown>;
+    const problems = gatePointProblems(rest);
+    if (typeof timeout !== "string" || !/^(\d+(ms|s|m|h|d))+$/.test(timeout)) problems.push("`point.timeout` is a duration such as \"48h\"");
+    return problems;
+  }
+  return gatePointProblems(point);
+}
+
+/** The point wave `name`'s gate asks (#3836): the wave's own, else the spec's, else none. */
+export function opWavePointAt(spec: Pick<OpWavesSpec, "point" | "waves">, name: string): OpWavePoint | undefined {
+  const wave = spec.waves.find((w) => w.name === name);
+  return opWavePointOf(wave?.point ?? spec.point);
+}
+
 export const OP_WAVE_HOOK_FAILURES: readonly OpWaveHookFailure[] = ["fail", "approve"];
 
 /** One stage hook (#3762): a command run before or after a wave's plan or apply. */
@@ -181,6 +227,11 @@ export interface OpWave {
    * Like `gate`, the runner reads it from the spec file at the base commit.
    */
   approval?: GateApprovalSource;
+  /**
+   * The decision point this wave's gate asks (#3836), in place of the spec's.
+   * Read at base like `gate`. See {@link OpWavesSpec.point}.
+   */
+  point?: string | OpWavePoint;
   /**
    * Split the wave into a deciding job and this many share jobs, each
    * applying a slice of the runs. Default 1: one job plans, decides and
@@ -266,6 +317,15 @@ export interface OpWavesSpec {
    * the rules (`@intentius/chant/override-gate`).
    */
   override?: OpWavesOverride;
+  /**
+   * The decision point every wave's gate asks (#3836), unless a wave names its
+   * own. Read at the base commit, like the policy: a wave that needs an
+   * approval asks the point with `gate.planDigest` set to its set digest, and
+   * only an answer the point's `pass` names (default yes) for that digest
+   * lets it apply. `chant approve` does not pass such a gate, and the wave's
+   * `approval` mode does not apply: the point's deciders and quorum decide.
+   */
+  point?: string | OpWavePoint;
   waves: OpWave[];
   /**
    * A scheduled job that starts again a wave job whose approval has arrived
@@ -442,6 +502,10 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (typeof value !== "string" || value.trim() === "") throw new Error(`${where}: override.overriders must be a path, such as ".chant/overriders".`);
     }
   }
+  if (spec.point !== undefined) {
+    const problems = opWavePointProblems(spec.point);
+    if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
+  }
   if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean") throw new Error(`${where}: neverOverMcp must be true or false.`);
   if (spec.notify !== undefined) {
     const problem = notifyConfigProblem(spec.notify, "notify");
@@ -461,6 +525,10 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       throw new Error(`${where}: wave "${wave.name}" has approval "${wave.approval}"; use ${GATE_APPROVAL_SOURCES.join(", ")}.`);
     }
     assertOpWaveHooks(`${where}, wave "${wave.name}"`, wave.hooks);
+    if (wave.point !== undefined) {
+      const problems = opWavePointProblems(wave.point);
+      if (problems.length > 0) throw new Error(`${where}: wave "${wave.name}": ${problems.join("; ")}.`);
+    }
     if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
     if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
     if (wave.discover) {

package/src/pr-forge.test.ts

@@ -824,6 +824,64 @@ describe("pull requests over REST (#3798)", () => {
     expect(l.calls.map((c) => c.body)).toEqual([{ description: "d" }, { add_labels: "minor,breaking" }]);
   });
 
+  test("Forgejo's 404 on the pull list of a just-pushed empty repository is no pull request (#3845)", async () => {
+    const empty = fakeFetch({ "GET /api/v1/repos/acme/infra": { default_branch: "main" } });
+    expect(await forgejoForge({ ...fjOpts, fetch: empty.fetch }).findPullRequest("chant/x")).toBeUndefined();
+    // A repository that is really missing 404s on its own read, and that still throws.
+    const gone = fakeFetch({});
+    await expect(forgejoForge({ ...fjOpts, fetch: gone.fetch }).findPullRequest("chant/x")).rejects.toThrow(/404/);
+    // GitHub's list 404 stays an error.
+    await expect(githubForge({ ...gh, fetch: fakeFetch({}).fetch }).findPullRequest("chant/x")).rejects.toThrow(/404/);
+  });
+
+  const answering = (status: number, body: unknown, calls: Call[] = []): ForgeFetch => async (url, init) => {
+    calls.push({ method: init.method, url, headers: init.headers, ...(init.body ? { body: JSON.parse(init.body) } : {}) });
+    return { ok: status < 400, status, text: async () => (body === undefined ? "" : JSON.stringify(body)) };
+  };
+
+  test("mergePullRequest merges only at the reviewed sha on GitHub", async () => {
+    const f = fakeFetch({
+      "PUT /repos/acme/infra/pulls/5/merge": { merged: true, sha: "m1" },
+      "GET /repos/acme/infra/pulls/5": { number: 5, head: { ref: "chant/x", repo: { full_name: "acme/infra" } } },
+      "DELETE /repos/acme/infra/git/refs/heads/chant/x": null,
+    });
+    const r = await githubForge({ ...gh, fetch: f.fetch }).mergePullRequest(5, { sha: SHA, method: "squash", title: "t", message: "m", deleteBranch: true });
+    expect(r).toEqual({ merged: true, sha: "m1" });
+    expect(f.calls[0].body).toEqual({ sha: SHA, merge_method: "squash", commit_title: "t", commit_message: "m" });
+    expect(f.calls.map((c) => c.method)).toEqual(["PUT", "GET", "DELETE"]);
+    const calls: Call[] = [];
+    const moved = await githubForge({ ...gh, fetch: answering(409, { message: "Head branch was modified. Review and try the merge again." }, calls) }).mergePullRequest(5, { sha: SHA });
+    expect(moved).toEqual({ merged: false, reason: "Head branch was modified. Review and try the merge again." });
+    expect(calls[0].body).toEqual({ sha: SHA, merge_method: "merge" });
+    const blocked = await githubForge({ ...gh, fetch: answering(405, { message: "Required status check is expected." }) }).mergePullRequest(5, { sha: SHA });
+    expect(blocked.merged).toBe(false);
+    await expect(githubForge({ ...gh, fetch: answering(401, { message: "Bad credentials" }) }).mergePullRequest(5, { sha: SHA })).rejects.toThrow(/401/);
+  });
+
+  test("mergePullRequest on Forgejo sends head_commit_id and reads the merge commit back", async () => {
+    const f = fakeFetch({
+      "POST /api/v1/repos/acme/infra/pulls/5/merge": null,
+      "GET /api/v1/repos/acme/infra/pulls/5": { number: 5, merge_commit_sha: "m2" },
+    });
+    const r = await forgejoForge({ ...fjOpts, fetch: f.fetch }).mergePullRequest(5, { sha: SHA, method: "rebase", title: "t", message: "m", deleteBranch: true });
+    expect(r).toEqual({ merged: true, sha: "m2" });
+    expect(f.calls[0].body).toEqual({ Do: "rebase", head_commit_id: SHA, MergeTitleField: "t", MergeMessageField: "m", delete_branch_after_merge: true });
+    const moved = await forgejoForge({ ...fjOpts, fetch: answering(409, { message: "head commit id does not match" }) }).mergePullRequest(5, { sha: SHA });
+    expect(moved).toEqual({ merged: false, reason: "head commit id does not match" });
+    expect((await forgejoForge({ ...fjOpts, fetch: answering(405, undefined) }).mergePullRequest(5, { sha: SHA })).merged).toBe(false);
+  });
+
+  test("mergePullRequest on GitLab passes sha and squash, and refuses rebase", async () => {
+    const f = fakeFetch({ "PUT /api/v4/projects/group%2Finfra/merge_requests/7/merge": { state: "merged", merge_commit_sha: "m3" } });
+    const g = gitlabForge({ ...gl, fetch: f.fetch });
+    expect(await g.mergePullRequest(7, { sha: SHA, method: "squash", title: "t", message: "m", deleteBranch: true })).toEqual({ merged: true, sha: "m3" });
+    expect(f.calls[0].body).toEqual({ sha: SHA, squash: true, squash_commit_message: "t\n\nm", merge_commit_message: "t\n\nm", should_remove_source_branch: true });
+    const moved = await gitlabForge({ ...gl, fetch: answering(409, { message: "SHA does not match HEAD of source branch" }) }).mergePullRequest(7, { sha: SHA });
+    expect(moved).toEqual({ merged: false, reason: "SHA does not match HEAD of source branch" });
+    expect((await gitlabForge({ ...gl, fetch: answering(405, { message: "Branch cannot be merged" }) }).mergePullRequest(7, { sha: SHA })).merged).toBe(false);
+    await expect(g.mergePullRequest(7, { sha: SHA, method: "rebase" })).rejects.toThrow(/rebase/);
+  });
+
   test("a repository with no default branch is refused by name", async () => {
     const { fetch } = fakeFetch({ "GET /api/v1/repos/acme/infra": {} });
     await expect(forgejoForge({ ...fjOpts, fetch }).openPullRequest({ head: "h", title: "t", body: "b" })).rejects.toThrow(/no default branch.*pass base/);

package/src/pr-forge.ts

@@ -212,6 +212,48 @@ export interface PullRequest {
   base?: string;
 }
 
+/** What {@link PrForge.mergePullRequest} merges, and how. */
+export interface MergeOptions {
+  /** The head commit the caller reviewed. The merge happens only while the pull request's head is still this commit. */
+  sha: string;
+  /** Default `merge`. GitLab has no one-call rebase merge, so `rebase` is refused there. */
+  method?: "merge" | "squash" | "rebase";
+  /** The merge (squash) commit's title. */
+  title?: string;
+  /** The merge (squash) commit's message body. */
+  message?: string;
+  /** Delete the head branch after a merge. A failure to delete does not undo the merge. */
+  deleteBranch?: boolean;
+}
+
+/** The outcome of {@link PrForge.mergePullRequest}. */
+export interface MergeResult {
+  merged: boolean;
+  /** The commit the merge produced, when the forge says. */
+  sha?: string;
+  /** Why it was not merged: the head moved, a conflict, a failing check, a required review. */
+  reason?: string;
+}
+
+/** Statuses a forge answers a refused merge with: not allowed, head moved, conflict, invalid. */
+const MERGE_REFUSED = new Set([405, 406, 409, 422]);
+
+/** A refused merge as a result, any other failure rethrown. */
+function refusedMerge(err: unknown): MergeResult {
+  if (err instanceof ForgeApiError && MERGE_REFUSED.has(err.status)) {
+    let reason = err.detail;
+    try {
+      const j = JSON.parse(err.detail) as Record<string, unknown>;
+      const m = j.message ?? j.error;
+      if (typeof m === "string") reason = m;
+    } catch {
+      /* not JSON: the raw text is the reason */
+    }
+    return { merged: false, reason: reason.slice(0, 300) || `the forge refused the merge (${err.status})` };
+  }
+  throw err;
+}
+
 export interface PrForge {
   kind: ForgeKind;
   /** Lower-cased, such as `github.com`. */
@@ -290,6 +332,13 @@ export interface PrForge {
   editPullRequest(pr: number, change: { title?: string; body?: string }): Promise<PullRequest | undefined>;
   /** Add labels to a pull request by name. Forgejo needs them to exist; GitHub and GitLab make them. */
   addLabels(pr: number, labels: readonly string[]): Promise<void>;
+  /**
+   * Merge pull request `pr` only if its head is still `opts.sha`. A moved
+   * head, a conflict or a branch rule the forge enforces comes back as
+   * `{ merged: false, reason }`; auth, missing-pull-request and server errors
+   * still throw.
+   */
+  mergePullRequest(pr: number, opts: MergeOptions): Promise<MergeResult>;
 }
 
 /** A GitHub or Forgejo client. */
@@ -301,7 +350,7 @@ export class ForgeApiError extends Error {
     readonly method: string,
     readonly url: string,
     readonly status: number,
-    detail: string,
+    readonly detail: string,
   ) {
     super(`${method} ${url} answered ${status}${detail ? `: ${detail.slice(0, 300)}` : ""}`);
     this.name = "ForgeApiError";
@@ -604,7 +653,18 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       // head filter, so every open page is read and matched here.
       const owner = opts.repo.split("/")[0];
       const query = kind === "github" ? `?state=open&head=${encodeURIComponent(`${owner}:${head}`)}` : "?state=open";
-      const open = (await api.list(`${repo}/pulls${query}`, pageParams, pageSize)).filter((p) => fromHere(p, head));
+      let listed: unknown[];
+      try {
+        listed = await api.list(`${repo}/pulls${query}`, pageParams, pageSize);
+      } catch (err) {
+        // Forgejo answers the list with 404 while it still counts the repository
+        // as empty (just after the first push). That is no pull request; a
+        // repository that is really missing 404s on its own read too.
+        if (kind !== "forgejo" || !(err instanceof ForgeApiError) || err.status !== 404) throw err;
+        await api.call("GET", repo);
+        return undefined;
+      }
+      const open = listed.filter((p) => fromHere(p, head));
       return open.map(pull).filter((p): p is PullRequest => p !== undefined).sort((a, b) => a.number - b.number)[0];
     },
     async editPullRequest(pr, change) {
@@ -614,6 +674,38 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       if (labels.length === 0) return;
       await api.call("POST", `${repo}/issues/${pr}/labels`, { labels: [...labels] });
     },
+    async mergePullRequest(pr, m) {
+      const method = m.method ?? "merge";
+      let res: unknown;
+      try {
+        res =
+          kind === "github"
+            ? await api.call("PUT", `${repo}/pulls/${pr}/merge`, {
+                sha: m.sha,
+                merge_method: method,
+                ...(m.title !== undefined ? { commit_title: m.title } : {}),
+                ...(m.message !== undefined ? { commit_message: m.message } : {}),
+              })
+            : await api.call("POST", `${repo}/pulls/${pr}/merge`, {
+                Do: method,
+                head_commit_id: m.sha,
+                ...(m.title !== undefined ? { MergeTitleField: m.title } : {}),
+                ...(m.message !== undefined ? { MergeMessageField: m.message } : {}),
+                ...(m.deleteBranch ? { delete_branch_after_merge: true } : {}),
+              });
+      } catch (err) {
+        return refusedMerge(err);
+      }
+      if (isObject(res) && res.merged === false) return { merged: false, reason: str(res.message) ?? "the forge did not merge it" };
+      // Forgejo answers an empty body, so the merge commit is read back.
+      const after = await api.call("GET", `${repo}/pulls/${pr}`).catch(() => undefined);
+      const sha = (isObject(res) ? str(res.sha) : undefined) ?? (isObject(after) ? str(after.merge_commit_sha) : undefined);
+      if (kind === "github" && m.deleteBranch && isObject(after) && isObject(after.head) && str(after.head.ref) && fromHere(after, str(after.head.ref) as string)) {
+        const ref = (str(after.head.ref) as string).split("/").map(encodeURIComponent).join("/");
+        await api.call("DELETE", `${repo}/git/refs/heads/${ref}`).catch(() => undefined);
+      }
+      return { merged: true, ...(sha ? { sha } : {}) };
+    },
   };
 }
 
@@ -773,6 +865,25 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       if (labels.length === 0) return;
       await api.call("PUT", `${notes}/${mr}`, { add_labels: labels.join(",") });
     },
+    async mergePullRequest(mr, m) {
+      const method = m.method ?? "merge";
+      if (method === "rebase") throw new Error("GitLab has no one-call rebase merge; use method merge or squash");
+      const text = m.title !== undefined ? (m.message ? `${m.title}\n\n${m.message}` : m.title) : m.message;
+      let res: unknown;
+      try {
+        res = await api.call("PUT", `${notes}/${mr}/merge`, {
+          sha: m.sha,
+          ...(method === "squash" ? { squash: true, ...(text !== undefined ? { squash_commit_message: text } : {}) } : {}),
+          ...(text !== undefined ? { merge_commit_message: text } : {}),
+          ...(m.deleteBranch ? { should_remove_source_branch: true } : {}),
+        });
+      } catch (err) {
+        return refusedMerge(err);
+      }
+      const sha = isObject(res) ? (str(res.merge_commit_sha) ?? str(res.squash_commit_sha)) : undefined;
+      if (isObject(res) && res.state !== undefined && res.state !== "merged") return { merged: false, reason: `the merge request is ${String(res.state)}` };
+      return { merged: true, ...(sha ? { sha } : {}) };
+    },
   };
 }
 

package/src/workspace/identity.test.ts

@@ -202,7 +202,10 @@ describe.skipIf(!hasSshKeygen)("identity.gates", () => {
 
     const roster = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex")] });
     expect((await evaluateGate(roster, input)).satisfied).toBe(true);
-    expect((await evaluateGate({ ...roster, approvalRule: async () => rule }, input)).satisfied).toBe(false);
+    const held = await evaluateGate({ ...roster, approvalRule: async () => rule }, input);
+    expect(held.satisfied).toBe(false);
+    // #3841: the approval the rule refused is named, with why.
+    expect(!held.satisfied && held.refused?.map((x) => [x.resolution.resolvedBy, x.reason])).toEqual([["alex", expect.stringMatching(/not signed/)]]);
     const sealed = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex"), signed(alice, approval("github:alice"))] });
     const check = await evaluateGate({ ...sealed, approvalRule: async () => rule }, input);
     expect(check.satisfied && check.resolution.resolvedBy).toBe("github:alice");

package/src/workspace/identity.ts

@@ -179,8 +179,9 @@ export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdm
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.
  * What a run, `chant approve` and `workspace status` ask before counting an
- * approval.
+ * approval. `base` names the commit to read at instead, as an op wave reads
+ * every rule at its `--base` (#3841).
  */
-export function gateAdmission(cwd: string, gate: string): GateAdmission | null {
-  return gateAdmissionFrom(scopeSource(cwd), gate);
+export function gateAdmission(cwd: string, gate: string, base?: string): GateAdmission | null {
+  return gateAdmissionFrom(scopeSource(cwd, base), gate);
 }

package/src/workspace/write-scope.ts

@@ -368,11 +368,12 @@ function readAt(cwd: string, at?: string): { declaration: Declaration; rootOnDis
  * The scope for a write from `cwd`: the declaration and the trust policy at
  * the base revision (`origin/HEAD`, `main` or `master`), so a write can't
  * widen its own scope by editing its copy of the declaration. Without a base,
- * or without a declaration at it, the working tree's declaration.
+ * or without a declaration at it, the working tree's declaration. `at` names
+ * the base instead, as an op wave's `--base` does (#3841).
  */
-export function scopeSource(cwd: string): ScopeSource {
+export function scopeSource(cwd: string, at?: string): ScopeSource {
   const top = gitRoot(cwd);
-  const base = top ? resolveBase(top) : null;
+  const base = top ? resolveBase(top, at) : null;
   const policy = top && base ? policyAtBase(top, base) : emptyPolicy(null);
   const withClasses = (read: NonNullable<ReturnType<typeof readAt>>) => {
     const { tree, ...rest } = read;