pr-merge-queue 0.0.0-stage → 0.0.0

package/src/pr-report/render.test.mts

@@ -0,0 +1,379 @@
+// cspell:ignore ededed
+
+import {
+  buildReport,
+  type Label,
+  type OpenIssue,
+  type PrReport,
+  type PullRequestFacts,
+} from 'pr-report-core';
+import { renderMarkdown, renderTerminal } from './render.mjs';
+
+/** Labels by name alone, for the tests that do not care what colour they are. */
+const labelled = (...names: readonly string[]): readonly Label[] =>
+  names.map((name) => ({ name, color: 'ededed', description: '' }));
+
+const facts = (
+  overrides: Partial<PullRequestFacts> & Readonly<{ number: number }>,
+): PullRequestFacts =>
+  ({
+    title: `pull request ${overrides.number}`,
+    body: '',
+    author: 'noshiro-pf',
+    isDraft: false,
+    labels: [],
+    headRef: `branch-${overrides.number}`,
+    headSha: '0'.repeat(40),
+    baseRef: 'main',
+    fromFork: false,
+    url: `https://github.com/noshiro-pf/mono/pull/${overrides.number}`,
+    updatedAt: '2026-09-18T00:00:00Z',
+    headCommittedAt: '2026-09-17T00:00:00Z',
+    comparison: { aheadBy: 1, behindBy: 0 },
+    autoMerge: false,
+    reported: new Map(),
+    checksRunning: false,
+    linkedIssues: [],
+    ...overrides,
+  }) as const;
+
+const report = (
+  pulls: readonly PullRequestFacts[],
+  issues: readonly OpenIssue[] = [],
+): PrReport =>
+  buildReport({
+    repo: { owner: 'noshiro-pf', name: 'mono' },
+    defaultBranch: 'main',
+    generatedAt: '2026-09-18T09:00:00Z',
+    required: ['code-check-result / result', 'no-skip-ci-label'],
+    merged: [],
+    mergedWithinDays: 7,
+    issues,
+    issuesLimit: 3,
+    authenticated: false,
+    pulls,
+  });
+
+const issue = (number: number): OpenIssue =>
+  ({
+    number,
+    title: `issue ${number}`,
+    author: 'noshiro-pf',
+    url: `https://github.com/noshiro-pf/mono/issues/${number}`,
+    labels: labelled('bug'),
+    createdAt: '2026-09-10T00:00:00Z',
+    updatedAt: '2026-09-17T00:00:00Z',
+    comments: 2,
+    startAfter: [],
+    misplacedMergeAfter: [],
+  }) as const;
+
+describe(renderMarkdown, () => {
+  test('says so plainly when there is nothing open', () => {
+    const rendered = renderMarkdown(report([]));
+
+    assert.isTrue(rendered.includes('No open pull requests.'));
+  });
+
+  test('nests a pull request under the one it declares it merges after', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({ number: 1901 }),
+        facts({ number: 1903, body: 'Merge-After: #1901' }),
+      ]),
+    );
+
+    const lines = rendered.split('\n');
+
+    const parent = lines.findIndex((l) => l.includes('#1901'));
+
+    const child = lines.findIndex((l) => l.includes('#1903'));
+
+    assert.isTrue(parent !== -1 && child === parent + 1);
+
+    // Two spaces of indent is one level of a Markdown list.
+    assert.isTrue(lines[child]?.startsWith('  - ') === true);
+
+    assert.isTrue(lines[parent]?.startsWith('- ') === true);
+  });
+
+  test('nests a stacked pull request under the one it is on, and says so', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({ number: 1901 }),
+        facts({ number: 1903, baseRef: 'branch-1901' }),
+      ]),
+    );
+
+    const lines = rendered.split('\n');
+
+    const child = lines.findIndex((l) => l.includes('#1903'));
+
+    assert.isTrue(lines[child]?.startsWith('  - ') === true);
+
+    assert.include(lines[child] ?? '', 'stacked on #1901');
+  });
+
+  test('says what the issues it closes add to the order', () => {
+    const rendered = renderMarkdown(
+      buildReport({
+        repo: { owner: 'noshiro-pf', name: 'mono' },
+        defaultBranch: 'main',
+        generatedAt: '2026-09-18T09:00:00Z',
+        required: [],
+        merged: [],
+        mergedWithinDays: 7,
+        issues: [],
+        issuesLimit: 3,
+        authenticated: false,
+        pulls: [
+          facts({
+            number: 1903,
+            linkedIssues: [
+              {
+                number: 1800,
+                title: '',
+                url: 'https://github.com/noshiro-pf/mono/issues/1800',
+                state: 'open',
+              },
+            ],
+          }),
+          facts({ number: 1901 }),
+        ],
+        issueDeclarations: {
+          startAfter: new Map([[1800, [1901, 1700]]]),
+          open: new Set([1700]),
+        },
+      }),
+    );
+
+    const lines = rendered.split('\n');
+
+    const child = lines.findIndex((l) => l.includes('#1903'));
+
+    // Drawn under the one it inherited, as a declared one would be.
+    assert.isTrue(lines[child]?.startsWith('  - ') === true);
+
+    assert.include(lines[child] ?? '', 'after #1901 (Start-After)');
+
+    assert.include(lines[child] ?? '', '#1700 (issue) not done');
+  });
+
+  test('links the pull request and every issue it closes', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({
+          number: 1901,
+          linkedIssues: [
+            {
+              number: 1880,
+              title: 'the bug',
+              url: 'https://github.com/noshiro-pf/mono/issues/1880',
+              state: 'open',
+            },
+          ],
+        }),
+      ]),
+    );
+
+    assert.isTrue(
+      rendered.includes(
+        '[#1901](https://github.com/noshiro-pf/mono/pull/1901)',
+      ),
+    );
+
+    assert.isTrue(
+      rendered.includes(
+        '[#1880](https://github.com/noshiro-pf/mono/issues/1880)',
+      ),
+    );
+  });
+
+  test('reports labels, the commit counts and a branch that is behind', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({
+          number: 1901,
+          labels: labelled('skip-ci', 'merge-queued'),
+          comparison: { aheadBy: 3, behindBy: 12 },
+        }),
+      ]),
+    );
+
+    assert.isTrue(rendered.includes('+3'));
+
+    assert.isTrue(rendered.includes('-12'));
+
+    assert.isTrue(rendered.includes('skip-ci'));
+
+    assert.isTrue(rendered.includes('merge-queued'));
+  });
+
+  test('says a queued pull request has auto-merge armed', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({
+          number: 1901,
+          labels: labelled('merge-queued'),
+          autoMerge: true,
+        }),
+      ]),
+    );
+
+    assert.isTrue(rendered.includes('auto-merge'));
+
+    assert.isFalse(rendered.includes('no auto-merge'));
+  });
+
+  // The ordinary state of a queued pull request: `unblock-prs` arms it when
+  // it picks it, so its absence until then is not news.
+  test('says nothing about a queued pull request not yet armed', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({
+          number: 1901,
+          labels: labelled('merge-queued'),
+          autoMerge: false,
+        }),
+      ]),
+    );
+
+    assert.isFalse(rendered.includes('auto-merge'));
+  });
+
+  test('says nothing about auto-merge on a pull request that is not queued', () => {
+    const rendered = renderMarkdown(
+      report([facts({ number: 1901, autoMerge: false })]),
+    );
+
+    assert.isFalse(rendered.includes('auto-merge'));
+  });
+
+  test('names the pull requests on a `Merge-After` cycle', () => {
+    const rendered = renderMarkdown(
+      report([
+        facts({ number: 1, body: 'Merge-After: #2' }),
+        facts({ number: 2, body: 'Merge-After: #1' }),
+      ]),
+    );
+
+    assert.isTrue(rendered.includes('Merge-After cycle'));
+
+    assert.isTrue(rendered.includes('#1'));
+
+    assert.isTrue(rendered.includes('#2'));
+  });
+});
+
+describe('the open issues section', () => {
+  test('lists every open issue with a link, its labels and its comments', () => {
+    const rendered = renderMarkdown(
+      report([facts({ number: 1901 })], [issue(2036)]),
+    );
+
+    assert.isTrue(rendered.includes('## Open issues (1)'));
+
+    assert.isTrue(
+      rendered.includes(
+        '- [#2036](https://github.com/noshiro-pf/mono/issues/2036) **issue 2036**',
+      ),
+    );
+
+    assert.isTrue(rendered.includes('`bug`'));
+
+    assert.isTrue(rendered.includes('2 comments'));
+  });
+
+  test('says how each issue stands for being started, and what it waits for', () => {
+    const rendered = renderMarkdown(
+      buildReport({
+        repo: { owner: 'noshiro-pf', name: 'mono' },
+        defaultBranch: 'main',
+        generatedAt: '2026-09-18T09:00:00Z',
+        required: [],
+        merged: [],
+        mergedWithinDays: 7,
+        issues: [
+          { ...issue(2001), startAfter: [1901, 1700] },
+          { ...issue(2002), startAfter: [1700] },
+          { ...issue(2003), misplacedMergeAfter: [1901] },
+          issue(2004),
+        ],
+        issuesLimit: 30,
+        authenticated: false,
+        pulls: [facts({ number: 1901 })],
+        references: new Map([[1700, 'done']]),
+      }),
+    );
+
+    const line = (number: number): string =>
+      rendered.split('\n').find((each) => each.includes(`#${number}]`)) ?? '';
+
+    assert.include(line(2001), 'waiting · after #1901 (open), #1700 (done)');
+
+    assert.include(line(2002), 'ready · after #1700 (done)');
+
+    assert.include(
+      line(2003),
+      'Merge-After: #1901 is not read on an issue; use Start-After:',
+    );
+
+    // Free is the ordinary case, and is not said.
+    assert.notInclude(line(2004), 'free');
+  });
+
+  test('says when the list is full, so that it may not be all of them', () => {
+    const rendered = renderMarkdown(
+      report([facts({ number: 1901 })], [issue(1), issue(2), issue(3)]),
+    );
+
+    assert.isTrue(rendered.includes('## Open issues (3+)'));
+  });
+
+  test('is left out when no issue is open', () => {
+    const rendered = renderMarkdown(report([facts({ number: 1901 })]));
+
+    assert.isFalse(rendered.includes('Open issues'));
+  });
+
+  test('is there even when no pull request is open', () => {
+    const rendered = renderMarkdown(report([], [issue(2036)]));
+
+    assert.isTrue(rendered.includes('No open pull requests.'));
+
+    assert.isTrue(rendered.includes('#2036'));
+  });
+
+  test('drops the Markdown in a terminal', () => {
+    const rendered = renderTerminal(
+      report([facts({ number: 1901 })], [issue(2036)]),
+    );
+
+    assert.isTrue(rendered.includes('Open issues (1)'));
+
+    assert.isFalse(rendered.includes('## Open issues'));
+
+    assert.isTrue(rendered.includes('#2036 issue 2036'));
+
+    assert.isTrue(rendered.includes('[bug]'));
+  });
+});
+
+describe(renderTerminal, () => {
+  test('draws the same nesting without Markdown', () => {
+    const rendered = renderTerminal(
+      report([
+        facts({ number: 1901 }),
+        facts({ number: 1903, body: 'Merge-After: #1901' }),
+      ]),
+    );
+
+    assert.isFalse(rendered.includes(']('));
+
+    assert.isTrue(rendered.includes('#1901'));
+
+    assert.isTrue(rendered.includes('#1903'));
+
+    assert.isTrue(/[└├]/u.test(rendered));
+  });
+});

