@jagreehal/shepherd 0.13.2 → 0.15.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/local.ts CHANGED
@@ -148,13 +148,66 @@ const headerPath = (line: string): string | null => {
148
148
  return raw === "/dev/null" ? null : raw.slice(2);
149
149
  };
150
150
 
151
- /** Changed ranges from a zero-context patch: new-side lines, or old lines for a file the change deletes. */
151
+ /**
152
+ * The lines a patch changes, as ranges: new-side lines it adds, the lines on both sides of a gap it deletes, or the
153
+ * old lines of a file it deletes. Each hunk is walked by its header's counts, so a context line never counts as
154
+ * changed (a GitHub diff carries three a side) and an added `++ x`, which reads `+++ x`, stays hunk content instead
155
+ * of naming a file.
156
+ */
152
157
  export function changedRanges(patch: string): ChangedRange[] {
153
- const out: ChangedRange[] = [];
158
+ const lines = new Map<string, { deleted: boolean; at: Set<number> }>();
154
159
  let oldFile: string | null = null;
155
160
  let newFile: string | null = null;
161
+ let oldAt = 0;
162
+ let newAt = 0;
163
+ let oldLeft = 0;
164
+ let newLeft = 0;
165
+ let emptyNew = false;
166
+ // The run of changed lines in progress: a deletion with no addition beside it changes the lines either side of its gap.
167
+ let block = { dels: 0, adds: 0, gap: 0 };
168
+
169
+ const mark = (file: string, deleted: boolean, ...ns: number[]) => {
170
+ const entry = lines.get(file) ?? { deleted, at: new Set<number>() };
171
+
172
+ for (const n of ns) entry.at.add(Math.max(n, 1));
173
+ lines.set(file, entry);
174
+ };
175
+
176
+ const endBlock = () => {
177
+ // In a hunk with no new lines, git numbers the line before the gap; otherwise the gap sits before `gap`.
178
+ if (block.dels && !block.adds && newFile !== null) mark(newFile, false, ...(emptyNew ? [block.gap, block.gap + 1] : [block.gap - 1, block.gap]));
179
+ block = { dels: 0, adds: 0, gap: 0 };
180
+ };
156
181
 
157
182
  for (const line of patch.split("\n")) {
183
+ if (oldLeft > 0 || newLeft > 0) {
184
+ if (line.startsWith("\\")) continue; // "" belongs to neither side
185
+
186
+ if (line.startsWith("+")) {
187
+ if (newFile !== null) mark(newFile, false, newAt);
188
+ block.adds++;
189
+ newAt++;
190
+ newLeft--;
191
+ } else if (line.startsWith("-")) {
192
+ // A deleted file keeps its old lines.
193
+ if (newFile === null && oldFile !== null) mark(oldFile, true, oldAt);
194
+
195
+ if (!block.dels) block.gap = newAt;
196
+ block.dels++;
197
+ oldAt++;
198
+ oldLeft--;
199
+ } else {
200
+ endBlock();
201
+ oldAt++;
202
+ newAt++;
203
+ oldLeft--;
204
+ newLeft--;
205
+ }
206
+
207
+ if (oldLeft <= 0 && newLeft <= 0) endBlock();
208
+ continue;
209
+ }
210
+
158
211
  if (line.startsWith("diff --git ")) oldFile = newFile = null;
159
212
  else if (line.startsWith("--- ")) oldFile = headerPath(line);
160
213
  else if (line.startsWith("+++ ")) newFile = headerPath(line);
@@ -164,21 +217,32 @@ export function changedRanges(patch: string): ChangedRange[] {
164
217
  if (!m) continue;
165
218
  const count = (n: string | undefined) => (n === undefined ? 1 : Number(n));
166
219
 
167
- if (newFile === null && oldFile !== null) {
168
- out.push({ file: oldFile, start: Number(m[1]), end: Number(m[1]) + count(m[2]) - 1, deleted: true });
220
+ [oldAt, oldLeft, newAt, newLeft] = [Number(m[1]), count(m[2]), Number(m[3]), count(m[4])];
221
+ emptyNew = newLeft === 0;
222
+ }
223
+ }
224
+
225
+ // Consecutive changed lines become one range, files in the order the patch names them.
226
+ return [...lines].flatMap(([file, { deleted, at }]) => {
227
+ const sorted = [...at].sort((a, b) => a - b);
228
+ const out: ChangedRange[] = [];
229
+
230
+ for (const n of sorted) {
231
+ const last = out.at(-1);
232
+
233
+ if (last && n === last.end + 1) {
234
+ last.end = n;
169
235
  continue;
170
236
  }
171
237
 
172
- if (newFile === null) continue;
173
- const start = Number(m[3]);
174
- const added = count(m[4]);
238
+ const range: ChangedRange = { file, start: n, end: n };
175
239
 
176
- // A pure deletion reports the line before it; the lines on both sides of the gap are what it changed.
177
- out.push(added === 0 ? { file: newFile, start: Math.max(start, 1), end: start + 1 } : { file: newFile, start, end: start + added - 1 });
240
+ if (deleted) range.deleted = true;
241
+ out.push(range);
178
242
  }
179
- }
180
243
 
181
- return out;
244
+ return out;
245
+ });
182
246
  }
