@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jagreehal/shepherd",
3
- "version": "0.12.2",
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",
@@ -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), reruns the jobs, and notifies. It refuses a
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.
@@ -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. A finding on a line
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
- process.stdout.write(orExit(() => renderSummary(input, b.emoji, opts.body ? null : b.headers.swarm, previous, fanout, reviewThreads())));
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
- evidence: absent(z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) })),
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>): 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 near: { from: number; score: number }[] = [];
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 = Math.max(1, start - NEAR); from <= Math.min(lines.length - size + 1, start + NEAR); from++) near.push({ from, score: score(from) });
400
- const [best, next] = near.sort((a, b) => b.score - a.score);
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 posted = SEVERITIES.flatMap((sev) => s.findings.filter((f) => f.severity === sev && sev !== "NIT" && f.inline && f.file && f.line !== undefined && f.line !== "general" && fits(f))).slice(0, PER_REVIEW);
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 comments = posted.map((f) => {
422
- let [start = 0, end] = String(f.line).split("-").map(Number); // `posted` kept only numeric lines and "a-b" ranges
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
- if (fix !== undefined) {
428
- const at = text === null ? null : anchorSuggestion(text.split("\n"), start, end ?? start, fix);
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
- if (at) [start, end] = [at.start, end === undefined ? undefined : at.end];
431
- else fix = undefined;
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),
@@ -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