pr-shepherd 0.35.0 → 0.36.0

package/bin/github/http.d.mts

@@ -1,5 +1,6 @@
 export { GitHubRequestError } from "./errors.mts";
 export { _resetTokenCache } from "./http-auth.mts";
 export { graphql, graphqlWithRateLimit } from "./graphql-http.mts";
-export { rest, restText } from "./rest-http.mts";
+export { rest, restWithRateLimit } from "./rest-http.mts";
+export { restText } from "./rest-text.mts";
 export type { RateLimitInfo } from "./http-utils.mts";

package/bin/github/http.mjs

@@ -1,4 +1,5 @@
 export { GitHubRequestError } from "./errors.mjs";
 export { _resetTokenCache } from "./http-auth.mjs";
 export { graphql, graphqlWithRateLimit } from "./graphql-http.mjs";
-export { rest, restText } from "./rest-http.mjs";
+export { rest, restWithRateLimit } from "./rest-http.mjs";
+export { restText } from "./rest-text.mjs";

package/bin/github/pagination.d.mts

@@ -6,8 +6,9 @@
  * that returns pages of fake data.
  *
  * GitHub's GraphQL connections support two cursor directions:
- *   - Forward (`after` + `first`) — used by check contexts.
- *   - Backward (`before` + `last`) — used by reviewThreads (default GitHub order).
+ *   - Forward (`after` + `first`) — used by check contexts and nested thread comments.
+ *   - Backward (`before` + `last`) — used by reviewThreads/comments/reviews extra pages
+ *     (combined in `batch-page.mts`; `paginateBackward` remains the generic primitive).
  */
 interface PageInfo {
     hasNextPage?: boolean;

package/bin/github/pagination.mjs

@@ -6,8 +6,9 @@
  * that returns pages of fake data.
  *
  * GitHub's GraphQL connections support two cursor directions:
- *   - Forward (`after` + `first`) — used by check contexts.
- *   - Backward (`before` + `last`) — used by reviewThreads (default GitHub order).
+ *   - Forward (`after` + `first`) — used by check contexts and nested thread comments.
+ *   - Backward (`before` + `last`) — used by reviewThreads/comments/reviews extra pages
+ *     (combined in `batch-page.mts`; `paginateBackward` remains the generic primitive).
  */
 /**
  * Paginate forward through a GraphQL connection (`first` / `after` cursors).

package/bin/github/queries.d.mts

@@ -8,6 +8,10 @@
  */
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export declare const BATCH_PR_QUERY: string;
+/** Slim @include follow-up for outstanding batch-query connections. */
+export declare const BATCH_PR_PAGE_QUERY: string;
+/** PR head fields plus a single review thread for `commit-suggestion`. */
+export declare const COMMIT_SUGGESTION_THREAD_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
 /** Fetch inline annotations for a single CheckRun by node ID. */

package/bin/github/queries.mjs

@@ -11,6 +11,10 @@ import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export const BATCH_PR_QUERY = gql("batch-pr.gql");
+/** Slim @include follow-up for outstanding batch-query connections. */
+export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
+/** PR head fields plus a single review thread for `commit-suggestion`. */
+export const COMMIT_SUGGESTION_THREAD_QUERY = gql("commit-suggestion-thread.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
 /** Fetch inline annotations for a single CheckRun by node ID. */

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

@@ -1,2 +1,7 @@
+import { type RateLimitInfo } from "./http-utils.mts";
+export interface RestResult<T = unknown> {
+    data: T;
+    rateLimit?: RateLimitInfo;
+}
 export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
-export declare function restText(path: string): Promise<string>;
+export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown): Promise<RestResult<T>>;

package/bin/github/rest-http.mjs

@@ -3,10 +3,29 @@ import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { parseRateLimit, parseRetryAfter, redactToken, redactUrl, sanitizeBody, } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
+const SAFE_GITHUB_REST_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*$/;
+function githubApiUrl(path) {
+    if (!SAFE_GITHUB_REST_PATH.test(path) || path.includes("://")) {
+        throw new Error(`Invalid GitHub REST path: ${path}`);
+    }
+    const url = new URL(path, `${BASE_URL}/`);
+    if (url.origin !== BASE_URL) {
+        throw new Error(`Invalid GitHub REST URL origin: ${url.origin}`);
+    }
+    const pathname = path.split("?")[0] ?? path;
+    if (pathname.split("/").some((seg) => seg === ".." || seg === ".")) {
+        throw new Error(`Invalid GitHub REST path: ${path}`);
+    }
+    return url.href;
+}
 export async function rest(method, path, body) {
-    const url = `${BASE_URL}${path}`;
+    const { data } = await restWithRateLimit(method, path, body);
+    return data;
+}
+export async function restWithRateLimit(method, path, body) {
+    const url = githubApiUrl(path);
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
     const t0 = performance.now();
@@ -17,6 +36,7 @@ export async function rest(method, path, body) {
     }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "REST", method, url, status, durationMs })));
     const durationMs = Math.round(performance.now() - retryT0);
     const ct = res.headers.get("content-type") ?? "";
