@jagreehal/shepherd 0.13.1 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/stack.ts CHANGED
@@ -119,3 +119,137 @@ export function prStack(number: number, repoRoot: string): Stack {
119
119
  range: `${parent?.parentHead ?? baseSha}...${view.headRefOid}`,
120
120
  };
121
121
  }
122
+
123
+ export type Interdiff = {
124
+ since: string;
125
+ head: string;
126
+ /** The PR's own change is the same as at `since`: only the base moved, or nothing did. */
127
+ unchanged: boolean;
128
+ /** Files whose part of the PR's change differs from what was reviewed at `since`. */
129
+ files: string[];
130
+ /** `git range-diff` of the two versions: a diff of the PR's diff, with base movement left out. */
131
+ text: string;
132
+ /** A plain diff of the two versions on one merge base, `+`/`-` meaning changed since `since`: the round's focus. `text` when the old version conflicts on the new base. */
133
+ focus: string;
134
+ };
135
+
136
+ /**
137
+ * How the PR's own change moved between two reviewed heads, free of whatever the base brought in between. Each
138
+ * version is squashed onto its own merge base (`git commit-tree`, which writes an unreferenced commit and no ref),
139
+ * the old one is replayed onto the new merge base (`replay`), and `git range-diff` compares the two squashes.
140
+ * `git diff since..head` would carry every base commit merged since, and after a rebase it compares two unrelated
141
+ * histories; this survives both, and a base edit beside the PR's lines is no change either.
142
+ */
143
+ export function interdiff(since: string, head: string, base: string, git: (...args: string[]) => string, sinceBase?: string): Interdiff {
144
+ const commit = (tree: string, parent: string) => git("-c", "user.name=shepherd", "-c", "user.email=shepherd@localhost", "commit-tree", tree, "-p", parent, "-m", "squash");
145
+
146
+ const ancestor = (a: string, b: string) => {
147
+ try {
148
+ git("merge-base", "--is-ancestor", a, b);
149
+
150
+ return true;
151
+ } catch {
152
+ return false;
153
+ }
154
+ };
155
+
156
+ const squash = (sha: string, from?: string) => {
157
+ const mb = from ?? git("merge-base", base, sha);
158
+
159
+ return { mb, sq: commit(`${sha}^{tree}`, mb) };
160
+ };
161
+
162
+ const b = squash(head);
163
+ // The base tip `since` was reviewed against, when it is still one of since's ancestors: a stacked parent force-pushed
164
+ // since then is no longer an ancestor of the new head, and squashing over today's merge base would carry its old change.
165
+ const a = replay(squash(since, sinceBase && ancestor(sinceBase, since) ? sinceBase : undefined), b.mb, git, commit);
166
+ // --creation-factor=1000: the two squashes always pair, however much they differ. Git's default treats a heavily
167
+ // rewritten one as a removed commit and an added one, and prints their subjects with no patch at all.
168
+ const text = git("range-diff", "--no-color", "--creation-factor=1000", `${a.mb}..${a.sq}`, `${b.mb}..${b.sq}`);
169
+
170
+ return { since, head, unchanged: /^\d+:\s+\S+ = /.test(text), files: rangeDiffFiles(text), text, focus: a.mb === b.mb ? git("diff", "--no-color", "--no-ext-diff", a.sq, b.sq) : text };
171
+ }
172
+
173
+ /**
174
+ * The old version replayed onto the new merge base, so a base edit near the PR's lines does not reach the
175
+ * comparison as changed context. `git merge-tree --merge-base` applies the old squash's change to the new base
176
+ * without touching the index or worktree. When the base moved under the PR's own lines it conflicts, and the old
177
+ * version stays where it was: that change needs a fresh look. Git before 2.40 lacks the flag, and falls back too.
178
+ */
179
+ function replay(old: { mb: string; sq: string }, mb: string, git: (...args: string[]) => string, commit: (tree: string, parent: string) => string) {
180
+ if (old.mb === mb) return old;
181
+
182
+ try {
183
+ return { mb, sq: commit(git("merge-tree", "--write-tree", `--merge-base=${old.mb}`, mb, old.sq), mb) };
184
+ } catch {
185
+ return old;
186
+ }
187
+ }
188
+
189
+ /** range-diff's own sections, never files: the commit message and its metadata. */
190
+ const NOT_FILES = new Set(["Commit message", "Metadata"]);
191
+
192
+ /** A file as a range-diff header names it: `f.ts`, `f.ts (new)`, `old => new` (the path it has now). */
193
+ const headerFile = (v: string) => v.replace(/ \((?:new|deleted|mode change)[^)]*\)$/, "").split(" => ").at(-1)!;
194
+
195
+ /**
196
+ * The files whose part of the PR's change differs between the two versions. The range-diff is read in order: an
197
+ * inner file header (`## f.ts ##`, marked `-`/`+` when the header itself differs) or range-diff's own hunk line
198
+ * (`@@ f.ts`, `@@ f.ts: <function>`) sets the current file, and a file counts only once a line under it differs
199
+ * (a `-` or `+` in the outer column). A hunk line alone is context: it names where the hunk starts, which can be
200
+ * the file before the one that changed.
201
+ */
202
+ export function rangeDiffFiles(text: string): string[] {
203
+ const lines = text.split("\n");
204
+ // Paths a header names whole, so a hunk line `src/b: c.ts: fn` resolves to `src/b: c.ts`, not `src/b`.
205
+ const known = lines.flatMap((l) => /^ {4}[-+ ]? ?## (.+) ##$/.exec(l)?.[1] ?? []).map(headerFile).sort((x, y) => y.length - x.length);
206
+ const files = new Set<string>();
207
+ let file: string | null = null;
208
+
209
+ for (const l of lines) {
210
+ const header = /^ {4}([-+ ]?) ?## (.+) ##$/.exec(l);
211
+ const hunk = /^ {4}@@ (.+)$/.exec(l);
212
+
213
+ if (header) {
214
+ file = NOT_FILES.has(header[2]!) ? null : headerFile(header[2]!);
215
+
216
+ if (file && header[1] !== " " && header[1] !== "") files.add(file); // the header itself differs: a new, removed or renamed file
217
+ } else if (hunk) {
218
+ const v = headerFile(hunk[1]!);
219
+
220
+ file = NOT_FILES.has(v) ? null : (known.find((k) => v === k || v.startsWith(`${k}: `)) ?? v.split(": ")[0]!);
221
+ } else if (file && /^ {4}[-+]/.test(l)) {
222
+ files.add(file);
223
+ }
224
+ }
225
+
226
+ return [...files];
227
+ }
228
+
229
+ /**
230
+ * `interdiff` against origin/<base>, or against a commit when `base` is a SHA (a stacked PR's parent head),
231
+ * fetching `since` when a force-push left it out of the local clone.
232
+ */
233
+ export function prInterdiff(since: string, head: string, base: string, repoRoot: string, sinceBase?: string): Interdiff {
234
+ const git = (...args: string[]) =>
235
+ execFileSync("git", ["-c", "credential.helper=", "-c", "credential.helper=!gh auth git-credential", ...args], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 << 20 }).trim();
236
+
237
+ const has = (sha: string) => {
238
+ try {
239
+ git("cat-file", "-e", `${sha}^{commit}`);
240
+
241
+ return true;
242
+ } catch {
243
+ return false;
244
+ }
245
+ };
246
+
247
+ for (const sha of [since, sinceBase]) if (sha && !has(sha)) git("fetch", "-q", "origin", sha); // GitHub serves a force-pushed-away commit by SHA
248
+
249
+ const sha = git("rev-parse", `${head}^{commit}`);
250
+
251
+ if (/^[0-9a-f]{40}$/.test(base)) return interdiff(since, sha, base, git, sinceBase);
252
+ git("fetch", "-q", "origin", `+refs/heads/${base}:refs/remotes/origin/${base}`);
253
+
254
+ return interdiff(since, sha, `refs/remotes/origin/${base}`, git, sinceBase);
255
+ }
package/src/summary.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  import { createHash } from "node:crypto";
6
6
  import { z } from "zod";
