@jagreehal/shepherd 0.11.0 → 0.12.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/swarm/SKILL.md +2 -2
- package/skills/swarm/references/formats.md +5 -3
- package/src/summary.ts +26 -8
- package/templates/shepherd.yml +17 -7
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.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/swarm/SKILL.md
CHANGED
|
@@ -463,8 +463,8 @@ new side of the diff.
|
|
|
463
463
|
P1 counts as HIGH). A gate that refused this head for an issue the code still
|
|
464
464
|
has counts too:
|
|
465
465
|
- any CRITICAL -> `emoji.blocked` (🚫) BLOCKED
|
|
466
|
-
-
|
|
467
|
-
-
|
|
466
|
+
- any HIGH -> `emoji.changes_needed` (⚠️) CHANGES NEEDED
|
|
467
|
+
- any MEDIUM -> `emoji.approve_with_nits` (💬) APPROVE WITH NITS
|
|
468
468
|
- only LOW, NIT, or nothing -> `emoji.looks_good` (✅) LOOKS GOOD
|
|
469
469
|
|
|
470
470
|
The verdict is advice to the author. It never becomes a GitHub approval.
|
|
@@ -85,13 +85,15 @@ change has a flow a reader would otherwise reconstruct (a request path, a state
|
|
|
85
85
|
machine, data moving between modules); leave it empty for a helper function.
|
|
86
86
|
The new fields are optional: a round without them renders as before.
|
|
87
87
|
The renderers hold the round to what they can check. A `url`, `reintroduces`
|
|
88
|
-
or still-open link that names no review comment on the PR
|
|
88
|
+
or still-open link that names no review comment on the PR, or is not a
|
|
89
|
+
GitHub URL, loses its link.
|
|
89
90
|
`convergent` needs a tag naming two lenses (`a + b`). A finding above NIT with
|
|
90
91
|
neither `verified` nor `checked` is shown as unverified, `checks/*` findings
|
|
91
92
|
aside. A HIGH or CRITICAL with no `evidence` is graded MEDIUM, `checks/*`
|
|
92
93
|
findings aside, and says so. A `verdict` milder than the findings allow by
|
|
93
94
|
Step 6's rule is raised to the stricter one, and `why` says so. A lens that
|
|
94
|
-
did not finish marks the round incomplete.
|
|
95
|
+
did not finish marks the round incomplete. A lens's take is the worst
|
|
96
|
+
severity among the findings its tag names, when any do. An inline finding whose line is
|
|
95
97
|
past the end of its file stays in the summary. So give each thread
|
|
96
98
|
link a review comment's `html_url` (`#discussion_r<id>`), and an issue comment's
|
|
97
99
|
never.
|
|
@@ -107,7 +109,7 @@ title: findings, numbered and linked to their threads (open unless the
|
|
|
107
109
|
verdict is LOOKS GOOD), one agent prompt holding every finding above NIT, the
|
|
108
110
|
walkthrough (bullets, a file table, review effort, the diagram), still open,
|
|
109
111
|
checks, lenses, and earlier rounds folded one line each. With `--fanout` (in CI,
|
|
110
|
-
`$SHEPHERD_FANOUT`), a first-wave lens the round does not report shows as
|
|
112
|
+
`$SHEPHERD_FANOUT`), the router or a first-wave lens the round does not report shows as
|
|
111
113
|
`could_not_run` and the round says it is incomplete. With `--body` it keeps the
|
|
112
114
|
round number but leaves the history out: the publish job folds the comment it
|
|
113
115
|
replaces in itself, so the history would otherwise appear twice. It escapes markers, mentions
|
package/src/summary.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
* Swarm's summary comment, rendered in code from the round's JSON. The comment keeps the same shape every round, so a
|
|
3
3
|
* reader scans one line per section and garden parses the heading. Every model-written string is defused here.
|
|
4
4
|
*/
|
|
5
|
+
import { createHash } from "node:crypto";
|
|
5
6
|
import { z } from "zod";
|
|
6
7
|
import type { BRANDING } from "./config.ts";
|
|
7
8
|
|
|
@@ -26,7 +27,8 @@ const Finding = z.object({
|
|
|
26
27
|
convergent: z.boolean().default(false),
|
|
27
28
|
// A reader triages by the title alone: a claim they can check, such as "`firstName` returns the second word".
|
|
28
29
|
title: z.string().default(""),
|
|
29
|
-
|
|
30
|
+
// A thread link that is not a GitHub URL is dropped and the finding kept.
|
|
31
|
+
url: z.string().regex(THREAD_URL).optional().catch(undefined), // the finding's inline thread, linked from the summary
|
|
30
32
|
verified: z.string().default(""), // what the verifier checked, quoted code included
|
|
31
33
|
// The claim made checkable: an input, what the code should do on it, and what it does.
|
|
32
34
|
evidence: z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) }).optional(),
|
|
@@ -35,7 +37,7 @@ const Finding = z.object({
|
|
|
35
37
|
// The read-only commands the reviewer or verifier ran to check it.
|
|
36
38
|
checked: z.array(z.object({ command: z.string(), result: z.string() })).default([]),
|
|
37
39
|
docs: z.array(z.object({ url: z.string().regex(/^https:\/\/[^\s()<>`]+$/), title: z.string() })).default([]), // the documentation the claim rests on
|
|
38
|
-
reintroduces: z.string().regex(THREAD_URL).optional(), // a resolved thread whose fix this change undoes
|
|
40
|
+
reintroduces: z.string().regex(THREAD_URL).optional().catch(undefined), // a resolved thread whose fix this change undoes
|
|
39
41
|
});
|
|
40
42
|
|
|
41
43
|
export const SummaryInput = z.object({
|
|
@@ -50,7 +52,7 @@ export const SummaryInput = z.object({
|
|
|
50
52
|
diagram: z.string().default(""), // mermaid flowchart source, when the change has a flow worth drawing
|
|
51
53
|
// Pre-merge checks: do the title, description, linked issue and scope match the diff.
|
|
52
54
|
pre_merge: z.array(z.object({ check: z.string(), status: z.enum(["pass", "warn", "fail"]), detail: z.string() })).default([]),
|
|
53
|
-
still_open: z.array(z.object({ url: z.string().regex(THREAD_URL), title: z.string() })).default([]),
|
|
55
|
+
still_open: z.array(z.object({ url: z.string().regex(THREAD_URL).catch(""), title: z.string() })).default([]), // "" renders the title alone
|
|
54
56
|
checks: z.array(z.object({ tool: z.string(), status: z.enum(["ran", "unavailable"]), findings: z.number().default(0), reason: z.string().optional() })).default([]),
|
|
55
57
|
lenses: z.array(z.object({ lens: z.string(), model: z.string().default(""), scope: z.union([z.string(), z.array(z.string())]).default("full"), status: z.enum(["ok", "failed", "could_not_run"]), take: z.string().default(""), skill_blob: z.string().default("") })).default([]),
|
|
56
58
|
lenses_yml_blob: z.string().default(""),
|
|
@@ -146,9 +148,10 @@ function verdictFloor(findings: { severity: z.infer<typeof Severity> }[]): keyof
|
|
|
146
148
|
|
|
147
149
|
if (n("CRITICAL")) return "blocked";
|
|
148
150
|
|
|
149
|
-
|
|
151
|
+
// A HIGH that survives checkedRound names an input the code gets wrong, or is a failing check.
|
|
152
|
+
if (n("HIGH")) return "changes";
|
|
150
153
|
|
|
151
|
-
return n("
|
|
154
|
+
return n("MEDIUM") ? "nits" : "good";
|
|
152
155
|
}
|
|
153
156
|
|
|
154
157
|
const STRICTNESS = ["good", "nits", "changes", "blocked"] as const;
|
|
@@ -189,6 +192,14 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>) {
|
|
|
189
192
|
return s;
|
|
190
193
|
}
|
|
191
194
|
|
|
195
|
+
/** The worst severity among the findings whose tag names the lens (`correctness/data`, `correctness + security`), and how many. */
|
|
196
|
+
function lensTake(lens: string, findings: { lens: string; severity: z.infer<typeof Severity> }[]): string | undefined {
|
|
197
|
+
const mine = findings.filter((f) => f.lens.split(/[\s+/]+/).includes(lens));
|
|
198
|
+
const worst = SEVERITIES.find((sev) => mine.some((f) => f.severity === sev));
|
|
199
|
+
|
|
200
|
+
return worst && `${worst} (${mine.length})`;
|
|
201
|
+
}
|
|
202
|
+
|
|
192
203
|
/** A finding above NIT that no verifier checked. */
|
|
193
204
|
const unverified = (f: z.infer<typeof Finding>) => f.severity !== "NIT" && !fromChecks(f) && !f.verified && !f.checked.length;
|
|
194
205
|
|
|
@@ -202,8 +213,11 @@ export function renderSummary(raw: SummaryInput, emoji: Emoji, header: string |
|
|
|
202
213
|
// as could_not_run.
|
|
203
214
|
const wave = fanout ? Fanout.parse(fanout) : null;
|
|
204
215
|
const sameHead = wave !== null && (wave.head_sha.startsWith(s.head_sha) || s.head_sha.startsWith(wave.head_sha));
|
|
205
|
-
|
|
206
|
-
const
|
|
216
|
+
// The router runs beside every first wave, so a round that leaves it out is missing a reviewer too.
|
|
217
|
+
const expected = sameHead ? [{ lens: "router", scope: "full" as const }, ...wave.lenses] : [];
|
|
218
|
+
const skipped = expected.filter((w) => !s.lenses.some((l) => l.lens === w.lens));
|
|
219
|
+
// A lens's take comes from the findings that name it, so it always agrees with them.
|
|
220
|
+
const lenses = [...s.lenses.map((l) => ({ ...l, take: lensTake(l.lens, s.findings) ?? l.take })), ...skipped.map((w) => ({ lens: w.lens, model: "", scope: w.scope, status: "could_not_run" as const, take: "listed by fanout, no result reported", skill_blob: "" }))];
|
|
207
221
|
const [key, label] = VERDICT[s.verdict];
|
|
208
222
|
const { round, history } = earlierRounds(previous);
|
|
209
223
|
const sha = s.head_sha.slice(0, 7);
|
|
@@ -435,6 +449,10 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
|
|
|
435
449
|
return comment;
|
|
436
450
|
});
|
|
437
451
|
|
|
438
|
-
|
|
452
|
+
// The marker names the head and the comments: publish skips a review only when these same comments are already on
|
|
453
|
+
// the PR, so a new round on the same head posts its own.
|
|
454
|
+
const fingerprint = createHash("sha256").update(JSON.stringify(comments)).digest("hex").slice(0, 12);
|
|
455
|
+
|
|
456
|
+
return { commit_id: s.head_sha, event: "COMMENT" as const, body: `${header}\n\nSee inline comments.\n<!-- shepherd-inline @ ${s.head_sha.slice(0, 7)} ${fingerprint} -->`, comments };
|
|
439
457
|
}
|
|
440
458
|
|
package/templates/shepherd.yml
CHANGED
|
@@ -503,15 +503,25 @@ jobs:
|
|
|
503
503
|
started=${RUN_STARTED:-$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .run_started_at)}
|
|
504
504
|
fresh=$(jq -r --arg s "$started" 'select((.updated_at // "") >= $s) | .id' summary.json)
|
|
505
505
|
if [ -f handoff/round.json ] && command -v shepherd >/dev/null; then
|
|
506
|
-
# The inline review, from the round JSON, unless
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
506
|
+
# The inline review, from the round JSON, unless these same comments are already on the PR: its marker names
|
|
507
|
+
# the head and a fingerprint of the comments, so a new round on an unchanged head still posts its own.
|
|
508
|
+
if ! (cd repo && shepherd inline ../handoff/round.json) > review.json; then
|
|
509
|
+
echo "::warning::could not render the inline review"
|
|
510
|
+
elif [ "$(jq '.comments | length' review.json)" -gt 0 ]; then
|
|
511
|
+
marker=$(jq -r .body review.json | grep -o '<!-- shepherd-inline @ [0-9a-f]* [0-9a-f]* -->' | tail -1)
|
|
512
|
+
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
|
|
513
|
+
echo "this round's inline review is already on the PR"
|
|
514
|
+
else
|
|
515
|
+
gh api "repos/$GITHUB_REPOSITORY/pulls/$PR/reviews" --method POST --input review.json >/dev/null || echo "::warning::could not post the rendered inline review"
|
|
516
|
+
fi
|
|
512
517
|
fi
|
|
513
518
|
fanout=(); [ -f handoff/fanout.json ] && fanout=(--fanout ../handoff/fanout.json)
|
|
514
|
-
|
|
519
|
+
# A round the CLI cannot render keeps whatever findings.md the model wrote; with neither, say so and stop.
|
|
520
|
+
if (cd repo && shepherd summary ../handoff/round.json --previous ../summary.md --body "${fanout[@]}") > rendered.md; then
|
|
521
|
+
mv rendered.md handoff/findings.md
|
|
522
|
+
elif [ ! -f handoff/findings.md ]; then
|
|
523
|
+
echo "::warning::could not render the round's summary, and the iteration left no findings.md"; exit 0
|
|
524
|
+
fi
|
|
515
525
|
else
|
|
516
526
|
[ -n "$fresh" ] && grep -q "@ ${H0:0:7}" summary.md && { echo "the iteration posted its summary ($id)"; exit 0; }
|
|
517
527
|
fi
|