pr-merge-queue 0.0.0-stage → 0.0.0

package/src/open-pr/main.mts

@@ -0,0 +1,327 @@
+import * as fs from 'node:fs/promises';
+import { AUTO_REBASE_LABEL, SKIP_CI_LABEL } from 'pr-report-core';
+import { Arr, Result, unknownToString } from 'ts-data-forge';
+import { addLabel, log, type ApiContext } from '../lib/index.mjs';
+import {
+  containsBase,
+  createPullRequest,
+  findOpenPullRequest,
+  findStackParent,
+  lastCommitSubject,
+  markReady,
+  missingInheritedOrder,
+  preflight,
+  pushBranch,
+  updateBody,
+  viewPullRequest,
+} from './github.mjs';
+import type { Options } from './options.mjs';
+import {
+  mergeAfterTrailer,
+  withInheritedMergeAfter,
+  withStackParent,
+} from './steps.mjs';
+
+/**
+ * Opens the pull request for the current branch the way this repository wants
+ * one opened: push, create it ready for review, add `skip-ci`, then
+ * `auto-rebase`.
+ *
+ * **It never arms auto-merge.** `unblock-prs` does, when it picks the pull
+ * request — once the author has queued it with `merge-queued`, and once it is
+ * onto the default branch. Armed any earlier, it would merge the moment its
+ * checks went green, reviewed or not; and a stacked one, onto a branch no
+ * ruleset covers, the moment nothing held it, into the layer below. So
+ * `skip-ci` holds the checks and nothing is armed until the queue says so.
+ *
+ * Every step is skipped when it is already done, so a run that failed part
+ * way through is finished by running it again rather than unpicked.
+ *
+ * **`auto-rebase` goes on every layer, stacked or not.** `unblock-prs` keeps
+ * only a pull request based on the default branch on its tip, so on a layer
+ * above it does nothing until the layer below merges and GitHub moves this
+ * one onto the default branch — the moment it is needed, and one at which
+ * nothing would add it. It goes on after `skip-ci`, so that its own `labeled`
+ * run finds the checks held.
+ *
+ * **A `--base` other than the default branch stacks it** on the open pull
+ * request that branch is from, which has to exist and which the branch has to
+ * contain, and declares that one with `Merge-After:` as well.
+ *
+ * **What the issues it closes start after is declared too**: the open pull
+ * requests their `Start-After:` comes to (`docs/issue-start-after.md`),
+ * written into the body's `Merge-After:` once GitHub has read which issues
+ * the body closes. The readers inherit it without, so the body is saying
+ * what they already derive.
+ */
+export const openPullRequest = async (
+  options: Options,
+): Promise<Result<string, string>> => {
+  const context = await preflight();
+
+  if (Result.isErr(context)) {
+    return context;
+  }
+
+  const { api, branch, defaultBranch } = context.value;
+
+  const base = options.base ?? defaultBranch;
+
+  const parent = base === defaultBranch ? undefined : await stackOn(api, base);
+
+  if (parent !== undefined && Result.isErr(parent)) {
+    return parent;
+  }
+
+  const mergeAfter = withStackParent(options.mergeAfter, parent?.value);
+
+  if (options.dryRun) {
+    return dryRun(api, branch, base, options, parent?.value, mergeAfter);
+  }
+
+  const pushed = await pushBranch(branch);
+
+  if (Result.isErr(pushed)) {
+    return Result.err(`cannot push: ${pushed.value}`);
+  }
+
+  log(`pushed ${branch}`);
+
+  const existing = await findOpenPullRequest(api, branch);
+
+  if (Result.isErr(existing)) {
+    return existing;
+  }
+
+  const prNumber =
+    existing.value === undefined
+      ? await open(api, branch, base, options, mergeAfter)
+      : Result.ok(existing.value.number);
+
+  if (Result.isErr(prNumber)) {
+    return prNumber;
+  }
+
+  // Re-read rather than reuse what the listing said: between then and now
+  // this run has created it.
+  const created = await viewPullRequest(api, prNumber.value);
+
+  if (Result.isErr(created)) {
+    return created;
+  }
+
+  if (created.value.isDraft) {
+    const ready = await markReady(api, created.value.nodeId);
+
+    if (Result.isErr(ready)) {
+      return Result.err(`cannot mark it ready for review: ${ready.value}`);
+    }
+
+    log(`#${prNumber.value}: marked ready for review`);
+  }
+
+  const carried = await carryStartAfter(api, prNumber.value, mergeAfter);
+
+  if (Result.isErr(carried)) {
+    return carried;
+  }
+
+  const labelled = await addLabel(api, prNumber.value, SKIP_CI_LABEL);
+
+  if (Result.isErr(labelled)) {
+    return Result.err(`cannot add ${SKIP_CI_LABEL}: ${labelled.value}`);
+  }
+
+  log(`#${prNumber.value}: ${SKIP_CI_LABEL} is on`);
+
+  const autoRebase = await addLabel(api, prNumber.value, AUTO_REBASE_LABEL);
+
+  if (Result.isErr(autoRebase)) {
+    return Result.err(`cannot add ${AUTO_REBASE_LABEL}: ${autoRebase.value}`);
+  }
+
+  log(`#${prNumber.value}: ${AUTO_REBASE_LABEL} is on`);
+
+  return Result.ok(
+    [
+      `#${prNumber.value}: opened, ${SKIP_CI_LABEL} and ${AUTO_REBASE_LABEL} on, auto-merge left unarmed.`,
+      `Once it is reviewed, add merge-queued: unblock-prs arms auto-merge when it picks it${parent === undefined ? '' : `, which is once #${parent.value} has merged`}.`,
+    ].join('\n'),
+  );
+};
+
+/**
+ * Writes into the body, as `Merge-After:`, the open pull requests the issues
+ * it closes start after (`docs/issue-start-after.md`), once the body exists
+ * for GitHub to say which issues those are. A run on a body that says them
+ * already writes nothing.
+ */
+const carryStartAfter = async (
+  api: ApiContext,
+  prNumber: number,
+  declared: readonly number[],
+): Promise<Result<undefined, string>> => {
+  const order = await missingInheritedOrder(api, prNumber, declared);
+
+  if (Result.isErr(order)) {
+    return Result.err(`cannot read the issues it closes: ${order.value}`);
+  }
+
+  const { body, missing } = order.value;
+
+  if (!Arr.isNonEmpty(missing)) {
+    return Result.ok(undefined);
+  }
+
+  const updated = await updateBody(
+    api,
+    prNumber,
+    withInheritedMergeAfter(body, missing),
+  );
+
+  if (Result.isErr(updated)) {
+    return Result.err(`cannot write the inherited order: ${updated.value}`);
+  }
+
+  log(
+    `#${prNumber}: ${mergeAfterTrailer(missing) ?? ''}, from the Start-After of the issues it closes`,
+  );
+
+  return Result.ok(undefined);
+};
+
+/**
+ * The pull request a new one onto `base` is stacked on, having checked that
+ * the branch is on its tip. Asked before anything is pushed, so that a base
+ * nothing will recognize as a stack is refused rather than opened.
+ */
+const stackOn = async (
+  api: ApiContext,
+  base: string,
+): Promise<Result<number, string>> => {
+  const parent = await findStackParent(api, base);
+
+  if (Result.isErr(parent)) {
+    return parent;
+  }
+
+  const contained = await containsBase(base);
+
+  if (Result.isErr(contained)) {
+    return contained;
+  }
+
+  log(`stacking on #${parent.value} (${base})`);
+
+  return parent;
+};
+
+const open = async (
+  api: ApiContext,
+  branch: string,
+  base: string,
+  options: Options,
+  mergeAfter: readonly number[],
+): Promise<Result<number, string>> => {
+  const title = await resolveTitle(options);
+
+  if (Result.isErr(title)) {
+    return title;
+  }
+
+  const body = await resolveBody(options, mergeAfter);
+
+  if (Result.isErr(body)) {
+    return body;
+  }
+
+  const created = await createPullRequest({
+    api,
+    branch,
+    base,
+    title: title.value,
+    body: body.value,
+  });
+
+  if (Result.isErr(created)) {
+    return Result.err(`cannot create the pull request: ${created.value}`);
+  }
+
+  log(`#${created.value}: opened against ${base}`);
+
+  return created;
+};
+
+const resolveTitle = async (
+  options: Options,
+): Promise<Result<string, string>> =>
+  options.title === undefined ? lastCommitSubject() : Result.ok(options.title);
+
+const resolveBody = async (
+  options: Options,
+  mergeAfter: readonly number[],
+): Promise<Result<string, string>> => {
+  const trailer = mergeAfterTrailer(mergeAfter);
+
+  if (options.bodyFile === undefined) {
+    return Result.ok(trailer === undefined ? '' : `${trailer}\n`);
+  }
+
+  const read = await Result.fromPromise(
+    // The path is one the operator typed; there is no literal to use here.
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    fs.readFile(options.bodyFile, 'utf8'),
+  );
+
+  if (Result.isErr(read)) {
+    return Result.err(
+      `cannot read ${options.bodyFile}: ${unknownToString(read.value)}`,
+    );
+  }
+
+  // The trailer goes first, where `unblock-prs` reads it and a reader sees it
+  // before the prose.
+  return Result.ok(
+    trailer === undefined ? read.value : `${trailer}\n\n${read.value}`,
+  );
+};
+
+const dryRun = async (
+  api: ApiContext,
+  branch: string,
+  base: string,
+  options: Options,
+  parent: number | undefined,
+  mergeAfter: readonly number[],
+): Promise<Result<string, string>> => {
+  const existing = await findOpenPullRequest(api, branch);
+
+  if (Result.isErr(existing)) {
+    return existing;
+  }
+
+  const title = await resolveTitle(options);
+
+  const trailer = mergeAfterTrailer(mergeAfter);
+
+  const steps: readonly string[] = [
+    `push ${branch} to origin`,
+    existing.value === undefined
+      ? `open a pull request against ${base} titled ${JSON.stringify(Result.isOk(title) ? title.value : '(unreadable)')}`
+      : `#${existing.value.number} is open already; leave it as it is`,
+    existing.value?.isDraft === true
+      ? `#${existing.value.number}: mark it ready for review`
+      : undefined,
+    `add ${SKIP_CI_LABEL}`,
+    `add ${AUTO_REBASE_LABEL}`,
+    parent === undefined
+      ? 'leave auto-merge unarmed: unblock-prs arms it when it picks it'
+      : `leave auto-merge unarmed: it is stacked on #${parent}, and unblock-prs arms it when it picks it, after #${parent} merges`,
+    trailer === undefined ? undefined : `declare ${trailer}`,
+    'add to Merge-After the open pull requests the issues it closes start after, if the body does not name them',
+  ].filter((step) => step !== undefined);
+
+  return Result.ok(
+    Arr.toUnshifted('Would:')(steps.map((step) => `  - ${step}`)).join('\n'),
+  );
+};

