pr-shepherd 0.56.5 → 0.57.0

package/bin/github/rest-http.mjs

@@ -3,11 +3,13 @@ import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { loadEtagEntry, storeEtagEntry } from "../state/rest-cache.mjs";
 import { GitHubRequestError } from "./errors.mjs";
+import { githubFetch } from "./github-fetch.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
 import { recordApiTelemetry } from "./api-telemetry.mjs";
 import { recordIntermediateResponse } from "./http-intermediate.mjs";
+import { isRestSessionRefusalResponse } from "./rest-session-refusal.mjs";
 const BASE_URL = "https://api.github.com";
 const SAFE_GITHUB_REST_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*$/;
 function githubApiUrl(path) {
@@ -34,13 +36,15 @@ export async function restWithRateLimit(method, path, body, opts) {
     appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
     const t0 = performance.now();
     let authSource = "unknown";
-    const cached = opts?.conditional
+    let credentialFingerprint;
+    const cached = opts?.conditional && !opts.conditional.revalidate
         ? await loadEtagEntry(opts.conditional.key, opts.conditional.name)
         : null;
     const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
         const auth = await makeAuthHeaders(cached ? { "If-None-Match": cached.etag } : undefined);
         authSource = auth.source;
-        return fetch(url, {
+        credentialFingerprint = auth.fingerprint;
+        return githubFetch(url, {
             method,
             headers: auth.headers,
             body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -53,7 +57,8 @@ export async function restWithRateLimit(method, path, body, opts) {
         response,
         durationMs,
         authSource,
-    }));
+        credentialFingerprint,
+    }), method === "GET" || method === "HEAD");
     const durationMs = Math.round(performance.now() - retryT0);
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
     const retryAfterSeconds = parseRetryAfter(res.headers);
@@ -73,11 +78,25 @@ export async function restWithRateLimit(method, path, body, opts) {
             rateLimit,
             retryAfterSeconds,
         }));
-        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
-        return { data: cached.body, rateLimit };
+        // A 304 consumes no quota: telemetry counts it as notModified, not as a request.
+        recordApiTelemetry({
+            kind: "REST",
+            method,
+            authSource,
+            credentialFingerprint,
+            rateLimit,
+            notModified: true,
+        });
+        return {
+            data: cached.body,
+            rateLimit,
+            status: res.status,
+            etag: cached.etag,
+            link: res.headers.get("link") ?? cached.link,
+        };
     }
     const ct = res.headers.get("content-type") ?? "";
