pr-merge-queue 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,82 @@
+/**
+ * The one sentence a set-aside record carries: what the log says, and what
+ * the comment on the pull request leads with.
+ *
+ * Each says what a reader would otherwise have to go and find — which check,
+ * which file, which hold — rather than restate the reason. The comment has
+ * room for more, and `set-aside-comment.mts` adds it: the failed checks with
+ * their runs, and what the command printed.
+ */
+
+import { Arr } from 'ts-data-forge';
+import { describeWaitingOn } from './checks.mjs';
+import type { ChecksSummary } from './types.mjs';
+
+/**
+ * The failed required checks by name, and each with its run, which the
+ * comment links so that the failure itself is one click away.
+ */
+export const describeFailedChecks = (
+  summary: ChecksSummary,
+): Readonly<{ detail: string; failedChecks: ChecksSummary['failedRuns'] }> =>
+  ({
+    detail: `failed: ${summary.failed.join(', ')}`,
+    failedChecks: summary.failedRuns,
+  }) as const;
+
+/**
+ * What holds a pull request whose required checks are all green.
+ * `reviewDecision` is GitHub's: `REVIEW_REQUIRED` when a review the
+ * rules ask for is missing, which with `required_approving_review_count: 0`
+ * leaves a code owner's; empty when the rules ask for none.
+ */
+export const describeHold = (
+  mergeStateStatus: string,
+  reviewDecision: string | undefined,
+): string => {
+  const head = `green but ${mergeStateStatus}` as const;
+
+  return reviewDecision === 'REVIEW_REQUIRED'
+    ? `${head}: a required review is missing (a code owner?)`
+    : reviewDecision === 'CHANGES_REQUESTED'
+      ? `${head}: changes requested`
+      : `${head}: an unresolved conversation, or armed by who may not merge?`;
+};
+
+/** What the watch was still waiting on when it gave up. */
+export const describeTimeout = (
+  summary: ChecksSummary,
+  timeoutMin: number,
+): string =>
+  `after ${timeoutMin} min, still waiting on ${describeWaitingOn(summary)}` as const;
+
+/**
+ * The files a rebase stopped on, or when git named none — a rebase can fail
+ * before it reaches a merge — the end of what it printed.
+ */
+export const describeConflict = (
+  conflicted: readonly string[],
+  output: string,
+  onto: string,
+): string =>
+  Arr.isNonEmpty(conflicted)
+    ? (`conflicts with ${onto} in ${conflicted.join(', ')}` as const)
+    : (`rebase onto ${onto} failed: ${output.replaceAll(/\s+/gu, ' ').trim()}` as const);
+
+/**
+ * The end of what a failed command printed. Node's message starts with
+ * `Command failed: <the command>`, which says nothing the reason does not and
+ * crowds out what does: an arm that failed was once reported as its own
+ * GraphQL mutation, cut off before GitHub's answer. Only a command that
+ * printed nothing is left with that line.
+ */
+export const describeCommandFailure = (message: string): string => {
+  const lines = message.trim().split('\n');
+
+  const printed =
+    lines[0]?.startsWith(COMMAND_FAILED) === true ? Arr.tail(lines) : lines;
+
+  return Arr.takeLast(Arr.isNonEmpty(printed) ? printed : lines, 2).join('\n');
+};
+
+const COMMAND_FAILED = 'Command failed: ';

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

