pr-shepherd 0.46.8 → 0.48.0

package/bin/commands/poll.mjs

@@ -1,69 +1,15 @@
 import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs } from "./poll-quota.mjs";
+import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
-function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
-    if (verbose) {
-        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
-    }
-    else {
-        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — still running; next tick in ${sleepSeconds}s\n`);
-    }
-}
-function waitSignature(result) {
-    const activity = result.activity ?? {
-        commitCount: 0,
-        reviewRoundCount: 0,
-        latestCommitCommittedAtUnix: null,
-        reviewItemsSinceLatestCommit: [],
-    };
-    return JSON.stringify({
-        status: result.status,
-        mergeStateStatus: result.mergeStateStatus,
-        reviewDecision: result.reviewDecision,
-        state: result.state,
-        active: (result.inProgressChecks ?? []).map((c) => [c.name, c.status, c.runId]),
-        commitCount: activity.commitCount,
-        latestCommitCommittedAtUnix: activity.latestCommitCommittedAtUnix,
-        reviewRoundCount: activity.reviewRoundCount,
-        reviewItemsSinceLatestCommit: activity.reviewItemsSinceLatestCommit.length,
-    });
-}
-function writeQuietStatus(tick, elapsedSeconds, sleepSeconds, result) {
-    const activeChecks = result.inProgressChecks ?? [];
-    const activeCheckText = activeChecks.map((c) => `${c.name} (${c.status})`).join(", ");
-    const active = activeChecks.length > 0 ? ` · active: ${activeCheckText}` : "";
-    const commitCount = result.activity?.commitCount ?? 0;
-    const reviewItems = result.activity?.reviewItemsSinceLatestCommit.length ?? 0;
-    const reviewRounds = result.activity?.reviewRoundCount ?? 0;
-    const commitSeg = commitCount > 0 ? ` · ${commitCount} commits` : "";
-    const reviewRoundSeg = reviewRounds > 0 ? ` · ${reviewRounds} review rounds` : "";
-    const reviewSeg = reviewItems > 0 ? ` · ${reviewItems} review items since latest commit` : "";
-    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT ${result.status}/${result.mergeStateStatus}/${result.reviewDecision ?? "NO_REVIEW_DECISION"}${active}${commitSeg}${reviewRoundSeg}${reviewSeg} — sleeping ${sleepSeconds}s\n`);
-}
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
-function writeWaitProgress(opts) {
-    const elapsedSeconds = Math.round(opts.elapsedMs / 1000);
-    const sleepSeconds = Math.round(opts.sleepMs / 1000);
-    if (!opts.quietStatus) {
-        writeTickProgress(opts.tick, elapsedSeconds, sleepSeconds, opts.verbose);
-        return opts.lastWaitSignature;
-    }
-    const signature = waitSignature(opts.result);
-    if (signature !== opts.lastWaitSignature) {
-        writeQuietStatus(opts.tick, elapsedSeconds, sleepSeconds, opts.result);
-    }
-    return signature;
-}
-function writeDebounceProgress(tick, elapsedMs, remainingMs) {
-    const elapsedSeconds = Math.round(elapsedMs / 1000);
-    const remainingSeconds = Math.round(remainingMs / 1000);
-    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
-}
 /** @deprecated Hidden implementation for the legacy `poll` alias. */
 export function runPoll(opts) {
-    return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true);
+    return withPollApiUsage(() => runPollCore(opts), opts.untilTerminal === true, opts.intervalSeconds / 60);
 }
 async function runPollCore(opts) {
     const { intervalSeconds, timeoutSeconds, debounceSeconds: debounceSecondsOpt, quietStatus: quietStatusOpt, untilTerminal: untilTerminalOpt, ...iterateOpts } = opts;
@@ -71,6 +17,7 @@ async function runPollCore(opts) {
     const timeoutMs = Math.min(timeoutSeconds * 1000, MAX_TIMER_MS);
     const debounceSeconds = debounceSecondsOpt ?? DEFAULT_POLL_DEBOUNCE_SECONDS;
     const debounceMs = Math.min(debounceSeconds * 1000, MAX_TIMER_MS);
+    const quotaBands = loadConfig().watch.graphqlQuotaWarnings;
     const start = Date.now();
     let tick = 0;
     let lastResult;
@@ -82,23 +29,65 @@ async function runPollCore(opts) {
     // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
+    let rateLimitRetries = 0;
     while (true) {
         tick += 1;
         const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
-        lastResult = await runIterate({
+        const remainingBefore = untilTerminal
+            ? Number.POSITIVE_INFINITY
+            : timeoutMs - (Date.now() - start);
+        // Cache only internal continuation ticks. Last bounded tick, FIX_CODE debounce,
+        // and any tick we return to the caller must fetch BatchPr.
+        const allowCache = debounceUntil === null && remainingBefore + TIMER_DRIFT_TOLERANCE_MS >= intervalMs;
+        const iterateTick = (fingerprintCache) => runIterate({
             ...iterateOpts,
             prNumber,
             persistSeen: debounceSeconds === 0 || pastDebounce,
-            // Until-terminal must persist before deciding to return.
+            fingerprintCache,
             deferQuotaWarning: !untilTerminal,
+            quotaWarningMinimumPollIntervalMinutes: intervalSeconds / 60,
         });
+        const runTick = async (fingerprintCache) => {
+            try {
+                const result = await iterateTick(fingerprintCache);
+                rateLimitRetries = 0;
+                return result;
+            }
+            catch (err) {
+                const retryMs = untilTerminal ? pollGraphQlRetryAfterMs(err) : null;
+                if (retryMs === null || rateLimitRetries >= 1)
+                    throw err;
+                rateLimitRetries += 1;
+                process.stderr.write(`[poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
+                await sleep(retryMs);
+                const result = await iterateTick(fingerprintCache);
+                rateLimitRetries = 0;
+                return result;
+            }
+        };
+        lastResult = await runTick(allowCache);
         prNumber ??= lastResult.pr;
         if (lastResult.quotaWarning !== undefined)
             pendingQuotaWarning = lastResult.quotaWarning;
+        const refreshIfReturning = async () => {
+            if (lastResult?.fingerprintReused !== true)
+                return;
+            lastResult = await runTick(false);
+            if (lastResult.quotaWarning !== undefined)
+                pendingQuotaWarning = lastResult.quotaWarning;
+        };
         if (untilTerminal &&
             pendingQuotaWarning !== undefined &&
             !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
             !(debounceUntil !== null && !pastDebounce)) {
+            await refreshIfReturning();
+            if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+                debounceUntil ??= Date.now() + debounceMs;
+                const remainingMs = Math.max(debounceUntil - Date.now(), 0);
+                writeDebounceProgress(tick, Date.now() - start, remainingMs);
+                await sleep(Math.min(intervalMs, remainingMs));
+                continue;
+            }
             if (["cancel", "escalate"].includes(lastResult.action)) {
                 const { quotaWarning: _quotaWarning, ...withoutQuotaWarning } = lastResult;
                 lastResult = withoutQuotaWarning;
@@ -112,30 +101,40 @@ async function runPollCore(opts) {
             if (pendingQuotaWarning === undefined)
                 debounceUntil = null;
             const elapsedMs = Date.now() - start;
+            const sleepMs = graphqlQuotaPollIntervalMs(quotaBands, lastResult.apiUsage?.graphql, intervalMs, MAX_TIMER_MS);
             if (!untilTerminal) {
                 const remainingMs = timeoutMs - elapsedMs;
-                if (remainingMs <= 0)
-                    break;
-                if (remainingMs + TIMER_DRIFT_TOLERANCE_MS < intervalMs)
+                if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
+                    await refreshIfReturning();
                     break;
+                }
             }
             lastWaitSignature = writeWaitProgress({
                 tick,
                 elapsedMs,
-                sleepMs: intervalMs,
+                sleepMs,
                 result: lastResult,
                 quietStatus,
                 verbose,
                 lastWaitSignature,
             });
-            await sleep(intervalMs);
+            await sleep(sleepMs);
             continue;
         }
         if ((untilTerminal || iterateOpts.merge) &&
             lastResult.action === "mark_ready" &&
             !pastDebounce) {
             debounceUntil = null;
-            await sleep(intervalMs);
+            const elapsedMs = Date.now() - start;
+            const sleepMs = graphqlQuotaPollIntervalMs(quotaBands, lastResult.apiUsage?.graphql, intervalMs, MAX_TIMER_MS);
+            if (!untilTerminal) {
+                const remainingMs = timeoutMs - elapsedMs;
+                if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
+                    await refreshIfReturning();
+                    break;
+                }
+            }
+            await sleep(sleepMs);
             continue;
         }
         if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
@@ -147,6 +146,7 @@ async function runPollCore(opts) {
             }
             continue;
         }
+        await refreshIfReturning();
         break;
     }
     return lastResult;

package/bin/config/load.d.mts

@@ -6,6 +6,12 @@ export interface GraphqlQuotaWarningBand {
     remainingPercent: number;
     pollIntervalMinutes: number;
 }
+interface PollConfig {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    debounceSeconds: number;
+    quietStatus: boolean;
+}
 export interface PrShepherdConfig {
     /** Optional user classification configuration; preserved for rule consumers. */
     classify?: unknown;
@@ -40,6 +46,7 @@ export interface PrShepherdConfig {
          */
         resolveOtherHumanThreads: ResolveOtherHumanThreads;
     };
+    poll: PollConfig;
     watch: {
         readyDelayMinutes: number;
         graphqlQuotaWarnings: GraphqlQuotaWarningBand[];

package/bin/config/load.mjs

@@ -137,7 +137,30 @@ function parseMergeCommandArgs(value) {
     }
     return strategies.length === 0 ? [...value, "--merge"] : [...value];
 }
-function parseGraphqlQuotaWarnings(value) {
+function parsePollConfig(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid config: poll must be a plain object");
+    }
+    const record = value;
+    const intervalSeconds = parsePollDuration(record["intervalSeconds"], "intervalSeconds");
+    const timeoutSeconds = parsePollDuration(record["timeoutSeconds"], "timeoutSeconds");
+    const debounceSeconds = parsePollDuration(record["debounceSeconds"], "debounceSeconds", true);
+    const quietStatus = record["quietStatus"];
+    if (typeof quietStatus !== "boolean") {
+        throw new Error(`Invalid config: poll.quietStatus must be a boolean, got ${JSON.stringify(quietStatus)}`);
+    }
+    return { intervalSeconds, timeoutSeconds, debounceSeconds, quietStatus };
+}
+function parsePollDuration(value, key, allowZero = false) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        (allowZero ? value < 0 : value <= 0)) {
+        const range = allowZero ? "a non-negative" : "a positive";
+        throw new Error(`Invalid config: poll.${key} must be ${range} finite number, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseGraphqlQuotaWarnings(value, pollIntervalSeconds) {
     if (!Array.isArray(value)) {
         throw new Error("Invalid config: watch.graphqlQuotaWarnings must be an array");
     }
@@ -149,30 +172,61 @@ function parseGraphqlQuotaWarnings(value) {
         const record = item;
         const remainingPercent = record["remainingPercent"];
         const pollIntervalMinutes = record["pollIntervalMinutes"];
+        const pollIntervalFactor = record["pollIntervalFactor"];
         if (typeof remainingPercent !== "number" ||
             !Number.isInteger(remainingPercent) ||
             remainingPercent < 1 ||
             remainingPercent > 100) {
             throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].remainingPercent must be an integer from 1 to 100`);
         }
-        if (typeof pollIntervalMinutes !== "number" ||
-            !Number.isFinite(pollIntervalMinutes) ||
-            pollIntervalMinutes <= 0) {
+        if (pollIntervalMinutes === undefined && pollIntervalFactor === undefined) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] must define pollIntervalMinutes, pollIntervalFactor, or both`);
+        }
+        if (pollIntervalMinutes !== undefined &&
+            (typeof pollIntervalMinutes !== "number" ||
+                !Number.isFinite(pollIntervalMinutes) ||
+                pollIntervalMinutes <= 0)) {
             throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalMinutes must be a positive number`);
         }
+        if (pollIntervalFactor !== undefined &&
+            (typeof pollIntervalFactor !== "number" ||
+                !Number.isFinite(pollIntervalFactor) ||
+                pollIntervalFactor < 1)) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalFactor must be a number greater than or equal to 1`);
+        }
         if (seen.has(remainingPercent)) {
             throw new Error(`Invalid config: watch.graphqlQuotaWarnings has duplicate remainingPercent ${remainingPercent}`);
         }
         seen.add(remainingPercent);
-        return { remainingPercent, pollIntervalMinutes };
+        const factorMinutes = typeof pollIntervalFactor === "number" ? (pollIntervalSeconds * pollIntervalFactor) / 60 : 0;
+        const absoluteMinutes = typeof pollIntervalMinutes === "number" ? pollIntervalMinutes : 0;
+        const resolvedPollIntervalMinutes = Math.max(absoluteMinutes, factorMinutes);
+        if (!Number.isFinite(resolvedPollIntervalMinutes)) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] resolves to a non-finite poll interval`);
+        }
+        return {
+            remainingPercent,
+            pollIntervalMinutes: resolvedPollIntervalMinutes,
+        };
     });
-    return parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
+    parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
+    for (let index = 1; index < parsed.length; index += 1) {
+        const previous = parsed[index - 1];
+        const current = parsed[index];
+        if (previous !== undefined &&
+            current !== undefined &&
+            current.pollIntervalMinutes < previous.pollIntervalMinutes) {
+            throw new Error("Invalid config: watch.graphqlQuotaWarnings pollIntervalMinutes must not decrease as remainingPercent decreases");
+        }
+    }
+    return parsed;
 }
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",
     "botUsernames",
     "ignoreChecks",
     "iterate",
+    "poll",
     "watch",
     "resolve",
     "checks",
@@ -189,6 +243,7 @@ const KNOWN_NESTED_KEYS = {
         "behindBaseHint",
         "resolveOtherHumanThreads",
     ]),
+    poll: new Set(["intervalSeconds", "timeoutSeconds", "debounceSeconds", "quietStatus"]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),
@@ -226,7 +281,23 @@ function warnUnknownConfigKeys(config) {
         }
     }
 }
-const defaults = builtins;
+const rawDefaults = builtins;
+function parseConfig(value, normalizeMergeArgs = true) {
+    const config = value;
+    config.botUsernames = parseBotUsernames(config.botUsernames);
+    config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
+    config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
+    if (config.merge && normalizeMergeArgs) {
+        config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
+    }
+    config.poll = parsePollConfig(config.poll);
+    config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings, config.poll.intervalSeconds);
+    config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
+    config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
+    config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
+    return config;
+}
+const defaults = parseConfig(structuredClone(rawDefaults), false);
 const configCache = new Map();
 function stripDeprecatedActionKeys(parsed) {
     const rawActions = parsed.actions;
@@ -277,24 +348,14 @@ export function loadConfig() {
             configCache.set(cwd, defaults);
             return defaults;
         }
-        const config = deepMerge(structuredClone(defaults), overlay);
-        config.botUsernames = parseBotUsernames(config.botUsernames);
-        config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
-        config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
-        if (config.merge)
-            config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
-        config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings);
-        config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
-        config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
-        config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
+        const config = parseConfig(deepMerge(structuredClone(rawDefaults), overlay));
         configCache.set(cwd, config);
         return config;
     }
     catch (err) {
         process.stderr.write(`pr-shepherd: failed to parse ${rcPaths[0]}: ${err instanceof Error ? err.message : String(err)}\n`);
-        const fallback = { ...defaults };
-        configCache.set(cwd, fallback);
-        return fallback;
+        configCache.set(cwd, defaults);
+        return defaults;
     }
 }
 /** Reset the config cache — for use in tests that change directories. */

package/bin/config.json

@@ -22,12 +22,18 @@
     "behindBaseHint": "",
     "resolveOtherHumanThreads": "none"
   },
+  "poll": {
+    "intervalSeconds": 60,
+    "timeoutSeconds": 270,
+    "debounceSeconds": 60,
+    "quietStatus": false
+  },
   "watch": {
     "readyDelayMinutes": 10,
     "graphqlQuotaWarnings": [
-      { "remainingPercent": 30, "pollIntervalMinutes": 2 },
-      { "remainingPercent": 20, "pollIntervalMinutes": 5 },
-      { "remainingPercent": 10, "pollIntervalMinutes": 10 }
+      { "remainingPercent": 30, "pollIntervalFactor": 2 },
+      { "remainingPercent": 20, "pollIntervalFactor": 5 },
+      { "remainingPercent": 10, "pollIntervalFactor": 10 }
     ]
   },
   "resolve": {

package/bin/github/batch-raw-rules.d.mts

@@ -21,7 +21,7 @@ interface RawCheckCommit {
             oid: string;
         }>;
     };
-    statusCheckRollup: {
+    statusCheckRollup?: {
         contexts: {
             pageInfo: {
                 hasNextPage: boolean;
@@ -82,6 +82,9 @@ interface RawRuleParameters {
 export interface RawBaseRef {
     branchProtectionRule: RawBranchProtectionRule | null;
     rules: {
+        pageInfo?: {
+            hasNextPage: boolean;
+        };
         nodes: RawRepositoryRule[];
     } | null;
 }

package/bin/github/batch-raw-types.d.mts

@@ -1,6 +1,9 @@
 import type { CommentAuthorAssociation } from "../types/github.mts";
 import type { RawPrMergeFields } from "./batch-raw-rules.mts";
 export interface RawBatchResponse {
+    viewer?: {
+        login: string | null;
+    } | null;
     repository: {
         viewerPermission: string | null;
         viewerCanAdminister: boolean;
@@ -10,6 +13,7 @@ export interface RawBatchResponse {
 export interface RawPr extends RawPrMergeFields {
     id: string;
     number: number;
+    updatedAt?: string;
     state: string;
     isDraft: boolean;
     viewerDidAuthor: boolean;
@@ -42,6 +46,7 @@ export interface RawPr extends RawPrMergeFields {
         }>;
     };
     reviewThreads: {
+        totalCount?: number;
         pageInfo: {
             hasPreviousPage: boolean;
             startCursor: string | null;
@@ -49,6 +54,7 @@ export interface RawPr extends RawPrMergeFields {
         nodes: RawThread[];
     };
     comments: {
+        totalCount?: number;
         pageInfo: {
             hasPreviousPage: boolean;
             startCursor: string | null;
@@ -71,6 +77,10 @@ export interface RawPr extends RawPrMergeFields {
     };
     allReviews?: {
         totalCount: number;
+        nodes?: Array<{
+            id: string;
+            updatedAt?: string;
+        }>;
     };
     approvedReviews: {
         pageInfo: {
@@ -87,6 +97,7 @@ export interface RawPr extends RawPrMergeFields {
                 committedDate?: string;
                 checkSuites?: RawCheckSuites;
                 statusCheckRollup: {
+                    state?: string | null;
                     contexts: {
                         pageInfo: {
                             hasNextPage: boolean;
@@ -104,6 +115,7 @@ interface RawCheckSuites {
         hasNextPage: boolean;
     };
     nodes: Array<{
+        id?: string;
         conclusion: string | null;
         workflowRun: {
             databaseId: number | null;
@@ -134,6 +146,7 @@ export interface RawThreadComment {
     line: number | null;
     startLine: number | null;
     createdAt?: string;
+    updatedAt?: string;
 }
 export interface RawThread {
     id: string;
@@ -173,6 +186,7 @@ export interface RawComment {
     author: RawAuthor | null;
     body: string;
     createdAt?: string;
+    updatedAt?: string;
 }
 export interface RawReview {
     id: string;

package/bin/github/batch.d.mts

@@ -1,7 +1,9 @@
 import { type RateLimitInfo, type RepoInfo } from "./client.mts";
 import type { BatchPrData } from "../types.mts";
+import { type PrFingerprint } from "./fingerprint.mts";
 interface BatchResult {
     data: BatchPrData;
+    fingerprint?: PrFingerprint;
     rateLimit?: RateLimitInfo;
     /** True when GraphQL returned a complete CheckSuite page; skip REST startup-failure fetch. */
     checkSuitesComplete?: boolean;

package/bin/github/batch.mjs

@@ -7,6 +7,7 @@ import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { paginateBatchConnections } from "./batch-page.mjs";
 import { requireRawPr } from "./batch-response.mjs";
 import { hydrateMergeQueueChecks } from "./merge-queue-checks.mjs";
+import { fingerprintFromRaw } from "./fingerprint.mjs";
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
@@ -24,6 +25,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
     data.checks = mergeStartupFailureChecks(data.checks, parseSuiteStartupFailures(raw));
     return {
         data,
+        fingerprint: fingerprintFromRaw(raw, result.data.repository?.viewerPermission ?? null, result.data.viewer?.login ?? null),
         rateLimit: paged.rateLimit ?? result.rateLimit,
         ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
     };

package/bin/github/fingerprint-fields.d.mts

@@ -0,0 +1,58 @@
+import type { RawBaseRef } from "./batch-raw-rules.mts";
+export interface FingerprintSuites {
+    pageInfo?: {
+        hasNextPage: boolean;
+    };
+    nodes?: Array<{
+        id?: string;
+        conclusion: string | null;
+        workflowRun?: {
+            databaseId: number | null;
+        } | null;
+    }>;
+}
+export interface FingerprintComment {
+    id: string;
+    updatedAt?: string;
+}
+export declare function suiteFingerprint(suites: FingerprintSuites | undefined): {
+    checkSuiteConclusions: string;
+    checkSuitesComplete: boolean;
+};
+export declare function mergePolicyFingerprint(raw: {
+    isMergeQueueEnabled?: boolean;
+    baseRef?: RawBaseRef | null;
+}): string;
+export declare function commentRevisions(nodes: FingerprintComment[]): string;
+export declare function threadCommentRevisions(nodes: Array<{
+    id: string;
+    comments?: {
+        totalCount?: number;
+        nodes: Array<{
+            id: string;
+            updatedAt?: string;
+        }>;
+    };
+}>): string;
+export declare function hasMultiCommentThreads(nodes: Array<{
+    comments?: {
+        totalCount?: number;
+    };
+}>): boolean;
+export declare function rulesComplete(baseRef?: {
+    rules?: {
+        pageInfo?: {
+            hasNextPage: boolean;
+        };
+    } | null;
+} | null): boolean;
+export declare function stackKey(raw: {
+    stack?: {
+        number: number;
+        size: number;
+        baseRefName: string;
+    } | null;
+    stackEntry?: {
+        position: number;
+    } | null;
+}): string;

package/bin/github/fingerprint-fields.mjs

@@ -0,0 +1,39 @@
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+export function suiteFingerprint(suites) {
+    if (suites === undefined)
+        return { checkSuiteConclusions: "", checkSuitesComplete: false };
+    return {
+        checkSuiteConclusions: (suites.nodes ?? [])
+            .map((node) => `${node.id ?? node.workflowRun?.databaseId ?? ""}:${node.conclusion ?? ""}`)
+            .join(","),
+        checkSuitesComplete: suites.pageInfo?.hasNextPage === false,
+    };
+}
+export function mergePolicyFingerprint(raw) {
+    return JSON.stringify({
+        isMergeQueueEnabled: Boolean(raw.isMergeQueueEnabled),
+        rules: parseBranchRules(raw.baseRef),
+    });
+}
+export function commentRevisions(nodes) {
+    return nodes.map((node) => `${node.id}:${node.updatedAt ?? ""}`).join(",");
+}
+export function threadCommentRevisions(nodes) {
+    return nodes
+        .map((thread) => {
+        const last = thread.comments?.nodes.at(-1);
+        return `${thread.id}:${last?.id ?? ""}:${last?.updatedAt ?? ""}`;
+    })
+        .join(",");
+}
+export function hasMultiCommentThreads(nodes) {
+    return nodes.some((thread) => (thread.comments?.totalCount ?? 0) > 1);
+}
+export function rulesComplete(baseRef) {
+    return baseRef?.rules?.pageInfo?.hasNextPage !== true;
+}
+export function stackKey(raw) {
+    if (!raw.stack)
+        return "";
+    return `${raw.stack.number}:${raw.stack.size}:${raw.stackEntry?.position ?? 0}:${raw.stack.baseRefName}`;
+}

package/bin/github/fingerprint.d.mts

@@ -0,0 +1,35 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawPr } from "./batch-raw-types.mts";
+export interface PrFingerprint {
+    headRefOid: string;
+    updatedAt: string;
+    state: string;
+    isDraft: boolean;
+    mergeable: string;
+    mergeStateStatus: string;
+    reviewDecision: string | null;
+    isInMergeQueue: boolean;
+    isMergeQueueEnabled: boolean;
+    mergePolicy: string;
+    commentCount: number;
+    commentRevisions: string;
+    threadCount: number;
+    reviewCount: number;
+    reviewRevisions: string;
+    latestCommentId: string | null;
+    latestThreadId: string | null;
+    latestReviewId: string | null;
+    checkRollupState: string | null;
+    checkSuiteConclusions: string;
+    checkSuitesComplete: boolean;
+    viewerCanUpdate: boolean;
+    viewerPermission: string | null;
+    viewerLogin: string | null;
+    stackKey: string;
+    threadCommentRevisions: string;
+    rulesComplete: boolean;
+    hasMultiCommentThreads: boolean;
+}
+export declare function fingerprintFromRaw(raw: RawPr, viewerPermission?: string | null, viewerLogin?: string | null): PrFingerprint;
+export declare function fingerprintsEqual(left: PrFingerprint, right: PrFingerprint): boolean;
+export declare function fetchPrFingerprint(pr: number, repo: RepoInfo): Promise<PrFingerprint>;