-    if (!res.ok) {
+    if (!res.ok && !opts?.acceptStatuses?.includes(res.status)) {
         const text = await res.text();
         appendEntry(formatResponseEntry({
             n,
@@ -92,17 +111,63 @@ export async function restWithRateLimit(method, path, body, opts) {
             rateLimit,
             retryAfterSeconds,
         }));
-        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
-        throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+        recordApiTelemetry({
+            kind: "REST",
+            method,
+            authSource,
+            credentialFingerprint,
+            rateLimit,
+        });
+        const responseMessage = isRestSessionRefusalResponse(res.status, text)
+            ? redactToken(text)
+            : sanitizeBody(text);
+        throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${responseMessage}`, {
             status: res.status,
             rateLimit,
             retryAfterSeconds,
             authSource,
-            responseMessage: sanitizeBody(text),
+            responseMessage,
         });
     }
     if (ct.includes("application/json")) {
-        const json = (await res.json());
+        let json;
+        try {
+            json = (await res.json());
+        }
+        catch (err) {
+            const detail = err instanceof Error ? `: ${err.message}` : "";
+            appendEntry(formatResponseEntry({
+                n,
+                kind: "REST",
+                method,
+                url,
+                status: res.status,
+                durationMs,
+                contentType: ct,
+                textBody: `Invalid JSON response${detail}`,
+                attempt: attempt > 1 ? attempt : undefined,
+                authSource,
+                rateLimit,
+                retryAfterSeconds,
+            }));
+            recordApiTelemetry({
+                kind: "REST",
+                method,
+                authSource,
+                credentialFingerprint,
+                rateLimit,
+            });
+            if (!res.ok) {
+                throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} Invalid JSON response${detail}`, {
+                    status: res.status,
+                    rateLimit,
+                    retryAfterSeconds,
+                    authSource,
+                    responseMessage: `Invalid JSON response${detail}`,
+                });
+            }
+            throw err;
+        }
         appendEntry(formatResponseEntry({
             n,
             kind: "REST",
@@ -117,18 +182,32 @@ export async function restWithRateLimit(method, path, body, opts) {
             rateLimit,
             retryAfterSeconds,
         }));
-        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
-        if (opts?.conditional) {
-            const etag = res.headers.get("etag");
-            if (etag) {
-                await storeEtagEntry(opts.conditional.key, opts.conditional.name, {
-                    etag,
-                    body: json,
-                    ...(opts.conditional.headSha !== undefined && { headSha: opts.conditional.headSha }),
-                });
-            }
+        recordApiTelemetry({
+            kind: "REST",
+            method,
+            authSource,
+            credentialFingerprint,
+            rateLimit,
+        });
+        const etag = opts?.conditional ? (res.headers.get("etag") ?? undefined) : undefined;
+        const link = res.headers.get("link") ?? undefined;
+        if (opts?.conditional && etag && (opts.conditional.shouldStore?.(json) ?? true)) {
+            await storeEtagEntry(opts.conditional.key, opts.conditional.name, {
+                etag,
+                body: json,
+                ...(opts.conditional.headSha !== undefined && {
+                    headSha: opts.conditional.headSha,
+                }),
+                ...(link !== undefined && { link }),
+            });
         }
-        return { data: json, rateLimit };
+        return {
+            data: json,
+            rateLimit,
+            status: res.status,
+            ...(etag !== undefined && { etag }),
+            link,
+        };
     }
     appendEntry(formatResponseEntry({
         n,
@@ -143,6 +222,12 @@ export async function restWithRateLimit(method, path, body, opts) {
         rateLimit,
         retryAfterSeconds,
     }));
-    recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
-    return { data: undefined, rateLimit };
+    recordApiTelemetry({
+        kind: "REST",
+        method,
+        authSource,
+        credentialFingerprint,
+        rateLimit,
+    });
+    return { data: undefined, rateLimit, status: res.status };
 }

package/bin/github/rest-identities.d.mts

@@ -0,0 +1,22 @@
+import type { SeenMarker } from "../state/seen-comments.mts";
+import type { RepoInfo } from "./client.mts";
+import type { FixAttemptsState } from "../state/fix-attempts.mts";
+type IdentityKind = "check" | "review" | "comment" | "pull" | "thread";
+interface RestIdentity {
+    repo: RepoInfo;
+    pr: number;
+    numericId: string;
+    kind: IdentityKind;
+    graphqlThreadId?: string;
+}
+export declare function restThreadId(rootCommentId: string | number): string;
+export declare function recordRestIdentity(repo: RepoInfo, pr: number, nodeId: string, numericId: string | number, kind: IdentityKind): Promise<void>;
+export declare function resolveRestIdentity(id: string, kind?: IdentityKind): Promise<RestIdentity>;
+export declare function recordThreadIdentity(repo: RepoInfo, pr: number, graphqlThreadId: string, rootCommentId: string | number): Promise<void>;
+export declare function resolveRestThreadRoot(repo: RepoInfo, pr: number, id: string): Promise<string>;
+export declare function resolveGraphqlThreadId(id: string): Promise<string>;
+/** Preserve previously displayed feedback when the adapter changes its thread handle. */
+export declare function aliasThreadSeenMarkers(repo: RepoInfo, pr: number, ids: readonly string[], seen: Map<string, SeenMarker>): Promise<void>;
+/** Keep fix-attempt counts tied to the same feedback when its transport handle changes. */
+export declare function aliasThreadFixAttempts(repo: RepoInfo, pr: number, ids: readonly string[], state: FixAttemptsState | null): Promise<void>;
+export {};

package/bin/github/rest-identities.mjs

@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveStateBase } from "../state/base.mjs";
+function identityPath(id) {
+    const hash = createHash("sha256").update(id).digest("hex");
+    return join(resolveStateBase(), "github-identities", `${hash}.json`);
+}
+function numeric(value) {
+    const result = String(value);
+    if (!/^[1-9][0-9]*$/.test(result))
+        throw new Error(`Invalid GitHub numeric ID: ${result}`);
+    return result;
+}
+export function restThreadId(rootCommentId) {
+    return `rest-thread-${numeric(rootCommentId)}`;
+}
+async function storeIdentity(id, entry) {
+    await mkdir(join(resolveStateBase(), "github-identities"), { recursive: true });
+    await writeFile(identityPath(id), JSON.stringify({ id, ...entry }));
+}
+export async function recordRestIdentity(repo, pr, nodeId, numericId, kind) {
+    if (!nodeId)
+        return;
+    await storeIdentity(nodeId, { repo, pr, numericId: numeric(numericId), kind });
+}
+export async function resolveRestIdentity(id, kind) {
+    let entry;
+    try {
+        entry = JSON.parse(await readFile(identityPath(id), "utf8"));
+    }
+    catch {
+        throw new Error(`No recorded REST identity for ${id}; refresh this PR with REST transport first`);
+    }
+    if (entry.id !== id ||
+        !entry.repo?.owner ||
+        !entry.repo.name ||
+        !Number.isSafeInteger(entry.pr) ||
+        entry.pr < (entry.kind === "check" ? 0 : 1) ||
+        !/^[1-9][0-9]*$/.test(entry.numericId) ||
+        (kind !== undefined && entry.kind !== kind))
+        throw new Error(`Invalid REST identity for ${id}`);
+    return entry;
+}
+export async function recordThreadIdentity(repo, pr, graphqlThreadId, rootCommentId) {
+    const numericId = numeric(rootCommentId);
+    const canonical = restThreadId(numericId);
+    let existing;
+    try {
+        existing = await resolveRestIdentity(canonical, "thread");
+    }
+    catch { }
+    const genuineId = graphqlThreadId.startsWith("rest-thread-")
+        ? existing?.graphqlThreadId
+        : graphqlThreadId;
+    const entry = {
+        repo,
+        pr,
+        numericId,
+        kind: "thread",
+        ...(genuineId && { graphqlThreadId: genuineId }),
+    };
+    if (genuineId)
+        await storeIdentity(genuineId, entry);
+    await storeIdentity(canonical, entry);
+}
+function samePr(entry, repo, pr) {
+    return (entry.pr === pr &&
+        entry.repo.owner.toLowerCase() === repo.owner.toLowerCase() &&
+        entry.repo.name.toLowerCase() === repo.name.toLowerCase());
+}
+export async function resolveRestThreadRoot(repo, pr, id) {
+    const match = /^rest-thread-([1-9][0-9]*)$/.exec(id);
+    if (match)
+        return match[1];
+    const entry = await resolveRestIdentity(id, "thread");
+    if (!samePr(entry, repo, pr))
+        throw new Error(`Thread ${id} does not belong to ${repo.owner}/${repo.name}#${pr}`);
+    return entry.numericId;
+}
+export async function resolveGraphqlThreadId(id) {
+    if (!id.startsWith("rest-thread-"))
+        return id;
+    const entry = await resolveRestIdentity(id, "thread");
+    if (!entry.graphqlThreadId)
+        throw new Error(`No GraphQL thread identity for ${id}; use --transport rest`);
+    return entry.graphqlThreadId;
+}
+/** Preserve previously displayed feedback when the adapter changes its thread handle. */
+export async function aliasThreadSeenMarkers(repo, pr, ids, seen) {
+    await Promise.all(ids.map(async (id) => {
+        try {
+            const entry = await resolveRestIdentity(id, "thread");
+            if (!samePr(entry, repo, pr))
+                return;
+            const aliases = [id, restThreadId(entry.numericId), entry.graphqlThreadId].filter((alias) => alias !== undefined);
+            const marker = aliases
+                .map((alias) => seen.get(alias))
+                .find((candidate) => candidate !== undefined);
+            if (marker)
+                for (const alias of aliases)
+                    if (!seen.has(alias))
+                        seen.set(alias, marker);
+        }
+        catch {
+            // Old snapshots may have no association. Surface again rather than hide an unseen item.
+        }
+    }));
+}
+/** Keep fix-attempt counts tied to the same feedback when its transport handle changes. */
+export async function aliasThreadFixAttempts(repo, pr, ids, state) {
+    if (!state?.threadBodyHashes)
+        return;
+    await Promise.all(ids.map(async (id) => {
+        try {
+            const entry = await resolveRestIdentity(id, "thread");
+            if (!samePr(entry, repo, pr))
+                return;
+            const aliases = [id, restThreadId(entry.numericId), entry.graphqlThreadId].filter((alias) => alias !== undefined);
+            const source = aliases.find((alias) => state.threadBodyHashes?.[alias] !== undefined);
+            if (!source)
+                return;
+            const bodyHash = state.threadBodyHashes[source];
+            const attempts = Math.max(...aliases
+                .filter((alias) => state.threadBodyHashes?.[alias] === bodyHash)
+                .map((alias) => state.threadAttempts[alias] ?? 0));
+            state.threadBodyHashes[id] = bodyHash;
+            state.threadAttempts[id] = attempts;
+        }
+        catch {
+            /* Unmapped older handles retain their ordinary first-look behavior. */
+        }
+    }));
+}

