pr-shepherd 0.37.1 → 0.37.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.37.1",
+  "version": "0.37.2",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/commands/commit-suggestion-instruction.mjs

@@ -19,9 +19,12 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
     const driftHint = includeDriftHint
         ? "If the patch does not apply because the suggestion drifted, use the manual-fix step below. Do not retry the command."
         : "If the patch does not apply, use the manual-edit step below. Do not retry the command.";
+    const manualStep = includeDriftHint ? "manual-fix step" : "manual-edit step";
     return [
         `For each thread marked \`[suggestion]\` under \`${sectionName}\`, run \`${command}\` to retrieve its patch and suggested commit.`,
         "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 use the ${manualStep} below. Do not retry the command.`,
+        "For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.",
         driftHint,
         "Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.",
     ];

package/bin/commands/commit-suggestion.mjs

@@ -6,6 +6,7 @@ import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/cli
 import { fetchSuggestionThread } from "../github/suggestion-thread.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
+import { getUnsafeSuggestionRangeReason } from "../suggestions/range.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 import { getEffectiveCwd, getExecutionCwd } from "../execution-context.mjs";
@@ -80,6 +81,18 @@ export async function runCommitSuggestion(opts) {
         throw new ShepherdError(`Thread ${opts.threadId} path escapes the working tree.`, EXIT.UNAVAILABLE);
     }
     const originalContent = await readFile(resolvedPath, "utf8");
