@jagreehal/shepherd 0.14.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.
- package/AGENTS.md +13 -5
- package/README.md +40 -27
- package/THIRD_PARTY_NOTICES.md +2 -0
- package/gate/.shepherd/gate.schema.json +647 -0
- package/gate/.shepherd/gate.yml +122 -0
- package/gate/.shepherd/review-guidance.md +95 -0
- package/gate/src/actions.ts +32 -0
- package/gate/src/cli.ts +1028 -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 +288 -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 +606 -0
- package/gate/src/notify.ts +57 -0
- package/gate/src/policy.ts +1297 -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 +127 -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 +20 -6
- 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 +29 -10
- package/skills/garden/references/telemetry.md +4 -4
- package/skills/incident/SKILL.md +19 -9
- package/skills/lens-import/SKILL.md +7 -7
- package/skills/review-maintainability/SKILL.md +1 -1
- package/skills/review-slop/SKILL.md +1 -1
- package/skills/shepherd/SKILL.md +59 -44
- package/skills/shepherd/references/degradation.md +3 -3
- package/skills/shepherd/references/dispatch.md +2 -2
- 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 +26 -17
- package/skills/swarm/references/custom-lenses.md +2 -2
- package/skills/swarm/references/formats.md +1 -1
- package/skills/triage/SKILL.md +11 -11
- package/src/bin.ts +10 -0
- package/src/cli.ts +283 -41
- package/src/config.ts +26 -25
- package/src/doctor.ts +31 -18
- package/src/garden-traces.ts +13 -13
- package/src/garden.ts +43 -8
- 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 +9 -12
- package/templates/shepherd.yml +39 -40
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// Pins a finding to the line it names. GitHub takes a review comment on a line inside a diff hunk, so gate checks each
|
|
2
|
+
// anchor against the diff before sending it. The review body lists every issue, anchored or not.
|
|
3
|
+
import { diffSectionPath } from "./reviewer.ts";
|
|
4
|
+
|
|
5
|
+
/** A finding on a line of the head's side of the diff. */
|
|
6
|
+
export type Anchored = { path: string; line: number; body: string };
|
|
7
|
+
|
|
8
|
+
const MAX_ANCHORS = 25;
|
|
9
|
+
|
|
10
|
+
/** The new-side lines of a section GitHub accepts a comment on: added and context lines, inside a hunk. */
|
|
11
|
+
export function commentableLines(section: string): Set<number> {
|
|
12
|
+
const lines = new Set<number>();
|
|
13
|
+
let next = 0;
|
|
14
|
+
let inHunk = false;
|
|
15
|
+
|
|
16
|
+
for (const l of section.split("\n")) {
|
|
17
|
+
const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l);
|
|
18
|
+
|
|
19
|
+
if (hunk) {
|
|
20
|
+
next = Number(hunk[1]);
|
|
21
|
+
inHunk = true;
|
|
22
|
+
} else if (inHunk && (l[0] === "+" || l[0] === " ")) lines.add(next++);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
return lines;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Each file's commentable lines, by its path on the head: a section's `+++` line when it has one, for a rename's new name. */
|
|
29
|
+
function commentableMap(diff: string): Map<string, Set<number>> {
|
|
30
|
+
const sections = diff.split(/^(?=diff --git )/m).filter((s) => s.startsWith("diff --git "));
|
|
31
|
+
|
|
32
|
+
return new Map(
|
|
33
|
+
sections.flatMap((s) => {
|
|
34
|
+
const firstHunk = s.search(/^@@/m);
|
|
35
|
+
const meta = firstHunk < 0 ? s : s.slice(0, firstHunk);
|
|
36
|
+
const head = /^\+\+\+ b\/(.+)$/m.exec(meta)?.[1]?.replace(/\t$/, "") ?? diffSectionPath(s);
|
|
37
|
+
|
|
38
|
+
return head ? [[head, commentableLines(s)] as const] : [];
|
|
39
|
+
}),
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The `file:line` an issue opens with, as the verdict schema asks; null when it opens with anything else. */
|
|
44
|
+
export function issueAnchor(issue: string): { path: string; line: number } | null {
|
|
45
|
+
const m = /^[\s*_`"']*(?:\.\/)?([^\s:*`"']+):(\d+)/.exec(issue);
|
|
46
|
+
|
|
47
|
+
return m ? { path: m[1]!, line: Number(m[2]) } : null; // SAFETY: both groups are mandatory in the match
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The issues that open with a line inside the diff, ready to post. The rest stay in the review body alone. */
|
|
51
|
+
export function anchoredIssues(issues: string[], diff: string): Anchored[] {
|
|
52
|
+
const map = commentableMap(diff);
|
|
53
|
+
|
|
54
|
+
return issues.flatMap((body) => {
|
|
55
|
+
const at = issueAnchor(body);
|
|
56
|
+
|
|
57
|
+
return at && map.get(at.path)?.has(at.line) ? [{ ...at, body }] : [];
|
|
58
|
+
}).slice(0, MAX_ANCHORS);
|
|
59
|
+
}
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
// Launch CLI reviewers in private process and mount namespaces with a trusted image.
|
|
2
|
+
import { spawnSync } from "node:child_process";
|
|
3
|
+
import { randomUUID } from "node:crypto";
|
|
4
|
+
import { chmodSync, closeSync, constants, cpSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
5
|
+
import { tmpdir } from "node:os";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
export const CLI_IMAGE = "gate-reviewer:local";
|
|
10
|
+
|
|
11
|
+
export const CLI_ROOT = "/review";
|
|
12
|
+
|
|
13
|
+
export const CLI_CONTROL = "/run/gate";
|
|
14
|
+
|
|
15
|
+
export const CLI_OUTPUT = "/output/verdict.json";
|
|
16
|
+
|
|
17
|
+
const preparedImages = new Set<string>();
|
|
18
|
+
|
|
19
|
+
/** Prepare the packaged image after The gate has handled standing approvals and gates. */
|
|
20
|
+
export function prepareCliImage(image: string, env: NodeJS.ProcessEnv, context: string): void {
|
|
21
|
+
if (process.env.SHEPHERD_BUILD_CLI_IMAGE !== "1" || preparedImages.has(image)) return;
|
|
22
|
+
|
|
23
|
+
const dockerfile = path.resolve(import.meta.dir, "../templates/reviewer.Dockerfile");
|
|
24
|
+
const run = spawnSync("docker", ["build", "--file", dockerfile, "--tag", image, context], { encoding: "utf8", env, maxBuffer: 8 << 20, timeout: 10 * 60_000 });
|
|
25
|
+
|
|
26
|
+
if (run.error || run.status !== 0) throw new Error(`CLI image preparation: ${run.error?.message ?? run.stderr.slice(0, 500)}`);
|
|
27
|
+
|
|
28
|
+
preparedImages.add(image);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** The only host:port each reviewer may reach: its model provider's API. */
|
|
32
|
+
export const EGRESS = { claude: ["api.anthropic.com:443"], codex: ["api.openai.com:443"] } as const;
|
|
33
|
+
|
|
34
|
+
export const EGRESS_PORT = 3128;
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The egress proxy, run with node from the reviewer image. It tunnels CONNECT to the allowed host:port pairs
|
|
38
|
+
* only when the client's TLS ClientHello names that same host, and refuses everything else, logging each
|
|
39
|
+
* decision.
|
|
40
|
+
*/
|
|
41
|
+
export const EGRESS_PROXY = `const http = require("http"), net = require("net");
|
|
42
|
+
const allow = new Set((process.env.SHEPHERD_EGRESS_ALLOW || "").split(",").filter(Boolean));
|
|
43
|
+
const [fromNet, fromBits] = (process.env.SHEPHERD_EGRESS_FROM || "").split("/");
|
|
44
|
+
const v4 = (a) => a.split(".").reduce((n, o) => n * 256 + Number(o), 0);
|
|
45
|
+
const fromReview = (address) => {
|
|
46
|
+
const ip = String(address).replace(/^::ffff:/, "");
|
|
47
|
+
if (!fromNet || !/^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(ip)) return false;
|
|
48
|
+
const size = 2 ** (32 - Number(fromBits));
|
|
49
|
+
return Math.floor(v4(ip) / size) === Math.floor(v4(fromNet) / size);
|
|
50
|
+
};
|
|
51
|
+
const server = http.createServer((req, res) => { res.writeHead(403); res.end("gate egress: CONNECT only\\n"); });
|
|
52
|
+
server.on("connection", (socket) => { if (!fromReview(socket.remoteAddress)) { console.log("refuse " + socket.remoteAddress); socket.destroy(); } });
|
|
53
|
+
// The TLS server name in the client's ClientHello, undefined until the whole message has arrived, null when
|
|
54
|
+
// the bytes are not a ClientHello or carry no name. TLS may split one handshake message across records, so
|
|
55
|
+
// the records' fragments are joined first. Checked so a tunnel to an allowed address cannot speak TLS to
|
|
56
|
+
// another site sharing that address (a CDN fronting many domains).
|
|
57
|
+
const sni = (b) => {
|
|
58
|
+
const parts = [];
|
|
59
|
+
let p = 0, have = 0, need = Infinity;
|
|
60
|
+
while (have < need) {
|
|
61
|
+
if (b.length > p && b[p] !== 22) return null;
|
|
62
|
+
if (b.length < p + 5) return undefined;
|
|
63
|
+
const len = b.readUInt16BE(p + 3);
|
|
64
|
+
if (b.length < p + 5 + len) return undefined;
|
|
65
|
+
parts.push(b.subarray(p + 5, p + 5 + len));
|
|
66
|
+
have += len;
|
|
67
|
+
p += 5 + len;
|
|
68
|
+
if (need === Infinity && have >= 4) {
|
|
69
|
+
const h = Buffer.concat(parts);
|
|
70
|
+
if (h[0] !== 1) return null;
|
|
71
|
+
need = 4 + h.readUIntBE(1, 3);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
const h = Buffer.concat(parts);
|
|
75
|
+
let q = 4 + 2 + 32;
|
|
76
|
+
q += 1 + h[q];
|
|
77
|
+
q += 2 + h.readUInt16BE(q);
|
|
78
|
+
q += 1 + h[q];
|
|
79
|
+
const extEnd = Math.min(need, q + 2 + h.readUInt16BE(q));
|
|
80
|
+
for (q += 2; q + 4 <= extEnd; q += 4 + h.readUInt16BE(q + 2)) {
|
|
81
|
+
if (h.readUInt16BE(q) === 0 && h[q + 6] === 0) return h.toString("latin1", q + 9, q + 9 + h.readUInt16BE(q + 7)).toLowerCase();
|
|
82
|
+
}
|
|
83
|
+
return null;
|
|
84
|
+
};
|
|
85
|
+
server.on("connect", (req, client, head) => {
|
|
86
|
+
const target = String(req.url).toLowerCase();
|
|
87
|
+
if (!allow.has(target)) { console.log("deny " + target); client.end("HTTP/1.1 403 Forbidden\\r\\n\\r\\n"); return; }
|
|
88
|
+
const at = target.lastIndexOf(":"), host = target.slice(0, at), port = Number(target.slice(at + 1));
|
|
89
|
+
let hello = head;
|
|
90
|
+
const timer = setTimeout(() => decide(null), 10000);
|
|
91
|
+
const decide = (name) => {
|
|
92
|
+
clearTimeout(timer);
|
|
93
|
+
client.removeListener("data", onData);
|
|
94
|
+
client.pause();
|
|
95
|
+
if (name !== host) { console.log("deny " + target + " sni " + name); client.destroy(); return; }
|
|
96
|
+
console.log("allow " + target);
|
|
97
|
+
const upstream = net.connect(port, host, () => { upstream.write(hello); upstream.pipe(client); client.pipe(upstream); });
|
|
98
|
+
upstream.on("error", () => client.destroy());
|
|
99
|
+
client.on("error", () => upstream.destroy());
|
|
100
|
+
};
|
|
101
|
+
const check = () => {
|
|
102
|
+
let name;
|
|
103
|
+
try { name = sni(hello); } catch { name = null; }
|
|
104
|
+
// A ClientHello is a few KiB; 64 KiB bounds what a client can make the proxy hold before it decides.
|
|
105
|
+
if (name === undefined && hello.length < 65536) return;
|
|
106
|
+
decide(name === undefined ? null : name);
|
|
107
|
+
};
|
|
108
|
+
const onData = (d) => { hello = Buffer.concat([hello, d]); check(); };
|
|
109
|
+
client.on("data", onData);
|
|
110
|
+
client.on("error", () => {});
|
|
111
|
+
client.write("HTTP/1.1 200 Connection Established\\r\\n\\r\\n");
|
|
112
|
+
if (hello.length) check();
|
|
113
|
+
});
|
|
114
|
+
server.listen(Number(process.env.SHEPHERD_EGRESS_PORT || ${3128}), "0.0.0.0", () => console.log("gate egress ready"));`;
|
|
115
|
+
|
|
116
|
+
export type Egress = { network: string; proxyUrl: string; logs: () => string; stop: () => void };
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* How many connections the proxy let through and refused, by kind, during one review. A refusal can mean a
|
|
120
|
+
* hijacked reviewer reaching out. Counts only: the target and the TLS name are chosen by the reviewer, so a
|
|
121
|
+
* hijacked one could encode a secret in them, and logs, evidence and telemetry would carry it out.
|
|
122
|
+
*/
|
|
123
|
+
export type EgressDecisions = { allowed: number; deniedHost: number; deniedName: number; refused: number };
|
|
124
|
+
|
|
125
|
+
/** Count the proxy's decision lines: `allow <target>`, `deny <target>`, `deny <target> sni <name>`, `refuse <address>`. */
|
|
126
|
+
export function egressDecisions(logs: string): EgressDecisions {
|
|
127
|
+
const counts = { allowed: 0, deniedHost: 0, deniedName: 0, refused: 0 };
|
|
128
|
+
|
|
129
|
+
for (const line of logs.split("\n")) {
|
|
130
|
+
if (line.startsWith("allow ")) counts.allowed++;
|
|
131
|
+
else if (line.startsWith("deny ")) counts[/ sni /.test(line) ? "deniedName" : "deniedHost"]++;
|
|
132
|
+
else if (line.startsWith("refuse ")) counts.refused++;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
return counts;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** Refusals across reviews, as one line: "2 to another host, 1 with another TLS name", or "" for none. */
|
|
139
|
+
export function egressRefusals(decisions: (EgressDecisions | undefined)[]): string {
|
|
140
|
+
const sum = (k: "deniedHost" | "deniedName" | "refused") => decisions.reduce((n, d) => n + (d?.[k] ?? 0), 0);
|
|
141
|
+
|
|
142
|
+
const parts = [
|
|
143
|
+
[sum("deniedHost"), "to another host"],
|
|
144
|
+
[sum("deniedName"), "with another TLS name"],
|
|
145
|
+
[sum("refused"), "from outside the review network"],
|
|
146
|
+
] as const;
|
|
147
|
+
|
|
148
|
+
return parts.flatMap(([n, what]) => (n ? [`${n} ${what}`] : [])).join(", ");
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
const pause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* A private network with no route out, and the proxy that is its one door: the proxy sits on the private
|
|
155
|
+
* network and the default bridge, accepts connections only from the private network's subnet, and passes
|
|
156
|
+
* only `allow`. Stopping removes both.
|
|
157
|
+
*/
|
|
158
|
+
export function startEgress(id: string, image: string, allow: readonly string[], env: NodeJS.ProcessEnv): Egress {
|
|
159
|
+
const network = `gate-net-${id}`;
|
|
160
|
+
const proxy = `gate-egress-${id}`;
|
|
161
|
+
|
|
162
|
+
const docker = (args: string[]) => {
|
|
163
|
+
const run = spawnSync("docker", args, { encoding: "utf8", env, timeout: 30_000 });
|
|
164
|
+
|
|
165
|
+
if (run.error || run.status !== 0) throw new Error(`docker ${args[0]} failed (${run.status ?? "launch"}): ${run.error?.message ?? run.stderr.slice(0, 300)}`);
|
|
166
|
+
|
|
167
|
+
return run.stdout;
|
|
168
|
+
};
|
|
169
|
+
|
|
170
|
+
const stop = () => {
|
|
171
|
+
spawnSync("docker", ["rm", "--force", proxy], { env, stdio: "ignore", timeout: 10_000 });
|
|
172
|
+
spawnSync("docker", ["network", "rm", network], { env, stdio: "ignore", timeout: 10_000 });
|
|
173
|
+
};
|
|
174
|
+
|
|
175
|
+
const logs = () => spawnSync("docker", ["logs", proxy], { encoding: "utf8", env, timeout: 10_000 }).stdout ?? "";
|
|
176
|
+
|
|
177
|
+
try {
|
|
178
|
+
// Give the reviewer an internal network whose bridge has no host IPv4 address.
|
|
179
|
+
docker(["network", "create", "--internal", "--opt", "com.docker.network.bridge.inhibit_ipv4=true", network]);
|
|
180
|
+
const subnet = docker(["network", "inspect", "--format", "{{(index .IPAM.Config 0).Subnet}}", network]).trim();
|
|
181
|
+
|
|
182
|
+
if (!/^\d+\.\d+\.\d+\.\d+\/\d+$/.test(subnet)) throw new Error(`the private network has no IPv4 subnet: ${subnet}`);
|
|
183
|
+
docker(["run", "--detach", "--pull=never", "--name", proxy, "--user", "1000:1000", "--read-only", "--cap-drop=ALL", "--security-opt=no-new-privileges",
|
|
184
|
+
"--pids-limit=64", "--memory=128m", "--network=bridge", "--env", `SHEPHERD_EGRESS_ALLOW=${allow.join(",")}`, "--env", `SHEPHERD_EGRESS_FROM=${subnet}`, "--entrypoint", "node", image, "-e", EGRESS_PROXY]);
|
|
185
|
+
docker(["network", "connect", network, proxy]);
|
|
186
|
+
|
|
187
|
+
for (let waited = 0; waited < 10_000; waited += 100) {
|
|
188
|
+
if (logs().includes("gate egress ready")) return { network, proxyUrl: `http://${proxy}:${EGRESS_PORT}`, logs, stop };
|
|
189
|
+
pause(100);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
throw new Error("the egress proxy did not start");
|
|
193
|
+
} catch (e) {
|
|
194
|
+
stop();
|
|
195
|
+
throw e;
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** No host namespace, home, socket or credential directory is exposed to the reviewer. */
|
|
200
|
+
export function containerArgs(name: string, image: string, repo: string, control: string, output: string, credential: string, egress?: Pick<Egress, "network" | "proxyUrl">): string[] {
|
|
201
|
+
// Docker --mount uses commas as delimiters; never reinterpret a host path as extra mount options.
|
|
202
|
+
if ([repo, control, output].some((p) => p.includes(","))) throw new Error("CLI isolation paths cannot contain commas");
|
|
203
|
+
|
|
204
|
+
return ["run", "--rm", "--pull=never", "--name", name, "--interactive", "--init", "--user", "1000:1000",
|
|
205
|
+
"--read-only", "--cap-drop=ALL", "--security-opt=no-new-privileges", "--pids-limit=256", "--memory=2g", "--cpus=2",
|
|
206
|
+
// No network at all, or the private network whose only route out is the egress proxy.
|
|
207
|
+
`--network=${egress?.network ?? "none"}`, "--ipc=private", "--workdir", CLI_ROOT,
|
|
208
|
+
"--tmpfs", "/tmp:rw,nosuid,nodev,size=256m,mode=1777",
|
|
209
|
+
"--tmpfs", "/home/node:rw,nosuid,nodev,size=64m,uid=1000,gid=1000,mode=700",
|
|
210
|
+
"--mount", `type=bind,src=${repo},dst=${CLI_ROOT},readonly`,
|
|
211
|
+
"--mount", `type=bind,src=${control},dst=${CLI_CONTROL},readonly`,
|
|
212
|
+
"--mount", `type=bind,src=${output},dst=/output`,
|
|
213
|
+
"--env", "HOME=/home/node", "--env", credential,
|
|
214
|
+
...(egress ? ["HTTPS_PROXY", "HTTP_PROXY", "https_proxy", "http_proxy"].flatMap((k) => ["--env", `${k}=${egress.proxyUrl}`]) : []),
|
|
215
|
+
"--env", "NO_PROXY=", "--env", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1",
|
|
216
|
+
"--entrypoint", "/usr/bin/env", image];
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** Container output is untrusted: never follow a planted symlink into The gate's filesystem. */
|
|
220
|
+
export function readCliVerdict(file: string): string {
|
|
221
|
+
const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
|
|
222
|
+
|
|
223
|
+
try {
|
|
224
|
+
const stat = fstatSync(fd);
|
|
225
|
+
|
|
226
|
+
if (!stat.isFile() || stat.size > 1 << 20) throw new Error("CLI verdict must be a regular file under 1 MiB");
|
|
227
|
+
|
|
228
|
+
return readFileSync(fd, "utf8");
|
|
229
|
+
} finally {
|
|
230
|
+
closeSync(fd);
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
export function isolatedCli(backend: "claude" | "codex", args: string[], options: { repoRoot: string; prompt: string; system: string; schema: string }) {
|
|
235
|
+
// codex exec reads its key from CODEX_API_KEY; OPENAI_API_KEY is accepted as the source so existing secrets work.
|
|
236
|
+
const credential = backend === "claude" ? "CLAUDE_CODE_OAUTH_TOKEN" : "CODEX_API_KEY";
|
|
237
|
+
const sources = backend === "claude" ? ["CLAUDE_CODE_OAUTH_TOKEN"] : ["CODEX_API_KEY", "OPENAI_API_KEY"];
|
|
238
|
+
const secret = sources.map((k) => process.env[k]).find(Boolean);
|
|
239
|
+
|
|
240
|
+
if (!secret) throw new Error(`${backend} isolation requires ${sources.join(" or ")}; host login directories are never mounted`);
|
|
241
|
+
|
|
242
|
+
const dir = mkdtempSync(path.join(tmpdir(), "gate-cli-"));
|
|
243
|
+
const id = randomUUID();
|
|
244
|
+
const name = `gate-${id}`;
|
|
245
|
+
const image = process.env.SHEPHERD_CLI_IMAGE || CLI_IMAGE;
|
|
246
|
+
const repo = path.join(dir, "repo");
|
|
247
|
+
const control = path.join(dir, "control");
|
|
248
|
+
const output = path.join(dir, "output");
|
|
249
|
+
// Docker needs runtime configuration on the client, but only the named --env value enters the container.
|
|
250
|
+
const env = { ...Object.fromEntries(Object.entries(process.env).filter(([k, v]) => v && /^(PATH|HOME|DOCKER_[A-Z_]+)$/.test(k))), [credential]: secret };
|
|
251
|
+
|
|
252
|
+
let egress: Egress | null = null;
|
|
253
|
+
|
|
254
|
+
try {
|
|
255
|
+
const context = path.join(dir, "context");
|
|
256
|
+
mkdirSync(context);
|
|
257
|
+
prepareCliImage(image, env, context);
|
|
258
|
+
cpSync(options.repoRoot, repo, { recursive: true, dereference: false, filter: (p) => path.basename(p) !== ".git" });
|
|
259
|
+
mkdirSync(control);
|
|
260
|
+
mkdirSync(output);
|
|
261
|
+
chmodSync(dir, 0o755);
|
|
262
|
+
chmodSync(output, 0o777);
|
|
263
|
+
writeFileSync(path.join(control, "schema.json"), options.schema);
|
|
264
|
+
writeFileSync(path.join(control, "instructions.md"), options.system);
|
|
265
|
+
|
|
266
|
+
egress = startEgress(id, image, EGRESS[backend], env);
|
|
267
|
+
|
|
268
|
+
const run = spawnSync("docker", [...containerArgs(name, image, repo, control, output, credential, egress), "timeout", "--signal=KILL", "900", backend, ...args], {
|
|
269
|
+
input: options.prompt, encoding: "utf8", env, maxBuffer: 64 << 20, timeout: 15 * 60_000,
|
|
270
|
+
});
|
|
271
|
+
|
|
272
|
+
if (run.error || run.status !== 0) throw new Error(`${backend} isolated review failed (${run.status ?? "launch"}); Docker and a trusted SHEPHERD_CLI_IMAGE are required. ${run.error?.message ?? run.stderr.slice(0, 500)}`);
|
|
273
|
+
|
|
274
|
+
return { stdout: run.stdout, verdict: backend === "codex" ? readCliVerdict(path.join(output, "verdict.json")) : null, egress: egressDecisions(egress.logs()) };
|
|
275
|
+
} finally {
|
|
276
|
+
// Killing the client on timeout does not necessarily stop its container.
|
|
277
|
+
spawnSync("docker", ["rm", "--force", name], { env, stdio: "ignore", timeout: 10_000 });
|
|
278
|
+
egress?.stop();
|
|
279
|
+
rmSync(dir, { recursive: true, force: true });
|
|
280
|
+
}
|
|
281
|
+
}
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
// Impact leads: where a change may reach beyond its diff. Changed exports and the files outside the PR that name
|
|
2
|
+
// them, and the test files that sit beside each changed source file. Advisory context only: a lead says where to
|
|
3
|
+
// look, it never stands in for reading the diff, and nothing here gates.
|
|
4
|
+
import { execFileSync } from "node:child_process";
|
|
5
|
+
import { callTimeout } from "./github.ts";
|
|
6
|
+
import { isSizeExempt, LOCKFILE_RE } from "./policy.ts";
|
|
7
|
+
|
|
8
|
+
export type Leads = {
|
|
9
|
+
/** An exported name the diff adds, removes or rewrites, and up to MAX_CALLERS files outside the PR that name it. */
|
|
10
|
+
symbols: { name: string; callers: string[] }[];
|
|
11
|
+
/** Changed source files with the test files that match their name; `tests` is empty when none does. */
|
|
12
|
+
sources: { file: string; tests: string[] }[];
|
|
13
|
+
/** Names only one side of the diff holds, and where the head uses them. */
|
|
14
|
+
names: NameLead[];
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
type At = { file: string; line: number };
|
|
18
|
+
|
|
19
|
+
/** A name whose count changed, however it is written: an env var, a config key, a private helper, a string constant. */
|
|
20
|
+
export type NameLead = { name: string; added: At | null; removed: At | null; count: number; refs: (At & { text: string })[] };
|
|
21
|
+
|
|
22
|
+
const MAX_SYMBOLS = 8;
|
|
23
|
+
|
|
24
|
+
const MAX_CALLERS = 5;
|
|
25
|
+
|
|
26
|
+
const MAX_SOURCES = 10;
|
|
27
|
+
|
|
28
|
+
// A declaration's name on a diff line: TS/JS exports, Python top-level defs and classes, Go exported funcs.
|
|
29
|
+
const DECLARATION = [
|
|
30
|
+
/^[+-]\s*export\s+(?:default\s+)?(?:declare\s+)?(?:async\s+)?(?:function\*?|const|let|var|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/,
|
|
31
|
+
/^[+-](?:def|class)\s+([A-Za-z_]\w*)/,
|
|
32
|
+
/^[+-]func\s+(?:\([^)]*\)\s*)?([A-Z]\w*)/,
|
|
33
|
+
];
|
|
34
|
+
|
|
35
|
+
const MAX_CANDIDATES = 24;
|
|
36
|
+
|
|
37
|
+
const MAX_NAMES = 12;
|
|
38
|
+
|
|
39
|
+
const MAX_REFS = 6;
|
|
40
|
+
|
|
41
|
+
const MAX_EXCERPT = 160;
|
|
42
|
+
|
|
43
|
+
// Lockfiles and tests churn names by the thousand. Name leads skip them; the reviewer still reads them as diff.
|
|
44
|
+
const noisy = (file: string) => isSizeExempt(file) || LOCKFILE_RE.test(file);
|
|
45
|
+
|
|
46
|
+
const SOURCE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb)$/;
|
|
47
|
+
|
|
48
|
+
const TEST_FILE = /(^|\/)(__tests__\/|tests?\/)|[._-](test|spec)\.[^/]+$|(^|\/)test_[^/]+\.py$|_test\.go$/;
|
|
49
|
+
|
|
50
|
+
/** The names the diff's hunk lines declare, in order of first appearance, at most MAX_SYMBOLS. */
|
|
51
|
+
export function changedSymbols(diff: string): string[] {
|
|
52
|
+
const names = new Set<string>();
|
|
53
|
+
let inHunk = false;
|
|
54
|
+
|
|
55
|
+
for (const l of diff.split("\n")) {
|
|
56
|
+
if (l.startsWith("diff --git ")) inHunk = false;
|
|
57
|
+
else if (l.startsWith("@@")) inHunk = true;
|
|
58
|
+
else if (inHunk)
|
|
59
|
+
for (const re of DECLARATION) {
|
|
60
|
+
const name = re.exec(l)?.[1];
|
|
61
|
+
|
|
62
|
+
if (name && name.length > 2) names.add(name);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
return [...names].slice(0, MAX_SYMBOLS);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
type Change = { name: string; declared: boolean; added: At[]; removed: At[] };
|
|
70
|
+
|
|
71
|
+
const DECLARES = /\b(?:const|let|var|function|class|type|interface|enum|def|func|fn|struct)\s+([A-Za-z_]\w*)/g;
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Names only one side of the diff holds, removed ones first, then declarations: a renamed or removed name
|
|
75
|
+
* leaves references behind that the diff cannot show. A name with a capital or underscore only: plain words are prose.
|
|
76
|
+
* `addedLines` holds `path:line` of every line the PR added.
|
|
77
|
+
*/
|
|
78
|
+
export function changedNames(diff: string) {
|
|
79
|
+
const changes = new Map<string, Change>();
|
|
80
|
+
const addedLines = new Set<string>();
|
|
81
|
+
let oldPath = "";
|
|
82
|
+
let newPath = "";
|
|
83
|
+
let oldLine = 0;
|
|
84
|
+
let newLine = 0;
|
|
85
|
+
let oldLeft = 0;
|
|
86
|
+
let newLeft = 0;
|
|
87
|
+
|
|
88
|
+
const record = (text: string, kind: "added" | "removed", at: At) => {
|
|
89
|
+
const declared = new Set([...text.matchAll(DECLARES)].map((m) => m[1]));
|
|
90
|
+
|
|
91
|
+
for (const name of new Set(text.match(/[A-Za-z_]\w*/g))) {
|
|
92
|
+
if (name.length < 4 || name.length > 128 || !/[A-Z_]/.test(name)) continue;
|
|
93
|
+
const c = changes.get(name) ?? { name, declared: false, added: [], removed: [] };
|
|
94
|
+
|
|
95
|
+
c.declared ||= declared.has(name);
|
|
96
|
+
c[kind].push(at);
|
|
97
|
+
changes.set(name, c);
|
|
98
|
+
}
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
for (const l of diff.split("\n")) {
|
|
102
|
+
// A hunk's own counts decide where it ends, so an added line reading `+++ x` stays an added line.
|
|
103
|
+
if (oldLeft > 0 || newLeft > 0) {
|
|
104
|
+
if (l[0] === "+") {
|
|
105
|
+
addedLines.add(`${newPath}:${newLine}`);
|
|
106
|
+
|
|
107
|
+
if (!noisy(newPath)) record(l.slice(1), "added", { file: newPath, line: newLine });
|
|
108
|
+
newLine++;
|
|
109
|
+
newLeft--;
|
|
110
|
+
} else if (l[0] === "-") {
|
|
111
|
+
if (!noisy(oldPath)) record(l.slice(1), "removed", { file: oldPath, line: oldLine });
|
|
112
|
+
oldLine++;
|
|
113
|
+
oldLeft--;
|
|
114
|
+
} else if (l[0] !== "\\") {
|
|
115
|
+
oldLine++;
|
|
116
|
+
newLine++;
|
|
117
|
+
oldLeft--;
|
|
118
|
+
newLeft--;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
const hunk = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(l);
|
|
125
|
+
|
|
126
|
+
if (hunk) {
|
|
127
|
+
oldLine = Number(hunk[1]);
|
|
128
|
+
oldLeft = Number(hunk[2] ?? 1);
|
|
129
|
+
newLine = Number(hunk[3]);
|
|
130
|
+
newLeft = Number(hunk[4] ?? 1);
|
|
131
|
+
} else if (l.startsWith("--- ")) oldPath = l.slice(4).replace(/^a\//, "").replace(/\t$/, "");
|
|
132
|
+
else if (l.startsWith("+++ ")) newPath = l.slice(4).replace(/^b\//, "").replace(/\t$/, "");
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const rank = (a: Change, b: Change) => Number(b.removed.length > 0) - Number(a.removed.length > 0) || Number(b.declared) - Number(a.declared) || a.name.localeCompare(b.name);
|
|
136
|
+
|
|
137
|
+
// A rename leaves its old name on one side and its new name on the other. Removed names rank first.
|
|
138
|
+
return { candidates: [...changes.values()].filter((c) => !c.added.length || !c.removed.length).sort(rank).slice(0, MAX_CANDIDATES), addedLines };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** `git grep -nz` output over the candidates: each name's lines outside the PR's added ones, a few kept with their text. */
|
|
142
|
+
export function nameLeads(candidates: Change[], addedLines: Set<string>, grep: string): NameLead[] {
|
|
143
|
+
const lead = (c: Change): NameLead => ({ name: c.name, added: c.added[0] ?? null, removed: c.removed[0] ?? null, count: 0, refs: [] });
|
|
144
|
+
const leads = new Map(candidates.map((c) => [c.name, lead(c)]));
|
|
145
|
+
|
|
146
|
+
for (const record of grep.split("\n")) {
|
|
147
|
+
const [file, n, text] = record.split("\0");
|
|
148
|
+
const line = Number(n);
|
|
149
|
+
|
|
150
|
+
if (!file || !Number.isInteger(line) || text === undefined || addedLines.has(`${file}:${line}`)) continue;
|
|
151
|
+
|
|
152
|
+
for (const word of new Set(text.match(/[A-Za-z_][A-Za-z0-9_]*/g))) {
|
|
153
|
+
const hit = leads.get(word);
|
|
154
|
+
|
|
155
|
+
if (!hit) continue;
|
|
156
|
+
hit.count++;
|
|
157
|
+
|
|
158
|
+
if (hit.refs.length < MAX_REFS) hit.refs.push({ file, line, text: text.trim().slice(0, MAX_EXCERPT) });
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
return [...leads.values()].filter((l) => l.count > 0).slice(0, MAX_NAMES);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** A file's language, so a TypeScript source never claims a Go test: JS and TS share one, any other extension is its own. */
|
|
166
|
+
const family = (f: string) => {
|
|
167
|
+
const ext = /\.([^./]+)$/.exec(f)?.[1] ?? "";
|
|
168
|
+
|
|
169
|
+
return /^[cm]?[jt]sx?$/.test(ext) ? "js" : ext;
|
|
170
|
+
};
|
|
171
|
+
|
|
172
|
+
/** Tracked test files whose name matches the source file's stem: `a.ts` → `a.test.ts`, `__tests__/a.ts`, `test_a.py`, `a_test.go`. */
|
|
173
|
+
export function relatedTests(file: string, tracked: string[]): string[] {
|
|
174
|
+
const stem = file.split("/").at(-1)!.replace(/\.[^.]+$/, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
175
|
+
const named = new RegExp(`(^|/)(test_)?${stem}([._-](test|spec))?\\.[^/]+$|(^|/)${stem}_test\\.go$`);
|
|
176
|
+
|
|
177
|
+
const lang = family(file);
|
|
178
|
+
|
|
179
|
+
return tracked.filter((t) => t !== file && TEST_FILE.test(t) && named.test(t) && family(t) === lang);
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export type LeadDeps = {
|
|
183
|
+
/** Tracked files, `git ls-files`. */
|
|
184
|
+
tracked: () => string[];
|
|
185
|
+
/** Tracked files naming `word` as a whole word, `git grep -lw`. */
|
|
186
|
+
naming: (word: string) => string[];
|
|
187
|
+
/** Every tracked line matching `pattern` as a whole word, `git grep -nz`; "" when git cannot answer. */
|
|
188
|
+
lines: (pattern: string) => string;
|
|
189
|
+
};
|
|
190
|
+
|
|
191
|
+
export function impactLeads(diff: string, changed: string[], deps: LeadDeps): Leads {
|
|
192
|
+
const inPR = new Set(changed);
|
|
193
|
+
const tracked = deps.tracked();
|
|
194
|
+
const exported = changedSymbols(diff);
|
|
195
|
+
const { candidates, addedLines } = changedNames(diff);
|
|
196
|
+
// An exported name is listed with its callers already.
|
|
197
|
+
const others = candidates.filter((c) => !exported.includes(c.name));
|
|
198
|
+
|
|
199
|
+
return {
|
|
200
|
+
names: others.length ? nameLeads(others, addedLines, deps.lines(others.map((c) => c.name).join("|"))) : [],
|
|
201
|
+
// A caller is code: a doc or changelog that mentions the name is not one.
|
|
202
|
+
symbols: exported.map((name) => ({ name, callers: deps.naming(name).filter((f) => !inPR.has(f) && SOURCE.test(f)).slice(0, MAX_CALLERS) })),
|
|
203
|
+
sources: changed
|
|
204
|
+
.filter((f) => !TEST_FILE.test(f) && SOURCE.test(f))
|
|
205
|
+
.slice(0, MAX_SOURCES)
|
|
206
|
+
.map((file) => ({ file, tests: relatedTests(file, tracked).slice(0, 3) })),
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** Leads over a checkout, through git: no PR code runs. Null when git fails, so the prompt simply goes without. */
|
|
211
|
+
export function leadsAt(root: string, diff: string, changed: string[]): Leads | null {
|
|
212
|
+
const git = (...args: string[]) => {
|
|
213
|
+
try {
|
|
214
|
+
return execFileSync("git", ["-C", root, ...args], { encoding: "utf8", maxBuffer: 16 << 20, timeout: callTimeout(), stdio: ["ignore", "pipe", "ignore"] });
|
|
215
|
+
} catch (e) {
|
|
216
|
+
// git grep exits 1 for "no matches", which is an answer.
|
|
217
|
+
if (e instanceof Error && "status" in e && e.status === 1) return "";
|
|
218
|
+
throw e;
|
|
219
|
+
}
|
|
220
|
+
};
|
|
221
|
+
|
|
222
|
+
// -z: paths as they are, NUL-separated. Without it git quotes a path holding a tab, a quote or non-ASCII bytes
|
|
223
|
+
// (`"src/caf\303\251.ts"`), and the quoted name matches neither the PR's files nor a test's.
|
|
224
|
+
const paths = (s: string) => s.split("\0").filter(Boolean);
|
|
225
|
+
|
|
226
|
+
// One alternation keeps the grep linear: with an `-e` per name, git rescans each pattern after a match. Names are
|
|
227
|
+
// word characters, so they need no escaping.
|
|
228
|
+
const lines = (pattern: string) => {
|
|
229
|
+
try {
|
|
230
|
+
return git("grep", "--no-color", "--full-name", "-nzIwE", "-e", pattern);
|
|
231
|
+
} catch {
|
|
232
|
+
return "";
|
|
233
|
+
}
|
|
234
|
+
};
|
|
235
|
+
|
|
236
|
+
try {
|
|
237
|
+
return impactLeads(diff, changed, { tracked: () => paths(git("ls-files", "-z")), naming: (w) => paths(git("grep", "-lwFz", "--", w)), lines });
|
|
238
|
+
} catch {
|
|
239
|
+
return null;
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** The leads for the prompt: one line each, untrusted names passed through `clean` by the caller. */
|
|
244
|
+
export function formatLeads(leads: Leads, clean: (s: string) => string): string[] {
|
|
245
|
+
const symbols = leads.symbols.map((s) => `${clean(s.name)}: ${s.callers.length ? `named in ${s.callers.map(clean).join(", ")}` : "named nowhere outside this PR"}`);
|
|
246
|
+
const sources = leads.sources.map((s) => `${clean(s.file)}: ${s.tests.length ? `tests in ${s.tests.map(clean).join(", ")}` : "no test file matches its name"}`);
|
|
247
|
+
|
|
248
|
+
const at = (a: At) => `${clean(a.file)}:${a.line}`;
|
|
249
|
+
|
|
250
|
+
const names = leads.names.map((n) => {
|
|
251
|
+
const changed = [n.removed && `removed at ${at(n.removed)}`, n.added && `added at ${at(n.added)}`].filter(Boolean).join(", ");
|
|
252
|
+
|
|
253
|
+
return `${clean(n.name)}: ${changed}; ${n.count} line(s) in the head use it${n.count > n.refs.length ? `, first ${n.refs.length}` : ""}: ${n.refs.map((r) => `${at(r)} ${JSON.stringify(clean(r.text))}`).join("; ")}`;
|
|
254
|
+
});
|
|
255
|
+
|
|
256
|
+
return [...symbols, ...names, ...sources];
|
|
257
|
+
}
|