pr-merge-queue 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,100 @@
+import { describeAction, orderCandidates } from './triage.mjs';
+import type { PullRequest } from './types.mjs';
+
+describe(orderCandidates, () => {
+  // The ranks themselves are `pr-report-core`'s; what this run demoted is
+  // what only the worker knows.
+
+  // Last of all, the release included: the release is known to be able to
+  // merge, and this one is known to have sat green without merging.
+  test('puts a pull request that sat green without merging last', () => {
+    assert.deepStrictEqual(
+      numbers(
+        orderCandidates(
+          [
+            pullRequest({ number: 1 }),
+            pullRequest({
+              number: 2,
+              headRefName: 'changeset-release/main',
+            }),
+            pullRequest({ number: 3, mergeStateStatus: 'DIRTY' }),
+            pullRequest({ number: 4 }),
+          ],
+          { defaultBranch: 'main', demoted: new Map([[1, 'a'.repeat(40)]]) },
+        ),
+      ),
+      [4, 3, 2, 1],
+    );
+  });
+
+  test('forgets the demotion once someone else has pushed', () => {
+    assert.deepStrictEqual(
+      numbers(
+        orderCandidates(
+          [
+            pullRequest({ number: 1, headRefOid: 'c'.repeat(40) }),
+            pullRequest({ number: 2 }),
+          ],
+          { defaultBranch: 'main', demoted: new Map([[1, 'a'.repeat(40)]]) },
+        ),
+      ),
+      [1, 2],
+    );
+  });
+});
+
+describe(describeAction, () => {
+  test('arms what it picks', () => {
+    assert.strictEqual(
+      describeAction(pullRequest({ number: 1 }), 'main', {
+        stackParents: new Map(),
+        toArm: new Set([1]),
+        bypass: new Map(),
+      }),
+      'rebase onto main, arm auto-merge',
+    );
+  });
+
+  test('leaves auto-merge off one that needs a bypass merge, and still runs its checks', () => {
+    assert.strictEqual(
+      describeAction(
+        pullRequest({
+          number: 1,
+          labels: [queued, { name: 'skip-ci' }],
+          autoMergeRequest: null,
+        }),
+        'main',
+        {
+          stackParents: new Map(),
+          toArm: new Set(),
+          bypass: new Map([[1, 'the author is the only owner']]),
+        },
+      ),
+      'rebase onto main, leave auto-merge off (the author is the only owner, so it needs a bypass merge), then take skip-ci off it',
+    );
+  });
+});
+
+const queued = { name: 'merge-queued' } as const;
+
+const numbers = (prs: readonly PullRequest[]): readonly number[] =>
+  prs.map((pr) => pr.number);
+
+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: 'BEHIND',
+    autoMergeRequest: {},
+    labels: [queued],
+    ...fields,
+  }) as const;

package/src/unblock-prs/types.mts