183
247
 
184
248
  /**
@@ -241,7 +305,7 @@ export type FinishResult = {
241
305
  receipt: string | null;
242
306
  };
243
307
 
244
- const covers = (scope: "full" | string[], r: ChangedRange): boolean =>
308
+ export const covers = (scope: "full" | string[], r: ChangedRange): boolean =>
245
309
  scope === "full" ||
246
310
  scope.some((s) => {
247
311
  const m = /^(.*):(\d+)-(\d+)$/.exec(s);
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
 
@@ -86,6 +87,9 @@ const Finding = z.object({
86
87
  .refine((l) => !l.includes("-") || Number(l.split("-")[0]) <= Number(l.split("-")[1]), "a range runs start-end, start first"),
87
88
  ]),
88
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"),
89
93
  severity: Severity,
90
94
  lens: z.string(),
91
95
  body: z.string(),
@@ -115,6 +119,9 @@ const Finding = z.object({
115
119
 
116
120
  export const SummaryInput = z.object({
117
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(),
118
125
  verdict: z.string().transform(VERDICT_ALIAS).pipe(z.enum(["blocked", "changes", "nits", "good"])),
119
126
  why: text,
120
127
  confidence: absent(z.number().int().min(0).max(5)), // how safe to merge, 5 safest
@@ -179,7 +186,7 @@ export function earlierRounds(previous: string | undefined) {
179
186
  const fenced = (text: string) => defuse(text).replace(/`{5,}/g, "````");
180
187
 
181
188
  /** `file:line` or `file:start-end`, the way the agent prompts cite a finding. */
182
- 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)" : ""}`;
183
190
 
184
191
  /**
185
192
  * Every finding as one prompt the author hands to the agent that wrote the PR, built in code so no finding is
@@ -245,11 +252,17 @@ const fromChecks = (f: { lens: string }) => f.lens.startsWith("checks/");
245
252
  * input, expected and actual result is graded MEDIUM. The verdict is at least as strict as its findings. Without
246
253
  * `threads`, links are kept as given.
247
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
+
248
258
  export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, read?: (path: string) => string | null) {
249
259
  const s = SummaryInput.parse(raw);
250
260
  const real = (url: string | undefined) => (url === undefined || threads === undefined || threads.has(url) ? url : undefined);
251
261
 
262
+ s.why = unescaped(s.why);
263
+
252
264
  for (const f of s.findings) {
265
+ f.body = unescaped(f.body);
253
266
  f.convergent &&= f.lens.includes("+");
254
267
  // A finding without a title takes its first sentence, so a reader can triage it by the title alone.
255
268
  f.title ||= firstSentence(f.body);
@@ -282,6 +295,13 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, r
282
295
  function place(f: z.infer<typeof Finding>, read: (path: string) => string | null) {
283
296
  if (f.suggestion === undefined) return;
284
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
+
285
305
  const text = f.suggestion.includes("```") || !insideRepo(f.file) ? null : read(f.file);
286
306
  const [start, end] = String(f.line).split("-").map(Number);
287
307
  const lines = text?.split("\n") ?? [];
@@ -417,6 +437,34 @@ function lensTake(lens: string, findings: { lens: string; severity: z.infer<type
417
437
  /** A finding above NIT that no verifier checked. */
