pr-shepherd 0.2.0

package/src/commands/status.mts

@@ -0,0 +1,173 @@
+/**
+ * `shepherd status PR1 [PR2 PR3 …]`
+ *
+ * Fetches readiness status for one or more PRs and prints a table.
+ * Uses a separate lightweight GraphQL query (MULTI_PR_STATUS_QUERY) per PR
+ * rather than the heavy batch query, since we only need summary data.
+ *
+ * Exit code: 0 if all PRs are READY, non-zero otherwise.
+ */
+
+import { graphql, getRepoInfo } from "../github/client.mts";
+import { MULTI_PR_STATUS_QUERY, MULTI_PR_STATUS_QUERY_WITH_CURSOR } from "../github/queries.mts";
+import type { GlobalOptions } from "../types.mts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface PrSummary {
+  number: number;
+  title: string;
+  state: string;
+  isDraft: boolean;
+  mergeStateStatus: string;
+  reviewDecision: string | null;
+  unresolvedThreads: number;
+  ciState: string | null;
+  /**
+   * True when `reviewThreads` returned exactly 100 nodes but `totalCount` is higher —
+   * meaning the unresolved-thread count may be undercounted.
+   */
+  threadsTruncated: boolean;
+}
+
+export interface StatusCommandOptions extends GlobalOptions {
+  prNumbers: number[];
+}
+
+export async function runStatus(opts: StatusCommandOptions): Promise<PrSummary[]> {
+  const repo = await getRepoInfo();
+  const summaries = await Promise.all(
+    opts.prNumbers.map((pr) => fetchSummary(pr, repo.owner, repo.name)),
+  );
+  return summaries;
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+async function fetchSummary(pr: number, owner: string, repo: string): Promise<PrSummary> {
+  const result = await graphql<RawStatusResponse>(MULTI_PR_STATUS_QUERY, {
+    owner,
+    repo,
+    pr,
+  });
+
+  const p = result.data.repository.pullRequest;
+  if (!p) {
+    throw new Error(`PR #${pr} not found in ${owner}/${repo}`);
+  }
+
+  let allNodes = p.reviewThreads.nodes;
+
+  // If the response was truncated, fetch additional pages to get the full count.
+  if (p.reviewThreads.totalCount > p.reviewThreads.nodes.length) {
+    // Fetch additional pages backward until we have all threads.
+    let cursor: string | null = p.reviewThreads.pageInfo?.startCursor ?? null;
+    while (cursor !== null) {
+      // eslint-disable-next-line no-await-in-loop
+      const extra = await graphql<RawStatusResponse>(MULTI_PR_STATUS_QUERY_WITH_CURSOR, {
+        owner,
+        repo,
+        pr,
+        cursor,
+      });
+      const p2 = extra.data.repository.pullRequest;
+      if (!p2) break;
+      allNodes = [...p2.reviewThreads.nodes, ...allNodes];
+      if (!p2.reviewThreads.pageInfo?.hasPreviousPage || !p2.reviewThreads.pageInfo.startCursor) {
+        break;
+      }
+      cursor = p2.reviewThreads.pageInfo.startCursor;
+    }
+  }
+
+  const unresolvedThreads = allNodes.filter((n) => !n.isResolved).length;
+  const ciState = p.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null;
+  // If we still have fewer nodes than totalCount, report truncation.
+  const threadsTruncated = p.reviewThreads.totalCount > allNodes.length;
+
+  return {
+    number: p.number,
+    title: p.title,
+    state: p.state,
+    isDraft: p.isDraft,
+    mergeStateStatus: p.mergeStateStatus,
+    reviewDecision: p.reviewDecision,
+    unresolvedThreads,
+    ciState,
+    threadsTruncated,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+
+export function formatStatusTable(summaries: PrSummary[], repoFull: string): string {
+  const lines: string[] = [`\n# ${repoFull} — PR status (${summaries.length})\n`];
+
+  for (const s of summaries) {
+    const verdict = deriveVerdict(s);
+    const ciLabel = s.ciState ?? "—";
+    const title = s.title.slice(0, 50);
+    const truncNote = s.threadsTruncated
+      ? " (threads truncated — run shepherd check for full count)"
+      : "";
+    lines.push(
+      `PR #${String(s.number).padEnd(5)} ${title.padEnd(52)} ${verdict.padEnd(12)} ${ciLabel}${truncNote}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function deriveVerdict(s: PrSummary): string {
+  if (s.state === "MERGED") return "MERGED";
+  if (s.state === "CLOSED") return "CLOSED";
+  if (s.isDraft) return "DRAFT";
+  if (
+    s.mergeStateStatus === "CLEAN" &&
+    s.unresolvedThreads === 0 &&
+    s.ciState === "SUCCESS" &&
+    s.reviewDecision !== "CHANGES_REQUESTED"
+  ) {
+    return "READY";
+  }
+  if (s.mergeStateStatus === "BLOCKED") return "BLOCKED";
+  if (s.mergeStateStatus === "DIRTY") return "CONFLICTS";
+  if (s.ciState === "PENDING" || s.ciState === "EXPECTED") return "IN PROGRESS";
+  if (s.ciState === "FAILURE" || s.ciState === "ERROR") return "FAILING";
+  return s.mergeStateStatus;
+}
+
+// ---------------------------------------------------------------------------
+// Raw GraphQL types
+// ---------------------------------------------------------------------------
+
+interface RawStatusResponse {
+  repository: {
+    pullRequest: {
+      number: number;
+      title: string;
+      state: string;
+      isDraft: boolean;
+      mergeStateStatus: string;
+      reviewDecision: string | null;
+      reviewThreads: {
+        totalCount: number;
+        pageInfo?: { hasPreviousPage: boolean; startCursor: string | null };
+        nodes: Array<{ isResolved: boolean }>;
+      };
+      commits: {
+        nodes: Array<{
+          commit: {
+            statusCheckRollup: { state: string } | null;
+          };
+        }>;
+      };
+    } | null;
+  };
+}

package/src/comments/outdated.mts

@@ -0,0 +1,18 @@
+/**
+ * Determines which review threads should be auto-resolved as outdated.
+ *
+ * A thread is eligible for auto-resolution when:
+ *   - `isOutdated == true` (GitHub marks these when the diff hunk changed), AND
+ *   - `isResolved == false`.
+ *
+ * GitHub's `isOutdated` flag means the thread's referenced code has changed
+ * enough that the comment no longer points to a live diff line. These threads
+ * are visually collapsed on GitHub and are safe to resolve programmatically.
+ */
+
+import type { ReviewThread } from "../types.mts";
+
+/** Returns the subset of threads that should be auto-resolved as outdated. */
+export function getOutdatedThreads(threads: ReviewThread[]): ReviewThread[] {
+  return threads.filter((t) => t.isOutdated && !t.isResolved);
+}

package/src/comments/resolve.mts

@@ -0,0 +1,179 @@
+/**
+ * Batched mutations for resolving threads, minimizing comments, and dismissing reviews.
+ *
+ * The three mutation types (resolve / minimize / dismiss) are run sequentially so total
+ * in-flight mutations never exceed CONCURRENCY at once, keeping us well within GitHub's
+ * secondary rate-limit window.
+ *
+ * Push-before-resolve safety:
+ *   When `requireSha` is set, shepherd verifies that GitHub has received that
+ *   commit before issuing any resolve/dismiss mutations. It polls up to 20 seconds.
+ *   If the push hasn't landed, shepherd throws rather than resolving prematurely
+ *   (which could allow auto-merge before reviewers see the fix).
+ */
+
+import { graphql, getPrHeadSha, type RepoInfo } from "../github/client.mts";
+import {
+  RESOLVE_THREAD_MUTATION,
+  MINIMIZE_COMMENT_MUTATION,
+  DISMISS_REVIEW_MUTATION,
+} from "../github/queries.mts";
+import type { ResolveOptions } from "../types.mts";
+import { loadConfig } from "../config/load.mts";
+
+const config = loadConfig();
+const CONCURRENCY = config.resolve.concurrency;
+const SHA_POLL_INTERVAL_MS = config.resolve.shaPoll.intervalMs;
+const SHA_POLL_MAX_ATTEMPTS = config.resolve.shaPoll.maxAttempts;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ResolveResult {
+  resolvedThreads: string[];
+  minimizedComments: string[];
+  dismissedReviews: string[];
+  errors: string[];
+}
+
+/**
+ * Execute all requested resolve/minimize/dismiss mutations.
+ *
+ * @throws Error if `requireSha` is set and GitHub hasn't received that commit
+ *              within the polling window.
+ */
+export async function applyResolveOptions(
+  pr: number,
+  repo: RepoInfo,
+  opts: ResolveOptions,
+): Promise<ResolveResult> {
+  // Require --message when dismissing reviews.
+  if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
+    throw new Error("--message is required when dismissing reviews");
+  }
+
+  // Safety check: verify the push landed before resolving.
+  if (opts.requireSha) {
+    await waitForSha(pr, repo, opts.requireSha);
+  }
+
+  const result: ResolveResult = {
+    resolvedThreads: [],
+    minimizedComments: [],
+    dismissedReviews: [],
+    errors: [],
+  };
+
+  await runBatched(
+    opts.resolveThreadIds ?? [],
+    (id) => resolveThread(id),
+    result.resolvedThreads,
+    result.errors,
+  );
+  await runBatched(
+    opts.minimizeCommentIds ?? [],
+    (id) => minimizeComment(id, "RESOLVED"),
+    result.minimizedComments,
+    result.errors,
+  );
+  await runBatched(
+    opts.dismissReviewIds ?? [],
+    (id) => dismissReview(id, opts.dismissMessage!),
+    result.dismissedReviews,
+    result.errors,
+  );
+
+  return result;
+}
+
+/**
+ * Auto-resolve a batch of outdated threads via the resolveReviewThread mutation.
+ */
+export async function autoResolveOutdated(
+  threadIds: string[],
+): Promise<{ resolved: string[]; errors: string[] }> {
+  const resolved: string[] = [];
+  const errors: string[] = [];
+  await runBatched(threadIds, (id) => resolveThread(id), resolved, errors);
+  return { resolved, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Mutation helpers
+// ---------------------------------------------------------------------------
+
+async function resolveThread(threadId: string): Promise<void> {
+  await graphql(RESOLVE_THREAD_MUTATION, { threadId });
+}
+
+async function minimizeComment(
+  commentId: string,
+  classifier: "RESOLVED" | "OFF_TOPIC",
+): Promise<void> {
+  await graphql(MINIMIZE_COMMENT_MUTATION, { commentId, classifier });
+}
+
+async function dismissReview(reviewId: string, message: string): Promise<void> {
+  await graphql(DISMISS_REVIEW_MUTATION, { reviewId, message });
+}
+
+// ---------------------------------------------------------------------------
+// Concurrency helper
+// ---------------------------------------------------------------------------
+
+async function runBatched(
+  ids: string[],
+  fn: (id: string) => Promise<void>,
+  successList: string[],
+  errorList: string[],
+): Promise<void> {
+  // Process in chunks of CONCURRENCY.
+  for (let i = 0; i < ids.length; i += CONCURRENCY) {
+    const chunk = ids.slice(i, i + CONCURRENCY);
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.all(
+      chunk.map(async (id) => {
+        try {
+          await fn(id);
+          successList.push(id);
+        } catch (err) {
+          errorList.push(`${id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SHA polling
+// ---------------------------------------------------------------------------
+
+async function waitForSha(pr: number, repo: RepoInfo, expectedSha: string): Promise<void> {
+  for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
+      if (currentSha === expectedSha) return;
+    } catch (err) {
+      // Transient network / 5xx error — keep polling unless this is the last attempt.
+      if (attempt === SHA_POLL_MAX_ATTEMPTS - 1) throw err;
+    }
+
+    if (attempt < SHA_POLL_MAX_ATTEMPTS - 1) {
+      // eslint-disable-next-line no-await-in-loop
+      await sleep(SHA_POLL_INTERVAL_MS);
+    }
+  }
+
+  // Total actual wait = (SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS (no sleep after last poll).
+  throw new Error(
+    `Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${
+      ((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000
+    }s. Push may still be in transit — retry shortly.`,
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/config/load.mts

@@ -0,0 +1,240 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { parse } from "yaml";
+import builtins from "../config.json" with { type: "json" };
+
+export interface PrShepherdConfig {
+  cache: {
+    ttlSeconds: number;
+  };
+  iterate: {
+    cooldownSeconds: number;
+    fixAttemptsPerThread: number;
+  };
+  watch: {
+    interval: string;
+    readyDelayMinutes: number;
+    expiresHours: number;
+    maxTurns: number;
+  };
+  resolve: {
+    concurrency: number;
+    shaPoll: {
+      intervalMs: number;
+      maxAttempts: number;
+    };
+  };
+  checks: {
+    ciTriggerEvents: string[];
+    timeoutPatterns: string[];
+    infraPatterns: string[];
+    logMaxLines: number;
+    logMaxChars: number;
+  };
+  mergeStatus: {
+    blockingReviewerLogins: string[];
+  };
+  execution: {
+    maxBufferMb: number;
+    triageLogBufferMb: number;
+  };
+  actions: {
+    autoResolveOutdated: boolean;
+    autoRebase: boolean;
+    autoMarkReady: boolean;
+  };
+}
+
+const RC_FILENAME = ".pr-shepherdrc.yml";
+
+function findRcFile(startDir: string): string | null {
+  const home = homedir();
+  let current = startDir;
+  while (true) {
+    const candidate = join(current, RC_FILENAME);
+    try {
+      readFileSync(candidate);
+      return candidate;
+    } catch {
+      // not found here
+    }
+    if (current === home || current === dirname(current)) return null;
+    current = dirname(current);
+  }
+}
+
+function deepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...base };
+  for (const key of Object.keys(override)) {
+    const overVal = override[key];
+    const baseVal = base[key];
+    if (
+      overVal !== null &&
+      typeof overVal === "object" &&
+      !Array.isArray(overVal) &&
+      typeof baseVal === "object" &&
+      baseVal !== null &&
+      !Array.isArray(baseVal)
+    ) {
+      result[key] = deepMerge(
+        baseVal as Record<string, unknown>,
+        overVal as Record<string, unknown>,
+      );
+    } else if (overVal !== undefined) {
+      result[key] = overVal;
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Compatibility shim — maps old RC keys to new ones and emits deprecation warnings
+// ---------------------------------------------------------------------------
+
+function applyCompat(raw: Record<string, unknown>): Record<string, unknown> {
+  const out = { ...raw };
+
+  // Removed keys — warn and strip.
+  for (const gone of ["baseBranch", "minimizeBots", "cancelCiOnFailure", "autoMinimize"]) {
+    if (gone in out) {
+      process.stderr.write(
+        `pr-shepherd: config key "${gone}" has been removed and has no effect.\n`,
+      );
+      delete out[gone];
+    }
+  }
+
+  // Renamed top-level section keys — iterate
+  const iterate = out["iterate"] as Record<string, unknown> | undefined;
+  if (iterate && "maxFixAttempts" in iterate) {
+    process.stderr.write(
+      `pr-shepherd: config key "iterate.maxFixAttempts" renamed to "iterate.fixAttemptsPerThread".\n`,
+    );
+    out["iterate"] = { fixAttemptsPerThread: iterate["maxFixAttempts"], ...iterate };
+    delete (out["iterate"] as Record<string, unknown>)["maxFixAttempts"];
+  }
+
+  // Renamed watch keys
+  const watch = out["watch"] as Record<string, unknown> | undefined;
+  if (watch) {
+    const watchOut = { ...watch };
+    if ("intervalDefault" in watch) {
+      process.stderr.write(
+        `pr-shepherd: config key "watch.intervalDefault" renamed to "watch.interval".\n`,
+      );
+      watchOut["interval"] = watch["intervalDefault"];
+      delete watchOut["intervalDefault"];
+    }
+    if ("readyDelayMinutesDefault" in watch) {
+      process.stderr.write(
+        `pr-shepherd: config key "watch.readyDelayMinutesDefault" renamed to "watch.readyDelayMinutes".\n`,
+      );
+      watchOut["readyDelayMinutes"] = watch["readyDelayMinutesDefault"];
+      delete watchOut["readyDelayMinutesDefault"];
+    }
+    if ("expiresHoursDefault" in watch) {
+      process.stderr.write(
+        `pr-shepherd: config key "watch.expiresHoursDefault" renamed to "watch.expiresHours".\n`,
+      );
+      watchOut["expiresHours"] = watch["expiresHoursDefault"];
+      delete watchOut["expiresHoursDefault"];
+    }
+    out["watch"] = watchOut;
+  }
+
+  // Renamed resolve keys (shaPollIntervalMs / shaPollMaxAttempts → shaPoll object)
+  const resolve = out["resolve"] as Record<string, unknown> | undefined;
+  if (resolve) {
+    const resolveOut = { ...resolve };
+    const shaPollOut: Record<string, unknown> = {};
+    let shaPollChanged = false;
+    if ("shaPollIntervalMs" in resolve) {
+      process.stderr.write(
+        `pr-shepherd: config key "resolve.shaPollIntervalMs" moved to "resolve.shaPoll.intervalMs".\n`,
+      );
+      shaPollOut["intervalMs"] = resolve["shaPollIntervalMs"];
+      delete resolveOut["shaPollIntervalMs"];
+      shaPollChanged = true;
+    }
+    if ("shaPollMaxAttempts" in resolve) {
+      process.stderr.write(
+        `pr-shepherd: config key "resolve.shaPollMaxAttempts" moved to "resolve.shaPoll.maxAttempts".\n`,
+      );
+      shaPollOut["maxAttempts"] = resolve["shaPollMaxAttempts"];
+      delete resolveOut["shaPollMaxAttempts"];
+      shaPollChanged = true;
+    }
+    if (shaPollChanged) {
+      resolveOut["shaPoll"] = {
+        ...(resolveOut["shaPoll"] as Record<string, unknown> | undefined),
+        ...shaPollOut,
+      };
+    }
+    out["resolve"] = resolveOut;
+  }
+
+  // Renamed checks keys
+  const checks = out["checks"] as Record<string, unknown> | undefined;
+  if (checks) {
+    const checksOut = { ...checks };
+    if ("relevantEvents" in checks) {
+      process.stderr.write(
+        `pr-shepherd: config key "checks.relevantEvents" renamed to "checks.ciTriggerEvents".\n`,
+      );
+      checksOut["ciTriggerEvents"] = checks["relevantEvents"];
+      delete checksOut["relevantEvents"];
+    }
+    if ("logLinesKept" in checks) {
+      process.stderr.write(
+        `pr-shepherd: config key "checks.logLinesKept" renamed to "checks.logMaxLines".\n`,
+      );
+      checksOut["logMaxLines"] = checks["logLinesKept"];
+      delete checksOut["logLinesKept"];
+    }
+    if ("logExcerptMaxChars" in checks) {
+      process.stderr.write(
+        `pr-shepherd: config key "checks.logExcerptMaxChars" renamed to "checks.logMaxChars".\n`,
+      );
+      checksOut["logMaxChars"] = checks["logExcerptMaxChars"];
+      delete checksOut["logExcerptMaxChars"];
+    }
+    out["checks"] = checksOut;
+  }
+
+  return out;
+}
+
+const defaults: PrShepherdConfig = builtins;
+
+let cached: PrShepherdConfig | null = null;
+
+export function loadConfig(): PrShepherdConfig {
+  if (cached) return cached;
+
+  const rcPath = findRcFile(process.cwd());
+  if (!rcPath) {
+    cached = defaults;
+    return cached;
+  }
+
+  try {
+    const raw = readFileSync(rcPath, "utf8");
+    const parsed = (parse(raw) ?? {}) as Record<string, unknown>;
+    const compat = applyCompat(parsed);
+    cached = deepMerge(
+      defaults as unknown as Record<string, unknown>,
+      compat,
+    ) as unknown as PrShepherdConfig;
+    return cached;
+  } catch (err) {
+    process.stderr.write(
+      `pr-shepherd: failed to parse ${rcPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    cached = { ...defaults };
+    return cached;
+  }
+}

package/src/config.json

@@ -0,0 +1,52 @@
+{
+  "cache": {
+    "ttlSeconds": 300
+  },
+  "iterate": {
+    "cooldownSeconds": 30,
+    "fixAttemptsPerThread": 3
+  },
+  "watch": {
+    "interval": "4m",
+    "readyDelayMinutes": 10,
+    "expiresHours": 8,
+    "maxTurns": 50
+  },
+  "resolve": {
+    "concurrency": 4,
+    "shaPoll": {
+      "intervalMs": 2000,
+      "maxAttempts": 10
+    }
+  },
+  "checks": {
+    "ciTriggerEvents": ["pull_request", "pull_request_target"],
+    "timeoutPatterns": [
+      "cancel timeout",
+      "exceeded the maximum execution time",
+      "job was cancelled"
+    ],
+    "infraPatterns": [
+      "runner error",
+      "service unavailable",
+      "ETIMEOUT",
+      "ECONNRESET",
+      "lost communication with the server",
+      "the hosted runner lost connection"
+    ],
+    "logMaxLines": 50,
+    "logMaxChars": 3000
+  },
+  "mergeStatus": {
+    "blockingReviewerLogins": ["copilot"]
+  },
+  "execution": {
+    "maxBufferMb": 10,
+    "triageLogBufferMb": 5
+  },
+  "actions": {
+    "autoResolveOutdated": true,
+    "autoRebase": true,
+    "autoMarkReady": true
+  }
+}