@@ -0,0 +1,358 @@
+// cspell:ignore unlabel retargeted
+
+/** The shapes every module here passes around. */
+
+import type {
+  Claim,
+  QueueContext,
+  QueueOwner,
+  RulesetRequirements,
+  SetAsideComment,
+  SetAsideReason,
+  ChecksSummary as SharedChecksSummary,
+} from 'pr-report-core';
+import * as t from 'ts-fortress';
+import type { StrictPick } from 'ts-type-forge';
+
+/** The fields read of each pull request (`github.mts`'s `listPullRequests`). */
+export const PullRequestSchema = t.record({
+  number: t.number(),
+  /** The node id, which the GraphQL mutation that arms auto-merge takes. */
+  id: t.string(),
+  title: t.string(),
+  /** Where a `Merge-After:` declaration is read from. */
+  body: t.string(),
+  state: t.string(),
+  headRefName: t.string(),
+  headRefOid: t.string(),
+  baseRefName: t.string(),
+  /**
+   * Whether the head branch lives in a fork. A fork's branch is never the
+   * parent of a stack, and never pushed to when one is restacked.
+   */
+  isCrossRepository: t.boolean(),
+  isDraft: t.boolean(),
+  mergeStateStatus: t.string(),
+  autoMergeRequest: t.unknown(),
+  labels: t.array(t.record({ name: t.string() })),
+});
+
+export type PullRequest = t.TypeOf<typeof PullRequestSchema>;
+
+export const PullRequestListSchema = t.array(PullRequestSchema);
+
+/**
+ * What moving a branch reads of its pull request, which `push-fixed-pr` fills
+ * in from the REST API rather than from GraphQL.
+ */
+export type BranchOf = StrictPick<
+  PullRequest,
+  | 'baseRefName'
+  | 'headRefName'
+  | 'headRefOid'
+  | 'isCrossRepository'
+  | 'number'
+  | 'state'
+>;
+
+/**
+ * Why a pull request was set aside: `pr-report-core`'s list, where each
+ * reason is given its owner (`queue-owner.mts`), so that a reason this
+ * script writes is one every reader knows.
+ */
+export type SkipReason = SetAsideReason;
+
+/**
+ * Why a pull request is being left alone, and the state it was in at the
+ * time. A record stops applying as soon as that state changes: a push to the
+ * branch clears every reason, and every reason but `checks-failed` and
+ * `awaiting-bypass` also clears when the base moves. `awaiting-bypass` is the
+ * one that is not a failure: every required check is green on a pull request
+ * nothing but a ruleset bypass will merge, and what is left is a person's
+ * (`pr-report-core`'s `review-hold.mts`). See `skipStillApplies`.
+ */
+export type SkipRecord = Readonly<{
+  number: number;
+  headSha: string;
+  baseSha: string;
+  reason: SkipReason;
+  /** One sentence, which the log says and the comment leads with. */
+  detail: string;
+  /** For `checks-failed`: each failed required check, with its run. */
+  failedChecks?: ChecksSummary['failedRuns'];
+  /** What the command that failed printed, which the comment folds away. */
+  output?: string;
+}>;
+
+export type SkipRecords = ReadonlyMap<number, SkipRecord>;
+
+/**
+ * One of this account's set-aside comments on a pull request, and what it
+ * says. `pr-report-core`'s `set-aside.mts` says what it is.
+ */
+export type OwnSetAsideComment = Readonly<{
+  /** The REST id, which editing it takes. */
+  databaseId: number;
+  says: SetAsideComment;
+}>;
+
+/**
+ * Pull request number → the head it was demoted at: the pull requests picked
+ * last, after a watch saw them green and still open. See `demotions.mts`.
+ */
+export type Demotions = ReadonlyMap<number, string>;
+
+/**
+ * What the ruleset asks of a review, read by `pr-report-core`'s
+ * `review-hold.mts`.
+ */
+export type ReviewRequirements = StrictPick<
+  RulesetRequirements,
+  'requireCodeOwnerReview' | 'requireConversationResolution'
+>;
+
+export type Survey = Readonly<{
+  pullRequests: readonly PullRequest[];
+  /** The tip of the default branch at the time of the survey. */
+  baseSha: string;
+  /** The contexts the ruleset requires, empty when they cannot be read. */
+  requiredContexts: readonly string[];
+  /** Nothing is required when the rules cannot be read. */
+  reviewRequirements: ReviewRequirements;
+}>;
+
+/**
+ * `pr-report-core`'s verdict over the required contexts — the one `pr-report`
+ * and the page reach too — with what the worker reads besides.
+ */
+export type ChecksSummary = SharedChecksSummary &
+  Readonly<{
+    /**
+     * {@link SharedChecksSummary.failed}, each with its run's link, which a
+     * set-aside comment points at.
+     */
+    failedRuns: readonly Readonly<{ name: string; link: string }>[];
+    /**
+     * Checks on the head that have not finished and are not among `pending`,
+     * mostly the jobs a required aggregate is still waiting on.
+     */
+    running: readonly string[];
+  }>;
+
+/** What a survey knows before the declared merge order has been read. */
+export type TriageBase = Readonly<{
+  defaultBranch: string;
+  baseSha: string;
+  skipped: SkipRecords;
+  /** The claims that still hold their pull requests (`claims.mts`). */
+  claimed: ReadonlyMap<number, Claim>;
+  demoted: Demotions;
+  requiredContexts: readonly string[];
+  reviewRequirements: ReviewRequirements;
+  /** What the issues the pull requests close add to the merge order. */
+  issueOrder: IssueOrder;
+}>;
+
+/**
+ * Which open issues each open pull request closes, and each such issue's
+ * `Start-After:`, which the pull request closing it inherits as a merge
+ * order (`docs/issue-start-after.md`).
+ */
+export type IssueOrder = Readonly<{
+  closes: ReadonlyMap<number, readonly number[]>;
+  startAfter: ReadonlyMap<number, readonly number[]>;
+}>;
+
+/**
+ * What triage decides each pull request against: the survey, and what the
+ * open pull requests say about one another (`pr-report-core`'s
+ * `queue-order.mts`).
+ */
+export type TriageContext = TriageBase & QueueContext;
+
+/** What one survey says about one pull request. */
+export type Classification = Readonly<
+  | { kind: 'candidate' }
+  | { kind: 'failing'; summary: ChecksSummary }
+  | { kind: 'held'; reason: string }
+  | { kind: 'ignore' }
+  | { kind: 'in-flight' }
+  | { kind: 'note'; note: string }
+>;
+
+export type Failing = Readonly<{ pr: PullRequest; summary: ChecksSummary }>;
+
+export type Triage = Readonly<{
+  /** How many of the surveyed pull requests this script has anything to say about. */
+  inScope: number;
+  /**
+   * The queued pull requests this cycle may act on — behind the base, or
+   * paused by `skip-ci`, or both — with nothing they declared `Merge-After`
+   * on still open, and on the default branch rather than stacked. Lowest
+   * number first.
+   */
+  candidates: readonly PullRequest[];
+  /**
+   * The candidates and the pull requests in flight that have no auto-merge
+   * yet, which this script arms when it picks them. See `armOnPick` in
+   * `rebase.mts`.
+   */
+  toArm: ReadonlySet<number>;
+  /** Which open pull request each stacked one is on: child → parent. */
+  stackParents: ReadonlyMap<number, number>;
+  /**
+   * The candidates and the pull requests in flight that only a ruleset bypass
+   * will merge, with why (`pr-report-core`'s `review-hold.mts`): their checks
+   * are run all the same, and they are never armed.
+   */
+  bypass: ReadonlyMap<number, string>;
+  /** Up to date with checks still running, or clean and about to merge. */
+  inFlight: readonly PullRequest[];
+  /** Up to date, but a required check has failed. */
+  failing: readonly Failing[];
+  /**
+   * Queued pull requests that would have been picked or watched but for
+   * their review — an owner's approval or a conversation still open — each
+   * as a note like the ones below.
+   */
+  held: readonly string[];
+  /** Everything else, with the reason it was set aside. */
+  notes: readonly string[];
+  /** The `Merge-After` cycles, each starting at its lowest number. */
+  cycles: readonly (readonly number[])[];
+  /**
+   * Who moves each queued pull request next (`owner.mts`), the same answer
+   * `pr-report` gives the skill. "3a" moves only the worker's.
+   */
+  owners: ReadonlyMap<number, QueueOwner>;
+}>;
+
+/**
+ * One change of a pull request's base, from its timeline. `stack.mts` reads
+ * the last of them to tell which branch GitHub moved a layer off.
+ */
+export type BaseChange = Readonly<{ from: string; to: string }>;
+
+export type WatchOutcome =
+  | 'auto-merge-disabled'
+  | 'awaiting-bypass'
+  | 'behind-again'
+  | 'checks-failed'
+  | 'closed'
+  | 'error'
+  | 'head-moved'
+  | 'merged'
+  | 'not-merging'
+  | 'stopped'
+  | 'timeout'
+  | 'skip-ci-labelled';
+
+/**
+ * How a watch ended, and for an outcome that sets the pull request aside,
+ * what its comment says: `detail` and, when checks failed, which.
+ */
+export type Watched = Readonly<{
+  outcome: WatchOutcome;
+  detail?: string;
+  failedChecks?: ChecksSummary['failedRuns'];
+}>;
+
+/**
+ * Pull request number → the branch it was last seen stacked on: every layer
+ * of a stack, and one whose parent has left the open list while GitHub has
+ * yet to move it off that parent's branch. A layer that leaves this map by
+ * landing on the default branch is one `stack.mts` may have to rebase off
+ * the layer that merged below it.
+ */
+export type StackedOn = ReadonlyMap<number, string>;
+
+/**
+ * A pull request on the default branch that may have been moved there when
+ * the layer below it merged: `from` is that layer's branch, or `undefined`
+ * when it has to be read from the pull request's timeline.
+ */
+export type RetargetedLayer = Readonly<{
+  pr: PullRequest;
+  from: string | undefined;
+}>;
+
+/** What the loop remembers about how long the list has sat still. */
+export type Quiet = Readonly<{
+  /** The last survey's fingerprint; none before any survey has succeeded. */
+  fingerprint: string | undefined;
+  /** How many surveys in a row have seen what the one before them saw. */
+  unchanged: number;
+}>;
+
+/**
+ * What one run carries from cycle to cycle: the pull requests it has given up
+ * on, the ones it picks last, the ones it has acted on and last saw open,
+ * where the base was when it last looked, how long the list has sat still,
+ * and which pull requests were stacked on what.
+ */
+export type LoopState = Readonly<{
+  skipped: SkipRecords;
+  demoted: Demotions;
+  tracked: ReadonlySet<number>;
+  baseSha: string | undefined;
+  quiet: Quiet;
+  /** `undefined` until the first survey, which has nothing to compare with. */
+  stackedOn: StackedOn | undefined;
+}>;
+
+export type CycleResult = Readonly<{
+  state: LoopState;
+  next: 'idle' | 'stop' | 'survey';
+  /**
+   * The records the cycle acted from — what it carried over, less what no
+   * longer applied, plus what the comments on the pull requests said. A
+   * record in `state` that is not among these, or differs from its entry, is
+   * one this cycle set aside, and the one its comment has to say.
+   */
+  settled: SkipRecords;
+}>;
+
+/**
+ * How far `advance` got with one pull request. `moved` is the branch moving
+ * under it — someone else, the skill or a person, is taking that pull
+ * request forward — which is neither progress nor a failure of the pull
+ * request.
+ */
+export type Advanced = Readonly<
+  | { kind: 'advanced'; head: string }
+  | { kind: 'moved' }
+  | { kind: 'stale-merge-state' }
+>;
+
+/**
+ * What `autoFix` did about a failed head. `declined` covers everything that
+ * is not a fixer's diff and everything that went wrong on the way; either way
+ * the failure stands and is the skill's. `moved` is what it is for `advance`.
+ */
+export type AutoFixed = Readonly<
+  | { kind: 'declined'; detail: string }
+  | { kind: 'moved' }
+  | { kind: 'pushed'; head: string; commands: readonly string[] }
+>;
+
+export type RebaseFailure = Readonly<{
+  reason:
+    | 'already-in-base'
+    | 'arm-failed'
+    | 'push-failed'
+    | 'rebase-failed'
+    | 'unlabel-failed';
+  detail: string;
+  /** What the command that failed printed, when there is more than `detail`. */
+  output?: string;
+}>;
+
+/**
+ * What `advance` is asked to do besides the rebase: arm auto-merge, and carry
+ * the layers stacked on it along.
+ */
+export type AdvancePlan = Readonly<{
+  arm: boolean;
+  /** Every open layer above it, each after the one it is on. */
+  descendants: readonly PullRequest[];
+}>;

