pr-shepherd 0.2.0

package/src/github/batch.mts

@@ -0,0 +1,351 @@
+/**
+ * Executes the primary batch GraphQL query and parses the raw GitHub response
+ * into shepherd's typed `BatchPrData` shape.
+ *
+ * The batch query fetches CI checks + review threads + PR comments + merge
+ * status in a single network round-trip, drastically reducing API call counts
+ * compared to the previous per-agent approach.
+ */
+
+import { graphql, graphqlWithRateLimit, type RateLimitInfo, type RepoInfo } from "./client.mts";
+import { paginateForward, paginateBackward } from "./pagination.mts";
+import { BATCH_PR_QUERY } from "./queries.mts";
+import type {
+  BatchPrData,
+  CheckConclusion,
+  CheckRun,
+  CheckStatus,
+  PrComment,
+  Review,
+  ReviewThread,
+} from "../types.mts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface BatchResult {
+  data: BatchPrData;
+  rateLimit?: RateLimitInfo;
+}
+
+/**
+ * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
+ */
+export async function fetchPrBatch(pr: number, repo: RepoInfo): Promise<BatchResult> {
+  // First page: no cursor variables.
+  const result = await graphqlWithRateLimit<RawBatchResponse>(BATCH_PR_QUERY, {
+    owner: repo.owner,
+    repo: repo.name,
+    pr,
+  });
+
+  const raw = result.data.repository.pullRequest;
+  if (!raw) {
+    throw new Error(`PR #${pr} not found`);
+  }
+
+  // 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<RawThread>(async (cursor) => {
+      const res = await graphql<RawBatchResponse>(BATCH_PR_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+        ...(cursor ? { threadsCursor: cursor } : {}),
+      });
+      const pr2 = res.data.repository.pullRequest;
+      if (!pr2) throw new Error(`PR #${pr} not found`);
+      return pr2.reviewThreads;
+    }, raw.reviewThreads.pageInfo.startCursor);
+    // extra contains pages before the first page.
+    rawThreadPages = [...extra, ...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<RawComment>(async (cursor) => {
+      const res = await graphql<RawBatchResponse>(BATCH_PR_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+        ...(cursor ? { commentsCursor: cursor } : {}),
+      });
+      const pr2 = res.data.repository.pullRequest;
+      if (!pr2) throw new Error(`PR #${pr} not found`);
+      return pr2.comments;
+    }, raw.comments.pageInfo.startCursor);
+    rawCommentNodes = [...extra, ...rawCommentNodes];
+  }
+
+  // Paginate reviews backward if the first page is incomplete.
+  let rawReviewNodes = raw.reviews.nodes;
+  if (raw.reviews.pageInfo.hasPreviousPage && raw.reviews.pageInfo.startCursor) {
+    const extra = await paginateBackward<RawReview>(async (cursor) => {
+      const res = await graphql<RawBatchResponse>(BATCH_PR_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+        ...(cursor ? { reviewsCursor: cursor } : {}),
+      });
+      const pr2 = res.data.repository.pullRequest;
+      if (!pr2) throw new Error(`PR #${pr} not found`);
+      return pr2.reviews;
+    }, raw.reviews.pageInfo.startCursor);
+    rawReviewNodes = [...extra, ...rawReviewNodes];
+  }
+
+  // Paginate check contexts forward if the first page is incomplete.
+  let rawCheckNodes = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? [];
+  const checksPageInfo = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.pageInfo;
+  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.
+    const extra = await paginateForward<RawContextNode>(async (cursor) => {
+      const res = await graphql<RawBatchResponse>(BATCH_PR_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+        ...(cursor ? { checksCursor: cursor } : {}),
+      });
+      const pr2 = res.data.repository.pullRequest;
+      const ctxs = pr2?.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
+      return ctxs ?? { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+    }, checksPageInfo.endCursor);
+    rawCheckNodes = [...rawCheckNodes, ...extra];
+  }
+
+  const data = parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawCheckNodes);
+  return { data, rateLimit: result.rateLimit };
+}
+
+// ---------------------------------------------------------------------------
+// Parsers
+// ---------------------------------------------------------------------------
+
+function parseRawPr(
+  raw: RawPr,
+  rawThreadPages: RawThread[],
+  rawCommentNodes: RawComment[],
+  rawReviewNodes: RawReview[],
+  rawCheckNodes: RawContextNode[],
+): BatchPrData {
+  const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
+    const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
+    return login ? [{ login }] : [];
+  });
+
+  const latestReviews = (raw.latestReviews?.nodes ?? []).map((n) => ({
+    login: n.author?.login ?? "unknown",
+    state: n.state,
+  }));
+
+  const reviewThreads: ReviewThread[] = rawThreadPages.map((t) => {
+    const comment = t.comments.nodes[0];
+    return {
+      id: t.id,
+      isResolved: t.isResolved,
+      isOutdated: t.isOutdated,
+      path: comment?.path ?? null,
+      line: comment?.line ?? null,
+      author: comment?.author?.login ?? "unknown",
+      body: comment?.body ?? "",
+      createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
+    };
+  });
+
+  const comments: PrComment[] = rawCommentNodes.map((c) => ({
+    id: c.id,
+    isMinimized: c.isMinimized,
+    author: c.author?.login ?? "unknown",
+    body: c.body,
+    createdAtUnix: parseCreatedAt(c.createdAt),
+  }));
+
+  const changesRequestedReviews: Review[] = rawReviewNodes.map((r) => ({
+    id: r.id,
+    author: r.author?.login ?? "unknown",
+    body: r.body,
+  }));
+
+  const checks: CheckRun[] = rawCheckNodes.flatMap((node) => {
+    if (node.__typename === "CheckRun") {
+      const event = node.checkSuite?.workflowRun?.event ?? null;
+      const runId = extractRunId(node.detailsUrl);
+      return [
+        {
+          name: node.name,
+          status: node.status as CheckRun["status"],
+          conclusion: node.conclusion as CheckRun["conclusion"],
+          detailsUrl: node.detailsUrl ?? "",
+          event,
+          runId,
+        },
+      ];
+    }
+    if (node.__typename === "StatusContext") {
+      const { status, conclusion } = mapStatusContextState(node.state);
+      return [
+        {
+          name: node.context,
+          status,
+          conclusion,
+          detailsUrl: node.targetUrl ?? "",
+          event: null,
+          runId: null,
+        },
+      ];
+    }
+    return [];
+  });
+
+  return {
+    number: raw.number,
+    state: raw.state as BatchPrData["state"],
+    isDraft: raw.isDraft,
+    mergeable: raw.mergeable as BatchPrData["mergeable"],
+    mergeStateStatus: raw.mergeStateStatus as BatchPrData["mergeStateStatus"],
+    reviewDecision: (raw.reviewDecision ?? null) as BatchPrData["reviewDecision"],
+    headRefOid: raw.headRefOid,
+    reviewRequests,
+    latestReviews,
+    reviewThreads,
+    comments,
+    changesRequestedReviews,
+    checks,
+  };
+}
+
+function parseCreatedAt(iso: string): number {
+  const ms = new Date(iso).getTime();
+  return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+
+function extractRunId(url: string | undefined | null): string | null {
+  if (!url) return null;
+  const m = /\/runs\/(\d+)/.exec(url);
+  return m ? (m[1] ?? null) : null;
+}
+
+/** Maps a GitHub commit status `state` to CheckRun-compatible status + conclusion. */
+function mapStatusContextState(state: string): {
+  status: CheckStatus;
+  conclusion: CheckConclusion;
+} {
+  switch (state) {
+    case "SUCCESS":
+      return { status: "COMPLETED", conclusion: "SUCCESS" };
+    case "FAILURE":
+    case "ERROR":
+      return { status: "COMPLETED", conclusion: "FAILURE" };
+    case "PENDING":
+    case "EXPECTED":
+    default:
+      return { status: "IN_PROGRESS", conclusion: null };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Raw GraphQL response types (private to this module)
+// ---------------------------------------------------------------------------
+
+interface RawBatchResponse {
+  repository: {
+    pullRequest: RawPr | null;
+  };
+}
+
+interface RawPr {
+  number: number;
+  state: string;
+  isDraft: boolean;
+  mergeable: string;
+  mergeStateStatus: string;
+  reviewDecision: string | null;
+  headRefOid: string;
+  reviewRequests: {
+    nodes: Array<{
+      requestedReviewer: { login?: string; name?: string } | null;
+    }>;
+  };
+  latestReviews: {
+    nodes: Array<{
+      author: { login: string } | null;
+      state: string;
+    }>;
+  };
+  reviewThreads: {
+    pageInfo: { hasPreviousPage: boolean; startCursor: string | null };
+    nodes: RawThread[];
+  };
+  comments: {
+    pageInfo: { hasPreviousPage: boolean; startCursor: string | null };
+    nodes: RawComment[];
+  };
+  reviews: {
+    pageInfo: { hasPreviousPage: boolean; startCursor: string | null };
+    nodes: RawReview[];
+  };
+  commits: {
+    nodes: Array<{
+      commit: {
+        statusCheckRollup: {
+          contexts: {
+            pageInfo: { hasNextPage: boolean; endCursor: string | null };
+            nodes: RawContextNode[];
+          };
+        } | null;
+      };
+    }>;
+  };
+}
+
+interface RawThread {
+  id: string;
+  isResolved: boolean;
+  isOutdated: boolean;
+  comments: {
+    nodes: Array<{
+      id: string;
+      author: { login: string } | null;
+      body: string;
+      path: string | null;
+      line: number | null;
+      createdAt: string;
+    }>;
+  };
+}
+
+interface RawComment {
+  id: string;
+  isMinimized: boolean;
+  author: { login: string } | null;
+  body: string;
+  createdAt: string;
+}
+
+interface RawReview {
+  id: string;
+  author: { login: string } | null;
+  body: string;
+}
+
+type RawContextNode =
+  | {
+      __typename: "CheckRun";
+      name: string;
+      status: string;
+      conclusion: string | null;
+      detailsUrl: string | null;
+      checkSuite: { workflowRun: { event: string } | null } | null;
+    }
+  | {
+      __typename: "StatusContext";
+      context: string;
+      state: string;
+      targetUrl: string | null;
+    };

package/src/github/client.mts

@@ -0,0 +1,207 @@
+/**
+ * Thin wrapper around the `gh` CLI for GraphQL and REST calls.
+ */
+
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import type { MergeableState, MergeStateStatus } from "../types.mts";
+import { loadConfig } from "../config/load.mts";
+
+const execFile = promisify(execFileCb);
+
+export interface RateLimitInfo {
+  remaining: number;
+  limit: number;
+  resetAt: number;
+}
+
+export interface GraphQlResult<T = unknown> {
+  data: T;
+  rateLimit?: RateLimitInfo;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a GraphQL query via `gh api graphql`.
+ *
+ * @param query   The full GraphQL query/mutation string.
+ * @param vars    Key-value pairs forwarded as `-f key=value` or `-F key=value`.
+ *                Numeric values are passed with `-F`; everything else with `-f`.
+ */
+export async function graphql<T = unknown>(
+  query: string,
+  vars: Record<string, string | number | boolean> = {},
+): Promise<GraphQlResult<T>> {
+  const args = buildGraphqlArgs(query, vars);
+  const raw = await runGh(args);
+  const parsed = JSON.parse(raw) as { data: T; errors?: Array<{ message: string }> };
+
+  if (parsed.errors?.length) {
+    const messages = parsed.errors.map((e) => e.message).join("; ");
+    throw new Error(`GitHub GraphQL error: ${messages}`);
+  }
+
+  return { data: parsed.data };
+}
+
+/** Like {@link graphql} but also returns the `x-ratelimit-remaining` header. */
+export async function graphqlWithRateLimit<T = unknown>(
+  query: string,
+  vars: Record<string, string | number | boolean> = {},
+): Promise<GraphQlResult<T>> {
+  // --include must come after 'api' (it's a flag for `gh api`, not for `gh`).
+  const [api, ...extraArgs] = buildGraphqlArgs(query, vars);
+  const args = [api!, "--include", ...extraArgs];
+  const raw = await runGh(args);
+
+  // `gh api -i` prepends HTTP headers before the JSON body.
+  // Handle both CRLF (\r\n\r\n) and LF-only (\n\n) header separators.
+  const crlfEnd = raw.indexOf("\r\n\r\n");
+  const lfEnd = raw.indexOf("\n\n");
+  const headerEnd = crlfEnd >= 0 ? crlfEnd : lfEnd;
+  const headerSection = headerEnd >= 0 ? raw.slice(0, headerEnd) : "";
+  const body = headerEnd >= 0 ? raw.slice(headerEnd + (crlfEnd >= 0 ? 4 : 2)) : raw;
+
+  const remaining = parseHeaderNumber(headerSection, "x-ratelimit-remaining");
+  const limit = parseHeaderNumber(headerSection, "x-ratelimit-limit");
+  const resetAt = parseHeaderNumber(headerSection, "x-ratelimit-reset");
+
+  const parsed = JSON.parse(body) as { data: T; errors?: Array<{ message: string }> };
+
+  if (parsed.errors?.length) {
+    const messages = parsed.errors.map((e) => e.message).join("; ");
+    throw new Error(`GitHub GraphQL error: ${messages}`);
+  }
+
+  return {
+    data: parsed.data,
+    rateLimit:
+      remaining !== null && limit !== null && resetAt !== null
+        ? { remaining, limit, resetAt }
+        : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Repo / PR lookup helpers
+// ---------------------------------------------------------------------------
+
+export interface RepoInfo {
+  owner: string;
+  name: string;
+}
+
+/** Returns the current repo's owner and name from `gh repo view`. */
+export async function getRepoInfo(): Promise<RepoInfo> {
+  const raw = await runGh(["repo", "view", "--json", "owner,name"]);
+  const parsed = JSON.parse(raw) as { owner: { login: string }; name: string };
+  return { owner: parsed.owner.login, name: parsed.name };
+}
+
+/**
+ * Derives the PR number for the current HEAD branch.
+ * Returns null if no open PR is found.
+ */
+export async function getCurrentPrNumber(): Promise<number | null> {
+  try {
+    const branch = await getCurrentBranch();
+    // In detached HEAD state git returns "HEAD" — no branch name to look up.
+    if (branch === "HEAD") return null;
+    const raw = await runGh([
+      "pr",
+      "list",
+      "--head",
+      branch,
+      "--json",
+      "number",
+      "--jq",
+      ".[0].number",
+    ]);
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed === "null") return null;
+    return parseInt(trimmed, 10);
+  } catch {
+    return null;
+  }
+}
+
+async function getCurrentBranch(): Promise<string> {
+  await runGh(["--version"]); // warm up gh CLI before git call
+  // Use git directly for branch name — gh doesn't expose it.
+  const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+  return stdout.trim();
+}
+
+/** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
+export async function getPrHeadSha(pr: number, owner: string, name: string): Promise<string> {
+  const raw = await runGh(["api", `repos/${owner}/${name}/pulls/${pr}`, "--jq", ".head.sha"]);
+  return raw.trim();
+}
+
+/**
+ * Fetches `mergeable` and `mergeStateStatus` via the REST API (`gh pr view`).
+ *
+ * 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 async function getMergeableState(
+  pr: number,
+  owner: string,
+  repo: string,
+): Promise<{ mergeable: MergeableState; mergeStateStatus: MergeStateStatus }> {
+  const raw = await runGh([
+    "pr",
+    "view",
+    String(pr),
+    "--repo",
+    `${owner}/${repo}`,
+    "--json",
+    "mergeable,mergeStateStatus",
+  ]);
+  const parsed = JSON.parse(raw) as {
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+  };
+  return parsed;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function buildGraphqlArgs(
+  query: string,
+  vars: Record<string, string | number | boolean>,
+): string[] {
+  const args = ["api", "graphql", "-f", `query=${query}`];
+  for (const [k, v] of Object.entries(vars)) {
+    if (typeof v === "number" || typeof v === "boolean") {
+      args.push("-F", `${k}=${String(v)}`);
+    } else {
+      args.push("-f", `${k}=${v}`);
+    }
+  }
+  return args;
+}
+
+async function runGh(args: string[]): Promise<string> {
+  try {
+    const { stdout } = await execFile("gh", args, {
+      maxBuffer: loadConfig().execution.maxBufferMb * 1024 * 1024,
+    });
+    return stdout;
+  } catch (err) {
+    // Re-throw with a more useful message
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`gh ${args[0] ?? ""} failed: ${msg}`, { cause: err });
+  }
+}
+
+function parseHeaderNumber(headers: string, name: string): number | null {
+  const re = new RegExp(`^${name}:\\s*(\\d+)`, "im");
+  const m = re.exec(headers);
+  return m ? parseInt(m[1]!, 10) : null;
+}

package/src/github/client.test.mts

@@ -0,0 +1,19 @@
+/**
+ * Unit tests for shepherd/github/client.mts — pure helper logic.
+ * Uses vi.mock for execFile — lives in client.mock.test.mts.
+ * This file covers things that don't need mocking (e.g. argument builders).
+ */
+
+import { describe, it, expect } from "vitest";
+
+// Test that the module exports exist (smoke test — real calls require gh CLI).
+describe("client module", () => {
+  it("exports the expected functions", async () => {
+    const module = await import("./client.mts");
+    expect(typeof module.graphql).toBe("function");
+    expect(typeof module.getRepoInfo).toBe("function");
+    expect(typeof module.getCurrentPrNumber).toBe("function");
+    expect(typeof module.getPrHeadSha).toBe("function");
+    expect(typeof module.graphqlWithRateLimit).toBe("function");
+  });
+});

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

@@ -0,0 +1,130 @@
+query BatchPr(
+  $owner: String!
+  $repo: String!
+  $pr: Int!
+  $threadsCursor: String
+  $checksCursor: String
+  $commentsCursor: String
+  $reviewsCursor: String
+) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      number
+      state
+      isDraft
+      mergeable
+      mergeStateStatus
+      reviewDecision
+      headRefOid
+      # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
+      reviewRequests(last: 50) {
+        nodes {
+          requestedReviewer {
+            ... on Bot {
+              login
+            }
+            ... on User {
+              login
+            }
+            ... on Team {
+              name
+            }
+          }
+        }
+      }
+      latestReviews(last: 100) {
+        nodes {
+          author {
+            login
+          }
+          state
+        }
+      }
+      reviewThreads(last: 100, before: $threadsCursor) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isResolved
+          isOutdated
+          # first: 1 — we want the reviewer's original comment, not the latest reply.
+          comments(first: 1) {
+            nodes {
+              id
+              author {
+                login
+              }
+              body
+              path
+              line
+              createdAt
+            }
+          }
+        }
+      }
+      comments(last: 100, before: $commentsCursor) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isMinimized
+          author {
+            login
+          }
+          body
+          createdAt
+        }
+      }
+      reviews(states: CHANGES_REQUESTED, last: 50, before: $reviewsCursor) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          author {
+            login
+          }
+          body
+        }
+      }
+      commits(last: 1) {
+        nodes {
+          commit {
+            statusCheckRollup {
+              contexts(first: 100, after: $checksCursor) {
+                pageInfo {
+                  hasNextPage
+                  endCursor
+                }
+                nodes {
+                  __typename
+                  ... on CheckRun {
+                    name
+                    status
+                    conclusion
+                    detailsUrl
+                    checkSuite {
+                      workflowRun {
+                        event
+                      }
+                    }
+                  }
+                  ... on StatusContext {
+                    context
+                    state
+                    targetUrl
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}