package/src/open-pr/options.mts

@@ -0,0 +1,101 @@
+/** What the command line says, and how it is read. */
+
+import { SKIP_CI_LABEL } from 'pr-report-core';
+import { Result } from 'ts-data-forge';
+import { parseCommandArgs, pullRequestNumber } from '../lib/index.mjs';
+
+export type Options = Readonly<{
+  /** The pull request title; the branch's last commit subject when absent. */
+  title: string | undefined;
+  /** A file to take the body from; only the trailer, or nothing, when absent. */
+  bodyFile: string | undefined;
+  /**
+   * What to target; the repository's default branch when absent. Another
+   * open pull request's branch stacks it on that pull request.
+   */
+  base: string | undefined;
+  /** Pull requests to declare with `Merge-After:`, in the order given. */
+  mergeAfter: readonly number[];
+  /** Say what would be done, and touch nothing. */
+  dryRun: boolean;
+}>;
+
+export const HELP = [
+  'Usage: open-pr [options]',
+  '',
+  'Opens the pull request for the current branch the way this repository',
+  'wants one opened: push, create it ready for review, and add the',
+  `${SKIP_CI_LABEL} label. It never arms auto-merge: unblock-prs does, when it`,
+  'picks the pull request once it is labelled merge-queued.',
+  '',
+  'Re-running is safe: each step is skipped when it is already done, so a run',
+  'that failed part way through is finished by running it again.',
+  '',
+  'The description is yours to write — say in it which checks you ran, since',
+  `while ${SKIP_CI_LABEL} is on they are the only checks the branch gets.`,
+  '',
+  'Options:',
+  '  --title <text>          pull request title (default: the last commit subject)',
+  '  --body-file <path>      file to take the body from (default: the trailer alone)',
+  '  --base <branch>         what to target (default: the repository default branch);',
+  '                          the branch of an open pull request stacks it on that one',
+  '  --merge-after <number>  declare a predecessor; repeat for several',
+  '  --dry-run               say what would be done, and touch nothing',
+  '  -h, --help              show this help',
+].join('\n');
+
+export const parseOptions = (
+  args: readonly string[],
+): Result<Options | 'help', string> => {
+  const parsed = parseCommandArgs(args, {
+    title: { type: 'string' },
+    'body-file': { type: 'string' },
+    base: { type: 'string' },
+    'merge-after': { type: 'string', multiple: true },
+    'dry-run': { type: 'boolean', default: false },
+  });
+
+  if (Result.isErr(parsed)) {
+    return parsed;
+  }
+
+  if (parsed.value === 'help') {
+    return Result.ok('help');
+  }
+
+  const values = parsed.value;
+
+  const mergeAfter = parseMergeAfter(values['merge-after'] ?? []);
+
+  if (Result.isErr(mergeAfter)) {
+    return mergeAfter;
+  }
+
+  return Result.ok({
+    title: values.title,
+    bodyFile: values['body-file'],
+    base: values.base,
+    mergeAfter: mergeAfter.value,
+    dryRun: values['dry-run'],
+  });
+};
+
+const parseMergeAfter = (
+  raw: readonly string[],
+): Result<readonly number[], string> => {
+  const mut_numbers: number[] = [];
+
+  for (const value of raw) {
+    const number = pullRequestNumber(value);
+
+    if (number === undefined) {
+      return Result.err(
+        `--merge-after must be a pull request number, got ${JSON.stringify(value)}`,
+      );
+    }
+
+    mut_numbers.push(number);
+  }
+
+  return Result.ok(mut_numbers);
+};

