pr-merge-queue 0.0.0-stage → 0.0.0

package/src/unblock-prs/merge-after.mts

@@ -0,0 +1,117 @@
+/**
+ * What the declared order means for picking a pull request, as a note, and
+ * the order the issues the pull requests close add to it. Reading the
+ * `Merge-After:` trailers and the `Start-After:` lines, finding the cycles in
+ * them and deciding that a pull request waits is `pr-report-core`'s, because
+ * the Pull Requests Manager page draws the same queue.
+ */
+
+import { closingKeywordIssuesIn, waitsFor, type RepoRef } from 'pr-report-core';
+import { Arr } from 'ts-data-forge';
+import type { Classification, IssueOrder, PullRequest } from './types.mjs';
+
+/**
+ * The note to report instead of picking this pull request while what it
+ * must merge after is still open. Picking is all this constrains: a pull
+ * request that is already up to date and merging is left to auto-merge,
+ * which takes no notice of anything declared here.
+ */
+export const waitingOnNote = (
+  pr: PullRequest,
+  on: readonly number[],
+  cyclic: boolean,
+  inherited: readonly number[] = [],
+): Classification => {
+  const fromIssues = on.filter((number) => inherited.includes(number));
+
+  return {
+    kind: 'note',
+    note: `#${pr.number}: Merge-After ${on.map((number) => `#${number}`).join(', ')}, still open${
+      Arr.isNonEmpty(fromIssues)
+        ? ` (${fromIssues.map((number) => `#${number}`).join(', ')} from the Start-After of an issue it closes)`
+        : ''
+    }${
+      cyclic
+        ? ' — and on a Merge-After cycle, so nothing here will move it'
+        : ''
+    }`,
+  } as const;
+};
+
+/** One issue as the closing-issue reads answer it. */
+export type ClosingIssueAnswer = Readonly<{
+  number: number;
+  /** `OPEN` or `CLOSED`. */
+  state: string;
+  body: string;
+  /** The issues of this repository GitHub records as blocking it. */
+  blockedBy: readonly number[];
+}>;
+
+/**
+ * Which open issues each pull request closes, and what those declare with
+ * `Start-After:`, for `queueGraph` to inherit.
+ *
+ * An issue closes when GitHub links it (`linked`, this repository's only) or
+ * when the body closes it by keyword, as GitHub marked it in `bodyHtml` —
+ * the one way to tell for a stacked pull request, which GitHub links
+ * nothing on. `described` is what was read of the keyword ones GitHub did
+ * not link; one it would not describe is left out, being unknown.
+ */
+export const issueOrderOf = (
+  repo: RepoRef,
+  pulls: readonly Readonly<{
+    number: number;
+    bodyHtml: string;
+    linked: readonly ClosingIssueAnswer[];
+  }>[],
+  described: ReadonlyMap<number, ClosingIssueAnswer>,
+): IssueOrder => {
+  const mut_issues = new Map(described);
+
+  for (const issue of pulls.flatMap(({ linked }) => linked)) {
+    mut_issues.set(issue.number, issue);
+  }
+
+  const issues: ReadonlyMap<number, ClosingIssueAnswer> = mut_issues;
+
+  const isOpen = (number: number): boolean =>
+    issues.get(number)?.state.toUpperCase() === 'OPEN';
+
+  return {
+    closes: new Map(
+      pulls.map(({ number, bodyHtml, linked }) => [
+        number,
+        Arr.uniq([
+          ...linked.map((issue) => issue.number),
+          ...closingKeywordIssuesIn(repo, bodyHtml),
+        ]).filter(isOpen),
+      ]),
+    ),
+    startAfter: new Map(
+      Array.from(issues.values(), ({ number, body, blockedBy }) => [
+        number,
+        waitsFor(body, blockedBy),
+      ]),
+    ),
+  } as const;
+};
+
+/** The keyword-closed issues of `pulls` that GitHub did not link. */
+export const unlinkedClosingIssues = (
+  repo: RepoRef,
+  pulls: readonly Readonly<{
+    bodyHtml: string;
+    linked: readonly ClosingIssueAnswer[];
+  }>[],
+): readonly number[] => {
+  const linked = new Set(
+    pulls.flatMap((pull) => pull.linked.map(({ number }) => number)),
+  );
+
+  return Arr.uniq(
+    pulls.flatMap(({ bodyHtml }) => closingKeywordIssuesIn(repo, bodyHtml)),
+  )
+    .filter((number) => !linked.has(number))
+    .toSorted((a, b) => a - b);
+};

package/src/unblock-prs/merge-after.test.mts

@@ -0,0 +1,120 @@
+import {
+  issueOrderOf,
+  unlinkedClosingIssues,
+  waitingOnNote,
+  type ClosingIssueAnswer,
+} from './merge-after.mjs';
+import type { PullRequest } from './types.mjs';
+
+const repo = { owner: 'noshiro-pf', name: 'mono' } as const;
+
+describe(waitingOnNote, () => {
+  test('names what the order is waiting on', () => {
+    assert.deepStrictEqual(waitingOnNote(pullRequest(), [5], false), {
+      kind: 'note',
+      note: '#10: Merge-After #5, still open',
+    });
+  });
+
+  test('says which of them an issue it closes asked for', () => {
+    assert.deepStrictEqual(waitingOnNote(pullRequest(), [5, 7], true, [7]), {
+      kind: 'note',
+      note: '#10: Merge-After #5, #7, still open (#7 from the Start-After of an issue it closes) — and on a Merge-After cycle, so nothing here will move it',
+    });
+  });
+});
+
+describe(issueOrderOf, () => {
+  test('reads what GitHub links and what the body closes by keyword', () => {
+    const order = issueOrderOf(
+      repo,
+      [
+        {
+          number: 10,
+          bodyHtml: '',
+          // What GitHub records as blocking it counts as the line does.
+          linked: [issue(1, 'Start-After: #20', 'OPEN', [21])],
+        },
+        // Stacked: GitHub links nothing, and marks the keyword.
+        { number: 11, bodyHtml: closes(2), linked: [] },
+      ],
+      new Map([[2, issue(2, 'Start-After: #3, #4')]]),
+    );
+
+    assert.deepStrictEqual(
+      order.closes,
+      new Map([
+        [10, [1]],
+        [11, [2]],
+      ]),
+    );
+
+    assert.deepStrictEqual(
+      order.startAfter,
+      new Map([
+        [2, [3, 4]],
+        [1, [20, 21]],
+      ]),
+    );
+  });
+
+  test('a closed issue, or one GitHub would not describe, closes nothing', () => {
+    const order = issueOrderOf(
+      repo,
+      [
+        {
+          number: 10,
+          bodyHtml: closes(3),
+          linked: [issue(1, 'Start-After: #20', 'CLOSED')],
+        },
+      ],
+      new Map(),
+    );
+
+    assert.deepStrictEqual(order.closes, new Map([[10, []]]));
+  });
+});
+
+describe(unlinkedClosingIssues, () => {
+  test('lists the keyword-closed issues GitHub did not link, once each', () => {
+    assert.deepStrictEqual(
+      unlinkedClosingIssues(repo, [
+        { bodyHtml: `${closes(5)}${closes(1)}`, linked: [issue(1, '')] },
+        { bodyHtml: closes(5), linked: [] },
+      ]),
+      [5],
+    );
+  });
+});
+
+const pullRequest = (): PullRequest =>
+  ({
+    number: 10,
+    id: 'PR_10',
+    title: '#10',
+    body: '',
+    state: 'OPEN',
+    headRefName: 'fix/a-thing',
+    headRefOid: 'c'.repeat(40),
+    baseRefName: 'main',
+    isCrossRepository: false,
+    isDraft: false,
+    mergeStateStatus: 'BEHIND',
+    autoMergeRequest: null,
+    labels: [{ name: 'merge-queued' }],
+  }) as const;
+
+const issue = (
+  number: number,
+  body: string,
+  state: string = 'OPEN',
+  blockedBy: readonly number[] = [],
+): ClosingIssueAnswer => ({ number, state, body, blockedBy }) as const;
+
+/** A closing keyword as GitHub renders one it recognized. */
+const closes = (number: number): string =>
+  [
+    '<p dir="auto"><span class="issue-keyword">Closes</span> ',
+    `<a class="issue-link js-issue-link" data-url="https://github.com/${repo.owner}/${repo.name}/issues/${number}"`,
+    ` data-hovercard-type="issue" href="https://github.com/${repo.owner}/${repo.name}/issues/${number}">#${number}</a></p>`,
+  ].join('');