@@ -0,0 +1,131 @@
+import {
+  describeCommandFailure,
+  describeConflict,
+  describeFailedChecks,
+  describeHold,
+  describeTimeout,
+} from './set-aside-detail.mjs';
+import type { ChecksSummary } from './types.mjs';
+
+describe(describeFailedChecks, () => {
+  test('names the failed checks and keeps each run', () => {
+    const failed = [
+      {
+        name: 'code-check-result / result',
+        link: 'https://example.test/1',
+      },
+      {
+        name: 'style-check-result / result',
+        link: 'https://example.test/2',
+      },
+    ] as const;
+
+    assert.deepStrictEqual(
+      describeFailedChecks(
+        summary({ failed: failed.map(({ name }) => name), failedRuns: failed }),
+      ),
+      {
+        detail:
+          'failed: code-check-result / result, style-check-result / result',
+        failedChecks: failed,
+      },
+    );
+  });
+});
+
+describe(describeHold, () => {
+  test('says a review is missing', () => {
+    assert.strictEqual(
+      describeHold('BLOCKED', 'REVIEW_REQUIRED'),
+      'green but BLOCKED: a required review is missing (a code owner?)',
+    );
+  });
+
+  test('says changes were requested', () => {
+    assert.strictEqual(
+      describeHold('BLOCKED', 'CHANGES_REQUESTED'),
+      'green but BLOCKED: changes requested',
+    );
+  });
+
+  // #2069 was set aside as "green but not merged", which named nothing.
+  test('names what is left when no review is missing', () => {
+    for (const reviewDecision of ['APPROVED', '', undefined]) {
+      assert.strictEqual(
+        describeHold('CLEAN', reviewDecision),
+        'green but CLEAN: an unresolved conversation, or armed by who may not merge?',
+      );
+    }
+  });
+});
+
+describe(describeTimeout, () => {
+  test('names what it was still waiting on', () => {
+    assert.strictEqual(
+      describeTimeout(summary({ running: ['code-check (ws:fix:lint)'] }), 90),
+      'after 90 min, still waiting on code-check (ws:fix:lint) (running)',
+    );
+  });
+});
+
+describe(describeConflict, () => {
+  test('names the conflicting files', () => {
+    assert.strictEqual(
+      describeConflict(['a.mts', 'b/c.mts'], 'CONFLICT (content): …', 'main'),
+      'conflicts with main in a.mts, b/c.mts',
+    );
+  });
+
+  test("falls back to git's own words when no file is named", () => {
+    assert.strictEqual(
+      describeConflict([], 'error: could not apply 1234abc\nhint: …', 'main'),
+      'rebase onto main failed: error: could not apply 1234abc hint: …',
+    );
+  });
+});
+
+describe(describeCommandFailure, () => {
+  test('keeps what the command printed rather than the command', () => {
+    // The command line alone once filled a 140-character status, which is
+    // how GitHub's answer came to be cut off.
+    assert.strictEqual(
+      describeCommandFailure(
+        "Command failed: gh api graphql -f 'id=PR_1' -f 'query=mutation($id: ID!) { enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: SQUASH }) { clientMutationId } }'\ngh: Auto-merge is not supported for stacked pull requests.",
+      ),
+      'gh: Auto-merge is not supported for stacked pull requests.',
+    );
+  });
+
+  test('keeps the last two lines of a longer answer', () => {
+    assert.strictEqual(
+      describeCommandFailure('Command failed: gh pr edit 1\none\ntwo\nthree'),
+      'two\nthree',
+    );
+  });
+
+  test('keeps the command when it printed nothing', () => {
+    assert.strictEqual(
+      describeCommandFailure('Command failed: gh pr edit 1'),
+      'Command failed: gh pr edit 1',
+    );
+  });
+
+  test('keeps the end of a message that names no command', () => {
+    assert.strictEqual(describeCommandFailure('one\ntwo\nthree'), 'two\nthree');
+  });
+});
+
+const summary = (overrides: Partial<ChecksSummary> = {}): ChecksSummary =>
+  ({
+    verdict: 'pending',
+    passed: [],
+    failed: [],
+    failedRuns: [],
+    pending: [],
+    skipped: [],
+    missing: [],
+    notRun: [],
+    running: [],
+    required: 9,
+    ...overrides,
+  }) as const;

package/src/unblock-prs/skips.mts

