pr-shepherd 0.34.0 → 0.36.0

package/bin/github/client.d.mts

@@ -0,0 +1,46 @@
+/**
+ * High-level GitHub client — wraps http.mts for application-level concerns.
+ *
+ * All GitHub I/O goes through native fetch (via http.mts); the `gh` CLI is no
+ * longer used for GitHub API calls, but may be invoked as an auth-token
+ * fallback via `gh auth token` when neither GH_TOKEN nor GITHUB_TOKEN is set.
+ */
+import type { MergeableState, MergeStateStatus } from "../types.mts";
+export type { RateLimitInfo } from "./http.mts";
+export { graphql, graphqlWithRateLimit } from "./http.mts";
+export interface RepoInfo {
+    owner: string;
+    name: string;
+}
+/**
+ * Returns the current repo's owner and name by parsing `git remote get-url origin`.
+ * Handles https://, git@, and ssh:// remote URL formats.
+ */
+export declare function getRepoInfo(): Promise<RepoInfo>;
+/**
+ * Derives the PR number for the current HEAD branch.
+ * Returns null if no open PR is found.
+ */
+export declare function getCurrentPrNumber(): Promise<number | null>;
+/** Returns the PR number for a given branch, or null if no open PR is found. */
+export declare function getPrNumberForBranch(branch: string, owner: string, repo: string): Promise<number | null>;
+/** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
+export declare function getPrHeadSha(pr: number, owner: string, name: string): Promise<string>;
+/** Fetches the node ID and body text for a PR. GitHub returns null body for empty bodies — coerced to "". */
+export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
+    nodeId: string;
+    body: string;
+}>;
+/** Overwrites the PR body. */
+export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
+/**
+ * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ *
+ * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
+ * a known GitHub quirk where GraphQL lags behind the REST layer.
+ */
+export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+}>;
+export declare function getCurrentBranch(): Promise<string>;

package/bin/github/client.mjs

@@ -9,6 +9,7 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { graphql as httpGraphql, rest } from "./http.mjs";
 import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY, GET_PR_BODY_QUERY, UPDATE_PR_BODY_MUTATION, } from "./queries.mjs";
+import { getExecutionCwd } from "../execution-context.mjs";
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly
@@ -19,7 +20,9 @@ export { graphql, graphqlWithRateLimit } from "./http.mjs";
  * Handles https://, git@, and ssh:// remote URL formats.
  */
 export async function getRepoInfo() {
-    const { stdout } = await execFile("git", ["remote", "get-url", "origin"]);
+    const { stdout } = await execFile("git", ["remote", "get-url", "origin"], {
+        cwd: getExecutionCwd(),
+    });
     const url = stdout.trim();
     return parseRemoteUrl(url);
 }