package/src/pr-report/repo-settings.mts

@@ -0,0 +1,34 @@
+/** The contexts a pull request has to satisfy, from where the repository says. */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { MAIN_RULESET_PATH, parseRuleset, type RepoRef } from 'pr-report-core';
+import { Result } from 'ts-data-forge';
+import { repoRoot } from '../lib/index.mjs';
+import type { Client } from './github.mjs';
+
+/**
+ * The required contexts: from the checkout's
+ * `repo-settings/rulesets/main.json` where the repository declares its
+ * ruleset there (`parseRuleset` says why the declaration rather than
+ * GitHub), and otherwise from what GitHub enforces on the default branch.
+ */
+export const readRequiredContexts = async (
+  client: Client,
+  repo: RepoRef,
+  defaultBranch: string,
+): Promise<Result<readonly string[], string>> => {
+  const file = path.resolve(await repoRoot(), MAIN_RULESET_PATH);
+
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const text = await Result.fromPromise(fs.readFile(file, 'utf8'));
+
+  if (Result.isErr(text)) {
+    return client.requiredContexts(repo, defaultBranch);
+  }
+
+  return Result.map(
+    parseRuleset(text.value, file),
+    ({ requiredContexts }) => requiredContexts,
+  );
+};

package/src/push-fixed-pr/index.mts