@@ -0,0 +1,215 @@
+/**
+ * What the loop remembers about a pull request it has given up on, and for
+ * how long.
+ */
+
+import {
+  isSetAsideReason,
+  setAsideApplies,
+  setAsideStillApplies,
+  type SetAside,
+} from 'pr-report-core';
+import { Arr } from 'ts-data-forge';
+import type { ResolvedBy } from './set-aside-comment.mjs';
+import type {
+  OwnSetAsideComment,
+  PullRequest,
+  SkipRecord,
+  SkipRecords,
+} from './types.mjs';
+
+/**
+ * A verdict lasts as long as the state it was reached in. Every reason is
+ * tied to the head, so a push to the branch clears it; all but
+ * `checks-failed` are tied to the base as well.
+ *
+ * The base is what makes the difference to a pull request that sat green
+ * without merging or ran out of watch time: once the base moves that pull
+ * request is `BEHIND`, which is the one thing this script knows how to fix,
+ * and a verdict that outlived its state is what left a ready pull request
+ * sitting still through cycle after cycle of "Nothing to do". One that sat
+ * green goes back in the running last, not first — `demotions.mts`. A rebase or
+ * push failure is tied to the base for the older reason: the commit it
+ * conflicted with may have gone with it.
+ *
+ * `checks-failed` is deliberately not tied to the base. Rebasing it would put
+ * the same failing matrix through again, and fixing the failure is the
+ * skill's job, not this script's — the push that carries the fix is what
+ * clears it. Nor is `awaiting-bypass`: the bypass merge it waits for does not
+ * wait for the base, and a rebase each time anything else merged would run
+ * the matrix again for nothing. Its comment's retry box is how a person asks
+ * for a run on the current tip.
+ *
+ * The rule is `pr-report-core`'s `setAsideApplies`, because the Pull Requests
+ * Manager page applies the same rule to the comment this script leaves on
+ * the pull request, and so does {@link settleSkips} here.
+ */
+export const skipStillApplies = (
+  skip: SkipRecord,
+  pr: PullRequest,
+  baseSha: string,
+): boolean => setAsideApplies(skip, pr.headRefOid, baseSha);
+
+/** Drops records for pull requests that are gone or have moved on. */
+export const pruneSkips = (
+  skipped: SkipRecords,
+  pullRequests: readonly PullRequest[],
+  baseSha: string,
+): SkipRecords =>
+  new Map(
+    Array.from(skipped.values())
+      .filter((skip) => {
+        const pr = pullRequests.find((p) => p.number === skip.number);
+
+        return pr !== undefined && skipStillApplies(skip, pr, baseSha);
+      })
+      .map((skip) => [skip.number, skip] as const),
+  );
+
+export const withSkip = (skipped: SkipRecords, skip: SkipRecord): SkipRecords =>
+  new Map([...skipped, [skip.number, skip]]);
+
+/**
+ * The records in `after` that `before` did not have — a pull request newly
+ * set aside, or set aside again for a different reason or in a different
+ * state. What the loop writes to GitHub, once each, rather than on every
+ * survey that finds the same record standing.
+ *
+ * `before` is what the cycle acted from, after {@link settleSkips}, so that a
+ * record read back from a comment is not written over that comment again.
+ */
+export const newSkips = (
+  before: SkipRecords,
+  after: SkipRecords,
+): readonly SkipRecord[] =>
+  Array.from(after.values()).filter((skip) => {
+    const previous = before.get(skip.number);
+
+    return (
+      previous?.headSha !== skip.headSha ||
+      previous.baseSha !== skip.baseSha ||
+      previous.reason !== skip.reason
+    );
+  });
+
+/**
+ * The records no comment says: never written, because the write failed, or
+ * written over since. Until it is written the worker holds the pull request
+ * aside while every other reader of the queue (`owner.mts`) reads it as the
+ * worker's, and each leaves it to the other; so the loop writes these again.
+ */
+export const unannouncedSkips = (
+  skipped: SkipRecords,
+  comments: ReadonlyMap<number, OwnSetAsideComment>,
+): readonly SkipRecord[] =>
+  Array.from(skipped.values()).filter((skip) => {
+    const says = comments.get(skip.number)?.says;
+
+    return (
+      says?.kind !== 'standing' ||
+      says.setAside.headSha !== skip.headSha ||
+      says.setAside.reason !== skip.reason
+    );
+  });
+
+/**
+ * What this account's set-aside comments on the open pull requests say, laid
+ * over the records: the comments to rewrite as resolved, and the records to
+ * act from.
+ *
+ * - **Ended**: a comment set aside at a head that has moved, or against a
+ *   base that has — by the same rule as the records, {@link skipStillApplies}
+ *   — is rewritten as resolved.
+ * - **Retry**: a comment whose box a person ticked is rewritten as resolved,
+ *   and the record goes with it, so this cycle's triage treats the pull
+ *   request as if it had never been set aside. One that fails again is set
+ *   aside again, and its comment says so again.
+ * - **Standing, and this run does not know it**: a record an earlier run
+ *   reached, which is taken up as it stands rather than tried again — a
+ *   rebase that conflicted would conflict the same way.
+ *
+ * A record this run holds is left as it is otherwise: the comment says what
+ * the record said when it was written.
+ */
+export const settleSkips = (
+  skipped: SkipRecords,
+  comments: ReadonlyMap<number, OwnSetAsideComment>,
+  pullRequests: readonly PullRequest[],
+  baseSha: string,
+): Readonly<{ skipped: SkipRecords; resolved: readonly Resolution[] }> => {
+  const judged = Array.from(comments).flatMap(([number, comment]) => {
+    const pr = pullRequests.find((p) => p.number === number);
+
+    if (pr === undefined || comment.says.kind === 'resolved') {
+      return [];
+    }
+
+    const { setAside, retry } = comment.says;
+
+    const resolvedBy: ResolvedBy | undefined =
+      setAside.headSha !== pr.headRefOid
+        ? 'pushed'
+        : !setAsideStillApplies(setAside, baseSha)
+          ? 'base-moved'
+          : retry
+            ? 'retry'
+            : undefined;
+
+    return [
+      { number, databaseId: comment.databaseId, setAside, resolvedBy } as const,
+    ];
+  });
+
+  const retried = new Set(
+    Arr.generate(function* () {
+      for (const { number, resolvedBy } of judged) {
+        if (resolvedBy === 'retry') {
+          yield number;
+        }
+      }
+    }),
+  );
+
+  const taken = Arr.generate(function* () {
+    for (const { number, setAside, resolvedBy } of judged) {
+      if (
+        resolvedBy === undefined &&
+        !skipped.has(number) &&
+        isSetAsideReason(setAside.reason)
+      ) {
+        yield {
+          number,
+          headSha: setAside.headSha,
+          baseSha: setAside.baseSha,
+          reason: setAside.reason,
+          detail: TAKEN_UP_DETAIL,
+        } as const;
+      }
+    }
+  });
+
+  return {
+    skipped: taken.reduce(
+      withSkip,
+      new Map(Array.from(skipped).filter(([number]) => !retried.has(number))),
+    ),
+    resolved: Arr.generate(function* () {
+      for (const { number, databaseId, setAside, resolvedBy } of judged) {
+        if (resolvedBy !== undefined) {
+          yield { number, databaseId, setAside, resolvedBy };
+        }
+      }
+    }),
+  };
+};
+
+/** A set-aside comment to rewrite as resolved, and why. */
+export type Resolution = Readonly<{
+  number: number;
+  databaseId: number;
+  setAside: SetAside;
+  resolvedBy: ResolvedBy;
+}>;
+
+/** What the log says about a record taken up from a comment. */
+const TAKEN_UP_DETAIL = 'set aside by an earlier run, as its comment says';

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