7
7
  import type { BRANDING } from "./config.ts";
8
+ import { changedRanges, covers } from "./local.ts";
8
9
 
9
10
  const Severity = z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW", "NIT"]);
10
11
 
@@ -23,11 +24,52 @@ const flag = (fallback: boolean) => z.boolean().nullish().transform((v) => v ??
23
24
 
24
25
  const EvidenceParts = z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) });
25
26
 
26
- /** `Input: "Ada Lovelace", Expected: "Ada", Actual: "Lovelace"`, in any case and with `;` or `·` between: the three parts, or nothing. */
27
+ /** The body's first sentence or line, up to 100 characters. */
28
+ function firstSentence(body: string): string {
29
+ const sentence = body.trim().split(/(?<=[.!?])\s|\n/)[0] ?? "";
30
+
31
+ return sentence.length > 100 ? `${sentence.slice(0, 99).trimEnd()}…` : sentence;
32
+ }
33
+
34
+ // A label with any bold around it (`**Input:**`, `**Input**:`, `__Input:__`), so emphasis is read off the label alone.
35
+ const label = (words: string) => new RegExp(String.raw`(?:\*\*|__)?(?<![a-z0-9])(?:${words})(?:\*\*|__)?\s*[:=](?:\*\*|__)?`, "i");
36
+
37
+ // The labels a worked example uses for its three parts, with the synonyms models reach for.
38
+ const EVIDENCE_LABELS = {
39
+ input: label("input|given|for input|when called with"),
40
+ expected: label("expected|expect|should (?:be|return)|wanted|want"),
41
+ actual: label("actual|got|returns|result|observed"),
42
+ };
43
+
44
+ /**
45
+ * A worked example written as text, such as `Input: "Ada Lovelace" | Expected: "Ada" | Actual: "Lovelace"`: each label
46
+ * found in any order and case, bold around a label ignored, and any separator (`,` `;` `|` `·` `→` `->` ` - ` or a line
47
+ * break) between the parts. A label inside a quoted value is part of that value, and each value keeps its own
48
+ * characters, so `-1` and a closing `;` stay. The three parts, or nothing when a label is missing.
49
+ */
27
50
  function evidenceFromLine(line: string) {
28
- const m = /input:\s*(.+?)\s*[,;·]\s*expected:\s*(.+?)\s*[,;·]\s*actual:\s*(.+)$/is.exec(line.trim());
51
+ // Blank each quoted value to its own length, so a label inside a quote stays part of the value and positions match.
52
+ const unquoted = line.replaceAll(/"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\\n])*`|(?<![a-z0-9])'(?:\\.|[^'\\\n])*'/gi, (quoted) => " ".repeat(quoted.length));
53
+
54
+ const found = Object.entries(EVIDENCE_LABELS).flatMap(([part, pattern]) => {
55
+ const m = pattern.exec(unquoted);
56
+
57
+ return m ? [{ part, start: m.index, from: m.index + m[0].length }] : [];
58
+ });
59
+
60
+ if (found.length < 3) return undefined;
61
+ const ordered = [...found].sort((a, b) => a.start - b.start);
62
+
63
+ // One separator comes off a value that runs into the next label on the same line; a line break is separator enough.
64
+ const valueOf = (raw: string, last: boolean) => {
65
+ const value = raw.trim();
66
+
67
+ return last || /\n\s*$/.test(raw) ? value : value.replace(/\s*(?:[|,;·→]|[-=]>|(?<=\s)-)$/, "");
68
+ };
29
69
 
30
- return m ? { input: m[1]!, expected: m[2]!, actual: m[3]! } : undefined;
70
+ const parts = Object.fromEntries(ordered.map((p, i) => [p.part, valueOf(line.slice(p.from, ordered[i + 1]?.start ?? line.length), i === ordered.length - 1)]));
71
+
72
+ return parts.input && parts.expected && parts.actual ? { input: parts.input, expected: parts.expected, actual: parts.actual } : undefined;
31
73
  }
32
74
 
33
75
  const VERDICT_ALIAS = alias({ changes_needed: "changes", approve_with_nits: "nits", looks_good: "good", approve: "good", approved: "good" });
@@ -45,6 +87,9 @@ const Finding = z.object({
45
87
  .refine((l) => !l.includes("-") || Number(l.split("-")[0]) <= Number(l.split("-")[1]), "a range runs start-end, start first"),
46
88
  ]),
47
89
  ),
