pr-shepherd 0.2.0

package/src/reporters/text.mts

@@ -0,0 +1,140 @@
+/**
+ * Human-readable text reporter for shepherd check output.
+ */
+
+import type { ShepherdReport, TriagedCheck } from "../types.mts";
+
+export function formatText(report: ShepherdReport): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`\nPR #${report.pr} — ${report.repo}`);
+  lines.push(`Status: ${report.status}`);
+  lines.push("");
+
+  // Merge status
+  const ms = report.mergeStatus;
+  lines.push(`Merge Status: ${ms.status}`);
+  lines.push(`  mergeStateStatus:       ${ms.mergeStateStatus}`);
+  lines.push(`  mergeable:              ${ms.mergeable}`);
+  lines.push(`  reviewDecision:         ${ms.reviewDecision ?? "(none)"}`);
+  lines.push(`  isDraft:                ${ms.isDraft}`);
+  lines.push(`  copilotReviewInProgress:${ms.copilotReviewInProgress}`);
+  lines.push("");
+
+  // CI checks
+  const { passing, failing, inProgress, skipped } = report.checks;
+  const total = passing.length + failing.length + inProgress.length + skipped.length;
+  lines.push(`CI Checks: ${passing.length}/${total} passed`);
+
+  if (failing.length > 0) {
+    lines.push(`\nFailed Checks (${failing.length}):`);
+    for (const c of failing) {
+      const triaged = c as TriagedCheck;
+      const kind = triaged.failureKind ? ` [${triaged.failureKind}]` : "";
+      lines.push(`  - ${c.name}${kind}: ${c.conclusion ?? c.status}`);
+      if (triaged.logExcerpt) {
+        lines.push(indent(triaged.logExcerpt.split("\n").slice(-10).join("\n"), "    "));
+      }
+    }
+  }
+
+  if (inProgress.length > 0) {
+    lines.push(`\nIn Progress (${inProgress.length}):`);
+    for (const c of inProgress) {
+      lines.push(`  - ${c.name}: ${c.status}`);
+    }
+  }
+
+  if (skipped.length > 0) {
+    lines.push(`\nSkipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
+  }
+
+  if (report.checks.filtered.length > 0) {
+    lines.push(
+      `\nFiltered (non-PR-trigger) (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`,
+    );
+    if (report.checks.blockedByFilteredCheck) {
+      lines.push(
+        "  Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.",
+      );
+    } else if (report.mergeStatus.status === "BLOCKED") {
+      lines.push(
+        "  Note: one or more of these filtered checks may be a required status check blocking merge.",
+      );
+    }
+  }
+
+  lines.push("");
+
+  // Review threads
+  const { actionable: actionableThreads, autoResolved, autoResolveErrors } = report.threads;
+  if (autoResolved.length > 0) {
+    lines.push(`Auto-resolved outdated threads (${autoResolved.length}):`);
+    for (const t of autoResolved) {
+      lines.push(`  - threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+    }
+    lines.push("");
+  }
+
+  if (autoResolveErrors.length > 0) {
+    lines.push(`Auto-resolve errors (${autoResolveErrors.length}):`);
+    for (const e of autoResolveErrors) {
+      lines.push(`  - ${e}`);
+    }
+    lines.push("");
+  }
+
+  if (actionableThreads.length > 0) {
+    lines.push(`Actionable Review Threads (${actionableThreads.length}):`);
+    for (const t of actionableThreads) {
+      const label = t.path ? `${t.path}:${t.line ?? "?"}` : "(general)";
+      lines.push(`  - threadId=${t.id} ${label} (@${t.author})`);
+      lines.push(`    ${firstLine(t.body)}`);
+    }
+    lines.push("");
+  }
+
+  // PR comments
+  const { actionable: actionableComments } = report.comments;
+  if (actionableComments.length > 0) {
+    lines.push(`Actionable PR Comments (${actionableComments.length}):`);
+    for (const c of actionableComments) {
+      lines.push(`  - commentId=${c.id} (@${c.author}): ${firstLine(c.body)}`);
+    }
+    lines.push("");
+  }
+
+  // CHANGES_REQUESTED reviews
+  if (report.changesRequestedReviews.length > 0) {
+    lines.push(`Pending CHANGES_REQUESTED reviews (${report.changesRequestedReviews.length}):`);
+    for (const r of report.changesRequestedReviews) {
+      lines.push(`  - reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+    }
+    lines.push("");
+  }
+
+  // Summary
+  const totalActionable =
+    actionableThreads.length + actionableComments.length + report.changesRequestedReviews.length;
+  lines.push(
+    `Summary: ${totalActionable === 0 ? "0 actionable — all threads resolved/minimized" : `${totalActionable} actionable item(s) remaining`}`,
+  );
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function firstLine(text: string): string {
+  return (text.split("\n")[0] ?? "").trim().slice(0, 120);
+}
+
+function indent(text: string, prefix: string): string {
+  return text
+    .split("\n")
+    .map((l) => prefix + l)
+    .join("\n");
+}

package/src/types.mts

@@ -0,0 +1,309 @@
+/** Shared type definitions for the shepherd CLI. */
+
+// ---------------------------------------------------------------------------
+// GitHub primitives
+// ---------------------------------------------------------------------------
+
+export type CheckConclusion =
+  | "ACTION_REQUIRED"
+  | "CANCELLED"
+  | "FAILURE"
+  | "NEUTRAL"
+  | "SKIPPED"
+  | "STALE"
+  | "STARTUP_FAILURE"
+  | "SUCCESS"
+  | "TIMED_OUT"
+  | null;
+
+export type CheckStatus =
+  | "COMPLETED"
+  | "IN_PROGRESS"
+  | "PENDING"
+  | "QUEUED"
+  | "REQUESTED"
+  | "WAITING";
+
+export type MergeableState = "CONFLICTING" | "MERGEABLE" | "UNKNOWN";
+
+export type MergeStateStatus =
+  | "BEHIND"
+  | "BLOCKED"
+  | "CLEAN"
+  | "DIRTY"
+  | "DRAFT"
+  | "HAS_HOOKS"
+  | "UNKNOWN"
+  | "UNSTABLE";
+
+export type ReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
+
+// ---------------------------------------------------------------------------
+// Check runs
+// ---------------------------------------------------------------------------
+
+export interface CheckRun {
+  name: string;
+  status: CheckStatus;
+  conclusion: CheckConclusion;
+  detailsUrl: string;
+  /** The workflow event that triggered this run (e.g. pull_request, push, schedule). */
+  event: string | null;
+  /** GitHub Actions run ID extracted from detailsUrl. */
+  runId: string | null;
+}
+
+export type CheckCategory = "passed" | "failing" | "in_progress" | "skipped" | "filtered";
+
+export interface ClassifiedCheck extends CheckRun {
+  category: CheckCategory;
+}
+
+export type FailureKind = "timeout" | "infrastructure" | "actionable" | "flaky";
+
+export interface TriagedCheck extends ClassifiedCheck {
+  failureKind?: FailureKind;
+  /** Log excerpt for actionable failures. */
+  logExcerpt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Review threads and comments
+// ---------------------------------------------------------------------------
+
+export interface ReviewThread {
+  id: string;
+  isResolved: boolean;
+  isOutdated: boolean;
+  path: string | null;
+  line: number | null;
+  author: string;
+  body: string;
+  createdAtUnix: number;
+}
+
+export interface PrComment {
+  id: string;
+  isMinimized: boolean;
+  author: string;
+  body: string;
+  createdAtUnix: number;
+}
+
+export interface Review {
+  id: string;
+  author: string;
+  body: string;
+}
+
+// ---------------------------------------------------------------------------
+// Merge status
+// ---------------------------------------------------------------------------
+
+export type ShepherdMergeStatus =
+  | "CLEAN"
+  | "BEHIND"
+  | "CONFLICTS"
+  | "BLOCKED"
+  | "UNSTABLE"
+  | "DRAFT"
+  | "UNKNOWN";
+
+export interface MergeStatusResult {
+  status: ShepherdMergeStatus;
+  state: "OPEN" | "CLOSED" | "MERGED";
+  isDraft: boolean;
+  mergeable: MergeableState;
+  reviewDecision: ReviewDecision;
+  copilotReviewInProgress: boolean;
+  mergeStateStatus: MergeStateStatus;
+}
+
+// ---------------------------------------------------------------------------
+// Batch query response (the combined GraphQL shape)
+// ---------------------------------------------------------------------------
+
+export interface BatchPrData {
+  number: number;
+  state: "OPEN" | "CLOSED" | "MERGED";
+  isDraft: boolean;
+  mergeable: MergeableState;
+  mergeStateStatus: MergeStateStatus;
+  reviewDecision: ReviewDecision;
+  headRefOid: string;
+  reviewRequests: Array<{ login: string }>;
+  latestReviews: Array<{ login: string; state: string }>;
+  reviewThreads: ReviewThread[];
+  comments: PrComment[];
+  changesRequestedReviews: Review[];
+  checks: CheckRun[];
+}
+
+// ---------------------------------------------------------------------------
+// Shepherd check report (output of the check command)
+// ---------------------------------------------------------------------------
+
+export type ShepherdStatus =
+  | "READY"
+  | "FAILING"
+  | "IN_PROGRESS"
+  | "UNRESOLVED_COMMENTS"
+  | "UNKNOWN";
+
+export interface ShepherdReport {
+  pr: number;
+  repo: string;
+  status: ShepherdStatus;
+  mergeStatus: MergeStatusResult;
+  checks: {
+    passing: ClassifiedCheck[];
+    failing: TriagedCheck[];
+    inProgress: ClassifiedCheck[];
+    skipped: ClassifiedCheck[];
+    /** Checks filtered out because they were triggered by a non-PR event (push, schedule, etc.). */
+    filtered: ClassifiedCheck[];
+    filteredNames: string[];
+    blockedByFilteredCheck: boolean;
+  };
+  threads: {
+    actionable: ReviewThread[];
+    autoResolved: ReviewThread[];
+    autoResolveErrors: string[];
+  };
+  comments: {
+    actionable: PrComment[];
+  };
+  changesRequestedReviews: Review[];
+  lastPushTime?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Resolve command input
+// ---------------------------------------------------------------------------
+
+export interface ResolveOptions {
+  resolveThreadIds?: string[];
+  minimizeCommentIds?: string[];
+  dismissReviewIds?: string[];
+  dismissMessage?: string;
+  /** When set, shepherd verifies GitHub has received this commit before resolving. */
+  requireSha?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Iterate command types
+// ---------------------------------------------------------------------------
+
+export type ShepherdAction =
+  | "cooldown"
+  | "wait"
+  | "fix_code"
+  | "rerun_ci"
+  | "rebase"
+  | "mark_ready"
+  | "cancel"
+  | "escalate";
+
+export interface EscalateDetails {
+  triggers: string[];
+  unresolvedThreads: ReviewThread[];
+  ambiguousComments: PrComment[];
+  changesRequestedReviews: Review[];
+  /** Populated when fix-thrash triggered — threads that have been attempted too many times. */
+  attemptHistory?: Array<{ threadId: string; attempts: number }>;
+  /** One-line hint for the human on what to do. */
+  suggestion: string;
+}
+
+export interface IterateResultSummary {
+  passing: number;
+  skipped: number;
+  filtered: number;
+  inProgress: number;
+}
+
+export interface IterateResultBase {
+  pr: number;
+  repo: string;
+  status: ShepherdStatus;
+  /** `'UNKNOWN'` during the cooldown early-return (no sweep has been run yet). */
+  state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
+  mergeStateStatus: MergeStateStatus;
+  copilotReviewInProgress: boolean;
+  isDraft: boolean;
+  shouldCancel: boolean;
+  remainingSeconds: number;
+  summary: IterateResultSummary;
+}
+
+export interface IterateResultCooldown extends IterateResultBase {
+  action: "cooldown";
+}
+
+export interface IterateResultWait extends IterateResultBase {
+  action: "wait";
+}
+
+export interface IterateResultCancel extends IterateResultBase {
+  action: "cancel";
+}
+
+export interface IterateResultFixCode extends IterateResultBase {
+  action: "fix_code";
+  fix: {
+    threads: ReviewThread[];
+    comments: PrComment[];
+    checks: TriagedCheck[];
+    changesRequestedReviews: Review[];
+  };
+  cancelled: string[];
+}
+
+export interface IterateResultRerunCi extends IterateResultBase {
+  action: "rerun_ci";
+  reran: string[];
+}
+
+export interface IterateResultRebase extends IterateResultBase {
+  action: "rebase";
+}
+
+export interface IterateResultMarkReady extends IterateResultBase {
+  action: "mark_ready";
+  markedReady: boolean;
+}
+
+export interface IterateResultEscalate extends IterateResultBase {
+  action: "escalate";
+  escalate: EscalateDetails;
+}
+
+export type IterateResult =
+  | IterateResultCooldown
+  | IterateResultWait
+  | IterateResultCancel
+  | IterateResultFixCode
+  | IterateResultRerunCi
+  | IterateResultRebase
+  | IterateResultMarkReady
+  | IterateResultEscalate;
+
+export interface IterateCommandOptions extends GlobalOptions {
+  cooldownSeconds?: number;
+  readyDelaySeconds?: number;
+  lastPushTime?: number;
+  noAutoRerun?: boolean;
+  noAutoMarkReady?: boolean;
+  noAutoCancelActionable?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// CLI options
+// ---------------------------------------------------------------------------
+
+export interface GlobalOptions {
+  prNumber?: number;
+  format: "text" | "json";
+  noCache: boolean;
+  cacheTtlSeconds: number;
+}

package/src/util/path-segment.mts

@@ -0,0 +1,2 @@
+/** Allowed characters: alphanumeric, hyphen, underscore, dot. Prevents path traversal. */
+export const SAFE_SEGMENT = /^[a-zA-Z0-9._-]+$/;