pr-merge-queue 0.0.0-stage → 0.0.0

package/src/pr-report/index.mts

@@ -0,0 +1,7 @@
+export * from './github.mjs';
+export * from './linked-issues.mjs';
+export * from './main.mjs';
+export * from './options.mjs';
+export * from './queue.mjs';
+export * from './render.mjs';
+export * from './repo-settings.mjs';

package/src/pr-report/linked-issues.mts

@@ -0,0 +1,51 @@
+/** The issues a pull request body says it closes. */
+
+import { outsideCodeFences, type RepoRef } from 'pr-report-core';
+import { Arr, Num, Result } from 'ts-data-forge';
+
+/**
+ * The keywords GitHub acts on, followed by `#12` or by the issue's URL.
+ *
+ * Only a closing keyword is read. A body mentioning `#12` in a sentence is a
+ * cross-reference — GitHub closes nothing for it, and reporting it as "the
+ * issue this pull request is for" would make every mention of another pull
+ * request look like a link.
+ */
+const CLOSING_REFERENCE =
+  /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\b[^\S\n]*:?[^\S\n]*(?:#(?<number>\d+)|https:\/\/github\.com\/(?<owner>[\w.-]+)\/(?<repo>[\w.-]+)\/issues\/(?<urlNumber>\d+))\b/giu;
+
+/**
+ * The issue numbers a body declares this pull request closes, in the order
+ * they first appear.
+ *
+ * Read from the body rather than from GitHub's own list because that list is
+ * only in the GraphQL API, which needs a token. What this misses is a link
+ * made by hand in the sidebar, and a reference to another repository's issue
+ * — deliberately, since neither can be rendered as a local `#N`.
+ *
+ * Fenced code is skipped for the same reason `Merge-After:` skips it.
+ */
+export const parseClosingIssueRefs = (
+  body: string,
+  repo: RepoRef,
+): readonly number[] =>
+  Arr.uniq(
+    outsideCodeFences(body)
+      .matchAll(CLOSING_REFERENCE)
+      .flatMap((match) => {
+        const { number, owner, repo: name, urlNumber } = match.groups ?? {};
+
+        return number !== undefined
+          ? readNumber(number)
+          : owner === repo.owner && name === repo.name
+            ? readNumber(urlNumber ?? '')
+            : [];
+      })
+      .toArray(),
+  );
+
+const readNumber = (raw: string): readonly number[] => {
+  const parsed = Num.safeParseInt(raw);
+
+  return Result.isOk(parsed) ? [parsed.value] : [];
+};

package/src/pr-report/linked-issues.test.mts

@@ -0,0 +1,65 @@
+import { parseClosingIssueRefs } from './linked-issues.mjs';
+
+const repo = { owner: 'noshiro-pf', name: 'mono' } as const;
+
+describe(parseClosingIssueRefs, () => {
+  test('reads every keyword GitHub reads', () => {
+    for (const keyword of [
+      'close',
+      'closes',
+      'closed',
+      'fix',
+      'fixes',
+      'fixed',
+      'resolve',
+      'resolves',
+      'resolved',
+    ]) {
+      assert.deepStrictEqual(
+        parseClosingIssueRefs(`${keyword} #12`, repo),
+        [12],
+      );
+    }
+  });
+
+  test('is case-insensitive and accepts the colon form', () => {
+    assert.deepStrictEqual(parseClosingIssueRefs('Closes: #12', repo), [12]);
+  });
+
+  test('reads a full URL, but only for this repository', () => {
+    assert.deepStrictEqual(
+      parseClosingIssueRefs(
+        'Fixes https://github.com/noshiro-pf/mono/issues/34',
+        repo,
+      ),
+      [34],
+    );
+
+    assert.deepStrictEqual(
+      parseClosingIssueRefs(
+        'Fixes https://github.com/someone/else/issues/34',
+        repo,
+      ),
+      [],
+    );
+  });
+
+  test('a bare reference is not a link', () => {
+    // `#12` on its own is a cross-reference; GitHub closes nothing for it,
+    // and neither does this.
+    assert.deepStrictEqual(parseClosingIssueRefs('see #12', repo), []);
+  });
+
+  test('ignores fenced code, like `Merge-After:` does', () => {
+    const body = ['```markdown', 'Closes #12', '```', 'Closes #13'].join('\n');
+
+    assert.deepStrictEqual(parseClosingIssueRefs(body, repo), [13]);
+  });
+
+  test('deduplicates and keeps the first occurrence order', () => {
+    assert.deepStrictEqual(
+      parseClosingIssueRefs('Closes #5\nFixes #3\nResolves #5', repo),
+      [5, 3],
+    );
+  });
+});

package/src/pr-report/main.mts

@@ -0,0 +1,257 @@
+import {
+  buildReport,
+  type IssueDeclarations,
+  type OpenIssue,
+  type PrReport,
+  type PullRequestFacts,
+  type QueueComments,
+  type QueueOwner,
+  type RepoRef,
+} from 'pr-report-core';
+import { Arr, Result } from 'ts-data-forge';
+import {
+  currentEpochMs,
+  isoSeconds,
+  resolveRepo,
+  tokenFromEnv,
+} from '../lib/index.mjs';
+import { createClient, type Client } from './github.mjs';
+import type { Format, Options } from './options.mjs';
+import { ownersOf } from './queue.mjs';
+import { renderMarkdown, renderTerminal } from './render.mjs';
+import { readRequiredContexts } from './repo-settings.mjs';
+
+/**
+ * Reports the state of every open pull request, in one page.
+ *
+ * What it answers, and why each part is here rather than a click away on
+ * GitHub:
+ *
+ * - **The merge order.** The `Merge-After:` trailers and the stacks — a pull
+ *   request onto another's branch — describe a graph that the pull request
+ *   list cannot show at all; a stack of four reads as four unrelated rows
+ *   there. Drawn as a tree, the one at the top is the one to look at.
+ * - **The issues each pull request closes**, so that "what is this for" does
+ *   not need the body opened.
+ * - **The labels**, because `skip-ci` and `merge-queued` are how this
+ *   repository says "not yet" and "ready", and neither means anything until
+ *   someone reads them.
+ * - **The verdict of the checks the ruleset requires**, which is not the same
+ *   as the checks that ran: a required context with nothing reported sits as
+ *   "Expected — waiting" forever, and a red aggregate does not name what
+ *   failed. Both are said here by name.
+ * - **How far ahead and behind the branch is.** A branch behind its base runs
+ *   nothing and merges nothing, and the pull request page states it only as
+ *   a sentence, without the size of the gap. For a stacked pull request the
+ *   base is the layer below, and behind it means the layer below has moved
+ *   and this one has not been restacked onto it.
+ * - **What landed recently.** The one section that is not about the queue,
+ *   and the first question a reader of a daily report has: did the thing I
+ *   queued yesterday go in.
+ * - **What is open that is not a pull request** — the open issues, so that
+ *   "what is there to do" does not need a second tab.
+ * - **In the JSON only, whether `unblock-prs` set each one aside, who has
+ *   claimed it** (`pr-report-core`'s `queue-comments.mts`), **and who moves
+ *   it next** (`owner`: `worker`, `skill`, `human` or `none`; `queue.mts`),
+ *   which is how a session working the queue picks what to fix.
+ *
+ * It reads and prints. Nothing here labels, rebases, merges or comments —
+ * that is `unblock-prs`, and keeping the report incapable of it is what makes
+ * it safe to run anywhere, on a schedule, with a read-only token or none.
+ */
+export const prReport = async (
+  options: Options,
+): Promise<Result<string, string>> => {
+  const repo = await resolveRepo(options.repo);
+
+  if (Result.isErr(repo)) {
+    return repo;
+  }
+
+  const client = createClient(tokenFromEnv());
+
+  const defaultBranch = await client.defaultBranch(repo.value);
+
+  if (Result.isErr(defaultBranch)) {
+    return defaultBranch;
+  }
+
+  const required = await readRequiredContexts(
+    client,
+    repo.value,
+    defaultBranch.value,
+  );
+
+  if (Result.isErr(required)) {
+    return required;
+  }
+
+  const facts = await client.facts(repo.value);
+
+  if (Result.isErr(facts)) {
+    return facts;
+  }
+
+  // One more request, and the one section that is not about what is open:
+  // what landed. A report that only lists the queue cannot answer "did the
+  // thing I queued yesterday go in", which is the first question a reader of
+  // a daily report has.
+  const merged = await client.merged(
+    repo.value,
+    options.mergedDays,
+    options.mergedLimit,
+  );
+
+  if (Result.isErr(merged)) {
+    return merged;
+  }
+
+  // And one more for what is open that is not a pull request, so that "what
+  // is there to do" is answered in one place rather than two.
+  const issues = await client.issues(repo.value, options.issuesLimit);
+
+  if (Result.isErr(issues)) {
+    return issues;
+  }
+
+  // And one request for each issue the open pull requests close that the
+  // open list did not cover, whose `Start-After:` the pull request closing
+  // it inherits as a merge order.
+  const issueDeclarations = await declarationsOf(
+    client,
+    repo.value,
+    facts.value,
+    issues.value,
+  );
+
+  // And one for each thing the issues' `Start-After:` names that is neither
+  // a listed issue nor an open pull request, to say where it stands.
+  const references = await client.references(
+    repo.value,
+    namedBeyond(facts.value, issues.value),
+  );
+
+  // Only the JSON carries these: they are what a session working the queue
+  // reads (`claude-plugin/skills/unblock-prs/SKILL.md`), not what a person does.
+  const queue =
+    options.format === 'json'
+      ? await client.queueComments(repo.value, defaultBranch.value, facts.value)
+      : new Map<number, QueueComments>();
+
+  const report = buildReport({
+    repo: repo.value,
+    defaultBranch: defaultBranch.value,
+    generatedAt: isoSeconds(currentEpochMs()),
+    required: required.value,
+    authenticated: client.authenticated,
+    pulls: facts.value,
+    merged: merged.value,
+    mergedWithinDays: options.mergedDays,
+    issues: issues.value,
+    issuesLimit: options.issuesLimit,
+    issueDeclarations,
+    references,
+  });
+
+  const owners = ownersOf(report, queue, defaultBranch.value, currentEpochMs());
+
+  return Result.ok(print(report, queue, owners, options.format));
+};
+
+/**
+ * What the open issues listed, and the ones the open pull requests close
+ * beyond them, declare with `Start-After:`. A closing issue already known to
+ * be closed is not read: it closes nothing that is still to do.
+ */
+const declarationsOf = async (
+  client: Client,
+  repo: RepoRef,
+  pulls: readonly PullRequestFacts[],
+  issues: readonly OpenIssue[],
+): Promise<IssueDeclarations> => {
+  const listed = new Set(issues.map(({ number }) => number));
+
+  const beyond = Arr.uniq(
+    pulls.flatMap(({ linkedIssues }) =>
+      linkedIssues
+        .filter(
+          ({ number, state }) => state !== 'closed' && !listed.has(number),
+        )
+        .map(({ number }) => number),
+    ),
+  ).toSorted((a, b) => a - b);
+
+  const read = await client.issueBodies(repo, beyond);
+
+  const mut_startAfter = new Map(
+    issues.map(({ number, startAfter }) => [number, startAfter] as const),
+  );
+
+  const mut_open = new Set(listed);
+
+  for (const [number, { open, startAfter }] of read) {
+    mut_startAfter.set(number, startAfter);
+
+    if (open) {
+      mut_open.add(number);
+    }
+  }
+
+  return { startAfter: mut_startAfter, open: mut_open };
+};
+
+/** What the listed issues name that is neither listed nor an open pull request. */
+const namedBeyond = (
+  pulls: readonly PullRequestFacts[],
+  issues: readonly OpenIssue[],
+): readonly number[] => {
+  const known = new Set(
+    pulls
+      .map(({ number }) => number)
+      .concat(issues.map(({ number }) => number)),
+  );
+
+  return Arr.uniq(issues.flatMap(({ startAfter }) => startAfter))
+    .filter((number) => !known.has(number))
+    .toSorted((a, b) => a - b);
+};
+
+const print = (
+  report: PrReport,
+  queue: ReadonlyMap<number, QueueComments>,
+  owners: ReadonlyMap<number, QueueOwner>,
+  format: Format,
+): string => {
+  switch (format) {
+    case 'json':
+      return JSON.stringify(serializable(report, queue, owners), undefined, 2);
+
+    case 'markdown':
+      return renderMarkdown(report);
+
+    case 'terminal':
+      return renderTerminal(report);
+  }
+};
+
+/**
+ * The report with its maps turned into objects, because `JSON.stringify`
+ * writes a `Map` as `{}` and would quietly drop every check verdict, and with
+ * what the queue's comments say on each entry (absent when there is none)
+ * and who moves it next (absent outside the queue, or when its comments
+ * could not be read; `queue.mts`).
+ */
+const serializable = (
+  report: PrReport,
+  queue: ReadonlyMap<number, QueueComments>,
+  owners: ReadonlyMap<number, QueueOwner>,
+): unknown =>
+  ({
+    ...report,
+    entries: report.entries.map((entry) => ({
+      ...entry,
+      reported: Object.fromEntries(entry.reported),
+      ...queue.get(entry.number),
+      owner: owners.get(entry.number),
+    })),
+  }) as const;

package/src/pr-report/options.mts

@@ -0,0 +1,140 @@
+/** What the command line says, and how it is read. */
+
+import { Result } from 'ts-data-forge';
+import { parseCommandArgs, positiveInteger } from '../lib/index.mjs';
+
+export const FORMATS = ['json', 'markdown', 'terminal'] as const;
+
+export type Format = (typeof FORMATS)[number];
+
+export type Options = Readonly<{
+  format: Format;
+  /** `owner/name`; the repository this checkout is of when not given. */
+  repo: string | undefined;
+  /** How far back the "recently merged" section goes. */
+  mergedDays: number;
+  /** And how many of them it lists, whatever the window turns up. */
+  mergedLimit: number;
+  /** How many open issues it lists, most recently updated first. */
+  issuesLimit: number;
+}>;
+
+/**
+ * A week, so that a report read on a Monday still covers the Friday. Long
+ * enough to answer "what landed since I last looked" and short enough that
+ * the section stays a list rather than an archive.
+ */
+export const DEFAULT_MERGED_DAYS = 7;
+
+/**
+ * A cap as well as a window, and a matter of reading rather than of
+ * fitting. Twenty is more than enough to answer "did the thing I queued go in", which is what
+ * the section is for, and past that the section stops being a list and
+ * starts being an archive.
+ */
+export const DEFAULT_MERGED_LIMIT = 20;
+
+/**
+ * Enough to see what is open without the section becoming the report. The
+ * page asks for the same number.
+ */
+export const DEFAULT_ISSUES_LIMIT = 30;
+
+export const HELP = [
+  'Usage: pr-report [options]',
+  '',
+  'Reports every open pull request: the order they declare with',
+  '`Merge-After:`, the issues they close, their labels, the verdict of the',
+  'checks the ruleset requires, and how far each branch is from its base.',
+  '',
+  'Options:',
+  `  --format <${FORMATS.join('|')}>  how to print it (default terminal)`,
+  '                                   `json` is the whole report, bodies and all',
+  '  --repo <owner/name>              which repository (default: this one)',
+  `  --merged-days <n>                how far back "recently merged" goes (default ${DEFAULT_MERGED_DAYS})`,
+  `  --merged-limit <n>               how many it lists at most (default ${DEFAULT_MERGED_LIMIT})`,
+  `  --issues-limit <n>               how many open issues it lists (default ${DEFAULT_ISSUES_LIMIT})`,
+  '  -h, --help                       show this help',
+  '',
+  'Reads GH_TOKEN or GITHUB_TOKEN when one is set. Without it the public API',
+  'allows 60 requests an hour, which is about twenty pull requests, and the',
+  'issue links are the ones the bodies declare rather than GitHub’s own list.',
+].join('\n');
+
+export const parseOptions = (
+  args: readonly string[],
+): Result<Options | 'help', string> => {
+  const parsed = parseCommandArgs(args, {
+    format: { type: 'string' },
+    repo: { type: 'string' },
+    'merged-days': { type: 'string' },
+    'merged-limit': { type: 'string' },
+    'issues-limit': { type: 'string' },
+  });
+
+  if (Result.isErr(parsed)) {
+    return parsed;
+  }
+
+  if (parsed.value === 'help') {
+    return Result.ok('help');
+  }
+
+  const values = parsed.value;
+
+  const format = values.format ?? 'terminal';
+
+  if (!isFormat(format)) {
+    return Result.err(
+      `--format must be one of ${FORMATS.join(', ')}, got ${JSON.stringify(format)}`,
+    );
+  }
+
+  const mergedDays = positiveInteger(
+    'merged-days',
+    values['merged-days'],
+    DEFAULT_MERGED_DAYS,
+  );
+
+  if (Result.isErr(mergedDays)) {
+    return mergedDays;
+  }
+
+  const mergedLimit = positiveInteger(
+    'merged-limit',
+    values['merged-limit'],
+    DEFAULT_MERGED_LIMIT,
+  );
+
+  if (Result.isErr(mergedLimit)) {
+    return mergedLimit;
+  }
+
+  const issuesLimit = positiveInteger(
+    'issues-limit',
+    values['issues-limit'],
+    DEFAULT_ISSUES_LIMIT,
+  );
+
+  if (Result.isErr(issuesLimit)) {
+    return issuesLimit;
+  }
+
+  return Result.ok({
+    format,
+    repo: values.repo,
+    mergedDays: mergedDays.value,
+    mergedLimit: mergedLimit.value,
+    issuesLimit: issuesLimit.value,
+  });
+};
+
+/**
+ * Typed as a set of plain strings so that the membership test takes the
+ * string it is narrowing. `FORMATS.includes(value)` does not compile against
+ * the strict standard library, whose `includes` accepts only the element
+ * type — which is the very thing being established here.
+ */
+const FORMAT_SET: ReadonlySet<string> = new Set(FORMATS);
+
+const isFormat = (value: string): value is Format => FORMAT_SET.has(value);

package/src/pr-report/queue.mts

@@ -0,0 +1,125 @@
+import {
+  buildEntries,
+  queueOwnerOfEntry,
+  type DecidedEntries,
+  type QueueComments,
+  type QueueOwner,
+  type RepoRef,
+} from 'pr-report-core';
+import { Arr, Result } from 'ts-data-forge';
+import { currentEpochMs, resolveRepo, tokenFromEnv } from '../lib/index.mjs';
+import { createClient } from './github.mjs';
+import { readRequiredContexts } from './repo-settings.mjs';
+
+/**
+ * Who moves each open pull request in the queue next (`pr-report-core`'s
+ * `queue-owner.mts`), from what `pr-report` reads.
+ *
+ * Every command a session runs on the queue decides through here — the
+ * `owner` in `pr-report --format json`, `claim-pr`, `push-fixed-pr`,
+ * `rebuild-pnpm-update` and `report-unowned-prs` — so none of them can come
+ * to a different answer from the others, and the worker asks the same
+ * function with the same facts read through `gh`.
+ */
+export const ownersOf = (
+  decided: DecidedEntries,
+  queue: ReadonlyMap<number, QueueComments>,
+  defaultBranch: string,
+  nowEpochMs: number,
+): ReadonlyMap<number, QueueOwner> =>
+  new Map(
+    Arr.generate(function* () {
+      for (const entry of decided.entries) {
+        // A pull request whose comments could not be read has no owner rather
+        // than the worker's: nothing is known of a set-aside on it.
+        const comments = queue.get(entry.number);
+
+        const owner =
+          comments === undefined
+            ? undefined
+            : queueOwnerOfEntry(entry, comments, {
+                defaultBranch,
+                cycles: decided.cycles,
+                nowEpochMs,
+              });
+
+        if (owner !== undefined) {
+          yield [entry.number, owner] as const;
+        }
+      }
+    }),
+  );
+
+export type QueueState = Readonly<{
+  repo: RepoRef;
+  defaultBranch: string;
+  decided: DecidedEntries;
+  queue: ReadonlyMap<number, QueueComments>;
+  owners: ReadonlyMap<number, QueueOwner>;
+}>;
+
+/**
+ * Reads the open pull requests, this account's comments on them and the
+ * owner of each, for a command that acts on the queue. It needs a token
+ * whose account is the one `unblock-prs` writes as: without one no comment
+ * is trusted, and there is no owner to read.
+ */
+export const readQueueState = async (
+  repoOption?: string,
+): Promise<Result<QueueState, string>> => {
+  const repo = await resolveRepo(repoOption);
+
+  if (Result.isErr(repo)) {
+    return repo;
+  }
+
+  const client = createClient(tokenFromEnv());
+
+  if (!client.authenticated) {
+    return Result.err(
+      'no GH_TOKEN or GITHUB_TOKEN: the queue comments, and so the owners, cannot be read',
+    );
+  }
+
+  const defaultBranch = await client.defaultBranch(repo.value);
+
+  if (Result.isErr(defaultBranch)) {
+    return defaultBranch;
+  }
+
+  const required = await readRequiredContexts(
+    client,
+    repo.value,
+    defaultBranch.value,
+  );
+
+  if (Result.isErr(required)) {
+    return required;
+  }
+
+  const facts = await client.facts(repo.value);
+
+  if (Result.isErr(facts)) {
+    return facts;
+  }
+
+  const queue = await client.queueComments(
+    repo.value,
+    defaultBranch.value,
+    facts.value,
+  );
+
+  const decided = buildEntries({
+    required: required.value,
+    defaultBranch: defaultBranch.value,
+    pulls: facts.value,
+  });
+
+  return Result.ok({
+    repo: repo.value,
+    defaultBranch: defaultBranch.value,
+    decided,
+    queue,
+    owners: ownersOf(decided, queue, defaultBranch.value, currentEpochMs()),
+  });
+};