@jagreehal/shepherd 0.15.0 → 0.16.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.
Files changed (81) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +40 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/gate/.shepherd/gate.schema.json +647 -0
  5. package/gate/.shepherd/gate.yml +122 -0
  6. package/gate/.shepherd/review-guidance.md +95 -0
  7. package/gate/src/actions.ts +32 -0
  8. package/gate/src/cli.ts +1028 -0
  9. package/gate/src/config.ts +102 -0
  10. package/gate/src/delta.ts +29 -0
  11. package/gate/src/env.ts +30 -0
  12. package/gate/src/eval.ts +288 -0
  13. package/gate/src/familiarity.ts +461 -0
  14. package/gate/src/github.ts +761 -0
  15. package/gate/src/inline.ts +59 -0
  16. package/gate/src/isolated-cli.ts +281 -0
  17. package/gate/src/leads.ts +257 -0
  18. package/gate/src/llm.ts +606 -0
  19. package/gate/src/notify.ts +57 -0
  20. package/gate/src/policy.ts +1297 -0
  21. package/gate/src/provider-errors.ts +80 -0
  22. package/gate/src/retention.ts +86 -0
  23. package/gate/src/reviewer.ts +739 -0
  24. package/gate/src/signals.ts +105 -0
  25. package/gate/src/smoke-live.ts +64 -0
  26. package/gate/src/stack.ts +87 -0
  27. package/gate/src/stories.ts +297 -0
  28. package/gate/templates/policy-strict.yml +127 -0
  29. package/gate/templates/reviewer.Dockerfile +8 -0
  30. package/gate/templates/rules/observability/SKILL.md +33 -0
  31. package/gate/templates/shepherd-gate-actions.yml +35 -0
  32. package/gate/templates/shepherd-gate-edited.yml +29 -0
  33. package/gate/templates/shepherd-gate.yml +111 -0
  34. package/lenses/dotnet/SKILL.md +1 -1
  35. package/lenses/go/SKILL.md +1 -1
  36. package/lenses/java/SKILL.md +1 -1
  37. package/lenses/nextjs/SKILL.md +1 -1
  38. package/lenses/node-api/SKILL.md +1 -1
  39. package/lenses/nx-monorepo/SKILL.md +1 -1
  40. package/lenses/observability/SKILL.md +1 -1
  41. package/lenses/owasp-asvs/SKILL.md +1 -1
  42. package/lenses/owasp-llm/SKILL.md +1 -1
  43. package/lenses/pstack/SKILL.md +1 -1
  44. package/lenses/python/SKILL.md +1 -1
  45. package/lenses/react/SKILL.md +1 -1
  46. package/lenses/rust/SKILL.md +1 -1
  47. package/package.json +20 -6
  48. package/schema/config.json +1 -1
  49. package/skills/branch-review/SKILL.md +123 -0
  50. package/skills/ci-repair/SKILL.md +79 -35
  51. package/skills/garden/SKILL.md +8 -8
  52. package/skills/garden/references/telemetry.md +4 -4
  53. package/skills/incident/SKILL.md +9 -9
  54. package/skills/lens-import/SKILL.md +7 -7
  55. package/skills/review-slop/SKILL.md +1 -1
  56. package/skills/shepherd/SKILL.md +43 -41
  57. package/skills/shepherd/references/degradation.md +3 -3
  58. package/skills/shepherd/references/dispatch.md +1 -1
  59. package/skills/shepherd/references/formats.md +5 -5
  60. package/skills/shepherd/references/models.md +2 -2
  61. package/skills/shepherd/references/policy.md +9 -9
  62. package/skills/swarm/SKILL.md +21 -17
  63. package/skills/swarm/references/custom-lenses.md +2 -2
  64. package/skills/swarm/references/formats.md +1 -1
  65. package/skills/triage/SKILL.md +10 -10
  66. package/src/bin.ts +10 -0
  67. package/src/cli.ts +283 -41
  68. package/src/config.ts +26 -25
  69. package/src/doctor.ts +31 -18
  70. package/src/garden-traces.ts +13 -13
  71. package/src/garden.ts +4 -4
  72. package/src/lens.ts +19 -7
  73. package/src/setup.ts +72 -0
  74. package/src/stack.ts +2 -2
  75. package/src/status.ts +80 -0
  76. package/src/summary.ts +52 -9
  77. package/src/trace.ts +4 -4
  78. package/src/working.ts +30 -0
  79. package/templates/shepherd-audit.yml +7 -15
  80. package/templates/shepherd-incident.yml +7 -12
  81. package/templates/shepherd.yml +39 -40