package/bin/github/rest-merge-stack-guard.d.mts

@@ -0,0 +1,14 @@
+/** Native stack and exact lower prefix observed when the merge command was generated. */
+export interface RestMergeStackGuard {
+    number: number;
+    baseRefName: string;
+    prefix: Array<{
+        pr: number;
+        headRefName: string;
+        headRefOid: string;
+        baseRefName: string;
+    }>;
+}
+export declare function validateRestMergeStackGuard(value: unknown): asserts value is RestMergeStackGuard;
+/** Stable equality ignores object key order and unknown caller fields. */
+export declare function restMergeStackGuardKey(guard: RestMergeStackGuard | undefined): string;

package/bin/github/rest-merge-stack-guard.mjs

@@ -0,0 +1,41 @@
+export function validateRestMergeStackGuard(value) {
+    const guard = value;
+    if (!guard ||
+        typeof guard !== "object" ||
+        Array.isArray(guard) ||
+        !Number.isSafeInteger(guard.number) ||
+        guard.number < 1 ||
+        typeof guard.baseRefName !== "string" ||
+        !guard.baseRefName ||
+        !Array.isArray(guard.prefix) ||
+        guard.prefix.length === 0 ||
+        guard.prefix.length > 100_000 ||
+        guard.prefix.some((member) => !member ||
+            typeof member !== "object" ||
+            Array.isArray(member) ||
+            !Number.isSafeInteger(member.pr) ||
+            member.pr < 1 ||
+            typeof member.headRefName !== "string" ||
+            !member.headRefName ||
+            typeof member.baseRefName !== "string" ||
+            !member.baseRefName ||
+            typeof member.headRefOid !== "string" ||
+            !/^[0-9a-f]{40}$/.test(member.headRefOid)) ||
+        new Set(guard.prefix.map((member) => member.pr)).size !== guard.prefix.length)
+        throw new Error("expectedStack must bind a positive stack number, trunk, and unique ordered PR prefix with full head SHAs and branch refs");
+}
+/** Stable equality ignores object key order and unknown caller fields. */
+export function restMergeStackGuardKey(guard) {
+    return JSON.stringify(guard
+        ? [
+            guard.number,
+            guard.baseRefName,
+            guard.prefix.map((member) => [
+                member.pr,
+                member.headRefName,
+                member.headRefOid,
+                member.baseRefName,
+            ]),
+        ]
+        : null);
+}

