pr-shepherd 0.56.6 → 0.57.0

package/bin/github/rest-feedback-read.mjs

@@ -0,0 +1,147 @@
+import { isCcrTransport } from "./transport.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { EXIT } from "../exit-codes.mjs";
+import { readRestPages, restRepoPath, restArray, restObject, restNumber, restBoolean, malformedRest, } from "./rest-reader-core.mjs";
+import { recordRestIdentity, recordThreadIdentity, restThreadId } from "./rest-identities.mjs";
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
+import { restCommentAuthorFields as authorFields } from "./rest-comment-authorship.mjs";
+import { validateRestReviews } from "./rest-review-read.mjs";
+import { validateRestComments, feedbackIdsMatch } from "./rest-feedback-validation.mjs";
+import { readRestViewerLogin } from "./rest-viewer-read.mjs";
+export async function readRestFeedback(pr, repo, knownViewerLogin) {
+    const prefix = restRepoPath(repo);
+    let inline = (await readRestPages(`${prefix}/pulls/${pr}/comments`)).nodes;
+    const issue = (await readRestPages(`${prefix}/issues/${pr}/comments`)).nodes;
+    const reviews = (await readRestPages(`${prefix}/pulls/${pr}/reviews`)).nodes;
+    if (new Set(issue.map((comment) => comment.id)).size !== issue.length ||
+        new Set(reviews.map((review) => review.id)).size !== reviews.length)
+        malformedRest("duplicate feedback IDs");
+    validateRestReviews(reviews);
+    validateRestComments([...inline, ...issue, ...reviews]);
+    let statuses = await readRestThreadStatuses(`${prefix}/pulls/${pr}/ccr/review_threads`);
+    if (statuses && !feedbackIdsMatch(inline, statuses)) {
+        // A reviewer can add or delete comments between these independently paginated reads.
+        // Retry both resources, with thread membership first, before certifying the join.
+        statuses = await readRestThreadStatuses(`${prefix}/pulls/${pr}/ccr/review_threads`);
+        inline = (await readRestPages(`${prefix}/pulls/${pr}/comments`)).nodes;
+        validateRestComments(inline);
+        if (statuses && !feedbackIdsMatch(inline, statuses))
+            throw new GitHubRequestError("Pull request feedback changed while REST snapshot was being read; retry", { status: 409, exitCodeOverride: EXIT.TEMPFAIL });
+    }
+    for (const comment of [...inline, ...issue, ...reviews]) {
+        await recordRestIdentity(repo, pr, comment.node_id, String(comment.id), "state" in comment ? "review" : "comment");
+    }
+    let unavailable = [];
+    if (!statuses && inline.length > 0)
+        unavailable = [
+            {
+                field: "reviewThreads.status",
+                reason: "REST has no resolved/outdated thread state; CCR review_threads is unavailable",
+            },
+        ];
+    const inlineMap = new Map(inline.map((comment) => [comment.id, comment]));
+    if (inlineMap.size !== inline.length)
+        malformedRest("duplicate inline comment IDs");
+    const groups = [];
+    if (statuses) {
+        for (const status of statuses) {
+            const comments = status.comment_ids.map((id) => inlineMap.get(id));
+            const root = comments[0];
+            if (root.in_reply_to_id != null)
+                malformedRest("CCR thread root is a reply");
+            for (const reply of comments.slice(1))
+                if (reply.in_reply_to_id !== root.id)
+                    malformedRest("CCR reply does not belong to its root");
+            groups.push({ id: root.id, comments, status });
+        }
+    }
+    else {
+        for (const comment of inline.filter((comment) => comment.in_reply_to_id == null)) {
+            groups.push({
+                id: comment.id,
+                comments: [comment, ...inline.filter((reply) => reply.in_reply_to_id === comment.id)],
+            });
+        }
+        if (groups.reduce((sum, group) => sum + group.comments.length, 0) !== inline.length)
+            malformedRest("inline comment reply has no root");
+    }
+    const threads = [];
+    const viewerLogin = knownViewerLogin === undefined ? await readRestViewerLogin() : knownViewerLogin;
+    for (const group of groups) {
+        const root = group.comments[0];
+        const id = restThreadId(String(group.id));
+        await recordThreadIdentity(repo, pr, id, String(group.id));
+        const review = reviews.find((review) => review.id === root.pull_request_review_id);
+        threads.push({
+            id,
+            ...(group.status
+                ? { isResolved: group.status.resolved, isOutdated: group.status.outdated }
+                : {}),
+            path: group.status ? group.status.path : (root.path ?? null),
+            line: group.status ? group.status.line : (root.line ?? null),
+            startLine: root.start_line ?? null,
+            ...(review ? { reviewId: review.node_id } : {}),
+            ...authorFields(root, viewerLogin),
+            body: root.body ?? "",
+            url: root.html_url,
+            createdAtUnix: parseCreatedAt(root.created_at),
+            comments: group.comments.map((comment) => ({
+                id: comment.node_id,
+                ...(review ? { reviewId: review.node_id } : {}),
+                ...authorFields(comment, viewerLogin),
+                body: comment.body ?? "",
+                url: comment.html_url,
+                createdAtUnix: parseCreatedAt(comment.created_at),
+            })),
+        });
+    }
+    const comments = issue.map((comment) => ({
+        id: comment.node_id,
+        ...authorFields(comment),
+        body: comment.body ?? "",
+        url: comment.html_url,
+        createdAtUnix: parseCreatedAt(comment.created_at),
+    }));
+    return { threads, comments, reviews, unavailable, viewerLogin };
+}
+async function readRestThreadStatuses(path) {
+    if (!isCcrTransport())
+        return undefined;
+    try {
+        const statuses = (await readRestPages(path)).nodes;
+        for (const status of statuses) {
+            restObject(status, "CCR thread");
+            restBoolean(status.resolved, "CCR thread resolved");
+            restBoolean(status.outdated, "CCR thread outdated");
+            restArray(status.comment_ids, "CCR comment_ids");
+            if (status.path !== null && typeof status.path !== "string")
+                malformedRest("CCR thread path");
+            if (status.line !== null)
+                restNumber(status.line, "CCR thread line");
+            if (status.comment_ids.length === 0)
+                malformedRest("CCR thread has no root comment");
+            for (const id of status.comment_ids)
+                restNumber(id, "CCR comment ID");
+        }
+        return statuses;
+    }
+    catch (error) {
+        if (!(error instanceof GitHubRequestError) || error.status !== 404)
+            throw error;
+        // The proxy answers a missing PR with 404 too; that is not an unavailable route.
+        if (/could not resolve to a pullrequest/i.test(error.responseMessage ?? error.message)) {
+            throw error;
+        }
+        return undefined;
+    }
+}
+export function restReviewToReview(review) {
+    return {
+        id: review.node_id,
+        ...authorFields(review),
+        body: review.body ?? "",
+        url: review.html_url,
+        ...(review.commit_id && { commitOid: review.commit_id }),
+        ...(review.submitted_at && { createdAtUnix: parseCreatedAt(review.submitted_at) }),
+    };
+}