@@ -95,7 +98,9 @@ export async function getMergeableState(pr, owner, repo) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 export async function getCurrentBranch() {
-    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: getExecutionCwd(),
+    });
     return stdout.trim();
 }
 function parseRemoteUrl(url) {

package/bin/github/errors.d.mts

@@ -0,0 +1,25 @@
+import { ShepherdError } from "../exit-codes.mts";
+import type { RateLimitInfo } from "./http.mts";
+export interface GitHubGraphQlError {
+    message: string;
+    path?: unknown;
+}
+export declare class GitHubRequestError extends ShepherdError {
+    readonly status: number;
+    readonly rateLimit?: RateLimitInfo;
+    readonly retryAfterSeconds?: number;
+    readonly graphqlErrors?: GitHubGraphQlError[];
+    constructor(message: string, opts: {
+        status: number;
+        rateLimit?: RateLimitInfo;
+        retryAfterSeconds?: number;
+        graphqlErrors?: GitHubGraphQlError[];
+        /**
+         * Bypasses status-based classification entirely — for callers that already
+         * know the failure kind better than the HTTP status can express (e.g. a
+         * response that failed to parse at all, which is an internal failure, not
+         * an availability or permission problem).
+         */
+        exitCodeOverride?: number;
+    });
+}

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

@@ -0,0 +1,189 @@
+# 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
+                    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
@@ -82,6 +123,7 @@ query BatchPr(
               id
               isMinimized
               url
+              authorAssociation
               author {
                 __typename
                 login
@@ -98,7 +140,7 @@ query BatchPr(
           }
         }
       }
-      comments(last: 100, before: $commentsCursor) {
+      comments(last: 100) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -107,6 +149,7 @@ query BatchPr(
           id
           isMinimized
           url
+          authorAssociation
           author {
             __typename
             login
@@ -115,17 +158,14 @@ query BatchPr(
           createdAt
         }
       }
-      changesRequestedReviews: reviews(
-        states: CHANGES_REQUESTED
-        last: 50
-        before: $changesRequestedCursor
-      ) {
+      changesRequestedReviews: reviews(states: CHANGES_REQUESTED, last: 50) {
         pageInfo {
           hasPreviousPage
           startCursor
         }
         nodes {
           id
+          authorAssociation
           author {
             __typename
             login
@@ -137,7 +177,7 @@ query BatchPr(
           }
         }
       }
-      reviewSummaries: reviews(states: COMMENTED, last: 50, before: $reviewSummariesCursor) {
+      reviewSummaries: reviews(states: COMMENTED, last: 50) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -145,6 +185,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          authorAssociation
           author {
             __typename
             login
@@ -156,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
@@ -164,6 +205,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          authorAssociation
           author {
             __typename
             login
@@ -178,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

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/gql/review-thread-comments.gql

@@ -11,6 +11,7 @@ query ReviewThreadComments($threadId: ID!, $commentsCursor: String) {
           id
           isMinimized
           url
+          authorAssociation
           author {
             __typename
             login

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

@@ -0,0 +1,19 @@
+import { type GitHubGraphQlError } from "./errors.mts";
+import { type RateLimitInfo } from "./http-utils.mts";
+interface GraphQlResult<T = unknown> {
+    data: T;
+    rateLimit?: RateLimitInfo;
+    retryAfterSeconds?: number;
+    errors?: GitHubGraphQlError[];
+}
+export interface GraphQlRequestOptions {
+    /**
+     * Mutation batches use partial GraphQL data to preserve per-alias successes.
+     * Read paths must keep the strict default so incomplete snapshots never drive
+     * PR state transitions.
+     */
+    allowPartialData?: boolean;
+}
+export declare function graphql<T = unknown>(query: string, vars?: Record<string, unknown>, opts?: GraphQlRequestOptions): Promise<GraphQlResult<T>>;
+export declare function graphqlWithRateLimit<T = unknown>(query: string, vars?: Record<string, unknown>, opts?: GraphQlRequestOptions): Promise<GraphQlResult<T>>;
+export {};

package/bin/github/graphql-response.d.mts

@@ -0,0 +1,7 @@
+import { type GitHubGraphQlError } from "./errors.mts";
+import type { RateLimitInfo } from "./http-utils.mts";
+export declare function parseGraphQlPayload<T>(parsed: unknown, status: number, rateLimit: RateLimitInfo | null, retryAfterSeconds: number | undefined): {
+    data: T | null;
+    errors?: GitHubGraphQlError[];
+};
+export declare function formatGraphQlErrors(errors: GitHubGraphQlError[] | undefined): string;

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

@@ -0,0 +1,4 @@
+export declare function _resetTokenCache(): void;
+export declare function hasCachedToken(): boolean;
+export declare function clearTokenCache(): void;
+export declare function makeHeaders(): Promise<Record<string, string>>;

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

@@ -0,0 +1,7 @@
+type RetryLogFn = (status: number, durationMs: number) => void;
+export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn): Promise<{
+    res: Response;
+    attempt: number;
+    retryT0: number;
+}>;
+export {};

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

@@ -0,0 +1,11 @@
+export declare function isTransportError(err: unknown): boolean;
+export interface RateLimitInfo {
+    remaining: number;
+    limit: number;
+    resetAt: number;
+}
+export declare function sanitizeBody(body: string): string;
+export declare function redactToken(body: string): string;
+export declare function redactUrl(url: string): string;
+export declare function parseRateLimit(headers: Headers): RateLimitInfo | null;
+export declare function parseRetryAfter(headers: Headers): number | undefined;

package/bin/github/http.d.mts

@@ -0,0 +1,6 @@
+export { GitHubRequestError } from "./errors.mts";
+export { _resetTokenCache } from "./http-auth.mts";
+export { graphql, graphqlWithRateLimit } from "./graphql-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

@@ -0,0 +1,46 @@
+/**
+ * Generic GraphQL cursor-based paginator for shepherd.
+ *
+ * Both paginators accept a `fetchFn` instead of calling `graphql` directly,
+ * which makes them testable without any mocking — tests supply a pure function
+ * that returns pages of fake data.
+ *
+ * GitHub's GraphQL connections support two cursor directions:
+ *   - 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;
+    hasPreviousPage?: boolean;
+    endCursor?: string | null;
+    startCursor?: string | null;
+}
+export interface Connection<T> {
+    pageInfo: PageInfo;
+    nodes: T[];
+}
+/**
+ * Paginate forward through a GraphQL connection (`first` / `after` cursors).
+ *
+ * @param fetchFn       Called once per page. Receives the cursor (or null for
+ *                      the very first page) and returns a Connection<T>.
+ * @param initialCursor Start from this cursor instead of null. Pass the
+ *                      `endCursor` of an already-fetched page to fetch only
+ *                      the pages *after* it, avoiding a duplicate re-fetch.
+ */
+export declare function paginateForward<T>(fetchFn: (cursor: string | null) => Promise<Connection<T>>, initialCursor?: string | null): Promise<T[]>;
+/**
+ * Paginate backward through a GraphQL connection (`last` / `before` cursors).
+ *
+ * Used for `reviewThreads(last: 100, before: $before)`.
+ *
+ * @param fetchFn       Called once per page. Receives the cursor (or null for
+ *                      the very first page). Returns a Connection<T> with
+ *                      `hasPreviousPage` and `startCursor` in pageInfo.
+ * @param initialCursor Start from this cursor instead of null. Pass the
+ *                      `startCursor` of an already-fetched page to avoid
+ *                      re-fetching it (fetch only the pages *before* it).
+ */
+export declare function paginateBackward<T>(fetchFn: (cursor: string | null) => Promise<Connection<T>>, initialCursor?: string | null): Promise<T[]>;
+export {};

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).