package/src/unblock-prs/options.mts

@@ -0,0 +1,157 @@
+/** What the command line says, and how it is read. */
+
+import { MERGE_QUEUED_LABEL, SKIP_CI_LABEL } from 'pr-report-core';
+import { Result } from 'ts-data-forge';
+import { parseCommandArgs, positiveInteger } from '../lib/index.mjs';
+
+export type Options = Readonly<{
+  /** Run one cycle — survey, act on one pull request, report — and exit. */
+  once: boolean;
+  /** Survey and say what would be done, without rebasing or pushing. */
+  dryRun: boolean;
+  /** How long to wait between surveys while the list is still changing. */
+  activeIntervalSec: number;
+  /**
+   * How many surveys in a row must see an unchanged list before the wait
+   * between them grows to `idleIntervalSec`.
+   */
+  idleAfter: number;
+  /** How long to wait between surveys once the list has sat still. */
+  idleIntervalSec: number;
+  /** How often to poll the pull request being watched. */
+  pollIntervalSec: number;
+  /** How long to watch one pull request before giving up on it. */
+  watchTimeoutMin: number;
+  /**
+   * Whether a watched pull request whose failure is only a fixer's diff has
+   * the fixer run, amended onto its commit and pushed. See `auto-fix.mts`.
+   */
+  autoFix: boolean;
+  /**
+   * The repository, `owner/name`, when it is not the one `origin` names
+   * (`lib/github-api.mts`'s `resolveRepo`).
+   */
+  repo: string | undefined;
+}>;
+
+export const defaultOptions: Options = {
+  once: false,
+  dryRun: false,
+  activeIntervalSec: 30,
+  idleAfter: 10,
+  idleIntervalSec: 300,
+  pollIntervalSec: 30,
+  watchTimeoutMin: 90,
+  autoFix: true,
+  repo: undefined,
+} as const;
+
+export const HELP = [
+  'Usage: unblock-prs [options]',
+  '',
+  `Takes the ${MERGE_QUEUED_LABEL} pull requests in the order they declare with`,
+  '`Merge-After:`, one at a time: rebases the one that is out of date with the',
+  `default branch, takes ${SKIP_CI_LABEL} off it, and waits for GitHub to merge it.`,
+  'When its checks fail only because a fix: or gen: entry of the check matrices',
+  'left a diff, runs that command, amends the result and pushes it, once.',
+  '',
+  'Options:',
+  '  --once                   run one cycle and exit',
+  '  --dry-run                survey and report what would be done, then exit',
+  `  --active-interval <sec>  wait between surveys while the list is changing (default ${defaultOptions.activeIntervalSec})`,
+  `  --idle-after <n>         unchanged surveys before slowing to --idle-interval (default ${defaultOptions.idleAfter})`,
+  `  --idle-interval <sec>    wait between surveys once the list has sat still (default ${defaultOptions.idleIntervalSec})`,
+  `  --poll-interval <sec>    wait between polls of the watched pull request (default ${defaultOptions.pollIntervalSec})`,
+  `  --watch-timeout <min>    give up on a pull request after this long (default ${defaultOptions.watchTimeoutMin})`,
+  "  --no-auto-fix            leave a failure that is only a fixer's diff as it is",
+  '  --repo <owner/name>      the repository, when origin does not name it',
+  '  -h, --help               show this help',
+].join('\n');
+
+export const parseOptions = (
+  args: readonly string[],
+): Result<Options | 'help', string> => {
+  const parsed = parseCommandArgs(args, {
+    once: { type: 'boolean', default: false },
+    'dry-run': { type: 'boolean', default: false },
+    'active-interval': { type: 'string' },
+    'idle-after': { type: 'string' },
+    'idle-interval': { type: 'string' },
+    'poll-interval': { type: 'string' },
+    'watch-timeout': { type: 'string' },
+    'no-auto-fix': { type: 'boolean', default: false },
+    repo: { type: 'string' },
+  });
+
+  if (Result.isErr(parsed)) {
+    return parsed;
+  }
+
+  if (parsed.value === 'help') {
+    return Result.ok('help');
+  }
+
+  const values = parsed.value;
+
+  const activeIntervalSec = positiveInteger(
+    'active-interval',
+    values['active-interval'],
+    defaultOptions.activeIntervalSec,
+  );
+
+  if (Result.isErr(activeIntervalSec)) {
+    return activeIntervalSec;
+  }
+
+  const idleAfter = positiveInteger(
+    'idle-after',
+    values['idle-after'],
+    defaultOptions.idleAfter,
+  );
+
+  if (Result.isErr(idleAfter)) {
+    return idleAfter;
+  }
+
+  const idleIntervalSec = positiveInteger(
+    'idle-interval',
+    values['idle-interval'],
+    defaultOptions.idleIntervalSec,
+  );
+
+  if (Result.isErr(idleIntervalSec)) {
+    return idleIntervalSec;
+  }
+
+  const pollIntervalSec = positiveInteger(
+    'poll-interval',
+    values['poll-interval'],
+    defaultOptions.pollIntervalSec,
+  );
+
+  if (Result.isErr(pollIntervalSec)) {
+    return pollIntervalSec;
+  }
+
+  const watchTimeoutMin = positiveInteger(
+    'watch-timeout',
+    values['watch-timeout'],
+    defaultOptions.watchTimeoutMin,
+  );
+
+  if (Result.isErr(watchTimeoutMin)) {
+    return watchTimeoutMin;
+  }
+
+  return Result.ok({
+    once: values.once,
+    dryRun: values['dry-run'],
+    activeIntervalSec: activeIntervalSec.value,
+    idleAfter: idleAfter.value,
+    idleIntervalSec: idleIntervalSec.value,
+    pollIntervalSec: pollIntervalSec.value,
+    watchTimeoutMin: watchTimeoutMin.value,
+    autoFix: !values['no-auto-fix'],
+    repo: values.repo,
+  });
+};

