@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/AGENTS.md +12 -3
- package/README.md +2 -0
- package/package.json +1 -1
- package/skills/ci-repair/SKILL.md +58 -12
- package/skills/git-archaeology/SKILL.md +188 -0
- package/skills/shepherd/SKILL.md +27 -6
- package/skills/shepherd/references/dispatch.md +13 -5
- package/skills/swarm/SKILL.md +120 -13
- package/skills/swarm/references/formats.md +11 -4
- package/skills/triage/SKILL.md +71 -14
- package/src/cilog.ts +55 -0
- package/src/cli.ts +81 -7
- package/src/diff.ts +70 -0
- package/src/eval.ts +57 -1
- package/src/leads.ts +234 -0
- package/src/local.ts +76 -12
- package/src/stack.ts +134 -0
- package/src/summary.ts +240 -13
- package/templates/shepherd.yml +11 -2
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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 ||
|
|
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:
|
|
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 =
|
|
844
|
+
comment.start_side = f.side;
|
|
618
845
|
}
|
|
619
846
|
|
|
620
847
|
return comment;
|
package/templates/shepherd.yml
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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)
|