package/src/open-pr/options.test.mts

@@ -0,0 +1,67 @@
+import { Result } from 'ts-data-forge';
+import { parseOptions, type Options } from './options.mjs';
+
+const parsed = (...args: readonly string[]): ReturnType<typeof parseOptions> =>
+  parseOptions(args);
+
+/** Every field, so that a new one cannot be added without a decision here. */
+const defaults: Options = {
+  title: undefined,
+  bodyFile: undefined,
+  base: undefined,
+  mergeAfter: [],
+  dryRun: false,
+} as const;
+
+describe(parseOptions, () => {
+  test('defaults to acting, on no declared predecessor', () => {
+    assert.deepStrictEqual(Result.unwrapOk(parsed()), defaults);
+  });
+
+  // `pnpm run open-pr -- --dry-run` forwards the `--` as well.
+  test('drops the separator pnpm forwards', () => {
+    assert.deepStrictEqual(Result.unwrapOk(parsed('--', '--dry-run')), {
+      ...defaults,
+      dryRun: true,
+    });
+  });
+
+  test('reads a title and a body file', () => {
+    assert.deepStrictEqual(
+      Result.unwrapOk(
+        parsed('--title', 'fix: a thing', '--body-file', './b.md'),
+      ),
+      { ...defaults, title: 'fix: a thing', bodyFile: './b.md' },
+    );
+  });
+
+  test('reads the base branch', () => {
+    assert.deepStrictEqual(Result.unwrapOk(parsed('--base', 'release')), {
+      ...defaults,
+      base: 'release',
+    });
+  });
+
+  test('accepts `--merge-after` once per predecessor, with or without a `#`', () => {
+    assert.deepStrictEqual(
+      Result.unwrapOk(
+        parsed('--merge-after', '#1901', '--merge-after', '1903'),
+      ),
+      { ...defaults, mergeAfter: [1901, 1903] },
+    );
+  });
+
+  test('refuses a `--merge-after` that is not a pull request number', () => {
+    assert.isTrue(Result.isErr(parsed('--merge-after', 'later')));
+  });
+
+  // `unblock-prs` passes a draft over, so the option that would ask for one
+  // is not quietly ignored.
+  test('refuses an unknown option rather than ignoring it', () => {
+    assert.isTrue(Result.isErr(parsed('--draft')));
+  });
+
+  test('asks for help', () => {
+    assert.strictEqual(Result.unwrapOk(parsed('--help')), 'help');
+  });
+});

