pr-shepherd 0.35.0 → 0.37.0

package/bin/github/batch.mjs

@@ -1,134 +1,28 @@
-import { graphql, graphqlWithRateLimit } from "./client.mjs";
-import { paginateForward, paginateBackward } from "./pagination.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
 import { hydrateThreadCommentPages } from "./thread-comments.mjs";
 import { BATCH_PR_QUERY } from "./queries.mjs";
 import { parseRawPr } from "./batch-parsers.mjs";
-import { requireContextNodes, requireRawPr } from "./batch-response.mjs";
+import { parseCheckSuitesComplete, parseSuiteStartupFailures } from "./batch-parse-suites.mjs";
+import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
+import { paginateBatchConnections } from "./batch-page.mjs";
+import { requireRawPr } from "./batch-response.mjs";
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
 export async function fetchPrBatch(pr, repo, opts = {}) {
-    // First page: no cursor variables.
     const result = await graphqlWithRateLimit(BATCH_PR_QUERY, {
         owner: repo.owner,
         repo: repo.name,
         pr,
     });
     const raw = requireRawPr(result.data, pr, repo);
-    // Paginate reviewThreads backward if the first page is incomplete.
-    let rawThreadPages = raw.reviewThreads.nodes;
-    if (raw.reviewThreads.pageInfo.hasPreviousPage && raw.reviewThreads.pageInfo.startCursor) {
-        // Pass startCursor so paginateBackward fetches pages *before* the already-
-        // fetched first page instead of re-fetching it from the start.
-        const extra = await paginateBackward(async (cursor) => {
-            const res = await graphql(BATCH_PR_QUERY, {
-                owner: repo.owner,
-                repo: repo.name,
-                pr,
-                ...(cursor ? { threadsCursor: cursor } : {}),
-            });
-            const pr2 = requireRawPr(res.data, pr, repo);
-            return pr2.reviewThreads;
-        }, raw.reviewThreads.pageInfo.startCursor);
-        // extra contains pages before the first page.
-        rawThreadPages = [...extra, ...rawThreadPages];
-    }
-    rawThreadPages = await hydrateThreadCommentPages(rawThreadPages);
-    // Paginate comments backward if the first page is incomplete.
-    let rawCommentNodes = raw.comments.nodes;
-    if (raw.comments.pageInfo.hasPreviousPage && raw.comments.pageInfo.startCursor) {
-        const extra = await paginateBackward(async (cursor) => {
-            const res = await graphql(BATCH_PR_QUERY, {
-                owner: repo.owner,
-                repo: repo.name,
-                pr,
-                ...(cursor ? { commentsCursor: cursor } : {}),
-            });
-            const pr2 = requireRawPr(res.data, pr, repo);
-            return pr2.comments;
-        }, raw.comments.pageInfo.startCursor);
-        rawCommentNodes = [...extra, ...rawCommentNodes];
-    }
-    // Paginate CHANGES_REQUESTED reviews backward if the first page is incomplete.
-    let rawReviewNodes = raw.changesRequestedReviews.nodes;
-    if (raw.changesRequestedReviews.pageInfo.hasPreviousPage &&
-        raw.changesRequestedReviews.pageInfo.startCursor) {
-        const extra = await paginateBackward(async (cursor) => {
-            const res = await graphql(BATCH_PR_QUERY, {
-                owner: repo.owner,
-                repo: repo.name,
-                pr,
-                ...(cursor ? { changesRequestedCursor: cursor } : {}),
-            });
-            const pr2 = requireRawPr(res.data, pr, repo);
-            return pr2.changesRequestedReviews;
-        }, raw.changesRequestedReviews.pageInfo.startCursor);
-        rawReviewNodes = [...extra, ...rawReviewNodes];
-    }
-    // Paginate COMMENTED review summaries backward if the first page is incomplete.
-    let rawReviewSummaryNodes = raw.reviewSummaries.nodes;
-    if (raw.reviewSummaries.pageInfo.hasPreviousPage && raw.reviewSummaries.pageInfo.startCursor) {
-        const extra = await paginateBackward(async (cursor) => {
-            const res = await graphql(BATCH_PR_QUERY, {
-                owner: repo.owner,
-                repo: repo.name,
-                pr,
-                ...(cursor ? { reviewSummariesCursor: cursor } : {}),
-            });
-            const pr2 = requireRawPr(res.data, pr, repo);
-            return pr2.reviewSummaries;
-        }, raw.reviewSummaries.pageInfo.startCursor);
-        rawReviewSummaryNodes = [...extra, ...rawReviewSummaryNodes];
-    }
-    // Paginate APPROVED reviews backward if the first page is incomplete — gated behind
-    // `paginateApprovedReviews` because approvals minimization is opt-in. See FetchPrBatchOptions.
-    let rawApprovedReviewNodes = raw.approvedReviews.nodes;
-    if (opts.paginateApprovedReviews &&
-        raw.approvedReviews.pageInfo.hasPreviousPage &&
-        raw.approvedReviews.pageInfo.startCursor) {
-        const extra = await paginateBackward(async (cursor) => {
-            const res = await graphql(BATCH_PR_QUERY, {
-                owner: repo.owner,
-                repo: repo.name,
-                pr,
-                ...(cursor ? { approvedReviewsCursor: cursor } : {}),
-            });
-            const pr2 = requireRawPr(res.data, pr, repo);
-            return pr2.approvedReviews;
-        }, raw.approvedReviews.pageInfo.startCursor);
-        rawApprovedReviewNodes = [...extra, ...rawApprovedReviewNodes];
-    }
-    // Paginate check contexts forward if the first page is incomplete.
-    let rawCheckNodes = requireContextNodes(raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? []);
-    const checksPageInfo = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.pageInfo;
-    const firstOid = raw.commits.nodes[0]?.commit.oid;
-    if (checksPageInfo?.hasNextPage && checksPageInfo.endCursor) {
-        // Pass endCursor so paginateForward fetches pages *after* the already-
-        // fetched first page instead of re-fetching it from the start.
-        let pageCount = 0;
-        const extra = await paginateForward(async (cursor) => {
-            const res = await graphql(BATCH_PR_QUERY, {
-                owner: repo.owner,
-                repo: repo.name,
-                pr,
-                ...(cursor ? { checksCursor: cursor } : {}),
-            });
-            const pr2 = requireRawPr(res.data, pr, repo);
-            if (!pr2?.commits.nodes[0]?.commit.statusCheckRollup) {
-                throw new Error(`Check-context pagination interrupted: statusCheckRollup disappeared on page ${pageCount + 2} (possible force-push race). Retry after the push stabilizes.`);
-            }
-            const currentOid = pr2.commits.nodes[0]?.commit.oid;
-            if (firstOid !== undefined && currentOid !== undefined && currentOid !== firstOid) {
-                throw new Error(`Check-context pagination interrupted: head commit changed from ${firstOid} to ${currentOid} between pages (force-push race). Retry.`);
-            }
-            pageCount++;
-            const ctxs = pr2.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
-            if (!ctxs)
-                return { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
-            return { ...ctxs, nodes: requireContextNodes(ctxs.nodes) };
-        }, checksPageInfo.endCursor);
-        rawCheckNodes = [...rawCheckNodes, ...extra];
-    }
-    const data = parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes);
-    return { data, rateLimit: result.rateLimit };
+    const paged = await paginateBatchConnections(pr, repo, raw, opts, result.rateLimit);
+    const rawThreadPages = await hydrateThreadCommentPages(paged.threads);
+    const data = parseRawPr(raw, rawThreadPages, paged.comments, paged.changesRequested, paged.reviewSummaries, paged.approvedReviews, paged.checks);
+    data.checks = mergeStartupFailureChecks(data.checks, parseSuiteStartupFailures(raw));
+    return {
+        data,
+        rateLimit: paged.rateLimit ?? result.rateLimit,
+        ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
+    };
 }

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

