@intentius/chant 0.124.6 → 0.124.8

package/src/pr-forge.ts

@@ -2,7 +2,8 @@
  * What chant and the products built on it ask of a forge: keep one comment
  * (a merge request note on GitLab) on a pull request up to date, set a commit
  * status, keep one tracking issue in the repository, list who approved a pull
- * request, and find the pull request that merged a commit.
+ * request, find the pull request that merged a commit, and open or edit a
+ * pull request (a merge request on GitLab) for a branch.
  *
  * The pull-request loop (#3183) uses the note, the status and the review
  * calls. `reconcilePr`'s `comment` and `issue` finding modes post through the
@@ -21,6 +22,10 @@
  * `gitlab:<login>`, or `<forge>@<host>:<login>` off the forge's default host.
  * The apply compares that string with the approval's `resolvedBy`.
  *
+ * Opening a pull request goes over REST too (#3798): `gh pr` speaks GitHub's
+ * GraphQL, which Forgejo does not serve, so chant's own pull-request paths
+ * open theirs through {@link PrForge.openPullRequest} on Forgejo and GitLab.
+ *
  * Like `./pr-loop.ts`, this bundles without the TypeScript toolchain (#3421):
  * it imports nothing but `node:fs`, to read a CI job's event payload.
  * `./pr-forge-bundle.test.ts` holds it to that.
@@ -41,7 +46,13 @@ export type ForgeFetch = (
 export interface ForgeStatus {
   /** The status's name, such as `chant/plan` or `terragucci/plan`. */
   context: string;
-  state: "pending" | "success" | "failure";
+  /**
+   * GitLab's own states, plus GitHub's `failure` and `error`. Each forge gets
+   * the nearest state it has ({@link statusStateFor}): `running` is `pending`
+   * on GitHub and Forgejo, `canceled` is `error` there, and `failure` and
+   * `error` are `failed` on GitLab.
+   */
+  state: ForgeStatusState;
   /** Cut to what the forge keeps: 140 characters on GitHub and Forgejo, 255 on GitLab. */
   description: string;
   /** The pipeline run, linked from the status. */
@@ -50,6 +61,30 @@ export interface ForgeStatus {
   pipelineId?: number;
 }
 
+/** A commit status's state, as a caller names it. */
+export type ForgeStatusState = "pending" | "running" | "success" | "failed" | "failure" | "canceled" | "error";
+
+/** Every {@link ForgeStatusState}, for a caller that reads one from its own input. */
+export const FORGE_STATUS_STATES: readonly ForgeStatusState[] = ["pending", "running", "success", "failed", "failure", "canceled", "error"];
+
+/**
+ * What each forge is sent for a {@link ForgeStatusState} (#3834). GitHub
+ * keeps `pending`, `success`, `failure` and `error`; Forgejo the same and
+ * `warning`; GitLab `pending`, `running`, `success`, `failed` and `canceled`.
+ * A state the forge lacks becomes its nearest one.
+ */
+const STATUS_STATE: Record<"github" | "gitlab", Record<ForgeStatusState, string>> = {
+  github: { pending: "pending", running: "pending", success: "success", failed: "failure", failure: "failure", canceled: "error", error: "error" },
+  gitlab: { pending: "pending", running: "running", success: "success", failed: "failed", failure: "failed", canceled: "canceled", error: "failed" },
+};
+
+/** The state `kind` is sent for `state`. Forgejo takes GitHub's. */
+export function statusStateFor(kind: ForgeKind, state: ForgeStatusState): string {
+  const mapped = STATUS_STATE[kind === "gitlab" ? "gitlab" : "github"][state];
+  if (mapped === undefined) throw new Error(`a commit status state is one of ${FORGE_STATUS_STATES.join(", ")}, not ${JSON.stringify(state)}`);
+  return mapped;
+}
+
 /**
  * How a comment or an issue is told to be the caller's own. By default the
  * body starts with the marker, chant's recipe since #2291, and anyone may
@@ -59,12 +94,15 @@ export interface MarkerMatch {
   /** `prefix` (the default): the body starts with the marker. `anywhere`: the body carries it. */
   match?: "prefix" | "anywhere";
   /**
-   * Only a comment or issue written by this login counts: `user.login` on
-   * GitHub and Forgejo, `author.username` on GitLab, compared without case.
-   * A merge request's author can write a note carrying any marker, so a
-   * product that reads its own notes back names its bot here.
+   * Only a comment or issue written by this login, or by any of these
+   * logins, counts: `user.login` on GitHub and Forgejo, `author.username` on
+   * GitLab, compared without case. A merge request's author can write a note
+   * carrying any marker, so a product that reads its own notes back names
+   * its bot here. A list is for a bot whose login the job cannot know in
+   * advance, such as `gitea-actions` or `forgejo-actions` on Forgejo (#3834).
+   * An empty list matches nobody.
    */
-  author?: string;
+  author?: string | readonly string[];
 }
 
 /** What {@link PrForge.upsertComment} did. */
@@ -146,6 +184,76 @@ export interface IssueResult {
   created?: string;
 }
 
+/** A pull request (merge request) for {@link PrForge.openPullRequest} to open. */
+export interface PullRequestSpec {
+  /** The branch with the change, in the same repository. */
+  head: string;
+  /** The branch it merges into. Default: the repository's default branch, read from the forge. */
+  base?: string;
+  title: string;
+  body: string;
+  /**
+   * Open it as a draft: GitHub's `draft`, GitLab's `Draft: ` title prefix,
+   * Forgejo's `WIP: ` title prefix (it has no draft field).
+   */
+  draft?: boolean;
+}
+
+/** A pull request (merge request) as the forge answered it. */
+export interface PullRequest {
+  /** The pull request's number, or the merge request's iid. */
+  number: number;
+  url?: string;
+  title: string;
+  body: string;
+  /** Its head (source) branch. */
+  head: string;
+  /** Its base (target) branch. */
+  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`. */
@@ -208,6 +316,29 @@ export interface PrForge {
   approvers(pr: number): Promise<string[]>;
   /** The merged pull request that produced `sha`, or null. */
   pullRequestFor(sha: string): Promise<number | null>;
+  /**
+   * Open a pull request (a merge request on GitLab) from `head` into `base`,
+   * or into the default branch when `base` is not given. Over REST on every
+   * forge, so it works on Forgejo, where `gh pr create` cannot (#3798).
+   */
+  openPullRequest(spec: PullRequestSpec): Promise<PullRequest>;
+  /**
+   * The OPEN pull request whose head is branch `head` in this repository (a
+   * fork's branch of the same name is not it), or undefined. The oldest when
+   * there are several.
+   */
+  findPullRequest(head: string): Promise<PullRequest | undefined>;
+  /** Change an open pull request's title or body. */
+  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. */
@@ -219,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";
@@ -301,8 +432,15 @@ interface Threads {
 const carries = (body: string, marker: string, match: MarkerMatch["match"]): boolean =>
   match === "anywhere" ? body.includes(marker) : body.startsWith(marker);
 
+/** Whether `author` is one of `want`, without case. No `want` (or `""`) takes anyone. */
+const authorIn = (want: MarkerMatch["author"], author: string | undefined): boolean => {
+  if (want === undefined || want === "") return true;
+  const logins = (typeof want === "string" ? [want] : want).map((l) => l.toLowerCase());
+  return author !== undefined && logins.includes(author.toLowerCase());
+};
+
 const ownedBy = (marker: string, opts: MarkerMatch) => (t: Thread): boolean =>
-  carries(t.body, marker, opts.match) && (!opts.author || t.author?.toLowerCase() === opts.author.toLowerCase());
+  carries(t.body, marker, opts.match) && authorIn(opts.author, t.author);
 
 function checkMarker(what: string, marker: string, body: string, match: MarkerMatch["match"]): void {
   if (!marker) throw new Error(`the ${what} needs a marker to be found again`);
@@ -420,6 +558,21 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     return { id, body: str(v.body) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
   };
   const threads = (items: unknown[]): Thread[] => items.map(thread).filter((t): t is Thread => t !== undefined);
+  const pull = (v: unknown): PullRequest | undefined => {
+    if (!isObject(v)) return undefined;
+    const number = num(v.number);
+    const head = isObject(v.head) ? str(v.head.ref) : undefined;
+    if (number === undefined) return undefined;
+    const base = isObject(v.base) ? str(v.base.ref) : undefined;
+    const url = str(v.html_url);
+    return { number, title: str(v.title) ?? "", body: str(v.body) ?? "", head: head ?? "", ...(base ? { base } : {}), ...(url ? { url } : {}) };
+  };
+  /** A pull request whose head branch lives in this repository, not a fork. */
+  const fromHere = (v: unknown, head: string): boolean => {
+    if (!isObject(v) || !isObject(v.head) || v.head.ref !== head) return false;
+    const full = isObject(v.head.repo) ? str(v.head.repo.full_name) : undefined;
+    return full === undefined || full.toLowerCase() === opts.repo.toLowerCase();
+  };
   const t: Threads = {
     comments: async (pr) => threads(await api.list(`${repo}/issues/${pr}/comments`, pageParams, pageSize)),
     addComment: async (pr, body) => thread(await api.call("POST", `${repo}/issues/${pr}/comments`, { body })),
@@ -445,7 +598,7 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     ...threadCalls(t),
     async setStatus(sha, status) {
       await api.call("POST", `${repo}/statuses/${sha}`, {
-        state: status.state,
+        state: statusStateFor(kind, status.state),
         context: status.context,
         description: status.description.slice(0, GITHUB_DESCRIPTION),
         ...(status.url ? { target_url: status.url } : {}),
@@ -483,9 +636,87 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       const pick = (exact ?? merged[0]) as Record<string, unknown> | undefined;
       return pick && typeof pick.number === "number" ? pick.number : null;
     },
+    async openPullRequest(spec) {
+      const base = spec.base ?? (await defaultBranchOf(api, repo, "default_branch"));
+      const title = spec.draft && kind === "forgejo" ? `WIP: ${spec.title}` : spec.title;
+      const made = await api.call("POST", `${repo}/pulls`, {
+        title,
+        body: spec.body,
+        head: spec.head,
+        base,
+        ...(spec.draft && kind === "github" ? { draft: true } : {}),
+      });
+      return pull(made) ?? { number: 0, title, body: spec.body, head: spec.head, base };
+    },
+    async findPullRequest(head) {
+      // GitHub filters by `owner:branch` server-side; Forgejo's list takes no
+      // 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";
+      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) {
+      return pull(await api.call("PATCH", `${repo}/pulls/${pr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { body: change.body } : {}) }));
+    },
+    async addLabels(pr, labels) {
+      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 } : {}) };
+    },
   };
 }
 