+    const rateLimit = parseRateLimit(res.headers) ?? undefined;
     if (!res.ok) {
         const text = await res.text();
         appendEntry(formatResponseEntry({
@@ -31,7 +51,7 @@ export async function rest(method, path, body) {
         }));
         throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            rateLimit,
             retryAfterSeconds: parseRetryAfter(res.headers),
         });
     }
@@ -48,7 +68,7 @@ export async function rest(method, path, body) {
             body: json,
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        return json;
+        return { data: json, rateLimit };
     }
     appendEntry(formatResponseEntry({
         n,
@@ -60,86 +80,5 @@ export async function rest(method, path, body) {
         contentType: ct || undefined,
         attempt: attempt > 1 ? attempt : undefined,
     }));
-    return undefined;
-}
-export async function restText(path) {
-    const url = `${BASE_URL}${path}`;
-    const n = nextEntry();
-    appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
-    const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
-    const durationMs = Math.round(performance.now() - retryT0);
-    if ([301, 302, 307, 308].includes(res.status)) {
-        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
-        if (redirected !== null)
-            return redirected;
-    }
-    if (!res.ok) {
-        const text = await res.text();
-        appendEntry(formatResponseEntry({
-            n,
-            kind: "restText",
-            method: "GET",
-            url,
-            status: res.status,
-            durationMs,
-            attempt: attempt > 1 ? attempt : undefined,
-        }));
-        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
-            status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(res.headers),
-        });
-    }
-    appendEntry(formatResponseEntry({
-        n,
-        kind: "restText",
-        method: "GET",
-        url,
-        status: res.status,
-        durationMs,
-        contentLength: parseContentLength(res.headers),
-        attempt: attempt > 1 ? attempt : undefined,
-    }));
-    return res.text();
-}
-async function followRestTextRedirect(res, entry) {
-    appendEntry(formatResponseEntry({
-        n: entry.n,
-        kind: "restText",
-        method: "GET",
-        url: entry.url,
-        status: res.status,
-        durationMs: entry.durationMs,
-        attempt: entry.attempt > 1 ? entry.attempt : undefined,
-    }));
-    const location = res.headers.get("location");
-    if (!location)
-        return null;
-    const n2 = nextEntry();
-    const logUrl = redactUrl(location);
-    appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
-    const t1 = performance.now();
-    const redirectRes = await fetch(location);
-    appendEntry(formatResponseEntry({
-        n: n2,
-        kind: "restText",
-        method: "GET",
-        url: logUrl,
-        status: redirectRes.status,
-        durationMs: Math.round(performance.now() - t1),
-        contentLength: parseContentLength(redirectRes.headers),
-    }));
-    if (!redirectRes.ok) {
-        throw new GitHubRequestError(`redirect target ${location} failed: ${redirectRes.status}`, {
-            status: redirectRes.status,
-            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
-        });
-    }
-    return redirectRes.text();
-}
-function parseContentLength(headers) {
-    const raw = headers.get("content-length");
-    return raw !== null && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+    return { data: undefined, rateLimit };
 }

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

@@ -0,0 +1 @@
+export declare function restText(path: string): Promise<string>;

package/bin/github/rest-text.mjs

