@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 +1 -1
- package/skills/swarm/SKILL.md +2 -1
- package/skills/swarm/references/formats.md +4 -1
- package/src/summary.ts +137 -5
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.13.
|
|
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",
|
package/skills/swarm/SKILL.md
CHANGED
|
@@ -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.
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
/**
|