package/src/unblock-prs/util.mts

@@ -0,0 +1,78 @@
+/**
+ * The small things every other module here needs: the stop signal and what
+ * listens to it. Quoting and logging are shared with the other commands, in
+ * `tools/scripts/lib/`.
+ */
+
+import { setTimeout as sleep } from 'node:timers/promises';
+import { log } from '../lib/index.mjs';
+
+/**
+ * Aborted by SIGINT / SIGTERM; every sleep listens to it.
+ *
+ * One per process, and it is never reset: an `AbortController` cannot be
+ * un-aborted, and nothing here wants to be. The stop it carries means "this
+ * run is over" — the loop in `main.mts` leaves, the process exits, and a
+ * second SIGINT does not wait for any of that (`installStopHandlers` arms
+ * `process.exit(130)` for it). The signal handlers it serves are
+ * process-scoped too, so a controller of the same scope is the honest shape.
+ *
+ * What that rules out is calling the loop twice in one process: the second
+ * call would find the signal already aborted and return immediately. So the
+ * loop has one caller, the `unblock-prs` command (`src/cmd/unblock-prs.mts`),
+ * which runs it once, and it is not exported from the package.
+ */
+const stopController = new AbortController();
+
+/**
+ * Read through a call rather than directly, because the flag flips inside a
+ * signal handler and TypeScript would otherwise narrow it to `false` for the
+ * rest of any block that has already tested it.
+ */
+export const stopRequested = (): boolean => stopController.signal.aborted;
+
+/**
+ * The SHA `git ls-remote` lists for `branch`, by its whole ref name. A ref
+ * pattern given to `ls-remote` matches on the tail of the name, so
+ * `ls-remote origin main` lists `refs/heads/changeset-release/main` too, and
+ * first; the first line is not the branch asked for.
+ */
+export const headShaFromListing = (
+  listing: string,
+  branch: string,
+): string | undefined =>
+  listing
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/u))
+    .find(([, ref]) => ref === `refs/heads/${branch}`)?.[0];
+
+export const lastLines = (text: string, count: number): string =>
+  text.trim().split('\n').slice(-count).join('\n');
+
+/** Sleeps, returning early when a stop has been requested. */
+export const pause = async (ms: number): Promise<void> => {
+  if (stopRequested()) {
+    return;
+  }
+
+  await sleep(ms, undefined, { signal: stopController.signal }).catch(
+    () => undefined,
+  );
+};
+
+export const installStopHandlers = (): void => {
+  process.once('SIGINT', onSignal);
+
+  process.once('SIGTERM', onSignal);
+};
+
+const onSignal = (signal: NodeJS.Signals): void => {
+  log(`${signal}: finishing the current step, then stopping.`);
+
+  stopController.abort();
+
+  // A second signal is not a request to be tidy.
+  process.once(signal, () => {
+    process.exit(130);
+  });
+};

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