@@ -0,0 +1,280 @@
+import type { SetAside } from 'pr-report-core';
+import { newSkips, settleSkips, unannouncedSkips, withSkip } from './skips.mjs';
+import type {
+  OwnSetAsideComment,
+  PullRequest,
+  SkipRecord,
+  SkipRecords,
+} from './types.mjs';
+
+describe(newSkips, () => {
+  const none: SkipRecords = new Map();
+
+  test('reports a pull request set aside for the first time', () => {
+    assert.deepStrictEqual(newSkips(none, withSkip(none, skip())), [skip()]);
+  });
+
+  test('does not report a record that is still standing', () => {
+    const standing = withSkip(none, skip());
+
+    assert.deepStrictEqual(newSkips(standing, standing), []);
+
+    // The detail is prose, and prose that changed is not a new state.
+    assert.deepStrictEqual(
+      newSkips(standing, withSkip(none, skip({ detail: 'reworded' }))),
+      [],
+    );
+  });
+
+  test('reports it again once the state it was reached in has changed', () => {
+    const standing = withSkip(none, skip());
+
+    for (const changed of [
+      skip({ headSha: 'pushed' }),
+      skip({ baseSha: 'moved' }),
+      skip({ reason: 'push-failed' }),
+    ]) {
+      assert.deepStrictEqual(newSkips(standing, withSkip(none, changed)), [
+        changed,
+      ]);
+    }
+  });
+});
+
+describe(unannouncedSkips, () => {
+  const none: SkipRecords = new Map();
+
+  const record = skip({ headSha: HEAD, baseSha: BASE });
+
+  test('names a record whose comment was never written, or says otherwise', () => {
+    // The worker holds it aside while the comment the skill reads does not:
+    // each would leave it to the other until the comment is written.
+    assert.deepStrictEqual(
+      unannouncedSkips(withSkip(none, record), comments()),
+      [record],
+    );
+
+    assert.deepStrictEqual(
+      unannouncedSkips(
+        withSkip(none, record),
+        comments([7, { databaseId: 0, says: { kind: 'resolved' } }]),
+      ),
+      [record],
+    );
+
+    assert.deepStrictEqual(
+      unannouncedSkips(
+        withSkip(none, record),
+        comments([
+          7,
+          standingComment({
+            setAside: { ...SET_ASIDE, reason: 'checks-failed' },
+          }),
+        ]),
+      ),
+      [record],
+    );
+  });
+
+  test('passes over a record its comment says', () => {
+    assert.deepStrictEqual(
+      unannouncedSkips(
+        withSkip(none, record),
+        comments([7, standingComment()]),
+      ),
+      [],
+    );
+  });
+});
+
+describe(settleSkips, () => {
+  const none: SkipRecords = new Map();
+
+  test('resolves a comment whose head has moved', () => {
+    assert.deepStrictEqual(
+      settleSkips(
+        none,
+        comments([7, standingComment()]),
+        [pullRequest(7, { headRefOid: PUSHED })],
+        BASE,
+      ),
+      {
+        skipped: none,
+        resolved: [
+          {
+            number: 7,
+            databaseId: 107,
+            setAside: SET_ASIDE,
+            resolvedBy: 'pushed',
+          },
+        ],
+      },
+    );
+  });
+
+  test('resolves a comment whose base has moved, except for failed checks', () => {
+    const settled = settleSkips(
+      none,
+      comments(
+        [7, standingComment()],
+        [
+          8,
+          standingComment({
+            setAside: { ...SET_ASIDE, reason: 'checks-failed' },
+          }),
+        ],
+      ),
+      [pullRequest(7), pullRequest(8)],
+      MOVED,
+    );
+
+    assert.deepStrictEqual(
+      settled.resolved.map(({ number, resolvedBy }) => [number, resolvedBy]),
+      [[7, 'base-moved']],
+    );
+
+    // The failed checks stand, and are taken up.
+    assert.strictEqual(settled.skipped.get(8)?.reason, 'checks-failed');
+  });
+
+  test('drops the record of a pull request a person asked to retry', () => {
+    const held = withSkip(none, skip({ headSha: HEAD, baseSha: BASE }));
+
+    const settled = settleSkips(
+      held,
+      comments([7, standingComment({ retry: true })]),
+      [pullRequest(7)],
+      BASE,
+    );
+
+    assert.isFalse(settled.skipped.has(7));
+
+    assert.deepStrictEqual(
+      settled.resolved.map(({ number, resolvedBy }) => [number, resolvedBy]),
+      [[7, 'retry']],
+    );
+  });
+
+  test('takes up a record an earlier run left standing', () => {
+    const settled = settleSkips(
+      none,
+      comments([7, standingComment()]),
+      [pullRequest(7)],
+      BASE,
+    );
+
+    assert.deepStrictEqual(settled.resolved, []);
+
+    assert.deepStrictEqual(
+      [settled.skipped.get(7)?.reason, settled.skipped.get(7)?.headSha],
+      ['rebase-failed', HEAD],
+    );
+
+    // Not new: the comment already says it, so nothing writes over it.
+    assert.deepStrictEqual(newSkips(settled.skipped, settled.skipped), []);
+  });
+
+  test('keeps the record this run holds over the one its comment says', () => {
+    const held = withSkip(
+      none,
+      skip({ headSha: HEAD, baseSha: BASE, detail: 'conflicts in a.mts' }),
+    );
+
+    assert.deepStrictEqual(
+      settleSkips(
+        held,
+        comments([7, standingComment()]),
+        [pullRequest(7)],
+        BASE,
+      ),
+      { skipped: held, resolved: [] },
+    );
+  });
+
+  test('leaves alone what is resolved, closed, or a reason it does not know', () => {
+    assert.deepStrictEqual(
+      settleSkips(
+        none,
+        comments(
+          [7, { databaseId: 107, says: { kind: 'resolved' } }],
+          [8, standingComment()],
+          [
+            9,
+            standingComment({ setAside: { ...SET_ASIDE, reason: 'renamed' } }),
+          ],
+        ),
+        [pullRequest(7), pullRequest(9)],
+        BASE,
+      ),
+      { skipped: none, resolved: [] },
+    );
+  });
+});
+
+const HEAD = 'c'.repeat(40);
+
+const PUSHED = 'd'.repeat(40);
+
+const BASE = 'a'.repeat(40);
+
+const MOVED = 'b'.repeat(40);
+
+const SET_ASIDE: SetAside = {
+  reason: 'rebase-failed',
+  headSha: HEAD,
+  baseSha: BASE,
+} as const;
+
+const standingComment = (
+  overrides: Partial<Readonly<{ setAside: SetAside; retry: boolean }>> = {},
+): OwnSetAsideComment =>
+  ({
+    databaseId: 0,
+    says: {
+      kind: 'standing',
+      setAside: overrides.setAside ?? SET_ASIDE,
+      retry: overrides.retry ?? false,
+    },
+  }) as const;
+
+/** Each pull request's comment, with a database id of 100 more than its number. */
+const comments = (
+  ...entries: readonly (readonly [number, OwnSetAsideComment])[]
+): ReadonlyMap<number, OwnSetAsideComment> =>
+  new Map(
+    entries.map(
+      ([number, comment]) =>
+        [number, { ...comment, databaseId: 100 + number }] as const,
+    ),
+  );
+
+const pullRequest = (
+  number: number,
+  fields: Partial<PullRequest> = {},
+): PullRequest =>
+  ({
+    number,
+    id: `PR_${number}`,
+    title: `pull request #${number}`,
+    body: '',
+    state: 'OPEN',
+    headRefName: `feature/${number}`,
+    headRefOid: HEAD,
+    baseRefName: 'main',
+    isCrossRepository: false,
+    isDraft: false,
+    mergeStateStatus: 'BEHIND',
+    autoMergeRequest: {},
+    labels: [{ name: 'merge-queued' }],
+    ...fields,
+  }) as const;
+
+const skip = (overrides: Partial<SkipRecord> = {}): SkipRecord =>
+  ({
+    number: 7,
+    headSha: 'head',
+    baseSha: 'base',
+    reason: 'rebase-failed',
+    detail: 'rebase conflicts',
+    ...overrides,
+  }) as const;