pr-shepherd 0.34.0 → 0.36.0

package/bin/suggestions/patch.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Build a git-apply-compatible unified diff for a single suggestion hunk.
+ *
+ * The diff uses `--- a/<path>` / `+++ b/<path>` headers so `git apply` and
+ * `git apply --check` accept it without a `diff --git` preamble.
+ */
+export declare function buildUnifiedDiff({ path, originalContent, startLine, endLine, replacementLines, context, }: {
+    path: string;
+    originalContent: string;
+    startLine: number;
+    endLine: number;
+    replacementLines: readonly string[];
+    context?: number;
+}): string;

package/bin/threads/transcript.d.mts

@@ -0,0 +1,14 @@
+import type { ReviewThread, ReviewThreadComment } from "../types.mts";
+export declare function threadComments(thread: {
+    body: string;
+    author: string;
+    authorType?: ReviewThreadComment["authorType"];
+    authorAssociation?: ReviewThreadComment["authorAssociation"];
+    url?: string;
+    createdAtUnix?: number;
+    comments?: Array<Pick<ReviewThreadComment, "id" | "author" | "body" | "url"> & {
+        authorType?: ReviewThreadComment["authorType"];
+        authorAssociation?: ReviewThreadComment["authorAssociation"];
+    } & Partial<Pick<ReviewThreadComment, "isMinimized" | "createdAtUnix">>>;
+}): ReviewThreadComment[];
+export declare function threadTranscriptBody(thread: ReviewThread, appendedBodies?: string[]): string;

package/bin/threads/transcript.mjs

@@ -5,6 +5,7 @@ export function threadComments(thread) {
             isMinimized: c.isMinimized ?? false,
             author: c.author,
             authorType: c.authorType ?? "Unknown",
+            ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAtUnix ?? 0,
@@ -16,6 +17,9 @@ export function threadComments(thread) {
             isMinimized: false,
             author: thread.author,
             authorType: thread.authorType ?? "Unknown",
+            ...(thread.authorAssociation !== undefined && {
+                authorAssociation: thread.authorAssociation,
+            }),
             body: thread.body,
             url: thread.url ?? "",
             createdAtUnix: thread.createdAtUnix ?? 0,

package/bin/types/activity.d.mts

@@ -0,0 +1,30 @@
+import type { AuthorType, CheckStatus, CommentAuthorAssociation } from "./github.mts";
+type ReviewActivityKind = "pr-comment" | "review-thread-comment" | "review-summary" | "approved-review" | "changes-requested-review";
+export interface ReviewActivityItem {
+    kind: ReviewActivityKind;
+    id: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url?: string;
+    createdAtUnix: number;
+    threadId?: string;
+    path?: string | null;
+    line?: number | null;
+}
+export interface PrActivitySummary {
+    commitCount: number;
+    reviewRoundCount: number;
+    latestCommitCommittedAtUnix: number | null;
+    reviewItemsSinceLatestCommit: ReviewActivityItem[];
+}
+export interface ActiveCheck {
+    name: string;
+    status: CheckStatus;
+    runId: string | null;
+    detailsUrl: string | null;
+    workflowName?: string;
+    summary?: string;
+}
+export {};

package/bin/types/agent-thread.d.mts

@@ -0,0 +1,9 @@
+import type { AuthorType, CommentAuthorAssociation } from "./github.mts";
+export interface AgentThreadComment {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+}

package/bin/types/check-annotations.d.mts

@@ -0,0 +1,14 @@
+export interface CheckAnnotation {
+    /** Stable marker id used by Shepherd; prefixed to avoid collisions with comment/review IDs. */
+    id: string;
+    path: string;
+    startLine: number | null;
+    endLine: number | null;
+    startColumn?: number | null;
+    endColumn?: number | null;
+    level: string;
+    title?: string;
+    message: string;
+    rawDetails?: string;
+    blobUrl?: string;
+}

package/bin/types/check-classification.d.mts

@@ -0,0 +1,19 @@
+import type { CheckAnnotation } from "./check-annotations.mts";
+import type { CheckRun } from "./github.mts";
+type CheckCategory = "passed" | "failing" | "in_progress" | "skipped" | "filtered" | "ignored" | "superseded";
+export interface ClassifiedCheck extends CheckRun {
+    category: CheckCategory;
+}
+export interface TriagedCheck extends ClassifiedCheck {
+    /** Workflow display name (e.g. `"CI"`). Populated when available from the jobs API; may be `undefined` on fetch failure or when no matching job is found. */
+    workflowName?: string;
+    /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from the check name for matrix builds. */
+    jobName?: string;
+    /** Name of the first failed step in the matched job (e.g. `"Run tests"`). */
+    failedStep?: string;
+    /** Bounded raw excerpt from the matched failed job log, when GitHub exposes one. */
+    logExcerpt?: string;
+    /** Inline annotations attached to this failing check run, surfaced once per PR. */
+    annotations?: CheckAnnotation[];
+}
+export {};

package/bin/types/github.d.mts

@@ -0,0 +1,136 @@
+import type { ReviewThreadComment } from "./review-thread.mts";
+import type { PrActivitySummary } from "./activity.mts";
+import type { BatchPrMergeFields, MergeRequirements } from "./merge-requirements.mts";
+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;
+export type AuthorType = "User" | "Bot" | "Unknown";
+/** Raw relationship between a comment author and the repository, as reported by GitHub. */
+export type CommentAuthorAssociation = "COLLABORATOR" | "CONTRIBUTOR" | "FIRST_TIMER" | "FIRST_TIME_CONTRIBUTOR" | "MANNEQUIN" | "MEMBER" | "NONE" | "OWNER";
+export interface CheckRun {
+    /** GitHub node ID for CheckRun contexts. Missing for StatusContext and synthetic checks. */
+    id?: string | null;
+    name: string;
+    status: CheckStatus;
+    conclusion: CheckConclusion;
+    source?: "check_run" | "status_context" | "startup_failure";
+    detailsUrl: string;
+    event: string | null;
+    runId: string | null;
+    createdAtUnix?: number;
+    startedAtUnix?: number;
+    completedAtUnix?: number;
+    updatedAtUnix?: number;
+    /** One-line status text shown in the GitHub UI (CheckRun.title or first line of summary; StatusContext.description). */
+    summary?: string;
+    /** Workflow display name for GitHub Actions check runs, when GraphQL exposes it. */
+    workflowName?: string;
+    workflowId?: string;
+}
+export interface ReviewThread {
+    id: string;
+    isResolved: boolean;
+    isOutdated: boolean;
+    isMinimized: boolean;
+    path: string | null;
+    line: number | null;
+    /** Start of the comment's line range. Null for single-line comments (use `line` for both). */
+    startLine: number | null;
+    /** PullRequestReview ID that created the top comment, when GitHub exposes it. */
+    reviewId?: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+    createdAtUnix?: number;
+    comments?: ReviewThreadComment[];
+    /** True when Shepherd re-surfaced this thread because its body changed after first look. */
+    edited?: boolean;
+}
+/** Parsed GitHub ```suggestion block attached to a review thread. */
+export interface SuggestionBlock {
+    /** 1-indexed inclusive start line. Equal to `endLine` for single-line suggestions. */
+    startLine: number;
+    /** 1-indexed inclusive end line. */
+    endLine: number;
+    /** Replacement lines verbatim. Empty array = delete; `[""]` = single blank line. Join with `"\n"` to display as a string. */
+    lines: readonly string[];
+    /** Reviewer login, surfaced so callers can co-credit them in commits. */
+    author: string;
+}
+export interface PrComment {
+    id: string;
+    isMinimized: boolean;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+    createdAtUnix: number;
+}
+export interface Review {
+    id: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    createdAtUnix?: number;
+    edited?: boolean;
+    /** True for bot CR re-surfaced after first look (body unchanged). Terse render. */
+    staleBotCr?: boolean;
+    /** Commit OID the review was made against, when available from GraphQL. */
+    commitOid?: string;
+    /** True when commitOid !== headRefOid AND all associated threads are resolved/outdated. Distinct from `staleBotCr` (time-based). Reviews with no threads are not marked stale. */
+    staleReview?: boolean;
+}
+export interface BranchProtection {
+    requiresApprovingReviews: boolean;
+    requiredApprovingReviewCount: number;
+    requiresConversationResolution: boolean;
+    requiresStatusChecks: boolean;
+    /** Required status check context names (e.g. "ci/build", "ci/test"). Empty when requiresStatusChecks is false, or when requiresStatusChecks is true but GitHub returns no explicit contexts. */
+    requiredStatusCheckContexts: string[];
+}
+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;
+    blockingBotReviewInProgress: boolean;
+    mergeStateStatus: MergeStateStatus;
+    mergeRequirements?: MergeRequirements;
+}
+export interface BatchPrData extends BatchPrMergeFields {
+    nodeId: string;
+    number: number;
+    state: "OPEN" | "CLOSED" | "MERGED";
+    isDraft: boolean;
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+    reviewDecision: ReviewDecision;
+    headRefOid: string;
+    headRefName: string;
+    /** `"owner/name"` of the head repository; null when the fork has been deleted. */
+    headRepoWithOwner: string | null;
+    baseRefName: string;
+    reviewRequests: Array<{
+        login: string;
+    }>;
+    latestReviews: Array<{
+        login: string;
+        state: string;
+    }>;
+    reviewThreads: ReviewThread[];
+    comments: PrComment[];
+    changesRequestedReviews: Review[];
+    reviewSummaries: Review[];
+    approvedReviews: Review[];
+    checks: CheckRun[];
+    branchProtection: BranchProtection | null;
+    activity?: PrActivitySummary;
+}

package/bin/types/iterate.d.mts

@@ -0,0 +1,156 @@
+import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
+import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
+import type { BranchProtection, CheckStatus, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
+import type { MergeRequirements } from "./merge-requirements.mts";
+import type { ProtectedRun } from "./protected-run.mts";
+export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "cancel" | "escalate";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "bot-cr-not-dismissed";
+export interface AgentStalledCheck {
+    name: string;
+    status: CheckStatus;
+    source: "check_run" | "status_context" | "startup_failure";
+    runId: string | null;
+    detailsUrl: string | null;
+    createdAtUnix?: number;
+    startedAtUnix?: number;
+    updatedAtUnix?: number;
+    ageSeconds: number;
+    summary?: string;
+}
+export interface EscalateDetails {
+    triggers: EscalateTrigger[];
+    unresolvedThreads: AgentThread[];
+    ambiguousComments: AgentComment[];
+    changesRequestedReviews: Review[];
+    /** Pending/unstarted CI checks that exceeded the stall timeout. */
+    stalledChecks?: AgentStalledCheck[];
+    /** Populated when fix-thrash triggered — threads that have been attempted too many times. */
+    thrashHistory?: Array<{
+        threadId: string;
+        attempts: number;
+    }>;
+    suggestion: string;
+    humanMessage: string;
+}
+export interface IterateResultSummary {
+    passing: number;
+    skipped: number;
+    filtered: number;
+    inProgress: number;
+    superseded: number;
+}
+export interface IterateResultBase {
+    pr: number;
+    repo: string;
+    status: ShepherdStatus;
+    state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
+    mergeStateStatus: MergeStateStatus;
+    mergeStatus: ShepherdMergeStatus;
+    reviewDecision: ReviewDecision;
+    blockingBotReviewInProgress: boolean;
+    isDraft: boolean;
+    shouldCancel: boolean;
+    remainingSeconds: number;
+    summary: IterateResultSummary;
+    /** Validated base branch (e.g. "main") for this PR. */
+    baseBranch: string;
+    /** Null when no classic protection rule exists or the base ref is unavailable. */
+    branchProtection: BranchProtection | null;
+    mergeRequirements?: MergeRequirements;
+    /**
+     * PR-event checks that completed and are not skipped/neutral.
+     * Failing entries carry `workflowName`, `jobName`, `failedStep`, and `summary`.
+     */
+    checks: RelevantCheck[];
+    inProgressChecks?: ActiveCheck[];
+    ignoredNames?: string[];
+    supersededNames?: string[];
+    activity?: PrActivitySummary;
+}
+interface IterateResultWait extends IterateResultBase {
+    action: "wait";
+    log: string;
+}
+export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
+interface IterateResultCancel extends IterateResultBase {
+    action: "cancel";
+    reason: CancelReason;
+    log: string;
+}
+export interface ResolveCommand {
+    /** Argv for spawn-style execution. May contain a `$DISMISS_MESSAGE` placeholder. `$HEAD_SHA` is never in `argv` — `renderResolveCommand` (from `commands/iterate/render.mts`) appends `--require-sha "$HEAD_SHA"` when rendering if `requiresHeadSha` is true. Use `renderResolveCommand` to render as a command string; don't naive-join. */
+    argv: string[];
+    /** When true, `renderResolveCommand` appends `--require-sha "$HEAD_SHA"` to the rendered command. */
+    requiresHeadSha: boolean;
+    /** Whether the model must substitute $DISMISS_MESSAGE with a specific description of the fix. */
+    requiresDismissMessage: boolean;
+    /** Thread IDs that should receive a reply instead of a resolve mutation. */
+    replyThreadIds?: string[];
+    /** Thread IDs that should be resolved on GitHub. Human-authored IDs must not appear here. */
+    resolveThreadIds?: string[];
+    /** Bot/non-human CHANGES_REQUESTED review IDs to dismiss. Human-authored IDs must not appear here. */
+    dismissReviewIds?: string[];
+    /** True when any mutation flag was appended (threads/comments/reviews). False for a bare runner-specific `pr-shepherd apply review <PR>` with nothing to do. Callers use this to gate emitting an apply instruction — coupling to argv length would break silently if the base argv ever grew a global flag. */
+    hasMutations: boolean;
+}
+/**
+ * Default fix_code variant: agent applies edits locally, commits, pushes,
+ * then runs the pre-built apply command. Emitted under `## Post-fix push`.
+ */
+interface FixRebaseAndPush {
+    threads: AgentThread[];
+    /** Unresolved threads that should be resolved on GitHub without requiring code edits. */
+    resolutionOnlyThreads: ReviewThread[];
+    /** PR comment bodies surfaced to the agent for evaluation, including previously filtered bot/noise comments; do not treat `actionableComments.length` as a proxy for "must push code". */
+    actionableComments: AgentComment[];
+    /** Review IDs (COMMENTED summaries and, if opted in, APPROVED reviews) to minimize — no code change needed. */
+    reviewSummaryIds: string[];
+    /** COMMENTED review summaries surfaced to the agent for the first time this iteration — body shown inline. */
+    firstLookSummaries: Review[];
+    /** COMMENTED review summaries whose body changed since the agent first saw them. Body shown inline; IDs not in `reviewSummaryIds`. */
+    editedSummaries: Review[];
+    /** APPROVED-state reviews surfaced for visibility (when `iterate.minimizeApprovals` is false). */
+    surfacedApprovals: Review[];
+    checks: AgentCheck[];
+    changesRequestedReviews: Review[];
+    /** Pre-built apply command. Run after committing and pushing. */
+    resolveCommand: ResolveCommand;
+    /** When present, run this command first (no SHA substitution needed) to resolve bot threads and minimize comments, independent of any push. */
+    resolveOnlyCommand?: ResolveCommand;
+    /** Ordered steps for the model to follow. */
+    instructions: string[];
+    /** Run IDs of in-progress GitHub Actions checks. The agent should cancel these before pushing new commits; if it decides not to push (e.g. resolve-only), it may skip cancellation. Empty when all in-progress runs are external status checks or already cancelled. */
+    inProgressRunIds: string[];
+    /** Workflow runs deliberately excluded from cancellation by actions.neverCancelRuns. */
+    protectedRuns: ProtectedRun[];
+    /** First-look threads — previously hidden, surfaced for acknowledgment only. */
+    firstLookThreads: FirstLookThread[];
+    /** First-look comments — previously hidden, surfaced for acknowledgment only. */
+    firstLookComments: FirstLookComment[];
+}
+export interface IterateResultFixCode extends IterateResultBase {
+    action: "fix_code";
+    fix: FixRebaseAndPush;
+    cancelled: string[];
+}
+interface IterateResultMarkReady extends IterateResultBase {
+    action: "mark_ready";
+    markedReady: boolean;
+    log: string;
+}
+interface IterateResultEscalate extends IterateResultBase {
+    action: "escalate";
+    escalate: EscalateDetails;
+}
+export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultEscalate;
+export interface IterateCommandOptions extends GlobalOptions {
+    readyDelaySeconds?: number;
+    noAutoMarkReady?: boolean;
+    noAutoCancelActionable?: boolean;
+    /** Override stall timeout seconds. Defaults to config.iterate.stallTimeoutMinutes * 60. */
+    stallTimeoutSeconds?: number;
+    /** Case-insensitive workflow/check glob patterns Shepherd must not cancel. */
+    neverCancelRuns?: string[];
+    persistSeen?: boolean;
+}
+export {};

package/bin/types/merge-requirements.d.mts

@@ -0,0 +1,82 @@
+/** Branch-rule and "why can't I merge" types shared by batch data and merge status. */
+export interface BranchRules {
+    requiredApprovingReviewCount: number;
+    requiresConversationResolution: boolean;
+    requiresCodeOwnerReviews: boolean;
+    requiresLastPushApproval: boolean;
+    requiresCommitSignatures: boolean;
+    requiresLinearHistory: boolean;
+    requiresStrictStatusChecks: boolean;
+    requiredStatusCheckContexts: string[];
+    requiredDeploymentEnvironments: string[];
+    requiresMergeQueue: boolean;
+    requiresWorkflows: boolean;
+    requiresCodeScanning: boolean;
+}
+export interface MergeQueueEntryStatus {
+    position: number;
+    state: string;
+    estimatedTimeToMerge: number | null;
+}
+export interface StackStatus {
+    number: number;
+    size: number;
+    position: number;
+    baseRefName: string;
+}
+/** Extra batch-PR fields for merge-queue, stacks, and folded branch rules. */
+export interface BatchPrMergeFields {
+    branchRules?: BranchRules;
+    isInMergeQueue?: boolean;
+    isMergeQueueEnabled?: boolean;
+    mergeQueueEntry?: MergeQueueEntryStatus | null;
+    stack?: StackStatus | null;
+}
+/** Snapshot of "why can't I merge" requirements vs current PR state. */
+export interface MergeRequirements {
+    approvals: {
+        current: number;
+        requiredCount: number;
+    };
+    conversationsResolved: {
+        resolved: boolean;
+        unresolvedCount: number;
+        required: boolean;
+    };
+    codeOwnerReview?: {
+        required: true;
+    };
+    lastPushApproval?: {
+        required: true;
+    };
+    signedCommits?: {
+        required: true;
+    };
+    linearHistory?: {
+        required: true;
+    };
+    branchUpToDate?: {
+        current: boolean;
+        required: true;
+    };
+    requiredStatusChecks?: {
+        contexts: string[];
+    };
+    requiredDeployments?: {
+        environments: string[];
+    };
+    requiredWorkflows?: {
+        required: true;
+    };
+    codeScanning?: {
+        required: true;
+    };
+    mergeQueue?: {
+        required: boolean;
+        enabled: boolean;
+        inQueue: boolean;
+        position?: number;
+        state?: string;
+    };
+    stack?: StackStatus;
+}

package/bin/types/merge-requirements.mjs

@@ -0,0 +1,2 @@
+/** Branch-rule and "why can't I merge" types shared by batch data and merge status. */
+export {};

package/bin/types/protected-run.d.mts

@@ -0,0 +1,6 @@
+export interface ProtectedRun {
+    runId: string;
+    matchedPattern: string;
+    checkNames: string[];
+    workflowName?: string;
+}