package/bin/github/rest-merge.d.mts

@@ -0,0 +1,29 @@
+import type { RepoInfo } from "./client.mts";
+import type { MergeMethod } from "../config/merge-method.mts";
+import type { RestMergeStackGuard } from "./rest-merge-stack-guard.mts";
+export type { RestMergeStackGuard } from "./rest-merge-stack-guard.mts";
+export type RestMergeAction = "direct_merge" | "merge_queue" | "default";
+export interface RestMergeOptions {
+    requireSha: string;
+    mergeAction: RestMergeAction;
+    mergeMethod?: MergeMethod;
+    expectedStack?: RestMergeStackGuard;
+}
+export interface RestMergeResponse {
+    status: "pending" | "enqueued" | "merged" | "failed";
+    details: {
+        message?: string;
+        uuid?: string;
+        expected_head_sha?: string;
+        merge_action?: RestMergeAction;
+        merge_method?: MergeMethod;
+        bypass_rules?: boolean;
+        sha?: string;
+        [key: string]: unknown;
+    };
+}
+/** This named mutation is never retried after a network failure or server error. */
+export declare function requestRestMerge(repo: RepoInfo, pr: number, options: RestMergeOptions): Promise<RestMergeResponse>;
+export declare function getRestMerge(repo: RepoInfo, pr: number, uuid: string): Promise<RestMergeResponse>;
+/** Conflict requests must match the caller's guarded options before their UUID can be adopted. */
+export declare function matchesRestMergeRequest(result: RestMergeResponse, options: RestMergeOptions): boolean;