package/bin/github/rest-feedback-validation.d.mts

@@ -0,0 +1,5 @@
+import type { RestComment } from "./rest-feedback-read.mts";
+export declare function validateRestComments(comments: RestComment[]): void;
+export declare function feedbackIdsMatch(inline: RestComment[], statuses: {
+    comment_ids: number[];
+}[]): boolean;

package/bin/github/rest-feedback-validation.mjs

@@ -0,0 +1,28 @@
+import { restObject, restString, restNumber, malformedRest } from "./rest-reader-core.mjs";
+export function validateRestComments(comments) {
+    for (const comment of comments) {
+        restObject(comment, "feedback comment");
+        restString(comment.html_url, "feedback html_url");
+        if (!("state" in comment)) {
+            restString(comment.created_at, "comment created_at");
+            restString(comment.updated_at, "comment updated_at");
+            if (!Number.isFinite(Date.parse(comment.created_at)) ||
+                !Number.isFinite(Date.parse(comment.updated_at)))
+                malformedRest("feedback timestamps");
+        }
+        restNumber(comment.id, "feedback id");
+        restString(comment.node_id, "feedback node_id");
+        if (typeof comment.body !== "string" && comment.body !== null)
+            malformedRest("feedback body");
+    }
+}
+export function feedbackIdsMatch(inline, statuses) {
+    const inlineIds = new Set(inline.map((comment) => comment.id));
+    if (inlineIds.size !== inline.length)
+        malformedRest("duplicate inline comment IDs");
+    const threadIds = statuses.flatMap((status) => status.comment_ids);
+    const covered = new Set(threadIds);
+    if (covered.size !== threadIds.length)
+        malformedRest("repeated CCR thread comment IDs");
+    return covered.size === inlineIds.size && threadIds.every((id) => inlineIds.has(id));
+}

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

@@ -3,6 +3,12 @@ import { type RateLimitInfo } from "./http-utils.mts";
 export interface RestResult<T = unknown> {
     data: T;
     rateLimit?: RateLimitInfo;
+    /** HTTP status, including documented non-2xx statuses accepted by the caller. */
+    status?: number;
+    /** Validator of a conditional read: the stored ETag on a 304, the response ETag on a 200. */
+    etag?: string;
+    /** GitHub pagination header, retained for named REST readers. */
+    link?: string;
 }
 /**
  * Enables `If-None-Match` conditional requests for a REST call, backed by a
@@ -11,11 +17,17 @@ export interface RestResult<T = unknown> {
  * the primary REST rate-limit quota.
  */
 export interface RestRequestOptions {
+    /** Endpoints such as merge-async return useful state on documented non-2xx responses. */
+    acceptStatuses?: readonly number[];
     conditional?: {
         key: StateKey;
         /** Logical cache name; must be unique per distinct resource + page. */
         name: string;
         headSha?: string;
+        /** Return false to keep a 200 body out of the cache (e.g. a still-computing resource). */
+        shouldStore?: (body: unknown) => boolean;
+        /** Send no validator, forcing a fresh body that then replaces the cached entry. */
+        revalidate?: boolean;
     };
 }
 export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;

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;