+    const unsafeRangeReason = getUnsafeSuggestionRangeReason({
+        originalContent,
+        startLine,
+        endLine,
+        replacementLines: parsed.lines,
+    });
+    if (unsafeRangeReason) {
+        const range = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
+        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion does not safely fit GitHub's anchored range ` +
+            `${filePath}:${range}: ${unsafeRangeReason} Refusing to build a patch; inspect the surrounding ` +
+            `source and reviewer intent, then apply the change manually.`, EXIT.UNAVAILABLE);
+    }
     const patch = buildUnifiedDiff({
         path: filePath,
         originalContent,

package/bin/commands/iterate/render.mjs

@@ -68,7 +68,7 @@ isBehind = false) {
         const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
         if (hasSuggestions) {
-            instructions.push("For a manual `[suggestion]` fix, 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.");
+            instructions.push("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.", "When `build-suggestion-patch` refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), do not apply the replacement block verbatim. Inspect the surrounding source and reviewer intent, then make the intended edit manually.");
         }
     }
     if (resolutionOnlyThreads.length > 0) {

package/bin/suggestions/lines.d.mts

@@ -0,0 +1,12 @@
+export declare const normalizeLine: (line: string) => string;
+export declare function splitFileLines(originalContent: string): string[];
+/**
+ * Strip leading/trailing replacement lines that exactly duplicate file lines
+ * immediately outside the anchored range.
+ */
+export declare function analyzeReplacementContext(fileLines: readonly string[], startLine: number, endLine: number, replacementLines: readonly string[]): {
+    leadingLength: number;
+    replacementLines: string[];
+    trailingLength: number;
+};
+export declare function trimReplacementToContext(fileLines: readonly string[], startLine: number, endLine: number, replacementLines: readonly string[]): readonly string[];

package/bin/suggestions/lines.mjs

@@ -0,0 +1,56 @@
+export const normalizeLine = (line) => line.endsWith("\r") ? line.slice(0, -1) : line;
+function linesEqual(left, right) {
+    return (left.length === right.length &&
+        left.every((line, index) => normalizeLine(line) === normalizeLine(right[index])));
+}
+export function splitFileLines(originalContent) {
+    const body = originalContent.endsWith("\n") ? originalContent.slice(0, -1) : originalContent;
+    return originalContent === "" ? [] : body.split("\n");
+}
+function retainsBoundaryAnchor(replacementLines, removedLines) {
+    return (removedLines.length > 0 &&
+        (linesEqual(replacementLines.slice(0, removedLines.length), removedLines) ||
+            linesEqual(replacementLines.slice(-removedLines.length), removedLines)));
+}
+function largestPermittedContextTrim({ maxLength, matchesContext, remainingAfterTrim, mustRetainAnchor, removedLines, }) {
+    for (let length = maxLength; length >= 1; length--) {
+        if (!matchesContext(length))
+            continue;
+        if (mustRetainAnchor && !retainsBoundaryAnchor(remainingAfterTrim(length), removedLines)) {
+            continue;
+        }
+        return length;
+    }
+    return 0;
+}
+/**
+ * Strip leading/trailing replacement lines that exactly duplicate file lines
+ * immediately outside the anchored range.
+ */
+export function analyzeReplacementContext(fileLines, startLine, endLine, replacementLines) {
+    const removedLines = fileLines.slice(startLine - 1, endLine);
+    const leadingMayBeAnchor = removedLines.length > 0 &&
+        linesEqual(replacementLines.slice(0, removedLines.length), removedLines);
+    const leadingLength = largestPermittedContextTrim({
+        maxLength: Math.min(startLine - 1, replacementLines.length),
+        matchesContext: (length) => linesEqual(replacementLines.slice(0, length), fileLines.slice(startLine - 1 - length, startLine - 1)),
+        remainingAfterTrim: (length) => replacementLines.slice(length),
+        mustRetainAnchor: leadingMayBeAnchor,
+        removedLines,
+    });
+    const remainder = replacementLines.slice(leadingLength);
+    const trailingMayBeAnchor = removedLines.length > 0 && linesEqual(remainder.slice(-removedLines.length), removedLines);
+    const trailingLength = largestPermittedContextTrim({
+        maxLength: Math.min(fileLines.length - endLine, remainder.length),
+        matchesContext: (length) => linesEqual(remainder.slice(-length), fileLines.slice(endLine, endLine + length)),
+        remainingAfterTrim: (length) => remainder.slice(0, -length),
+        mustRetainAnchor: trailingMayBeAnchor,
+        removedLines,
+    });
+    const trimmedLines = trailingLength === 0 ? remainder : remainder.slice(0, -trailingLength);
+    return { leadingLength, replacementLines: trimmedLines, trailingLength };
+}
+export function trimReplacementToContext(fileLines, startLine, endLine, replacementLines) {
+    return analyzeReplacementContext(fileLines, startLine, endLine, replacementLines)
+        .replacementLines;
+}

package/bin/suggestions/patch.mjs

@@ -4,53 +4,10 @@
  * The diff uses `--- a/<path>` / `+++ b/<path>` headers so `git apply` and
  * `git apply --check` accept it without a `diff --git` preamble.
  */
-/**
- * Strip leading/trailing replacement lines that are identical to the adjacent
- * file lines just outside the removed range.
- *
- * GitHub stores a suggestion as a verbatim replacement for the *highlighted*
- * line range, but reviewers often paste surrounding context into the box. Those
- * context-duplicating lines must not appear as additions in the diff — they
- * belong to the surrounding unchanged file content. Stripping them here produces
- * a minimal diff that applies cleanly without duplicating lines.
- *
- * Comparison normalises trailing `\r` from file lines so CRLF files (which
- * carry `\r` on each entry after `split("\n")`) still match suggestion lines
- * delivered as LF-only by the GitHub API.
- */
-function trimReplacementToContext(fileLines, startLine, endLine, replacementLines) {
-    const norm = (s) => (s.endsWith("\r") ? s.slice(0, -1) : s);
-    // Leading trim: largest L where replacement[0..L) == fileLines[startLine-1-L..startLine-1)
-    const maxL = Math.min(startLine - 1, replacementLines.length);
-    let L = 0;
-    leading: for (let l = maxL; l >= 1; l--) {
-        for (let i = 0; i < l; i++) {
-            if (norm(replacementLines[i]) !== norm(fileLines[startLine - 1 - l + i]))
-                continue leading;
-        }
-        L = l;
-        break;
-    }
-    const remainder = replacementLines.slice(L);
-    // Trailing trim: largest T where remainder[len-T..len) == fileLines[endLine..endLine+T)
-    const maxT = Math.min(fileLines.length - endLine, remainder.length);
-    let T = 0;
-    trailing: for (let t = maxT; t >= 1; t--) {
-        for (let j = 0; j < t; j++) {
-            if (norm(remainder[remainder.length - t + j]) !== norm(fileLines[endLine + j]))
-                continue trailing;
-        }
-        T = t;
-        break;
-    }
-    if (L === 0 && T === 0)
-        return replacementLines;
-    return T === 0 ? remainder : remainder.slice(0, remainder.length - T);
-}
+import { splitFileLines, trimReplacementToContext } from "./lines.mjs";
 export function buildUnifiedDiff({ path, originalContent, startLine, endLine, replacementLines, context = 3, }) {
     const endsWithNewline = originalContent.endsWith("\n");
-    const body = endsWithNewline ? originalContent.slice(0, -1) : originalContent;
-    const fileLines = body === "" ? [] : body.split("\n");
+    const fileLines = splitFileLines(originalContent);
     const removedLines = fileLines.slice(startLine - 1, endLine);
     const beforeStart = Math.max(0, startLine - 1 - context);
     const beforeLines = fileLines.slice(beforeStart, startLine - 1);

package/bin/suggestions/range-adjacent.d.mts

@@ -0,0 +1,7 @@
+export declare function getAdjacentSuggestionRangeReason({ fileLines, removedLines, startLine, endLine, replacementLines, }: {
+    fileLines: readonly string[];
+    removedLines: readonly string[];
+    startLine: number;
+    endLine: number;
+    replacementLines: readonly string[];
+}): string | null;

package/bin/suggestions/range-adjacent.mjs

@@ -0,0 +1,100 @@
+import { findLineSequenceOffsets } from "./range-anchor.mjs";
+import { sharesExactProperPrefix, sharesExactProperSuffix } from "./range-exact-overlap.mjs";
+import { likelyRewritesChangedLineSubrange, likelyRewritesAdjacentSpan, } from "./range-similarity.mjs";
+import { createScanWorkBudget } from "./range-work.mjs";
+function adjacentSpansBefore(fileLines, startLine, replacementLineCount) {
+    const endIndex = startLine - 1;
+    const limit = Math.min(endIndex, Math.max(2, replacementLineCount * 2));
+    return Array.from({ length: limit }, (_, index) => fileLines.slice(endIndex - index - 1, endIndex));
+}
+function adjacentSpansAfter(fileLines, endLine, replacementLineCount) {
+    const limit = Math.min(fileLines.length - endLine, Math.max(2, replacementLineCount * 2));
+    return Array.from({ length: limit }, (_, index) => fileLines.slice(endLine, endLine + index + 1));
+}
+function likelyRewritesAdjacentSource(replacementLines, adjacentSpans, allowSingleLinePair) {
+    if (adjacentSpans
+        .slice(0, 8)
+        .some((span) => likelyRewritesAdjacentSpan(replacementLines, span, allowSingleLinePair))) {
+        return true;
+    }
+    return likelyRewritesChangedLineSubrange(replacementLines, adjacentSpans);
+}
+function extensionRewritesAfter(fileLines, endLine, extension) {
+    if (extension.length === 0)
+        return false;
+    const adjacentLines = fileLines.slice(endLine, endLine + extension.length);
+    return (sharesExactProperPrefix(extension, adjacentLines) ||
+        likelyRewritesAdjacentSource(extension, adjacentSpansAfter(fileLines, endLine, extension.length), true));
+}
+function extensionRewritesBefore(fileLines, startLine, extension) {
+    if (extension.length === 0)
+        return false;
+    const adjacentStart = startLine - 1 - extension.length;
+    const adjacentLines = fileLines.slice(Math.max(0, adjacentStart), startLine - 1);
+    return (sharesExactProperSuffix(extension, adjacentLines) ||
+        likelyRewritesAdjacentSource(extension, adjacentSpansBefore(fileLines, startLine, extension.length), true));
+}
+function scanExtension(fileLines, startLine, endLine, extension, direction, chargeScanWork) {
+    const available = direction === "before" ? startLine - 1 : fileLines.length - endLine;
+    if (chargeScanWork(extension.length, available))
+        return "work";
+    const rewrites = direction === "before"
+        ? extensionRewritesBefore(fileLines, startLine, extension)
+        : extensionRewritesAfter(fileLines, endLine, extension);
+    return rewrites ? direction : null;
+}
+function retainedAnchorRewriteDirection(fileLines, removedLines, startLine, endLine, replacementLines, chargeScanWork) {
+    const offsets = findLineSequenceOffsets(replacementLines, removedLines);
+    // Bound repeated extension scans while rejecting ambiguous bodies safely.
+    if (offsets.length * replacementLines.length > 4_096)
+        return "ambiguous";
+    if (offsets.length === 0)
+        return null;
+    for (const offset of offsets) {
+        const before = replacementLines.slice(0, offset);
+        const after = replacementLines.slice(offset + removedLines.length);
+        const scans = [
+            [after, "after"],
+            [after, "before"],
+            [before, "before"],
+            [before, "after"],
+        ];
+        for (const [extension, direction] of scans) {
+            const result = scanExtension(fileLines, startLine, endLine, extension, direction, chargeScanWork);
+            if (result !== null)
+                return result;
+        }
+    }
+    return "safe";
+}
+export function getAdjacentSuggestionRangeReason({ fileLines, removedLines, startLine, endLine, replacementLines, }) {
+    const chargeScanWork = createScanWorkBudget();
+    const retainedAnchorDirection = retainedAnchorRewriteDirection(fileLines, removedLines, startLine, endLine, replacementLines, chargeScanWork);
+    if (retainedAnchorDirection === "after") {
+        return "The replacement retains the complete anchored range and appears to rewrite source immediately after it.";
+    }
+    if (retainedAnchorDirection === "before") {
+        return "The replacement retains the complete anchored range and appears to rewrite source immediately before it.";
+    }
+    if (retainedAnchorDirection === "ambiguous") {
+        return "The replacement repeats the complete anchored range too many times to validate its surrounding source safely.";
+    }
+    if (retainedAnchorDirection === "work") {
+        return "The replacement and adjacent source require too much similarity work to validate the anchored range safely.";
+    }
+    if (retainedAnchorDirection === "safe")
+        return null;
+    if (chargeScanWork(replacementLines.length, startLine - 1)) {
+        return "The replacement and adjacent source require too much similarity work to validate the anchored range safely.";
+    }
+    if (likelyRewritesAdjacentSource(replacementLines, adjacentSpansBefore(fileLines, startLine, replacementLines.length), false)) {
+        return "The replacement partially rewrites a source block before the anchored range.";
+    }
+    if (chargeScanWork(replacementLines.length, fileLines.length - endLine)) {
+        return "The replacement and adjacent source require too much similarity work to validate the anchored range safely.";
+    }
+    if (likelyRewritesAdjacentSource(replacementLines, adjacentSpansAfter(fileLines, endLine, replacementLines.length), false)) {
+        return "The replacement partially rewrites a source block after the anchored range.";
+    }
+    return null;
+}

package/bin/suggestions/range-anchor.d.mts

@@ -0,0 +1 @@
+export declare function findLineSequenceOffsets(lines: readonly string[], sequence: readonly string[]): readonly number[];

package/bin/suggestions/range-anchor.mjs

@@ -0,0 +1,40 @@
+import { normalizeLine } from "./lines.mjs";
+function buildPrefixTable(pattern) {
+    const table = Array.from({ length: pattern.length }, () => 0);
+    let prefixLength = 0;
+    for (let index = 1; index < pattern.length;) {
+        if (pattern[index] === pattern[prefixLength]) {
+            prefixLength++;
+            table[index] = prefixLength;
+            index++;
+        }
+        else if (prefixLength > 0) {
+            prefixLength = table[prefixLength - 1];
+        }
+        else {
+            index++;
+        }
+    }
+    return table;
+}
+export function findLineSequenceOffsets(lines, sequence) {
+    if (sequence.length === 0)
+        return [];
+    const pattern = sequence.map(normalizeLine);
+    const prefixTable = buildPrefixTable(pattern);
+    const offsets = [];
+    let matchedLength = 0;
+    for (let index = 0; index < lines.length; index++) {
+        const line = normalizeLine(lines[index]);
+        while (matchedLength > 0 && line !== pattern[matchedLength]) {
+            matchedLength = prefixTable[matchedLength - 1];
+        }
+        if (line === pattern[matchedLength])
+            matchedLength++;
+        if (matchedLength !== pattern.length)
+            continue;
+        offsets.push(index - pattern.length + 1);
+        matchedLength = prefixTable[matchedLength - 1];
+    }
+    return offsets;
+}

package/bin/suggestions/range-exact-overlap.d.mts

@@ -0,0 +1,2 @@
+export declare function sharesExactProperPrefix(replacementLines: readonly string[], adjacentLines: readonly string[]): boolean;
+export declare function sharesExactProperSuffix(replacementLines: readonly string[], adjacentLines: readonly string[]): boolean;

package/bin/suggestions/range-exact-overlap.mjs

@@ -0,0 +1,28 @@
+import { normalizeLine } from "./lines.mjs";
+function sharedExactPrefixLength(replacementLines, adjacentLines) {
+    const limit = Math.min(replacementLines.length, adjacentLines.length);
+    let length = 0;
+    while (length < limit &&
+        normalizeLine(replacementLines[length]) === normalizeLine(adjacentLines[length])) {
+        length++;
+    }
+    return length;
+}
+function sharedExactSuffixLength(replacementLines, adjacentLines) {
+    const limit = Math.min(replacementLines.length, adjacentLines.length);
+    let length = 0;
+    while (length < limit &&
+        normalizeLine(replacementLines[replacementLines.length - 1 - length]) ===
+            normalizeLine(adjacentLines[adjacentLines.length - 1 - length])) {
+        length++;
+    }
+    return length;
+}
+export function sharesExactProperPrefix(replacementLines, adjacentLines) {
+    const sharedLength = sharedExactPrefixLength(replacementLines, adjacentLines);
+    return sharedLength > 0 && sharedLength < replacementLines.length;
+}
+export function sharesExactProperSuffix(replacementLines, adjacentLines) {
+    const sharedLength = sharedExactSuffixLength(replacementLines, adjacentLines);
+    return sharedLength > 0 && sharedLength < replacementLines.length;
+}

package/bin/suggestions/range-similarity.d.mts

@@ -0,0 +1,2 @@
+export declare function likelyRewritesAdjacentSpan(replacementLines: readonly string[], adjacentLines: readonly string[], allowSingleLinePair: boolean): boolean;
+export declare function likelyRewritesChangedLineSubrange(replacementLines: readonly string[], adjacentSpans: readonly (readonly string[])[]): boolean;

package/bin/suggestions/range-similarity.mjs

@@ -0,0 +1,135 @@
+import { normalizeLine } from "./lines.mjs";
+import { hasLetterOrNumber, isSubstantiveExactAlignedBlock, isSubstantiveLine, isSubstantiveSharedRun, } from "./range-substantive.mjs";
+function closelyRewritesText(replacement, adjacent) {
+    const shorterLength = Math.min(replacement.length, adjacent.length);
+    let prefixLength = 0;
+    while (prefixLength < shorterLength && replacement[prefixLength] === adjacent[prefixLength]) {
+        prefixLength++;
+    }
+    let suffixLength = 0;
+    while (prefixLength + suffixLength < shorterLength &&
+        replacement[replacement.length - 1 - suffixLength] ===
+            adjacent[adjacent.length - 1 - suffixLength]) {
+        suffixLength++;
+    }
+    const sharedLength = prefixLength + suffixLength;
+    return sharedLength >= 12 && sharedLength >= Math.ceil(shorterLength * 0.6);
+}
+function normalizeBlockText(lines) {
+    return lines.map(normalizeLine).join(" ").trim().replace(/\s+/g, " ");
+}
+const normalizeSharedLine = (line) => normalizeLine(line).trim().replace(/\s+/g, " ");
+function sharedInternalRunAt(replacementLines, adjacentLines, replacementStart, adjacentStart) {
+    const sharedLines = [];
+    while (replacementStart + sharedLines.length < replacementLines.length - 1 &&
+        adjacentStart + sharedLines.length < adjacentLines.length - 1) {
+        const replacement = normalizeSharedLine(replacementLines[replacementStart + sharedLines.length]);
+        const adjacent = normalizeSharedLine(adjacentLines[adjacentStart + sharedLines.length]);
+        if (replacement !== adjacent)
+            break;
+        sharedLines.push(replacement);
+    }
+    return sharedLines;
+}
+function hasSubstantiveInternalOverlap(replacementLines, adjacentLines) {
+    if (replacementLines.length < 4 || adjacentLines.length < 4)
+        return false;
+    for (let replacementStart = 1; replacementStart < replacementLines.length - 1; replacementStart++) {
+        for (let adjacentStart = 1; adjacentStart < adjacentLines.length - 1; adjacentStart++) {
+            if (isSubstantiveSharedRun(sharedInternalRunAt(replacementLines, adjacentLines, replacementStart, adjacentStart))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+export function likelyRewritesAdjacentSpan(replacementLines, adjacentLines, allowSingleLinePair) {
+    if (replacementLines.length === 0 || adjacentLines.length === 0)
+        return false;
+    if (!allowSingleLinePair && replacementLines.length === 1 && adjacentLines.length === 1) {
+        return false;
+    }
+    const replacement = normalizeBlockText(replacementLines);
+    const adjacent = normalizeBlockText(adjacentLines);
+    return (replacement === adjacent ||
+        closelyRewritesText(replacement, adjacent) ||
+        hasSubstantiveInternalOverlap(replacementLines, adjacentLines));
+}
+function alignedLineRelation(replacementLine, adjacentLine) {
+    const replacement = normalizeSharedLine(replacementLine);
+    const adjacent = normalizeSharedLine(adjacentLine);
+    if (replacement === adjacent) {
+        const isNeutral = replacement === "" || !hasLetterOrNumber(replacement);
+        return isNeutral || isSubstantiveLine(replacementLine) ? "exact" : null;
+    }
+    if (!isSubstantiveLine(replacementLine) || !isSubstantiveLine(adjacentLine))
+        return null;
+    return closelyRewritesText(replacement, adjacent) ? "changed" : null;
+}
+function isMixedAlignedRewrite(candidate, adjacentSpan) {
+    for (let index = 0; index < candidate.length - 1; index++) {
+        const first = alignedLineRelation(candidate[index], adjacentSpan[index]);
+        const second = alignedLineRelation(candidate[index + 1], adjacentSpan[index + 1]);
+        if ((first === "exact" && second === "changed") ||
+            (first === "changed" && second === "exact")) {
+            return true;
+        }
+    }
+    return false;
+}
+function isChangedWithUnrelatedSubstantiveNeighbors(candidate, adjacentSpan) {
+    const relations = new Set(candidate.map((line, index) => alignedLineRelation(line, adjacentSpan[index])));
+    if (!relations.has("changed") || relations.has("exact"))
+        return false;
+    if (![...candidate, ...adjacentSpan].every((line) => isSubstantiveLine(line) || !hasLetterOrNumber(line))) {
+        return false;
+    }
+    return (candidate.filter((line, index) => isSubstantiveLine(line) && isSubstantiveLine(adjacentSpan[index])).length >= 2);
+}
+function likelyRewritesChangedWindow(replacementLines, adjacentSpan) {
+    const length = adjacentSpan.length;
+    for (let start = 0; start <= replacementLines.length - length; start++) {
+        const candidate = replacementLines.slice(start, start + length);
+        if (isMixedAlignedRewrite(candidate, adjacentSpan))
+            return true;
+        if (isChangedWithUnrelatedSubstantiveNeighbors(candidate, adjacentSpan))
+            return true;
+        const isProperSubrange = start > 0 || start + length < replacementLines.length;
+        if (isProperSubrange && isSubstantiveExactAlignedBlock(candidate, adjacentSpan)) {
+            return true;
+        }
+        if (!candidate.every(isSubstantiveLine) || !adjacentSpan.every(isSubstantiveLine))
+            continue;
+        const hasExactLine = candidate.some((line, index) => normalizeSharedLine(line) === normalizeSharedLine(adjacentSpan[index]));
+        if (length > 8 || hasExactLine)
+            continue;
+        if (likelyRewritesAdjacentSpan(candidate, adjacentSpan, true))
+            return true;
+    }
+    return false;
+}
+export function likelyRewritesChangedLineSubrange(replacementLines, adjacentSpans) {
+    if (replacementLines.length < 2)
+        return false;
+    const adjacentLine = adjacentSpans.find((span) => span.length === 1)?.[0];
+    if (adjacentLine !== undefined && isSubstantiveLine(adjacentLine)) {
+        const adjacent = normalizeSharedLine(adjacentLine);
+        if (replacementLines.some((line) => {
+            if (!isSubstantiveLine(line))
+                return false;
+            const replacement = normalizeSharedLine(line);
+            return replacement !== adjacent && closelyRewritesText(replacement, adjacent);
+        })) {
+            return true;
+        }
+    }
+    const maxLength = Math.min(replacementLines.length, adjacentSpans.length);
+    for (let length = 2; length <= maxLength; length++) {
+        const adjacentSpan = adjacentSpans.find((span) => span.length === length);
+        if (adjacentSpan === undefined)
+            continue;
+        if (likelyRewritesChangedWindow(replacementLines, adjacentSpan))
+            return true;
+    }
+    return false;
+}

package/bin/suggestions/range-substantive.d.mts

@@ -0,0 +1,4 @@
+export declare const hasLetterOrNumber: (line: string) => boolean;
+export declare const isSubstantiveLine: (line: string) => boolean;
+export declare function isSubstantiveSharedRun(sharedLines: readonly string[]): boolean;
+export declare function isSubstantiveExactAlignedBlock(candidate: readonly string[], adjacentLines: readonly string[]): boolean;

package/bin/suggestions/range-substantive.mjs

@@ -0,0 +1,12 @@
+import { normalizeLine } from "./lines.mjs";
+export const hasLetterOrNumber = (line) => /[\p{L}\p{N}]/u.test(line);
+export const isSubstantiveLine = (line) => hasLetterOrNumber(line) && line.replace(/\s/g, "").length >= 8;
+export function isSubstantiveSharedRun(sharedLines) {
+    const substantiveLines = sharedLines.filter(isSubstantiveLine);
+    return substantiveLines.length >= 2 && substantiveLines.join("").replace(/\s/g, "").length >= 24;
+}
+export function isSubstantiveExactAlignedBlock(candidate, adjacentLines) {
+    return (isSubstantiveSharedRun(candidate) &&
+        candidate.every((line, index) => normalizeLine(line).trim().replace(/\s+/g, " ") ===
+            normalizeLine(adjacentLines[index]).trim().replace(/\s+/g, " ")));
+}

package/bin/suggestions/range-work.d.mts

@@ -0,0 +1,2 @@
+export type ChargeScanWork = (replacementLineCount: number, availableLineCount: number) => boolean;
+export declare function createScanWorkBudget(): ChargeScanWork;

package/bin/suggestions/range-work.mjs

@@ -0,0 +1,12 @@
+const MAX_ADJACENT_SCAN_WORK = 1_000_000;
+function estimatedScanWork(replacementLineCount, availableLineCount) {
+    const changedWindowLimit = Math.min(availableLineCount, replacementLineCount);
+    return replacementLineCount * changedWindowLimit ** 2;
+}
+export function createScanWorkBudget() {
+    let work = 0;
+    return (replacementLineCount, availableLineCount) => {
+        work += estimatedScanWork(replacementLineCount, availableLineCount);
+        return work > MAX_ADJACENT_SCAN_WORK;
+    };
+}

package/bin/suggestions/range.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Return why a suggestion body cannot be reconciled safely with GitHub's
+ * anchored line range, or null when the exact range is safe to use.
+ *
+ * The range is authoritative: this validator never shifts or expands it. It
+ * only detects bodies that appear to reach beyond the anchor, leaving manual
+ * interpretation to the caller instead of emitting a structurally unsafe diff.
+ */
+export declare function getUnsafeSuggestionRangeReason({ originalContent, startLine, endLine, replacementLines, }: {
+    originalContent: string;
+    startLine: number;
+    endLine: number;
+    replacementLines: readonly string[];
+}): string | null;

package/bin/suggestions/range.mjs

@@ -0,0 +1,56 @@
+import { analyzeReplacementContext, normalizeLine, splitFileLines } from "./lines.mjs";
+import { getAdjacentSuggestionRangeReason } from "./range-adjacent.mjs";
+import { findLineSequenceOffsets } from "./range-anchor.mjs";
+import { hasLetterOrNumber } from "./range-substantive.mjs";
+function discardedContextContainsAnchorLine({ leadingLength, removedLines, replacementLines, trailingLength, }) {
+    if (removedLines.length < 2)
+        return false;
+    const discardedLines = [
+        ...replacementLines.slice(0, leadingLength),
+        ...replacementLines.slice(replacementLines.length - trailingLength),
+    ];
+    const normalizedAnchorLines = new Set(removedLines.map(normalizeLine).filter(hasLetterOrNumber));
+    return discardedLines.some((line) => normalizedAnchorLines.has(normalizeLine(line)));
+}
+/**
+ * Return why a suggestion body cannot be reconciled safely with GitHub's
+ * anchored line range, or null when the exact range is safe to use.
+ *
+ * The range is authoritative: this validator never shifts or expands it. It
+ * only detects bodies that appear to reach beyond the anchor, leaving manual
+ * interpretation to the caller instead of emitting a structurally unsafe diff.
+ */
+export function getUnsafeSuggestionRangeReason({ originalContent, startLine, endLine, replacementLines, }) {
+    const fileLines = splitFileLines(originalContent);
+    if (!Number.isInteger(startLine) ||
+        !Number.isInteger(endLine) ||
+        startLine < 1 ||
+        endLine < startLine ||
+        endLine > fileLines.length) {
+        return `GitHub reported an invalid or out-of-bounds range (${startLine}-${endLine}) for a ${fileLines.length}-line file.`;
+    }
+    const removedLines = fileLines.slice(startLine - 1, endLine);
+    const contextTrim = analyzeReplacementContext(fileLines, startLine, endLine, replacementLines);
+    if (contextTrim.leadingLength > 0 || contextTrim.trailingLength > 0) {
+        const originalOccurrences = findLineSequenceOffsets(replacementLines, removedLines).length;
+        const trimmedOccurrences = findLineSequenceOffsets(contextTrim.replacementLines, removedLines).length;
+        if (originalOccurrences > trimmedOccurrences) {
+            return "Exact-context trimming would discard a complete copy of the anchored range, so the intended duplicate insertion is ambiguous.";
+        }
+        if (discardedContextContainsAnchorLine({
+            leadingLength: contextTrim.leadingLength,
+            removedLines,
+            replacementLines,
+            trailingLength: contextTrim.trailingLength,
+        })) {
+            return "Exact-context trimming would discard a partial copy of the anchored range, so the intended duplicate insertion is ambiguous.";
+        }
+    }
+    return getAdjacentSuggestionRangeReason({
+        fileLines,
+        removedLines,
+        startLine,
+        endLine,
+        replacementLines: contextTrim.replacementLines,
+    });
+}

package/package.json

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

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

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