pr-shepherd 0.9.0 → 0.10.0

package/bin/reporters/text.mjs

@@ -1,167 +1,146 @@
 import { buildCheckInstructions } from "./check-instructions.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "../cli/list-formatters.mjs";
+import { joinSections } from "../util/markdown.mjs";
 export function formatText(report) {
-    const parts = [];
-    parts.push(`\nPR #${report.pr} — ${report.repo}`);
-    parts.push(`Status: ${report.status}`);
-    parts.push(`Base: ${report.baseBranch}`);
-    parts.push("");
+    const header = [
+        `# PR #${report.pr} [CHECK] — ${report.repo}`,
+        `Status: ${report.status}`,
+        `Base: ${report.baseBranch}`,
+    ].join("\n");
     const ms = report.mergeStatus;
-    parts.push("## Merge Status");
-    parts.push("");
-    parts.push(`${ms.status}`);
-    parts.push(`  mergeStateStatus:        ${ms.mergeStateStatus}`);
-    parts.push(`  mergeable:               ${ms.mergeable}`);
-    parts.push(`  reviewDecision:          ${ms.reviewDecision ?? "(none)"}`);
-    parts.push(`  isDraft:                 ${ms.isDraft}`);
-    parts.push(`  copilotReviewInProgress: ${ms.copilotReviewInProgress}`);
-    parts.push("");
+    const mergeStatusSection = [
+        "## Merge Status",
+        "",
+        `- status: \`${ms.status}\``,
+        `- mergeStateStatus: \`${ms.mergeStateStatus}\``,
+        `- mergeable: \`${ms.mergeable}\``,
+        `- reviewDecision: \`${ms.reviewDecision ?? "(none)"}\``,
+        `- isDraft: \`${ms.isDraft}\``,
+        `- copilotReviewInProgress: \`${ms.copilotReviewInProgress}\``,
+    ].join("\n");
     const { passing, failing, inProgress, skipped } = report.checks;
     const total = passing.length + failing.length + inProgress.length + skipped.length;
-    parts.push("## CI Checks");
-    parts.push("");
-    parts.push(`${passing.length}/${total} passed`);
-    parts.push("");
+    const ciSubsections = [`${passing.length}/${total} passed`];
     if (failing.length > 0) {
-        parts.push(`### Failed (${failing.length})`);
-        parts.push("");
+        const lines = [`### Failed (${failing.length})`, ""];
         for (const c of failing) {
             const triaged = c;
             const prefix = triaged.workflowName ? `${triaged.workflowName} › ` : "";
-            parts.push(`- ${prefix}${c.name}: ${c.conclusion ?? c.status}`);
+            lines.push(`- ${prefix}${c.name}: ${c.conclusion ?? c.status}`);
             if (triaged.failedStep) {
-                parts.push(`    failed step: ${triaged.failedStep}`);
+                lines.push(`    failed step: ${triaged.failedStep}`);
             }
             if (triaged.summary) {
-                parts.push(`    summary: ${triaged.summary}`);
+                lines.push(`    summary: ${triaged.summary}`);
             }
         }
-        parts.push("");
+        ciSubsections.push(lines.join("\n"));
     }
     if (inProgress.length > 0) {
-        parts.push(`### In Progress (${inProgress.length})`);
-        parts.push("");
+        const lines = [`### In Progress (${inProgress.length})`, ""];
         for (const c of inProgress) {
-            parts.push(`- ${c.name}: ${c.status}`);
+            lines.push(`- ${c.name}: ${c.status}`);
         }
-        parts.push("");
+        ciSubsections.push(lines.join("\n"));
     }
     if (skipped.length > 0) {
-        parts.push(`### Skipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
-        parts.push("");
+        ciSubsections.push(`### Skipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
     }
     if (report.checks.filtered.length > 0) {
-        parts.push(`### Filtered non-PR-trigger (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`);
-        parts.push("");
+        const lines = [
+            `### Filtered non-PR-trigger (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`,
+            "",
+        ];
         if (report.checks.blockedByFilteredCheck) {
-            parts.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.");
+            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") {
-            parts.push("  Note: one or more of these filtered checks may be a required status check blocking merge.");
+            lines.push("> Note: one or more of these filtered checks may be a required status check blocking merge.");
         }
-        parts.push("");
+        ciSubsections.push(lines.join("\n"));
     }
+    const ciSection = `## CI Checks\n\n${ciSubsections.join("\n\n")}`;
     const { actionable: actionableThreads, autoResolved, autoResolveErrors, firstLook: firstLookThreads, } = report.threads;
     const hasThreadSection = autoResolved.length > 0 || autoResolveErrors.length > 0 || actionableThreads.length > 0;
+    let threadsSection = null;
     if (hasThreadSection) {
-        parts.push("## Review Threads");
-        parts.push("");
+        const subparts = [];
         if (autoResolved.length > 0) {
-            parts.push(`Auto-resolved outdated (${autoResolved.length}):`);
+            const lines = [`Auto-resolved outdated (${autoResolved.length}):`];
             for (const t of autoResolved) {
-                parts.push(`- threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+                lines.push(renderThreadBullet(t));
             }
-            parts.push("");
+            subparts.push(lines.join("\n"));
         }
         if (autoResolveErrors.length > 0) {
-            parts.push(`Auto-resolve errors (${autoResolveErrors.length}):`);
+            const lines = [`Auto-resolve errors (${autoResolveErrors.length}):`];
             for (const e of autoResolveErrors) {
-                parts.push(`- ${e}`);
+                lines.push(`- ${e}`);
             }
-            parts.push("");
+            subparts.push(lines.join("\n"));
         }
         if (actionableThreads.length > 0) {
-            parts.push(`### Actionable (${actionableThreads.length})`);
-            parts.push("");
+            const lines = [`### Actionable (${actionableThreads.length})`, ""];
             for (const t of actionableThreads) {
-                const label = t.path ? `${t.path}:${t.line ?? "?"}` : "(general)";
-                parts.push(`- threadId=${t.id} ${label} (@${t.author})`);
-                parts.push(`  ${firstLine(t.body)}`);
+                lines.push(renderThreadBullet(t));
             }
-            parts.push("");
+            subparts.push(lines.join("\n"));
         }
+        threadsSection = `## Review Threads\n\n${subparts.join("\n\n")}`;
     }
     const { actionable: actionableComments, firstLook: firstLookComments } = report.comments;
+    let commentsSection = null;
     if (actionableComments.length > 0) {
-        parts.push("## PR Comments");
-        parts.push("");
-        parts.push(`### Actionable (${actionableComments.length})`);
-        parts.push("");
+        const lines = [`### Actionable (${actionableComments.length})`, ""];
         for (const c of actionableComments) {
-            parts.push(`- commentId=${c.id} (@${c.author}): ${firstLine(c.body)}`);
+            lines.push(renderCommentBullet(c));
         }
-        parts.push("");
-    }
-    if (report.changesRequestedReviews.length > 0) {
-        parts.push("## CHANGES_REQUESTED Reviews");
-        parts.push("");
-        for (const r of report.changesRequestedReviews) {
-            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
-        }
-        parts.push("");
-    }
-    if (report.reviewSummaries.length > 0) {
-        parts.push("## Review Summaries");
-        parts.push("");
-        for (const r of report.reviewSummaries) {
-            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
-        }
-        parts.push("");
-    }
-    if (report.approvedReviews.length > 0) {
-        parts.push("## Approved Reviews");
-        parts.push("");
-        for (const r of report.approvedReviews) {
-            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
-        }
-        parts.push("");
+        commentsSection = `## PR Comments\n\n${lines.join("\n")}`;
     }
+    const changesRequestedSection = reviewListSection("CHANGES_REQUESTED Reviews", report.changesRequestedReviews);
+    const reviewSummariesSection = reviewListSection("Review Summaries", report.reviewSummaries);
+    const approvedReviewsSection = reviewListSection("Approved Reviews", report.approvedReviews);
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    let firstLookSection = null;
     if (firstLookTotal > 0) {
-        parts.push("## First-look items");
-        parts.push("");
+        const lines = [
+            `## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`,
+            "",
+        ];
         for (const t of firstLookThreads) {
-            const statusTag = t.autoResolved
-                ? `[status: outdated, auto-resolved]`
-                : `[status: ${t.firstLookStatus}]`;
-            const loc = t.path ? `${t.path}:${t.line ?? "?"}` : "(no location)";
-            parts.push(`- threadId=${t.id} ${loc} (@${t.author}) ${statusTag}`);
-            parts.push(`  ${firstLine(t.body)}`);
+            lines.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of firstLookComments) {
-            parts.push(`- commentId=${c.id} (@${c.author}) [status: minimized]`);
-            parts.push(`  ${firstLine(c.body)}`);
+            lines.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
         }
-        parts.push("");
+        firstLookSection = lines.join("\n");
     }
     const totalActionable = actionableThreads.length + actionableComments.length + report.changesRequestedReviews.length;
-    parts.push("## Summary");
-    parts.push("");
     const counts = [];
     if (totalActionable > 0)
         counts.push(`${totalActionable} actionable`);
     if (firstLookTotal > 0)
         counts.push(`${firstLookTotal} first-look`);
     const summaryLine = counts.join(", ") || "0 actionable — all threads resolved/minimized";
-    parts.push(summaryLine);
-    parts.push("");
-    parts.push("## Instructions");
-    parts.push("");
+    const summarySection = `## Summary\n\n${summaryLine}`;
     const instructions = buildCheckInstructions(report);
-    instructions.forEach((step, i) => {
-        parts.push(`${i + 1}. ${step}`);
-    });
-    return parts.join("\n");
+    const instructionsSection = `## Instructions\n\n${instructions.map((step, i) => `${i + 1}. ${step}`).join("\n")}`;
+    return joinSections([
+        header,
+        mergeStatusSection,
+        ciSection,
+        threadsSection,
+        commentsSection,
+        changesRequestedSection,
+        reviewSummariesSection,
+        approvedReviewsSection,
+        firstLookSection,
+        summarySection,
+        instructionsSection,
+    ]);
 }
-function firstLine(text) {
-    return (text.split("\n")[0] ?? "").trim().slice(0, 120);
+function reviewListSection(heading, items) {
+    if (items.length === 0)
+        return null;
+    return `## ${heading}\n\n${items.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n")}`;
 }

package/bin/state/base.mjs

@@ -0,0 +1,5 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+export function resolveStateBase() {
+    return process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+}

package/bin/state/fix-attempts.mjs

@@ -10,8 +10,8 @@
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -62,6 +62,6 @@ function resolvePath(key) {
             throw new Error(`Invalid state key segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const base = resolveStateBase();
     return join(base, `${key.owner}-${key.repo}`, String(key.pr), "fix-attempts.json");
 }

package/bin/state/iterate-stall.mjs

@@ -10,8 +10,8 @@
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -69,6 +69,6 @@ function resolvePath(key) {
             throw new Error(`Invalid state key segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const base = resolveStateBase();
     return join(base, `${key.owner}-${key.repo}`, String(key.pr), "iterate-stall.json");
 }

package/bin/state/seen-comments.mjs

@@ -1,7 +1,7 @@
 import { readFile, writeFile, mkdir, access, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
-import { tmpdir } from "node:os";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -65,7 +65,7 @@ function resolveDir(key) {
             throw new Error(`Invalid state key segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const base = resolveStateBase();
     return join(base, `${key.owner}-${key.repo}`, String(key.pr), "seen");
 }
 function resolvePath(key, id) {

package/bin/suggestions/extract.mjs

@@ -0,0 +1,15 @@
+import { parseSuggestion } from "./parse.mjs";
+export function extractSuggestion(thread) {
+    if (!thread.path || thread.line === null)
+        return null;
+    const parsed = parseSuggestion(thread.body);
+    if (!parsed)
+        return null;
+    const startLine = thread.startLine ?? thread.line;
+    return {
+        startLine,
+        endLine: thread.line,
+        lines: parsed.lines,
+        author: thread.author,
+    };
+}

package/bin/suggestions/parse.mjs

@@ -3,8 +3,7 @@
  *
  * GitHub's "Commit suggestion" UI button treats the first ```suggestion fenced
  * block in a review comment as a replacement for the commented line range.
- * This module extracts that block from the comment body, plus applies a
- * parsed suggestion to a file's contents.
+ * This module extracts that block from the comment body.
  *
  * There is no GitHub API for applying suggestions — tools that reproduce the
  * button (this one included) must parse + commit themselves.
@@ -93,27 +92,3 @@ export function isCommittableSuggestion(parsed) {
     const fenceRuns = (replacement.match(/`{3,}/g) ?? []).length;
     return fenceRuns % 2 === 0;
 }
-/**
- * Apply a suggestion to a file's full contents by replacing lines
- * [startLine..endLine] (1-indexed, inclusive) with the given replacement lines.
- *
- * Pass `[]` to delete the range, `[""]` to replace with a single blank line,
- * or `["a", "b", ...]` for arbitrary replacements. The file's trailing-newline
- * state is preserved exactly.
- */
-export function applySuggestionToFile(fileContent, startLine, endLine, replacementLines) {
-    if (startLine < 1 || endLine < startLine) {
-        throw new Error(`Invalid line range: start=${startLine}, end=${endLine}`);
-    }
-    const endsWithNewline = fileContent.endsWith("\n");
-    // Strip a single trailing \n so split/join round-trips exactly.
-    const body = endsWithNewline ? fileContent.slice(0, -1) : fileContent;
-    const lines = body.split("\n");
-    if (endLine > lines.length) {
-        throw new Error(`Line ${endLine} is out of range (file has ${lines.length} line(s))`);
-    }
-    const before = lines.slice(0, startLine - 1);
-    const after = lines.slice(endLine);
-    const result = [...before, ...replacementLines, ...after].join("\n");
-    return endsWithNewline ? `${result}\n` : result;
-}

package/bin/util/markdown.mjs

@@ -0,0 +1,7 @@
+export function joinSections(sections) {
+    return sections
+        .filter((s) => s != null)
+        .map((s) => s.replace(/^[\r\n]+|[\r\n]+$/g, ""))
+        .filter((s) => s !== "")
+        .join("\n\n");
+}

package/bin/util/worktree.mjs

@@ -0,0 +1,23 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { SAFE_SEGMENT } from "./path-segment.mjs";
+const execFile = promisify(execFileCb);
+/** Returns the absolute path to the current git worktree root. Throws outside a git repo. */
+export async function getWorktreeRoot() {
+    const { stdout } = await execFile("git", ["rev-parse", "--show-toplevel"]);
+    return stdout.trim();
+}
+/**
+ * Returns a filesystem-safe key for the current worktree, unique across
+ * worktrees of the same repo. Format: `<basename>-<sha8>` where sha8 is
+ * the first 8 hex chars of sha256(toplevel). Falls back to sha8-only if
+ * the basename contains characters outside SAFE_SEGMENT.
+ */
+export async function getWorktreeKey() {
+    const root = await getWorktreeRoot();
+    const sha8 = createHash("sha256").update(root).digest("hex").slice(0, 8);
+    const base = basename(root);
+    return SAFE_SEGMENT.test(base) ? `${base}-${sha8}` : sha8;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -24,7 +24,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "oxfmt": "^0.45.0",
+    "oxfmt": "^0.46.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4",

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

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

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

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

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

@@ -1,32 +0,0 @@
-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/bin/github/gql/resolve-thread.gql

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