@@ -0,0 +1,26 @@
+import { headShaFromListing } from './util.mjs';
+
+describe(headShaFromListing, () => {
+  const listing = [
+    '870363ea81583350b5f32664fa27c27fd7b6c9b2\trefs/heads/changeset-release/main',
+    '71f48d84b3fffa6a45b654836e9357153e1e949e\trefs/heads/main',
+  ].join('\n');
+
+  test('reads the branch named, not one whose name ends with it', () => {
+    assert.strictEqual(
+      headShaFromListing(listing, 'main'),
+      '71f48d84b3fffa6a45b654836e9357153e1e949e',
+    );
+
+    assert.strictEqual(
+      headShaFromListing(listing, 'changeset-release/main'),
+      '870363ea81583350b5f32664fa27c27fd7b6c9b2',
+    );
+  });
+
+  test('is undefined for a branch the listing does not have', () => {
+    assert.isUndefined(headShaFromListing(listing, 'release/main'));
+
+    assert.isUndefined(headShaFromListing('', 'main'));
+  });
+});

package/src/unblock-prs/version-pr.mts

@@ -0,0 +1,112 @@
+/**
+ * The version pull request — `changeset-release/<base>`, opened and rewritten
+ * by `changesets/action` — and what holds it back.
+ *
+ * It is the one pull request here that is derived rather than written. On
+ * every push to the base the release workflow rebuilds the branch from the
+ * tip, force-pushes it, and overwrites the title and body through
+ * `updatePullRequest`. Two consequences shape everything in this file:
+ *
+ * - **Nothing written in its body survives.** A `Merge-After:` trailer put
+ *   there is wiped by the next push to the base — which, when several pull
+ *   requests are queued, is exactly while the ordering still mattered. So the
+ *   ordering is declared from the other side, with `blocks-release` on the
+ *   pull request the release is waiting for.
+ * - **It must not be rebased.** `unblock-prs` and the release workflow would
+ *   be two things force-pushing one branch. Worse, a rebase lands the old
+ *   version commit on a tip that carries a changeset it never consumed, so
+ *   what merges is a release missing the change the queue was assembled for.
+ *   Whether the branch is ready is not this script's to fix: it is the
+ *   release workflow's, and the only thing to do here is wait for it.
+ */
+
+import { BLOCKS_RELEASE_LABEL, isVersionBranch } from 'pr-report-core';
+import { Result } from 'ts-data-forge';
+import { git, sh } from '../lib/index.mjs';
+import type { Classification, PullRequest, TriageContext } from './types.mjs';
+import { lastLines } from './util.mjs';
+
+/**
+ * Whether this is the version pull request, by the branch it comes from
+ * (`isVersionBranch`).
+ */
+export const isVersionPullRequest = (
+  pr: PullRequest,
+  defaultBranch: string,
+): boolean => isVersionBranch(pr.headRefName, defaultBranch);
+
+/**
+ * What to report while pull requests labelled `blocks-release` are open.
+ * Nothing here can clear it: a `blocks-release` pull request ends when a
+ * person merges or closes it.
+ */
+export const releaseBlockedNote = (
+  pr: PullRequest,
+  by: readonly Readonly<{ number: number; isDraft: boolean }>[],
+): Classification =>
+  ({
+    kind: 'note',
+    note: `#${pr.number}: ${BLOCKS_RELEASE_LABEL} on ${by
+      .map(
+        (blocker) => `#${blocker.number}${blocker.isDraft ? ' (draft)' : ''}`,
+      )
+      .join(', ')} — still open, so the release waits`,
+  }) as const;
+
+/**
+ * What to report while the branch was built on a stale tip, which the
+ * release workflow's next run rebuilds.
+ */
+export const releaseStaleNote = (
+  pr: PullRequest,
+  context: Readonly<{ defaultBranch: string; baseSha: string }>,
+): Classification =>
+  ({
+    kind: 'note',
+    note: `#${pr.number}: built before ${context.defaultBranch} reached ${context.baseSha.slice(0, 10)}; waiting for the release workflow to rebuild it`,
+  }) as const;
+
+/**
+ * Whether the branch was built on the current tip of the base — the question
+ * `mergeStateStatus` is asked everywhere else here, asked of git instead —
+ * or, when git cannot say, the note to report.
+ *
+ * GitHub's answer is computed asynchronously and cached, and being wrong
+ * about this one releases a set the branch was built before, so it is worth
+ * a fetch. `git merge-base` rather than `--is-ancestor`, whose "no" is an
+ * exit status this module could not tell apart from a git that failed.
+ */
+export const isRebuiltOnBaseTip = async (
+  pr: PullRequest,
+  context: TriageContext,
+): Promise<Result<boolean, Classification>> => {
+  const answered = await mergeBaseIsTip(pr, context);
+
+  return Result.isErr(answered)
+    ? Result.err({
+        kind: 'note',
+        note: `#${pr.number}: cannot tell whether it was rebuilt on ${context.baseSha.slice(0, 10)}: ${answered.value}`,
+      })
+    : answered;
+};
+
+const mergeBaseIsTip = async (
+  pr: PullRequest,
+  context: TriageContext,
+): Promise<Result<boolean, string>> => {
+  const fetched = await git(
+    `git fetch --quiet origin ${sh(context.defaultBranch)} ${sh(pr.headRefName)}`,
+  );
+
+  if (Result.isErr(fetched)) {
+    return Result.err(`fetch failed: ${lastLines(fetched.value, 2)}`);
+  }
+
+  const mergeBase = await git(
+    `git merge-base ${sh(context.baseSha)} ${sh(pr.headRefOid)}`,
+  );
+
+  return Result.isErr(mergeBase)
+    ? Result.err(`merge-base failed: ${lastLines(mergeBase.value, 2)}`)
+    : Result.ok(mergeBase.value.trim() === context.baseSha);
+};