pr-shepherd 0.38.1 → 0.40.0

package/bin/journal/reconcile.mjs

@@ -0,0 +1,184 @@
+import { inQuotedHtmlAttribute } from "./markdown-html.mjs";
+import { isSafeMarkdownInsertionPoint, scanMarkdownLines } from "./markdown-line.mjs";
+import { setextParagraphStart } from "./markdown-setext.mjs";
+import { structuralDetailsStart } from "./markdown-structure.mjs";
+const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
+const JOURNAL_SUMMARY = /^<summary>\s*Shepherd\s+Journal\b/i;
+const SETEXT = /^ {0,3}(?:=+|-+)[ \t]*$/;
+const CLOSE = "</details>";
+const OPEN = "<details>";
+const SUMMARY = "<summary>Shepherd Journal</summary>";
+const stripCr = (s) => s.replace(/\r$/, "");
+function detailsTags(line, closing) {
+    if (structuralDetailsStart(line) === null)
+        return 0;
+    const expression = closing ? /<\/details>/gi : /<details(?:\s+[^>]*)?\/?>/gi;
+    return [...line.matchAll(expression)].filter((match) => !inQuotedHtmlAttribute(line, match.index)).length;
+}
+function close(lines, syntax, start) {
+    let depth = 1;
+    for (let i = start; i < lines.length; i++) {
+        if (syntax[i].ignored || syntax[i].nested)
+            continue;
+        const visible = syntax[i].visiblePrefix;
+        if (JOURNAL_SUMMARY.test(visible.trimStart()) || LEGACY.test(visible))
+            return null;
+        depth += detailsTags(visible, false);
+        const closes = detailsTags(visible, true);
+        if (closes) {
+            depth -= closes;
+            if (depth <= 0)
+                return depth === 0 && lines[i] === CLOSE ? i : null;
+        }
+    }
+    return null;
+}
+export function scanShepherdJournal(lines) {
+    const syntax = scanMarkdownLines(lines);
+    const found = [];
+    let detailsDepth = 0;
+    let legacy = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (!syntax[i].ignored &&
+            !syntax[i].nested &&
+            legacy?.end === lines.length &&
+            /^ {0,3}#{1,2}(?:[ \t]+|$)/.test(lines[i])) {
+            if (LEGACY.test(syntax[i].visiblePrefix))
+                return "error";
+            legacy.contentEnd = legacy.end = i;
+            continue;
+        }
+        if (syntax[i].ignored || syntax[i].nested)
+            continue;
+        const visible = syntax[i].visiblePrefix;
+        detailsDepth += detailsTags(visible, false);
+        const closes = detailsTags(visible, true);
+        if (closes) {
+            if (detailsDepth >= closes) {
+                detailsDepth -= closes;
+                continue;
+            }
+            return "error";
+        }
+        if (JOURNAL_SUMMARY.test(visible.trimStart())) {
+            if (lines[i] !== SUMMARY || lines[i - 1] !== OPEN || lines[i + 1] !== "")
+                return "error";
+            const end = close(lines, syntax, i + 2);
+            if (end === null)
+                return "error";
+            detailsDepth--;
+            found.push({
+                contentEnd: end,
+                contentStart: i + 2,
+                end: end + 1,
+                format: "details",
+                start: i - 1,
+            });
+            i = end;
+            continue;
+        }
+        if (LEGACY.test(visible)) {
+            if (legacy)
+                return "error";
+            legacy = {
+                contentEnd: lines.length,
+                contentStart: i + 1,
+                end: lines.length,
+                format: "legacy",
+                start: i,
+            };
+            found.push(legacy);
+            continue;
+        }
+        const start = SETEXT.test(visible) ? setextParagraphStart(lines, syntax, i) : null;
+        if (legacy && legacy.end === lines.length && start !== null && start >= legacy.contentStart) {
+            legacy.contentEnd = legacy.end = start;
+        }
+        if (legacy && legacy.end === lines.length && lines[i].trim() === CLOSE)
+            return "error";
+    }
+    return detailsDepth !== 0 || found.length > 1 ? "error" : (found[0] ?? null);
+}
+function trim(lines) {
+    let a = 0;
+    let b = lines.length;
+    while (a < b && lines[a].trim() === "")
+        a++;
+    while (b > a && lines[b - 1].trim() === "")
+        b--;
+    return lines.slice(a, b);
+}
+function entries(lines) {
+    const result = [];
+    const syntax = scanMarkdownLines(lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line)));
+    let current = null;
+    for (const [index, line] of lines.entries()) {
+        if (syntax[index].visiblePrefix.startsWith("- ")) {
+            if (current)
+                result.push(trim(current));
+            current = [line];
+        }
+        else if (current)
+            current.push(line);
+    }
+    if (current)
+        result.push(trim(current));
+    return result;
+}
+function hasUnrecognizedLeadingContent(lines) {
+    const syntax = scanMarkdownLines(lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line)));
+    const firstEntry = syntax.findIndex((line) => line.visiblePrefix.startsWith("- "));
+    if (firstEntry === -1)
+        return lines.some((line) => line.trim() !== "");
+    return lines.slice(0, firstEntry).some((line) => line.trim() !== "");
+}
+function contains(a, b) {
+    return a.length === b.length && a.every((s, i) => stripCr(s) === stripCr(b[i]));
+}
+export function containsJournalEntry(lines, item) {
+    const target = item.split("\n");
+    return entries(lines).some((entry) => contains(target, entry));
+}
+function fail(reason) {
+    return {
+        error: `${reason}. Supply every live Shepherd Journal entry verbatim, or omit the journal from the supplied body to preserve it automatically.`,
+        ok: false,
+    };
+}
+export function reconcileShepherdJournal(suppliedBody, liveBody) {
+    const liveLines = liveBody.split("\n");
+    const live = scanShepherdJournal(liveBody.replaceAll("\r\n", "\n").split("\n"));
+    const suppliedLines = suppliedBody.split("\n");
+    const supplied = scanShepherdJournal(suppliedBody.replaceAll("\r\n", "\n").split("\n"));
+    if (supplied === "error" || live === "error")
+        return fail("malformed, duplicate, or ambiguous Shepherd Journal container");
+    if (!live)
+        return { body: suppliedBody, ok: true };
+    if (live.format === "details" && supplied?.format === "legacy")
+        return fail("canonical Shepherd Journal details container cannot be downgraded to legacy H2");
+    const liveContent = trim(liveLines.slice(live.contentStart, live.contentEnd));
+    if (!liveContent.length)
+        return { body: suppliedBody, ok: true };
+    if (!supplied) {
+        if (!isSafeMarkdownInsertionPoint(suppliedBody.replaceAll("\r\n", "\n").split("\n")))
+            return fail("supplied body ends inside a Markdown construct that would hide the preserved journal");
+        const journal = liveLines.slice(live.start, live.end).join("\n");
+        const preservedJournal = journal.endsWith("\r") ? `${journal}\n` : journal;
+        return {
+            body: `${suppliedBody}${suppliedBody === "" ? "" : suppliedBody.endsWith("\n") ? "\n" : "\n\n"}${preservedJournal}`,
+            ok: true,
+        };
+    }
+    const liveEntries = entries(liveLines.slice(live.contentStart, live.contentEnd));
+    const liveJournalLines = liveLines.slice(live.contentStart, live.contentEnd);
+    if (!liveEntries.length || hasUnrecognizedLeadingContent(liveJournalLines))
+        return fail("live Shepherd Journal content uses an unrecognized entry format");
+    const target = entries(suppliedLines.slice(supplied.contentStart, supplied.contentEnd));
+    for (const entry of liveEntries) {
+        const match = target.findIndex((candidate) => contains(entry, candidate));
+        if (match === -1)
+            return fail(`supplied Shepherd Journal would drop live entry ${JSON.stringify(entry[0])}`);
+        target.splice(match, 1);
+    }
+    return { body: suppliedBody, ok: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -53,6 +53,10 @@
     "./classify": {
       "types": "./src/classify/types.mts",
       "default": "./bin/classify/types.mjs"
+    },
+    "./journal": {
+      "types": "./bin/journal/index.d.mts",
+      "default": "./bin/journal/index.mjs"
     }
   },
   "scripts": {

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.38.1",
+  "version": "0.40.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.38.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.40.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -19,3 +19,47 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patch`; do not run a shell `pr-shepherd apply` command.
 
 4. After completing the returned instructions, repeat step 2 unless the action is `[CANCEL]` or `[ESCALATE]`, the instructions require a human handoff, or the human directs you to stop.
+
+## Playbooks
+
+`## Instructions` steps reference these playbooks by name instead of repeating their
+mechanics every tick. Apply the referenced playbook in full whenever a step points here.
+
+### Suggestion patches
+
+- The CLI only builds the patch. Apply it, stage the listed file, and follow the returned commit instructions.
+- If the command refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), skip patch application and edit the file manually. Do not retry the command.
+- For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.
+- If the patch does not apply for any other reason, edit the file manually instead. Do not retry the command.
+- After source drift prevents a generated suggestion patch from applying, replace the heading's exact `path:startLine-endLine` range with the `Replaces lines …` block verbatim. An empty replacement deletes the range. One blank line replaces it with one blank line.
+- Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.
+
+### CI failure triage
+
+Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule:
+
+More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
+
+| Tag / kind                                                               | Do                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If missing or insufficient, run a bounded command such as `gh run view <runId> --log-failed \| tail -n 200` — the unbounded form can dump excessive log output into context. Open the run URL only if that still lacks detail. |
+| Transient infrastructure failure                                         | Rerun with `gh run rerun <runId> --failed`.                                                                                                                                                                                                                                      |
+| Real test or build failure                                               | Apply a code fix — do not rerun.                                                                                                                                                                                                                                                 |
+| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered for this conclusion. Run `gh run rerun <runId>` unless this tick will push new commits. Not resolved by a rerun classification — `## Cancelled runs` is a different section.                                                                          |
+| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered for this conclusion. Inspect with `gh run view <runId>`, rerun with `gh run rerun <runId>` if warranted.                                                                                                                                              |
+| `external` (no run ID, has a URL)                                        | Open its URL and inspect it.                                                                                                                                                                                                                                                     |
+
+### Review-mutation mechanics
+
+Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution and the self-reply exclusion rule are separate CLI-printed steps, not covered here, because the printed command is unsafe by default without them.
+
+- Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.
+- Keep every existing `--dismiss-review-ids` ID the CLI already included. Each is a bot or non-human review that must be dismissed; omitting one leaves the PR in `CHANGES_REQUESTED`.
+
+### Review-mutation routing
+
+For threads under `## Review threads to resolve`: human-authored IDs use `--reply-thread-ids` (Shepherd replies instead of resolving them); bot and non-human IDs use `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
+
+### Shepherd Journal
+
+Link threads and comments in a journal entry from their headings in the CLI output. Cite reviews by ID.