package/bin/github/rest-merge.mjs

@@ -0,0 +1,56 @@
+import { restWithRateLimit } from "./rest-http.mjs";
+import { restRepoPath } from "./rest-reader-core.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { sanitizeBody } from "./http-utils.mjs";
+function parseRestMergeResponse(raw) {
+    if (raw === null || typeof raw !== "object")
+        throw new Error("Invalid asynchronous merge response");
+    const value = raw;
+    if (!["pending", "enqueued", "merged", "failed"].includes(String(value["status"])) ||
+        value["details"] === null ||
+        typeof value["details"] !== "object" ||
+        Array.isArray(value["details"])) {
+        throw new Error("Invalid asynchronous merge response");
+    }
+    return value;
+}
+/** This named mutation is never retried after a network failure or server error. */
+export async function requestRestMerge(repo, pr, options) {
+    const { data, status, rateLimit } = await restWithRateLimit("PUT", `${restRepoPath(repo)}/pulls/${pr}/merge-async`, {
+        sha: options.requireSha,
+        merge_action: options.mergeAction,
+        bypass_rules: false,
+        ...(options.mergeAction === "direct_merge" && options.mergeMethod
+            ? { merge_method: options.mergeMethod }
+            : {}),
+    }, { acceptStatuses: [400, 409] });
+    try {
+        return parseRestMergeResponse(data);
+    }
+    catch (error) {
+        // Accepted 400/409 responses may contain an ordinary API error envelope,
+        // rather than merge state. Retain their definite refusal for intent recovery.
+        if (status !== undefined && status >= 400 && status < 500) {
+            const responseMessage = sanitizeBody(JSON.stringify(data) ?? "");
+            throw new GitHubRequestError(`Invalid asynchronous merge response: ${status} ${responseMessage}`, { status, rateLimit, responseMessage });
+        }
+        // A malformed acknowledgement may follow a successful submission.
+        throw error;
+    }
+}
+export async function getRestMerge(repo, pr, uuid) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid))
+        throw new Error("Invalid asynchronous merge UUID");
+    const { data } = await restWithRateLimit("GET", `${restRepoPath(repo)}/pulls/${pr}/merge-async/${uuid}`);
+    return parseRestMergeResponse(data);
+}
+/** Conflict requests must match the caller's guarded options before their UUID can be adopted. */
+export function matchesRestMergeRequest(result, options) {
+    const details = result.details;
+    return (details.expected_head_sha === options.requireSha &&
+        details.merge_action === options.mergeAction &&
+        details.bypass_rules === false &&
+        (options.mergeMethod === undefined || details.merge_method === options.mergeMethod) &&
+        typeof details.uuid === "string" &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(details.uuid));
+}

