pr-merge-queue 0.0.0-stage → 0.0.0

package/src/lib/github-api.test.mts

@@ -0,0 +1,40 @@
+import { Result } from 'ts-data-forge';
+import { parseRepoRef, repoOfUrl } from './github-api.mjs';
+
+describe(parseRepoRef, () => {
+  test('reads `owner/name`', () => {
+    assert.deepStrictEqual(
+      parseRepoRef('noshiro-pf/mono'),
+      Result.ok({ owner: 'noshiro-pf', name: 'mono' }),
+    );
+  });
+
+  test.each(['mono', 'noshiro-pf/', '/mono', 'a/b/c'])('refuses %j', (raw) => {
+    assert.deepStrictEqual(
+      parseRepoRef(raw),
+      Result.err(`expected owner/name, got ${JSON.stringify(raw)}`),
+    );
+  });
+});
+
+describe(repoOfUrl, () => {
+  test.each([
+    'https://github.com/noshiro-pf/mono',
+    'https://github.com/noshiro-pf/mono.git',
+    'git+https://github.com/noshiro-pf/mono.git',
+    'git@github.com:noshiro-pf/mono.git',
+  ])('reads the repository out of %j', (url) => {
+    assert.deepStrictEqual(repoOfUrl(url), {
+      owner: 'noshiro-pf',
+      name: 'mono',
+    });
+  });
+
+  test.each([
+    'http://local_proxy@127.0.0.1:41234/git/noshiro-pf/mono',
+    'https://gitlab.com/noshiro-pf/mono.git',
+    '',
+  ])('names no GitHub repository in %j', (url) => {
+    assert.isUndefined(repoOfUrl(url));
+  });
+});

package/src/lib/index.mts

@@ -0,0 +1,6 @@
+export * from './cli-args.mjs';
+export * from './github-api.mjs';
+export * from './json.mjs';
+export * from './log.mjs';
+export * from './shell.mjs';
+export * from './time.mjs';

package/src/lib/json.mts

@@ -0,0 +1,43 @@
+/** Reading JSON into a schema's type, from text or from a file. */
+
+import * as fs from 'node:fs/promises';
+import { Json, Result } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+
+/**
+ * `text` parsed and validated against `schema`. `source` names where the text
+ * came from — a file, an API route, a command — so that the message says
+ * which answer was wrong, not only how.
+ */
+export const parseJson = <A,>(
+  text: string,
+  schema: t.Type<A>,
+  source: string,
+): Result<A, string> => {
+  const parsed = Json.parse(text);
+
+  if (Result.isErr(parsed)) {
+    return Result.err(`${source} is not valid JSON: ${parsed.value}`);
+  }
+
+  const validated = schema.validate(parsed.value);
+
+  return Result.isErr(validated)
+    ? Result.err(
+        `${source} has an unexpected shape:\n${t.validationErrorsToMessages(validated.value).join('\n')}`,
+      )
+    : Result.ok(validated.value);
+};
+
+/** {@link parseJson} of a file's contents, the file naming itself. */
+export const readJsonFile = async <A,>(
+  file: string,
+  schema: t.Type<A>,
+): Promise<Result<A, string>> => {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const text = await Result.fromPromise(fs.readFile(file, 'utf8'));
+
+  return Result.isErr(text)
+    ? Result.err(`cannot read ${file}`)
+    : parseJson(text.value, schema, file);
+};

package/src/lib/json.test.mts