package/src/unblock-prs/owner.mts

@@ -0,0 +1,91 @@
+/**
+ * Who moves each pull request next, as the worker reads it: `pr-report-core`'s
+ * `queueOwner`, the one function `pr-report`, `claim-pr` and every other
+ * command a session runs read it through, given the facts GitHub returned.
+ *
+ * The set-aside comes from the records, which by the time triage reads them
+ * are what this account's comments say (`settleSkips`): a record the base
+ * moved under is pruned as its comment is rewritten as resolved, and one an
+ * earlier run left is taken up from its comment. The claims are the ones
+ * that still hold (`claims.mts`).
+ */
+
+import { queueOwner, type Claim, type QueueOwner } from 'pr-report-core';
+import type { Classification, PullRequest, SkipRecords } from './types.mjs';
+
+export type OwnerContext = Readonly<{
+  defaultBranch: string;
+  skipped: SkipRecords;
+  claimed: ReadonlyMap<number, Claim>;
+  /** Which open pull request each stacked one is on: child → parent. */
+  stackParents: ReadonlyMap<number, number>;
+  /** Every number that sits on a `Merge-After` cycle. */
+  cyclic: ReadonlySet<number>;
+  nowEpochMs: number;
+}>;
+
+/** Who moves `pr` next, or `undefined` outside the queue. */
+export const ownerOf = (
+  pr: PullRequest,
+  context: OwnerContext,
+): QueueOwner | undefined => {
+  const skip = context.skipped.get(pr.number);
+
+  const claim = context.claimed.get(pr.number);
+
+  return queueOwner({
+    number: pr.number,
+    labels: pr.labels.map(({ name }) => name),
+    isDraft: pr.isDraft,
+    fromFork: pr.isCrossRepository,
+    headRef: pr.headRefName,
+    headSha: pr.headRefOid,
+    baseRef: pr.baseRefName,
+    defaultBranch: context.defaultBranch,
+    stackedOn: context.stackParents.get(pr.number),
+    inCycle: context.cyclic.has(pr.number),
+    setAside:
+      skip === undefined
+        ? undefined
+        : {
+            kind: 'standing',
+            setAside: {
+              reason: skip.reason,
+              headSha: skip.headSha,
+              baseSha: skip.baseSha,
+            },
+            retry: false,
+          },
+    claim: claim === undefined ? undefined : { kind: 'standing', claim },
+    nowEpochMs: context.nowEpochMs,
+  });
+};
+
+/**
+ * What triage says about a pull request that is not the worker's to move: a
+ * note naming its owner and why, with the record's detail when one set it
+ * aside. `undefined` for one the worker moves, or one outside the queue.
+ */
+export const ownerNote = (
+  pr: PullRequest,
+  owner: QueueOwner | undefined,
+  skipped: SkipRecords,
+): Classification | undefined => {
+  if (owner === undefined || owner.owner === 'worker') {
+    return undefined;
+  }
+
+  const skip = skipped.get(pr.number);
+
+  const whose =
+    owner.owner === 'skill'
+      ? "the /unblock-prs skill's"
+      : owner.owner === 'human'
+        ? "a person's"
+        : "nobody's — a bug";
+
+  return {
+    kind: 'note',
+    note: `#${pr.number}: ${whose} (${owner.reason})${skip === undefined ? '' : `; set aside: ${skip.detail}`}`,
+  };
+};

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