package/bin/github/rest-merged-base-read.d.mts

@@ -0,0 +1,9 @@
+import type { MergedBasePullRequest } from "../types.mts";
+export interface MergedBaseLookupInput {
+    owner: string;
+    repo: string;
+    baseRefName: string;
+    baseRefOid: string;
+}
+/** A reused branch name or a fork is insufficient evidence of a merged parent. */
+export declare function readRestMergedBasePullRequests(input: MergedBaseLookupInput): Promise<MergedBasePullRequest[]>;

package/bin/github/rest-merged-base-read.mjs

@@ -0,0 +1,48 @@
+import { readRestPages, restRepoPath, restObject, restString, restNumber, malformedRest, } from "./rest-reader-core.mjs";
+/** A reused branch name or a fork is insufficient evidence of a merged parent. */
+export async function readRestMergedBasePullRequests(input) {
+    const repo = { owner: input.owner, name: input.repo };
+    const head = encodeURIComponent(`${input.owner}:${input.baseRefName}`);
+    const pulls = await readRestPages(`${restRepoPath(repo)}/pulls?state=closed&head=${head}&sort=updated&direction=desc`);
+    const candidates = [];
+    const ids = new Set();
+    for (const value of pulls.nodes) {
+        const pull = restObject(value, "closed pull request");
+        const number = restNumber(pull.number, "closed pull number");
+        if (number === 0 || ids.has(number))
+            malformedRest("closed pull number missing or repeated");
+        ids.add(number);
+        const state = restString(pull.state, "closed pull state");
+        if (!["open", "closed"].includes(state))
+            malformedRest("closed pull state");
+        if (pull.merged_at !== null && typeof pull.merged_at !== "string")
+            malformedRest("closed pull merged_at");
+        if (state !== "closed" || pull.merged_at === null)
+            continue;
+        if (!Number.isFinite(Date.parse(pull.merged_at)))
+            malformedRest("closed pull merged_at");
+        const source = restObject(pull.head, "closed pull head");
+        const headRefName = restString(source.ref, "closed pull head ref");
+        const headRefOid = restString(source.sha, "closed pull head SHA");
+        if (headRefName !== input.baseRefName || headRefOid !== input.baseRefOid)
+            continue;
+        if (source.repo === null)
+            continue;
+        const headRepository = restObject(source.repo, "closed pull head repository");
+        const nameWithOwner = restString(headRepository.full_name, "closed pull head repository name");
+        if (nameWithOwner.toLowerCase() !== `${input.owner}/${input.repo}`.toLowerCase())
+            continue;
+        const base = restObject(pull.base, "closed pull base");
+        candidates.push({
+            number,
+            url: restString(pull.html_url, "closed pull URL"),
+            state: "MERGED",
+            headRefName,
+            headRefOid,
+            baseRefName: restString(base.ref, "closed pull base ref"),
+            mergedAt: pull.merged_at,
+            headRepository: { nameWithOwner },
+        });
+    }
+    return candidates;
+}

package/bin/github/rest-pr-core.d.mts