+/** The repository's default branch, from `GET` on the repository (`/repos/{repo}`, `/projects/{id}`). */
+async function defaultBranchOf(api: Transport, path: string, field: string): Promise<string> {
+  const r = await api.call("GET", path);
+  const branch = isObject(r) ? str(r[field]) : undefined;
+  if (!branch) throw new Error(`${path} names no default branch to open the pull request against; pass base`);
+  return branch;
+}
+
 /** A GitHub client (github.com or GitHub Enterprise Server). */
 export function githubForge(opts: GithubForgeOptions): GithubShapedForge {
   return githubShaped("github", opts);
@@ -515,8 +746,6 @@ export interface GitlabForgeOptions {
   fetch?: ForgeFetch;
 }
 
-const GITLAB_STATE: Record<ForgeStatus["state"], string> = { pending: "pending", success: "success", failure: "failed" };
-
 /**
  * A GitLab client. Writing notes needs an access token with the `api` scope
  * on most instances: the job token reaches only the endpoints the instance's
@@ -545,6 +774,14 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     return { id, body: str(v.description) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
   };
   const notes = `${project}/merge_requests`;
+  const mergeRequest = (v: unknown): PullRequest | undefined => {
+    if (!isObject(v)) return undefined;
+    const number = num(v.iid);
+    if (number === undefined) return undefined;
+    const base = str(v.target_branch);
+    const url = str(v.web_url);
+    return { number, title: str(v.title) ?? "", body: str(v.description) ?? "", head: str(v.source_branch) ?? "", ...(base ? { base } : {}), ...(url ? { url } : {}) };
+  };
   const t: Threads = {
     comments: async (mr) =>
       (await api.list(`${notes}/${mr}/notes`, pageParams, 100))
@@ -577,7 +814,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
     async setStatus(sha, status) {
       try {
         await api.call("POST", `${project}/statuses/${sha}`, {
-          state: GITLAB_STATE[status.state],
+          state: statusStateFor("gitlab", status.state),
           name: status.context,
           description: status.description.slice(0, GITLAB_DESCRIPTION),
           ...(status.url ? { target_url: status.url } : {}),
@@ -606,6 +843,47 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         ?? mrs.find((m) => isObject(m) && m.state === "merged");
       return isObject(merged) && typeof merged.iid === "number" ? merged.iid : null;
     },
+    async openPullRequest(spec) {
+      const base = spec.base ?? (await defaultBranchOf(api, project, "default_branch"));
+      const title = spec.draft ? `Draft: ${spec.title}` : spec.title;
+      const made = await api.call("POST", notes, { source_branch: spec.head, target_branch: base, title, description: spec.body });
+      return mergeRequest(made) ?? { number: 0, title, body: spec.body, head: spec.head, base };
+    },
+    async findPullRequest(head) {
+      const open = await api.list(`${notes}?state=opened&source_branch=${encodeURIComponent(head)}`, pageParams, 100);
+      return open
+        // A fork's merge request into this project has another source project.
+        .filter((m) => isObject(m) && m.source_branch === head && (m.source_project_id === undefined || m.source_project_id === m.project_id))
+        .map(mergeRequest)
+        .filter((m): m is PullRequest => m !== undefined)
+        .sort((a, b) => a.number - b.number)[0];
+    },
+    async editPullRequest(mr, change) {
+      return mergeRequest(await api.call("PUT", `${notes}/${mr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { description: change.body } : {}) }));
+    },
+    async addLabels(mr, labels) {
+      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 } : {}) };
+    },
   };
 }