@@ -0,0 +1,114 @@
+import type { Claim } from 'pr-report-core';
+import { ownerNote, ownerOf, type OwnerContext } from './owner.mjs';
+import type { PullRequest, SkipRecord } from './types.mjs';
+
+const HEAD = 'c'.repeat(40);
+
+const NOW = Date.parse('2026-10-15T00:30:00Z');
+
+const pullRequest = (fields: Partial<PullRequest> = {}): PullRequest =>
+  ({
+    number: 2267,
+    id: 'PR_2267',
+    title: '#2267',
+    body: '',
+    state: 'OPEN',
+    headRefName: 'fix/a-thing',
+    headRefOid: HEAD,
+    baseRefName: 'main',
+    isCrossRepository: false,
+    isDraft: false,
+    mergeStateStatus: 'BLOCKED',
+    autoMergeRequest: null,
+    labels: [{ name: 'merge-queued' }, { name: 'skip-ci' }],
+    ...fields,
+  }) as const;
+
+const SKIP: SkipRecord = {
+  number: 2267,
+  headSha: HEAD,
+  baseSha: 'b'.repeat(40),
+  reason: 'rebase-failed',
+  detail: 'conflicts in a.mts',
+} as const;
+
+const CLAIM: Claim = {
+  headSha: HEAD,
+  by: 'unblock-wren',
+  at: '2026-10-15T00:00:00Z',
+} as const;
+
+const context = (fields: Partial<OwnerContext> = {}): OwnerContext =>
+  ({
+    defaultBranch: 'main',
+    skipped: new Map(),
+    claimed: new Map(),
+    stackParents: new Map(),
+    cyclic: new Set(),
+    nowEpochMs: NOW,
+    ...fields,
+  }) as const;
+
+describe(ownerOf, () => {
+  test('is the worker’s with nothing set aside or claimed', () => {
+    assert.strictEqual(ownerOf(pullRequest(), context())?.owner, 'worker');
+  });
+
+  test('reads a record as the comment it was taken up from', () => {
+    assert.deepStrictEqual(
+      ownerOf(pullRequest(), context({ skipped: new Map([[2267, SKIP]]) })),
+      {
+        owner: 'skill',
+        reason: 'set aside `rebase-failed` at its head; the skill fixes it',
+      },
+    );
+  });
+
+  test('is the claimant’s while the claim holds', () => {
+    assert.strictEqual(
+      ownerOf(pullRequest(), context({ claimed: new Map([[2267, CLAIM]]) }))
+        ?.owner,
+      'skill',
+    );
+  });
+
+  test('is undefined outside the queue', () => {
+    assert.isUndefined(ownerOf(pullRequest({ labels: [] }), context()));
+  });
+});
+
+describe(ownerNote, () => {
+  test('says whose a set-aside pull request is, and why it was set aside', () => {
+    const skipped = new Map([[2267, SKIP]]);
+
+    assert.deepStrictEqual(
+      ownerNote(
+        pullRequest(),
+        ownerOf(pullRequest(), context({ skipped })),
+        skipped,
+      ),
+      {
+        kind: 'note',
+        note: "#2267: the /unblock-prs skill's (set aside `rebase-failed` at its head; the skill fixes it); set aside: conflicts in a.mts",
+      },
+    );
+  });
+
+  test('names the claimant', () => {
+    const claimed = new Map([[2267, CLAIM]]);
+
+    const note = ownerNote(
+      pullRequest(),
+      ownerOf(pullRequest(), context({ claimed })),
+      new Map(),
+    );
+
+    assert.include(note?.kind === 'note' ? note.note : '', 'unblock-wren');
+  });
+
+  test('says nothing about the worker’s own', () => {
+    assert.isUndefined(
+      ownerNote(pullRequest(), ownerOf(pullRequest(), context()), new Map()),
+    );
+  });
+});

