pr-shepherd 0.46.8 → 0.47.0

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>;

package/bin/github/fingerprint.mjs

@@ -0,0 +1,67 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { PR_FINGERPRINT_QUERY } from "./queries.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { commentRevisions, mergePolicyFingerprint, rulesComplete, stackKey, suiteFingerprint, hasMultiCommentThreads, threadCommentRevisions, } from "./fingerprint-fields.mjs";
+function coreFingerprint(raw, counts, viewer) {
+    return {
+        headRefOid: raw.headRefOid,
+        updatedAt: raw.updatedAt ?? "",
+        state: raw.state,
+        isDraft: raw.isDraft,
+        mergeable: raw.mergeable,
+        mergeStateStatus: raw.mergeStateStatus,
+        reviewDecision: raw.reviewDecision,
+        isInMergeQueue: Boolean(raw.isInMergeQueue),
+        isMergeQueueEnabled: Boolean(raw.isMergeQueueEnabled),
+        mergePolicy: mergePolicyFingerprint(raw),
+        commentCount: raw.comments.totalCount ?? raw.comments.nodes.length,
+        commentRevisions: commentRevisions(raw.comments.nodes),
+        threadCount: raw.reviewThreads.totalCount ?? raw.reviewThreads.nodes.length,
+        reviewCount: counts.reviewCount,
+        reviewRevisions: counts.reviewRevisions,
+        latestCommentId: raw.comments.nodes.at(-1)?.id ?? null,
+        latestThreadId: raw.reviewThreads.nodes.at(-1)?.id ?? null,
+        latestReviewId: counts.latestReviewId,
+        checkRollupState: raw.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null,
+        ...suiteFingerprint(raw.commits.nodes[0]?.commit.checkSuites),
+        viewerCanUpdate: raw.viewerCanUpdate === true,
+        viewerPermission: viewer.permission,
+        viewerLogin: viewer.login,
+        stackKey: stackKey(raw),
+        threadCommentRevisions: threadCommentRevisions(raw.reviewThreads.nodes),
+        rulesComplete: rulesComplete(raw.baseRef),
+        hasMultiCommentThreads: hasMultiCommentThreads(raw.reviewThreads.nodes),
+    };
+}
+export function fingerprintFromRaw(raw, viewerPermission = null, viewerLogin = null) {
+    return coreFingerprint(raw, {
+        reviewCount: raw.allReviews?.totalCount ?? 0,
+        latestReviewId: raw.allReviews?.nodes?.at(-1)?.id ?? null,
+        reviewRevisions: commentRevisions(raw.allReviews?.nodes ?? []),
+    }, { permission: viewerPermission, login: viewerLogin });
+}
+export function fingerprintsEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export async function fetchPrFingerprint(pr, repo) {
+    const result = await graphqlWithRateLimit(PR_FINGERPRINT_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+    });
+    if (!result.data.repository) {
+        throw new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
+    }
+    const raw = result.data.repository.pullRequest;
+    if (!raw)
+        throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
+    return coreFingerprint(raw, {
+        reviewCount: raw.reviews.totalCount,
+        latestReviewId: raw.reviews.nodes.at(-1)?.id ?? null,
+        reviewRevisions: commentRevisions(raw.reviews.nodes),
+    }, {
+        permission: result.data.repository.viewerPermission,
+        login: result.data.viewer?.login ?? null,
+    });
+}

package/bin/github/gql/batch-pr.gql

@@ -9,12 +9,16 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
     resetAt
     used
   }
+  viewer {
+    login
+  }
   repository(owner: $owner, name: $repo) {
     viewerPermission
     viewerCanAdminister
     pullRequest(number: $pr) {
       id
       number
+      updatedAt
       state
       isDraft
       viewerDidAuthor
@@ -32,7 +36,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       }
       baseRefName
       isInMergeQueue
-      isMergeQueueEnabled
+      ...PrMergePolicy
       autoMergeRequest {
         enabledAt
         mergeMethod
@@ -49,7 +53,8 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           login
         }
         headCommit {
-          ...QueueCheckCommit
+          oid
+          committedDate
         }
       }
       mergeQueueAdditions: timelineItems(last: 1, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT]) {
@@ -68,7 +73,13 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
               login
             }
             beforeCommit {
-              ...QueueCheckCommit
+              oid
+              committedDate
+              parents(first: 100) {
+                nodes {
+                  oid
+                }
+              }
             }
           }
         }
