@jagreehal/shepherd 0.12.2 → 0.13.1

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.1",
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
@@ -530,7 +533,8 @@ carries its evidence (the failing check, the gate's refusal, the matched
530
533
  credential shape) and keeps the grade Step 2 gives it. Give a `suggestion`
531
534
  (the replacement lines, no fence) only when the fix replaces exactly the lines
532
535
  in `line`, written `"start-end"` for a range: GitHub commits it as written, so
533
- it must compile on its own. When the fix spans other lines or files, put a
536
+ it must compile on its own. It holds the new code and nothing else; advice
537
+ such as "use `toBe` for an exact match" belongs in the body. When the fix spans other lines or files, put a
534
538
  `diff` block in the body instead. `verified` holds what the verifier quoted,
535
539
  for every finding above NIT.
536
540
 
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,141 @@ 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
+ const replaced = lines.slice((at?.start ?? 1) - 1, at?.end ?? 0);
243
+
244
+ // A suggestion is committed as written, so over code it carries code: advice stays in the comment.
245
+ if (!at || adviceOverCode(f.file, f.suggestion, replaced, lines.slice(0, at.start - 1).join("\n"))) {
246
+ f.suggestion = undefined;
247
+
248
+ return;
249
+ }
250
+
251
+ f.line = end === undefined ? at.start : `${at.start}-${at.end}`;
252
+ // The baseline is the indentation the replaced lines share, so a block that dedents keeps its shape.
253
+ f.suggestion = reindent(f.suggestion, sharedIndent(replaced));
254
+ }
255
+
256
+ // Files whose lines are prose: a sentence there is the content, not advice.
257
+ const PROSE_FILE = /\.(md|mdx|markdown|txt|rst|adoc)$/i;
258
+
259
+ // Words that mark English advice rather than code: articles and the verbs reviewers use to recommend a change.
260
+ const ADVICE_WORDS = new Set(["the", "an", "instead", "should", "use", "rather", "than", "consider", "prefer", "avoid", "please", "add", "replace", "change", "remove", "make", "sure"]);
261
+
262
+ /**
263
+ * Whether a suggestion over code carries advice in place of code: a run of three or more plain words outside strings
264
+ * and comments that holds an English marker word, with at least two in three of its words new to the replaced lines.
265
+ * `before` is the file above the replaced lines, so a string or comment already open there counts as open.
266
+ */
267
+ export function adviceOverCode(file: string, suggestion: string, replaced: string[], before = ""): boolean {
268
+ if (PROSE_FILE.test(file)) return false;
269
+
270
+ const known = new Set(replaced.join("\n").toLowerCase().match(/[a-z]+/g) ?? []);
271
+ const code = outsideStrings(suggestion, outsideStrings(before).open);
272
+
273
+ return (code.text.match(/[A-Za-z]+(?:[ \t]+[A-Za-z]+){2,}/g) ?? []).some((run) => {
274
+ const words = run.toLowerCase().split(/[ \t]+/);
275
+
276
+ return words.some((w) => ADVICE_WORDS.has(w)) && words.filter((w) => !known.has(w)).length * 3 >= words.length * 2;
277
+ });
278
+ }
279
+
280
+ /**
281
+ * The text outside string literals and comments, each masked by `◊`, and the string or block comment still open at
282
+ * the end. Backticks, triple quotes and block comments carry across lines; single and double quotes, and `//`, `#`
283
+ * and `--` comments, end at the line. `open` starts the scan inside one.
284
+ */
285
+ function outsideStrings(text: string, open = "") {
286
+ let out = "";
287
+ let i = 0;
288
+ let inside = open;
289
+
290
+ while (i < text.length) {
291
+ if (inside) {
292
+ const close = text.indexOf(inside, i);
293
+ const newline = inside === '"' || inside === "'" ? text.indexOf("\n", i) : -1;
294
+
295
+ if (newline >= 0 && (close < 0 || close > newline)) {
296
+ [i, inside] = [newline, ""];
297
+ out += " ◊ ";
298
+ continue;
299
+ }
300
+
301
+ if (inside.length === 1 && close > 0 && text[close - 1] === "\\") {
302
+ i = close + 1;
303
+ continue;
304
+ }
305
+
306
+ i = close < 0 ? text.length : close + inside.length;
307
+ inside = close < 0 ? inside : "";
308
+ out += " ◊ ";
309
+ continue;
310
+ }
311
+
312
+ const rest = text.slice(i);
313
+ const opener = /^("""|'''|\/\*|["'`])/.exec(rest)?.[1];
314
+
315
+ if (opener) {
316
+ inside = opener === "/*" ? "*/" : opener;
317
+ i += opener.length;
318
+ continue;
319
+ }
320
+
321
+ if (/^(\/\/|#|--)/.test(rest)) {
322
+ const newline = text.indexOf("\n", i);
323
+
324
+ i = newline < 0 ? text.length : newline;
325
+ out += " ◊ ";
326
+ continue;
327
+ }
328
+
329
+ out += text[i];
330
+ i++;
331
+ }
332
+
333
+ return { text: out, open: inside };
334
+ }
335
+
336
+ /**
337
+ * The suggestion at the indentation of the lines it replaces, since GitHub commits it as written. The indentation its
338
+ * non-blank lines share becomes `target`, in spaces or tabs, and each line keeps what it adds on top.
339
+ */
340
+ export function reindent(suggestion: string, target: string): string {
341
+ const lines = suggestion.split("\n");
342
+ const common = sharedIndent(lines);
343
+
344
+ return lines.map((l) => (l.trim() ? target + l.slice(common.length) : l)).join("\n");
345
+ }
346
+
347
+ /** The leading whitespace every non-blank line starts with: the block's own indentation. */
348
+ function sharedIndent(lines: string[]): string {
349
+ const indents = lines.flatMap((l) => (l.trim() ? [/^[ \t]*/.exec(l)![0]] : []));
350
+
351
+ return indents.reduce((shared, own) => {
352
+ let n = 0;
353
+
354
+ while (n < shared.length && n < own.length && shared[n] === own[n]) n++;
355
+
356
+ return shared.slice(0, n);
357
+ }, indents[0] ?? "");
358
+ }
359
+
218
360
  /** The worst severity among the findings whose tag names the lens (`correctness/data`, `correctness + security`), and how many. */
219
361
  function lensTake(lens: string, findings: { lens: string; severity: z.infer<typeof Severity> }[]): string | undefined {
220
362
  const mine = findings.filter((f) => f.lens.split(/[\s+/]+/).includes(lens));
@@ -230,8 +372,8 @@ const unverified = (f: z.infer<typeof Finding>) => f.severity !== "NIT" && !from
230
372
  * The summary comment: the verdict heading, why, then one collapsed section per part of the round. With a null header
231
373
  * it is the body alone, for the handoff file the publish job wraps in its own marker and header.
232
374
  */
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);
375
+ 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 {
376
+ const s = checkedRound(raw, threads, read);
235
377
  // A lens fanout listed for this head that the round does not report never ran as its own reviewer, so it shows
236
378
  // as could_not_run.
237
379
  const wave = fanout ? Fanout.parse(fanout) : null;
@@ -383,7 +525,7 @@ const AHEAD = 0.1; // how far a moved suggestion's window must lead the next mos
383
525
  * rewrites. The lines named stay when they are alike enough. Otherwise it moves to the window of the same size, within
384
526
  * five lines, that is alike enough, differs from the suggestion and leads the next most alike; with none, it is dropped.
385
527
  */
386
- export function anchorSuggestion(lines: string[], start: number, end: number, suggestion: string): { start: number; end: number } | null {
528
+ export function anchorSuggestion(lines: string[], start: number, end: number, suggestion: string, near = NEAR): { start: number; end: number } | null {
387
529
  const size = end - start + 1;
388
530
  const flat = (t: string) => t.replace(/\s+/g, " ").trim();
389
531
 
@@ -394,10 +536,13 @@ export function anchorSuggestion(lines: string[], start: number, end: number, su
394
536
  };
395
537
 
396
538
  if (end <= lines.length && score(start) >= LIKE) return { start, end };
397
- const near: { from: number; score: number }[] = [];
539
+ const tried: { from: number; score: number }[] = [];
540
+
541
+ // A whole-file search (near >= the file's length) covers every window, wherever the cited line was.
542
+ 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
543
 
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);
544
+ for (let from = lo; from <= hi; from++) tried.push({ from, score: score(from) });
545
+ const [best, next] = tried.sort((a, b) => b.score - a.score);
401
546
 
402
547
  return best && best.score >= LIKE && best.score - (next?.score ?? 0) >= AHEAD ? { start: best.from, end: best.from + size - 1 } : null;
403
548
  }
@@ -406,7 +551,7 @@ export function anchorSuggestion(lines: string[], start: number, end: number, su
406
551
  const insideRepo = (p: string) => !p.startsWith("/") && !p.split(/[\\/]/).includes("..");
407
552
 
408
553
  export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, read: (path: string) => string | null = () => null, threads?: ReadonlySet<string>) {
409
- const s = checkedRound(raw, threads);
554
+ const s = checkedRound(raw, threads, read);
410
555
  const glyph = (sev: z.infer<typeof Severity>) => emoji[GLYPH[sev]];
411
556
 
412
557
  // A line past the end of the file it names cannot anchor: GitHub rejects the whole review over one such comment.
@@ -416,20 +561,22 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
416
561
  return text === null || Number(String(f.line).split("-").at(-1)) <= text.replace(/\n$/, "").split("\n").length;
417
562
  };
418
563
 
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);
564
+ 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
+ // One comment per place, the most severe finding's. Others on the same lines are named under it and appear in full
566
+ // in the summary.
567
+ const at = (f: (typeof s.findings)[number]) => `${f.file}:${f.line}`;
568
+ const posted = anchored.filter((f, i) => anchored.findIndex((g) => at(g) === at(f)) === i).slice(0, PER_REVIEW);
420
569
 
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;
570
+ const alsoHere = (f: (typeof s.findings)[number]) => {
571
+ const rest = anchored.filter((g) => g !== f && at(g) === at(f));
426
572
 
427
- if (fix !== undefined) {
428
- const at = text === null ? null : anchorSuggestion(text.split("\n"), start, end ?? start, fix);
573
+ return rest.length ? ["", `**Also here:** ${rest.map((g) => `${glyph(g.severity)} ${g.severity} ${defuse(g.title || g.body.split("\n")[0]!, true)}`).join(" · ")}`] : [];
574
+ };
429
575
 
430
- if (at) [start, end] = [at.start, end === undefined ? undefined : at.end];
431
- else fix = undefined;
432
- }
576
+ const comments = posted.map((f) => {
577
+ const [start = 0, end] = String(f.line).split("-").map(Number); // `posted` kept only numeric lines and "a-b" ranges
578
+ // checkedRound placed the suggestion and kept it only where it fits.
579
+ const fix = f.suggestion;
433
580
 
434
581
  const suggestion = fix !== undefined ? ["", "```suggestion", fix, "```"] : [];
435
582
  const where = end === undefined ? `${start}` : `${start}-${end}`;
@@ -446,6 +593,7 @@ export function renderReview(raw: SummaryInput, emoji: Emoji, header: string, re
446
593
  ...evidenceBlock(f),
447
594
  ...docsLine(f),
448
595
  ...suggestion,
596
+ ...alsoHere(f),
449
597
  ...(f.verified ? ["", `**Verified:** ${defuse(f.verified)}`] : []),
450
598
  ...(unverified(f) ? ["", "⚠️ No verifier has checked this yet."] : []),
451
599
  ...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