package/src/unblock-prs/quiet.mts

@@ -0,0 +1,62 @@
+/**
+ * How long the loop sleeps when there is nothing to do: briefly while the
+ * list is still changing, so a pull request queued a moment ago is picked up
+ * in seconds, and at the idle interval once it has sat still for a while.
+ */
+
+import { isRecord } from 'ts-data-forge';
+import type { StrictPick } from 'ts-type-forge';
+import type { Options } from './options.mjs';
+import type { Quiet, Survey } from './types.mjs';
+
+export const initialQuiet: Quiet = {
+  fingerprint: undefined,
+  unchanged: 0,
+} as const;
+
+/**
+ * The part of a survey triage reads: the base, and for every open pull
+ * request its head, merge state, labels, auto-merge, draft flag and body —
+ * the body because that is where `Merge-After:` is declared — and what the
+ * reviews hold, which triage reads separately: an approval or a resolved
+ * conversation is exactly what a held pull request is waiting for. The title
+ * is left out, as is the order GitHub lists things in.
+ */
+export const surveyFingerprint = (
+  survey: StrictPick<Survey, 'baseSha' | 'pullRequests'>,
+  reviewHolds: readonly string[] = [],
+): string =>
+  JSON.stringify({
+    baseSha: survey.baseSha,
+    reviewHolds: reviewHolds.toSorted(),
+    pullRequests: survey.pullRequests
+      .toSorted((a, b) => a.number - b.number)
+      .map((pr) => [
+        pr.number,
+        pr.headRefOid,
+        pr.baseRefName,
+        pr.mergeStateStatus,
+        pr.isDraft,
+        isRecord(pr.autoMergeRequest),
+        pr.labels.map((label) => label.name).toSorted(),
+        pr.body,
+      ]),
+  });
+
+export const observeSurvey = (quiet: Quiet, fingerprint: string): Quiet =>
+  ({
+    fingerprint,
+    unchanged:
+      quiet.fingerprint === fingerprint ? quiet.unchanged + 1 : (0 as const),
+  }) as const;
+
+export const idleWaitSec = (
+  quiet: Quiet,
+  options: StrictPick<
+    Options,
+    'activeIntervalSec' | 'idleAfter' | 'idleIntervalSec'
+  >,
+): number =>
+  quiet.unchanged >= options.idleAfter
+    ? options.idleIntervalSec
+    : options.activeIntervalSec;