@@ -81,49 +92,6 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       stackEntry {
         position
       }
-      baseRef {
-        branchProtectionRule {
-          requiresApprovingReviews
-          requiredApprovingReviewCount
-          requiresConversationResolution
-          requiresCodeOwnerReviews
-          requireLastPushApproval
-          requiresCommitSignatures
-          requiresLinearHistory
-          requiresStatusChecks
-          requiredStatusCheckContexts
-          requiresStrictStatusChecks
-          requiresDeployments
-          requiredDeploymentEnvironments
-        }
-        rules(first: 100) {
-          nodes {
-            type
-            parameters {
-              ... on PullRequestParameters {
-                requiredApprovingReviewCount
-                requiredReviewThreadResolution
-                requireCodeOwnerReview
-                requireLastPushApproval
-              }
-              ... on RequiredStatusChecksParameters {
-                strictRequiredStatusChecksPolicy
-                requiredStatusChecks {
-                  context
-                }
-              }
-              ... on RequiredDeploymentsParameters {
-                requiredDeploymentEnvironments
-              }
-              ... on CodeScanningParameters {
-                codeScanningTools {
-                  tool
-                }
-              }
-            }
-          }
-        }
-      }
       # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
       reviewRequests(last: 50) {
         nodes {
@@ -153,6 +121,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
         }
       }
       reviewThreads(last: 100) {
+        totalCount
         pageInfo {
           hasPreviousPage
           startCursor
@@ -189,11 +158,13 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
               line
               startLine
               createdAt
+              updatedAt
             }
           }
         }
       }
       comments(last: 100) {
+        totalCount
         pageInfo {
           hasPreviousPage
           startCursor
@@ -210,6 +181,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           }
           body
           createdAt
+          updatedAt
         }
       }
       changesRequestedReviews: reviews(states: CHANGES_REQUESTED, last: 50) {
@@ -249,8 +221,12 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           createdAt
         }
       }
