@jagreehal/shepherd 0.13.0 → 0.13.2

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.13.0",
3
+ "version": "0.13.2",
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",
@@ -533,7 +533,8 @@ carries its evidence (the failing check, the gate's refusal, the matched
533
533
  credential shape) and keeps the grade Step 2 gives it. Give a `suggestion`
534
534
  (the replacement lines, no fence) only when the fix replaces exactly the lines
535
535
  in `line`, written `"start-end"` for a range: GitHub commits it as written, so
536
- 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
537
538
  `diff` block in the body instead. `verified` holds what the verifier quoted,
538
539
  for every finding above NIT.
539
540
 
@@ -84,7 +84,10 @@ read takes, 1 (a minute) to 5 (an hour or more). Draw a `diagram` only when the
84
84
  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. A field
87
- written as `null` reads as absent and takes its default.
87
+ written as `null` reads as absent and takes its default. Write `evidence` as
88
+ the object above; text that labels its input, expected and actual result is
89
+ read too. A finding without a `title` takes its body's first sentence, and
90
+ `line` with `line_end` reads as `"line-line_end"`.
88
91
  The renderers hold the round to what they can check. A `url`, `reintroduces`
89
92
  or still-open link that names no review comment on the PR, or is not a
90
93
  GitHub URL, loses its link.
package/src/summary.ts CHANGED
@@ -23,11 +23,52 @@ const flag = (fallback: boolean) => z.boolean().nullish().transform((v) => v ??
23
23
 
24
24
  const EvidenceParts = z.object({ input: z.string().min(1), expected: z.string().min(1), actual: z.string().min(1) });
25
25
 
26
- /** `Input: "Ada Lovelace", Expected: "Ada", Actual: "Lovelace"`, in any case and with `;` or `·` between: the three parts, or nothing. */
26
+ /** The body's first sentence or line, up to 100 characters. */
27
+ function firstSentence(body: string): string {
28
+ const sentence = body.trim().split(/(?<=[.!?])\s|\n/)[0] ?? "";
29
+
30
+ return sentence.length > 100 ? `${sentence.slice(0, 99).trimEnd()}…` : sentence;
31
+ }
32
+
33
+ // A label with any bold around it (`**Input:**`, `**Input**:`, `__Input:__`), so emphasis is read off the label alone.
34
+ const label = (words: string) => new RegExp(String.raw`(?:\*\*|__)?(?<![a-z0-9])(?:${words})(?:\*\*|__)?\s*[:=](?:\*\*|__)?`, "i");
35
+
36
+ // The labels a worked example uses for its three parts, with the synonyms models reach for.
37
+ const EVIDENCE_LABELS = {
38
+ input: label("input|given|for input|when called with"),
39
+ expected: label("expected|expect|should (?:be|return)|wanted|want"),
40
+ actual: label("actual|got|returns|result|observed"),
41
+ };
42
+
43
+ /**
44
+ * A worked example written as text, such as `Input: "Ada Lovelace" | Expected: "Ada" | Actual: "Lovelace"`: each label
45
+ * found in any order and case, bold around a label ignored, and any separator (`,` `;` `|` `·` `→` `->` ` - ` or a line
46
+ * break) between the parts. A label inside a quoted value is part of that value, and each value keeps its own
47
+ * characters, so `-1` and a closing `;` stay. The three parts, or nothing when a label is missing.
48
+ */
27
49
  function evidenceFromLine(line: string) {
28
- const m = /input:\s*(.+?)\s*[,;·]\s*expected:\s*(.+?)\s*[,;·]\s*actual:\s*(.+)$/is.exec(line.trim());
50
+ // Blank each quoted value to its own length, so a label inside a quote stays part of the value and positions match.
51
+ const unquoted = line.replaceAll(/"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\\n])*`|(?<![a-z0-9])'(?:\\.|[^'\\\n])*'/gi, (quoted) => " ".repeat(quoted.length));
52
+
53
+ const found = Object.entries(EVIDENCE_LABELS).flatMap(([part, pattern]) => {
54
+ const m = pattern.exec(unquoted);
55
+
56
+ return m ? [{ part, start: m.index, from: m.index + m[0].length }] : [];
57
+ });
58
+
59
+ if (found.length < 3) return undefined;
60
+ const ordered = [...found].sort((a, b) => a.start - b.start);
29
61
 
30
- return m ? { input: m[1]!, expected: m[2]!, actual: m[3]! } : undefined;
62
+ // One separator comes off a value that runs into the next label on the same line; a line break is separator enough.
63
+ const valueOf = (raw: string, last: boolean) => {
64
+ const value = raw.trim();
65
+
66
+ return last || /\n\s*$/.test(raw) ? value : value.replace(/\s*(?:[|,;·→]|[-=]>|(?<=\s)-)$/, "");
67
+ };
68
+
69
+ 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)]));
70
+
71
+ return parts.input && parts.expected && parts.actual ? { input: parts.input, expected: parts.expected, actual: parts.actual } : undefined;
31
72
  }
32
73
 
33
74
  const VERDICT_ALIAS = alias({ changes_needed: "changes", approve_with_nits: "nits", looks_good: "good", approve: "good", approved: "good" });
@@ -64,6 +105,12 @@ const Finding = z.object({
64
105
  checked: z.array(z.object({ command: z.string(), result: z.string() })).nullish().transform((v) => v ?? []),
65
106
  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
107
  reintroduces: absent(z.string().regex(THREAD_URL)).catch(undefined), // a resolved thread whose fix this change undoes
108
+ // A range written as `line` and `line_end` reads as "line-line_end".
109
+ line_end: absent(z.union([z.number().int().positive(), z.string().regex(/^[1-9]\d*$/).transform(Number)])),
110
+ }).transform(({ line_end: last, ...f }) => {
111
+ const start = /^\d+$/.test(String(f.line)) ? Number(f.line) : undefined;
112
+
113
+ return last !== undefined && start !== undefined && last > start ? { ...f, line: `${start}-${last}` } : f;
67
114
  });
