pr-shepherd 0.2.0

package/src/github/gql/dismiss-review.gql

@@ -0,0 +1,7 @@
+mutation DismissReview($reviewId: ID!, $message: String!) {
+  dismissPullRequestReview(input: { pullRequestReviewId: $reviewId, message: $message }) {
+    pullRequestReview {
+      state
+    }
+  }
+}

package/src/github/gql/minimize-comment.gql

@@ -0,0 +1,7 @@
+mutation MinimizeComment($commentId: ID!, $classifier: ReportedContentClassifiers!) {
+  minimizeComment(input: { subjectId: $commentId, classifier: $classifier }) {
+    minimizedComment {
+      isMinimized
+    }
+  }
+}

package/src/github/gql/multi-pr-status-paged.gql

@@ -0,0 +1,31 @@
+query MultiPrStatusPaged($owner: String!, $repo: String!, $pr: Int!, $cursor: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      number
+      title
+      state
+      isDraft
+      mergeStateStatus
+      reviewDecision
+      reviewThreads(last: 100, before: $cursor) {
+        totalCount
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          isResolved
+        }
+      }
+      commits(last: 1) {
+        nodes {
+          commit {
+            statusCheckRollup {
+              state
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/github/gql/multi-pr-status.gql

@@ -0,0 +1,32 @@
+query MultiPrStatus($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      number
+      state
+      isDraft
+      title
+      mergeStateStatus
+      reviewDecision
+      # totalCount lets callers detect truncation; pageInfo enables backward pagination.
+      reviewThreads(last: 100) {
+        totalCount
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          isResolved
+        }
+      }
+      commits(last: 1) {
+        nodes {
+          commit {
+            statusCheckRollup {
+              state
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/github/gql/resolve-thread.gql

@@ -0,0 +1,7 @@
+mutation ResolveThread($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) {
+    thread {
+      isResolved
+    }
+  }
+}

package/src/github/pagination.mts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ *   - Backward (`before` + `last`) — used by reviewThreads (default GitHub order).
+ */
+
+export 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 async function paginateForward<T>(
+  fetchFn: (cursor: string | null) => Promise<Connection<T>>,
+  initialCursor?: string | null,
+): Promise<T[]> {
+  const all: T[] = [];
+  let cursor: string | null = initialCursor ?? null;
+
+  for (;;) {
+    // eslint-disable-next-line no-await-in-loop
+    const conn = await fetchFn(cursor);
+
+    all.push(...conn.nodes);
+
+    if (!conn.pageInfo.hasNextPage || !conn.pageInfo.endCursor) break;
+    cursor = conn.pageInfo.endCursor;
+  }
+
+  return all;
+}
+
+/**
+ * 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 async function paginateBackward<T>(
+  fetchFn: (cursor: string | null) => Promise<Connection<T>>,
+  initialCursor?: string | null,
+): Promise<T[]> {
+  const all: T[] = [];
+  let cursor: string | null = initialCursor ?? null;
+
+  for (;;) {
+    // eslint-disable-next-line no-await-in-loop
+    const conn = await fetchFn(cursor);
+
+    // Backward pagination returns items oldest-first within each page but pages
+    // go from newest-to-oldest. Prepend each page so final array is oldest-first.
+    all.unshift(...conn.nodes);
+
+    if (!conn.pageInfo.hasPreviousPage || !conn.pageInfo.startCursor) break;
+    cursor = conn.pageInfo.startCursor;
+  }
+
+  return all;
+}

package/src/github/pagination.test.mts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import { paginateForward, paginateBackward, type Connection } from "./pagination.mts";
+
+// ---------------------------------------------------------------------------
+// paginateForward
+// ---------------------------------------------------------------------------
+
+describe("paginateForward", () => {
+  it("collects all nodes across three pages", async () => {
+    const pages: Connection<string>[] = [
+      { pageInfo: { hasNextPage: true, endCursor: "cursor1" }, nodes: ["a", "b"] },
+      { pageInfo: { hasNextPage: true, endCursor: "cursor2" }, nodes: ["c"] },
+      { pageInfo: { hasNextPage: false, endCursor: null }, nodes: ["d", "e"] },
+    ];
+    const cursors: Array<string | null> = [];
+    let i = 0;
+
+    const result = await paginateForward((cursor) => {
+      cursors.push(cursor);
+      return Promise.resolve(pages[i++]!);
+    });
+
+    expect(result).toEqual(["a", "b", "c", "d", "e"]);
+    expect(cursors).toEqual([null, "cursor1", "cursor2"]);
+  });
+
+  it("stops after a single page when hasNextPage is false", async () => {
+    let calls = 0;
+    const result = await paginateForward(() => {
+      calls++;
+      return Promise.resolve({
+        pageInfo: { hasNextPage: false, endCursor: null },
+        nodes: ["x", "y"],
+      });
+    });
+
+    expect(result).toEqual(["x", "y"]);
+    expect(calls).toBe(1);
+  });
+
+  it("returns an empty array for an empty first page", async () => {
+    const result = await paginateForward(() =>
+      Promise.resolve({
+        pageInfo: { hasNextPage: false, endCursor: null },
+        nodes: [] as string[],
+      }),
+    );
+
+    expect(result).toEqual([]);
+  });
+
+  it("starts from initialCursor to avoid re-fetching the already-known page", async () => {
+    // Simulates the batch.mts use case: the initial query already returned page
+    // ending at 'cur-first'. paginateForward should start from that endCursor
+    // so it only fetches pages *after* it.
+    const pages: Record<string, Connection<string>> = {
+      "cur-first": {
+        pageInfo: { hasNextPage: true, endCursor: "cur-second" },
+        nodes: ["c", "d"],
+      },
+      "cur-second": {
+        pageInfo: { hasNextPage: false, endCursor: null },
+        nodes: ["e"],
+      },
+    };
+    const cursors: Array<string | null> = [];
+
+    const result = await paginateForward((cursor) => {
+      cursors.push(cursor);
+      return Promise.resolve(pages[cursor ?? ""]!);
+    }, "cur-first");
+
+    // Should fetch pages after 'cur-first', not re-fetch it.
+    expect(cursors).toEqual(["cur-first", "cur-second"]);
+    expect(result).toEqual(["c", "d", "e"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// paginateBackward
+// ---------------------------------------------------------------------------
+
+describe("paginateBackward", () => {
+  it("collects nodes across pages and returns oldest-first", async () => {
+    // Backward pagination: newest page first, oldest last.
+    const pages: Connection<string>[] = [
+      { pageInfo: { hasPreviousPage: true, startCursor: "cur1" }, nodes: ["newer", "newest"] },
+      { pageInfo: { hasPreviousPage: true, startCursor: "cur2" }, nodes: ["older"] },
+      { pageInfo: { hasPreviousPage: false, startCursor: null }, nodes: ["oldest"] },
+    ];
+    const cursors: Array<string | null> = [];
+    let i = 0;
+
+    const result = await paginateBackward((cursor) => {
+      cursors.push(cursor);
+      return Promise.resolve(pages[i++]!);
+    });
+
+    // unshift inserts older pages at the front.
+    expect(result).toEqual(["oldest", "older", "newer", "newest"]);
+    expect(cursors).toEqual([null, "cur1", "cur2"]);
+  });
+
+  it("returns single-page nodes unchanged", async () => {
+    const result = await paginateBackward(() =>
+      Promise.resolve({
+        pageInfo: { hasPreviousPage: false, startCursor: null },
+        nodes: ["a", "b"],
+      }),
+    );
+
+    expect(result).toEqual(["a", "b"]);
+  });
+
+  it("starts from initialCursor to avoid re-fetching the already-known page", async () => {
+    // Simulates the batch.mts use case: the initial query already returned the
+    // "newest" page (cur-newest). paginateBackward should start from that
+    // startCursor so it only fetches pages *before* it.
+    const pages: Record<string, Connection<string>> = {
+      "cur-newest": {
+        pageInfo: { hasPreviousPage: true, startCursor: "cur-middle" },
+        nodes: ["middle"],
+      },
+      "cur-middle": {
+        pageInfo: { hasPreviousPage: false, startCursor: null },
+        nodes: ["oldest"],
+      },
+    };
+    const cursors: Array<string | null> = [];
+
+    const result = await paginateBackward((cursor) => {
+      cursors.push(cursor);
+      return Promise.resolve(pages[cursor ?? ""]!);
+    }, "cur-newest");
+
+    // Should fetch pages before 'cur-newest', not re-fetch 'cur-newest' itself.
+    expect(cursors).toEqual(["cur-newest", "cur-middle"]);
+    expect(result).toEqual(["oldest", "middle"]);
+  });
+});

package/src/github/queries.mts

@@ -0,0 +1,30 @@
+/**
+ * GraphQL query strings used by pr-shepherd.
+ *
+ * Query strings live in src/github/gql/*.gql.
+ * Never inline raw GraphQL strings in .ts source files.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const gql = (name: string): string =>
+  readFileSync(join((import.meta as { dirname: string }).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");
+
+/** Resolve a single review thread. */
+export const RESOLVE_THREAD_MUTATION = gql("resolve-thread.gql");
+
+/** Minimize a PR comment (IssueComment). */
+export const MINIMIZE_COMMENT_MUTATION = gql("minimize-comment.gql");
+
+/** Dismiss a pull request review. */
+export const DISMISS_REVIEW_MUTATION = gql("dismiss-review.gql");
+
+/** Multi-PR status query for `shepherd status PR1 PR2 …`. */
+export const MULTI_PR_STATUS_QUERY = gql("multi-pr-status.gql");
+
+/** Paginated version — used when reviewThreads is truncated (totalCount > 100). */
+export const MULTI_PR_STATUS_QUERY_WITH_CURSOR = gql("multi-pr-status-paged.gql");

package/src/index.mts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * pr-shepherd — unified GitHub PR status + auto-resolve CLI
+ *
+ * Usage:
+ *   pr-shepherd check [PR]
+ *   pr-shepherd resolve [PR]
+ *   pr-shepherd iterate [PR]
+ *   pr-shepherd status PR1 [PR2 …]
+ */
+
+import { main } from "./cli.mts";
+
+main(process.argv).catch((err) => {
+  process.stderr.write(`pr-shepherd error: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/src/merge-status/derive.mts

@@ -0,0 +1,74 @@
+/**
+ * Derives a shepherd `MergeStatusResult` from raw PR data.
+ *
+ * `pr.state` is passed through unchanged; `iterate` handles the cancel action
+ * for non-OPEN (merged/closed) PRs — this function does not branch on it.
+ *
+ * Interpretation order for `status` — first match wins:
+ *   1. mergeable == CONFLICTING       → CONFLICTS
+ *   2. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts)
+ *   3. copilotReviewInProgress        → BLOCKED
+ *   4. mergeStateStatus BEHIND        → BEHIND
+ *   5. mergeStateStatus BLOCKED / HAS_HOOKS → BLOCKED
+ *   6. mergeStateStatus UNSTABLE      → UNSTABLE
+ *   7. isDraft                        → DRAFT
+ *   8. mergeStateStatus UNKNOWN       → UNKNOWN
+ *   9. mergeStateStatus CLEAN         → CLEAN
+ */
+
+import type { BatchPrData, MergeStatusResult } from "../types.mts";
+import { loadConfig } from "../config/load.mts";
+
+export function deriveMergeStatus(pr: BatchPrData): MergeStatusResult {
+  const copilotReviewInProgress = detectCopilotReview(pr);
+
+  let status: MergeStatusResult["status"];
+
+  if (pr.mergeable === "CONFLICTING") {
+    status = "CONFLICTS";
+  } else if (copilotReviewInProgress) {
+    status = "BLOCKED";
+  } else if (pr.mergeStateStatus === "DIRTY") {
+    // DIRTY means GitHub detected merge conflicts in the branch.
+    status = "CONFLICTS";
+  } else if (pr.mergeStateStatus === "BEHIND") {
+    status = "BEHIND";
+  } else if (pr.mergeStateStatus === "BLOCKED" || pr.mergeStateStatus === "HAS_HOOKS") {
+    status = "BLOCKED";
+  } else if (pr.mergeStateStatus === "UNSTABLE") {
+    status = "UNSTABLE";
+  } else if (pr.isDraft || pr.mergeStateStatus === "DRAFT") {
+    status = "DRAFT";
+  } else if (pr.mergeStateStatus === "UNKNOWN") {
+    status = "UNKNOWN";
+  } else {
+    status = "CLEAN";
+  }
+
+  return {
+    status,
+    state: pr.state,
+    isDraft: pr.isDraft,
+    mergeable: pr.mergeable,
+    reviewDecision: pr.reviewDecision,
+    copilotReviewInProgress,
+    mergeStateStatus: pr.mergeStateStatus,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Copilot review detection
+// ---------------------------------------------------------------------------
+
+function detectCopilotReview(pr: BatchPrData): boolean {
+  // A blocking bot review is "in progress" when:
+  //   1. Any reviewRequest has a login starting with one of the configured prefixes, OR
+  //   2. Any latestReview has such a login AND state == "PENDING"
+  const prefixes = loadConfig().mergeStatus.blockingReviewerLogins.map((l) => l.toLowerCase());
+  const isBlocking = (login: string) => prefixes.some((p) => login.toLowerCase().startsWith(p));
+
+  const requested = pr.reviewRequests.some((r) => isBlocking(r.login));
+  const pendingReview = pr.latestReviews.some((r) => isBlocking(r.login) && r.state === "PENDING");
+
+  return requested || pendingReview;
+}

package/src/merge-status/derive.test.mts

@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest";
+import { deriveMergeStatus } from "./derive.mts";
+import type { BatchPrData } from "../types.mts";
+
+function makePr(overrides: Partial<BatchPrData>): BatchPrData {
+  return {
+    number: 42,
+    state: "OPEN",
+    isDraft: false,
+    mergeable: "MERGEABLE",
+    mergeStateStatus: "CLEAN",
+    reviewDecision: null,
+    headRefOid: "abc123",
+    reviewRequests: [],
+    latestReviews: [],
+    reviewThreads: [],
+    comments: [],
+    changesRequestedReviews: [],
+    checks: [],
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Interpretation order (first match wins)
+// ---------------------------------------------------------------------------
+
+describe("deriveMergeStatus", () => {
+  it("CONFLICTING mergeable → CONFLICTS", () => {
+    const result = deriveMergeStatus(makePr({ mergeable: "CONFLICTING" }));
+    expect(result.status).toBe("CONFLICTS");
+  });
+
+  it("Copilot review requested → BLOCKED", () => {
+    const result = deriveMergeStatus(
+      makePr({ reviewRequests: [{ login: "copilot-pull-request-reviewer[bot]" }] }),
+    );
+    expect(result.status).toBe("BLOCKED");
+    expect(result.copilotReviewInProgress).toBe(true);
+  });
+
+  it("Copilot review PENDING in latestReviews → BLOCKED", () => {
+    const result = deriveMergeStatus(
+      makePr({
+        latestReviews: [{ login: "copilot[bot]", state: "PENDING" }],
+      }),
+    );
+    expect(result.status).toBe("BLOCKED");
+    expect(result.copilotReviewInProgress).toBe(true);
+  });
+
+  it("Copilot review APPROVED in latestReviews → not copilotInProgress", () => {
+    const result = deriveMergeStatus(
+      makePr({
+        latestReviews: [{ login: "copilot[bot]", state: "APPROVED" }],
+      }),
+    );
+    expect(result.copilotReviewInProgress).toBe(false);
+  });
+
+  it("CONFLICTING takes priority over copilot blocked", () => {
+    const result = deriveMergeStatus(
+      makePr({
+        mergeable: "CONFLICTING",
+        reviewRequests: [{ login: "copilot[bot]" }],
+      }),
+    );
+    expect(result.status).toBe("CONFLICTS");
+  });
+
+  it("BEHIND mergeStateStatus → BEHIND", () => {
+    const result = deriveMergeStatus(makePr({ mergeStateStatus: "BEHIND" }));
+    expect(result.status).toBe("BEHIND");
+  });
+
+  it("BLOCKED mergeStateStatus → BLOCKED", () => {
+    const result = deriveMergeStatus(makePr({ mergeStateStatus: "BLOCKED" }));
+    expect(result.status).toBe("BLOCKED");
+  });
+
+  it("UNSTABLE mergeStateStatus → UNSTABLE", () => {
+    const result = deriveMergeStatus(makePr({ mergeStateStatus: "UNSTABLE" }));
+    expect(result.status).toBe("UNSTABLE");
+  });
+
+  it("isDraft → DRAFT", () => {
+    const result = deriveMergeStatus(makePr({ isDraft: true }));
+    expect(result.status).toBe("DRAFT");
+  });
+
+  it("UNKNOWN mergeStateStatus → UNKNOWN", () => {
+    const result = deriveMergeStatus(makePr({ mergeStateStatus: "UNKNOWN" }));
+    expect(result.status).toBe("UNKNOWN");
+  });
+
+  it("CLEAN mergeStateStatus → CLEAN", () => {
+    const result = deriveMergeStatus(makePr({ mergeStateStatus: "CLEAN" }));
+    expect(result.status).toBe("CLEAN");
+  });
+
+  it("includes full detail fields in result", () => {
+    const result = deriveMergeStatus(
+      makePr({ reviewDecision: "CHANGES_REQUESTED", isDraft: false }),
+    );
+    expect(result.reviewDecision).toBe("CHANGES_REQUESTED");
+    expect(result.isDraft).toBe(false);
+    expect(result.mergeable).toBe("MERGEABLE");
+  });
+});
+
+describe("deriveMergeStatus — state pass-through", () => {
+  it("passes OPEN state through", () => {
+    const result = deriveMergeStatus(makePr({ state: "OPEN" }));
+    expect(result.state).toBe("OPEN");
+  });
+
+  it("passes MERGED state through", () => {
+    const result = deriveMergeStatus(
+      makePr({ state: "MERGED", mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" }),
+    );
+    expect(result.state).toBe("MERGED");
+  });
+
+  it("passes CLOSED state through", () => {
+    const result = deriveMergeStatus(
+      makePr({ state: "CLOSED", mergeable: "UNKNOWN", mergeStateStatus: "UNKNOWN" }),
+    );
+    expect(result.state).toBe("CLOSED");
+  });
+});

package/src/reporters/json.mts

@@ -0,0 +1,12 @@
+/**
+ * Machine-readable JSON reporter.
+ *
+ * Slash commands parse this output to extract IDs, status, and actionable items
+ * without string-scraping the human-readable text reporter.
+ */
+
+import type { ShepherdReport } from "../types.mts";
+
+export function formatJson(report: ShepherdReport): string {
+  return JSON.stringify(report, null, 2);
+}