@@ -0,0 +1,34 @@
+import { Result } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+import { parseJson } from './json.mjs';
+
+describe(parseJson, () => {
+  const Schema = t.record({ number: t.number() });
+
+  test('answers the value when the text is JSON of the shape', () => {
+    assert.deepStrictEqual(
+      parseJson('{"number":1}', Schema, 'gh pr view 1'),
+      Result.ok({ number: 1 }),
+    );
+  });
+
+  test('names the source when the text is not JSON', () => {
+    const parsed = parseJson('not json', Schema, 'gh pr view 1');
+
+    assert.isTrue(Result.isErr(parsed));
+
+    assert.isTrue(parsed.value.startsWith('gh pr view 1 is not valid JSON: '));
+  });
+
+  test('names the source and the field when the shape is wrong', () => {
+    const parsed = parseJson('{"number":"1"}', Schema, 'gh pr view 1');
+
+    assert.isTrue(Result.isErr(parsed));
+
+    assert.isTrue(
+      parsed.value.startsWith('gh pr view 1 has an unexpected shape:\n'),
+    );
+
+    assert.include(parsed.value, 'number');
+  });
+});

package/src/lib/log.mts

@@ -0,0 +1,19 @@
+/** The log line every long-running command writes. */
+
+import { currentEpochMs, localTimestamp } from './time.mjs';
+
+export const log = (message: string): void => {
+  console.info(logLine(message));
+};
+
+/**
+ * `message` stamped with the time in the machine's time zone (`TZ`), because
+ * the person reading the log reads it against their own clock. The offset
+ * stays in the stamp, so a line pasted elsewhere still names one instant.
+ * `offsetMinutes` (east of UTC) is the machine's unless given.
+ */
+export const logLine = (
+  message: string,
+  epochMs: number = currentEpochMs(),
+  offsetMinutes?: number,
+): string => `[${localTimestamp(epochMs, offsetMinutes)}] ${message}` as const;

package/src/lib/log.test.mts

@@ -0,0 +1,45 @@
+// cspell:ignore unstub
+
+import { logLine } from './log.mjs';
+
+describe(logLine, () => {
+  test('stamps the line with the local time and its offset from UTC', () => {
+    assert.strictEqual(
+      logLine('surveying', Date.parse('2026-09-27T12:03:04.500Z'), 9 * 60),
+      '[2026-09-27T21:03:04.500+09:00] surveying',
+    );
+  });
+
+  test('writes the offset of a zone west of UTC, and of UTC itself', () => {
+    assert.strictEqual(
+      logLine('surveying', Date.parse('2026-09-27T12:03:04Z'), -4 * 60),
+      '[2026-09-27T08:03:04.000-04:00] surveying',
+    );
+
+    assert.strictEqual(
+      logLine('surveying', Date.parse('2026-09-27T12:03:04Z'), 0),
+      '[2026-09-27T12:03:04.000+00:00] surveying',
+    );
+  });
+
+  describe('without a time given', () => {
+    test.each([
+      [
+        'Asia/Tokyo',
+        /^\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}\+09:00\] surveying$/u,
+      ],
+      [
+        'UTC',
+        /^\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}\+00:00\] surveying$/u,
+      ],
+    ] as const)('uses the machine time zone (TZ=%s)', (tz, expected) => {
+      vi.stubEnv('TZ', tz);
+
+      try {
+        assert.match(logLine('surveying'), expected);
+      } finally {
+        vi.unstubAllEnvs();
+      }
+    });
+  });
+});

package/src/lib/shell.mts