68
115
 
69
116
  export const SummaryInput = z.object({
@@ -204,6 +251,8 @@ export function checkedRound(raw: SummaryInput, threads?: ReadonlySet<string>, r
204
251
 
205
252
  for (const f of s.findings) {
206
253
  f.convergent &&= f.lens.includes("+");
254
+ // A finding without a title takes its first sentence, so a reader can triage it by the title alone.
255
+ f.title ||= firstSentence(f.body);
207
256
  f.url = real(f.url);
208
257
  f.reintroduces = real(f.reintroduces);
209
258
 
@@ -239,7 +288,10 @@ function place(f: z.infer<typeof Finding>, read: (path: string) => string | null
239
288
  // Near the cited line first, then across the whole file, which still needs one clear best match.
240
289
  const at = text === null || !start ? null : (anchorSuggestion(lines, start, end ?? start, f.suggestion) ?? anchorSuggestion(lines, start, end ?? start, f.suggestion, lines.length));
241
290
 
242
- if (!at) {
291
+ const replaced = lines.slice((at?.start ?? 1) - 1, at?.end ?? 0);
292
+
293
+ // A suggestion is committed as written, so over code it carries code: advice stays in the comment.
294
+ if (!at || adviceOverCode(f.file, f.suggestion, replaced, lines.slice(0, at.start - 1).join("\n"))) {
243
295
  f.suggestion = undefined;
244
296
 
245
297
  return;
@@ -247,7 +299,87 @@ function place(f: z.infer<typeof Finding>, read: (path: string) => string | null
247
299
 
248
300
  f.line = end === undefined ? at.start : `${at.start}-${at.end}`;
249
301
  // 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)));
302
+ f.suggestion = reindent(f.suggestion, sharedIndent(replaced));
303
+ }
304
+
305
+ // Files whose lines are prose: a sentence there is the content, not advice.
306
+ const PROSE_FILE = /\.(md|mdx|markdown|txt|rst|adoc)$/i;
307
+
308
+ // Words that mark English advice rather than code: articles and the verbs reviewers use to recommend a change.
309
+ const ADVICE_WORDS = new Set(["the", "an", "instead", "should", "use", "rather", "than", "consider", "prefer", "avoid", "please", "add", "replace", "change", "remove", "make", "sure"]);
310
+
311
+ /**
312
+ * Whether a suggestion over code carries advice in place of code: a run of three or more plain words outside strings
313
+ * and comments that holds an English marker word, with at least two in three of its words new to the replaced lines.
314
+ * `before` is the file above the replaced lines, so a string or comment already open there counts as open.
315
+ */
316
+ export function adviceOverCode(file: string, suggestion: string, replaced: string[], before = ""): boolean {
317
+ if (PROSE_FILE.test(file)) return false;
318
+
319
+ const known = new Set(replaced.join("\n").toLowerCase().match(/[a-z]+/g) ?? []);
320
+ const code = outsideStrings(suggestion, outsideStrings(before).open);
321
+
322
+ return (code.text.match(/[A-Za-z]+(?:[ \t]+[A-Za-z]+){2,}/g) ?? []).some((run) => {
323
+ const words = run.toLowerCase().split(/[ \t]+/);
324
+
325
+ return words.some((w) => ADVICE_WORDS.has(w)) && words.filter((w) => !known.has(w)).length * 3 >= words.length * 2;
326
+ });
327
+ }
328
+
329
+ /**
330
+ * The text outside string literals and comments, each masked by `◊`, and the string or block comment still open at
331
+ * the end. Backticks, triple quotes and block comments carry across lines; single and double quotes, and `//`, `#`
332
+ * and `--` comments, end at the line. `open` starts the scan inside one.
333
+ */
334
+ function outsideStrings(text: string, open = "") {
335
+ let out = "";
336
+ let i = 0;
337
+ let inside = open;
338
+
339
+ while (i < text.length) {
340
+ if (inside) {
341
+ const close = text.indexOf(inside, i);
342
+ const newline = inside === '"' || inside === "'" ? text.indexOf("\n", i) : -1;
343
+
344
+ if (newline >= 0 && (close < 0 || close > newline)) {
345
+ [i, inside] = [newline, ""];
346
+ out += " ◊ ";
347
+ continue;
348
+ }
349
+
350
+ if (inside.length === 1 && close > 0 && text[close - 1] === "\\") {
351
+ i = close + 1;
352
+ continue;
353
+ }
354
+
355
+ i = close < 0 ? text.length : close + inside.length;
356
+ inside = close < 0 ? inside : "";
357
+ out += " ◊ ";
358
+ continue;
359
+ }
360
+
361
+ const rest = text.slice(i);
362
+ const opener = /^("""|'''|\/\*|["'`])/.exec(rest)?.[1];
363
+
364
+ if (opener) {
365
+ inside = opener === "/*" ? "*/" : opener;
366
+ i += opener.length;
367
+ continue;
368
+ }
369
+
370
+ if (/^(\/\/|#|--)/.test(rest)) {
371
+ const newline = text.indexOf("\n", i);
372
+
373
+ i = newline < 0 ? text.length : newline;
374
+ out += " ◊ ";
375
+ continue;
376
+ }
377
+
378
+ out += text[i];
379
+ i++;
380
+ }
381
+
382
+ return { text: out, open: inside };
251
383
  }
252
384
 
253
385
  /**