pr-merge-queue 0.0.0-stage → 0.0.0

package/src/unblock-prs/release.mts

@@ -0,0 +1,149 @@
+/**
+ * Keeping to one released pull request without touching any other.
+ *
+ * A pull request labelled `merge-queued` without `skip-ci` is released: a push
+ * to it, or the label coming off, runs the full matrix. Only one of them can
+ * merge before `main` moves and puts the rest back to `BEHIND`, so a second
+ * released pull request is a matrix run to be thrown away.
+ *
+ * **This script puts `skip-ci` on a pull request only to give back the label
+ * it has just taken off**, yielding to another released in the same moment,
+ * and on no other pull request. It used to pause every other released one before releasing its own, which
+ * labelled pull requests nobody had handed it — the dependency update the bot
+ * opens released, one a person had just released on purpose. Now it keeps the
+ * rule from its own side only: triage watches one already in flight rather
+ * than picking another, and once its own is released it looks again, and when
+ * another of its pull requests was released in the same moment and goes
+ * first, it pauses its own ({@link yieldsTo}). A pull request someone else
+ * releases runs, and what that costs is a matrix, not a wrong merge.
+ *
+ * "In the same moment" is the whole of it: only one the survey saw paused by
+ * `skip-ci` is yielded to. One already released when the survey picked
+ * `target` and not in flight — waiting on its declared order, held by its
+ * review, conflicting, released by hand — is released on the next survey
+ * too, which picks `target` again, so yielding to it took `skip-ci` off and
+ * put it back on `target` for as long as the script ran.
+ */
+
+import { SKIP_CI_LABEL, type QueueOwner } from 'pr-report-core';
+import { Arr, Result } from 'ts-data-forge';
+import { log, type ApiContext } from '../lib/index.mjs';
+import { addSkipCiLabel, listPullRequests } from './github.mjs';
+import { isMergeQueued, isSkipCiLabelled, priorityRank } from './labels.mjs';
+import type { PullRequest } from './types.mjs';
+import { isVersionPullRequest } from './version-pr.mjs';
+
+/**
+ * Looks again once `target` has been released, and when another pull request
+ * the worker owns was released in the same moment and goes first, pauses
+ * `target` — the one pull request this may label. `pausedAtSurvey` is the
+ * pull requests the survey that picked `target` saw labelled `skip-ci`.
+ * Resolves to whether `target` keeps its release.
+ */
+export const settleAfterRelease = async (
+  api: ApiContext,
+  target: PullRequest,
+  owners: ReadonlyMap<number, QueueOwner>,
+  pausedAtSurvey: ReadonlySet<number>,
+  defaultBranch: string,
+): Promise<'kept' | 'yielded'> => {
+  const listed = await listPullRequests(api);
+
+  if (Result.isErr(listed)) {
+    log(`Cannot list pull requests to check the release: ${listed.value}`);
+
+    return 'kept';
+  }
+
+  const first = yieldsTo(
+    target,
+    listed.value,
+    owners,
+    pausedAtSurvey,
+    defaultBranch,
+  );
+
+  if (first === undefined) {
+    return 'kept';
+  }
+
+  const added = await addSkipCiLabel(api, target.number);
+
+  log(
+    Result.isErr(added)
+      ? `#${target.number}: cannot put ${SKIP_CI_LABEL} back on it to let #${first.number} go first: ${added.value}`
+      : `#${target.number}: put ${SKIP_CI_LABEL} back on it; #${first.number} was released in the same moment and goes first.`,
+  );
+
+  return Result.isErr(added) ? 'kept' : 'yielded';
+};
+
+/**
+ * The pull request `target` should step back for, if any: another one the
+ * worker owns, paused when the survey ran (`pausedAtSurvey`) and released
+ * since, that goes first in {@link firstInReleaseOrder}. One set aside or
+ * claimed is a skill's or a person's and runs nothing until its fix is
+ * pushed, so it holds nothing back; counting it would stall the queue behind
+ * a pull request nobody is about to run. One released before the survey is
+ * not counted either: see the top of this file.
+ */
+export const yieldsTo = (
+  target: PullRequest,
+  pullRequests: readonly PullRequest[],
+  owners: ReadonlyMap<number, QueueOwner>,
+  pausedAtSurvey: ReadonlySet<number>,
+  defaultBranch: string,
+): PullRequest | undefined => {
+  const others = releasedExcept(pullRequests, target.number).filter(
+    (pr) =>
+      owners.get(pr.number)?.owner === 'worker' &&
+      pausedAtSurvey.has(pr.number),
+  );
+
+  const first = firstInReleaseOrder(
+    Arr.toUnshifted(target)(others),
+    defaultBranch,
+  );
+
+  return first === undefined || first.number === target.number
+    ? undefined
+    : first;
+};
+
+/**
+ * The open pull requests labelled `merge-queued` without `skip-ci`, other
+ * than `keep`. A draft, one without auto-merge and one on another base count
+ * as well: each runs a matrix when pushed to, and whether it could merge
+ * afterwards is a different question.
+ */
+export const releasedExcept = (
+  pullRequests: readonly PullRequest[],
+  keep: number | undefined,
+): readonly PullRequest[] =>
+  pullRequests.filter(
+    (pr) =>
+      pr.number !== keep &&
+      pr.state === 'OPEN' &&
+      isMergeQueued(pr) &&
+      !isSkipCiLabelled(pr),
+  );
+
+/**
+ * Which of several released pull requests keeps its release: `priority:high`
+ * first and `priority:low` last, then the lowest number with the version pull
+ * request last — the order candidates are picked in, so that the skill,
+ * reading the same rule, settles it the same way.
+ */
+export const firstInReleaseOrder = (
+  released: readonly PullRequest[],
+  defaultBranch: string,
+): PullRequest | undefined => {
+  const rank = (pr: PullRequest): number =>
+    priorityRank(pr) * 2 + (isVersionPullRequest(pr, defaultBranch) ? 1 : 0);
+
+  const sorted = released.toSorted((a, b) =>
+    rank(a) === rank(b) ? a.number - b.number : rank(a) - rank(b),
+  );
+
+  return Arr.isNonEmpty(sorted) ? sorted[0] : undefined;
+};

package/src/unblock-prs/release.test.mts

@@ -0,0 +1,209 @@
+import type { QueueOwner } from 'pr-report-core';
+import { Arr } from 'ts-data-forge';
+import { firstInReleaseOrder, releasedExcept, yieldsTo } from './release.mjs';
+import type { PullRequest } from './types.mjs';
+
+describe(releasedExcept, () => {
+  test('is every other open queued pull request without skip-ci', () => {
+    const released = pullRequest({ number: 1, labels: [queued] });
+
+    const kept = pullRequest({ number: 2, labels: [queued] });
+
+    assert.deepStrictEqual(
+      releasedExcept(
+        [
+          released,
+          kept,
+          pullRequest({ number: 3, labels: [queued, skipCi] }),
+          pullRequest({ number: 4, labels: [] }),
+          pullRequest({ number: 5, labels: [queued], state: 'MERGED' }),
+        ],
+        kept.number,
+      ),
+      [released],
+    );
+  });
+
+  test('counts a draft, a pull request without auto-merge and one on another base', () => {
+    // Each of them runs a matrix when pushed to, which is what the rule is
+    // about; whether it could merge afterwards is a different question.
+    const others = [
+      pullRequest({ number: 1, labels: [queued], isDraft: true }),
+      pullRequest({ number: 2, labels: [queued], autoMergeRequest: null }),
+      pullRequest({ number: 3, labels: [queued], baseRefName: 'feature' }),
+    ] as const;
+
+    assert.deepStrictEqual(releasedExcept(others, 9), others);
+  });
+});
+
+describe(firstInReleaseOrder, () => {
+  test('is the lowest number', () => {
+    assert.strictEqual(
+      firstInReleaseOrder(
+        [pullRequest({ number: 12 }), pullRequest({ number: 7 })],
+        'main',
+      )?.number,
+      7,
+    );
+  });
+
+  test('puts the version pull request last', () => {
+    assert.strictEqual(
+      firstInReleaseOrder(
+        [
+          pullRequest({ number: 3, headRefName: 'changeset-release/main' }),
+          pullRequest({ number: 12 }),
+        ],
+        'main',
+      )?.number,
+      12,
+    );
+  });
+
+  test('puts priority:high first and priority:low last, the version pull request included', () => {
+    const released = [
+      pullRequest({ number: 1, labels: [queued, low] }),
+      pullRequest({ number: 2 }),
+      pullRequest({
+        number: 3,
+        headRefName: 'changeset-release/main',
+        labels: [queued, high],
+      }),
+    ] as const;
+
+    assert.strictEqual(firstInReleaseOrder(released, 'main')?.number, 3);
+
+    assert.strictEqual(
+      firstInReleaseOrder(Arr.take(released, 2), 'main')?.number,
+      2,
+    );
+  });
+
+  test('is undefined for nothing', () => {
+    assert.isUndefined(firstInReleaseOrder([], 'main'));
+  });
+});
+
+describe(yieldsTo, () => {
+  const target = pullRequest({ number: 7, labels: [queued] });
+
+  const worker: QueueOwner = {
+    owner: 'worker',
+    reason: 'in the queue',
+  } as const;
+
+  const skill: QueueOwner = {
+    owner: 'skill',
+    reason: 'set aside `checks-failed` at its head',
+  } as const;
+
+  test('yields to a worker’s pull request released in the same moment that goes first', () => {
+    const other = pullRequest({ number: 3, labels: [queued] });
+
+    assert.strictEqual(
+      yieldsTo(
+        target,
+        [target, other],
+        new Map([[3, worker]]),
+        new Set([3, 7]),
+        'main',
+      )?.number,
+      3,
+    );
+  });
+
+  test('keeps its release against one that goes after it', () => {
+    const other = pullRequest({ number: 12, labels: [queued] });
+
+    assert.isUndefined(
+      yieldsTo(
+        target,
+        [target, other],
+        new Map([[12, worker]]),
+        new Set([7, 12]),
+        'main',
+      ),
+    );
+  });
+
+  test('keeps its release against one that was already released when the survey picked it', () => {
+    // Released before the survey — a person took `skip-ci` off, or labelled
+    // `merge-queued` one that never had it — and not in flight, or the survey
+    // would have watched it: waiting on its declared order, held by its
+    // review, conflicting. It is still released on the next survey, so
+    // yielding to it would release and pause the same pull request forever.
+    const other = pullRequest({ number: 3, labels: [queued, high] });
+
+    assert.isUndefined(
+      yieldsTo(
+        target,
+        [target, other],
+        new Map([[3, worker]]),
+        new Set([7]),
+        'main',
+      ),
+    );
+  });
+
+  test('does not count one set aside with its label off, which runs nothing', () => {
+    // A pull request whose checks failed stays released; it is the skill's
+    // until its fix is pushed, and holding the queue for it would stall it.
+    const other = pullRequest({ number: 3, labels: [queued] });
+
+    assert.isUndefined(
+      yieldsTo(
+        target,
+        [target, other],
+        new Map([[3, skill]]),
+        new Set([3, 7]),
+        'main',
+      ),
+    );
+
+    assert.isUndefined(
+      yieldsTo(target, [target, other], new Map(), new Set([3, 7]), 'main'),
+    );
+  });
+
+  test('does not count one paused by skip-ci', () => {
+    const other = pullRequest({ number: 3, labels: [queued, skipCi] });
+
+    assert.isUndefined(
+      yieldsTo(
+        target,
+        [target, other],
+        new Map([[3, worker]]),
+        new Set([3, 7]),
+        'main',
+      ),
+    );
+  });
+});
+
+const queued = { name: 'merge-queued' } as const;
+
+const skipCi = { name: 'skip-ci' } as const;
+
+const high = { name: 'priority:high' } as const;
+
+const low = { name: 'priority:low' } as const;
+
+const pullRequest = (
+  fields: Partial<PullRequest> & Readonly<{ number: number }>,
+): PullRequest =>
+  ({
+    id: `PR_${fields.number}`,
+    title: `pull request #${fields.number}`,
+    body: '',
+    state: 'OPEN',
+    headRefName: `feature/${fields.number}`,
+    headRefOid: 'a'.repeat(40),
+    baseRefName: 'main',
+    isCrossRepository: false,
+    isDraft: false,
+    mergeStateStatus: 'BLOCKED',
+    autoMergeRequest: {},
+    labels: [],
+    ...fields,
+  }) as const;

