@jagreehal/shepherd 0.12.2 → 0.13.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/package.json +1 -1
- package/skills/shepherd/SKILL.md +3 -1
- package/skills/swarm/SKILL.md +4 -1
- package/src/cli.ts +4 -1
- package/src/summary.ts +85 -20
- package/templates/shepherd.yml +15 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.0",
|
|
4
4
|
"description": "Agent skills that drive a PR to merge-ready: a review swarm, thread triage, CI repair, and a loop that hands the result to stamp.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": "github:jagreehal/shepherd",
|
package/skills/shepherd/SKILL.md
CHANGED
|
@@ -126,7 +126,9 @@ model pushes what you hand it. An iteration then differs in six places:
|
|
|
126
126
|
each job id ci-repair wants rerun on its own line in
|
|
127
127
|
`$SHEPHERD_HANDOFF/rerun-jobs.txt`. The publish job pushes your commits,
|
|
128
128
|
sets the status on the head it pushed (`pending` whenever it pushed: those
|
|
129
|
-
commits are not reviewed yet
|
|
129
|
+
commits are not reviewed yet; with nothing pushed or rerun, `failure` in
|
|
130
|
+
place of `pending` when the round has findings above NIT), reruns the jobs,
|
|
131
|
+
and notifies. It refuses a
|
|
130
132
|
push that is not a fast-forward of `H0` or that touches a protected path
|
|
131
133
|
(workflows, hooks, package manager config, manifests, lockfiles), and sets
|
|
132
134
|
`failure` naming why.
|
package/skills/swarm/SKILL.md
CHANGED
|
@@ -497,7 +497,10 @@ gh api repos/<owner>/<repo>/pulls/<number>/reviews --method POST --input review.
|
|
|
497
497
|
`shepherd inline` keeps the shape a reader learns once: the tag line, a bold
|
|
498
498
|
title, the body, a suggestion block, `Verified:`, and a collapsed "Prompt for
|
|
499
499
|
AI agents". It leaves out NITs, findings with `"inline": false`, and findings
|
|
500
|
-
with no line, and posts at most 10, most severe first
|
|
500
|
+
with no line, and posts at most 10, most severe first, one per place: other
|
|
501
|
+
findings on the same lines are named under it. Run it from the reviewed
|
|
502
|
+
checkout, so it can place each `suggestion` on the lines it rewrites, at their
|
|
503
|
+
indentation. A finding on a line
|
|
501
504
|
outside the diff cannot anchor inline: keep its `line` and set
|
|
502
505
|
`"inline": false`. When `review.json` has no `comments`, skip the post.
|
|
503
506
|
Otherwise read the new threads' URLs
|
package/src/cli.ts
CHANGED
|
@@ -586,7 +586,10 @@ if (command === "install") {
|
|
|
586
586
|
|
|
587
587
|
const fanout = fanoutFile && existsSync(fanoutFile) ? orExit(() => JSON.parse(readFileSync(fanoutFile, "utf8"))) : undefined;
|
|
588
588
|
|
|
589
|
-
|
|
589
|
+
// Read from the reviewed checkout, as inline does, so both place each suggestion on the same lines.
|
|
590
|
+
const read = (p: string) => (existsSync(p) ? readFileSync(p, "utf8") : null);
|
|
591
|
+
|
|
592
|
+
process.stdout.write(orExit(() => renderSummary(input, b.emoji, opts.body ? null : b.headers.swarm, previous, fanout, reviewThreads(), read)));
|
|
590
593
|
} else if (command === "inline" && sub) {
|
|
591
594
|
// Swarm's inline review, rendered from the same round JSON: the payload for POST /pulls/<n>/reviews.
|
|
592
595
|
const input = orExit(() => JSON.parse(readFileSync(sub, "utf8")));
|
package/src/summary.ts
CHANGED
|
@@ -21,6 +21,15 @@ const text = z.string().nullish().transform((v) => v ?? "");
|
|
|
21
21
|
|
|
22
22
|
const flag = (fallback: boolean) => z.boolean().nullish().transform((v) => v ?? fallback);
|
|
23
23
|
|
|
24
|
+
const EvidenceParts = z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) });
|
|
25
|
+
|
|
26
|
+
/** `Input: "Ada Lovelace", Expected: "Ada", Actual: "Lovelace"`, in any case and with `;` or `·` between: the three parts, or nothing. */
|
|
27
|
+
function evidenceFromLine(line: string) {
|
|
28
|
+
const m = /input:\s*(.+?)\s*[,;·]\s*expected:\s*(.+?)\s*[,;·]\s*actual:\s*(.+)$/is.exec(line.trim());
|
|
29
|
+
|
|
30
|
+
return m ? { input: m[1]!, expected: m[2]!, actual: m[3]! } : undefined;
|
|
31
|
+
}
|
|
32
|
+
|
|
24
33
|
const VERDICT_ALIAS = alias({ changes_needed: "changes", approve_with_nits: "nits", looks_good: "good", approve: "good", approved: "good" });
|
|
25
34
|
|
|
26
35
|
const STATUS_ALIAS = alias({ success: "ok", done: "ok", completed: "ok", complete: "ok", passed: "ok", error: "failed", errored: "failed", skipped: "could_not_run", not_run: "could_not_run", did_not_run: "could_not_run", missing: "could_not_run" });
|
|
@@ -47,7 +56,8 @@ const Finding = z.object({
|
|
|
47
56
|
// What the verifier checked, quoted code included. A bare `true` carries no evidence, so it reads as unverified.
|
|
48
57
|
verified: z.union([z.string(), z.boolean().transform(() => "")]).nullish().transform((v) => v ?? ""),
|
|
49
58
|
// The claim made checkable: an input, what the code should do on it, and what it does.
|
|
50
|
-
|
|
59
|
+
// Also accepted as one line, `Input: …, Expected: …, Actual: …`, and split into its parts.
|
|
60
|
+
evidence: absent(z.union([EvidenceParts, z.string().transform(evidenceFromLine).pipe(EvidenceParts.optional())])),
|
|
51
61
|
suggestion: absent(z.string()), // replacement for exactly the lines the comment covers: GitHub's one-click commit
|
|
52
62
|
inline: flag(true), // false when the finding has no line in the diff to anchor on
|
|
53
63
|
// The read-only commands the reviewer or verifier ran to check it.
|
|
@@ -188,7 +198,7 @@ const fromChecks = (f: { lens: string }) => f.lens.startsWith("checks/");
|
|
|
188
198
|
* input, expected and actual result is graded MEDIUM. The verdict is at least as strict as its findings. Without
|
|
189
199
|
* `threads`, links are kept as given.
|
|
190
200
|
*/
|
|
191
|
-
export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string
|
|
201
|
+
export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, read?: (path: string) => string | null) {
|
|
192
202
|
const s = SummaryInput.parse(raw);
|
|
193
203
|
const real = (url: string | undefined) => (url === undefined || threads === undefined || threads.has(url) ? url : undefined);
|
|
194
204
|
|
|
@@ -212,9 +222,58 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>) {
|
|
|
212
222
|
|
|
213
223
|
for (const t of s.still_open) t.url = real(t.url) ?? "";
|
|
214
224
|
|
|
225
|
+
// With the reviewed files at hand, each suggestion is placed once, so the summary and the inline comment cite the
|
|
226
|
+
// same lines.
|
|
227
|
+
if (read) for (const f of s.findings) place(f, read);
|
|
228
|
+
|
|
215
229
|
return s;
|
|
216
230
|
}
|
|
217
231
|
|
|
232
|
+
/** A suggestion moved onto the lines it rewrites and given their indentation, or dropped when it fits nowhere near. */
|
|
233
|
+
function place(f: z.infer<typeof Finding>, read: (path: string) => string | null) {
|
|
234
|
+
if (f.suggestion === undefined) return;
|
|
235
|
+
|
|
236
|
+
const text = f.suggestion.includes("```") || !insideRepo(f.file) ? null : read(f.file);
|
|
237
|
+
const [start, end] = String(f.line).split("-").map(Number);
|
|
238
|
+
const lines = text?.split("\n") ?? [];
|
|
239
|
+
// Near the cited line first, then across the whole file, which still needs one clear best match.
|
|
240
|
+
const at = text === null || !start ? null : (anchorSuggestion(lines, start, end ?? start, f.suggestion) ?? anchorSuggestion(lines, start, end ?? start, f.suggestion, lines.length));
|
|
241
|
+
|
|
242
|
+
if (!at) {
|
|
243
|
+
f.suggestion = undefined;
|
|
244
|
+
|
|
245
|
+
return;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
f.line = end === undefined ? at.start : `${at.start}-${at.end}`;
|
|
249
|
+
// The baseline is the indentation the replaced lines share, so a block that dedents keeps its shape.
|
|
250
|
+
f.suggestion = reindent(f.suggestion, sharedIndent(lines.slice(at.start - 1, at.end)));
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* The suggestion at the indentation of the lines it replaces, since GitHub commits it as written. The indentation its
|
|
255
|
+
* non-blank lines share becomes `target`, in spaces or tabs, and each line keeps what it adds on top.
|
|
256
|
+
*/
|
|
257
|
+
export function reindent(suggestion: string, target: string): string {
|
|
258
|
+
const lines = suggestion.split("\n");
|
|
259
|
+
const common = sharedIndent(lines);
|
|
260
|
+
|
|
261
|
+
return lines.map((l) => (l.trim() ? target + l.slice(common.length) : l)).join("\n");
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** The leading whitespace every non-blank line starts with: the block's own indentation. */
|
|
265
|
+
function sharedIndent(lines: string[]): string {
|
|
266
|
+
const indents = lines.flatMap((l) => (l.trim() ? [/^[ \t]*/.exec(l)![0]] : []));
|
|
267
|
+
|
|
268
|
+
return indents.reduce((shared, own) => {
|
|
269
|
+
let n = 0;
|
|
270
|
+
|
|
271
|
+
while (n < shared.length && n < own.length && shared[n] === own[n]) n++;
|
|
272
|
+
|
|
273
|
+
return shared.slice(0, n);
|
|
274
|
+
}, indents[0] ?? "");
|
|
275
|
+
}
|
|
276
|
+
|
|
218
277
|
/** The worst severity among the findings whose tag names the lens (`correctness/data`, `correctness + security`), and how many. */
|
|
219
278
|
function lensTake(lens: string, findings: { lens: string; severity: z.infer<typeof Severity> }[]): string | undefined {
|
|
220
279
|
const mine = findings.filter((f) => f.lens.split(/[\s+/]+/).includes(lens));
|
|
@@ -230,8 +289,8 @@ const unverified = (f: z.infer<typeof Finding>) => f.severity !== "NIT" && !from
|
|
|
230
289
|
* The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
|
|
231
290
|
* it is the body alone, for the handoff file the publish job wraps in its own marker and header.
|
|
232
291
|
*/
|
|
233
|
-
export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string, fanout?: z.input<typeof Fanout>, threads?: ReadonlySet<string
|
|
234
|
-
const s = checkedRound(raw, threads);
|
|
292
|
+
export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string | null, previous?: string, fanout?: z.input<typeof Fanout>, threads?: ReadonlySet<string>, read?: (path: string) => string | null): string {
|
|
293
|
+
const s = checkedRound(raw, threads, read);
|
|
235
294
|
// A lens fanout listed for this head that the round does not report never ran as its own reviewer, so it shows
|
|
236
295
|
// as could_not_run.
|
|
237
296
|
const wave = fanout ? Fanout.parse(fanout) : null;
|
|
@@ -383,7 +442,7 @@ const AHEAD = 0.1; // how far a moved suggestion's window must lead the next mos
|
|
|
383
442
|
* rewrites. The lines named stay when they are alike enough. Otherwise it moves to the window of the same size, within
|
|
384
443
|
* five lines, that is alike enough, differs from the suggestion and leads the next most alike; with none, it is dropped.
|
|
385
444
|
*/
|
|
386
|
-
export function anchorSuggestion(lines: string[], start: number, end: number, suggestion: string): { start: number; end: number } | null {
|
|
445
|
+
export function anchorSuggestion(lines: string[], start: number, end: number, suggestion: string, near = NEAR): { start: number; end: number } | null {
|
|
387
446
|
const size = end - start + 1;
|
|
388
447
|
const flat = (t: string) => t.replace(/\s+/g, " ").trim();
|
|
389
448
|
|
|
@@ -394,10 +453,13 @@ export function anchorSuggestion(lines: string[], start: number, end: number, su
|
|
|
394
453
|
};
|
|
395
454
|
|
|
396
455
|
if (end <= lines.length && score(start) >= LIKE) return { start, end };
|
|
397
|
-
const
|
|
456
|
+
const tried: { from: number; score: number }[] = [];
|
|
457
|
+
|
|
458
|
+
// A whole-file search (near >= the file's length) covers every window, wherever the cited line was.
|
|
459
|
+
const [lo, hi] = near >= lines.length ? [1, lines.length - size + 1] : [Math.max(1, start - near), Math.min(lines.length - size + 1, start + near)];
|
|
398
460
|
|
|
399
|
-
for (let from =
|
|
400
|
-
const [best, next] =
|
|
461
|
+
for (let from = lo; from <= hi; from++) tried.push({ from, score: score(from) });
|
|
462
|
+
const [best, next] = tried.sort((a, b) => b.score - a.score);
|
|
401
463
|
|
|
402
464
|
return best && best.score >= LIKE && best.score - (next?.score ?? 0) >= AHEAD ? { start: best.from, end: best.from + size - 1 } : null;
|
|
403
465
|
}
|
|
@@ -406,7 +468,7 @@ export function anchorSuggestion(lines: string[], start: number, end: number, su
|
|
|
406
468
|
const insideRepo = (p: string) => !p.startsWith("/") && !p.split(/[\\/]/).includes("..");
|
|
407
469
|
|
|
408
470
|
export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>) {
|
|
409
|
-
const s = checkedRound(raw, threads);
|
|
471
|
+
const s = checkedRound(raw, threads, read);
|
|
410
472
|
const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
|
|
411
473
|
|
|
412
474
|
// A line past the end of the file it names cannot anchor: GitHub rejects the whole review over one such comment.
|
|
@@ -416,20 +478,22 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
|
|
|
416
478
|
return text === null || Number(String(f.line).split("-").at(-1)) <= text.replace(/\n$/, "").split("\n").length;
|
|
417
479
|
};
|
|
418
480
|
|
|
419
|
-
const
|
|
481
|
+
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)));
|
|
482
|
+
// One comment per place, the most severe finding's. Others on the same lines are named under it and appear in full
|
|
483
|
+
// in the summary.
|
|
484
|
+
const at = (f: (typeof s.findings)[number]) => `${f.file}:${f.line}`;
|
|
485
|
+
const posted = anchored.filter((f, i) => anchored.findIndex((g) => at(g) === at(f)) === i).slice(0, PER_REVIEW);
|
|
420
486
|
|
|
421
|
-
const
|
|
422
|
-
|
|
423
|
-
// A suggestion is committed as written: it posts only when it cannot close its own fence and its lines are placed.
|
|
424
|
-
let fix = f.suggestion !== undefined && !f.suggestion.includes("```") ? f.suggestion : undefined;
|
|
425
|
-
const text = fix !== undefined && insideRepo(f.file) ? read(f.file) : null;
|
|
487
|
+
const alsoHere = (f: (typeof s.findings)[number]) => {
|
|
488
|
+
const rest = anchored.filter((g) => g !== f && at(g) === at(f));
|
|
426
489
|
|
|
427
|
-
|
|
428
|
-
|
|
490
|
+
return rest.length ? ["", `**Also here:** ${rest.map((g) => `${glyph(g.severity)} ${g.severity} ${defuse(g.title || g.body.split("\n")[0]!, true)}`).join(" · ")}`] : [];
|
|
491
|
+
};
|
|
429
492
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
493
|
+
const comments = posted.map((f) => {
|
|
494
|
+
const [start = 0, end] = String(f.line).split("-").map(Number); // `posted` kept only numeric lines and "a-b" ranges
|
|
495
|
+
// checkedRound placed the suggestion and kept it only where it fits.
|
|
496
|
+
const fix = f.suggestion;
|
|
433
497
|
|
|
434
498
|
const suggestion = fix !== undefined ? ["", "```suggestion", fix, "```"] : [];
|
|
435
499
|
const where = end === undefined ? `${start}` : `${start}-${end}`;
|
|
@@ -446,6 +510,7 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
|
|
|
446
510
|
...evidenceBlock(f),
|
|
447
511
|
...docsLine(f),
|
|
448
512
|
...suggestion,
|
|
513
|
+
...alsoHere(f),
|
|
449
514
|
...(f.verified ? ["", `**Verified:** ${defuse(f.verified)}`] : []),
|
|
450
515
|
...(unverified(f) ? ["", "⚠️ No verifier has checked this yet."] : []),
|
|
451
516
|
...checkedBlock(f),
|
package/templates/shepherd.yml
CHANGED
|
@@ -479,6 +479,21 @@ jobs:
|
|
|
479
479
|
state, desc = "failure", f"fixes not pushed, a person should look: {' '.join(sys.argv[3].split())}"
|
|
480
480
|
elif sys.argv[2]:
|
|
481
481
|
state, desc = "pending", f"pushed {sys.argv[2]} commit(s) for review; {desc}"
|
|
482
|
+
elif state == "pending":
|
|
483
|
+
# Nothing pushed and no CI re-run asked for: findings above NIT leave work for the author, so the status
|
|
484
|
+
# is failure and the sweep, which re-runs pending PRs every half hour, leaves the PR to them. Otherwise it
|
|
485
|
+
# stays pending: success needs stamp's approval, green CI and no open thread, which this step cannot see.
|
|
486
|
+
try:
|
|
487
|
+
reruns = open("handoff/rerun-jobs.txt").read().strip() not in ("", "[]")
|
|
488
|
+
except OSError:
|
|
489
|
+
reruns = False
|
|
490
|
+
try:
|
|
491
|
+
r = json.load(open("handoff/round.json"))
|
|
492
|
+
found = [f for f in (r.get("findings") or []) if isinstance(f, dict) and f.get("severity") != "NIT"]
|
|
493
|
+
if found and not reruns:
|
|
494
|
+
state, desc = "failure", f"{len(found)} finding(s) for the author; {desc}"
|
|
495
|
+
except Exception:
|
|
496
|
+
pass
|
|
482
497
|
print(state)
|
|
483
498
|
print(desc[:139])
|
|
484
499
|
PY
|