@@ -0,0 +1,52 @@
+import type { RepoInfo } from "./client.mts";
+export interface RestPull {
+    id: number;
+    node_id: string;
+    number: number;
+    title: string;
+    body: string | null;
+    html_url: string;
+    state: string;
+    merged_at: string | null;
+    draft: boolean;
+    mergeable: boolean | null;
+    mergeable_state: string;
+    updated_at: string;
+    user: {
+        login: string;
+        type?: string;
+    } | null;
+    head: {
+        ref: string;
+        sha: string;
+        repo: {
+            full_name: string;
+        } | null;
+    };
+    base: {
+        ref: string;
+        sha: string;
+    };
+    requested_reviewers: Array<{
+        login: string;
+    }>;
+    requested_teams: Array<{
+        name: string;
+    }>;
+    auto_merge?: {
+        enabled_by?: {
+            login: string;
+        };
+        merge_method: string;
+    } | null;
+}
+export declare function readRestPull(pr: number, repo: RepoInfo): Promise<RestPull>;
+export declare function restPullRefs(pull: RestPull): {
+    number: number;
+    state: string;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    baseRefOid: string;
+};
+export declare function restPullRevision(pull: RestPull): string;

package/bin/github/rest-pr-core.mjs

@@ -0,0 +1,60 @@
+import { readRest as rest } from "./rest-reader-core.mjs";
+import { restRepoPath, restObject, restString, restNumber, restBoolean, restArray, malformedRest, } from "./rest-reader-core.mjs";
+import { recordRestIdentity } from "./rest-identities.mjs";
+export async function readRestPull(pr, repo) {
+    const value = await rest("GET", `${restRepoPath(repo)}/pulls/${pr}`);
+    const data = restObject(value, "pull request");
+    const head = restObject(data.head, "pull request head");
+    const base = restObject(data.base, "pull request base");
+    restNumber(data.id, "pull request id");
+    restString(data.node_id, "pull request node_id");
+    if (restNumber(data.number, "pull request number") !== pr)
+        throw new Error("REST pull request identity changed");
+    restString(data.title, "pull request title");
+    restString(data.html_url, "pull request html_url");
+    if (data.body !== null && typeof data.body !== "string")
+        malformedRest("pull request body");
+    if (data.merged_at !== null && typeof data.merged_at !== "string")
+        malformedRest("pull request merged_at");
+    restArray(data.requested_reviewers, "requested reviewers");
+    restArray(data.requested_teams, "requested teams");
+    restString(data.state, "pull request state");
+    restBoolean(data.draft, "pull request draft");
+    restString(head.sha, "pull request head SHA");
+    restString(head.ref, "pull request head ref");
+    restString(base.sha, "pull request base SHA");
+    restString(base.ref, "pull request base ref");
+    restString(data.updated_at, "pull request updated_at");
+    if (!Number.isFinite(Date.parse(data.updated_at)))
+        malformedRest("pull request revision timestamp");
+    restString(data.mergeable_state, "pull request mergeable_state");
+    if (data.mergeable !== null)
+        restBoolean(data.mergeable, "pull request mergeable");
+    await recordRestIdentity(repo, pr, data.node_id, String(data.id), "pull");
+    return data;
+}
+export function restPullRefs(pull) {
+    return {
+        number: pull.number,
+        state: pull.merged_at ? "MERGED" : pull.state.toUpperCase(),
+        headRefName: pull.head.ref,
+        headRefOid: pull.head.sha,
+        baseRefName: pull.base.ref,
+        baseRefOid: pull.base.sha,
+    };
+}
+export function restPullRevision(pull) {
+    return JSON.stringify([
+        pull.head.ref,
+        pull.head.sha,
+        pull.base.ref,
+        pull.base.sha,
+        pull.updated_at,
+        pull.state,
+        pull.draft,
+        pull.merged_at,
+        pull.mergeable,
+        pull.mergeable_state,
+        pull.auto_merge ?? null,
+    ]);
+}