-      allReviews: reviews(last: 1) {
+      allReviews: reviews(last: 100) {
         totalCount
+        nodes {
+          id
+          updatedAt
+        }
       }
       approvedReviews: reviews(states: APPROVED, last: 50) {
         pageInfo {
@@ -276,23 +252,9 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           commit {
             oid
             committedDate
-            checkSuites(first: 50) {
-              pageInfo {
-                hasNextPage
-              }
-              nodes {
-                conclusion
-                workflowRun {
-                  databaseId
-                  event
-                  url
-                  workflow {
-                    name
-                  }
-                }
-              }
-            }
+            ...CommitCheckSuites
             statusCheckRollup {
+              state
               contexts(first: 100) {
                 pageInfo {
                   hasNextPage
@@ -345,60 +307,3 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
     }
   }
 }
-
-fragment QueueCheckCommit on Commit {
-  oid
-  committedDate
-  parents(first: 100) {
-    nodes {
-      oid
-    }
-  }
-  statusCheckRollup {
-    contexts(first: 100) {
-      pageInfo {
-        hasNextPage
-        endCursor
-      }
-      nodes {
-        __typename
-        ... on CheckRun {
-          id
-          name
-          status
-          conclusion
-          detailsUrl
-          completedAt
-          startedAt
-          title
-          summary
-          annotations(first: 1) {
-            nodes {
-              message
-            }
-          }
-          checkSuite {
-            createdAt
-            updatedAt
-            workflowRun {
-              event
-              createdAt
-              updatedAt
-              workflow {
-                name
-                databaseId
-              }
-            }
-          }
-        }
-        ... on StatusContext {
-          context
-          state
-          createdAt
-          targetUrl
-          description
-        }
-      }
-    }
-  }
-}

package/bin/github/gql/commit-check-suites.gql

@@ -0,0 +1,19 @@
+fragment CommitCheckSuites on Commit {
+  checkSuites(first: 50) {
+    pageInfo {
+      hasNextPage
+    }
+    nodes {
+      id
+      conclusion
+      workflowRun {
+        databaseId
+        event
+        url
+        workflow {
+          name
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/pr-fingerprint.gql

@@ -0,0 +1,75 @@
+# Cheap preflight. Cost is 1. Used to skip BatchPr when GitHub state is unchanged.
+query PrFingerprint($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  viewer {
+    login
+  }
+  repository(owner: $owner, name: $repo) {
+    viewerPermission
+    pullRequest(number: $pr) {
+      updatedAt
+      state
+      isDraft
+      viewerCanUpdate
+      headRefOid
+      mergeable
+      mergeStateStatus
+      reviewDecision
+      isInMergeQueue
+      stack {
+        number
+        size
+        baseRefName
+      }
+      stackEntry {
+        position
+      }
+      ...PrMergePolicy
+      comments(last: 100) {
+        totalCount
+        nodes {
+          id
+          updatedAt
+        }
+      }
+      reviewThreads(last: 20) {
+        totalCount
+        nodes {
+          id
+          comments(last: 1) {
+            totalCount
+            nodes {
+              id
+              updatedAt
+            }
+          }
+        }
+      }
+      reviews(last: 100) {
+        totalCount
+        nodes {
+          id
+          updatedAt
+        }
+      }
+      commits(last: 1) {
+        nodes {
+          commit {
+            oid
+            statusCheckRollup {
+              state
+            }
+            ...CommitCheckSuites
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/pr-merge-policy.gql

@@ -0,0 +1,49 @@
+fragment PrMergePolicy on PullRequest {
+  isMergeQueueEnabled
+  baseRef {
+    branchProtectionRule {
+      requiresApprovingReviews
+      requiredApprovingReviewCount
+      requiresConversationResolution
+      requiresCodeOwnerReviews
+      requireLastPushApproval
+      requiresCommitSignatures
+      requiresLinearHistory
+      requiresStatusChecks
+      requiredStatusCheckContexts
+      requiresStrictStatusChecks
+      requiresDeployments
+      requiredDeploymentEnvironments
+    }
+    rules(first: 100) {
+      pageInfo {
+        hasNextPage
+      }
+      nodes {
+        type
+        parameters {
+          ... on PullRequestParameters {
+            requiredApprovingReviewCount
+            requiredReviewThreadResolution
+            requireCodeOwnerReview
+            requireLastPushApproval
+          }
+          ... on RequiredStatusChecksParameters {
+            strictRequiredStatusChecksPolicy
+            requiredStatusChecks {
+              context
+            }
+          }
+          ... on RequiredDeploymentsParameters {
+            requiredDeploymentEnvironments
+          }
+          ... on CodeScanningParameters {
+            codeScanningTools {
+              tool
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/merge-queue-checks.mjs

@@ -1,46 +1,73 @@
 import { graphql } from "./client.mjs";
 import { requireContextNodes } from "./batch-response.mjs";
 import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
-async function hydrateCommitContexts(commit, repo) {
-    const contexts = commit.statusCheckRollup?.contexts;
-    if (!contexts)
-        return;
-    contexts.nodes = requireContextNodes(contexts.nodes);
-    if (contexts.pageInfo.hasNextPage && !contexts.pageInfo.endCursor) {
-        throw new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${commit.oid}. Retry.`);
+function omittedCursorError(oid) {
+    return new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${oid}. Retry.`);
+}
+function nextPageCursor(contexts, oid) {
+    if (!contexts.pageInfo.hasNextPage)
+        return undefined;
+    if (!contexts.pageInfo.endCursor)
+        throw omittedCursorError(oid);
+    return contexts.pageInfo.endCursor;
+}
+function initialQueueCursor(existing, oid) {
+    if (!existing)
+        return null;
+    return nextPageCursor(existing, oid);
+}
+async function fetchQueuePage(oid, repo, cursor) {
+    const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        oid,
+        ...(cursor !== null && { cursor }),
+    });
+    const object = result.data.repository?.object;
+    if (object?.__typename !== "Commit" || object.oid !== oid) {
+        if (cursor === null)
+            return null;
+        throw new Error(`Merge queue check pagination interrupted: commit ${oid} disappeared or changed. Retry.`);
     }
-    let cursor = contexts.pageInfo.hasNextPage ? contexts.pageInfo.endCursor : null;
-    while (cursor) {
+    return object.statusCheckRollup?.contexts ?? null;
+}
+async function hydrateCommitContexts(commit, repo) {
+    const existing = commit.statusCheckRollup?.contexts;
+    const nodes = existing ? [...requireContextNodes(existing.nodes)] : [];
+    let cursor = initialQueueCursor(existing, commit.oid);
+    while (cursor !== undefined) {
         // eslint-disable-next-line no-await-in-loop
-        const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
-            owner: repo.owner,
-            repo: repo.name,
-            oid: commit.oid,
-            cursor,
-        });
-        const object = result.data.repository?.object;
-        if (object?.__typename !== "Commit" || object.oid !== commit.oid) {
-            throw new Error(`Merge queue check pagination interrupted: commit ${commit.oid} disappeared or changed. Retry.`);
-        }
-        const next = object.statusCheckRollup?.contexts;
+        const next = await fetchQueuePage(commit.oid, repo, cursor);
         if (!next) {
+            if (cursor === null) {
+                cursor = undefined;
+                continue;
+            }
             throw new Error(`Merge queue check pagination interrupted: statusCheckRollup disappeared for ${commit.oid}. Retry.`);
         }
-        contexts.nodes.push(...requireContextNodes(next.nodes));
-        contexts.pageInfo = next.pageInfo;
-        cursor = next.pageInfo.hasNextPage ? next.pageInfo.endCursor : null;
-        if (next.pageInfo.hasNextPage && !cursor) {
-            throw new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${commit.oid}. Retry.`);
-        }
+        nodes.push(...requireContextNodes(next.nodes));
+        cursor = nextPageCursor(next, commit.oid);
     }
+    commit.statusCheckRollup = {
+        contexts: { pageInfo: { hasNextPage: false, endCursor: null }, nodes },
+    };
+}
+function currentRemovalCommit(raw) {
+    const removal = raw.mergeQueueRemovals?.nodes[0];
+    const addition = raw.mergeQueueAdditions?.nodes[0];
+    if (!removal?.beforeCommit)
+        return undefined;
+    if (addition && Date.parse(removal.createdAt) < Date.parse(addition.createdAt))
+        return undefined;
+    const parentOids = removal.beforeCommit.parents?.nodes.map((node) => node.oid);
+    if (!parentOids?.includes(raw.headRefOid))
+        return undefined;
+    return removal.beforeCommit;
 }
 /** Hydrate all status contexts for the active or most recently removed queue commit. */
 export async function hydrateMergeQueueChecks(raw, repo) {
     const active = raw.mergeQueueEntry?.headCommit;
-    const removal = raw.mergeQueueRemovals?.nodes[0];
-    const addition = raw.mergeQueueAdditions?.nodes[0];
-    const removalIsCurrent = Boolean(removal && (!addition || Date.parse(removal.createdAt) >= Date.parse(addition.createdAt)));
-    const removed = removalIsCurrent ? removal?.beforeCommit : undefined;
+    const removed = currentRemovalCommit(raw);
     if (active)
         await hydrateCommitContexts(active, repo);
     if (removed && removed.oid !== active?.oid)

package/bin/github/queries.d.mts

@@ -10,6 +10,8 @@
 export declare const BATCH_PR_QUERY: string;
 /** Slim @include follow-up for outstanding batch-query connections. */
 export declare const BATCH_PR_PAGE_QUERY: string;
+/** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
+export declare const PR_FINGERPRINT_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */