pr-shepherd 0.35.0 → 0.37.0

package/bin/state/seen-comments.mjs

@@ -3,7 +3,7 @@ import { readFile, writeFile, rename, unlink, mkdir, access, readdir } from "nod
 import { join, dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
-import { resolveStateBase } from "./base.mjs";
+import { resolvePrStatePath } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -57,7 +57,9 @@ export async function loadSeenMap(key) {
     try {
         const dir = resolveDir(key);
         const entries = await readdir(dir);
-        for (const entry of entries.filter((e) => e.endsWith(".json"))) {
+        for (const entry of entries) {
+            if (!entry.endsWith(".json") || !SAFE_SEGMENT.test(entry))
+                continue;
             try {
                 const raw = await readFile(join(dir, entry), "utf8");
                 const marker = JSON.parse(raw);
@@ -182,16 +184,7 @@ export async function readSeenMarker(key, id) {
 // Helpers
 // ---------------------------------------------------------------------------
 function resolveDir(key) {
-    for (const [field, value] of [
-        ["owner", key.owner],
-        ["repo", key.repo],
-    ]) {
-        if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid state key segment "${field}": ${value}`);
-        }
-    }
-    const base = resolveStateBase();
-    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "seen");
+    return resolvePrStatePath(key, "seen");
 }
 function resolvePath(key, id) {
     if (!SAFE_SEGMENT.test(id)) {
@@ -203,5 +196,5 @@ function resolvePath(key, id) {
     // causing seen-markers to overwrite each other and items to re-surface every
     // tick. SHA-256 is case-sensitive so distinct IDs get distinct files.
     const hash = createHash("sha256").update(id, "utf8").digest("hex");
-    return join(resolveDir(key), `${hash}.json`);
+    return resolvePrStatePath(key, "seen", `${hash}.json`);
 }

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

@@ -3,6 +3,8 @@ import type { CheckRun } from "./github.mts";
 type CheckCategory = "passed" | "failing" | "in_progress" | "skipped" | "filtered" | "ignored" | "superseded";
 export interface ClassifiedCheck extends CheckRun {
     category: CheckCategory;
+    /** Inline annotations attached to this check run, surfaced once per PR. */
+    annotations?: CheckAnnotation[];
 }
 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. */
@@ -13,7 +15,5 @@ export interface TriagedCheck extends ClassifiedCheck {
     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

@@ -1,5 +1,6 @@
 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";
@@ -27,6 +28,8 @@ export interface CheckRun {
     /** Workflow display name for GitHub Actions check runs, when GraphQL exposes it. */
     workflowName?: string;
     workflowId?: string;
+    /** True when GraphQL reported at least one CheckRun annotation. Omitted when false. */
+    hasAnnotations?: boolean;
 }
 export interface ReviewThread {
     id: string;
@@ -49,12 +52,7 @@ export interface ReviewThread {
     /** 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 when the
- * reviewer left a machine-applicable replacement. The `lines` are the
- * exact text the agent (or the CLI's commit-suggestions path) would write
- * into the file in place of lines [startLine..endLine].
- */
+/** 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;
@@ -107,8 +105,9 @@ export interface MergeStatusResult {
     reviewDecision: ReviewDecision;
     blockingBotReviewInProgress: boolean;
     mergeStateStatus: MergeStateStatus;
+    mergeRequirements?: MergeRequirements;
 }
-export interface BatchPrData {
+export interface BatchPrData extends BatchPrMergeFields {
     nodeId: string;
     number: number;
     state: "OPEN" | "CLOSED" | "MERGED";

package/bin/types/iterate.d.mts

@@ -1,6 +1,7 @@
 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";
@@ -53,15 +54,12 @@ export interface IterateResultBase {
     summary: IterateResultSummary;
     /** Validated base branch (e.g. "main") for this PR. */
     baseBranch: string;
-    /** Branch protection rule for the PR's base branch. Null when no rule exists or the base ref is unavailable. */
+    /** Null when no classic protection rule exists or the base ref is unavailable. */
     branchProtection: BranchProtection | null;
+    mergeRequirements?: MergeRequirements;
     /**
-     * All CI checks that are relevant to PR readiness: triggered by a PR event
-     * (pull_request / pull_request_target, or StatusContext with null event),
-     * completed (status === COMPLETED), and not skipped/neutral.
-     *
-     * Includes both passing and failing checks. Failing entries carry
-     * `workflowName`, `jobName`, `failedStep`, and `summary`.
+     * PR-event checks that completed and are not skipped/neutral.
+     * Failing entries carry `workflowName`, `jobName`, `failedStep`, and `summary`.
      */
     checks: RelevantCheck[];
     inProgressChecks?: ActiveCheck[];
@@ -153,5 +151,6 @@ export interface IterateCommandOptions extends GlobalOptions {
     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/report.d.mts

@@ -32,6 +32,8 @@ export interface ShepherdReport {
         skipped: ClassifiedCheck[];
         /** Checks filtered out because they were triggered by a non-PR event (push, schedule, etc.). */
         filtered: ClassifiedCheck[];
+        /** Ignored checks with unseen annotations; omitted when empty. */
+        ignored?: ClassifiedCheck[];
         filteredNames: string[];
         blockedByFilteredCheck: boolean;
         ignoredNames?: string[];
@@ -104,16 +106,14 @@ export interface AgentComment {
     url: string;
     edited?: boolean;
 }
-/** Check shape emitted to the iterate agent under `fix_code`. Cancelled checks
- * should be handled from `name`/`runId`/`detailsUrl`/`conclusion`; optional
- * workflow/job/step metadata may still be present when available. */
+/** Check shape emitted to the iterate agent under `fix_code`. */
 export interface AgentCheck {
     name: string;
     runId: string | null;
     /** Fallback for checks where runId is null (e.g. external status checks). */
     detailsUrl: string | null;
     /** Raw GitHub check conclusion; may be null for some completed checks from upstream data. */
-    conclusion: Exclude<CheckConclusion, "SKIPPED" | "NEUTRAL">;
+    conclusion: CheckConclusion;
     /** Workflow display name (e.g. `"CI"`). Populated on a best-effort basis when available from the jobs API. */
     workflowName?: string;
     /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from check name for matrix builds. */
@@ -123,8 +123,8 @@ export interface AgentCheck {
     /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
     summary?: string;
     logExcerpt?: string;
-    /** Marker-gated inline annotations from this failing check. */
     annotations?: CheckAnnotation[];
+    annotationOnly?: true;
 }
 /**
  * A single CI check that is relevant to PR readiness — triggered by a PR event

package/bin/types.d.mts

@@ -7,3 +7,4 @@ export * from "./types/agent-thread.mts";
 export * from "./types/check-annotations.mts";
 export * from "./types/report.mts";
 export * from "./types/iterate.mts";
+export * from "./types/merge-requirements.mts";

package/bin/types.mjs

@@ -7,3 +7,4 @@ export * from "./types/agent-thread.mjs";
 export * from "./types/check-annotations.mjs";
 export * from "./types/report.mjs";
 export * from "./types/iterate.mjs";
+export * from "./types/merge-requirements.mjs";

package/bin/util/path-segment.d.mts

@@ -1,2 +1,4 @@
 /** Allowed characters: alphanumeric, hyphen, underscore, dot. Prevents path traversal. */
 export declare const SAFE_SEGMENT: RegExp;
+/** Positive decimal integer. Rejects traversal payloads that stringify as non-digits. */
+export declare const SAFE_PR_NUMBER: RegExp;

package/bin/util/path-segment.mjs

@@ -1,2 +1,4 @@
 /** Allowed characters: alphanumeric, hyphen, underscore, dot. Prevents path traversal. */
 export const SAFE_SEGMENT = /^[a-zA-Z0-9._-]+$/;
+/** Positive decimal integer. Rejects traversal payloads that stringify as non-digits. */
+export const SAFE_PR_NUMBER = /^[1-9][0-9]*$/;

package/bin/util/pool.d.mts

@@ -0,0 +1,2 @@
+/** Bounded concurrent map — used so follow-up GraphQL pages do not burst N posts. */
+export declare function mapPool<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/bin/util/pool.mjs

@@ -0,0 +1,18 @@
+/** Bounded concurrent map — used so follow-up GraphQL pages do not burst N posts. */
+export async function mapPool(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    const results = Array.from({ length: items.length });
+    let next = 0;
+    const workerCount = Math.min(Math.max(1, concurrency), items.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        for (;;) {
+            const i = next;
+            next += 1;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }));
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.35.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.37.0", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.35.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.37.0", "pr-shepherd-mcp"]
   }
 }