418
438
  const unverified = (f: z.infer<typeof Finding>) => f.severity !== "NIT" && !fromChecks(f) && !f.verified && !f.checked.length;
419
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
+
420
468
  /**
421
469
  * The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
422
470
  * it is the body alone, for the handoff file the publish job wraps in its own marker and header.
@@ -436,7 +484,7 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
436
484
  const { round, history } = earlierRounds(previous);
437
485
  const sha = s.head_sha.slice(0, 7);
438
486
  const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
439
- 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)" : ""}` : "");
440
488
 
441
489
  const findings = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev));
442
490
 
@@ -524,13 +572,36 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
524
572
  // The handoff body (no header) leaves history to the publish job, which folds in the comment it replaces.
525
573
  if (history.length && header !== null) out.push(...section(`Earlier rounds (${history.length})`, [defuse(history.join("\n"))]));
526
574
 
527
- 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");
528
599
  }
529
600
 
530
601
  const PER_REVIEW = 10;
531
602
 
532
603
  /** One comment in POST /pulls/<n>/reviews: `start_line` and `start_side` only for a range. */
533
- 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" };
534
605
 
535
606
  /**
536
607
  * The inline review swarm posts, rendered from the same round JSON as the summary: each finding worth a thread, most
@@ -599,21 +670,128 @@ export function anchorSuggestion(lines: string[], start: number, end: number, su
599
670
  /** A path inside the repository, as the model gave it: never absolute, never climbing out. */
600
671
  const insideRepo = (p: string) => !p.startsWith("/") && !p.split(/[\\/]/).includes("..");
601
672
 
602
- 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>>) {
603
767
  const s = checkedRound(raw, threads, read);
604
768
  const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
605
769
 
606
- // 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.
607
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;
608
786
  const text = insideRepo(f.file) ? read(f.file) : null;
609
787
 
610
- 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;
611
789
  };
612
790
 
613
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)));
614
792
  // One comment per place, the most severe finding's. Others on the same lines are named under it and appear in full
615
793
  // in the summary.
616
- 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}`;
617
795
  const posted = anchored.filter((f, i) => anchored.findIndex((g) => at(g) === at(f)) === i).slice(0, PER_REVIEW);
618
796
 
619
797
  const alsoHere = (f: (typeof s.findings)[number]) => {
@@ -659,11 +837,11 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
659
837
  "</details>",
660
838
  ].join("\n");
661
839
 
662
- 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 };
663
841
 
664
842
  if (end !== undefined && end !== start) {
665
843
  comment.start_line = start;
666
- comment.start_side = "RIGHT";
844
+ comment.start_side = f.side;
667
845
  }
668
846
 
669
847
  return comment;
@@ -126,11 +126,13 @@ jobs:
126
126
  You are running in GitHub Actions on the default branch, already checked out, with no push access.
127
127
  At Step 6 do not push or open the PR: commit on incident/<issue>, write the PR title to $HANDOFF/pr-title.txt
128
128
  and the body to $HANDOFF/pr-body.md; the next job pushes and opens it.
129
+ When the skill stops because a security failure stays private, create the empty file $HANDOFF/private.
129
130
  Nobody is watching this session: never wait for an answer. Anything you would ask is reported in the final JSON."
130
131
  - name: Bundle the fix branch
131
132
  env:
132
133
  DEFAULT: ${{ github.event.repository.default_branch }}
133
134
  run: |
135
+ [ ! -e "$RUNNER_TEMP/handoff/private" ] || { echo "::error::a possible security failure needs private handling"; exit 1; }
134
136
  branch=$(git branch --list 'incident/*' --format='%(refname:short)' | head -1)
135
137
  [ -n "$branch" ] || { echo "no fix branch: see the incident issue"; exit 0; }
136
138
  echo "$branch" > "$RUNNER_TEMP/handoff/branch"
@@ -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)