@@ -0,0 +1,88 @@
+import { appendEntry, nextEntry } from "../log/log-file.mjs";
+import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { makeHeaders } from "./http-auth.mjs";
+import { requestWithTokenRetry } from "./http-request.mjs";
+import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+const BASE_URL = "https://api.github.com";
+export async function restText(path) {
+    const url = `${BASE_URL}${path}`;
+    const n = nextEntry();
+    appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
+    const t0 = performance.now();
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
+    const durationMs = Math.round(performance.now() - retryT0);
+    if ([301, 302, 307, 308].includes(res.status)) {
+        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
+        if (redirected !== null)
+            return redirected;
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "restText",
+            method: "GET",
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
+        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
+    }
+    appendEntry(formatResponseEntry({
+        n,
+        kind: "restText",
+        method: "GET",
+        url,
+        status: res.status,
+        durationMs,
+        contentLength: parseContentLength(res.headers),
+        attempt: attempt > 1 ? attempt : undefined,
+    }));
+    return res.text();
+}
+async function followRestTextRedirect(res, entry) {
+    appendEntry(formatResponseEntry({
+        n: entry.n,
+        kind: "restText",
+        method: "GET",
+        url: entry.url,
+        status: res.status,
+        durationMs: entry.durationMs,
+        attempt: entry.attempt > 1 ? entry.attempt : undefined,
+    }));
+    const location = res.headers.get("location");
+    if (!location)
+        return null;
+    const n2 = nextEntry();
+    const logUrl = redactUrl(location);
+    appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
+    const t1 = performance.now();
+    const redirectRes = await fetch(location);
+    appendEntry(formatResponseEntry({
+        n: n2,
+        kind: "restText",
+        method: "GET",
+        url: logUrl,
+        status: redirectRes.status,
+        durationMs: Math.round(performance.now() - t1),
+        contentLength: parseContentLength(redirectRes.headers),
+    }));
+    if (!redirectRes.ok) {
+        throw new GitHubRequestError(`redirect target ${logUrl} failed: ${redirectRes.status}`, {
+            status: redirectRes.status,
+            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+        });
+    }
+    return redirectRes.text();
+}
+function parseContentLength(headers) {
+    const raw = headers.get("content-length");
+    return raw !== null && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+}

package/bin/github/suggestion-thread.d.mts

@@ -0,0 +1,9 @@
+import type { ReviewThread } from "../types.mts";
+import type { RepoInfo } from "./client.mts";
+export interface SuggestionThreadResult {
+    headRefOid: string;
+    headRefName: string;
+    headRepoWithOwner: string | null;
+    thread: ReviewThread | null;
+}
+export declare function fetchSuggestionThread(pr: number, repo: RepoInfo, threadId: string): Promise<SuggestionThreadResult>;

package/bin/github/suggestion-thread.mjs

@@ -0,0 +1,45 @@
+import { graphql } from "./client.mjs";
+import { COMMIT_SUGGESTION_THREAD_QUERY } from "./queries.mjs";
+import { mapAuthorType, parseCreatedAt } from "./batch-parser-helpers.mjs";
+export async function fetchSuggestionThread(pr, repo, threadId) {
+    const result = await graphql(COMMIT_SUGGESTION_THREAD_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+        threadId,
+    });
+    const pull = result.data.repository.pullRequest;
+    if (!pull) {
+        throw new Error(`PR #${pr} not found`);
+    }
+    return {
+        headRefOid: pull.headRefOid,
+        headRefName: pull.headRefName,
+        headRepoWithOwner: pull.headRepository?.nameWithOwner ?? null,
+        thread: parseThread(result.data.node, pr, threadId),
+    };
+}
+function parseThread(raw, pr, threadId) {
+    if (!raw?.id || !raw.comments || raw.id !== threadId)
+        return null;
+    if (raw.pullRequest?.number !== pr)
+        return null;
+    const comment = raw.comments.nodes[0];
+    return {
+        id: raw.id,
+        isResolved: raw.isResolved,
+        isOutdated: raw.isOutdated,
+        isMinimized: comment?.isMinimized ?? false,
+        path: raw.path ?? comment?.path ?? null,
+        line: raw.line ?? comment?.line ?? null,
+        startLine: raw.startLine ?? comment?.startLine ?? null,
+        author: comment?.author?.login ?? "unknown",
+        authorType: mapAuthorType(comment?.author?.__typename, comment?.author?.login),
+        ...(comment?.authorAssociation !== undefined && {
+            authorAssociation: comment.authorAssociation,
+        }),
+        body: comment?.body ?? "",
+        url: comment?.url ?? "",
+        createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,
+    };
+}

