@jagreehal/shepherd 0.13.0 → 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.13.0",
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",
@@ -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
 
package/src/summary.ts CHANGED
@@ -239,7 +239,10 @@ function place(f: z.infer<typeof Finding>, read: (path: string) => string | null
239
239
  // Near the cited line first, then across the whole file, which still needs one clear best match.
240
240
  const at = text === null || !start ? null : (anchorSuggestion(lines, start, end ?? start, f.suggestion) ?? anchorSuggestion(lines, start, end ?? start, f.suggestion, lines.length));
241
241
 
242
- if (!at) {
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"))) {
243
246
  f.suggestion = undefined;
244
247
 
245
248
  return;
@@ -247,7 +250,87 @@ function place(f: z.infer<typeof Finding>, read: (path: string) => string | null
247
250
 
248
251
  f.line = end === undefined ? at.start : `${at.start}-${at.end}`;
249
252
  // 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)));
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 };
251
334
  }
252
335
 
253
336
  /**