@@ -0,0 +1,52 @@
+/** Running `git`, `gh` and `pnpm` from a command, and quoting what they take. */
+
+import { Result } from 'ts-data-forge';
+import { $ } from 'ts-repo-utils';
+
+/**
+ * Runs a git or gh command silently and resolves to its stdout, or to a
+ * message that includes what it printed to stderr. `unblock-prs` runs its
+ * `pnpm` commands through it too. It runs where the command was started
+ * unless told otherwise; git finds the repository from any directory in it.
+ */
+export const git = async (
+  command: string,
+  cwd: string = process.cwd(),
+): Promise<Result<string, string>> => {
+  const result = await $(command, {
+    cwd,
+    silent: true,
+    env: childEnv,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+  return Result.isOk(result)
+    ? Result.ok(result.value.stdout)
+    : Result.err(result.value.message.trim());
+};
+
+/**
+ * The root of the repository the command runs in, where its configuration
+ * files are read from: the working tree holding the current directory, or
+ * the current directory itself where git finds none (a tree without `.git`).
+ */
+export const repoRoot = async (): Promise<string> => {
+  const top = await git('git rev-parse --show-toplevel');
+
+  return Result.isOk(top) ? top.value.trim() : process.cwd();
+};
+
+/** Single-quotes a string for a POSIX shell. */
+export const sh = (value: string): string =>
+  `'${value.replaceAll("'", String.raw`'\''`)}'` as const;
+
+/**
+ * Passed to every git and gh invocation. `GIT_TERMINAL_PROMPT=0` turns a
+ * missing credential into a failure instead of a hang; `GIT_EDITOR=true`
+ * keeps any editor git might want out of the way.
+ */
+const childEnv: NodeJS.ProcessEnv = {
+  ...process.env,
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_EDITOR: 'true',
+} as const;

package/src/lib/time.mts

@@ -0,0 +1,49 @@
+/**
+ * The clock, and instants written as the commands write them — through
+ * `Date` rather than `Temporal`, which the oldest Node.js this package's
+ * `engines` names has only behind a flag. GitHub's
+ * timestamps are read with `pr-report-core`'s `epochMsOf`.
+ */
+
+/** Milliseconds since the epoch, now. */
+export const currentEpochMs = (): number => Date.now();
+
+/** An instant in UTC to the second, as GitHub writes one: `2026-09-29T01:02:03Z`. */
+export const isoSeconds = (epochMs: number): string =>
+  `${isoMillis(epochMs).slice(0, 19)}Z` as const;
+
+/**
+ * An instant in local time to the millisecond, with its offset from UTC:
+ * `2026-09-27T21:03:04.500+09:00`. The offset is the machine's (`TZ`) at
+ * that instant unless one is given, in minutes east of UTC.
+ */
+export const localTimestamp = (
+  epochMs: number,
+  offsetMinutes: number = machineOffsetMinutes(epochMs),
+): string => {
+  const local = isoMillis(epochMs + offsetMinutes * 60_000).slice(0, 23);
+
+  const sign = offsetMinutes < 0 ? '-' : '+';
+
+  const hours = Math.floor(Math.abs(offsetMinutes) / 60)
+    .toString()
+    .padStart(2, '0');
+
+  const minutes = (Math.abs(offsetMinutes) % 60).toString().padStart(2, '0');
+
+  return `${local}${sign}${hours}:${minutes}` as const;
+};
+
+/** `2026-09-27T12:03:04.500Z`. */
+const isoMillis = (epochMs: number): string => {
+  const date = new Date(epochMs);
+
+  return date.toISOString();
+};
+
+/** The machine's (`TZ`) offset from UTC at an instant, in minutes east. */
+const machineOffsetMinutes = (epochMs: number): number => {
+  const date = new Date(epochMs);
+
+  return -date.getTimezoneOffset();
+};

package/src/open-pr/README.md

@@ -0,0 +1,237 @@
+<!-- cspell:ignore unreviewed -->
+
+# `open-pr`
+
+`pnpm run open-pr` — opens the pull request for the current branch the way
+this repository wants one opened: held by `skip-ci`, and never armed.
+
+- [日本語](#日本語)
+- [English](#english)
+
+The conventions this follows are `CLAUDE.md`'s: "Commits and pull requests"
+and "CI". This file describes what the script does with them.
+
+## 日本語
+
+### 何をするスクリプトか
+
+現在のブランチを push し、PR を **ready for review** で作り、**`skip-ci`** と
+**`auto-rebase`** を付けます。することはこれだけです。マージもせず、
+`merge-queued` も付けず（それはレビュー後に人が行うことです）、**auto-merge も
+張りません**。
+
+### auto-merge を張らない理由
+
+`main` の ruleset は `required_approving_review_count: 0` なので、
+`.github/CODEOWNERS` が挙げるパスの外では、auto-merge の張られた PR は緑に
+なった瞬間にマージされます。レビューが済んでいるかどうかは関係ありません。
+stack する PR（下記）ならなおさらで、base は ruleset の掛からないブランチなので、
+張った瞬間に下の層のブランチへマージされかねません。
+
+そこで **auto-merge は `unblock-prs` が、`merge-queued` の付いた PR を pick した
+ときに張ります**。キューに入れること（ `merge-queued` ）が「マージしてよい」の
+合図で、それより前には誰も張りません。`skip-ci` はチェックを止め、
+`no-skip-ci-label` でマージも止めておくためのものです。
+
+### `auto-rebase` を付ける理由
+
+`auto-rebase` は、レビューや順番を待っている間も `unblock-prs` に `main` へ追従
+させるためのラベルです（`../unblock-prs/README.md`）。stack の
+場合も全層に付けます。`unblock-prs` が rebase するのは base が `main` の PR だけ
+なので、上の層に付いていても、下の層がマージされるまでは何も起きません。その
+層が `main` に付け替えられたときに初めて効きますが、そのときに付ける仕組みは無
+いので、最初から付けておきます。`skip-ci` の後に付けるのは、このラベルの
+`labeled` で走る CI を `skip-ci` で止めるためです。
+
+### 認証情報
+
+GitHub の API を直接叩きます（`gh` は要りません）。トークンは
+**`GH_TOKEN` → `GITHUB_TOKEN` → `gh auth token`** の順に探します（前2つは `gh` 自身が読む順で、`unblock-prs` などほかのコマンドと同じアカウントになるように揃えています）。コンテナや
+runner には前2つが既にあり、`gh` で設定しただけのマシンでは3つ目が拾われるので、
+どちらでも何も書き出さずに動きます。どれも無ければその旨を言って止まります。
+
+`gh` を捨てたのは、このコマンドが一番効く場所 — クラウドのコンテナや runner —
+が `gh` の入っていない場所だからです。呼ぶ API は `gh` と同じものです。
+
+既存の PR が draft だったときに ready にする操作だけは REST に無いので、GraphQL
+の mutation を使います。
+
+**プロキシ配下でも動きます。** Node の `fetch` は `HTTPS_PROXY` を自動では見な
+いため、スクリプト側で `NODE_USE_ENV_PROXY=1` を付けています。これが無いと
+プロキシを迂回して `401 Bad credentials` になり、トークンの問題に見えます。
+
+### 途中で失敗したら、もう一度実行してください
+
+各ステップは既に済んでいればスキップされます。PR が既にあれば作らず、ラベルが
+既にあれば付け直しません。巻き戻す必要はありません。
+
+### 実行
+
+```bash
+pnpm run open-pr                                   # 既定
+pnpm run open-pr -- --dry-run                      # 何をするかだけ表示
+pnpm run open-pr -- --title 'fix: 説明' --body-file ./pr.md
+pnpm run open-pr -- --merge-after '#1901'          # 順序を宣言
+pnpm run open-pr -- --base feat/lower-layer        # その PR の上に積む
+```
+
+| オプション           |                既定 | 意味                                      |
+| :------------------- | ------------------: | :---------------------------------------- |
+| `--title <text>`     |  直前のコミット件名 | PR タイトル（英語、Conventional Commits） |
+| `--body-file <path>` | トレーラのみ / 空欄 | 本文を読むファイル                        |
+| `--base <branch>`    |  リポジトリの既定値 | 対象ブランチ（PR のブランチなら stack）   |
+| `--merge-after <n>`  |                なし | `Merge-After:` を宣言（複数回可）         |
+| `--dry-run`          |                 off | 何も触らずに手順だけ出す                  |
+
+**本文は自分で書くものです。** `skip-ci` が付いている間はローカルで走らせた
+チェックがそのブランチの唯一のチェックなので、どれを走らせたかを本文に書いて
+ください。`--merge-after` を付けると `Merge-After:` 行が本文の先頭に入ります。
+
+**閉じる issue の `Start-After:` も本文に書きます。** PR を作った後、GitHub が
+本文から読んだ closing keyword の issue を読み、その `Start-After:` が名指す
+開いた PR（開いた issue なら、それを閉じる開いた PR。GitHub の issue の依存関係
+blocked by も同じに読みます）のうち本文にまだ無いものを、
+先頭の `Merge-After:` 行に足します（`docs/issue-start-after.md`）。`unblock-prs`
+と各レポートは本文に無くても引き継ぐので、これは順序を本文にも書いておくための
+ものです。サイドバーで手でリンクした issue は見ません。
+
+### stacked PR
+
+`--base` に別の open な PR のブランチを渡すと、その PR の上に積んだ PR になり
+ます。差分はこの層の分だけになり、`unblock-prs` と各レポートは下の層がマージ
+されるまで待つものとして扱います。下の層の番号は `Merge-After:` として本文の
+先頭にも自動で入ります（ `--merge-after` を併用すれば同じ行にまとめます）。
+ツールは base だけでも stack を読むので、これは順序を本文にも書いておくための
+ものです。
+
+- その base を head とする open な PR がこのリポジトリにちょうど1本あること、
+  そして現在のブランチが `origin/<base>` の先端を含んでいることを、push の前に
+  確かめます。どちらかが違えば何もせずに止まります。
+- auto-merge はほかの PR と同じく張りません。`unblock-prs` は下の層がマージされ
+  て GitHub がこの PR を既定ブランチに付け替えるまで pick しないので、張られる
+  のもそのときです。
+- **GitHub のネイティブ stack にはしないでください。** stack は base だけで
+  作ります。GitHub はネイティブ stack に入った PR に auto-merge を張らせず、
+  下の層がマージされて既定ブランチに付け替えられた後も stack から外さないので、
+  `unblock-prs` はその PR を pick せず、手でマージするよう報告します。
+
+### 拒否すること
+
+- 既定ブランチの上にいるとき（先にブランチを切ってください）
+- detached HEAD のとき
+- 認証情報がどこからも取れないとき
+- `--base` が open な PR のブランチでない、または現在のブランチがその先端を
+  含まないとき
+
+既存の PR が draft だった場合は ready にします。`unblock-prs` は draft を pick
+しないからです。
+
+### この後
+
+レビューが終わったら **`merge-queued` を付けるだけ**です。順番が来ると
+`unblock-prs` が rebase して auto-merge を張り、`skip-ci` を外し、緑になった
+時点で GitHub がマージします。**auto-merge を手で張らないでください** — それが
+未レビューのままマージさせる操作です。
+
+## English
+
+`pnpm run open-pr` pushes the current branch, creates the pull request ready
+for review, and adds `skip-ci` and `auto-rebase`. It merges nothing, never
+adds `merge-queued`, which is a person's statement that the pull request has
+been reviewed, and **never arms auto-merge**.
+
+**Why it arms nothing.** The `main` ruleset asks for
+`required_approving_review_count: 0`, so outside the paths `.github/CODEOWNERS`
+lists an armed pull request merges the moment it goes green, reviewed or not.
+A stacked one (below) is worse off: its base is a branch no ruleset covers, so
+armed it could merge into the layer below at once. So **`unblock-prs` arms a
+pull request when it picks it**, which it does only once it is labelled
+`merge-queued` and onto the default branch: queueing is the signal that it may
+merge, and nothing is armed before it. `skip-ci` holds the checks, and with
+`no-skip-ci-label` the merge, until then.
+
+**Why it adds `auto-rebase`.** The label asks `unblock-prs` to keep the pull
+request on `main` while it waits for review or its turn
+(`../unblock-prs/README.md`). It goes on every layer of a stack
+too: `unblock-prs` rebases only a pull request based on `main`, so on a layer
+above it does nothing until the layer below merges and GitHub moves this one
+onto `main` — the moment it is needed, and one at which nothing would add it.
+It goes on after `skip-ci`, so that the run its `labeled` event starts finds
+the checks held.
+
+It calls the GitHub API directly; `gh` is not required. The token is looked
+for in **`GH_TOKEN`, then `GITHUB_TOKEN`, then `gh auth token`** — the order
+`gh` itself reads the first two in, so that this acts as the account
+`unblock-prs` does — the first
+two are already set in a container or on a runner, and the third picks up a
+machine set up with `gh` alone, so neither kind of machine has to export
+anything. `gh` was dropped because the places this command is most useful are
+the places `gh` is least likely to be installed; the API it calls is the same
+one `gh` calls. Taking an existing pull request out of draft has no REST
+equivalent and goes through GraphQL.
+
+It works behind a proxy: Node's `fetch` does not read `HTTPS_PROXY` on its
+own, so the script sets `NODE_USE_ENV_PROXY=1`. Without that it bypasses the
+proxy and fails with `401 Bad credentials`, which reads like a token problem
+and is not one.
+
+Every step is skipped when it is already done, so a run that failed part way
+through is finished by running it again rather than unpicked.
+
+```bash
+pnpm run open-pr                                   # the default
+pnpm run open-pr -- --dry-run                      # say what would be done
+pnpm run open-pr -- --title 'fix: a thing' --body-file ./pr.md
+pnpm run open-pr -- --merge-after '#1901'          # declare an order
+pnpm run open-pr -- --base feat/lower-layer        # stack it on that one
+```
+
+| option               |                default | meaning                                   |
+| :------------------- | ---------------------: | :---------------------------------------- |
+| `--title <text>`     |    last commit subject | the title, in English                     |
+| `--body-file <path>` |  the trailer, or empty | where to read the body from               |
+| `--base <branch>`    | the repository default | what to target; a pull request's stacks   |
+| `--merge-after <n>`  |                   none | declare a predecessor; repeat for several |
+| `--dry-run`          |                    off | print the steps and touch nothing         |
+
+The description is yours to write: while `skip-ci` is on, the checks you ran
+locally are the only checks the branch gets, so say which ones. `--merge-after`
+puts the `Merge-After:` line at the top of the body, where `unblock-prs` reads
+it.
+
+**What the issues it closes start after is written too.** Once the pull
+request exists, the script reads the issues GitHub found closing keywords for
+in the body, and adds to the `Merge-After:` line at the top the open pull
+requests their `Start-After:` names — or, for an open issue named, the open
+pull requests closing it; GitHub's "blocked by" counts the same — that the
+body does not name yet
+(`docs/issue-start-after.md`). `unblock-prs` and the reports inherit the same
+without it; this is the body stating the order. An issue linked by hand in
+the sidebar is not seen.
+
+A `--base` that is another open pull request's branch stacks this one on it:
+the diff is its own layer, and `unblock-prs` and the reports treat it as
+waiting for the layer below. That layer is also written into the
+`Merge-After:` line at the top of the body, first, alongside anything given
+with `--merge-after`: the tools read the stack from the base alone, and the
+trailer states the order in the body as every other declared order is. Before
+pushing, the script checks that exactly one open pull request here is from
+that branch and that the current branch contains the tip of `origin/<base>`,
+and stops otherwise. `unblock-prs` does not pick it, and so does not arm it,
+until the layer below has merged and GitHub has moved it onto the default
+branch.
+
+**Do not make it one of GitHub's native stacks**; the base alone is the
+stack. GitHub refuses auto-merge on a pull request in a native stack, and
+keeps it in the stack after the layer below has merged and it has been moved
+onto the default branch, so `unblock-prs` does not pick it and reports it to
+be merged by hand.
+
+It refuses to run on the default branch, on a detached HEAD, and without a
+credential. An existing pull request that is a draft is marked ready, because
+`unblock-prs` does not pick a draft.
+
+Afterwards, queueing it is one action: add `merge-queued` once it has been
+reviewed. When its turn comes `unblock-prs` rebases it, arms auto-merge, takes
+`skip-ci` off, and GitHub merges it once the checks are green. Arming it by
+hand is the action that merges unreviewed work.