package/bin/github/thread-comments.mjs

@@ -1,22 +1,26 @@
-import { graphql } from "./client.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { paginateForward } from "./pagination.mjs";
 import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
+import { mapPool } from "../util/pool.mjs";
+const THREAD_COMMENT_PAGE_CONCURRENCY = 4;
 export async function hydrateThreadCommentPages(threads) {
-    const hydrated = [];
-    for (const thread of threads) {
-        hydrated.push(await hydrateThreadCommentPage(thread));
-    }
-    return hydrated;
+    const gate = {};
+    return mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, (thread) => hydrateThreadCommentPage(thread, gate));
 }
-async function hydrateThreadCommentPage(thread) {
+async function hydrateThreadCommentPage(thread, gate) {
     const pageInfo = thread.comments.pageInfo;
     if (!pageInfo?.hasNextPage || !pageInfo.endCursor)
         return thread;
     const extra = await paginateForward(async (cursor) => {
-        const res = await graphql(REVIEW_THREAD_COMMENTS_QUERY, {
+        if (gate.remaining === 0) {
+            throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; thread comment pagination incomplete", { status: 403 });
+        }
+        const res = await graphqlWithRateLimit(REVIEW_THREAD_COMMENTS_QUERY, {
             threadId: thread.id,
             ...(cursor ? { commentsCursor: cursor } : {}),
         });
+        gate.remaining = res.rateLimit?.remaining;
         const node = res.data.node;
         if (!node?.comments) {
             const nodeType = node?.__typename ?? "null";

package/bin/merge-status/derive.mjs

@@ -16,6 +16,7 @@
  *   9. mergeStateStatus CLEAN         → CLEAN
  */
 import { loadConfig } from "../config/load.mjs";
+import { deriveMergeRequirements } from "./requirements.mjs";
 export function deriveMergeStatus(pr) {
     const blockingBotReviewInProgress = detectBlockingBotReview(pr);
     let status;
@@ -55,6 +56,7 @@ export function deriveMergeStatus(pr) {
         reviewDecision: pr.reviewDecision,
         blockingBotReviewInProgress,
         mergeStateStatus: pr.mergeStateStatus,
+        mergeRequirements: deriveMergeRequirements(pr),
     };
 }
 // ---------------------------------------------------------------------------

package/bin/merge-status/requirements-format.d.mts

@@ -0,0 +1,3 @@
+import type { MergeRequirements } from "../types.mts";
+export declare function formatMergeRequirementLines(req: MergeRequirements): string[];
+export declare function blockedReasonFromRequirements(req: MergeRequirements | undefined): string | null;

package/bin/merge-status/requirements-format.mjs

@@ -0,0 +1,88 @@
+const REQUIRED = "[Required]";
+const NOT_REQUIRED = "[Not Required]";
+export function formatMergeRequirementLines(req) {
+    const lines = [
+        formatApprovals(req.approvals.current, req.approvals.requiredCount),
+        formatConversations(req.conversationsResolved),
+    ];
+    if (req.codeOwnerReview)
+        lines.push(`Code owner review: ${REQUIRED}`);
+    if (req.lastPushApproval)
+        lines.push(`Last-push approval: ${REQUIRED}`);
+    if (req.signedCommits)
+        lines.push(`Signed commits: ${REQUIRED}`);
+    if (req.linearHistory)
+        lines.push(`Linear history: ${REQUIRED}`);
+    if (req.branchUpToDate) {
+        const value = req.branchUpToDate.current ? "Yes" : "No";
+        lines.push(`Branch up to date: ${value} ${REQUIRED}`);
+    }
+    if (req.requiredStatusChecks) {
+        const n = req.requiredStatusChecks.contexts.length;
+        lines.push(`Required status checks: ${n} ${REQUIRED}`);
+    }
+    if (req.requiredDeployments) {
+        const envs = req.requiredDeployments.environments.join(", ");
+        lines.push(`Required deployments: ${envs} ${REQUIRED}`);
+    }
+    if (req.requiredWorkflows)
+        lines.push(`Required workflows: ${REQUIRED}`);
+    if (req.codeScanning)
+        lines.push(`Code scanning: ${REQUIRED}`);
+    if (req.mergeQueue)
+        lines.push(formatMergeQueue(req.mergeQueue));
+    if (req.stack) {
+        const { number, position, size, baseRefName } = req.stack;
+        lines.push(`Stack: #${number} ${position}/${size} (base ${baseRefName})`);
+    }
+    return lines;
+}
+export function blockedReasonFromRequirements(req) {
+    if (!req)
+        return null;
+    const unmet = [];
+    if (req.approvals.requiredCount > 0 && req.approvals.current < req.approvals.requiredCount) {
+        const need = req.approvals.requiredCount - req.approvals.current;
+        unmet.push(`awaiting ${need} approval${need === 1 ? "" : "s"}`);
+    }
+    if (req.conversationsResolved.required && !req.conversationsResolved.resolved) {
+        unmet.push("unresolved conversations are required");
+    }
+    if (req.branchUpToDate && !req.branchUpToDate.current) {
+        unmet.push("branch is behind base");
+    }
+    if (req.mergeQueue?.inQueue) {
+        const pos = req.mergeQueue.position != null ? ` position ${req.mergeQueue.position}` : "";
+        unmet.push(`in merge queue${pos}`);
+    }
+    else if (req.mergeQueue?.required) {
+        unmet.push("merge queue is required");
+    }
+    return unmet.length > 0 ? unmet.join("; ") : null;
+}
+function formatApprovals(current, requiredCount) {
+    const tag = requiredCount > 0 ? REQUIRED : NOT_REQUIRED;
+    if (current === 0 && requiredCount === 0)
+        return `Approvals: None ${NOT_REQUIRED}`;
+    if (current === 0)
+        return `Approvals: None ${REQUIRED}`;
+    if (requiredCount > 0)
+        return `Approvals: ${current}/${requiredCount} ${tag}`;
+    return `Approvals: ${current} ${NOT_REQUIRED}`;
+}
+function formatConversations(c) {
+    const value = c.resolved ? "Yes" : "No";
+    const tag = c.required ? REQUIRED : NOT_REQUIRED;
+    return `Conversations Resolved: ${value} ${tag}`;
+}
+function formatMergeQueue(q) {
+    const tag = q.required ? REQUIRED : NOT_REQUIRED;
+    if (q.inQueue) {
+        const pos = q.position != null ? `position ${q.position}` : "Yes";
+        const state = q.state ? ` ${q.state}` : "";
+        return `Merge queue: ${pos}${state} ${tag}`;
+    }
+    if (q.required || q.enabled)
+        return `Merge queue: No ${tag}`;
+    return `Merge queue: No ${NOT_REQUIRED}`;
+}

package/bin/merge-status/requirements.d.mts

@@ -0,0 +1,2 @@
+import type { BatchPrData, MergeRequirements } from "../types.mts";
+export declare function deriveMergeRequirements(pr: BatchPrData): MergeRequirements;

package/bin/merge-status/requirements.mjs

@@ -0,0 +1,51 @@
+import { EMPTY_BRANCH_RULES } from "../github/batch-parsers-rules.mjs";
+export function deriveMergeRequirements(pr) {
+    const rules = pr.branchRules ?? EMPTY_BRANCH_RULES;
+    const currentApprovals = pr.latestReviews.filter((r) => r.state === "APPROVED").length;
+    const unresolvedCount = pr.reviewThreads.filter((t) => !t.isResolved).length;
+    const req = {
+        approvals: {
+            current: currentApprovals,
+            requiredCount: rules.requiredApprovingReviewCount,
+        },
+        conversationsResolved: {
+            resolved: unresolvedCount === 0,
+            unresolvedCount,
+            required: rules.requiresConversationResolution,
+        },
+    };
+    if (rules.requiresCodeOwnerReviews)
+        req.codeOwnerReview = { required: true };
+    if (rules.requiresLastPushApproval)
+        req.lastPushApproval = { required: true };
+    if (rules.requiresCommitSignatures)
+        req.signedCommits = { required: true };
+    if (rules.requiresLinearHistory)
+        req.linearHistory = { required: true };
+    if (rules.requiresStrictStatusChecks) {
+        req.branchUpToDate = { current: pr.mergeStateStatus !== "BEHIND", required: true };
+    }
+    if (rules.requiredStatusCheckContexts.length > 0) {
+        req.requiredStatusChecks = { contexts: rules.requiredStatusCheckContexts };
+    }
+    if (rules.requiredDeploymentEnvironments.length > 0) {
+        req.requiredDeployments = { environments: rules.requiredDeploymentEnvironments };
+    }
+    if (rules.requiresWorkflows)
+        req.requiredWorkflows = { required: true };
+    if (rules.requiresCodeScanning)
+        req.codeScanning = { required: true };
+    const queueRequired = rules.requiresMergeQueue || Boolean(pr.isMergeQueueEnabled);
+    if (queueRequired || pr.isInMergeQueue) {
+        req.mergeQueue = {
+            required: queueRequired,
+            enabled: Boolean(pr.isMergeQueueEnabled),
+            inQueue: Boolean(pr.isInMergeQueue),
+            ...(pr.mergeQueueEntry?.position !== undefined && { position: pr.mergeQueueEntry.position }),
+            ...(pr.mergeQueueEntry?.state !== undefined && { state: pr.mergeQueueEntry.state }),
+        };
+    }
+    if (pr.stack)
+        req.stack = pr.stack;
+    return req;
+}

package/bin/state/base.d.mts

@@ -1 +1,10 @@
 export declare function resolveStateBase(): string;
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/...parts`.
+ * Owner, repo, PR number, and each extra part must be a safe path segment.
+ */
+export declare function resolvePrStatePath(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, ...parts: string[]): string;

package/bin/state/base.mjs

@@ -1,6 +1,29 @@
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { SAFE_PR_NUMBER, SAFE_SEGMENT } from "../util/path-segment.mjs";
 export function resolveStateBase() {
     const envDir = process.env["PR_SHEPHERD_STATE_DIR"];
     return envDir ? envDir : join(tmpdir(), "pr-shepherd-state");
 }
+/**
+ * `$PR_SHEPHERD_STATE_DIR/<owner>-<repo>/<pr>/...parts`.
+ * Owner, repo, PR number, and each extra part must be a safe path segment.
+ */
+export function resolvePrStatePath(key, ...parts) {
+    if (!SAFE_SEGMENT.test(key.owner)) {
+        throw new Error(`Invalid state key segment "owner": ${key.owner}`);
+    }
+    if (!SAFE_SEGMENT.test(key.repo)) {
+        throw new Error(`Invalid state key segment "repo": ${key.repo}`);
+    }
+    const pr = String(key.pr);
+    if (!SAFE_PR_NUMBER.test(pr)) {
+        throw new Error(`Invalid state key segment "pr": ${key.pr}`);
+    }
+    for (const part of parts) {
+        if (!SAFE_SEGMENT.test(part)) {
+            throw new Error(`Invalid state key segment: ${part}`);
+        }
+    }
+    return join(resolveStateBase(), `${key.owner}-${key.repo}`, pr, ...parts);
+}

package/bin/state/bot-cr-seen.mjs

@@ -17,9 +17,8 @@
  */
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join, dirname } from "node:path";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "./base.mjs";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
 import { hashBody } from "./seen-comments.mjs";
 export async function readBotCrSeenState(key) {
     try {
@@ -97,14 +96,5 @@ export function updateBotCrSeenState(previous, currentBotCrReviews, nowSeconds,
     return { next: { reviews: next }, staleIds };
 }
 function resolvePath(key) {
-    for (const [field, value] of [
-        ["owner", key.owner],
-        ["repo", key.repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid state key segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "bot-cr-seen.json");
+    return resolvePrStatePath(key, "bot-cr-seen.json");
 }