@@ -0,0 +1,461 @@
1
+ // Author-familiarity signal for the reviewer (judgment layer only).
2
+ //
3
+ // Blame overlap + prior merged PRs in the changed paths → STRONG / MODERATE / NONE.
4
+ // Never a gate; failures yield null (signal absent). NONE omits negative facts
5
+ // from the prompt (one-way ratchet).
6
+ //
7
+ // Every history query is anchored to the default branch (`trustedRef`), never to
8
+ // the checkout: the checkout is the PR head, and a PR's own commit subjects could
9
+ // otherwise claim the author's merged PR numbers and manufacture familiarity.
10
+ import { execFileSync } from "node:child_process";
11
+ import path from "node:path";
12
+ import { z } from "zod";
13
+ import { GH_CREDENTIALS, mergedPRNumbers } from "./github.ts";
14
+
15
+ /** Author names are untrusted display hints; strip controls and cap length. */
16
+ const scrubName = (s: string, max: number) => s.replace(/[^\P{C}\n\t]/gu, "").slice(0, max);
17
+
18
+ export const FamiliarityPolicySchema = z
19
+ .object({
20
+ strong: z.object({ min_blame_overlap_pct: z.number().min(0).max(100) }),
21
+ moderate: z.object({
22
+ min_prior_prs: z.number().int().positive(),
23
+ max_days_since_touch: z.number().int().positive(),
24
+ }),
25
+ })
26
+ .strict();
27
+
28
+ export type FamiliarityPolicy = z.infer<typeof FamiliarityPolicySchema>;
29
+
30
+ export type AuthorFamiliarity = {
31
+ band: "STRONG" | "MODERATE" | "NONE";
32
+ blame_overlap_pct: number;
33
+ modified_lines_owned: number;
34
+ modified_lines_total: number;
35
+ prior_prs_in_paths: number;
36
+ days_since_last_touch: number | null;
37
+ files_prev_count: number;
38
+ files_total: number;
39
+ capped: boolean;
40
+ blame_incomplete_files: number;
41
+ top_prior_authors: string[];
42
+ };
43
+
44
+ export const familiarityEvidence = (fam: AuthorFamiliarity | null) => fam && { ...fam, blame_overlap_pct: Math.round(fam.blame_overlap_pct * 10) / 10 };
45
+
46
+ const TIMEOUT_MS = 30_000;
47
+
48
+ const UNSHALLOW_TIMEOUT_MS = 5 * 60_000;
49
+
50
+ const MAX_CHANGED_LINES_PER_FILE = 2000;
51
+
52
+ const MAX_BLAME_FILES = 30;
53
+
54
+ const LOG_SINCE = "18.months";
55
+
56
+ const TWELVE_MONTHS_DAYS = 365;
57
+
58
+ const TOP_PRIOR_AUTHORS = 2;
59
+
60
+ const SQUASH_PR_RE = /\(#(\d+)\)/g;
61
+
62
+ const HUNK_RE = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
63
+
64
+
65
+ type FileDiff = {
66
+ old_path: string | null;
67
+ new_path: string | null;
68
+ base_modified_lines: number[];
69
+ changed_lines: number;
70
+ is_binary: boolean;
71
+ };
72
+
73
+ type BlameOverlap = { owned: number; total: number; incomplete: number; topPriorAuthors: string[] };
74
+
75
+ const path_of = (f: FileDiff) => f.new_path || f.old_path || "";
76
+
77
+ function git(repoRoot: string, args: string[], timeout = TIMEOUT_MS): string | null {
78
+ try {
79
+ return execFileSync("git", ["-C", repoRoot, ...args], {
80
+ encoding: "utf8",
81
+ timeout,
82
+ maxBuffer: 16 << 20,
83
+ stdio: ["ignore", "pipe", "ignore"],
84
+ });
85
+ } catch {
86
+ return null;
87
+ }
88
+ }
89
+
90
+ /** The author's merged PR numbers, or null when GitHub cannot say: the signal is then absent, never wrong. */
91
+ function fetchAuthorPrNumbers(authorLogin: string, repo: string, cwd: string): Set<number> | null {
92
+ try {
93
+ return mergedPRNumbers(repo, authorLogin, cwd);
94
+ } catch {
95
+ return null;
96
+ }
97
+ }
98
+
99
+ function extractPrNumber(subject: string): number | null {
100
+ let last: number | null = null;
101
+
102
+ for (const m of subject.matchAll(SQUASH_PR_RE)) last = Number(m[1]);
103
+
104
+ return last;
105
+ }
106
+
107
+ // C escapes Git writes inside a quoted path, as the byte each one stands for.
108
+ const QUOTED_ESCAPES = new Map([["a", 7], ["b", 8], ["t", 9], ["n", 10], ["v", 11], ["f", 12], ["r", 13], ['"', 34], ["\\", 92]]);
109
+
110
+ /** A path Git quoted (`"b/caf\\303\\251.ts"`, for non-ASCII bytes or control characters) back to its UTF-8 text. */
111
+ function unquoteGitPath(quoted: string): string {
112
+ const bytes: number[] = [];
113
+
114
+ for (let i = 0; i < quoted.length; i++) {
115
+ if (quoted[i] !== "\\") {
116
+ bytes.push(...Buffer.from(quoted[i]!));
117
+ continue;
118
+ }
119
+
120
+ const octal = /^[0-7]{3}/.exec(quoted.slice(i + 1));
121
+
122
+ if (octal) {
123
+ bytes.push(parseInt(octal[0], 8));
124
+ i += 3;
125
+ } else {
126
+ bytes.push(QUOTED_ESCAPES.get(quoted[i + 1] ?? "") ?? quoted.charCodeAt(i + 1));
127
+ i++;
128
+ }
129
+ }
130
+
131
+ return Buffer.from(bytes).toString("utf8");
132
+ }
133
+
134
+ /** The repository path in a `---`/`+++` header value, unquoted, without its a/ or b/ prefix; null for /dev/null. */
135
+ export function stripDiffPath(raw: string): string | null {
136
+ let t = raw.trim();
137
+
138
+ if (t.length > 1 && t.startsWith('"') && t.endsWith('"')) t = unquoteGitPath(t.slice(1, -1));
139
+
140
+ if (t === "/dev/null") return null;
141
+
142
+ if (t.startsWith("a/") || t.startsWith("b/")) return t.slice(2);
143
+
144
+ return t;
145
+ }
146
+
147
+ /** Parse a unified diff into per-file base-side modified line numbers (deleted/replaced lines). */
148
+ export function parseDiff(diffText: string): FileDiff[] {
149
+ const files: FileDiff[] = [];
150
+ let current: FileDiff | null = null;
151
+ let seenHunk = false;
152
+ let oldLine = 0;
153
+
154
+ for (const line of diffText.split("\n")) {
155
+ if (line.startsWith("diff --git")) {
156
+ if (current) files.push(current);
157
+ current = { old_path: null, new_path: null, base_modified_lines: [], changed_lines: 0, is_binary: false };
158
+ seenHunk = false;
159
+ oldLine = 0;
160
+ continue;
161
+ }
162
+
163
+ if (!current) continue;
164
+
165
+ if (line.startsWith("Binary files") || line.startsWith("GIT binary patch")) {
166
+ current.is_binary = true;
167
+ continue;
168
+ }
169
+
170
+ if (!seenHunk && line.startsWith("--- ")) {
171
+ current.old_path = stripDiffPath(line.slice(4));
172
+ continue;
173
+ }
174
+
175
+ if (!seenHunk && line.startsWith("+++ ")) {
176
+ current.new_path = stripDiffPath(line.slice(4));
177
+ continue;
178
+ }
179
+
180
+ const hunk = HUNK_RE.exec(line);
181
+
182
+ if (hunk) {
183
+ seenHunk = true;
184
+ oldLine = Number(hunk[1]);
185
+ continue;
186
+ }
187
+
188
+ if (!seenHunk || !line) continue;
189
+ const tag = line[0];
190
+
191
+ if (tag === "-") {
192
+ current.base_modified_lines.push(oldLine);
193
+ current.changed_lines += 1;
194
+ oldLine += 1;
195
+ } else if (tag === "+") {
196
+ current.changed_lines += 1;
197
+ } else if (tag === " ") {
198
+ oldLine += 1;
199
+ }
200
+ }
201
+
202
+ if (current) files.push(current);
203
+
204
+ return files;
205
+ }
206
+
207
+ function coalesce(lines: number[]): [number, number][] {
208
+ const ranges: [number, number][] = [];
209
+
210
+ for (const n of [...new Set(lines)].sort((a, b) => a - b)) {
211
+ const last = ranges.at(-1);
212
+
213
+ if (last && n === last[1] + 1) last[1] = n;
214
+ else ranges.push([n, n]);
215
+ }
216
+
217
+ return ranges;
218
+ }
219
+
220
+ function selectConsidered(fileDiffs: FileDiff[]) {
221
+ const eligible = fileDiffs.filter((f) => !f.is_binary && f.changed_lines <= MAX_CHANGED_LINES_PER_FILE);
222
+ const oversize = fileDiffs.some((f) => !f.is_binary && f.changed_lines > MAX_CHANGED_LINES_PER_FILE);
223
+ eligible.sort((a, b) => b.changed_lines - a.changed_lines);
224
+
225
+ return { considered: eligible.slice(0, MAX_BLAME_FILES), capped: oversize || eligible.length > MAX_BLAME_FILES };
226
+ }
227
+
228
+ const BLAME_HEADER_RE = /^([0-9a-f]{40,64}) \d+ \d+/;
229
+
230
+ type BlameLine = { commit: string | null; author: string | null; summary: string | null };
231
+
232
+ function parseBlamePorcelain(text: string): BlameLine[] {
233
+ const entries: BlameLine[] = [];
234
+ let commit: string | null = null;
235
+ let author: string | null = null;
236
+ let summary: string | null = null;
237
+
238
+ for (const line of text.split("\n")) {
239
+ const header = BLAME_HEADER_RE.exec(line);
240
+
241
+ if (header) commit = header[1] ?? null;
242
+ else if (line.startsWith("author ")) author = line.slice("author ".length);
243
+ else if (line.startsWith("summary ")) summary = line.slice("summary ".length);
244
+ else if (line.startsWith("\t")) {
245
+ entries.push({ commit, author, summary });
246
+ commit = null;
247
+ author = null;
248
+ summary = null;
249
+ }
250
+ }
251
+
252
+ return entries;
253
+ }
254
+
255
+ /** `unmerged` commits never earn credit: their subjects, and so their `(#N)`, are PR-authored. */
256
+ function blameOverlap(considered: FileDiff[], blameSha: string, unmerged: Set<string>, authorPrs: Set<number>, repoRoot: string): BlameOverlap {
257
+ let owned = 0;
258
+ let total = 0;
259
+ let incomplete = 0;
260
+ const counts = new Map<string, number>();
261
+
262
+ for (const fileDiff of considered) {
263
+ const blamePath = fileDiff.old_path;
264
+
265
+ if (!blamePath) continue;
266
+ const ranges = coalesce(fileDiff.base_modified_lines);
267
+
268
+ if (!ranges.length) continue;
269
+ const rangeFlags = ranges.flatMap(([start, end]) => ["-L", `${start},${end}`]);
270
+ const out = git(repoRoot, ["blame", blameSha, ...rangeFlags, "--line-porcelain", "--", blamePath]);
271
+
272
+ if (out === null) {
273
+ total += ranges.reduce((n, [s, e]) => n + (e - s + 1), 0);
274
+ incomplete += 1;
275
+ continue;
276
+ }
277
+
278
+ for (const { commit, author, summary } of parseBlamePorcelain(out)) {
279
+ total += 1;
280
+
281
+ if (!commit || unmerged.has(commit)) continue;
282
+ const prNumber = extractPrNumber(summary || "");
283
+
284
+ if (prNumber !== null && authorPrs.has(prNumber)) owned += 1;
285
+ else if (author) counts.set(author, (counts.get(author) ?? 0) + 1);
286
+ }
287
+ }
288
+
289
+ const topPriorAuthors = [...counts.entries()]
290
+ .sort((a, b) => b[1] - a[1])
291
+ .slice(0, TOP_PRIOR_AUTHORS)
292
+ .map(([name]) => name);
293
+
294
+ return { owned, total, incomplete, topPriorAuthors };
295
+ }
296
+
297
+ /** Each path's parent directory; a top-level file stands for itself rather than the whole repo. */
298
+ const pathSpecs = (paths: string[]) => [...new Set(paths.map((p) => (p.includes("/") ? path.posix.dirname(p) : p)))].sort();
299
+
300
+ function priorPrsInPaths(paths: string[], authorPrs: Set<number>, repoRoot: string, trustedRef: string, now: number) {
301
+ const specs = pathSpecs(paths);
302
+
303
+ if (!specs.length) return { prior: 0, daysSince: null };
304
+ const out = git(repoRoot, ["log", trustedRef, `--since=${LOG_SINCE}`, "--format=%ct%x09%s", "--", ...specs]);
305
+
306
+ if (out === null) return { prior: 0, daysSince: null };
307
+ const cutoff = now / 1000 - TWELVE_MONTHS_DAYS * 86400;
308
+ const recent = new Set<number>();
309
+ let lastTouch: number | null = null;
310
+
311
+ for (const line of out.split("\n")) {
312
+ const tab = line.indexOf("\t");
313
+
314
+ if (tab < 0) continue;
315
+ const commitTime = Number(line.slice(0, tab));
316
+
317
+ if (!Number.isFinite(commitTime)) continue;
318
+ const prNumber = extractPrNumber(line.slice(tab + 1));
319
+
320
+ if (prNumber === null || !authorPrs.has(prNumber)) continue;
321
+
322
+ if (lastTouch === null || commitTime > lastTouch) lastTouch = commitTime;
323
+
324
+ if (commitTime >= cutoff) recent.add(prNumber);
325
+ }
326
+
327
+ const daysSince = lastTouch !== null ? Math.floor((now / 1000 - lastTouch) / 86400) : null;
328
+
329
+ return { prior: recent.size, daysSince };
330
+ }
331
+
332
+ /** How many considered files the author's merged PRs touched. */
333
+ function filesPreviouslyModified(considered: FileDiff[], authorPrs: Set<number>, repoRoot: string, trustedRef: string): number {
334
+ const allPaths = [...new Set(considered.flatMap((f) => [f.old_path, f.new_path].filter((p): p is string => !!p)))].sort();
335
+
336
+ if (!allPaths.length) return 0;
337
+ const out = git(repoRoot, ["log", trustedRef, `--since=${LOG_SINCE}`, "--format=%x01%s", "--name-only", "--no-renames", "--", ...allPaths]);
338
+
339
+ if (out === null) return 0;
340
+ const wanted = new Set(allPaths);
341
+ const touched = new Set<string>();
342
+ let currentIsAuthors = false;
343
+
344
+ for (const line of out.split("\n")) {
345
+ if (line.startsWith("\x01")) {
346
+ const prNumber = extractPrNumber(line.slice(1));
347
+ currentIsAuthors = prNumber !== null && authorPrs.has(prNumber);
348
+ } else if (line && currentIsAuthors && wanted.has(line)) {
349
+ touched.add(line);
350
+ }
351
+ }
352
+
353
+ return considered.filter((f) => (f.old_path && touched.has(f.old_path)) || (f.new_path && touched.has(f.new_path))).length;
354
+ }
355
+
356
+ /** STRONG / MODERATE / NONE from policy thresholds. */
357
+ export function band(
358
+ blameOverlapPct: number,
359
+ priorPrsInPathsCount: number,
360
+ daysSinceLastTouch: number | null,
361
+ thresholds: FamiliarityPolicy,
362
+ ): AuthorFamiliarity["band"] {
363
+ if (blameOverlapPct >= thresholds.strong.min_blame_overlap_pct) return "STRONG";
364
+
365
+ if (
366
+ priorPrsInPathsCount >= thresholds.moderate.min_prior_prs &&
367
+ daysSinceLastTouch !== null &&
368
+ daysSinceLastTouch <= thresholds.moderate.max_days_since_touch
369
+ ) {
370
+ return "MODERATE";
371
+ }
372
+
373
+ return "NONE";
374
+ }
375
+
376
+ const isShallow = (repoRoot: string) => git(repoRoot, ["rev-parse", "--is-shallow-repository"])?.trim() !== "false";
377
+
378
+ /**
379
+ * Blame and log need real history. CI checks out at depth 1, where the merge-base is missing and
380
+ * blame would pin every older line on the boundary commit. Deepen once, on demand, so runs that never
381
+ * reach familiarity pay nothing. False when the repo is still shallow; the signal is then skipped.
382
+ */
383
+ export function ensureFullHistory(repoRoot: string): boolean {
384
+ if (isShallow(repoRoot)) git(repoRoot, [...GH_CREDENTIALS, "fetch", "-q", "--unshallow", "origin"], UNSHALLOW_TIMEOUT_MS);
385
+
386
+ return !isShallow(repoRoot);
387
+ }
388
+
389
+ /**
390
+ * Compute author familiarity with the code the PR modifies.
391
+ * Returns null when the gh call failed or history is shallow (signal absent); other
392
+ * degradations yield a result.
393
+ */
394
+ export function computeFamiliarity(opts: {
395
+ authorLogin: string;
396
+ diff: string;
397
+ baseSha: string;
398
+ headSha: string;
399
+ repo: string;
400
+ repoRoot: string;
401
+ /** The default branch: only history merged there counts. */
402
+ trustedRef: string;
403
+ thresholds: FamiliarityPolicy;
404
+ now?: number;
405
+ }, deps = { fetchAuthorPrNumbers }): AuthorFamiliarity | null {
406
+ const authorPrs = deps.fetchAuthorPrNumbers(opts.authorLogin, opts.repo, opts.repoRoot);
407
+
408
+ if (authorPrs === null || isShallow(opts.repoRoot)) return null;
409
+ const now = opts.now ?? Date.now();
410
+ const { considered, capped } = selectConsidered(parseDiff(opts.diff));
411
+ const consideredPaths = considered.map(path_of).filter(Boolean);
412
+ const blameSha = git(opts.repoRoot, ["merge-base", opts.baseSha, opts.headSha])?.trim() || null;
413
+ // Blame runs where the diff's line numbers live, the merge-base. On a stacked PR that sits on an
414
+ // unmerged branch, so commits not yet on the default branch are listed and never credited.
415
+ const unmergedLog = blameSha ? git(opts.repoRoot, ["rev-list", blameSha, `^${opts.trustedRef}`]) : null;
416
+ const unmerged = unmergedLog === null ? null : new Set(unmergedLog.split("\n").filter(Boolean));
417
+ const emptyOverlap: BlameOverlap = { owned: 0, total: 0, incomplete: 0, topPriorAuthors: [] };
418
+ const overlap = blameSha && unmerged ? blameOverlap(considered, blameSha, unmerged, authorPrs, opts.repoRoot) : emptyOverlap;
419
+ const blameOverlapPct = overlap.total ? (100 * overlap.owned) / overlap.total : 0;
420
+ const { prior, daysSince } = priorPrsInPaths(consideredPaths, authorPrs, opts.repoRoot, opts.trustedRef, now);
421
+
422
+ return {
423
+ band: band(blameOverlapPct, prior, daysSince, opts.thresholds),
424
+ blame_overlap_pct: blameOverlapPct,
425
+ modified_lines_owned: overlap.owned,
426
+ modified_lines_total: overlap.total,
427
+ prior_prs_in_paths: prior,
428
+ days_since_last_touch: daysSince,
429
+ files_prev_count: filesPreviouslyModified(considered, authorPrs, opts.repoRoot, opts.trustedRef),
430
+ files_total: considered.length,
431
+ capped,
432
+ blame_incomplete_files: overlap.incomplete,
433
+ top_prior_authors: overlap.topPriorAuthors,
434
+ };
435
+ }
436
+
437
+ /**
438
+ * TRUSTED prompt block, or "" when absent / NONE without reviewer hints, which leaves the
439
+ * prompt unchanged (ratchet).
440
+ */
441
+ export function formatFamiliarity(fam: AuthorFamiliarity | null | undefined): string {
442
+ if (!fam) return "";
443
+
444
+ const reviewers = fam.top_prior_authors.length
445
+ ? `\nMost familiar with the modified lines (suggested reviewers if you escalate): ${fam.top_prior_authors.map((n) => scrubName(n, 80)).join(", ")}.`
446
+ : "";
447
+
448
+ if (fam.band === "NONE") return reviewers;
449
+
450
+ const parts = [
451
+ `band ${fam.band}`,
452
+ `author last-touched ${fam.blame_overlap_pct.toFixed(0)}% of the lines this diff modifies`,
453
+ `${fam.files_prev_count}/${fam.files_total} changed files previously modified`,
454
+ `${fam.prior_prs_in_paths} merged PRs in these paths in 12 months`,
455
+ fam.days_since_last_touch !== null ? `last touch ${fam.days_since_last_touch} days ago` : "no prior touch found in the last 18 months",
456
+ ];
457
+
458
+ const capped = fam.capped ? " (Metrics computed on a bounded subset of the changed files.)" : "";
459
+
460
+ return `\nAuthor familiarity with the changed code (computed from default-branch git history): ${parts.join("; ")}.${capped}${reviewers}`;
461
+ }