90
+ // LEFT anchors on a line the diff removes: `line` is then its number in the old file. A finding about deleted code
91
+ // has no line on the new side.
92
+ side: z.enum(["LEFT", "RIGHT"]).nullish().catch(undefined).transform((v) => v ?? "RIGHT"),
48
93
  severity: Severity,
49
94
  lens: z.string(),
50
95
  body: z.string(),
@@ -64,10 +109,19 @@ const Finding = z.object({
64
109
  checked: z.array(z.object({ command: z.string(), result: z.string() })).nullish().transform((v) => v ?? []),
65
110
  docs: z.array(z.object({ url: z.string().regex(/^https:\/\/[^\s()<>`]+$/), title: z.string() })).nullish().transform((v) => v ?? []), // the documentation the claim rests on
66
111
  reintroduces: absent(z.string().regex(THREAD_URL)).catch(undefined), // a resolved thread whose fix this change undoes
112
+ // A range written as `line` and `line_end` reads as "line-line_end".
113
+ line_end: absent(z.union([z.number().int().positive(), z.string().regex(/^[1-9]\d*$/).transform(Number)])),
114
+ }).transform(({ line_end: last, ...f }) => {
115
+ const start = /^\d+$/.test(String(f.line)) ? Number(f.line) : undefined;
116
+
117
+ return last !== undefined && start !== undefined && last > start ? { ...f, line: `${start}-${last}` } : f;
67
118
  });
68
119
 
69
120
  export const SummaryInput = z.object({
70
121
  head_sha: z.string().regex(/^[0-9a-f]{7,40}$/),
122
+ // The base tip the round reviewed against: the PR's base, or a stacked PR's parent head. The next round passes it
123
+ // to interdiff as --since-base, so a parent force-pushed in between keeps its old change out of the focus.
124
+ base_sha: z.string().regex(/^[0-9a-f]{40}$/).optional(),
71
125
  verdict: z.string().transform(VERDICT_ALIAS).pipe(z.enum(["blocked", "changes", "nits", "good"])),
72
126
  why: text,
73
127
  confidence: absent(z.number().int().min(0).max(5)), // how safe to merge, 5 safest
@@ -132,7 +186,7 @@ export function earlierRounds(previous: string | undefined) {
132
186
  const fenced = (text: string) => defuse(text).replace(/`{5,}/g, "````");
133
187
 
134
188
  /** `file:line` or `file:start-end`, the way the agent prompts cite a finding. */
135
- const cite = (f: { file: string; line?: number | string }) => `${f.file}${f.line !== undefined && f.line !== "general" ? `:${f.line}` : ""}`;
189
+ const cite = (f: { file: string; line?: number | string; side?: string }) => `${f.file}${f.line !== undefined && f.line !== "general" ? `:${f.line}` : ""}${f.side === "LEFT" ? " (removed line)" : ""}`;
136
190
 
137
191
  /**
138
192
  * Every finding as one prompt the author hands to the agent that wrote the PR, built in code so no finding is
@@ -198,12 +252,20 @@ const fromChecks = (f: { lens: string }) => f.lens.startsWith("checks/");
198
252
  * input, expected and actual result is graded MEDIUM. The verdict is at least as strict as its findings. Without
199
253
  * `threads`, links are kept as given.
200
254
  */
255
+ /** Text a model escaped twice: two or more literal `\\n` and no real line break. One may be code the body quotes. */
256
+ const unescaped = (t: string) => (!t.includes("\n") && t.split("\\n").length > 2 ? t.replaceAll("\\n", "\n").replaceAll("\\t", "\t").replaceAll('\\"', '"') : t);
257
+
201
258
  export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, read?: (path: string) => string | null) {
202
259
  const s = SummaryInput.parse(raw);
203
260
  const real = (url: string | undefined) => (url === undefined || threads === undefined || threads.has(url) ? url : undefined);
204
261
 
262
+ s.why = unescaped(s.why);
263
+
205
264
  for (const f of s.findings) {
265
+ f.body = unescaped(f.body);
206
266
  f.convergent &&= f.lens.includes("+");
267
+ // A finding without a title takes its first sentence, so a reader can triage it by the title alone.
268
+ f.title ||= firstSentence(f.body);
207
269
  f.url = real(f.url);
208
270
  f.reintroduces = real(f.reintroduces);
209
271
 
@@ -233,6 +295,13 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, r
233
295
  function place(f: z.infer<typeof Finding>, read: (path: string) => string | null) {
234
296
  if (f.suggestion === undefined) return;
235
297
 
298
+ // GitHub applies a suggestion to the new side, and a removed line has no place there.
299
+ if (f.side === "LEFT") {
300
+ f.suggestion = undefined;
301
+
302
+ return;
303
+ }
304
+
236
305
  const text = f.suggestion.includes("```") || !insideRepo(f.file) ? null : read(f.file);
237
306
  const [start, end] = String(f.line).split("-").map(Number);
238
307
  const lines = text?.split("\n") ?? [];
@@ -368,6 +437,34 @@ function lensTake(lens: string, findings: { lens: string; severity: z.infer<type
368
437
  /** A finding above NIT that no verifier checked. */
369
438
  const unverified = (f: z.infer<typeof Finding>) => f.severity !== "NIT" && !fromChecks(f) && !f.verified && !f.checked.length;
370
439
 
440
+ /**
441
+ * Whether every changed range of the PR's diff reached a lens that finished, as `shepherd local finish` checks a local
442
+ * review. `uncovered` lists the ranges no finished lens's scope holds, for one more lens
443
+ * before the round posts; `failed` names the lenses that did not finish.
444
+ */
445
+ export type RoundCoverage = { complete: boolean; uncovered: string[]; failed: string[] };
446
+
447
+ export function roundCoverage(raw: SummaryInput, diff: string): RoundCoverage {
448
+ const lenses = SummaryInput.parse(raw).lenses;
449
+ const ok = lenses.filter((l) => l.status === "ok").map((l) => (Array.isArray(l.scope) ? l.scope : l.scope === "full" ? ("full" as const) : [l.scope]));
450
+ const uncovered = changedRanges(diff).flatMap((r) => (ok.some((scope) => covers(scope, r)) ? [] : [`${r.file}:${r.start}-${r.end}`]));
451
+ const failed = lenses.filter((l) => l.status !== "ok").map((l) => l.lens);
452
+
453
+ return { complete: !uncovered.length && !failed.length, uncovered, failed };
454
+ }
455
+
456
+ const REVIEWED = /<!-- shepherd-reviewed:head=([0-9a-f]{7,40});base=([0-9a-f]{40}) -->/;
457
+
458
+ /** The head and base tip a round reviewed, as a marker at the end of its summary comment. */
459
+ export const reviewedMarker = (head: string, base: string) => `<!-- shepherd-reviewed:head=${head};base=${base} -->`;
460
+
461
+ /** The tips the previous summary reviewed, or null when it carries no marker. Read only from the bot's own summary. */
462
+ export function reviewedTips(previous: string): { head_sha: string; base_sha: string } | null {
463
+ const m = REVIEWED.exec(previous);
464
+
465
+ return m ? { head_sha: m[1]!, base_sha: m[2]! } : null;
466
+ }
467
+
371
468
  /**
372
469
  * The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
373
470
  * it is the body alone, for the handoff file the publish job wraps in its own marker and header.
@@ -387,7 +484,7 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
387
484
  const { round, history } = earlierRounds(previous);
388
485
  const sha = s.head_sha.slice(0, 7);
389
486
  const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
390
- const where = (f: (typeof s.findings)[number]) => (f.file ? ` · \`${defuse(f.file, true).replaceAll("`", "")}${f.line !== undefined && f.line !== "general" ? `:${f.line}` : ""}\`` : "");
487
+ const where = (f: (typeof s.findings)[number]) => (f.file ? ` · \`${defuse(f.file, true).replaceAll("`", "")}${f.line !== undefined && f.line !== "general" ? `:${f.line}` : ""}\`${f.side === "LEFT" ? " (removed)" : ""}` : "");
391
488
 
392
489
  const findings = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev));
393
490
 
@@ -475,13 +572,36 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
475
572
  // The handoff body (no header) leaves history to the publish job, which folds in the comment it replaces.
476
573
  if (history.length && header !== null) out.push(...section(`Earlier rounds (${history.length})`, [defuse(history.join("\n"))]));
477
574
 
478
- return out.join("\n").trimEnd() + "\n";
575
+ const body = capped(out.join("\n").trimEnd());
576
+
577
+ return (s.base_sha ? `${body}\n\n${reviewedMarker(s.head_sha, s.base_sha)}` : body) + "\n";
578
+ }
579
+
580
+ /** GitHub rejects a comment over 65,536 characters, and the review with it; the room left is for the marker and the note. */
581
+ const MAX_COMMENT = 60_000;
582
+
583
+ /** A comment cut at a line, with its open code fence and collapsed sections closed, so what follows it still renders. */
584
+ export function capped(text: string, max = MAX_COMMENT): string {
585
+ if (text.length <= max) return text;
586
+ const lines = text.slice(0, text.lastIndexOf("\n", max)).split("\n");
587
+ let fence = "";
588
+
589
+ for (const l of lines) {
590
+ const tick = /^`{3,}/.exec(l)?.[0];
591
+
592
+ if (tick && !fence) fence = tick;
593
+ else if (tick && tick.length >= fence.length) fence = "";
594
+ }
595
+
596
+ const open = lines.filter((l) => l === "<details>" || l === "<details open>").length - lines.filter((l) => l === "</details>").length;
597
+
598
+ return [...lines, ...(fence ? [fence] : []), ...Array.from({ length: Math.max(0, open) }, () => "\n</details>"), "", "_(truncated: the comment reached GitHub's size limit)_"].join("\n");
479
599
  }
480
600
 
481
601
  const PER_REVIEW = 10;
482
602
 
483
603
  /** One comment in POST /pulls/<n>/reviews: `start_line` and `start_side` only for a range. */
484
- type InlineComment = { path: string; line: number; side: "RIGHT"; body: string; start_line?: number; start_side?: "RIGHT" };
604
+ type InlineComment = { path: string; line: number; side: "LEFT" | "RIGHT"; body: string; start_line?: number; start_side?: "LEFT" | "RIGHT" };
485
605
 
486
606
  /**
487
607
  * The inline review swarm posts, rendered from the same round JSON as the summary: each finding worth a thread, most
@@ -550,21 +670,128 @@ export function anchorSuggestion(lines: string[], start: number, end: number, su
550
670
  /** A path inside the repository, as the model gave it: never absolute, never climbing out. */
551
671
  const insideRepo = (p: string) => !p.startsWith("/") && !p.split(/[\\/]/).includes("..");
552
672
 
553
- export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>) {
673
+ /** A C-quoted git path (`"b/caf\\303\\251.ts"`: escapes and octal UTF-8 bytes), or null when it is not one. */
674
+ export function unquotePath(s: string): string | null {
675
+ if (!s.startsWith('"') || !s.endsWith('"') || s.length < 2) return null;
676
+ const named = new Map([["a", 7], ["b", 8], ["t", 9], ["n", 10], ["v", 11], ["f", 12], ["r", 13], ['"', 34], ["\\", 92]]);
677
+ const bytes: number[] = [];
678
+ const body = s.slice(1, -1);
679
+
680
+ for (let i = 0; i < body.length; i++) {
681
+ const c = body[i]!;
682
+
683
+ if (c !== "\\") {
684
+ bytes.push(...new TextEncoder().encode(c));
685
+ continue;
686
+ }
687
+
688
+ const octal = /^[0-7]{3}/.exec(body.slice(i + 1));
689
+ const e = octal ? parseInt(octal[0], 8) : named.get(body[i + 1] ?? "");
690
+
691
+ if (e === undefined) return null;
692
+ bytes.push(e);
693
+ i += octal ? 3 : 1;
694
+ }
695
+
696
+ return new TextDecoder().decode(new Uint8Array(bytes));
697
+ }
698
+
699
+ /**
700
+ * The new-side lines of each file a unified diff lets a review comment anchor on: the added and context lines
701
+ * inside its hunks. GitHub rejects a whole review over one comment anywhere else. The file comes from `+++`, bare
702
+ * (`b/f.ts`, with the tab git may append dropped) or C-quoted (`"b/caf\\303\\251.ts"`), and every `diff --git`
703
+ * line ends the one before, so a file with no `+++` (binary, a pure rename) never inherits its neighbour's lines.
704
+ */
705
+ export function commentableLines(diff: string, side: "LEFT" | "RIGHT" = "RIGHT"): Map<string, Set<number>> {
706
+ const lines = new Map<string, Set<number>>();
707
+ let file: Set<number> | null = null;
708
+ let oldName: string | null = null;
709
+ let at = 0;
710
+ let oldAt = 0;
711
+ // Lines a hunk still holds, from its header's counts. Inside one, "+++ x" is an added "++ x", never a file header.
712
+ let oldLeft = 0;
713
+ let newLeft = 0;
714
+
715
+ for (const l of diff.split("\n")) {
716
+ if (oldLeft > 0 || newLeft > 0) {
717
+ if (l.startsWith("\\")) continue; // "" belongs to neither side
718
+ const added = l.startsWith("+");
719
+ const removed = l.startsWith("-");
720
+
721
+ if (!removed) {
722
+ if (side === "RIGHT") file?.add(at);
723
+ at++;
724
+ newLeft--;
725
+ }
726
+
727
+ if (!added) {
728
+ if (side === "LEFT") file?.add(oldAt);
729
+ oldAt++;
730
+ oldLeft--;
731
+ }
732
+
733
+ continue;
734
+ }
735
+
736
+ const hunk = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(l);
737
+
738
+ if (l.startsWith("diff --git ")) {
739
+ file = null;
740
+ oldName = null;
741
+ } else if (l.startsWith("--- ")) {
742
+ const v = l.slice(4).replace(/\t$/, "");
743
+ const p = v === "/dev/null" ? null : (unquotePath(v) ?? v);
744
+
745
+ oldName = p?.startsWith("a/") ? p.slice(2) : null;
746
+ } else if (l.startsWith("+++ ")) {
747
+ const v = l.slice(4).replace(/\t$/, "");
748
+ const p = v === "/dev/null" ? null : (unquotePath(v) ?? v);
749
+ // A review comment names the file as the PR leaves it; a deleted file keeps its old name.
750
+ const name = p?.startsWith("b/") ? p.slice(2) : side === "LEFT" ? oldName : null;
751
+
752
+ file = name ? new Set() : null;
753
+
754
+ if (file) lines.set(name!, file);
755
+ } else if (hunk) {
756
+ oldAt = Number(hunk[1]);
757
+ at = Number(hunk[3]);
758
+ oldLeft = Number(hunk[2] ?? 1);
759
+ newLeft = Number(hunk[4] ?? 1);
760
+ }
761
+ }
762
+
763
+ return lines;
764
+ }
765
+
766
+ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>, commentable?: Map<string, Set<number>>, removable?: Map<string, Set<number>>) {
554
767
  const s = checkedRound(raw, threads, read);
555
768
  const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
556
769
 
557
- // A line past the end of the file it names cannot anchor: GitHub rejects the whole review over one such comment.
770
+ // A line past the end of the file it names, or (given the diff) outside its hunks, cannot anchor: GitHub rejects
771
+ // the whole review over one such comment. The finding stays in the summary comment.
558
772
  const fits = (f: (typeof s.findings)[number]) => {
773
+ const [start = 0, end = start] = String(f.line).split("-").map(Number);
774
+ const left = f.side === "LEFT";
775
+
776
+ // A removed line can only be checked against the diff, so without one it stays in the summary.
777
+ if (left && !removable) return false;
778
+
779
+ if (commentable || left) {
780
+ const inDiff = (left ? removable : commentable)?.get(f.file);
781
+
782
+ for (let n = start; n <= end; n++) if (!inDiff?.has(n)) return false;
783
+ }
784
+
785
+ if (left) return true;
559
786
  const text = insideRepo(f.file) ? read(f.file) : null;
560
787
 
561
- return text === null || Number(String(f.line).split("-").at(-1)) <= text.replace(/\n$/, "").split("\n").length;
788
+ return text === null || end <= text.replace(/\n$/, "").split("\n").length;
562
789
  };
563
790
 
564
791
  const anchored = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev && sev !== "NIT" && f.inline && f.file && f.line !== undefined && f.line !== "general" && fits(f)));
565
792
  // One comment per place, the most severe finding's. Others on the same lines are named under it and appear in full
566
793
  // in the summary.
567
- const at = (f: (typeof s.findings)[number]) => `${f.file}:${f.line}`;
794
+ const at = (f: (typeof s.findings)[number]) => `${f.file}:${f.side}:${f.line}`;
568
795
  const posted = anchored.filter((f, i) => anchored.findIndex((g) => at(g) === at(f)) === i).slice(0, PER_REVIEW);
569
796
 
570
797
  const alsoHere = (f: (typeof s.findings)[number]) => {
@@ -610,11 +837,11 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
610
837
  "</details>",
611
838
  ].join("\n");
612
839
 
613
- const comment: InlineComment = { path: f.file, line: end ?? start, side: "RIGHT", body };
840
+ const comment: InlineComment = { path: f.file, line: end ?? start, side: f.side, body };
614
841
 
615
842
  if (end !== undefined && end !== start) {
616
843
  comment.start_line = start;
617
- comment.start_side = "RIGHT";
844
+ comment.start_side = f.side;
618
845
  }
619
846
 
620
847
  return comment;
@@ -498,6 +498,11 @@ jobs:
498
498
  print(desc[:139])
499
499
  PY
500
500
  state=$(sed -n 1p status.out); sed -n 2p status.out > description.txt
501
+ # A person's "changes requested" reaches no thread, and it holds until they approve or it is dismissed.
502
+ if [ "$state" = success ]; then
503
+ blocked=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews?per_page=100" --paginate | jq -s 'add // [] | map(select(.user != null and .user.type != "Bot" and (.state == "APPROVED" or .state == "CHANGES_REQUESTED" or .state == "DISMISSED"))) | group_by(.user.login) | map(last | select(.state == "CHANGES_REQUESTED") | .user.login)' | jq -r 'join(", ")')
504
+ if [ -n "$blocked" ]; then state=failure; echo "changes requested by $blocked" | cut -c1-139 > description.txt; fi
505
+ fi
501
506
  gh api "repos/$GITHUB_REPOSITORY/statuses/$HEAD_SHA" -f context=shepherd -f state="$state" -f description="$(cat description.txt)" >/dev/null
502
507
  echo "state=$state" >> "$GITHUB_OUTPUT"
503
508
  # Under suggest, posting is the review. If the iteration ended without its summary on the PR, post the findings it
@@ -530,14 +535,18 @@ jobs:
530
535
  if [ -f handoff/round.json ] && command -v shepherd >/dev/null; then
531
536
  # The inline review, from the round JSON, unless these same comments are already on the PR: its marker names
532
537
  # the head and a fingerprint of the comments, so a new round on an unchanged head still posts its own.
533
- if ! (cd repo && shepherd inline ../handoff/round.json) > review.json; then
538
+ # The PR's diff from GitHub, never from the model's job: only lines inside its hunks can carry a comment.
539
+ gh pr diff "$PR" -R "$GITHUB_REPOSITORY" > pr.diff || : > pr.diff
540
+ if ! (cd repo && if [ -s ../pr.diff ]; then shepherd inline ../handoff/round.json --diff ../pr.diff; else shepherd inline ../handoff/round.json; fi) > review.json; then
534
541
  echo "::warning::could not render the inline review"
535
542
  elif [ "$(jq '.comments | length' review.json)" -gt 0 ]; then
536
543
  marker=$(jq -r .body review.json | grep -o '<!-- shepherd-inline @ [0-9a-f]* [0-9a-f]* -->' | tail -1)
537
544
  if [ -n "$marker" ] && gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --paginate --jq '.[] | select(.user.login == "github-actions[bot]") | .body' | grep -F -- "$marker" >/dev/null; then
538
545
  echo "this round's inline review is already on the PR"
539
546
  else
540
- gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --method POST --input review.json >/dev/null || echo "::warning::could not post the rendered inline review"
547
+ # A 5xx or a 422 "internal error" clears in seconds, so it gets one more try.
548
+ post_review() { gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --method POST --input review.json >/dev/null 2>post.err; }
549
+ post_review || { grep -qiE 'internal error occurred|HTTP 5[0-9]{2}' post.err && { sleep 5; post_review; }; } || { cat post.err; echo "::warning::could not post the rendered inline review"; }
541
550
  fi
542
551
  fi
543
552
  fanout=(); [ -f handoff/fanout.json ] && fanout=(--fanout ../handoff/fanout.json)