dw-sdlc 0.6.0 → 0.9.0

package/dist/pr/decide.js

@@ -0,0 +1,250 @@
+// The decision of the Ship script: one ordered list of rows, and the first row whose `when` holds for
+// the pull request answers its Action at the time given; every later row that holds rides in its
+// blockers. The last rows say who merges what no row before them holds back.
+/** How long a head may carry no check before it parks as unverified, from its commit. */
+const GRACE_SECONDS = 120;
+/** How long CI may stay pending before it parks as stuck, from the first start among the pending checks. */
+const BUDGET_MINUTES = 40;
+/** The prefix of the contexts the script posts itself, as `dw-sdlc/review`: never CI. */
+const OWN_PREFIX = "dw-sdlc/";
+/** The commit status a clean review of the head leaves on it. */
+export const REVIEW = "dw-sdlc/review";
+/** Its one state: a failure or a pending status would turn the pull request unstable. */
+export const REVIEW_STATE = "success";
+/** The words as one POSIX shell command line, each word that needs it single-quoted. */
+export function shellLine(words) {
+    return words.map((word) => (/^[\w./:=@%+,-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`)).join(" ");
+}
+function ciOf(pr) {
+    return pr.checks.filter((check) => !check.name.startsWith(OWN_PREFIX));
+}
+function pendingOf(pr) {
+    return ciOf(pr).filter((check) => check.bucket === "pending");
+}
+function failingOf(pr) {
+    return ciOf(pr).filter((check) => check.bucket === "fail");
+}
+/** A failing check as the agent reads it: its link, and the command that prints a GitHub Actions job's log. */
+function failure({ name, link, log }) {
+    return { name, link, ...(log === null ? {} : { log: shellLine(log) }) };
+}
+/** The unresolved threads whose last comment is the viewer's, or with `false` someone else's. */
+function threads(pr, lastByViewer) {
+    return pr.unresolvedThreads.filter((thread) => thread.lastByViewer === lastByViewer);
+}
+function listed({ id, path, line, author, body }) {
+    return { id, path, line, author, body };
+}
+/**
+ * The gh arguments that post the `dw-sdlc/review` success on the head, `description` saying how it was
+ * read. The path names the repository, so the call reads the same from any checkout.
+ */
+export function reviewStatusArgs(pr, description) {
+    const fields = { state: REVIEW_STATE, context: REVIEW, target_url: pr.url, description };
+    const flags = Object.entries(fields).flatMap(([key, value]) => ["-f", `${key}=${value}`]);
+    return ["api", `repos/${pr.repo}/statuses/${pr.head}`, "--method", "POST", "--silent", ...flags];
+}
+/** Why a head no one reads carries the success: the dev's word or the config. */
+function offDescription(policy) {
+    return `off: ${policy.review.source === "flag" ? "--review off" : "pr.review"}`;
+}
+/** A script Action's gh arguments; `repo` is `-R` and the repository when the call names it, else empty. */
+const HOST = {
+    "update-branch": (pr, repo) => ["pr", "update-branch", String(pr.number), ...repo],
+    "mark-ready": (pr, repo) => ["pr", "ready", String(pr.number), ...repo],
+    "mark-reviewed": (pr, _, policy) => reviewStatusArgs(pr, offDescription(policy)),
+    merge: (pr, repo) => ["pr", "merge", String(pr.number), ...repo, "--squash", "--match-head-commit", pr.head]
+};
+export function isScriptAction(action) {
+    return Object.hasOwn(HOST, action);
+}
+/**
+ * The gh arguments of a script Action, `-R` naming the repository when `named`. The update merges the
+ * base in, never --rebase, which rewrites the branch on GitHub; the merge names the head it read.
+ */
+export function hostArgs(pr, action, policy, named) {
+    return HOST[action](pr, named ? ["-R", pr.repo] : [], policy);
+}
+/** The command a script Action leaves the dev to run, from a checkout of the repository. */
+export function devCommand(pr, action, policy) {
+    return shellLine(["gh", ...hostArgs(pr, action, policy, false)]);
+}
+/** The merge left to the dev, `reason` saying why it is theirs. */
+export function readyToMerge(pr, policy, reason) {
+    return { status: "park", action: "ready-to-merge", actor: "dev", reason, command: devCommand(pr, "merge", policy) };
+}
+const ROWS = [
+    {
+        when: (pr) => pr.state === "MERGED",
+        answer: (pr) => ({
+            status: "done",
+            action: "done",
+            actor: "dev",
+            reason: pr.mergeCommit === null ? "merged" : `merged as ${pr.mergeCommit.slice(0, 7)}`,
+            command: shellLine(["git", "push", "origin", "--delete", pr.branch]),
+            ...(pr.mergeCommit === null ? {} : { details: { mergeCommit: pr.mergeCommit } })
+        }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.state === "CLOSED",
+        answer: () => ({ status: "park", action: "stop", actor: "dev", reason: "closed without merging" }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.mergeable === "UNKNOWN",
+        answer: () => ({
+            status: "wait",
+            action: "wait",
+            actor: "script",
+            reason: "mergeability-unknown",
+            recheckAfter: 15
+        }),
+        alone: true
+    },
+    {
+        when: (pr) => pr.mergeable === "CONFLICTING",
+        answer: (pr) => ({
+            status: "act",
+            action: "fix-conflicts",
+            actor: "agent",
+            reason: `conflicts with ${pr.base}`,
+            details: { base: pr.base }
+        })
+    },
+    {
+        when: (pr) => pr.mergeStateStatus === "BEHIND",
+        answer: (pr) => ({ status: "act", action: "update-branch", actor: "script", reason: `behind ${pr.base}` })
+    },
+    {
+        when: (pr) => failingOf(pr).length > 0,
+        answer: (pr) => ({
+            status: "act",
+            action: "fix-ci",
+            actor: "agent",
+            reason: `${failingOf(pr).length} check(s) failing`,
+            details: { checks: failingOf(pr).map(failure) }
+        })
+    },
+    {
+        when: (pr) => threads(pr, false).length > 0,
+        answer: (pr) => ({
+            status: "act",
+            action: "address-review",
+            actor: "agent",
+            reason: `${threads(pr, false).length} unresolved thread(s)`,
+            details: { threads: threads(pr, false).map(listed) }
+        })
+    },
+    {
+        when: (pr) => pr.reviewDecision === "CHANGES_REQUESTED",
+        answer: () => ({ status: "act", action: "address-review", actor: "agent", reason: "changes requested" })
+    },
+    {
+        // The dev merges another author's pull request, so it needs no Review. Under off no one reads
+        // the head: the script posts the success itself.
+        when: (pr) => pr.viewerDidAuthor && !pr.checks.some((check) => check.name === REVIEW && check.bucket === "pass"),
+        answer: (pr, _, { review, reviewCommand }) => {
+            const off = review.depth === "off";
+            return {
+                status: "act",
+                action: off ? "mark-reviewed" : "review",
+                actor: off ? "script" : "agent",
+                reason: `no ${REVIEW} success on ${pr.head.slice(0, 7)}`,
+                details: { ...review, ...(review.depth === "full" ? { reviewCommand } : {}) }
+            };
+        }
+    },
+    {
+        when: (pr) => ciOf(pr).length === 0,
+        answer: (pr, now, policy) => now - Date.parse(pr.headCommittedAt) <= GRACE_SECONDS * 1000
+            ? { status: "wait", action: "wait", actor: "script", reason: "unverified", recheckAfter: 15 }
+            : {
+                status: "park",
+                action: "unverified",
+                actor: "dev",
+                reason: `no check reported on ${pr.head.slice(0, 7)} within ${GRACE_SECONDS} s of its commit`,
+                command: devCommand(pr, "merge", policy)
+            }
+    },
+    {
+        when: (pr) => pendingOf(pr).length > 0,
+        answer: (pr, now) => {
+            const pending = pendingOf(pr);
+            // A check queued and not yet started counts from the head's commit.
+            const start = Math.min(...pending.map((check) => Date.parse(check.startedAt ?? pr.headCommittedAt)));
+            const minutes = Math.floor((now - start) / 60_000);
+            return now - start <= BUDGET_MINUTES * 60_000
+                ? { status: "wait", action: "wait", actor: "script", reason: "ci-pending", recheckAfter: 60 }
+                : {
+                    status: "park",
+                    action: "ci-stuck",
+                    actor: "dev",
+                    reason: `${pending.length} check(s) pending for ${minutes} min, past the ${BUDGET_MINUTES} min budget`
+                };
+        }
+    },
+    {
+        when: (pr) => threads(pr, true).length > 0,
+        answer: (pr) => ({
+            status: "park",
+            action: "awaiting-reply",
+            actor: "dev",
+            reason: `${threads(pr, true).length} thread(s) await a reply`,
+            details: { threads: threads(pr, true).map(listed) }
+        })
+    },
+    {
+        when: (pr) => pr.draft && pr.viewerDidAuthor,
+        answer: () => ({ status: "act", action: "mark-ready", actor: "script", reason: "still a draft" })
+    },
+    {
+        when: (pr) => pr.draft && !pr.viewerDidAuthor,
+        answer: () => ({
+            status: "park",
+            action: "awaiting-author",
+            actor: "dev",
+            reason: "another author's draft: marking it ready is the author's"
+        })
+    },
+    {
+        when: (pr) => pr.reviewDecision === "REVIEW_REQUIRED",
+        answer: () => ({
+            status: "park",
+            action: "awaiting-approval",
+            actor: "dev",
+            reason: "an approving review is required"
+        })
+    },
+    {
+        when: (pr) => !pr.viewerDidAuthor,
+        answer: (pr, _, policy) => readyToMerge(pr, policy, "another author's pull request: the merge is the dev's"),
+        merging: true
+    },
+    {
+        when: (_, { merge }) => merge === "auto",
+        answer: () => ({ status: "act", action: "merge", actor: "script", reason: "green, reviewed and the viewer's own" }),
+        merging: true
+    },
+    {
+        when: (_, { merge }) => merge === "ask",
+        answer: (pr, _, policy) => readyToMerge(pr, policy, "pr.merge is ask: the merge is the dev's"),
+        merging: true
+    }
+];
+function blockerOf({ action, actor, reason, details }) {
+    return { action, actor, reason, ...(details === undefined ? {} : { details }) };
+}
+/** The Action `pr` needs at `now`, milliseconds since the epoch, under `policy`. */
+export function decide(pr, now, policy) {
+    const index = ROWS.findIndex((row) => row.when(pr, policy));
+    const row = ROWS[index];
+    if (row === undefined) {
+        throw new Error(`no row of the decision matches ${pr.url} under pr.merge ${policy.merge}`);
+    }
+    const later = row.alone === true ? [] : ROWS.slice(index + 1).filter((other) => !other.merging && other.when(pr, policy));
+    return {
+        ...row.answer(pr, now, policy),
+        blockers: later.map((other) => blockerOf(other.answer(pr, now, policy)))
+    };
+}

package/dist/pr/read.d.ts

@@ -0,0 +1,24 @@
+import { type PrState } from "./state.ts";
+/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+export declare class CannotRun extends Error {
+    remedy: string;
+    constructor(message: string, remedy: string);
+}
+/** The pull request a command line names; what it leaves out, `gh pr view` resolves. */
+export type Named = {
+    number: number | undefined;
+    repo: string | undefined;
+};
+/** The problem with `<n>` or `-R` as given on a command line, if there is one. */
+export declare function namedProblem(number: string | undefined, repo: string | undefined): string | undefined;
+/** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
+export declare function said(stderr: string): string;
+export declare function gh(args: string[]): {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
+export declare function read(named: Named, command: string): PrState;
+/** The state of `pr` once more, after an action the script performed on it: the same pull request. */
+export declare function readAgain(pr: PrState): PrState;

package/dist/pr/read.js

@@ -0,0 +1,112 @@
+// The read both pr commands make: gh as a child process, its auth on the host gh api reads from, the
+// pull request a command names, and that pull request's state from one GraphQL request.
+import { spawnSync } from "node:child_process";
+import { parsePr, parseView, QUERY, ReplyError } from "./state.js";
+/** What stops a pr command before it answers: exit 2, the problem and its remedy on one line. */
+export class CannotRun extends Error {
+    remedy;
+    constructor(message, remedy) {
+        super(message);
+        this.remedy = remedy;
+    }
+}
+const REMEDIES = {
+    missing: "install the GitHub CLI from https://cli.github.com",
+    auth: "run gh auth login, or set GH_TOKEN",
+    target: "check the number, or name the repository with -R owner/name",
+    read: "check gh auth status and the network, then call again",
+    reply: "gh answered a shape dw-sdlc does not read; report it with the output of gh --version"
+};
+/** The problem with `<n>` or `-R` as given on a command line, if there is one. */
+export function namedProblem(number, repo) {
+    if (number !== undefined && !/^[1-9]\d*$/.test(number)) {
+        return `${JSON.stringify(number)} is not a pull request number`;
+    }
+    if (repo !== undefined && !/^[\w.-]+\/[\w.-]+$/.test(repo)) {
+        return `-R takes owner/name, not ${JSON.stringify(repo)}`;
+    }
+    return undefined;
+}
+function firstLine(text) {
+    return text.trim().split("\n")[0] ?? "";
+}
+/** What gh said went wrong: the first line of its stderr, without its `gh: ` prefix or its `X` icon. */
+export function said(stderr) {
+    return firstLine(stderr).replace(/^(?:gh: |X )/, "");
+}
+/** The problem `gh auth status` reports: its line marked `X` under the host, else its first line. */
+function authProblem(stderr) {
+    const marked = stderr.split("\n").find((line) => line.trimStart().startsWith("X "));
+    return marked === undefined ? firstLine(stderr) : marked.trim().slice(2);
+}
+export function gh(args) {
+    const result = spawnSync("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (result.error !== undefined) {
+        if ("code" in result.error && result.error.code === "ENOENT") {
+            throw new CannotRun("gh is not on PATH", REMEDIES.missing);
+        }
+        throw result.error;
+    }
+    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+}
+/** What `parse` returns; a reply it cannot parse stops the command, naming the field. */
+function parseOrCannotRun(parse) {
+    try {
+        return parse();
+    }
+    catch (error) {
+        if (error instanceof ReplyError) {
+            throw new CannotRun(`the reply does not parse: ${error.message}`, REMEDIES.reply);
+        }
+        throw error;
+    }
+}
+/** The pull request named in full, or the one `gh pr view` resolves from what is given. */
+function targetOf({ number, repo }, command) {
+    if (number !== undefined && repo !== undefined) {
+        return { repo, number };
+    }
+    const named = [...(number === undefined ? [] : [String(number)]), ...(repo === undefined ? [] : ["-R", repo])];
+    const view = gh(["pr", "view", ...named, "--json", "url"]);
+    if (view.status !== 0) {
+        const remedy = `name it: dw-sdlc ${command} <n> -R owner/name`;
+        throw new CannotRun(`gh pr view found no pull request: ${firstLine(view.stderr)}`, remedy);
+    }
+    return parseOrCannotRun(() => parseView(view.stdout));
+}
+/** The state of the pull request `named`; `command`, as `pr ship`, names the call in a remedy. */
+export function read(named, command) {
+    // The host gh api reads from: an account on any other host has no say in this call.
+    const host = process.env.GH_HOST?.trim() || "github.com";
+    const auth = gh(["auth", "status", "--active", "--hostname", host]);
+    if (auth.status !== 0) {
+        throw new CannotRun(`gh auth status failed: ${authProblem(auth.stderr)}`, REMEDIES.auth);
+    }
+    return query(targetOf(named, command));
+}
+/** The state of `pr` once more, after an action the script performed on it: the same pull request. */
+export function readAgain(pr) {
+    return query(pr);
+}
+/** The state of pull request `number` of `repo`, from one GraphQL request. */
+function query({ repo, number }) {
+    const [owner = "", name = ""] = repo.split("/");
+    const reply = gh([
+        "api",
+        "graphql",
+        "-f",
+        `query=${QUERY}`,
+        "-f",
+        `owner=${owner}`,
+        "-f",
+        `name=${name}`,
+        "-F",
+        `number=${number}`
+    ]);
+    if (reply.status !== 0) {
+        const problem = said(reply.stderr);
+        const remedy = problem.startsWith("Could not resolve to a") ? REMEDIES.target : REMEDIES.read;
+        throw new CannotRun(`${repo}#${number}: ${problem}`, remedy);
+    }
+    return parseOrCannotRun(() => parsePr(reply.stdout, repo));
+}

package/dist/pr/state.d.ts

@@ -0,0 +1,54 @@
+export declare const QUERY = "query($owner: String!, $name: String!, $number: Int!) {\n  repository(owner: $owner, name: $name) {\n    pullRequest(number: $number) {\n      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName\n      viewerDidAuthor mergeCommit { oid }\n      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line\n        comments(first: 1) { nodes { author { login } body } }\n        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }\n      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {\n        contexts(first: 50) { nodes {\n          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }\n          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }\n    }\n  }\n}";
+export type Bucket = "pass" | "fail" | "pending" | "skipping";
+export type CiCheck = {
+    name: string;
+    bucket: Bucket;
+    required: boolean;
+    link: string | null;
+    /** The command that prints a failed GitHub Actions job's log; null for any other CI. */
+    log: string[] | null;
+    startedAt: string | null;
+};
+export type Thread = {
+    id: string;
+    path: string;
+    line: number | null;
+    author: string;
+    body: string;
+    /** Whether the viewer, the account gh reads as, wrote the thread's last comment. */
+    lastByViewer: boolean;
+};
+declare const STATES: readonly ["OPEN", "CLOSED", "MERGED"];
+declare const MERGEABLE: readonly ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
+declare const REVIEW_DECISIONS: readonly ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+export type PrState = {
+    url: string;
+    repo: string;
+    number: number;
+    state: (typeof STATES)[number];
+    draft: boolean;
+    mergeable: (typeof MERGEABLE)[number];
+    /** BEHIND, BLOCKED, CLEAN, DIRTY, HAS_HOOKS, UNKNOWN or UNSTABLE, as GitHub reports it. */
+    mergeStateStatus: string;
+    reviewDecision: (typeof REVIEW_DECISIONS)[number] | null;
+    viewerDidAuthor: boolean;
+    head: string;
+    headCommittedAt: string;
+    branch: string;
+    base: string;
+    mergeCommit: string | null;
+    checks: CiCheck[];
+    /** The threads neither resolved nor outdated. */
+    unresolvedThreads: Thread[];
+};
+/** A reply that is not the shape the query asks for; the message names the field. */
+export declare class ReplyError extends Error {
+}
+/** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
+export declare function parseView(reply: string): {
+    repo: string;
+    number: number;
+};
+/** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
+export declare function parsePr(reply: string, repo: string): PrState;
+export {};

package/dist/pr/state.js

@@ -0,0 +1,220 @@
+// One pull request as the Ship script reads it: the one GraphQL query, and its reply parsed into the
+// state the decision reads. Every field the state needs is checked; a reply that fails names the field.
+export const QUERY = `query($owner: String!, $name: String!, $number: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      url number state isDraft mergeable mergeStateStatus reviewDecision headRefOid headRefName baseRefName
+      viewerDidAuthor mergeCommit { oid }
+      reviewThreads(first: 100) { nodes { id isResolved isOutdated path line
+        comments(first: 1) { nodes { author { login } body } }
+        latest: comments(last: 1) { nodes { viewerDidAuthor } } } }
+      commits(last: 1) { nodes { commit { committedDate statusCheckRollup {
+        contexts(first: 50) { nodes {
+          ... on CheckRun { name status conclusion detailsUrl startedAt isRequired(pullRequestNumber: $number) }
+          ... on StatusContext { context state targetUrl createdAt isRequired(pullRequestNumber: $number) } } } } } } }
+    }
+  }
+}`;
+const STATES = ["OPEN", "CLOSED", "MERGED"];
+const MERGEABLE = ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
+const REVIEW_DECISIONS = ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"];
+/** A reply that is not the shape the query asks for; the message names the field. */
+export class ReplyError extends Error {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function shown(value) {
+    return value === undefined ? "missing" : JSON.stringify(value);
+}
+/** The JSON object `reply` holds, the root its fields' paths start from; `what` names it in a problem. */
+function rootOf(reply, what) {
+    let json;
+    try {
+        json = JSON.parse(reply);
+    }
+    catch {
+        throw new ReplyError(`${what} is not JSON`);
+    }
+    if (!isRecord(json)) {
+        throw new ReplyError(`${what} is not a JSON object`);
+    }
+    return { value: json, at: "" };
+}
+function fieldOf(node, key) {
+    return { value: node.value[key], at: node.at === "" ? key : `${node.at}.${key}` };
+}
+function object(value, at) {
+    if (!isRecord(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an object`);
+    }
+    return { value, at };
+}
+function child(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return object(value, at);
+}
+function childOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    return value === null ? null : object(value, at);
+}
+function string(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "string") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a string`);
+    }
+    return value;
+}
+function stringOrNull(node, key) {
+    return node.value[key] === null ? null : string(node, key);
+}
+function boolean(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "boolean") {
+        throw new ReplyError(`${at} is ${shown(value)}, not a boolean`);
+    }
+    return value;
+}
+function integer(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an integer`);
+    }
+    return value;
+}
+function integerOrNull(node, key) {
+    const { value, at } = fieldOf(node, key);
+    if (value !== null && !Number.isInteger(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not an integer or null`);
+    }
+    return typeof value === "number" ? value : null;
+}
+/** A time as GitHub writes it, ISO 8601; the decision reads it as one. */
+function time(node, key) {
+    const value = string(node, key);
+    if (Number.isNaN(Date.parse(value))) {
+        throw new ReplyError(`${fieldOf(node, key).at} is ${shown(value)}, not a time`);
+    }
+    return value;
+}
+function timeOrNull(node, key) {
+    return node.value[key] === null ? null : time(node, key);
+}
+function isOneOf(values, value) {
+    return values.some((known) => known === value);
+}
+function oneOf(node, key, values) {
+    const { value, at } = fieldOf(node, key);
+    if (!isOneOf(values, value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not one of ${values.join(", ")}`);
+    }
+    return value;
+}
+/** The objects of a connection's `nodes`. */
+function nodes(node, key) {
+    const { value, at } = fieldOf(child(node, key), "nodes");
+    if (!Array.isArray(value)) {
+        throw new ReplyError(`${at} is ${shown(value)}, not a list`);
+    }
+    return value.map((item, index) => object(item, `${at}[${index}]`));
+}
+/** The first object of a connection's `nodes`; an empty connection does not parse. */
+function firstNode(node, key) {
+    const [first] = nodes(node, key);
+    if (first === undefined) {
+        throw new ReplyError(`${node.at}.${key}.nodes is empty`);
+    }
+    return first;
+}
+const FAIL = new Set(["ERROR", "FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "CANCELLED", "STARTUP_FAILURE"]);
+const SKIPPING = new Set(["SKIPPED", "NEUTRAL"]);
+/** A check's bucket as `gh pr checks` sorts it: every word not passed, failed or skipped is pending. */
+function bucketOf(word) {
+    if (word === "SUCCESS") {
+        return "pass";
+    }
+    if (word !== null && FAIL.has(word)) {
+        return "fail";
+    }
+    return word !== null && SKIPPING.has(word) ? "skipping" : "pending";
+}
+function logCommand(link, repo) {
+    const job = link?.match(/\/actions\/runs\/\d+\/job\/(\d+)/)?.[1];
+    return job === undefined ? null : ["gh", "run", "view", "--job", job, "-R", repo, "--log-failed"];
+}
+/** A CheckRun has a name and a status; a StatusContext has a context and a state. */
+function checkOf(context, repo) {
+    if ("name" in context.value) {
+        const status = string(context, "status");
+        const link = stringOrNull(context, "detailsUrl");
+        return {
+            name: string(context, "name"),
+            bucket: bucketOf(status === "COMPLETED" ? stringOrNull(context, "conclusion") : status),
+            required: boolean(context, "isRequired"),
+            link,
+            log: logCommand(link, repo),
+            startedAt: timeOrNull(context, "startedAt")
+        };
+    }
+    if ("context" in context.value) {
+        const link = stringOrNull(context, "targetUrl");
+        return {
+            name: string(context, "context"),
+            bucket: bucketOf(string(context, "state")),
+            required: boolean(context, "isRequired"),
+            link,
+            log: logCommand(link, repo),
+            startedAt: time(context, "createdAt")
+        };
+    }
+    throw new ReplyError(`${context.at} is neither a CheckRun nor a StatusContext`);
+}
+/** A thread by its opening comment; a deleted account's comment has no author and reads as GitHub's ghost. */
+function threadOf(thread) {
+    const first = firstNode(thread, "comments");
+    const author = childOrNull(first, "author");
+    return {
+        id: string(thread, "id"),
+        path: string(thread, "path"),
+        line: integerOrNull(thread, "line"),
+        author: author === null ? "ghost" : string(author, "login"),
+        body: string(first, "body"),
+        lastByViewer: boolean(firstNode(thread, "latest"), "viewerDidAuthor")
+    };
+}
+/** The repository and number of the pull request whose URL `gh pr view --json url` printed. */
+export function parseView(reply) {
+    const url = string(rootOf(reply, "the reply of gh pr view"), "url");
+    const [, repo, number] = /^https:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\/(\d+)$/.exec(url) ?? [];
+    if (repo === undefined || number === undefined) {
+        throw new ReplyError(`url is ${JSON.stringify(url)}, not a pull request's URL`);
+    }
+    return { repo, number: Number(number) };
+}
+/** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
+export function parsePr(reply, repo) {
+    const pr = child(child(child(rootOf(reply, "the reply"), "data"), "repository"), "pullRequest");
+    const commit = child(firstNode(pr, "commits"), "commit");
+    const rollup = childOrNull(commit, "statusCheckRollup");
+    const mergeCommit = childOrNull(pr, "mergeCommit");
+    return {
+        url: string(pr, "url"),
+        repo,
+        number: integer(pr, "number"),
+        state: oneOf(pr, "state", STATES),
+        draft: boolean(pr, "isDraft"),
+        mergeable: oneOf(pr, "mergeable", MERGEABLE),
+        mergeStateStatus: string(pr, "mergeStateStatus"),
+        reviewDecision: pr.value.reviewDecision === null ? null : oneOf(pr, "reviewDecision", REVIEW_DECISIONS),
+        viewerDidAuthor: boolean(pr, "viewerDidAuthor"),
+        head: string(pr, "headRefOid"),
+        headCommittedAt: time(commit, "committedDate"),
+        branch: string(pr, "headRefName"),
+        base: string(pr, "baseRefName"),
+        mergeCommit: mergeCommit === null ? null : string(mergeCommit, "oid"),
+        checks: rollup === null ? [] : nodes(rollup, "contexts").map((context) => checkOf(context, repo)),
+        unresolvedThreads: nodes(pr, "reviewThreads")
+            .filter((thread) => !boolean(thread, "isResolved") && !boolean(thread, "isOutdated"))
+            .map(threadOf)
+    };
+}

package/dist/router-block.d.ts

@@ -1,5 +1,8 @@
 import type { Reference } from "./references-key.ts";
-/** The block the file gives: one row per Reference in the file's order, or one line when it has none. */
+/**
+ * The block the file gives: one row per Reference in the file's order, or one line when it has none,
+ * with a blank line inside each marker and each `when` trimmed, as oxfmt leaves it.
+ */
 export declare function renderBlock(references: Reference[]): string;
 /**
  * The Router's text with `block` in place of the one between its markers: as it is when the two say