@jagreehal/shepherd 0.15.0 → 0.17.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.
- package/AGENTS.md +3 -3
- package/README.md +40 -27
- package/THIRD_PARTY_NOTICES.md +2 -0
- package/gate/.shepherd/gate.schema.json +657 -0
- package/gate/.shepherd/gate.yml +123 -0
- package/gate/.shepherd/review-guidance.md +95 -0
- package/gate/src/actions.ts +32 -0
- package/gate/src/cli.ts +1046 -0
- package/gate/src/config.ts +102 -0
- package/gate/src/delta.ts +29 -0
- package/gate/src/env.ts +30 -0
- package/gate/src/eval.ts +292 -0
- package/gate/src/familiarity.ts +461 -0
- package/gate/src/github.ts +761 -0
- package/gate/src/inline.ts +59 -0
- package/gate/src/isolated-cli.ts +281 -0
- package/gate/src/leads.ts +257 -0
- package/gate/src/llm.ts +647 -0
- package/gate/src/notify.ts +57 -0
- package/gate/src/policy.ts +1313 -0
- package/gate/src/prices.ts +62 -0
- package/gate/src/provider-errors.ts +80 -0
- package/gate/src/retention.ts +86 -0
- package/gate/src/reviewer.ts +739 -0
- package/gate/src/signals.ts +105 -0
- package/gate/src/smoke-live.ts +64 -0
- package/gate/src/stack.ts +87 -0
- package/gate/src/stories.ts +297 -0
- package/gate/templates/policy-strict.yml +128 -0
- package/gate/templates/reviewer.Dockerfile +8 -0
- package/gate/templates/rules/observability/SKILL.md +33 -0
- package/gate/templates/shepherd-gate-actions.yml +35 -0
- package/gate/templates/shepherd-gate-edited.yml +29 -0
- package/gate/templates/shepherd-gate.yml +111 -0
- package/lenses/dotnet/SKILL.md +1 -1
- package/lenses/go/SKILL.md +1 -1
- package/lenses/java/SKILL.md +1 -1
- package/lenses/nextjs/SKILL.md +1 -1
- package/lenses/node-api/SKILL.md +1 -1
- package/lenses/nx-monorepo/SKILL.md +1 -1
- package/lenses/observability/SKILL.md +1 -1
- package/lenses/owasp-asvs/SKILL.md +1 -1
- package/lenses/owasp-llm/SKILL.md +1 -1
- package/lenses/pstack/SKILL.md +1 -1
- package/lenses/python/SKILL.md +1 -1
- package/lenses/react/SKILL.md +1 -1
- package/lenses/rust/SKILL.md +1 -1
- package/package.json +21 -7
- package/schema/config.json +1 -1
- package/skills/branch-review/SKILL.md +123 -0
- package/skills/ci-repair/SKILL.md +79 -35
- package/skills/garden/SKILL.md +8 -8
- package/skills/garden/references/telemetry.md +4 -4
- package/skills/incident/SKILL.md +9 -9
- package/skills/lens-import/SKILL.md +7 -7
- package/skills/review-slop/SKILL.md +1 -1
- package/skills/shepherd/SKILL.md +43 -41
- package/skills/shepherd/references/degradation.md +3 -3
- package/skills/shepherd/references/dispatch.md +1 -1
- package/skills/shepherd/references/formats.md +5 -5
- package/skills/shepherd/references/models.md +2 -2
- package/skills/shepherd/references/policy.md +9 -9
- package/skills/swarm/SKILL.md +21 -17
- package/skills/swarm/references/custom-lenses.md +2 -2
- package/skills/swarm/references/formats.md +1 -1
- package/skills/triage/SKILL.md +10 -10
- package/src/bin.ts +10 -0
- package/src/cli.ts +285 -42
- package/src/config.ts +26 -25
- package/src/doctor.ts +31 -18
- package/src/garden-traces.ts +13 -13
- package/src/garden.ts +4 -4
- package/src/lens.ts +19 -7
- package/src/setup.ts +72 -0
- package/src/stack.ts +2 -2
- package/src/status.ts +80 -0
- package/src/summary.ts +52 -9
- package/src/trace.ts +4 -4
- package/src/working.ts +30 -0
- package/templates/shepherd-audit.yml +7 -15
- package/templates/shepherd-incident.yml +7 -12
- package/templates/shepherd.yml +39 -40
|
@@ -0,0 +1,1313 @@
|
|
|
1
|
+
// Policy loading + deterministic gates. No LLM here: everything in this file is
|
|
2
|
+
// reproducible from the file list, the diff stats, and .shepherd/gate.yml.
|
|
3
|
+
import { execFileSync } from "node:child_process";
|
|
4
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { LineCounter, isNode, parse as parseYaml, parseDocument, visit } from "yaml";
|
|
7
|
+
import { z } from "zod";
|
|
8
|
+
import { FamiliarityPolicySchema, stripDiffPath } from "./familiarity.ts";
|
|
9
|
+
import { TimedOut, TRUSTED_ASSOCIATIONS, callTimeout, type LinkedIssue } from "./github.ts";
|
|
10
|
+
import { StoriesPolicySchema } from "./stories.ts";
|
|
11
|
+
|
|
12
|
+
const Match = z.object({
|
|
13
|
+
any: z.array(z.string()).default([]),
|
|
14
|
+
titles: z.array(z.string()).default([]),
|
|
15
|
+
paths: z.array(z.string()).default([]),
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
const denyCategory = { description: z.string().optional(), match: Match };
|
|
19
|
+
|
|
20
|
+
const OverrideCeiling = z.object({ ceiling: z.number().int().positive() });
|
|
21
|
+
|
|
22
|
+
const OnBreak = z.enum(["refuse", "escalate", "note"]);
|
|
23
|
+
|
|
24
|
+
type OnBreak = z.infer<typeof OnBreak>;
|
|
25
|
+
|
|
26
|
+
const RulePackSchema = z
|
|
27
|
+
.object({
|
|
28
|
+
// A path in this repository, or a pack pinned to a commit in another: github:owner/repo/<path>@<40 hex>.
|
|
29
|
+
skill: z.string().refine((p) => {
|
|
30
|
+
const inner = PINNED_PACK.exec(p)?.[3] ?? (p.startsWith("github:") ? null : p);
|
|
31
|
+
|
|
32
|
+
return inner !== null && !path.isAbsolute(inner) && !inner.split(/[\\/]/).includes("..");
|
|
33
|
+
}, "a repository-relative path without .., or github:owner/repo/<path>@<full commit sha>"),
|
|
34
|
+
applies_to: z.array(z.string()).optional(),
|
|
35
|
+
on_break: OnBreak.default("escalate"), // for rules that carry no [refuse|escalate|note] tag of their own
|
|
36
|
+
only: z.array(z.string().min(1)).min(1).optional(), // rule id globs to keep
|
|
37
|
+
disable: z.array(z.string().min(1)).min(1).optional(), // rule id globs to drop
|
|
38
|
+
})
|
|
39
|
+
.strict();
|
|
40
|
+
|
|
41
|
+
type RulePack = z.infer<typeof RulePackSchema>;
|
|
42
|
+
|
|
43
|
+
// One glyph per verdict and gate result, as posted today. Kept short and free of whitespace: Shepherd and people
|
|
44
|
+
// grep a review's header, and a value is not a place for markup.
|
|
45
|
+
const DEFAULT_GLYPHS = { APPROVED: "✅", REFUSED: "❌", ESCALATE: "🙋", ERROR: "⚠️", pass: "✓", fail: "✗", fix: "🤖" };
|
|
46
|
+
|
|
47
|
+
const Glyph = z.string().min(1).max(16).regex(/^\S+$/, "a glyph has no whitespace");
|
|
48
|
+
|
|
49
|
+
const Branding = z
|
|
50
|
+
.object({
|
|
51
|
+
name: z.string().trim().min(1).max(40).optional(),
|
|
52
|
+
avatar: z.url({ protocol: /^https$/, hostname: z.regexes.domain }).max(500).optional(),
|
|
53
|
+
emoji: z.object({ APPROVED: Glyph, REFUSED: Glyph, ESCALATE: Glyph, ERROR: Glyph, pass: Glyph, fail: Glyph, fix: Glyph }).partial().strict().optional(),
|
|
54
|
+
})
|
|
55
|
+
.strict();
|
|
56
|
+
|
|
57
|
+
const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
|
|
58
|
+
|
|
59
|
+
// Policy text lands in Markdown and HTML: escape anything either reads as markup, Markdown first so the entities stay whole.
|
|
60
|
+
const escapeText = (s: string) => escapeHtml(s.replace(/[\\`*_[\]()#!|~]/g, "\\$&"));
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The glyphs and header a posted review uses, from the policy's `branding`, with today's defaults for anything
|
|
64
|
+
* unset. Every value is escaped, so a policy cannot inject markup. The gate finds its own reviews by the hidden
|
|
65
|
+
* run and reviewed markers only, never this header, so branding cannot affect retraction or retention.
|
|
66
|
+
*/
|
|
67
|
+
export function brand(b: z.infer<typeof Branding> | undefined) {
|
|
68
|
+
const g = { ...DEFAULT_GLYPHS, ...b?.emoji };
|
|
69
|
+
const glyphs = { APPROVED: escapeText(g.APPROVED), REFUSED: escapeText(g.REFUSED), ESCALATE: escapeText(g.ESCALATE), ERROR: escapeText(g.ERROR), pass: escapeText(g.pass), fail: escapeText(g.fail), fix: escapeText(g.fix) };
|
|
70
|
+
const name = b?.name ?? "shepherd gate";
|
|
71
|
+
const avatar = b?.avatar ? `<img src="${escapeHtml(b.avatar)}" width="20" height="20" alt="${escapeHtml(name)}"> ` : "";
|
|
72
|
+
|
|
73
|
+
return { ...glyphs, heading: (verdict: "APPROVED" | "REFUSED" | "ESCALATE" | "ERROR") => `## ${avatar}${glyphs[verdict]} ${escapeText(name)}: ${verdict}` };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Prices per million tokens by model, dated: `{"kimi-k3":{"inputPer1M":3,"outputPer1M":15,"as_of":"2026-11-15"}}`. */
|
|
77
|
+
export const Pricing = z.record(
|
|
78
|
+
z.string(),
|
|
79
|
+
z
|
|
80
|
+
.object({
|
|
81
|
+
inputPer1M: z.number(),
|
|
82
|
+
outputPer1M: z.number(),
|
|
83
|
+
cachedInputPer1M: z.number().optional(),
|
|
84
|
+
as_of: z.iso.date().optional().describe("The date you read these prices (YYYY-MM-DD), so a stale price is visible."),
|
|
85
|
+
source: z.string().optional().describe("Where the prices came from: a price page, a contract, a region."),
|
|
86
|
+
})
|
|
87
|
+
.strict(),
|
|
88
|
+
);
|
|
89
|
+
|
|
90
|
+
export const Effort = z.enum(["low", "medium", "high"]);
|
|
91
|
+
|
|
92
|
+
export const PolicySchema = z
|
|
93
|
+
.object({
|
|
94
|
+
version: z.literal(1),
|
|
95
|
+
// A property, so the published schema requires gate_policy too.
|
|
96
|
+
deny: z
|
|
97
|
+
.object({ gate_policy: z.object(denyCategory, { error: (i) => (i.input === undefined ? "required: the gate cannot approve edits to itself" : undefined) }) })
|
|
98
|
+
.catchall(z.object(denyCategory))
|
|
99
|
+
.describe("Categories a PR may not touch: a match sends it to a human. deny.gate_policy is required."),
|
|
100
|
+
allow: z.object({ path_patterns: z.array(z.string()), extensions_only: z.array(z.string()) }).describe("Paths and extensions that count as low-risk."),
|
|
101
|
+
size_gate: z.object({ max_lines: z.number().int().positive(), max_files: z.number().int().positive() }).describe("The largest change gate reviews; anything bigger goes to a human."),
|
|
102
|
+
tiers: z.record(z.string(), z.object({ max_lines: z.number().int(), max_files: z.number().int() })),
|
|
103
|
+
overrides: z
|
|
104
|
+
.object({
|
|
105
|
+
"size_gate.max_lines": OverrideCeiling,
|
|
106
|
+
"size_gate.max_files": OverrideCeiling,
|
|
107
|
+
})
|
|
108
|
+
.strict()
|
|
109
|
+
.optional()
|
|
110
|
+
.describe("Contract ceilings for AGENT_APPROVALS.md grants. Absent = no folder delegation."),
|
|
111
|
+
familiarity: FamiliarityPolicySchema.optional().describe("Judgment-layer only; never a gate. Absent = no familiarity signal computed."),
|
|
112
|
+
stories: StoriesPolicySchema.optional().describe("Judgment-layer, never a gate; a scenario the report measures checking less than the base branch holds an approval for a person. Absent = no test evidence read from CI."),
|
|
113
|
+
scrutiny: z.record(z.string(), z.object({ description: z.string().optional(), paths: z.array(z.string()), instruction: z.string() })).default({}).describe("Paths the reviewer looks at harder, with what to check. Never changes a gate."),
|
|
114
|
+
reviewer_bots: z.array(z.string()).default([]).describe("Review bots whose fresh 👀 reaction gate briefly waits on."),
|
|
115
|
+
long_lived_branches: z.array(z.string().min(1)).default(["main", "master", "develop", "release", "release/*", "staging"]).describe("Long-lived branches (globs): a PR whose commits mostly sit on one of these, other than its base, was opened against the wrong base."),
|
|
116
|
+
reviewer_checks: z.array(z.string()).default([]).describe("Review services that report progress as a check run on the head, such as Claude Code Review."),
|
|
117
|
+
rules: z.record(z.string().regex(/^[a-z][a-z0-9-]*$/), RulePackSchema).default({}).describe('Team rule packs: SKILL.md files whose "## Review" rules the reviewer applies to matching files.'),
|
|
118
|
+
rules_from: z.object({ shepherd: z.object({ on_break: OnBreak.default("escalate") }).strict() }).strict().optional().describe("Rule packs declared once, in another tool's config: shepherd's lenses become rule packs here."),
|
|
119
|
+
branding: Branding.optional().describe("How posted reviews look: the header name, a small avatar, and any glyph. Absent = today's output, byte for byte."),
|
|
120
|
+
// Settings, read from the default branch like the rest, so a change to one is reviewed. A non-blank environment
|
|
121
|
+
// variable overrides each one (config.ts, `gate config`). Secrets are never here.
|
|
122
|
+
model: z.string().min(1).optional().describe("The reviewer model, provider/model. Overridden by SHEPHERD_MODEL."),
|
|
123
|
+
backends: z.array(z.string().min(1)).min(1).optional().describe("Primary backend, then a second opinion."),
|
|
124
|
+
pricing: Pricing.optional().describe("Prices per million tokens for each model you use. Shepherd ships no prices: without one, the $ budget is inactive and costs show as unpriced."),
|
|
125
|
+
provider: z.object({ region: z.string().regex(/^[a-z]{2}(-[a-z]+)+-\d$/, "an AWS region such as eu-west-1").optional(), base_url: z.url({ protocol: /^https?$/ }).optional(), anthropic_base_url: z.url({ protocol: /^https?$/ }).optional() }).strict().optional(),
|
|
126
|
+
guard: z
|
|
127
|
+
.object({
|
|
128
|
+
budget_usd: z.number().positive(),
|
|
129
|
+
tokens: z.union([z.number().int().positive(), z.string().regex(/^\d+(\.\d+)?[km]?$/, "a count such as 3m or 500k")]),
|
|
130
|
+
loop: z.string().regex(/^\d+\/\d+$/, "repeats/window, such as 4/12"),
|
|
131
|
+
max_tools: z.number().int().positive(),
|
|
132
|
+
timeout: z.string().regex(/^\d+(\.\d+)?(ms|s|m|h)?$/, "a duration such as 15m"),
|
|
133
|
+
})
|
|
134
|
+
.partial()
|
|
135
|
+
.strict()
|
|
136
|
+
.optional()
|
|
137
|
+
.describe("Bounds on one review's cost, tokens, repeated calls, tool calls and time."),
|
|
138
|
+
max_output_tokens: z.number().int().positive().optional(),
|
|
139
|
+
effort: Effort.optional().describe("How hard the reviewer reasons, on every backend. Unset leaves each model's default."),
|
|
140
|
+
cli: z.object({ claude_model: z.string().min(1).optional(), codex_model: z.string().min(1).optional() }).strict().optional(),
|
|
141
|
+
label: z.string().min(1).optional().describe("When set, a PR needs this label before gate reviews it."),
|
|
142
|
+
notify: z.object({ on: z.array(z.enum(["APPROVED", "REFUSED", "ESCALATE", "ERROR"])).min(1).optional() }).strict().optional(),
|
|
143
|
+
telemetry: z.object({ endpoint: z.url({ protocol: /^https?$/ }).optional(), service: z.string().min(1).optional() }).strict().optional(),
|
|
144
|
+
advise_on_deny: z.boolean().optional().describe("When a gate denies, still ask the model, and append its findings to the refusal as advice. It cannot approve."),
|
|
145
|
+
})
|
|
146
|
+
.strict()
|
|
147
|
+
.refine((p) => !p.overrides || (p.overrides["size_gate.max_lines"].ceiling >= p.size_gate.max_lines && p.overrides["size_gate.max_files"].ceiling >= p.size_gate.max_files), {
|
|
148
|
+
message: "overrides ceilings must cover the global size_gate limits",
|
|
149
|
+
path: ["overrides"],
|
|
150
|
+
});
|
|
151
|
+
|
|
152
|
+
/** The JSON schema editors validate `.shepherd/gate.yml` against, published as `.shepherd/gate.schema.json`. */
|
|
153
|
+
export const policyJsonSchema = () => ({
|
|
154
|
+
...z.toJSONSchema(PolicySchema, { io: "input", target: "draft-7" }),
|
|
155
|
+
title: "gate policy",
|
|
156
|
+
description: "gate's merge-gate policy, .shepherd/gate.yml. Read from the default branch, never the PR head.",
|
|
157
|
+
});
|
|
158
|
+
|
|
159
|
+
// Files outside .shepherd/ that the policy was built from (shepherd's config and its local packs): editing one edits policy.
|
|
160
|
+
export type Policy = z.infer<typeof PolicySchema> & { policyFiles?: string[] };
|
|
161
|
+
|
|
162
|
+
/** The package's own .shepherd/: the hosted default a repo with no policy files reviews under. */
|
|
163
|
+
export const DEFAULTS_DIR = path.resolve(import.meta.dir, "..");
|
|
164
|
+
|
|
165
|
+
let localPolicyDir: string | null = null;
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* `--policy-dir`: read `.shepherd/` files from this directory first, to try a policy before it is merged. Only for a
|
|
169
|
+
* run that posts nothing: the CLI refuses it with `--post`, because a PR must never supply the policy that gates it.
|
|
170
|
+
*/
|
|
171
|
+
export function useLocalPolicy(dir: string | null): void {
|
|
172
|
+
localPolicyDir = dir;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Read a policy file from the trusted ref (the default branch), else the package's bundled
|
|
177
|
+
* default. The working tree is NEVER consulted: it is the PR head, and a PR must not be able to
|
|
178
|
+
* supply the policy that gates it. A repo with no .shepherd/ on its default branch reviews under
|
|
179
|
+
* the bundled defaults, however many .shepherd/ files the PR adds.
|
|
180
|
+
*/
|
|
181
|
+
export function readTrusted(repoRoot: string, rel: string, ref = "origin/HEAD"): string | null {
|
|
182
|
+
const local = localPolicyDir && rel.startsWith(".shepherd/") ? path.join(localPolicyDir, rel.slice(".shepherd/".length)) : null;
|
|
183
|
+
|
|
184
|
+
if (local && existsSync(local)) return readFileSync(local, "utf8");
|
|
185
|
+
const git = (args: string[]) => execFileSync("git", ["-C", repoRoot, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: callTimeout() });
|
|
186
|
+
let refExists = false;
|
|
187
|
+
|
|
188
|
+
try {
|
|
189
|
+
git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
|
|
190
|
+
refExists = true;
|
|
191
|
+
} catch (e) {
|
|
192
|
+
if (TimedOut.safeParse(e).success) throw e;
|
|
193
|
+
/* no such ref: local run with no remote */
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
if (refExists) {
|
|
197
|
+
try {
|
|
198
|
+
return git(["show", `${ref}:${rel}`]);
|
|
199
|
+
} catch (e) {
|
|
200
|
+
if (TimedOut.safeParse(e).success) throw e;
|
|
201
|
+
/* ref exists, file absent on it: bundled default below */
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
try {
|
|
206
|
+
return readFileSync(path.join(DEFAULTS_DIR, rel), "utf8");
|
|
207
|
+
} catch {
|
|
208
|
+
return null;
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
export function loadPolicy(repoRoot: string, ref?: string): Policy {
|
|
213
|
+
const raw = readTrusted(repoRoot, ".shepherd/gate.yml", ref);
|
|
214
|
+
|
|
215
|
+
if (raw === null) throw new Error("missing .shepherd/gate.yml");
|
|
216
|
+
|
|
217
|
+
return parsePolicy(raw);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** Parse policy text, failing with one `.shepherd/gate.yml:line:col key: problem` line per issue. */
|
|
221
|
+
export function parsePolicy(raw: string): Policy {
|
|
222
|
+
const lines = new LineCounter();
|
|
223
|
+
const doc = parseDocument(raw, { lineCounter: lines, prettyErrors: false });
|
|
224
|
+
|
|
225
|
+
const at = (offset: number) => {
|
|
226
|
+
const { line, col } = lines.linePos(offset);
|
|
227
|
+
|
|
228
|
+
return `.shepherd/gate.yml:${line}:${col}`;
|
|
229
|
+
};
|
|
230
|
+
|
|
231
|
+
const problems = doc.errors.map((e) => `${at(e.pos[0])} ${e.message}`);
|
|
232
|
+
|
|
233
|
+
// An alias to an anchor that does not exist parses cleanly, then throws from toJS with no position.
|
|
234
|
+
visit(doc, {
|
|
235
|
+
Alias(_, alias) {
|
|
236
|
+
if (!alias.resolve(doc) && alias.range) problems.push(`${at(alias.range[0])} unresolved alias *${alias.source}`);
|
|
237
|
+
},
|
|
238
|
+
});
|
|
239
|
+
|
|
240
|
+
if (problems.length) throw new Error(problems.join("\n"));
|
|
241
|
+
let value: unknown;
|
|
242
|
+
|
|
243
|
+
try {
|
|
244
|
+
value = doc.toJS();
|
|
245
|
+
} catch (e) {
|
|
246
|
+
throw new Error(`.shepherd/gate.yml: ${e instanceof Error ? e.message : e}`); // such as an excessive alias count
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
const parsed = PolicySchema.safeParse(value);
|
|
250
|
+
|
|
251
|
+
if (parsed.success) return parsed.data;
|
|
252
|
+
|
|
253
|
+
const where = (keys: PropertyKey[]): string => {
|
|
254
|
+
// A missing key has no node of its own: point at the nearest parent that exists.
|
|
255
|
+
for (let n = keys.length; n >= 0; n--) {
|
|
256
|
+
const node = doc.getIn(keys.slice(0, n), true);
|
|
257
|
+
|
|
258
|
+
if (isNode(node) && node.range) return at(node.range[0]);
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
return ".shepherd/gate.yml";
|
|
262
|
+
};
|
|
263
|
+
|
|
264
|
+
throw new Error(parsed.error.issues.map((i) => `${where(i.code === "unrecognized_keys" ? [...i.path, i.keys[0]!] : i.path)} ${i.path.join(".") || "(top level)"}: ${i.message}`).join("\n"));
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
export function loadGuidance(repoRoot: string, ref?: string): string {
|
|
268
|
+
const raw = readTrusted(repoRoot, ".shepherd/review-guidance.md", ref);
|
|
269
|
+
|
|
270
|
+
if (raw === null) throw new Error("missing .shepherd/review-guidance.md");
|
|
271
|
+
// Optional repo-specific appendix, so a repo can add norms without replacing the whole file.
|
|
272
|
+
const steering = readTrusted(repoRoot, ".shepherd/steering.md", ref);
|
|
273
|
+
|
|
274
|
+
return steering ? `${raw}\n\n# Repository-specific steering\n\n${steering}` : raw;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
// ── Classification ────────────────────────────────────────────────────────────
|
|
278
|
+
|
|
279
|
+
export type PRFile = { filename: string; previousFilename?: string; additions: number; deletions: number; status?: string };
|
|
280
|
+
|
|
281
|
+
// Path fragments (contain "/" or start with a dot) match literally. Words get boundaries that also
|
|
282
|
+
// break on _ and -, so "secret" hits "secret_key.ts" but not "nosecrets.ts", and "auth" not "author".
|
|
283
|
+
const wb = (p: string) =>
|
|
284
|
+
p.includes("/") || p.startsWith("\\.") ? new RegExp(p, "i") : new RegExp(`(?<![a-z0-9])(?:${p})(?![a-z0-9])`, "i");
|
|
285
|
+
|
|
286
|
+
// File names test runners collect, wherever they live; TEST_RE adds the test directories.
|
|
287
|
+
const TEST_NAME_RE = /\.(test|spec)\.[cm]?[jt]sx?$|_test\.(py|go|rs)$|(^|\/)test_[^/]+\.py$|(^|\/)conftest\.py$/i;
|
|
288
|
+
|
|
289
|
+
const TEST_RE = new RegExp(`(^|\\/)(tests?|__tests__|spec|e2e)\\/|${TEST_NAME_RE.source}`, "i");
|
|
290
|
+
|
|
291
|
+
const SIZE_EXEMPT_RE = /\.(md|mdx|txt|rst|snap|ambr|lock|png|jpe?g|gif|svg|webp|ico)$|(^|\/)__snapshots__\//i;
|
|
292
|
+
|
|
293
|
+
const MANIFEST_RE = /(^|\/)(package\.json|pyproject\.toml|Cargo\.toml|go\.mod|Gemfile|tsconfig[^/]*\.json)$/i;
|
|
294
|
+
|
|
295
|
+
export const LOCKFILE_RE = /(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lock|uv\.lock|poetry\.lock|Cargo\.lock|go\.sum|Gemfile\.lock)$/i;
|
|
296
|
+
|
|
297
|
+
export const isTest = (p: string) => TEST_RE.test(p);
|
|
298
|
+
|
|
299
|
+
export const isSizeExempt = (p: string) => isTest(p) || SIZE_EXEMPT_RE.test(p);
|
|
300
|
+
|
|
301
|
+
export function denyCategories(policy: Policy, files: string[]): string[] {
|
|
302
|
+
const hit: string[] = [];
|
|
303
|
+
|
|
304
|
+
for (const [cat, rule] of Object.entries(policy.deny)) {
|
|
305
|
+
const res = [...rule.match.paths, ...rule.match.any].map(wb);
|
|
306
|
+
|
|
307
|
+
if (files.some((f) => res.some((r) => r.test(f)))) hit.push(cat);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
return hit;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
export function titleFlags(policy: Policy, title: string, denied: string[]): string[] {
|
|
314
|
+
const hit: string[] = [];
|
|
315
|
+
|
|
316
|
+
for (const [cat, rule] of Object.entries(policy.deny)) {
|
|
317
|
+
if (denied.includes(cat)) continue;
|
|
318
|
+
const res = [...rule.match.any, ...rule.match.titles].map(wb);
|
|
319
|
+
|
|
320
|
+
if (res.some((r) => r.test(title))) hit.push(cat);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
return hit;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
export type ScrutinyFlag = { name: string; files: string[]; instruction: string };
|
|
327
|
+
|
|
328
|
+
/** Paths that never deny but must be named to the reviewer with what would make them a refusal. */
|
|
329
|
+
export function scrutinyFlags(policy: Policy, files: string[]): ScrutinyFlag[] {
|
|
330
|
+
const out: ScrutinyFlag[] = [];
|
|
331
|
+
|
|
332
|
+
for (const [name, rule] of Object.entries(policy.scrutiny)) {
|
|
333
|
+
const res = rule.paths.map(wb);
|
|
334
|
+
const hit = files.filter((f) => res.some((r) => r.test(f)));
|
|
335
|
+
|
|
336
|
+
if (hit.length) out.push({ name, files: hit, instruction: rule.instruction });
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
return out;
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/** `github:owner/repo/<path>@<40-hex commit>`: a rule pack in another repository, fixed to one commit. */
|
|
343
|
+
// Path characters are limited so nothing in it reaches the API URL as a query or fragment (`?ref=`, `#`).
|
|
344
|
+
export const PINNED_PACK = /^github:([\w-][\w.-]*)\/([\w-][\w.-]*)\/([\w./-]+)@([0-9a-f]{40})$/;
|
|
345
|
+
|
|
346
|
+
/** Reads a file from another repository at a commit; null when it cannot. */
|
|
347
|
+
export type FetchPinned = (owner: string, repo: string, file: string, sha: string) => string | null;
|
|
348
|
+
|
|
349
|
+
/** The repository path of the file gate reads for a pack: the `.md` named, or SKILL.md in the directory named. */
|
|
350
|
+
export function rulePackFile(skill: string): string {
|
|
351
|
+
const p = path.posix.normalize(skill.replaceAll("\\", "/"));
|
|
352
|
+
|
|
353
|
+
return p.endsWith(".md") ? p : path.posix.join(p, "SKILL.md");
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
/**
|
|
357
|
+
* True when `file` is part of a configured pack: the file gate reads, or anything in the directory a pack
|
|
358
|
+
* names, since its rules link reference files there that shape how they are read. All of it is trusted context,
|
|
359
|
+
* so editing it is editing policy. Matching through `rulePackFile` leaves no spelling of the path (`.`, `./x/`,
|
|
360
|
+
* `x//y`) that reads one file and guards another. A pack at the repository root guards only its SKILL.md.
|
|
361
|
+
*/
|
|
362
|
+
export function touchesRulePack(policy: Policy, file: string): boolean {
|
|
363
|
+
// A pinned pack lives in another repository at a fixed commit: no PR here can edit what gate reads.
|
|
364
|
+
const normal = path.posix.normalize(file);
|
|
365
|
+
|
|
366
|
+
const inPack = (skill: string) => {
|
|
367
|
+
const read = rulePackFile(skill);
|
|
368
|
+
const dir = path.posix.dirname(read);
|
|
369
|
+
|
|
370
|
+
return read === normal || (!skill.endsWith(".md") && dir !== "." && normal.startsWith(`${dir}/`));
|
|
371
|
+
};
|
|
372
|
+
|
|
373
|
+
return Boolean(policy.policyFiles?.includes(normal)) || Object.values(policy.rules).some((r) => !PINNED_PACK.test(r.skill) && inPack(r.skill));
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
const ON_BREAK = {
|
|
377
|
+
refuse: "REFUSE when the diff breaks one of these rules, and name the rule id.",
|
|
378
|
+
escalate: "ESCALATE when the diff breaks one of these rules, and name the rule id.",
|
|
379
|
+
note: "Note each broken rule in notes with its id; a broken rule alone never changes the verdict.",
|
|
380
|
+
} as const;
|
|
381
|
+
|
|
382
|
+
// `- **<id>**: <rule>`, or `- **<id>** [refuse|escalate|note]: <rule>` to set that rule's severity. shepherd reads the same shape.
|
|
383
|
+
const RULE_LINE = /^- \*\*([a-z0-9][a-z0-9-]*)\*\*(?: \[(refuse|escalate|note)\])?:/;
|
|
384
|
+
|
|
385
|
+
export type PackRule = { id: string; severity?: OnBreak; text: string };
|
|
386
|
+
|
|
387
|
+
/** The rules under a pack's "## Review" heading, each with its continuation lines; null when it has no such section. */
|
|
388
|
+
export function packRules(text: string): PackRule[] | null {
|
|
389
|
+
const review = /^## Review\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text.replace(/\r\n/g, "\n"))?.[1];
|
|
390
|
+
|
|
391
|
+
if (review === undefined) return null;
|
|
392
|
+
const rules: PackRule[] = [];
|
|
393
|
+
|
|
394
|
+
for (const line of review.split("\n")) {
|
|
395
|
+
const m = RULE_LINE.exec(line);
|
|
396
|
+
|
|
397
|
+
if (m) {
|
|
398
|
+
const rule: PackRule = { id: m[1]!, text: line };
|
|
399
|
+
const severity = OnBreak.optional().parse(m[2]);
|
|
400
|
+
|
|
401
|
+
if (severity) rule.severity = severity;
|
|
402
|
+
rules.push(rule);
|
|
403
|
+
} else if (rules.length && /^\s+\S/.test(line)) rules.at(-1)!.text += `\n${line}`; // a rule wrapped onto indented lines
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
return rules;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
/** Whether a pack's `only` and `disable` keep this rule. */
|
|
410
|
+
export const keepsRule = (pack: Pick<RulePack, "only" | "disable">, id: string) =>
|
|
411
|
+
(!pack.only || pack.only.some((g) => path.matchesGlob(id, g))) && !pack.disable?.some((g) => path.matchesGlob(id, g));
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* Team rule packs that apply to this change, as scrutiny flags carrying the rules. `read` returns a trusted
|
|
415
|
+
* (default-branch) file, so a PR cannot write the rules it is judged by; `fetchPinned` reads a pack pinned to a
|
|
416
|
+
* commit in another repository. A pack that does not resolve, or has no rules under "## Review", is reported in
|
|
417
|
+
* `missing` and skipped: the whole file is never read as rules.
|
|
418
|
+
*/
|
|
419
|
+
export type RuleFlags = { flags: ScrutinyFlag[]; missing: string[] };
|
|
420
|
+
|
|
421
|
+
export function ruleFlags(policy: Policy, files: string[], read: (rel: string) => string | null, fetchPinned: FetchPinned = () => null): RuleFlags {
|
|
422
|
+
const flags: ScrutinyFlag[] = [];
|
|
423
|
+
const missing: string[] = [];
|
|
424
|
+
|
|
425
|
+
for (const [name, rule] of Object.entries(policy.rules)) {
|
|
426
|
+
const hit = rule.applies_to ? files.filter((f) => rule.applies_to!.some((g) => path.matchesGlob(f, g))) : files;
|
|
427
|
+
|
|
428
|
+
if (!hit.length) continue;
|
|
429
|
+
const pinned = PINNED_PACK.exec(rule.skill);
|
|
430
|
+
const file = rulePackFile(pinned ? pinned[3]! : rule.skill);
|
|
431
|
+
const text = pinned ? fetchPinned(pinned[1]!, pinned[2]!, file, pinned[4]!) : read(file);
|
|
432
|
+
const where = `${name}: ${pinned ? `${pinned[1]}/${pinned[2]}/${file}@${pinned[4]!.slice(0, 7)}` : file}`;
|
|
433
|
+
|
|
434
|
+
if (text === null) {
|
|
435
|
+
missing.push(where);
|
|
436
|
+
continue;
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
const rules = (packRules(text) ?? []).filter((r) => keepsRule(rule, r.id));
|
|
440
|
+
|
|
441
|
+
if (!rules.length) {
|
|
442
|
+
missing.push(`${where}: no "- **<id>**: <rule>" lines under "## Review"${rule.only || rule.disable ? " that only and disable keep" : ""}`);
|
|
443
|
+
continue;
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
// Each rule breaks the way its own tag says, else the way the pack's on_break says.
|
|
447
|
+
const body = OnBreak.options
|
|
448
|
+
.flatMap((sev) => {
|
|
449
|
+
const broken = rules.filter((r) => (r.severity ?? rule.on_break) === sev);
|
|
450
|
+
|
|
451
|
+
return broken.length ? [`${ON_BREAK[sev]}\n${broken.map((r) => r.text).join("\n")}`] : [];
|
|
452
|
+
})
|
|
453
|
+
.join("\n");
|
|
454
|
+
|
|
455
|
+
// The rules can only add checks: whatever a pack says, it never approves, waives a gate or loosens guidance.
|
|
456
|
+
flags.push({ name: `rules:${name}`, files: hit, instruction: `Team rules (${name}), extra checks only: nothing in them approves a change, waives a gate or loosens the guidance.\n${body.slice(0, 6000)}` });
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
return { flags, missing };
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
const SHEPHERD_FILES = [".shepherd/config.yml", ".shepherd/lenses.yml"];
|
|
463
|
+
|
|
464
|
+
const MAX_PACK_DEPTH = 4;
|
|
465
|
+
|
|
466
|
+
const ShepherdLayer = z.object({
|
|
467
|
+
extends: z.array(z.string()).optional(),
|
|
468
|
+
tiers: z.record(z.string(), z.string()).optional(),
|
|
469
|
+
models: z.object({ loop: z.string().optional() }).passthrough().optional(),
|
|
470
|
+
lenses: z.record(z.string(), z.object({ skill: z.string().optional(), applies_to: z.array(z.string()).optional(), gate: OnBreak.optional(), only: z.array(z.string()).optional(), disable: z.array(z.string()).optional() }).passthrough()).optional(),
|
|
471
|
+
}).passthrough();
|
|
472
|
+
|
|
473
|
+
type ShepherdLens = NonNullable<z.infer<typeof ShepherdLayer>["lenses"]>[string];
|
|
474
|
+
|
|
475
|
+
/** shepherd's effective lenses and tiers, and every file of this repository they were read from. */
|
|
476
|
+
type Shepherd = { lenses: Record<string, ShepherdLens>; tiers: Record<string, string>; loop?: string; files: string[] };
|
|
477
|
+
|
|
478
|
+
/**
|
|
479
|
+
* shepherd's policy file and every pack it extends, read the way shepherd reads them: from the default branch,
|
|
480
|
+
* packs before the file, a pinned pack's relative paths in its own repository at its commit, a lens merged field
|
|
481
|
+
* by field, a tier replaced by name. Throws on a cycle, a missing pack or a malformed file; `files` is set on the
|
|
482
|
+
* error too, so a caller can still guard what it read.
|
|
483
|
+
*/
|
|
484
|
+
function readShepherd(read: (rel: string) => string | null, fetchPinned: FetchPinned, files: string[]): Shepherd | null {
|
|
485
|
+
const out: Shepherd = { lenses: {}, tiers: {}, files };
|
|
486
|
+
|
|
487
|
+
const layer = (text: string, source: string) => {
|
|
488
|
+
const parsed = ShepherdLayer.safeParse(parseYaml(text) ?? {});
|
|
489
|
+
|
|
490
|
+
if (!parsed.success) throw new Error(`${source}: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
|
|
491
|
+
|
|
492
|
+
return parsed.data;
|
|
493
|
+
};
|
|
494
|
+
|
|
495
|
+
const apply = (config: z.infer<typeof ShepherdLayer>, skillPath: (skill: string) => string) => {
|
|
496
|
+
Object.assign(out.tiers, config.tiers);
|
|
497
|
+
|
|
498
|
+
if (config.models?.loop) out.loop = config.models.loop;
|
|
499
|
+
|
|
500
|
+
for (const [name, l] of Object.entries(config.lenses ?? {})) {
|
|
501
|
+
const merged = { ...out.lenses[name], ...l };
|
|
502
|
+
|
|
503
|
+
if (l.skill) merged.skill = skillPath(l.skill);
|
|
504
|
+
out.lenses[name] = merged;
|
|
505
|
+
}
|
|
506
|
+
};
|
|
507
|
+
|
|
508
|
+
const pack = (ref: string, chain: string[]): void => {
|
|
509
|
+
if (chain.includes(ref) || chain.length >= MAX_PACK_DEPTH) throw new Error(`${[...chain, ref].join(" > ")}: packs extend in a cycle or more than ${MAX_PACK_DEPTH} deep`);
|
|
510
|
+
const pinned = PINNED_PACK.exec(ref);
|
|
511
|
+
|
|
512
|
+
if (!pinned && (ref.startsWith("github:") || path.isAbsolute(ref) || ref.split(/[\\/]/).includes(".."))) throw new Error(`${ref}: a pack is repository-relative, or pinned as github:owner/repo/<path>@<full commit sha>`);
|
|
513
|
+
const text = pinned ? fetchPinned(pinned[1]!, pinned[2]!, pinned[3]!, pinned[4]!) : read(ref);
|
|
514
|
+
|
|
515
|
+
if (text === null) throw new Error(`${ref}: pack not found`);
|
|
516
|
+
|
|
517
|
+
if (!pinned) files.push(path.posix.normalize(ref));
|
|
518
|
+
const config = layer(text, ref);
|
|
519
|
+
const inPack = (rel: string) => (pinned && !rel.startsWith("github:") ? `github:${pinned[1]}/${pinned[2]}/${rel.replace(/\/+$/, "")}@${pinned[4]}` : rel);
|
|
520
|
+
|
|
521
|
+
for (const e of config.extends ?? []) pack(inPack(e), [...chain, ref]);
|
|
522
|
+
apply(config, (skill) => (skill.includes("/") ? inPack(skill) : skill));
|
|
523
|
+
};
|
|
524
|
+
|
|
525
|
+
const file = SHEPHERD_FILES.find((f) => read(f) !== null);
|
|
526
|
+
|
|
527
|
+
if (!file) return null;
|
|
528
|
+
const team = layer(read(file)!, file);
|
|
529
|
+
|
|
530
|
+
for (const e of team.extends ?? []) pack(e, []);
|
|
531
|
+
apply(team, (skill) => skill);
|
|
532
|
+
|
|
533
|
+
return out;
|
|
534
|
+
}
|
|
535
|
+
|
|
536
|
+
/**
|
|
537
|
+
* With `rules_from.shepherd`, shepherd's lenses become rule packs, so a team declares them once. A lens's `gate`
|
|
538
|
+
* sets its `on_break`; a lens gate cannot read (an installed skill named, not a path) is reported in `missing`.
|
|
539
|
+
* A `rules:` entry of the same name wins. The policy file and local packs are guarded.
|
|
540
|
+
*/
|
|
541
|
+
export type Inherited = { policy: Policy; missing: string[] };
|
|
542
|
+
|
|
543
|
+
export function inheritRules(policy: Policy, read: (rel: string) => string | null, fetchPinned: FetchPinned = () => null): Inherited {
|
|
544
|
+
if (!policy.rules_from?.shepherd) return { policy, missing: [] };
|
|
545
|
+
const missing: string[] = [];
|
|
546
|
+
const policyFiles = [...SHEPHERD_FILES]; // both: a PR adding config.yml would replace an older lenses.yml
|
|
547
|
+
let shepherd: Shepherd | null;
|
|
548
|
+
|
|
549
|
+
try {
|
|
550
|
+
shepherd = readShepherd(read, fetchPinned, policyFiles);
|
|
551
|
+
} catch (e) {
|
|
552
|
+
return { policy: { ...policy, policyFiles }, missing: [`rules_from.shepherd: ${e instanceof Error ? e.message : e}`] };
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
if (!shepherd) return { policy: { ...policy, policyFiles }, missing: ["rules_from.shepherd: no .shepherd/config.yml on the default branch"] };
|
|
556
|
+
const inherited: Record<string, RulePack> = {};
|
|
557
|
+
|
|
558
|
+
for (const [name, l] of Object.entries(shepherd.lenses)) {
|
|
559
|
+
if (name in policy.rules) continue;
|
|
560
|
+
|
|
561
|
+
if (!l.skill || !(l.skill.includes("/") || l.skill === ".")) {
|
|
562
|
+
missing.push(`${name}: shepherd lens ${l.skill ? `names the installed skill ${l.skill}; gate reads a lens by path` : "has no skill"}`);
|
|
563
|
+
continue;
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
const rule = RulePackSchema.safeParse({ skill: l.skill, applies_to: l.applies_to, on_break: l.gate ?? policy.rules_from.shepherd.on_break, only: l.only, disable: l.disable });
|
|
567
|
+
|
|
568
|
+
if (rule.success) inherited[name] = rule.data;
|
|
569
|
+
else missing.push(`${name}: shepherd lens ${l.skill}: ${rule.error.issues[0]?.message}`);
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
return { policy: { ...policy, rules: { ...inherited, ...policy.rules }, policyFiles }, missing };
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* Model names resolved through shepherd's tiers, so one list of named models drives both tools. A name with no
|
|
577
|
+
* tier stays as written (a bare Claude id is Anthropic). Once any name could be a tier, shepherd's policy file
|
|
578
|
+
* and its local packs can choose gate's model, so editing them is editing policy: their paths join `policyFiles`
|
|
579
|
+
* whether or not a tier matches today, since a PR could add one.
|
|
580
|
+
*/
|
|
581
|
+
export type TierResolution = { policy: Policy; models: string[]; tiers: Record<string, string>; missing: string[] };
|
|
582
|
+
|
|
583
|
+
export function resolveTiers(policy: Policy, models: string[], read: (rel: string) => string | null, fetchPinned: FetchPinned = () => null): TierResolution {
|
|
584
|
+
const names = models.filter((m) => /^[a-z][a-z0-9-]*$/.test(m));
|
|
585
|
+
|
|
586
|
+
if (!names.length) return { policy, models, tiers: {}, missing: [] };
|
|
587
|
+
const files = [...SHEPHERD_FILES];
|
|
588
|
+
const guarded = (): Policy => ({ ...policy, policyFiles: [...new Set([...(policy.policyFiles ?? []), ...files])] });
|
|
589
|
+
let tiers: Record<string, string>;
|
|
590
|
+
|
|
591
|
+
try {
|
|
592
|
+
tiers = readShepherd(read, fetchPinned, files)?.tiers ?? {};
|
|
593
|
+
} catch (e) {
|
|
594
|
+
return { policy: guarded(), models, tiers: {}, missing: [`model tiers: ${e instanceof Error ? e.message : e}`] };
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
const used = Object.fromEntries(names.flatMap((n) => (tiers[n] ? [[n, tiers[n]!]] : [])));
|
|
598
|
+
|
|
599
|
+
return { policy: guarded(), models: models.map((m) => used[m] ?? m), tiers: used, missing: [] };
|
|
600
|
+
}
|
|
601
|
+
|
|
602
|
+
/**
|
|
603
|
+
* The loop's model (`models.loop` in shepherd's config), for a gate whose policy names none: one setting moves both.
|
|
604
|
+
* Reading it makes shepherd's config gate policy, so its files join `policyFiles`, as tiers do.
|
|
605
|
+
*/
|
|
606
|
+
export function shepherdModel(policy: Policy, read: (rel: string) => string | null, fetchPinned: FetchPinned = () => null): Policy {
|
|
607
|
+
const files = [...SHEPHERD_FILES];
|
|
608
|
+
let loop: string | undefined;
|
|
609
|
+
|
|
610
|
+
try {
|
|
611
|
+
loop = readShepherd(read, fetchPinned, files)?.loop;
|
|
612
|
+
} catch {
|
|
613
|
+
return policy; // a broken shepherd config: the gate keeps its own default, and the tiers step names the problem
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
return loop ? { ...policy, model: loop, policyFiles: [...new Set([...(policy.policyFiles ?? []), ...files])] } : policy;
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
export function manifestsWithoutLockfile(files: string[]): string[] {
|
|
620
|
+
if (files.some((f) => LOCKFILE_RE.test(f))) return [];
|
|
621
|
+
|
|
622
|
+
return files.filter((f) => MANIFEST_RE.test(f));
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
// Deterministic first line for manifests: scripts and lifecycle hooks execute in CI and on dev
|
|
626
|
+
// machines even when no lockfile changes. package.json is compared structurally between base and
|
|
627
|
+
// head (editing an existing script's command never mentions "scripts" on the changed line, so a
|
|
628
|
+
// line scan would miss it); other manifests fall back to a line scan. Parse failure fails closed.
|
|
629
|
+
const PKG_RISKY_KEYS = ["scripts", "husky", "lint-staged", "pnpm", "simple-git-hooks"];
|
|
630
|
+
|
|
631
|
+
const RISKY_LINE_RE = /^[+-]\s*(\[?(tool\.)?scripts|entry[-_]points|build\s*=|replace\s|"?(pre|post)?(install|prepare|publish|pack)"?\s*[:=])/;
|
|
632
|
+
|
|
633
|
+
/**
|
|
634
|
+
* Reviewer bots that are still working: a 👀 from a bot on the policy's list, young enough to be a
|
|
635
|
+
* live review rather than a crashed one. Logins come from the REST API, so they carry the `[bot]`
|
|
636
|
+
* suffix the policy list is written with.
|
|
637
|
+
*/
|
|
638
|
+
export function inFlightBots(reactions: { user: string; content: string; created: string }[], bots: string[], staleMs: number, now = Date.now()): string[] {
|
|
639
|
+
return reactions.flatMap((r) => (r.content === "eyes" && bots.includes(r.user) && now - Date.parse(r.created) < staleMs ? [r.user] : []));
|
|
640
|
+
}
|
|
641
|
+
|
|
642
|
+
/** Review services still working on this head: a listed check run that has not completed. */
|
|
643
|
+
export const inFlightChecks = (runs: { name: string; status: string }[], names: string[]): string[] => runs.flatMap((r) => (names.includes(r.name) && r.status !== "completed" ? [r.name] : []));
|
|
644
|
+
|
|
645
|
+
export function manifestScriptEdits(repoRoot: string, baseSha: string, headSha: string, manifests: string[]): string[] {
|
|
646
|
+
const show = (ref: string, file: string) => {
|
|
647
|
+
try {
|
|
648
|
+
return execFileSync("git", ["-C", repoRoot, "show", `${ref}:${file}`], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: callTimeout() });
|
|
649
|
+
} catch (e) {
|
|
650
|
+
if (TimedOut.safeParse(e).success) throw e;
|
|
651
|
+
|
|
652
|
+
return ""; // absent on that side (added/deleted file)
|
|
653
|
+
}
|
|
654
|
+
};
|
|
655
|
+
|
|
656
|
+
const risky: string[] = [];
|
|
657
|
+
|
|
658
|
+
for (const file of manifests) {
|
|
659
|
+
const base = show(baseSha, file);
|
|
660
|
+
const head = show(headSha, file);
|
|
661
|
+
|
|
662
|
+
if (path.basename(file) === "package.json") {
|
|
663
|
+
const pick = (t: string) => {
|
|
664
|
+
const o = t.trim() ? JSON.parse(t) : {};
|
|
665
|
+
|
|
666
|
+
return JSON.stringify(Object.fromEntries(PKG_RISKY_KEYS.map((k) => [k, o[k]])));
|
|
667
|
+
};
|
|
668
|
+
|
|
669
|
+
try {
|
|
670
|
+
if (pick(base) !== pick(head)) risky.push(file);
|
|
671
|
+
} catch {
|
|
672
|
+
risky.push(file); // unparseable: fail closed
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
continue;
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
let diff = "";
|
|
679
|
+
|
|
680
|
+
try {
|
|
681
|
+
diff = execFileSync("git", ["-C", repoRoot, "diff", baseSha, headSha, "--", file], { encoding: "utf8", timeout: callTimeout() });
|
|
682
|
+
} catch (e) {
|
|
683
|
+
if (TimedOut.safeParse(e).success) throw e;
|
|
684
|
+
risky.push(file);
|
|
685
|
+
continue;
|
|
686
|
+
}
|
|
687
|
+
|
|
688
|
+
if (diff.split("\n").some((l) => RISKY_LINE_RE.test(l))) risky.push(file);
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
return risky;
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
export function isAllowListedOnly(policy: Policy, files: string[]): boolean {
|
|
695
|
+
if (files.length === 0) return false;
|
|
696
|
+
const exts = new Set(policy.allow.extensions_only.map((e) => e.toLowerCase()));
|
|
697
|
+
|
|
698
|
+
return files.every(
|
|
699
|
+
(f) =>
|
|
700
|
+
isTest(f) ||
|
|
701
|
+
policy.allow.path_patterns.some((p) => f.includes(p)) ||
|
|
702
|
+
exts.has(path.extname(f).toLowerCase()),
|
|
703
|
+
);
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
export type Size = { lines: number; files: number };
|
|
707
|
+
|
|
708
|
+
export function substantiveSize(files: PRFile[]): Size {
|
|
709
|
+
const s = files.filter((f) => !isSizeExempt(f.filename));
|
|
710
|
+
|
|
711
|
+
return { lines: s.reduce((n, f) => n + f.additions + f.deletions, 0), files: s.length };
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
// ── Per-folder size overrides (AGENT_APPROVALS.md, trusted ref only) ─────────
|
|
715
|
+
//
|
|
716
|
+
// Size grants are gate inputs, so they are read from the default branch via
|
|
717
|
+
// readTrusted — never from the PR head. Frontmatter under `gate:` may raise
|
|
718
|
+
// max_files / max_lines within the policy's overrides ceilings. Invalid
|
|
719
|
+
// frontmatter = no grant from that file.
|
|
720
|
+
|
|
721
|
+
const FOLDER_POLICY_FILENAME = "AGENT_APPROVALS.md";
|
|
722
|
+
|
|
723
|
+
export type ScopeBudget = { path: string | null; ceiling: number; files: string[] };
|
|
724
|
+
|
|
725
|
+
export type EffectiveSize = { file_scopes: ScopeBudget[]; line_scopes: ScopeBudget[]; invalid_folder_files: string[] };
|
|
726
|
+
|
|
727
|
+
type SizeKey = "max_files" | "max_lines";
|
|
728
|
+
|
|
729
|
+
type FolderGrant = { [K in SizeKey]?: number } & { invalid?: true };
|
|
730
|
+
|
|
731
|
+
const INVALID: FolderGrant = { invalid: true };
|
|
732
|
+
|
|
733
|
+
const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/;
|
|
734
|
+
|
|
735
|
+
const FolderFrontmatter = z
|
|
736
|
+
.object({
|
|
737
|
+
gate: z
|
|
738
|
+
.object({ size_gate: z.object({ max_files: z.number().int().positive().optional(), max_lines: z.number().int().positive().optional() }).strict() })
|
|
739
|
+
.strict()
|
|
740
|
+
.optional(),
|
|
741
|
+
})
|
|
742
|
+
.passthrough();
|
|
743
|
+
|
|
744
|
+
function parseFolderGrant(text: string, contract: NonNullable<Policy["overrides"]>): FolderGrant {
|
|
745
|
+
const yaml = FRONTMATTER_RE.exec(text)?.[1];
|
|
746
|
+
|
|
747
|
+
if (yaml === undefined) return INVALID;
|
|
748
|
+
let front: unknown;
|
|
749
|
+
|
|
750
|
+
try {
|
|
751
|
+
front = parseYaml(yaml);
|
|
752
|
+
} catch {
|
|
753
|
+
return INVALID;
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
const parsed = FolderFrontmatter.safeParse(front);
|
|
757
|
+
|
|
758
|
+
if (!parsed.success) return INVALID;
|
|
759
|
+
const grant = parsed.data.gate?.size_gate;
|
|
760
|
+
|
|
761
|
+
if (!grant) return {}; // prose-only / advisory
|
|
762
|
+
|
|
763
|
+
if (grant.max_files === undefined && grant.max_lines === undefined) return INVALID;
|
|
764
|
+
|
|
765
|
+
if ((grant.max_files ?? 0) > contract["size_gate.max_files"].ceiling || (grant.max_lines ?? 0) > contract["size_gate.max_lines"].ceiling) return INVALID;
|
|
766
|
+
|
|
767
|
+
return grant;
|
|
768
|
+
}
|
|
769
|
+
|
|
770
|
+
/** Directories at or above the file, nearest first; "" is the repo root. */
|
|
771
|
+
function scopeChain(filePath: string): string[] {
|
|
772
|
+
const dirs: string[] = [];
|
|
773
|
+
|
|
774
|
+
for (let dir = path.posix.dirname(filePath); dir !== "." && dir !== "/"; dir = path.posix.dirname(dir)) dirs.push(dir);
|
|
775
|
+
|
|
776
|
+
return [...dirs, ""];
|
|
777
|
+
}
|
|
778
|
+
|
|
779
|
+
/** Buckets each file under its nearest grant for `key`; files with none share the global pool, listed last. */
|
|
780
|
+
function nearestScopes(changedFiles: string[], key: SizeKey, globalCeiling: number, grantAt: (rel: string) => FolderGrant): ScopeBudget[] {
|
|
781
|
+
const folders = new Map<string, ScopeBudget>();
|
|
782
|
+
const pool: ScopeBudget = { path: null, ceiling: globalCeiling, files: [] };
|
|
783
|
+
|
|
784
|
+
for (const file of changedFiles) {
|
|
785
|
+
let scope = pool;
|
|
786
|
+
|
|
787
|
+
for (const dir of scopeChain(file)) {
|
|
788
|
+
const rel = dir ? `${dir}/${FOLDER_POLICY_FILENAME}` : FOLDER_POLICY_FILENAME;
|
|
789
|
+
const ceiling = grantAt(rel)[key];
|
|
790
|
+
|
|
791
|
+
if (ceiling === undefined) continue;
|
|
792
|
+
scope = folders.get(rel) ?? { path: rel, ceiling, files: [] };
|
|
793
|
+
folders.set(rel, scope);
|
|
794
|
+
break;
|
|
795
|
+
}
|
|
796
|
+
|
|
797
|
+
scope.files.push(file);
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
return [...folders.values(), pool];
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
/**
|
|
804
|
+
* Resolve per-scope size budgets from AGENT_APPROVALS.md files on the trusted ref.
|
|
805
|
+
* When policy.overrides is absent, nothing is read and every file shares the global pool.
|
|
806
|
+
*/
|
|
807
|
+
export function resolveSizeOverrides(policy: Policy, changedFiles: string[], readFile: (rel: string) => string | null): EffectiveSize {
|
|
808
|
+
const contract = policy.overrides;
|
|
809
|
+
const cache = new Map<string, FolderGrant>();
|
|
810
|
+
|
|
811
|
+
const grantAt = (rel: string): FolderGrant => {
|
|
812
|
+
if (!contract) return {};
|
|
813
|
+
let grant = cache.get(rel);
|
|
814
|
+
|
|
815
|
+
if (!grant) {
|
|
816
|
+
const text = readFile(rel);
|
|
817
|
+
grant = text === null ? {} : parseFolderGrant(text, contract);
|
|
818
|
+
cache.set(rel, grant);
|
|
819
|
+
}
|
|
820
|
+
|
|
821
|
+
return grant;
|
|
822
|
+
};
|
|
823
|
+
|
|
824
|
+
return {
|
|
825
|
+
file_scopes: nearestScopes(changedFiles, "max_files", policy.size_gate.max_files, grantAt),
|
|
826
|
+
line_scopes: nearestScopes(changedFiles, "max_lines", policy.size_gate.max_lines, grantAt),
|
|
827
|
+
invalid_folder_files: [...cache].flatMap(([rel, grant]) => (grant.invalid ? [rel] : [])).sort(),
|
|
828
|
+
};
|
|
829
|
+
}
|
|
830
|
+
|
|
831
|
+
const roofOf = (scopes: ScopeBudget[]) => Math.max(...scopes.map((s) => s.ceiling));
|
|
832
|
+
|
|
833
|
+
/** Whether the PR fits every per-scope budget and the whole-PR roof (the most generous ceiling in play). */
|
|
834
|
+
export function sizeWithinBudgets(files: PRFile[], budgets: EffectiveSize) {
|
|
835
|
+
const byName = new Map(files.map((f) => [f.filename, f]));
|
|
836
|
+
const total = substantiveSize(files);
|
|
837
|
+
|
|
838
|
+
for (const [unit, scopes] of [["lines", budgets.line_scopes], ["files", budgets.file_scopes]] as const) {
|
|
839
|
+
for (const scope of scopes) {
|
|
840
|
+
const n = substantiveSize(scope.files.flatMap((name) => byName.get(name) ?? []))[unit];
|
|
841
|
+
|
|
842
|
+
if (n > scope.ceiling) {
|
|
843
|
+
return { ok: false, message: `${n} substantive ${unit} in ${scope.path ?? "global"} (ceiling ${scope.ceiling}; ${total.lines}L/${total.files}F total)` };
|
|
844
|
+
}
|
|
845
|
+
}
|
|
846
|
+
|
|
847
|
+
const roof = roofOf(scopes);
|
|
848
|
+
|
|
849
|
+
if (total[unit] > roof) return { ok: false, message: `${total[unit]} substantive ${unit} across the PR (roof ${roof})` };
|
|
850
|
+
}
|
|
851
|
+
|
|
852
|
+
return { ok: true, message: `${total.lines} substantive lines / ${total.files} files (limit ${roofOf(budgets.line_scopes)}/${roofOf(budgets.file_scopes)})` };
|
|
853
|
+
}
|
|
854
|
+
|
|
855
|
+
export type Tier = { tier: string; sub?: string };
|
|
856
|
+
|
|
857
|
+
export function tier(policy: Policy, files: PRFile[], denied: string[]): Tier {
|
|
858
|
+
if (denied.length) return { tier: "T2-never" };
|
|
859
|
+
const names = files.map((f) => f.filename);
|
|
860
|
+
|
|
861
|
+
if (isAllowListedOnly(policy, names) && manifestsWithoutLockfile(names).length === 0) return { tier: "T0-deterministic" };
|
|
862
|
+
const { lines, files: n } = substantiveSize(files);
|
|
863
|
+
|
|
864
|
+
for (const [name, t] of Object.entries(policy.tiers)) {
|
|
865
|
+
if (lines <= t.max_lines && n <= t.max_files) return { tier: "T1-agent", sub: name };
|
|
866
|
+
}
|
|
867
|
+
|
|
868
|
+
return { tier: "T1-agent", sub: "T1d-complex" };
|
|
869
|
+
}
|
|
870
|
+
|
|
871
|
+
// ── Ownership (CODEOWNERS, advisory) ─────────────────────────────────────────
|
|
872
|
+
//
|
|
873
|
+
// Who owns the changed files, so an ESCALATE names a person and an author who owns what they
|
|
874
|
+
// touched can count as assurance. Read from the trusted ref: ownership is a gate input. Last
|
|
875
|
+
// matching pattern wins, as GitHub resolves it.
|
|
876
|
+
|
|
877
|
+
export type Ownership = { owners: Map<string, string[]>; unowned: string[]; authorOwns: boolean | null };
|
|
878
|
+
|
|
879
|
+
const codeownersGlob = (p: string): RegExp => {
|
|
880
|
+
const anchored = p.startsWith("/");
|
|
881
|
+
let g = p.replace(/^\//, "");
|
|
882
|
+
const dirOnly = g.endsWith("/");
|
|
883
|
+
g = g.replace(/\/$/, "");
|
|
884
|
+
|
|
885
|
+
// Tokenize rather than chain replaces: a later replace would otherwise rewrite the `?` and `.`
|
|
886
|
+
// inside regex syntax an earlier one emitted.
|
|
887
|
+
let re = "";
|
|
888
|
+
|
|
889
|
+
for (let i = 0; i < g.length; i++) {
|
|
890
|
+
if (g.startsWith("**/", i)) {
|
|
891
|
+
re += "(?:.*/)?";
|
|
892
|
+
i += 2;
|
|
893
|
+
} else if (g.startsWith("**", i)) {
|
|
894
|
+
re += ".*";
|
|
895
|
+
i += 1;
|
|
896
|
+
} else if (g[i] === "*") re += "[^/]*";
|
|
897
|
+
else if (g[i] === "?") re += "[^/]";
|
|
898
|
+
else re += g[i]!.replace(/[.+^${}()|[\]\\]/, "\\$&");
|
|
899
|
+
}
|
|
900
|
+
|
|
901
|
+
const prefix = anchored || g.includes("/") ? "^" : "(?:^|/)";
|
|
902
|
+
|
|
903
|
+
return new RegExp(`${prefix}${re}${dirOnly || !g.includes(".") ? "(?:/|$)" : "$"}`);
|
|
904
|
+
};
|
|
905
|
+
|
|
906
|
+
export function parseCodeowners(text: string): { re: RegExp; owners: string[] }[] {
|
|
907
|
+
return text
|
|
908
|
+
.split("\n")
|
|
909
|
+
.map((l) => l.replace(/(^|\s)#.*$/, "").trim())
|
|
910
|
+
.filter(Boolean)
|
|
911
|
+
.map((l) => {
|
|
912
|
+
const [pattern, ...owners] = l.split(/\s+/);
|
|
913
|
+
|
|
914
|
+
return { re: codeownersGlob(pattern!), owners };
|
|
915
|
+
});
|
|
916
|
+
}
|
|
917
|
+
|
|
918
|
+
export function detectOwnership(rules: { re: RegExp; owners: string[] }[], files: string[], author: string): Ownership {
|
|
919
|
+
const owners = new Map<string, string[]>();
|
|
920
|
+
const unowned: string[] = [];
|
|
921
|
+
|
|
922
|
+
for (const f of files) {
|
|
923
|
+
const hit = [...rules].reverse().find((r) => r.re.test(f));
|
|
924
|
+
|
|
925
|
+
if (hit?.owners.length) owners.set(f, hit.owners);
|
|
926
|
+
else unowned.push(f);
|
|
927
|
+
}
|
|
928
|
+
|
|
929
|
+
const all = [...new Set([...owners.values()].flat())];
|
|
930
|
+
// Individuals are checked directly; team handles (@org/team) can't be resolved without an org read.
|
|
931
|
+
const authorOwns = all.length === 0 ? null : all.some((o) => o.toLowerCase() === `@${author.toLowerCase()}`) ? true : all.every((o) => o.includes("/")) ? null : false;
|
|
932
|
+
|
|
933
|
+
return { owners, unowned, authorOwns };
|
|
934
|
+
}
|
|
935
|
+
|
|
936
|
+
export type Gate = { gate: string; passed: boolean; message: string };
|
|
937
|
+
|
|
938
|
+
// Credential shapes that are unambiguous enough to deny on: a match is a key, not a variable named
|
|
939
|
+
// like one. Generic high-entropy strings are deliberately absent — they are how a secret scanner
|
|
940
|
+
// earns a reputation for noise, and this one denies the PR outright.
|
|
941
|
+
const CREDENTIAL_PATTERNS: [string, RegExp][] = [
|
|
942
|
+
["private key block", /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/],
|
|
943
|
+
["Anthropic key", /\bsk-ant-[\w-]{20,}/],
|
|
944
|
+
["OpenAI key", /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/],
|
|
945
|
+
["GitHub token", /\bgh[pousr]_[A-Za-z0-9]{20,}|\bgithub_pat_[A-Za-z0-9_]{20,}/],
|
|
946
|
+
["AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
|
|
947
|
+
["Google API key", /\bAIza[0-9A-Za-z_-]{35}\b/],
|
|
948
|
+
["Slack token", /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
|
|
949
|
+
["Stripe live key", /\b[sr]k_live_[0-9a-zA-Z]{16,}/],
|
|
950
|
+
];
|
|
951
|
+
|
|
952
|
+
/** Lines the diff adds, with the file each one lands in. */
|
|
953
|
+
function addedLines(diff: string): [file: string, line: string][] {
|
|
954
|
+
const out: [string, string][] = [];
|
|
955
|
+
let file = "";
|
|
956
|
+
// File headers appear only between `diff --git` and the first hunk. Inside a hunk every `+` line is
|
|
957
|
+
// added content, including one whose text starts with "++" and so renders as "+++…".
|
|
958
|
+
let inHunk = false;
|
|
959
|
+
|
|
960
|
+
for (const line of diff.split("\n")) {
|
|
961
|
+
if (line.startsWith("diff --git ")) inHunk = false;
|
|
962
|
+
else if (line.startsWith("@@")) inHunk = true;
|
|
963
|
+
else if (!inHunk && line.startsWith("+++ ")) file = stripDiffPath(line.slice(4)) ?? ""; // "+++ b/path", or quoted
|
|
964
|
+
else if (inHunk && line.startsWith("+")) out.push([file, line]);
|
|
965
|
+
}
|
|
966
|
+
|
|
967
|
+
return out;
|
|
968
|
+
}
|
|
969
|
+
|
|
970
|
+
/** Credentials in the PR's title or description, which reach the model and every reader of the PR. */
|
|
971
|
+
export const describedSecrets = (text: string) => CREDENTIAL_PATTERNS.flatMap(([what, re]) => (re.test(text) ? [`the PR title or description: ${what}`] : []));
|
|
972
|
+
|
|
973
|
+
/**
|
|
974
|
+
* Credentials added by the diff, as "path: what it looks like". Added lines only: a key being
|
|
975
|
+
* deleted is a key being removed, and context lines are already in the base.
|
|
976
|
+
*/
|
|
977
|
+
export function addedSecrets(diff: string): string[] {
|
|
978
|
+
const found = new Set<string>();
|
|
979
|
+
|
|
980
|
+
for (const [file, line] of addedLines(diff)) {
|
|
981
|
+
const hit = CREDENTIAL_PATTERNS.find(([, re]) => re.test(line));
|
|
982
|
+
|
|
983
|
+
if (hit) found.add(`${file}: ${hit[0]}`);
|
|
984
|
+
}
|
|
985
|
+
|
|
986
|
+
return [...found];
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
// A call that writes telemetry: a span attribute or event, or a logger method. The receiver names a logger
|
|
990
|
+
// (`log`, `logger`, `requestLog`, `console`) or a span (`span`, `rootSpan`), so a Map's `.set(`, a
|
|
991
|
+
// catalog's `.set(` or an emitter's `.error(` is not one.
|
|
992
|
+
const TELEMETRY_CALL_RE = /(?:\bsetAttributes?|\.addEvent|\b(?:log|logger|console|span|\w+(?:Log|Logger|Span))\s*\.\s*(?:set|info|warn|error|debug|trace|fatal|log|child))\s*\(/;
|
|
993
|
+
|
|
994
|
+
// A credential or card field by name, as an object key (`{ password }`, `apiKey:`, `'authorization':`) or as
|
|
995
|
+
// the attribute name a setAttribute call writes. The name ends at a word boundary, so `passwordReset`,
|
|
996
|
+
// `password_hash` and `tokens` are other fields. A word inside a log message is prose, not a key.
|
|
997
|
+
const SECRET_FIELD = String.raw`(?:password|passwd|secret|client_?secret|authorization|cookie|api_?key|private_?key|access_?token|refresh_?token|id_?token|session_?token|card_?number|cvv|cvc|ssn)`;
|
|
998
|
+
|
|
999
|
+
const SECRET_KEY_RES = [
|
|
1000
|
+
new RegExp(String.raw`[{,]\s*(?:["'\`][\w.-]*?)?\b(${SECRET_FIELD})\b["'\`]?\s*[:,}]`, "i"),
|
|
1001
|
+
new RegExp(String.raw`setAttribute\s*\(\s*["'\`][\w.-]*?\b(${SECRET_FIELD})["'\`]`, "i"),
|
|
1002
|
+
];
|
|
1003
|
+
|
|
1004
|
+
// A whole request's headers, body or cookies: every header is an Authorization or Cookie waiting to happen.
|
|
1005
|
+
// A single field (`req.headers['x-request-id']`, `req.body.orderId`) is bounded and fine.
|
|
1006
|
+
const WHOLE_REQUEST_RE = /\b((?:req|request|c\.req|ctx\.request)\.(?:headers|body|cookies)\b(?!\s*[.[(?])|c\.req\.header\(\s*\))/;
|
|
1007
|
+
|
|
1008
|
+
const JS_RE = /\.(?:[cm]?[jt]sx?)$/i;
|
|
1009
|
+
|
|
1010
|
+
/**
|
|
1011
|
+
* Credentials and whole requests the diff writes into logs or spans, as "path: what". Telemetry is copied to
|
|
1012
|
+
* vendors, kept for weeks and read by people who could not see the request, so a leak there is not fixed by
|
|
1013
|
+
* rotating a key. JS and TS source only, tests aside: the shapes are JavaScript's, and a test asserting on
|
|
1014
|
+
* redaction names the field on purpose. Added lines only, like the secrets gate.
|
|
1015
|
+
*/
|
|
1016
|
+
export function telemetryLeaks(diff: string): string[] {
|
|
1017
|
+
const found = new Set<string>();
|
|
1018
|
+
|
|
1019
|
+
for (const [file, added] of addedLines(diff)) {
|
|
1020
|
+
if (!JS_RE.test(file) || isTest(file)) continue;
|
|
1021
|
+
const raw = added.slice(1);
|
|
1022
|
+
const call = TELEMETRY_CALL_RE.exec(codeOnly(file, raw));
|
|
1023
|
+
|
|
1024
|
+
if (!call) continue;
|
|
1025
|
+
const rest = raw.slice(call.index);
|
|
1026
|
+
const key = SECRET_KEY_RES.map((re) => re.exec(rest)?.[1]).find(Boolean);
|
|
1027
|
+
const whole = WHOLE_REQUEST_RE.exec(codeOnly(file, rest))?.[1];
|
|
1028
|
+
|
|
1029
|
+
if (key) found.add(`${file}: ${key.toLowerCase()} written to telemetry`);
|
|
1030
|
+
|
|
1031
|
+
if (whole) found.add(`${file}: ${whole.replace(/\s+/g, "")} written to telemetry`);
|
|
1032
|
+
}
|
|
1033
|
+
|
|
1034
|
+
return [...found];
|
|
1035
|
+
}
|
|
1036
|
+
|
|
1037
|
+
// Markers that switch a test off, or narrow a run to one: JS/TS, pytest/unittest, Go, Rust, JUnit. A
|
|
1038
|
+
// conditional skip (`skipIf`, `mark.skipif`) is left to the reviewer: it is usually an environment guard.
|
|
1039
|
+
// Any .skip or .only access counts, so a call split across lines (`test\n .skip(`) or a parameterized form
|
|
1040
|
+
// (`.skip.each`) still matches.
|
|
1041
|
+
const TEST_SKIP_RE = /(\.(?:skip|only)\b|\bx(?:it|describe|test)\b|(?<![.\w])f(?:it|describe)\s*\(|mark\.(?:skip|xfail)\b|unittest\.skip\b|skipTest\s*\(|\bt\.Skip(?:Now|f)?\s*\()/i;
|
|
1042
|
+
|
|
1043
|
+
// A computed access needs a receiver (`test["skip"]`, `describe ['only']`), so an array literal of the word is not one.
|
|
1044
|
+
const COMPUTED_SKIP_RE = /([\w$)\]]\s*\[\s*)(["'`])(skip|only)\2\s*\]/g;
|
|
1045
|
+
|
|
1046
|
+
// Attribute markers, read in their own language wherever the file lives: Rust keeps unit tests inside src/*.rs.
|
|
1047
|
+
const ATTRIBUTE_SKIPS: [language: RegExp, marker: RegExp][] = [
|
|
1048
|
+
[/\.rs$/i, /(#\[ignore\b)/],
|
|
1049
|
+
[/\.(?:java|kts?|groovy|scala)$/i, /(@(?:[\w.]+\.)?(?:Disabled|Ignore)\b)/],
|
|
1050
|
+
];
|
|
1051
|
+
|
|
1052
|
+
// Class names JVM runners collect (Surefire, Failsafe, Gradle, Spock), read for renames only: TEST_RE leaves
|
|
1053
|
+
// them to the test directories, so they stay out of size exemptions.
|
|
1054
|
+
const JVM_TEST_NAME_RE = /(^|\/)(Test[^/]*|[^/]*(Tests?|TestCase|Spec|IT))\.(java|kts?|groovy|scala)$/;
|
|
1055
|
+
|
|
1056
|
+
const blank = (text: string) => " ".repeat(text.length);
|
|
1057
|
+
|
|
1058
|
+
/**
|
|
1059
|
+
* A line's code with its quoted string contents and comments blanked to spaces, so a marker named in prose or a
|
|
1060
|
+
* fixture reads as text and every column still lines up with the raw line. Strings go first, so a `//` inside
|
|
1061
|
+
* a URL survives. Template literals stay, since `${}` holds code, and `#` starts a comment in Python only.
|
|
1062
|
+
* Anything this cannot tell apart stays in, and the gate flags it.
|
|
1063
|
+
*/
|
|
1064
|
+
const codeOnly = (file: string, line: string) => {
|
|
1065
|
+
const code = line
|
|
1066
|
+
.replace(file.endsWith(".rs") ? /(")(?:\\.|(?!\1).)*\1/g : /(["'])(?:\\.|(?!\1).)*\1/g, (s, q: string) => q + blank(s.slice(2)) + q) // ' opens a Rust lifetime
|
|
1067
|
+
.replace(/\/\*.*?\*\//g, blank)
|
|
1068
|
+
.replace(/\/\/.*$/, blank);
|
|
1069
|
+
|
|
1070
|
+
return file.endsWith(".py") ? code.replace(/(?:^|\s)#.*$/, blank) : code;
|
|
1071
|
+
};
|
|
1072
|
+
|
|
1073
|
+
/** Computed skip or only accesses in a raw line, split by whether the receiver and bracket sit in code or in text. */
|
|
1074
|
+
function computedSkips(raw: string, code: string) {
|
|
1075
|
+
const inCode: string[] = [];
|
|
1076
|
+
const inText: string[] = [];
|
|
1077
|
+
|
|
1078
|
+
for (const m of raw.matchAll(COMPUTED_SKIP_RE)) {
|
|
1079
|
+
const end = m.index + m[1]!.length + 1; // through the opening quote, which codeOnly keeps
|
|
1080
|
+
|
|
1081
|
+
(code.slice(m.index, end) === raw.slice(m.index, end) ? inCode : inText).push(`[${m[2]}${m[3]}${m[2]}]`);
|
|
1082
|
+
}
|
|
1083
|
+
|
|
1084
|
+
return { inCode, inText };
|
|
1085
|
+
}
|
|
1086
|
+
|
|
1087
|
+
/**
|
|
1088
|
+
* Tests the change switches off, as "path: what": deleted test files and skip or only markers added to
|
|
1089
|
+
* test files. Agents reach green this way, and it is the one shape of it a regex can decide.
|
|
1090
|
+
*/
|
|
1091
|
+
export function weakenedTests(files: PRFile[], diff: string): string[] {
|
|
1092
|
+
// A rename takes a test out of the suite, the same as deleting it, when it leaves the test paths, drops a
|
|
1093
|
+
// runner's file-name pattern (a.test.ts → a.ts) or moves to an extension no runner collects (FooTest.java → FooTest.java.off).
|
|
1094
|
+
const runnerName = (p: string) => TEST_NAME_RE.test(p) || JVM_TEST_NAME_RE.test(p);
|
|
1095
|
+
|
|
1096
|
+
const renamedOut = (from: string, to: string) =>
|
|
1097
|
+
isTest(from) && (!isTest(to) || (runnerName(from) && !runnerName(to)) || (path.posix.extname(from) !== path.posix.extname(to) && !runnerName(to)));
|
|
1098
|
+
|
|
1099
|
+
const gone = (f: PRFile) => (f.status === "removed" && isTest(f.filename)) || (f.previousFilename !== undefined && renamedOut(f.previousFilename, f.filename));
|
|
1100
|
+
const found = new Set(files.flatMap((f) => (gone(f) ? [`${f.previousFilename ?? f.filename}: deleted`] : [])));
|
|
1101
|
+
|
|
1102
|
+
for (const [file, added] of addedLines(diff)) {
|
|
1103
|
+
const raw = added.slice(1);
|
|
1104
|
+
const line = codeOnly(file, raw);
|
|
1105
|
+
// A computed access (`test["skip"]`) is a string by shape, so it is read from the raw line, where it lines up with the code.
|
|
1106
|
+
const marker = (isTest(file) && (TEST_SKIP_RE.exec(line)?.[1] ?? computedSkips(raw, line).inCode[0])) || ATTRIBUTE_SKIPS.find(([language]) => language.test(file))?.[1].exec(line)?.[1];
|
|
1107
|
+
|
|
1108
|
+
if (marker) found.add(`${file}: ${marker.toLowerCase().replace(/\s+/g, "")}`);
|
|
1109
|
+
}
|
|
1110
|
+
|
|
1111
|
+
return [...found];
|
|
1112
|
+
}
|
|
1113
|
+
|
|
1114
|
+
// Skips that are often legitimate: a condition (an environment guard, mostly) or a placeholder for a test to come.
|
|
1115
|
+
const CONDITIONAL_SKIP_RE = /(\.(?:skipIf|runIf|todo)\b|mark\.skipif\b|#\[cfg_attr\()/i;
|
|
1116
|
+
|
|
1117
|
+
const TEST_MARKER_INSTRUCTION =
|
|
1118
|
+
"These lines gained a conditional skip, a todo, or a skip or only marker inside a comment or string, where the tests gate leaves the call to you. Read each line. REFUSE if it switches a test off or narrows the run where it should run: a condition that is always true, a todo replacing a test that had a body, a marker hidden in code a line-by-line read misses.";
|
|
1119
|
+
|
|
1120
|
+
/** Skip markers the tests gate leaves to the reviewer, as one scrutiny flag: conditional skips, todos, and markers it read as prose. */
|
|
1121
|
+
export function testMarkerFlags(diff: string): ScrutinyFlag[] {
|
|
1122
|
+
const found = new Set<string>();
|
|
1123
|
+
|
|
1124
|
+
for (const [file, added] of addedLines(diff)) {
|
|
1125
|
+
const raw = added.slice(1);
|
|
1126
|
+
const code = codeOnly(file, raw);
|
|
1127
|
+
const attribute = ATTRIBUTE_SKIPS.find(([language]) => language.test(file))?.[1];
|
|
1128
|
+
const conditional = (isTest(file) || attribute) && CONDITIONAL_SKIP_RE.exec(code)?.[1];
|
|
1129
|
+
|
|
1130
|
+
const prose =
|
|
1131
|
+
(isTest(file) && !TEST_SKIP_RE.test(code) && (TEST_SKIP_RE.exec(raw)?.[1] ?? computedSkips(raw, code).inText[0])) ||
|
|
1132
|
+
(attribute && !attribute.test(code) && attribute.exec(raw)?.[1]);
|
|
1133
|
+
|
|
1134
|
+
const marker = conditional || prose;
|
|
1135
|
+
|
|
1136
|
+
if (marker) found.add(`${file}: ${marker.toLowerCase().replace(/\s+/g, "")}`);
|
|
1137
|
+
}
|
|
1138
|
+
|
|
1139
|
+
return found.size ? [{ name: "test_markers", files: [...found], instruction: TEST_MARKER_INSTRUCTION }] : [];
|
|
1140
|
+
}
|
|
1141
|
+
|
|
1142
|
+
// Inline comments that silence a linter, type checker, scanner or coverage tool for the lines around them.
|
|
1143
|
+
const SUPPRESSION_RE =
|
|
1144
|
+
/(?<![\w-])(eslint-disable|oxlint-disable|biome-ignore|@ts-ignore|@ts-expect-error|@ts-nocheck|noqa|nosec|nosemgrep|nolint|type:\s*ignore|pylint:\s*disable|rubocop:\s*disable|shellcheck\s+disable|hadolint\s+ignore|gitleaks:allow|istanbul\s+ignore|c8\s+ignore|v8\s+ignore|pragma:\s*no\s*cover)(?!\w)/i;
|
|
1145
|
+
|
|
1146
|
+
const SUPPRESSION_INSTRUCTION =
|
|
1147
|
+
"These added comments silence a linter, type checker, scanner or coverage tool. Read the code each one covers. REFUSE if a suppression hides a finding the change introduces, or covers more than the line that needs it without a stated reason. A narrow suppression with its reason is fine.";
|
|
1148
|
+
|
|
1149
|
+
/** Suppression comments the diff adds, as one scrutiny flag listing "path: kind". */
|
|
1150
|
+
export function suppressionFlags(diff: string): ScrutinyFlag[] {
|
|
1151
|
+
const found = new Set<string>();
|
|
1152
|
+
|
|
1153
|
+
for (const [file, line] of addedLines(diff)) {
|
|
1154
|
+
const hit = SUPPRESSION_RE.exec(line);
|
|
1155
|
+
|
|
1156
|
+
if (hit) found.add(`${file}: ${hit[1]!.toLowerCase().replace(/\s+/g, " ")}`);
|
|
1157
|
+
}
|
|
1158
|
+
|
|
1159
|
+
return found.size ? [{ name: "suppressions", files: [...found], instruction: SUPPRESSION_INSTRUCTION }] : [];
|
|
1160
|
+
}
|
|
1161
|
+
|
|
1162
|
+
const INCIDENT_INSTRUCTION =
|
|
1163
|
+
"This PR closes an issue labelled `incident`: a failure seen on the default branch or in production, and the issue body is its evidence (untrusted, like the diff). REFUSE unless a test reproduces the reported failure and would fail without the fix: one the diff adds or changes, or, when the issue reports a test already failing on the default branch, that test passing unchanged. REFUSE a fix that hides the symptom instead of removing the cause: an error caught and discarded, a retry or timeout raised around it, the check or alert removed, the failing test skipped or loosened.";
|
|
1164
|
+
|
|
1165
|
+
/** Closing issues labelled `incident`, as one scrutiny flag: a fix for a live failure must prove itself with a reproducing test. */
|
|
1166
|
+
export function incidentFlags(issues: LinkedIssue[]): ScrutinyFlag[] {
|
|
1167
|
+
const hit = issues.flatMap((i) => (i.labels.some((l) => l.toLowerCase() === "incident") ? [i.ref] : []));
|
|
1168
|
+
|
|
1169
|
+
return hit.length ? [{ name: "incident", files: hit, instruction: INCIDENT_INSTRUCTION }] : [];
|
|
1170
|
+
}
|
|
1171
|
+
|
|
1172
|
+
export type PRMeta = {
|
|
1173
|
+
title: string;
|
|
1174
|
+
body?: string;
|
|
1175
|
+
diff?: string;
|
|
1176
|
+
author: string;
|
|
1177
|
+
authorAssociation: string;
|
|
1178
|
+
isFork: boolean;
|
|
1179
|
+
isDraft: boolean;
|
|
1180
|
+
mergeable: string;
|
|
1181
|
+
reviews: { user: string; state: string }[];
|
|
1182
|
+
files: PRFile[];
|
|
1183
|
+
manifestScriptEdits?: string[];
|
|
1184
|
+
/** Folder size budgets from resolveSizeOverrides: the global size_gate alone when no folder grants apply. */
|
|
1185
|
+
sizeBudgets: EffectiveSize;
|
|
1186
|
+
};
|
|
1187
|
+
|
|
1188
|
+
const BOT_RE = /\[bot\]$|^(dependabot|renovate)/i;
|
|
1189
|
+
|
|
1190
|
+
export { TRUSTED_ASSOCIATIONS };
|
|
1191
|
+
|
|
1192
|
+
export type GateRun = Tier & { gates: Gate[]; denied: string[] };
|
|
1193
|
+
|
|
1194
|
+
export function runGates(policy: Policy, pr: PRMeta): GateRun {
|
|
1195
|
+
// Both ends of a rename count: moving a file out of auth/ is a change to auth/.
|
|
1196
|
+
const names = pr.files.flatMap((f) => (f.previousFilename ? [f.filename, f.previousFilename] : [f.filename]));
|
|
1197
|
+
const gates: Gate[] = [];
|
|
1198
|
+
|
|
1199
|
+
// A CHANGES_REQUESTED stays blocking until that user APPROVES or it is DISMISSED; a later COMMENTED
|
|
1200
|
+
// review does not withdraw it. Track each user's latest *decision*, skipping comments.
|
|
1201
|
+
const latest = new Map<string, string>();
|
|
1202
|
+
|
|
1203
|
+
for (const r of pr.reviews) if (r.state !== "COMMENTED" && r.state !== "PENDING") latest.set(r.user, r.state);
|
|
1204
|
+
const blocking = [...latest].flatMap(([u, s]) => (s === "CHANGES_REQUESTED" ? [u] : []));
|
|
1205
|
+
|
|
1206
|
+
const prereqProblems = [
|
|
1207
|
+
pr.isDraft ? "draft" : null,
|
|
1208
|
+
pr.mergeable === "CONFLICTING" ? "merge conflicts" : null,
|
|
1209
|
+
blocking.length ? `changes requested by ${blocking.join(", ")}` : null,
|
|
1210
|
+
BOT_RE.test(pr.author) ? `bot author ${pr.author}` : null,
|
|
1211
|
+
pr.isFork ? "head is on a fork" : null,
|
|
1212
|
+
TRUSTED_ASSOCIATIONS.has(pr.authorAssociation) ? null : `author is ${pr.authorAssociation}, not a collaborator`,
|
|
1213
|
+
].filter(Boolean);
|
|
1214
|
+
|
|
1215
|
+
gates.push({ gate: "prerequisites", passed: prereqProblems.length === 0, message: prereqProblems.join("; ") || "ready" });
|
|
1216
|
+
|
|
1217
|
+
const denied = denyCategories(policy, names);
|
|
1218
|
+
|
|
1219
|
+
// A rule pack reaches the reviewer as trusted context, wherever it lives, so a PR that edits one is
|
|
1220
|
+
// editing gate's policy and needs a human. Otherwise an approved PR could rewrite the rules later PRs
|
|
1221
|
+
// are judged by.
|
|
1222
|
+
if (!denied.includes("gate_policy") && names.some((n) => touchesRulePack(policy, n))) denied.push("gate_policy");
|
|
1223
|
+
const scripts = pr.manifestScriptEdits ?? [];
|
|
1224
|
+
gates.push({
|
|
1225
|
+
gate: "deny-list",
|
|
1226
|
+
passed: denied.length === 0 && scripts.length === 0,
|
|
1227
|
+
message: [denied.length ? `touches ${denied.join(", ")}` : "", scripts.length ? `scripts/hooks changed in ${scripts.join(", ")}` : ""].filter(Boolean).join("; ") || "no sensitive paths",
|
|
1228
|
+
});
|
|
1229
|
+
|
|
1230
|
+
const sizeCheck = sizeWithinBudgets(pr.files, pr.sizeBudgets);
|
|
1231
|
+
gates.push({ gate: "size", passed: sizeCheck.ok, message: sizeCheck.message });
|
|
1232
|
+
|
|
1233
|
+
// A committed credential is never auto-approvable, whatever tier the change is: this runs before
|
|
1234
|
+
// the model and denies on its own. It reads the diff, not the checkout, so a key that was already
|
|
1235
|
+
// in the tree is someone else's problem to rotate, not this PR's gate.
|
|
1236
|
+
const secrets = [...(pr.diff ? addedSecrets(pr.diff) : []), ...describedSecrets(`${pr.title}\n${pr.body ?? ""}`)];
|
|
1237
|
+
|
|
1238
|
+
gates.push({ gate: "secrets", passed: secrets.length === 0, message: secrets.length ? `credential added in ${secrets.join("; ")}` : "no credentials in the diff" });
|
|
1239
|
+
|
|
1240
|
+
// Telemetry outlives the request and leaves the team's hands, so a credential or a whole request written
|
|
1241
|
+
// into a log or span denies before the model, the same as a committed key.
|
|
1242
|
+
const leaks = pr.diff ? telemetryLeaks(pr.diff) : [];
|
|
1243
|
+
|
|
1244
|
+
gates.push({ gate: "telemetry", passed: leaks.length === 0, message: leaks.length ? `sensitive data in telemetry: ${leaks.join("; ")}` : "no credentials or whole requests in logs or spans" });
|
|
1245
|
+
|
|
1246
|
+
// A green run over a deleted or skipped test proves nothing, and no reviewer paragraph should be able to
|
|
1247
|
+
// argue otherwise, so this denies before the model. Rewritten assertions stay with the reviewer.
|
|
1248
|
+
const weakened = weakenedTests(pr.files, pr.diff ?? "");
|
|
1249
|
+
|
|
1250
|
+
gates.push({ gate: "tests", passed: weakened.length === 0, message: weakened.length ? `tests weakened: ${weakened.join("; ")}` : "no tests deleted or skipped" });
|
|
1251
|
+
|
|
1252
|
+
const t = tier(policy, pr.files, denied);
|
|
1253
|
+
gates.push({ gate: "tier", passed: t.tier !== "T2-never", message: [t.tier, t.sub].filter(Boolean).join(" / ") });
|
|
1254
|
+
|
|
1255
|
+
return { gates, denied, ...t };
|
|
1256
|
+
}
|
|
1257
|
+
|
|
1258
|
+
/**
|
|
1259
|
+
* A workflow template with its Bedrock OIDC lines turned on: every `#aws-oidc ` prefix removed, which grants
|
|
1260
|
+
* `id-token: write` and adds the step that exchanges it for the AWS_ROLE_ARN role's credentials.
|
|
1261
|
+
*/
|
|
1262
|
+
export const enableAwsOidc = (template: string) => template.replace(/^(\s*)#aws-oidc /gm, "$1");
|
|
1263
|
+
|
|
1264
|
+
/** The bundled policy with the settings `gate init` was given written in, so a first run needs only the secret. */
|
|
1265
|
+
export function policyWithSettings(text: string, s: { model?: string; region?: string; pricing?: z.infer<typeof Pricing> }): string {
|
|
1266
|
+
const lines = [
|
|
1267
|
+
s.model && `model: ${JSON.stringify(s.model)}`,
|
|
1268
|
+
s.region && `provider:\n region: ${JSON.stringify(s.region)}`,
|
|
1269
|
+
s.pricing && `pricing:\n${Object.entries(s.pricing).map(([model, price]) => ` ${JSON.stringify(model)}: ${JSON.stringify(price)}`).join("\n")}`,
|
|
1270
|
+
].filter(Boolean);
|
|
1271
|
+
|
|
1272
|
+
const out = lines.length ? text.replace(/^version: 1\n/m, `$&\n# Written by gate init.\n${lines.join("\n")}\n`) : text;
|
|
1273
|
+
|
|
1274
|
+
PolicySchema.parse(parseYaml(out)); // a bad --model or --region fails here, not on the first review
|
|
1275
|
+
|
|
1276
|
+
return out;
|
|
1277
|
+
}
|
|
1278
|
+
|
|
1279
|
+
/** This package's version: what `gate init` pins the workflow to, and what every review records. */
|
|
1280
|
+
export const SHEPHERD_VERSION = z.object({ version: z.string() }).parse(JSON.parse(readFileSync(path.join(DEFAULTS_DIR, "..", "package.json"), "utf8"))).version;
|
|
1281
|
+
|
|
1282
|
+
const JobEnvironment = z.union([z.string(), z.object({ name: z.string() }).transform((e) => e.name)]);
|
|
1283
|
+
|
|
1284
|
+
const InstalledJobs = z.object({ jobs: z.record(z.string(), z.object({ environment: JobEnvironment.optional() }).loose()) }).loose();
|
|
1285
|
+
|
|
1286
|
+
/** The environment a workflow's job runs in, read as YAML: `environment: "ai-review"` and `{ name: … }` both count. */
|
|
1287
|
+
const environmentOf = (workflow: string) => Object.values(InstalledJobs.parse(parseYaml(workflow)).jobs).find((j) => j.environment)?.environment;
|
|
1288
|
+
|
|
1289
|
+
/** The choices an installed workflow was written with, so `gate init --upgrade` keeps them on today's template. */
|
|
1290
|
+
export function workflowChoices(installed: string) {
|
|
1291
|
+
return {
|
|
1292
|
+
awsOidc: /^\s*id-token: write/m.test(installed),
|
|
1293
|
+
environment: environmentOf(installed),
|
|
1294
|
+
region: /vars\.AWS_REGION \|\| '([a-z0-9-]+)'/.exec(installed)?.[1],
|
|
1295
|
+
};
|
|
1296
|
+
}
|
|
1297
|
+
|
|
1298
|
+
/**
|
|
1299
|
+
* A workflow template as `gate init` writes it: pinned to this gate, with OIDC turned on and the review job in a
|
|
1300
|
+
* GitHub environment when asked. An environment's secrets reach only the jobs that name it, so the model key
|
|
1301
|
+
* stays out of every other workflow in the repository.
|
|
1302
|
+
*/
|
|
1303
|
+
export function installWorkflow(template: string, o: { awsOidc?: boolean; environment?: string; region?: string } = {}): string {
|
|
1304
|
+
if (o.environment !== undefined && !/^[\w.-]+$/.test(o.environment)) throw new Error(`--environment: not a GitHub environment name: ${o.environment}`);
|
|
1305
|
+
|
|
1306
|
+
if (o.region !== undefined && !/^[a-z]{2}(-[a-z]+)+-\d$/.test(o.region)) throw new Error(`--region: not an AWS region: ${o.region}`);
|
|
1307
|
+
// The OIDC step runs before gate reads its policy, so it gets the region written in, under the variable.
|
|
1308
|
+
const regional = o.region ? template.replace("aws-region: ${{ vars.AWS_REGION }}", `aws-region: \${{ vars.AWS_REGION || '${o.region}' }}`) : template;
|
|
1309
|
+
const pinned = regional.replace(/^(\s*SHEPHERD_VERSION: )\S+/m, `$1${SHEPHERD_VERSION}`);
|
|
1310
|
+
const placed = o.environment ? pinned.replace(/^( {4}runs-on: .*\n)/m, `$1 environment: ${o.environment} # holds the model key: only this job can read it\n`) : pinned;
|
|
1311
|
+
|
|
1312
|
+
return o.awsOidc ? enableAwsOidc(placed) : placed;
|
|
1313
|
+
}
|