@@ -0,0 +1,194 @@
+# Follow-up pages only — skipped connections are omitted via @include so extra
+# pages do not re-pay the full batch-pr.gql node cost. Outstanding cursors are
+# sent together in one request.
+query BatchPrPage(
+  $owner: String!
+  $repo: String!
+  $pr: Int!
+  $includeThreads: Boolean!
+  $threadsCursor: String
+  $includeComments: Boolean!
+  $commentsCursor: String
+  $includeChangesRequested: Boolean!
+  $changesRequestedCursor: String
+  $includeReviewSummaries: Boolean!
+  $reviewSummariesCursor: String
+  $includeApprovedReviews: Boolean!
+  $approvedReviewsCursor: String
+  $includeChecks: Boolean!
+  $checksCursor: String
+) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      reviewThreads(last: 100, before: $threadsCursor) @include(if: $includeThreads) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isResolved
+          isOutdated
+          path
+          line
+          startLine
+          comments(first: 100) {
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+            nodes {
+              id
+              isMinimized
+              url
+              authorAssociation
+              author {
+                __typename
+                login
+              }
+              pullRequestReview {
+                id
+              }
+              body
+              path
+              line
+              startLine
+              createdAt
+            }
+          }
+        }
+      }
+      comments(last: 100, before: $commentsCursor) @include(if: $includeComments) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isMinimized
+          url
+          authorAssociation
+          author {
+            __typename
+            login
+          }
+          body
+          createdAt
+        }
+      }
+      changesRequestedReviews: reviews(
+        states: CHANGES_REQUESTED
+        last: 50
+        before: $changesRequestedCursor
+      ) @include(if: $includeChangesRequested) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          authorAssociation
+          author {
+            __typename
+            login
+          }
+          body
+          createdAt
+          commit {
+            oid
+          }
+        }
+      }
+      reviewSummaries: reviews(states: COMMENTED, last: 50, before: $reviewSummariesCursor)
+        @include(if: $includeReviewSummaries) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isMinimized
+          authorAssociation
+          author {
+            __typename
+            login
+          }
+          body
+          createdAt
+        }
+      }
+      approvedReviews: reviews(states: APPROVED, last: 50, before: $approvedReviewsCursor)
+        @include(if: $includeApprovedReviews) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isMinimized
+          authorAssociation
+          author {
+            __typename
+            login
+          }
+          body
+          createdAt
+        }
+      }
+      commits(last: 1) @include(if: $includeChecks) {
+        nodes {
+          commit {
+            oid
+            statusCheckRollup {
+              contexts(first: 100, after: $checksCursor) {
+                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/batch-pr.gql

@@ -1,14 +1,6 @@
-query BatchPr(
-  $owner: String!
-  $repo: String!
-  $pr: Int!
-  $threadsCursor: String
-  $checksCursor: String
-  $commentsCursor: String
-  $changesRequestedCursor: String
-  $reviewSummariesCursor: String
-  $approvedReviewsCursor: String
-) {
+# First page only. Extra pages use batch-pr-page.gql so follow-ups do not
+# re-select every connection (GraphQL points scale with possible nodes).
+query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       id
@@ -24,13 +16,62 @@ query BatchPr(
         nameWithOwner
       }
       baseRefName
+      isInMergeQueue
+      isMergeQueueEnabled
+      mergeQueueEntry {
+        position
+        state
+        estimatedTimeToMerge
+      }
+      stack {
+        number
+        size
+        baseRefName
+      }
+      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.
@@ -61,7 +102,7 @@ query BatchPr(
           state
         }
       }
-      reviewThreads(last: 100, before: $threadsCursor) {
+      reviewThreads(last: 100) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -99,7 +140,7 @@ query BatchPr(
           }
         }
       }
-      comments(last: 100, before: $commentsCursor) {
+      comments(last: 100) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -117,11 +158,7 @@ query BatchPr(
           createdAt
         }
       }
-      changesRequestedReviews: reviews(
-        states: CHANGES_REQUESTED
-        last: 50
-        before: $changesRequestedCursor
-      ) {
+      changesRequestedReviews: reviews(states: CHANGES_REQUESTED, last: 50) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -140,7 +177,7 @@ query BatchPr(
           }
         }
       }
-      reviewSummaries: reviews(states: COMMENTED, last: 50, before: $reviewSummariesCursor) {
+      reviewSummaries: reviews(states: COMMENTED, last: 50) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -160,7 +197,7 @@ query BatchPr(
       allReviews: reviews(last: 1) {
         totalCount
       }
-      approvedReviews: reviews(states: APPROVED, last: 50, before: $approvedReviewsCursor) {
+      approvedReviews: reviews(states: APPROVED, last: 50) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -183,8 +220,24 @@ query BatchPr(
           commit {
             oid
             committedDate
+            checkSuites(first: 50) {
+              pageInfo {
+                hasNextPage
+              }
+              nodes {
+                conclusion
+                workflowRun {
+                  databaseId
+                  event
+                  url
+                  workflow {
+                    name
+                  }
+                }
+              }
+            }
             statusCheckRollup {
-              contexts(first: 100, after: $checksCursor) {
+              contexts(first: 100) {
                 pageInfo {
                   hasNextPage
                   endCursor
@@ -201,6 +254,11 @@ query BatchPr(
                     startedAt
                     title
                     summary
+                    annotations(first: 1) {
+                      nodes {
+                        message
+                      }
+                    }
                     checkSuite {
                       createdAt
                       updatedAt

package/bin/github/gql/commit-suggestion-thread.gql

@@ -0,0 +1,40 @@
+query CommitSuggestionThread($owner: String!, $repo: String!, $pr: Int!, $threadId: ID!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      headRefOid
+      headRefName
+      headRepository {
+        nameWithOwner
+      }
+    }
+  }
+  node(id: $threadId) {
+    ... on PullRequestReviewThread {
+      id
+      isResolved
+      isOutdated
+      path
+      line
+      startLine
+      pullRequest {
+        number
+      }
+      comments(first: 1) {
+        nodes {
+          isMinimized
+          url
+          authorAssociation
+          author {
+            __typename
+            login
+          }
+          body
+          path
+          line
+          startLine
+          createdAt
+        }
+      }
+    }
+  }
+}

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