pr-merge-queue 0.0.0-stage → 0.0.0

package/src/unblock-prs/stack.mts

@@ -0,0 +1,220 @@
+// cspell:ignore retarget retargeted
+
+/**
+ * Stacked pull requests: one whose base is another open pull request's
+ * branch rather than the default branch. Which pull request is on which is
+ * `pr-report-core`'s `stack.mts`, because the reports draw the same stacks;
+ * what this script does about them is decided here.
+ *
+ * The life of a layer, and what this script does at each point:
+ *
+ * 1. **Stacked.** Its base is the layer below, so its diff is its own and its
+ *    turn has not come: it is reported as waiting, and nothing else. It has
+ *    no auto-merge, and must not: nothing holds a pull request onto an
+ *    unprotected branch, so armed it would land in the layer below rather
+ *    than on the default branch. Nothing arms it — `open-pr` arms nothing,
+ *    and this script arms a pull request only when it picks it
+ *    (`armOnPick` in `rebase.mts`), which a stacked one never is.
+ * 2. **The layer below moves.** When this script rebases a pull request, it
+ *    replays every layer stacked on it onto the new head with
+ *    `git rebase --onto <new head> <old head>`, which carries exactly the
+ *    layer's own commits. Otherwise each layer would show the old commits of
+ *    the one below in its diff, and GitHub's own rebase, when that one
+ *    merges, would start from a head the layer does not contain.
+ * 3. **The layer below merges.** GitHub moves this one onto the default
+ *    branch. From then on it is an ordinary pull request, picked and armed
+ *    in its turn like any other, save one thing: it still carries the merged
+ *    layer's commits, so its diff shows that layer's changes as its own. The
+ *    next survey rebases them off with `--onto`, from the head that layer
+ *    merged at to its squash commit, and carries the layers above along —
+ *    without waiting for it to be queued, because that is an undoing of
+ *    GitHub's move, not a turn: it adds nothing from the base, and needs no
+ *    review to have finished. The ruleset merges a branch only when it is up
+ *    to date and only by squash, so that commit's tree is the merged head's,
+ *    and the rebased layer's tree is the one it had: only its history, and
+ *    so its diff, changes. A queued layer is left to its own rebase when it
+ *    is picked, which drops the same commits the same way on its way onto
+ *    the tip.
+ *
+ * A stack here is made by the base alone. GitHub's native stacks are not
+ * landed: GitHub refuses auto-merge on a pull request in one ("Auto-merge is
+ * not supported for stacked pull requests"), and keeps a layer in its stack
+ * after the one below has merged and it has been moved onto the default
+ * branch — so one is reported rather than picked, and merged by hand.
+ */
+
+import {
+  findStackParents,
+  isSafeRefName,
+  type NativeStackEntry,
+  type QueueOwner,
+} from 'pr-report-core';
+import { isMergeQueued, isSkipCiLabelled, wantsAutoRebase } from './labels.mjs';
+import type {
+  BaseChange,
+  BranchOf,
+  Classification,
+  PullRequest,
+  RetargetedLayer,
+  StackedOn,
+  TriageContext,
+} from './types.mjs';
+import { isVersionPullRequest } from './version-pr.mjs';
+
+/**
+ * The branch the pull request was stacked on, if the last change of its base
+ * moved it off that branch and onto the default one.
+ */
+export const retargetedFrom = (
+  changes: readonly BaseChange[],
+  defaultBranch: string,
+): string | undefined => {
+  const last = changes.at(-1);
+
+  return last?.to === defaultBranch && last.from !== defaultBranch
+    ? last.from
+    : undefined;
+};
+
+/** What to report for a stacked pull request in place of anything else. */
+export const stackedNote = (
+  pr: PullRequest,
+  parent: number,
+  context: TriageContext,
+): Classification =>
+  ({
+    kind: 'note',
+    note: `#${pr.number}: stacked on #${parent}, which merges first${
+      context.cyclic.has(pr.number)
+        ? ' — and on a cycle of stacks and Merge-After, so nothing here will move it'
+        : ''
+    }`,
+  }) as const;
+
+/**
+ * What to report instead of picking a pull request in one of GitHub's native
+ * stacks, which GitHub will not let this script arm.
+ */
+export const nativeStackNote = (
+  pr: PullRequest,
+  entry: NativeStackEntry,
+): Classification =>
+  ({
+    kind: 'note',
+    note: `#${pr.number}: layer ${entry.position} of ${entry.size} of GitHub's native stack #${entry.stack}, on which GitHub refuses auto-merge; merge it by hand (a stack made by the base alone needs no native stack)`,
+  }) as const;
+
+/**
+ * Why a layer cannot be carried along when the one below it moves, or
+ * `undefined` when it can. A fork's branch is not this repository's to push
+ * to, whatever its name.
+ */
+export const restackable = (pr: BranchOf): string | undefined =>
+  pr.state !== 'OPEN'
+    ? (`it is ${pr.state}` as const)
+    : pr.isCrossRepository
+      ? 'its branch is in a fork'
+      : !isSafeRefName(pr.headRefName)
+        ? (`branch name ${JSON.stringify(pr.headRefName)} will not be passed to a shell` as const)
+        : undefined;
+
+/**
+ * The pull requests this script rebases onto the default branch ahead of any
+ * turn: the bottom layer of a stack, or a lone pull request, that asked for it
+ * (`wantsAutoRebase`) and is paused by `skip-ci`, so the push costs no
+ * matrix. Whether it is actually behind is for the caller to ask
+ * git: `skip-ci` leaves the merge state at `BLOCKED` whatever the branch is.
+ * The version pull request is the release workflow's. Only the worker's own
+ * are moved (`owner.mts`): one set aside or claimed is a skill's or a
+ * person's until its comment is resolved or the claim ends.
+ */
+export const autoRebaseTargets = (
+  pullRequests: readonly PullRequest[],
+  defaultBranch: string,
+  {
+    owners,
+  }: Readonly<{
+    /** Who moves each queued pull request next (`owner.mts`). */
+    owners: ReadonlyMap<number, QueueOwner>;
+  }>,
+): readonly PullRequest[] =>
+  pullRequests.filter(
+    (pr) =>
+      pr.baseRefName === defaultBranch &&
+      !pr.isDraft &&
+      wantsAutoRebase(pr) &&
+      isSkipCiLabelled(pr) &&
+      !isVersionPullRequest(pr, defaultBranch) &&
+      restackable(pr) === undefined &&
+      owners.get(pr.number)?.owner === 'worker',
+  );
+
+/** Which open pull request each stacked one is on: child → parent. */
+export const stackParentsOf = (
+  pullRequests: readonly PullRequest[],
+  defaultBranch: string,
+): ReadonlyMap<number, number> =>
+  findStackParents(
+    pullRequests.map((pr) => ({
+      number: pr.number,
+      headRef: pr.headRefName,
+      baseRef: pr.baseRefName,
+      fromFork: pr.isCrossRepository,
+    })),
+    defaultBranch,
+  );
+
+/**
+ * What to remember of this survey's stacks for the next one: every layer, by
+ * the branch it is on, and every layer remembered before that is still on
+ * that branch. The second is a layer whose parent has merged while GitHub
+ * has yet to move it — no open pull request heads its base any longer, so
+ * the bases alone no longer say it is a layer, but it has still to come off
+ * one.
+ */
+export const stackedOnAfter = (
+  before: StackedOn | undefined,
+  pullRequests: readonly PullRequest[],
+  stackParents: ReadonlyMap<number, number>,
+): StackedOn =>
+  new Map(
+    pullRequests
+      .filter(
+        (pr) =>
+          stackParents.has(pr.number) ||
+          before?.get(pr.number) === pr.baseRefName,
+      )
+      .map((pr) => [pr.number, pr.baseRefName] as const),
+  );
+
+/**
+ * The pull requests the last survey saw stacked and this one sees on the
+ * default branch — before the first survey, every pull request on the
+ * default branch, whose timeline then says whether it came off a stack.
+ *
+ * A queued one is not among them: its own rebase, when it is picked, drops
+ * the merged layer's commits on its way onto the tip. Nor is anything that
+ * cannot be pushed to, or the version pull request, which was never a layer.
+ */
+export const retargetedLayers = (
+  before: StackedOn | undefined,
+  pullRequests: readonly PullRequest[],
+  defaultBranch: string,
+): readonly RetargetedLayer[] =>
+  pullRequests
+    .filter(
+      (pr) =>
+        pr.baseRefName === defaultBranch &&
+        !isMergeQueued(pr) &&
+        !isVersionPullRequest(pr, defaultBranch) &&
+        restackable(pr) === undefined,
+    )
+    .flatMap((pr): readonly RetargetedLayer[] => {
+      if (before === undefined) {
+        return [{ pr, from: undefined }];
+      }
+
+      const from = before.get(pr.number);
+
+      return from === undefined ? [] : [{ pr, from }];
+    });

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

@@ -0,0 +1,449 @@
+// cspell:ignore retarget retargeted
+
+import type { Claim } from 'pr-report-core';
+import { Arr } from 'ts-data-forge';
+import { ownerOf } from './owner.mjs';
+import {
+  autoRebaseTargets,
+  nativeStackNote,
+  restackable,
+  retargetedFrom,
+  retargetedLayers,
+  stackedNote,
+  stackedOnAfter,
+  stackParentsOf,
+} from './stack.mjs';
+import type {
+  BaseChange,
+  PullRequest,
+  SkipRecord,
+  TriageContext,
+} from './types.mjs';
+
+const NOW = Date.parse('2026-10-15T00:30:00Z');
+
+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: null,
+    labels: [],
+    ...fields,
+  }) as const;
+
+const context = (
+  stackParents: ReadonlyMap<number, number>,
+  cyclic: ReadonlySet<number> = new Set(),
+): TriageContext =>
+  ({
+    defaultBranch: 'main',
+    baseSha: 'b'.repeat(40),
+    skipped: new Map(),
+    claimed: new Map(),
+    owners: new Map(),
+    demoted: new Map(),
+    requiredContexts: [],
+    issueOrder: { closes: new Map(), startAfter: new Map() },
+    reviewRequirements: {
+      requireCodeOwnerReview: false,
+      requireConversationResolution: false,
+    },
+    openNumbers: new Set(),
+    dependencies: new Map(),
+    inherited: new Map(),
+    stackParents,
+    cycles: [],
+    cyclic,
+    releaseBlockers: [],
+  }) as const;
+
+const retarget = (from: string, to = 'main'): BaseChange =>
+  ({ from, to }) as const;
+
+describe(retargetedFrom, () => {
+  test('names the branch the last change of base moved it off', () => {
+    assert.strictEqual(
+      retargetedFrom([retarget('feature/1')], 'main'),
+      'feature/1',
+    );
+  });
+
+  test('is nothing for a pull request that never changed base', () => {
+    assert.isUndefined(retargetedFrom([], 'main'));
+  });
+
+  test('is nothing when the last change was away from the default branch', () => {
+    assert.isUndefined(
+      retargetedFrom(
+        [retarget('feature/1'), retarget('main', 'feature/2')],
+        'main',
+      ),
+    );
+  });
+
+  test('reads the last change of base, not the first', () => {
+    assert.strictEqual(
+      retargetedFrom(
+        [retarget('feature/1', 'feature/2'), retarget('feature/2')],
+        'main',
+      ),
+      'feature/2',
+    );
+  });
+});
+
+describe(stackedNote, () => {
+  test('says which layer it waits for', () => {
+    assert.deepStrictEqual(
+      stackedNote(pullRequest({ number: 2 }), 1, context(new Map([[2, 1]]))),
+      {
+        kind: 'note',
+        note: '#2: stacked on #1, which merges first',
+      },
+    );
+  });
+
+  test('says when the stack loops back on itself', () => {
+    const note = stackedNote(
+      pullRequest({ number: 2 }),
+      1,
+      context(
+        new Map([
+          [2, 1],
+          [1, 2],
+        ]),
+        new Set([1, 2]),
+      ),
+    );
+
+    assert.isTrue(note.kind === 'note' && note.note.includes('cycle'));
+  });
+});
+
+describe(restackable, () => {
+  test('keeps a layer this repository can push to', () => {
+    assert.isUndefined(restackable(pullRequest({ number: 2 })));
+  });
+
+  test("refuses a fork's branch", () => {
+    assert.isDefined(
+      restackable(pullRequest({ number: 2, isCrossRepository: true })),
+    );
+  });
+
+  test('refuses a branch name it will not pass to a shell', () => {
+    assert.isDefined(
+      restackable(pullRequest({ number: 2, headRefName: "it's" })),
+    );
+  });
+
+  test('refuses one that is not open', () => {
+    assert.isDefined(restackable(pullRequest({ number: 2, state: 'CLOSED' })));
+  });
+});
+
+describe(nativeStackNote, () => {
+  test('says why one in a native stack is not armed, and what to do', () => {
+    // GitHub keeps the layer in the stack after the one below it merged and
+    // it was moved onto `main`, and refuses auto-merge for as long.
+    assert.deepStrictEqual(
+      nativeStackNote(pullRequest({ number: 2 }), {
+        stack: 3,
+        position: 2,
+        size: 2,
+      }),
+      {
+        kind: 'note',
+        note: "#2: layer 2 of 2 of GitHub's native stack #3, on which GitHub refuses auto-merge; merge it by hand (a stack made by the base alone needs no native stack)",
+      },
+    );
+  });
+});
+
+describe(stackParentsOf, () => {
+  test('reads which open pull request each layer is on from the bases', () => {
+    assert.deepStrictEqual(
+      stackParentsOf(
+        [
+          pullRequest({ number: 1 }),
+          pullRequest({ number: 2, baseRefName: 'feature/1' }),
+          pullRequest({ number: 3, baseRefName: 'feature/2' }),
+        ],
+        'main',
+      ),
+      new Map([
+        [2, 1],
+        [3, 2],
+      ]),
+    );
+  });
+});
+
+describe(stackedOnAfter, () => {
+  test('remembers the branch each layer is stacked on', () => {
+    const pulls = [
+      pullRequest({ number: 1 }),
+      pullRequest({ number: 2, baseRefName: 'feature/1' }),
+    ] as const;
+
+    assert.deepStrictEqual(
+      stackedOnAfter(undefined, pulls, stackParentsOf(pulls, 'main')),
+      new Map([[2, 'feature/1']]),
+    );
+  });
+
+  test('keeps a layer whose parent merged until GitHub moves it', () => {
+    // #1 merged and left the open list, and GitHub has not moved #2 yet: the
+    // bases no longer make a stack, but #2 has still to come off one.
+    const pulls = [
+      pullRequest({ number: 2, baseRefName: 'feature/1' }),
+    ] as const;
+
+    assert.deepStrictEqual(
+      stackedOnAfter(
+        new Map([[2, 'feature/1']]),
+        pulls,
+        stackParentsOf(pulls, 'main'),
+      ),
+      new Map([[2, 'feature/1']]),
+    );
+  });
+
+  test('forgets a layer once it is on another base', () => {
+    const pulls = [pullRequest({ number: 2 })] as const;
+
+    assert.deepStrictEqual(
+      stackedOnAfter(
+        new Map([[2, 'feature/1']]),
+        pulls,
+        stackParentsOf(pulls, 'main'),
+      ),
+      new Map(),
+    );
+  });
+
+  test('forgets a layer that is no longer open', () => {
+    assert.deepStrictEqual(
+      stackedOnAfter(new Map([[2, 'feature/1']]), [], new Map()),
+      new Map(),
+    );
+  });
+});
+
+describe(retargetedLayers, () => {
+  test('names a layer that was stacked and is now on the default branch', () => {
+    const layer = pullRequest({ number: 2 });
+
+    assert.deepStrictEqual(
+      retargetedLayers(new Map([[2, 'feature/1']]), [layer], 'main'),
+      [{ pr: layer, from: 'feature/1' }],
+    );
+  });
+
+  test('is nothing for a layer GitHub has not moved yet', () => {
+    assert.deepStrictEqual(
+      retargetedLayers(
+        new Map([[2, 'feature/1']]),
+        [pullRequest({ number: 2, baseRefName: 'feature/1' })],
+        'main',
+      ),
+      [],
+    );
+  });
+
+  test('is nothing for a pull request that was never seen stacked', () => {
+    assert.deepStrictEqual(
+      retargetedLayers(new Map(), [pullRequest({ number: 2 })], 'main'),
+      [],
+    );
+  });
+
+  test('before the first survey, offers every pull request on the default branch, with the branch to be read from its timeline', () => {
+    const layer = pullRequest({ number: 2 });
+
+    assert.deepStrictEqual(
+      retargetedLayers(
+        undefined,
+        [layer, pullRequest({ number: 3, baseRefName: 'feature/2' })],
+        'main',
+      ),
+      [{ pr: layer, from: undefined }],
+    );
+  });
+
+  test('leaves a queued pull request to its own rebase when it is picked', () => {
+    assert.deepStrictEqual(
+      retargetedLayers(
+        new Map([[2, 'feature/1']]),
+        [pullRequest({ number: 2, labels: [{ name: 'merge-queued' }] })],
+        'main',
+      ),
+      [],
+    );
+  });
+
+  test("leaves a fork's branch and the version pull request alone", () => {
+    assert.deepStrictEqual(
+      retargetedLayers(
+        undefined,
+        [
+          pullRequest({ number: 2, isCrossRepository: true }),
+          pullRequest({ number: 3, headRefName: 'changeset-release/main' }),
+        ],
+        'main',
+      ),
+      [],
+    );
+  });
+});
+
+const labelled = (...names: readonly string[]): PullRequest['labels'] =>
+  names.map((name) => ({ name }));
+
+const targets = (
+  pullRequests: readonly PullRequest[],
+  skipped: ReadonlyMap<number, SkipRecord> = new Map(),
+  claimed: ReadonlyMap<number, Claim> = new Map(),
+): readonly number[] =>
+  autoRebaseTargets(pullRequests, 'main', {
+    owners: new Map(
+      Arr.generate(function* () {
+        for (const pr of pullRequests) {
+          const owner = ownerOf(pr, {
+            defaultBranch: 'main',
+            skipped,
+            claimed,
+            stackParents: new Map(),
+            cyclic: new Set(),
+            nowEpochMs: NOW,
+          });
+
+          if (owner !== undefined) {
+            yield [pr.number, owner] as const;
+          }
+        }
+      }),
+    ),
+  }).map((pr) => pr.number);
+
+describe(autoRebaseTargets, () => {
+  test('takes a paused pull request labelled auto-rebase, and a paused queued one', () => {
+    assert.deepStrictEqual(
+      targets([
+        pullRequest({ number: 1, labels: labelled('skip-ci', 'auto-rebase') }),
+        pullRequest({ number: 2, labels: labelled('skip-ci', 'merge-queued') }),
+      ]),
+      [1, 2],
+    );
+  });
+
+  test('leaves a paused pull request that asked for neither', () => {
+    assert.deepStrictEqual(
+      targets([pullRequest({ number: 1, labels: labelled('skip-ci') })]),
+      [],
+    );
+  });
+
+  test('leaves one that skip-ci is not on, since a push would run the matrix', () => {
+    assert.deepStrictEqual(
+      targets([
+        pullRequest({ number: 1, labels: labelled('auto-rebase') }),
+        pullRequest({ number: 2, labels: labelled('merge-queued') }),
+      ]),
+      [],
+    );
+  });
+
+  test('leaves a draft, a layer, a fork and the version pull request', () => {
+    assert.deepStrictEqual(
+      targets([
+        pullRequest({
+          number: 1,
+          isDraft: true,
+          labels: labelled('skip-ci', 'auto-rebase'),
+        }),
+        pullRequest({
+          number: 2,
+          baseRefName: 'feature/1',
+          labels: labelled('skip-ci', 'auto-rebase'),
+        }),
+        pullRequest({
+          number: 3,
+          isCrossRepository: true,
+          labels: labelled('skip-ci', 'auto-rebase'),
+        }),
+        pullRequest({
+          number: 4,
+          headRefName: 'changeset-release/main',
+          labels: labelled('skip-ci', 'merge-queued'),
+        }),
+      ]),
+      [],
+    );
+  });
+
+  test('leaves one set aside at its head, whatever the base', () => {
+    const given = pullRequest({
+      number: 1,
+      labels: labelled('skip-ci', 'auto-rebase'),
+    });
+
+    assert.deepStrictEqual(
+      targets(
+        [given],
+        new Map([
+          [
+            1,
+            {
+              number: 1,
+              headSha: given.headRefOid,
+              baseSha: 'b'.repeat(40),
+              reason: 'rebase-failed',
+              detail: 'conflict',
+            },
+          ],
+        ]),
+      ),
+      [],
+    );
+  });
+
+  test('leaves one a session has claimed, until its claim ends', () => {
+    assert.deepStrictEqual(
+      targets(
+        [
+          pullRequest({
+            number: 1,
+            labels: labelled('skip-ci', 'auto-rebase'),
+          }),
+          pullRequest({
+            number: 2,
+            labels: labelled('skip-ci', 'auto-rebase'),
+          }),
+        ],
+        new Map(),
+        new Map([
+          [
+            1,
+            {
+              headSha: pullRequest({ number: 1 }).headRefOid,
+              by: 'unblock-wren',
+              at: '2026-10-15T00:00:00Z',
+            },
+          ],
+        ]),
+      ),
+      [2],
+    );
+  });
+});