package/src/unblock-prs/set-aside-comment.mts

@@ -0,0 +1,143 @@
+/**
+ * The prose of the comment a pull request gets when this script sets it
+ * aside, and of the one line it is rewritten to once that is over.
+ * `pr-report-core`'s `set-aside.mts` wraps it in the record the script and
+ * the page read back; nothing reads the prose.
+ */
+
+import {
+  writeResolvedComment,
+  writeSetAsideComment,
+  type SetAside,
+} from 'pr-report-core';
+import { Arr } from 'ts-data-forge';
+import { isoSeconds } from '../lib/index.mjs';
+import type { SkipRecord } from './types.mjs';
+import { lastLines } from './util.mjs';
+
+/**
+ * What a reader needs without the terminal this ran in: the reason and its
+ * sentence, each failed check with its run, what the command printed —
+ * folded, and cut to its end — and what will take it off.
+ */
+export const setAsideCommentBody = (
+  skip: SkipRecord,
+  defaultBranch: string,
+): string => {
+  const failedChecks = skip.failedChecks ?? [];
+
+  const output = skip.output?.trim() ?? '';
+
+  return writeSetAsideComment(
+    { reason: skip.reason, headSha: skip.headSha, baseSha: skip.baseSha },
+    [
+      `**\`unblock-prs\` set this pull request aside** (\`${skip.reason}\`): ${escapeMarkdown(skip.detail.replaceAll(/\s+/gu, ' ').trim())}`,
+      ...(Arr.isNonEmpty(failedChecks)
+        ? [
+            '',
+            'Failed required checks:',
+            '',
+            ...failedChecks.map(({ name, link }) =>
+              link === ''
+                ? `- ${escapeMarkdown(name)}`
+                : `- [${escapeMarkdown(name)}](${link})`,
+            ),
+          ]
+        : []),
+      ...(output === ''
+        ? []
+        : [
+            '',
+            '<details><summary>What the command printed</summary>',
+            '',
+            fenced(tailOf(output)),
+            '',
+            '</details>',
+          ]),
+      ...(skip.reason === 'awaiting-bypass'
+        ? [
+            '',
+            "Nothing but a ruleset bypass merges it, which is a person's to do; auto-merge was left off.",
+          ]
+        : []),
+      '',
+      `Set aside at \`${short(skip.headSha)}\`, with \`${defaultBranch}\` at \`${short(skip.baseSha)}\`. ${stays(skip.reason, defaultBranch)}`,
+    ].join('\n'),
+  );
+};
+
+/** What takes the set-aside off, as the comment's last sentence. */
+const stays = (reason: SkipRecord['reason'], defaultBranch: string): string =>
+  reason === 'checks-failed'
+    ? 'It stays aside until the branch is pushed again: rebasing it would only put the same failing checks through again.'
+    : reason === 'awaiting-bypass'
+      ? (`It stays aside until the branch is pushed again: rebasing it would only put the same checks through again. Tick the retry box to have it rebased and checked on the current \`${defaultBranch}\`.` as const)
+      : (`It stays aside until the branch is pushed again or \`${defaultBranch}\` moves.` as const);
+
+/** The one line a comment is rewritten to: what it was, what ended it, when. */
+export const resolvedCommentBody = (
+  setAside: SetAside,
+  resolvedBy: ResolvedBy,
+  defaultBranch: string,
+  atEpochMs: number,
+): string =>
+  writeResolvedComment(
+    `Resolved at ${isoSeconds(atEpochMs)}: no longer set aside (\`${setAside.reason}\` at \`${short(setAside.headSha)}\`) — ${describeResolvedBy(resolvedBy, defaultBranch)}.`,
+  );
+
+export const describeResolvedBy = (
+  resolvedBy: ResolvedBy,
+  defaultBranch: string,
+): string => {
+  switch (resolvedBy) {
+    case 'base-moved':
+      return `\`${defaultBranch}\` moved`;
+
+    case 'pushed':
+      return 'the branch was pushed';
+
+    case 'retry':
+      return 'a retry was asked for';
+  }
+};
+
+/** What ended a set-aside, as the resolved line says it. */
+export type ResolvedBy = 'base-moved' | 'pushed' | 'retry';
+
+/**
+ * How much of what a command printed the comment keeps, from its end, where
+ * git says what stopped it. GitHub takes a comment of up to 65,536
+ * characters.
+ */
+const OUTPUT_LINES = 60;
+
+const OUTPUT_CHARS = 20_000;
+
+const tailOf = (output: string): string => {
+  const kept = lastLines(output, OUTPUT_LINES);
+
+  const cut = kept.length > OUTPUT_CHARS ? kept.slice(-OUTPUT_CHARS) : kept;
+
+  return cut === output ? cut : `…\n${cut}`;
+};
+
+/** A fence longer than any run of backticks inside it, so none closes it. */
+const fenced = (text: string): string => {
+  const longest = Math.max(
+    0,
+    ...Array.from(text.matchAll(/`+/gu), ([run]) => run.length),
+  );
+
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+
+  return [`${fence}text`, text, fence].join('\n');
+};
+
+/**
+ * A sentence built from what git and GitHub said, as literal text: file
+ * names carry underscores, and nothing in it should mention anyone.
+ */
+const escapeMarkdown = (text: string): string =>
+  text.replaceAll(/[\\`*_[\]<>|~@]/gu, String.raw`\$&`);
+
+const short = (sha: string): string => sha.slice(0, 10);

package/src/unblock-prs/set-aside-comment.test.mts

@@ -0,0 +1,148 @@
+import { parseSetAsideComment } from 'pr-report-core';
+import {
+  resolvedCommentBody,
+  setAsideCommentBody,
+} from './set-aside-comment.mjs';
+import type { SkipRecord } from './types.mjs';
+
+describe(setAsideCommentBody, () => {
+  test('writes a record the script and the page read back', () => {
+    assert.deepStrictEqual(
+      parseSetAsideComment(setAsideCommentBody(skip(), 'main')),
+      {
+        kind: 'standing',
+        setAside: { reason: 'rebase-failed', headSha: HEAD, baseSha: BASE },
+        retry: false,
+      },
+    );
+  });
+
+  test('says why, and what takes it off', () => {
+    const body = setAsideCommentBody(skip(), 'main');
+
+    assert.include(
+      body,
+      '(`rebase-failed`): conflicts with origin/main in a\\_b.mts',
+    );
+
+    assert.include(
+      body,
+      'It stays aside until the branch is pushed again or `main` moves.',
+    );
+
+    assert.notInclude(body, '<details>');
+  });
+
+  test('links each failed check, and says a moved base does not clear it', () => {
+    const body = setAsideCommentBody(
+      skip({
+        reason: 'checks-failed',
+        detail: 'failed: code-check-result / result, no-skip-ci-label',
+        failedChecks: [
+          {
+            name: 'code-check-result / result',
+            link: 'https://example.test/run/1',
+          },
+          { name: 'no-skip-ci-label', link: '' },
+        ],
+      }),
+      'main',
+    );
+
+    assert.include(
+      body,
+      '- [code-check-result / result](https://example.test/run/1)\n- no-skip-ci-label',
+    );
+
+    assert.include(body, 'until the branch is pushed again: rebasing it');
+  });
+
+  test('asks for a bypass merge of a green one, and says a moved base does not clear it', () => {
+    const body = setAsideCommentBody(
+      skip({
+        reason: 'awaiting-bypass',
+        detail:
+          'every required check is green; @owner is the only owner of .github/workflows/ci.yml and its author, who may not approve it',
+      }),
+      'main',
+    );
+
+    assert.include(body, '(`awaiting-bypass`): every required check is green');
+
+    assert.include(
+      body,
+      "Nothing but a ruleset bypass merges it, which is a person's to do; auto-merge was left off.",
+    );
+
+    assert.include(
+      body,
+      'It stays aside until the branch is pushed again: rebasing it would only put the same checks through again. Tick the retry box to have it rebased and checked on the current `main`.',
+    );
+  });
+
+  test('folds what the command printed away, in a fence nothing inside closes', () => {
+    const body = setAsideCommentBody(
+      skip({ output: 'CONFLICT (content): ```\nhint: @someone' }),
+      'main',
+    );
+
+    assert.include(
+      body,
+      '<details><summary>What the command printed</summary>\n\n````text\nCONFLICT (content): ```\nhint: @someone\n````\n\n</details>',
+    );
+  });
+
+  test('keeps the end of a long output', () => {
+    const body = setAsideCommentBody(
+      skip({
+        output: Array.from({ length: 100 }, (_, i) => `line ${i}`).join('\n'),
+      }),
+      'main',
+    );
+
+    assert.include(body, '```text\n…\nline 40\n');
+
+    assert.include(body, 'line 99\n```');
+
+    assert.notInclude(body, 'line 39\n');
+  });
+
+  test('keeps a mention in the detail from mentioning anyone', () => {
+    assert.include(
+      setAsideCommentBody(skip({ detail: 'refused by @someone' }), 'main'),
+      String.raw`refused by \@someone`,
+    );
+  });
+});
+
+describe(resolvedCommentBody, () => {
+  test('is one line saying what ended it and when, read back as resolved', () => {
+    const body = resolvedCommentBody(
+      { reason: 'rebase-failed', headSha: HEAD, baseSha: BASE },
+      'base-moved',
+      'main',
+      Date.parse('2026-09-29T01:02:03.456Z'),
+    );
+
+    assert.deepStrictEqual(parseSetAsideComment(body), { kind: 'resolved' });
+
+    assert.strictEqual(
+      body.split('\n').at(-1),
+      'Resolved at 2026-09-29T01:02:03Z: no longer set aside (`rebase-failed` at `cccccccccc`) — `main` moved.',
+    );
+  });
+});
+
+const HEAD = 'c'.repeat(40);
+
+const BASE = 'a'.repeat(40);
+
+const skip = (overrides: Partial<SkipRecord> = {}): SkipRecord =>
+  ({
+    number: 7,
+    headSha: HEAD,
+    baseSha: BASE,
+    reason: 'rebase-failed',
+    detail: 'conflicts with origin/main in a_b.mts',
+    ...overrides,
+  }) as const;