@@ -0,0 +1 @@
+export * from './push-fixed-pr.mjs';

package/src/push-fixed-pr/push-fixed-pr.mts

@@ -0,0 +1,276 @@
+import {
+  PNPM_UPDATE_BRANCH,
+  SKIP_CI_LABEL,
+  stackDescendants,
+  type QueueComments,
+  type QueueOwner,
+  type ReportEntry,
+} from 'pr-report-core';
+import { Arr, Result } from 'ts-data-forge';
+import {
+  addLabel,
+  git,
+  pullRequestNumber,
+  resolveApiContext,
+  sh,
+} from '../lib/index.mjs';
+import { readQueueState } from '../pr-report/index.mjs';
+import { pushLeased, restack, type BranchOf } from '../unblock-prs/index.mjs';
+
+/** What `push-fixed-pr --help` prints. */
+export const PUSH_FIXED_PR_HELP = [
+  'Usage: push-fixed-pr <number> --by <claimant> --head <commit>',
+  '',
+  'Hands a fixed pull request back to unblock-prs: pushes <commit> onto the',
+  'branch --by claimed, under skip-ci, and restacks the pull requests stacked',
+  "on it. It refuses unless the claim on it is --by's.",
+  '',
+  'Options:',
+  '  --by <claimant>  the claimant, as given to claim-pr',
+  "  --head <commit>  the fix, already in this repository's objects",
+  '  -h, --help       show this help',
+].join('\n');
+
+/**
+ * Hands a fixed pull request back to the worker: pushes the commit a session
+ * made onto the branch it claimed, under `skip-ci`, and carries the layers
+ * stacked on it along — with the worker's own code (`pushLeased`, `restack`
+ * in `unblock-prs/rebase.mts`), so that a session's push is the push the
+ * worker would have made.
+ *
+ * ```sh
+ * push-fixed-pr 2267 --by <session URL> --head <commit>
+ * ```
+ *
+ * It refuses unless the pull request is a skill's (`pr-report-core`'s
+ * `queue-owner.mts`, read as every other command reads it) and the claim on
+ * it is `--by`'s: the claim is what kept the worker off it, and its head is
+ * the lease. `<commit>` is the fix, already in this repository's objects —
+ * any worktree of it will do. The push moves the head, which ends the claim
+ * and resolves the set-aside: from then on the pull request is the worker's.
+ */
+export const pushFixedPr = async (
+  args: PushArgs,
+): Promise<Result<string, string>> => {
+  const commit = await git(
+    `git rev-parse --verify --quiet ${sh(`${args.head}^0`)}`,
+  );
+
+  if (Result.isErr(commit)) {
+    return Result.err(`${args.head} is not a commit here.`);
+  }
+
+  const state = await readQueueState();
+
+  if (Result.isErr(state)) {
+    return Result.err(`cannot read the queue: ${state.value}`);
+  }
+
+  const { decided, queue, owners } = state.value;
+
+  const decision = decidePush({
+    number: args.number,
+    by: args.by,
+    head: commit.value.trim(),
+    entries: decided.entries,
+    owner: owners.get(args.number),
+    comments: queue.get(args.number),
+  });
+
+  if (decision.kind === 'refuse') {
+    return Result.err(`#${args.number} not pushed: ${decision.reason}.`);
+  }
+
+  if (decision.addSkipCi) {
+    const api = await resolveApiContext();
+
+    const added = Result.isErr(api)
+      ? api
+      : await addLabel(api.value, args.number, SKIP_CI_LABEL);
+
+    if (Result.isErr(added)) {
+      return Result.err(
+        `#${args.number} not pushed: cannot put ${SKIP_CI_LABEL} on it first, and without it the push runs the matrix: ${added.value}`,
+      );
+    }
+  }
+
+  const pushed = await pushLeased(
+    decision.pr.headRefName,
+    decision.head,
+    decision.pr.headRefOid,
+  );
+
+  if (Result.isErr(pushed)) {
+    return Result.err(`#${args.number}: push refused: ${pushed.value}`);
+  }
+
+  if (pushed.value === 'moved') {
+    return Result.err(
+      `#${args.number}: someone pushed to ${decision.pr.headRefName} since it was claimed; throw the work away and survey again.`,
+    );
+  }
+
+  await restack(decision.pr, decision.head, decision.layers);
+
+  return Result.ok(
+    `#${args.number}: pushed ${decision.head.slice(0, 10)} under ${SKIP_CI_LABEL}${Arr.isNonEmpty(decision.layers) ? `, and carried ${decision.layers.map(({ number }) => `#${number}`).join(', ')} along` : ''}; it is the worker's again.`,
+  );
+};
+
+/**
+ * Whether `by` may push `head` to pull request `number`, and what that
+ * involves: the lease, whether `skip-ci` has to go on first, and the layers
+ * to carry along, lowest first.
+ */
+export const decidePush = ({
+  number,
+  by,
+  head,
+  entries,
+  owner,
+  comments,
+}: Readonly<{
+  number: number;
+  by: string;
+  head: string;
+  entries: readonly ReportEntry[];
+  owner: QueueOwner | undefined;
+  comments: QueueComments | undefined;
+}>): Readonly<
+  | {
+      kind: 'push';
+      pr: BranchOf;
+      head: string;
+      addSkipCi: boolean;
+      layers: readonly BranchOf[];
+    }
+  | { kind: 'refuse'; reason: string }
+> => {
+  const entry = entries.find((e) => e.number === number);
+
+  if (entry === undefined) {
+    return { kind: 'refuse', reason: 'it is not open' };
+  }
+
+  if (owner?.owner !== 'skill') {
+    return {
+      kind: 'refuse',
+      reason:
+        owner === undefined
+          ? 'who owns it could not be read'
+          : `it is the ${owner.owner}'s (${owner.reason}), not a skill's`,
+    };
+  }
+
+  const claim = comments?.claim;
+
+  if (
+    claim?.applies !== true ||
+    claim.says.kind !== 'standing' ||
+    claim.says.claim.by !== by
+  ) {
+    return {
+      kind: 'refuse',
+      reason: `${by} holds no claim on it at its head; claim it first (claim-pr)`,
+    };
+  }
+
+  if (head === entry.headSha) {
+    return { kind: 'refuse', reason: `${head} is already its head` };
+  }
+
+  // A generated branch, lockfile and all: its conflict is resolved by
+  // generating it again from the tip, not by a rebase resolved by hand.
+  if (
+    entry.headRef === PNPM_UPDATE_BRANCH &&
+    comments?.setAside?.says.kind === 'standing' &&
+    comments.setAside.says.setAside.reason === 'rebase-failed'
+  ) {
+    return {
+      kind: 'refuse',
+      reason:
+        'a conflict on the dependency update is resolved by building it again: pnpm run rebuild-pnpm-update',
+    };
+  }
+
+  const parents: ReadonlyMap<number, number> = new Map(
+    Arr.generate(function* () {
+      for (const e of entries) {
+        if (e.stackedOn !== undefined) {
+          yield [e.number, e.stackedOn] as const;
+        }
+      }
+    }),
+  );
+
+  return {
+    kind: 'push',
+    pr: branchOf(entry),
+    head,
+    addSkipCi: entry.labels.every(({ name }) => name !== SKIP_CI_LABEL),
+    layers: stackDescendants(parents, number).flatMap((n) =>
+      entries.filter((e) => e.number === n).map(branchOf),
+    ),
+  };
+};
+
+/** The command line, or what is wrong with it. */
+export const parsePushArgs = (args: readonly string[]): PushArgs | string => {
+  const flagValue = (flag: string): string | undefined => {
+    const at = args.indexOf(flag);
+
+    return at === -1 ? undefined : args[at + 1];
+  };
+
+  const by = flagValue('--by');
+
+  const head = flagValue('--head');
+
+  const flagged = new Set(
+    Arr.generate(function* () {
+      for (const flag of ['--by', '--head']) {
+        const at = args.indexOf(flag);
+
+        if (at === -1) {
+          continue;
+        }
+
+        yield at;
+
+        yield at + 1;
+      }
+    }),
+  );
+
+  const positional = args.filter(
+    (arg, index) => arg !== '--' && !flagged.has(index),
+  );
+
+  const [first] = positional;
+
+  const number = first === undefined ? undefined : pullRequestNumber(first);
+
+  return positional.length > 1
+    ? `unexpected argument: ${Arr.tail(positional).join(' ')}`
+    : number === undefined
+      ? 'name the pull request by its number'
+      : by === undefined || by.startsWith('--')
+        ? '--by names the claimant, as it claimed the pull request'
+        : head === undefined || !/^[0-9a-f]{7,40}$/u.test(head)
+          ? '--head names the commit to push, by its SHA'
+          : { number, by, head };
+};
+
+export type PushArgs = Readonly<{ number: number; by: string; head: string }>;
+
+const branchOf = (entry: ReportEntry): BranchOf =>
+  ({
+    number: entry.number,
+    // Every entry is an open pull request.
+    state: 'OPEN',
+    headRefName: entry.headRef,
+    headRefOid: entry.headSha,
+    baseRefName: entry.baseRef,
+    isCrossRepository: entry.fromFork,
+  }) as const;