package/src/open-pr/steps.mts

@@ -0,0 +1,57 @@
+/** What the observed state allows, and nothing that talks to GitHub. */
+
+import { Arr } from 'ts-data-forge';
+
+/**
+ * The `Merge-After:` line for a chained pull request, or `undefined` when
+ * nothing was declared. One line, in the order given, which is the form
+ * `unblock-prs` reads.
+ */
+export const mergeAfterTrailer = (
+  numbers: readonly number[],
+): string | undefined =>
+  Arr.isNonEmpty(numbers)
+    ? (`Merge-After: ${numbers.map((n) => `#${n}`).join(', ')}` as const)
+    : undefined;
+
+/**
+ * What to declare with `Merge-After:`: what was asked for, and — for a pull
+ * request stacked on another — that one first. The base already says it, and
+ * `unblock-prs` and the reports read the base alone; the trailer is written
+ * as well so that the order is stated in the body like every other, and
+ * survives the base being moved by hand.
+ */
+export const withStackParent = (
+  mergeAfter: readonly number[],
+  parent: number | undefined,
+): readonly number[] =>
+  parent === undefined
+    ? mergeAfter
+    : Arr.uniq(Arr.toUnshifted(parent)(mergeAfter));
+
+/**
+ * `body` with `numbers` declared in it as well: added to the `Merge-After:`
+ * line it opens with, which is where this command writes one, or in a line
+ * of their own before it. The numbers are what the issues it closes start
+ * after and the body does not yet say (`openPullRequest`).
+ */
+export const withInheritedMergeAfter = (
+  body: string,
+  numbers: readonly number[],
+): string => {
+  const trailer = mergeAfterTrailer(numbers);
+
+  if (trailer === undefined) {
+    return body;
+  }
+
+  const [first = '', ...rest] = body.split('\n');
+
+  if (/^merge-after\s*:/iu.test(first)) {
+    return Arr.toUnshifted(
+      `${first.trimEnd()}, ${numbers.map((n) => `#${n}`).join(', ')}`,
+    )(rest).join('\n');
+  }
+
+  return body === '' ? `${trailer}\n` : `${trailer}\n\n${body}`;
+};

package/src/open-pr/steps.test.mts

@@ -0,0 +1,59 @@
+import {
+  mergeAfterTrailer,
+  withInheritedMergeAfter,
+  withStackParent,
+} from './steps.mjs';
+
+describe(mergeAfterTrailer, () => {
+  test('is nothing when no pull request was named', () => {
+    assert.isUndefined(mergeAfterTrailer([]));
+  });
+
+  test('writes the numbers on one line, in the declared order', () => {
+    assert.strictEqual(
+      mergeAfterTrailer([1901, 1903]),
+      'Merge-After: #1901, #1903',
+    );
+  });
+});
+
+describe(withStackParent, () => {
+  test('declares the layer below first when it is stacked', () => {
+    assert.deepStrictEqual(withStackParent([1903], 1901), [1901, 1903]);
+  });
+
+  test('does not name the layer below twice', () => {
+    assert.deepStrictEqual(withStackParent([1903, 1901], 1901), [1901, 1903]);
+  });
+
+  test('leaves the declaration alone when it is not stacked', () => {
+    assert.deepStrictEqual(withStackParent([1903], undefined), [1903]);
+  });
+});
+
+describe(withInheritedMergeAfter, () => {
+  test('adds the numbers to the trailer the body opens with', () => {
+    assert.strictEqual(
+      withInheritedMergeAfter('Merge-After: #1901\n\nProse.', [1905]),
+      'Merge-After: #1901, #1905\n\nProse.',
+    );
+  });
+
+  test('puts a trailer first when the body opens with prose', () => {
+    assert.strictEqual(
+      withInheritedMergeAfter('Prose.\n', [1905, 1907]),
+      'Merge-After: #1905, #1907\n\nProse.\n',
+    );
+  });
+
+  test('writes the trailer alone into an empty body', () => {
+    assert.strictEqual(
+      withInheritedMergeAfter('', [1905]),
+      'Merge-After: #1905\n',
+    );
+  });
+
+  test('leaves the body as it is when there is nothing to add', () => {
+    assert.strictEqual(withInheritedMergeAfter('Prose.', []), 'Prose.');
+  });
+});

package/src/open-pr/types.mts

@@ -0,0 +1,42 @@
+/** The shapes this command passes around, and what the API answers with. */
+
+import * as t from 'ts-fortress';
+
+/**
+ * The fields the run needs, and no more. Deliberately smaller than
+ * `unblock-prs`'s pull request: this command decides two things — whether
+ * the pull request exists, and whether it is a draft — and asking for less
+ * keeps what a failure can be about small.
+ *
+ * `nodeId` is here because taking a pull request out of draft is a GraphQL
+ * mutation, which addresses it by node id rather than by number. It is
+ * carried on the read that already happens rather than fetched again.
+ */
+export type PullRequest = Readonly<{
+  number: number;
+  nodeId: string;
+  isDraft: boolean;
+}>;
+
+/**
+ * What `GET /repos/{owner}/{repo}/pulls[/{number}]` answers with, in the
+ * REST API's own names. Only the fields above are declared; everything else
+ * in that response is ignored.
+ */
+export const PullRequestResponseSchema = t.record({
+  number: t.number(),
+  node_id: t.string(),
+  draft: t.boolean(),
+});
+
+export const PullRequestListResponseSchema = t.array(PullRequestResponseSchema);
+
+export type PullRequestResponse = t.TypeOf<typeof PullRequestResponseSchema>;
+
+/** The REST response in this command's own terms. */
+export const toPullRequest = (response: PullRequestResponse): PullRequest =>
+  ({
+    number: response.number,
+    nodeId: response.node_id,
+    isDraft: response.draft,
+  }) as const;