rungate 0.8.6 → 0.8.8
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/gates/.gate-salt +1 -1
- package/lib/ai-review-rounds.ts +121 -1
- package/lib/ai-review-suppression.ts +80 -127
- package/lib/ai-review-threads.ts +296 -0
- package/lib/cli-commands.ts +21 -0
- package/lib/github.ts +25 -0
- package/lib/prose-self-distance.ts +414 -0
- package/lib/review-tool-agreement.ts +364 -15
- package/lib/scaffold/ai-review-findings.ts +167 -0
- package/lib/scaffold/ai-review-step.ts +454 -34
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +12 -17
- package/scripts/ai-review-threads.ts +211 -0
|
@@ -43,12 +43,22 @@
|
|
|
43
43
|
*
|
|
44
44
|
* ## Scope, stated rather than implied
|
|
45
45
|
*
|
|
46
|
-
* No
|
|
47
|
-
* a reason to add a fifth to a published package — the same decision
|
|
48
|
-
* `test/claude-review-no-key.test.ts` records.
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
*
|
|
46
|
+
* No ADDED dependency. This repo ships four runtime dependencies and a guard
|
|
47
|
+
* is not a reason to add a fifth to a published package — the same decision
|
|
48
|
+
* `test/claude-review-no-key.test.ts` records.
|
|
49
|
+
*
|
|
50
|
+
* That rule is about the dependency list, not about parsing, and this
|
|
51
|
+
* paragraph used to say "no YAML parser" as though the two were the same
|
|
52
|
+
* thing. They are not: `triggerNames` parses the workflow with `Bun.YAML`,
|
|
53
|
+
* which is built into the runtime and adds nothing to `package.json`. Six
|
|
54
|
+
* revisions of hand-rolled trigger matching shipped two fail-open holes
|
|
55
|
+
* before that distinction was drawn (#1614), so it is drawn here explicitly
|
|
56
|
+
* — if a real parser is reachable without a dependency, use it.
|
|
57
|
+
*
|
|
58
|
+
* Everything else here is a cut and a regex over the cut, and every cut
|
|
59
|
+
* refuses by name when it cannot find its region, because a slice that
|
|
60
|
+
* missed its section is an empty string and an empty string satisfies every
|
|
61
|
+
* claim of the form "X is not in here".
|
|
52
62
|
*/
|
|
53
63
|
|
|
54
64
|
import { structuralCut } from "./source-slice";
|
|
@@ -60,6 +70,9 @@ export type ReviewToolViolationKind =
|
|
|
60
70
|
| "PROMPT_NAMES_A_DENIED_TOOL"
|
|
61
71
|
| "PROMPT_NAMES_AN_UNGRANTED_TOOL"
|
|
62
72
|
| "ALLOWED_TOOL_CANNOT_EXIST_ON_THIS_TRIGGER"
|
|
73
|
+
| "ENTITY_TRIGGER_WITHOUT_A_FORK_GUARD"
|
|
74
|
+
| "PULL_REQUEST_TARGET_TRIGGER"
|
|
75
|
+
| "TRIGGERS_UNMEASURED"
|
|
63
76
|
| "NO_POSTING_TOOL_IS_ALLOWED"
|
|
64
77
|
| "NO_SUBJECT_REACHES_THE_AGENT"
|
|
65
78
|
| "MUTABLE_PLUGIN_MARKETPLACE"
|
|
@@ -100,6 +113,226 @@ export const AUTOMATION_ONLY_TRIGGERS = [
|
|
|
100
113
|
"workflow_run",
|
|
101
114
|
] as const;
|
|
102
115
|
|
|
116
|
+
/**
|
|
117
|
+
* Triggers that fire on somebody else's pull request, so the job sees a diff
|
|
118
|
+
* written by a person who is not a collaborator (#631/#675).
|
|
119
|
+
*
|
|
120
|
+
* `pull_request_target` is here as a trigger to REFUSE, not one to guard. It
|
|
121
|
+
* runs the base branch's workflow definition with a full write token against
|
|
122
|
+
* the fork's code, which is this workflow's egress sink with the credential
|
|
123
|
+
* handed over on purpose. There is no condition that makes it safe for a job
|
|
124
|
+
* that runs an agent, so it gets its own violation rather than a guard.
|
|
125
|
+
*/
|
|
126
|
+
export const ENTITY_TRIGGERS = ["pull_request", "pull_request_target"] as const;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* The trigger names a workflow declares, parsed as YAML.
|
|
130
|
+
*
|
|
131
|
+
* **This was hand-rolled text matching and it should not have been.** Six
|
|
132
|
+
* revisions on #1614, each correct for the case it was shown and wrong for
|
|
133
|
+
* the next one, and the reviewer's round-cap assessment on round 13 named
|
|
134
|
+
* the class rather than the instance: *hand-rolled regex parsing of the
|
|
135
|
+
* `on:` block, patched edge case by edge case*. It was right, so the
|
|
136
|
+
* instrument changed instead of the pattern. What the six revisions cost:
|
|
137
|
+
*
|
|
138
|
+
* two-space-only every other spelling read as `[]`, which made the
|
|
139
|
+
* callers SILENT. `on: {pull_request_target: }` passed
|
|
140
|
+
* — a WRITE token on a fork's pull request
|
|
141
|
+
* any-indentation any indentation is any DEPTH, so every field of the
|
|
142
|
+
* `workflow_dispatch.inputs` schema read as a trigger
|
|
143
|
+
* outermost-depth correct for block and flow style, and still blind to
|
|
144
|
+
* a YAML merge key, a list form and a scalar form
|
|
145
|
+
*
|
|
146
|
+
* `Bun.YAML` is built in, so this costs no dependency, and it answers all
|
|
147
|
+
* three plus the forms nobody had thought to ask about:
|
|
148
|
+
*
|
|
149
|
+
* on: {pull_request_target: } flow
|
|
150
|
+
* on:\n pull_request_target: four-space
|
|
151
|
+
* on:\n <<: *anchor merge key, resolved
|
|
152
|
+
* on: [push, pull_request_target] list
|
|
153
|
+
* on: pull_request_target scalar
|
|
154
|
+
*
|
|
155
|
+
* The refusal stays and is still load-bearing: a source that will not parse,
|
|
156
|
+
* or declares no `on`, yields `[]` and the caller reports
|
|
157
|
+
* `TRIGGERS_UNMEASURED`. A reading that could not be taken is never a clean
|
|
158
|
+
* one — and that is now the ONLY way this returns empty, because the parser
|
|
159
|
+
* no longer has spellings it cannot see.
|
|
160
|
+
*/
|
|
161
|
+
export function triggerNames(source: string): string[] {
|
|
162
|
+
let doc: unknown;
|
|
163
|
+
try {
|
|
164
|
+
doc = (Bun as unknown as { YAML: { parse(s: string): unknown } }).YAML.parse(source);
|
|
165
|
+
} catch {
|
|
166
|
+
// A workflow that is not YAML has no readable triggers. UNMEASURED, and
|
|
167
|
+
// never a silent pass — the caller turns `[]` into a reported refusal.
|
|
168
|
+
return [];
|
|
169
|
+
}
|
|
170
|
+
if (doc === null || typeof doc !== "object") return [];
|
|
171
|
+
// YAML 1.1 resolves a bare `on` to the boolean true, and parsers differ on
|
|
172
|
+
// whether the key survives as "on" or "true". Read both rather than
|
|
173
|
+
// depending on which one this runtime picked.
|
|
174
|
+
const rec = doc as Record<string, unknown>;
|
|
175
|
+
const on = rec.on ?? rec["true"];
|
|
176
|
+
if (typeof on === "string") return [on];
|
|
177
|
+
if (Array.isArray(on)) return on.filter((t): t is string => typeof t === "string");
|
|
178
|
+
if (on !== null && typeof on === "object") return Object.keys(on as object);
|
|
179
|
+
return [];
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* The two expressions a job-level condition needs to compare before it can be
|
|
184
|
+
* said to refuse a fork. Spelled out so the check names what is missing rather
|
|
185
|
+
* than reporting that an `if:` "looks wrong".
|
|
186
|
+
*/
|
|
187
|
+
export const FORK_GUARD_TERMS = [
|
|
188
|
+
"github.event.pull_request.head.repo.full_name",
|
|
189
|
+
"github.repository",
|
|
190
|
+
] as const;
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* The comparison itself, in either operand order, with `==` and not `!=`.
|
|
194
|
+
*
|
|
195
|
+
* An earlier revision of this check asked only whether both `FORK_GUARD_TERMS`
|
|
196
|
+
* appeared anywhere in the job header, and said so in a comment: "this cannot
|
|
197
|
+
* tell `==` from `!=`". **The reviewer this module exists to make work caught
|
|
198
|
+
* that on the pull request that promoted the trigger**, and it was right —
|
|
199
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, fifth shape. An inverted
|
|
200
|
+
* guard contains both terms, passes a presence check, and runs the job on
|
|
201
|
+
* forks ONLY, which is the precise opposite of the property the check is
|
|
202
|
+
* named after. A check satisfied by a dangerously backwards version of its
|
|
203
|
+
* own subject is worse than no check: it certifies the regression.
|
|
204
|
+
*
|
|
205
|
+
* It is also read from the `if:` block rather than the whole job header, for
|
|
206
|
+
* the same reason every other cut here is bounded — a `name:` or an `env:`
|
|
207
|
+
* value carrying both substrings would otherwise satisfy it.
|
|
208
|
+
*/
|
|
209
|
+
export const FORK_GUARD_COMPARISON =
|
|
210
|
+
/^(?:github\.event\.pull_request\.head\.repo\.full_name\s*==\s*github\.repository|github\.repository\s*==\s*github\.event\.pull_request\.head\.repo\.full_name)$/;
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* The only other thing a disjunct of this condition is allowed to be: a guard
|
|
214
|
+
* naming the event, which is how the dispatch arm earns its place beside the
|
|
215
|
+
* fork comparison.
|
|
216
|
+
*/
|
|
217
|
+
export const FORK_GUARD_COMPANION_EVENTS = ["workflow_dispatch", "schedule"] as const;
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* And the event it names must be one that CANNOT carry a fork's head.
|
|
221
|
+
*
|
|
222
|
+
* The first spelling of this was `'[a-z_]+'` — any event at all — and the
|
|
223
|
+
* reviewer caught it, the third real finding about this one guard:
|
|
224
|
+
*
|
|
225
|
+
* if: >-
|
|
226
|
+
* github.event_name == 'pull_request' ||
|
|
227
|
+
* github.event.pull_request.head.repo.full_name == github.repository
|
|
228
|
+
*
|
|
229
|
+
* On a fork's pull request the FIRST arm is true, so the job runs and the
|
|
230
|
+
* comparison beside it decides nothing. That is the bypass `forkGuardDefect`
|
|
231
|
+
* was written to close, reopened by the escape hatch added to let the live
|
|
232
|
+
* file's dispatch arm through.
|
|
233
|
+
*
|
|
234
|
+
* `FORK_GUARD_COMPANION_EVENTS` is the closed set, and the membership test is
|
|
235
|
+
* what the event has in common: no `github.event.pull_request` context at
|
|
236
|
+
* all, so the fork comparison cannot be the predicate for it and a separate
|
|
237
|
+
* arm is the only way to express the case. `pull_request` and
|
|
238
|
+
* `pull_request_target` are excluded by construction rather than by being
|
|
239
|
+
* listed as denied — an allowlist cannot be widened by forgetting a denial.
|
|
240
|
+
*/
|
|
241
|
+
export const FORK_GUARD_COMPANION_ARM = new RegExp(
|
|
242
|
+
`^github\\.event_name\\s*==\\s*'(?:${FORK_GUARD_COMPANION_EVENTS.join("|")})'$`,
|
|
243
|
+
);
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* Why an ANCHORED per-disjunct test and not a substring search.
|
|
247
|
+
*
|
|
248
|
+
* The previous revision of this check asked whether `FORK_GUARD_COMPARISON`
|
|
249
|
+
* matched anywhere in the condition. **The reviewer caught that too** — the
|
|
250
|
+
* second time on the same pull request, and the same shape as the `!=`
|
|
251
|
+
* inversion it had already caught once. A substring search is satisfied by a
|
|
252
|
+
* condition that contains the correct comparison and then neutralises it:
|
|
253
|
+
*
|
|
254
|
+
* if: >-
|
|
255
|
+
* true ||
|
|
256
|
+
* github.event.pull_request.head.repo.full_name == github.repository
|
|
257
|
+
*
|
|
258
|
+
* if: >-
|
|
259
|
+
* !(github.event.pull_request.head.repo.full_name == github.repository)
|
|
260
|
+
*
|
|
261
|
+
* Both contain `A == B`. The first runs on every fork; the second runs on
|
|
262
|
+
* forks ONLY. So the fix is not a better regex for the comparison — it is
|
|
263
|
+
* asking a different question: **is that comparison the governing predicate?**
|
|
264
|
+
*
|
|
265
|
+
* The condition is split on `||` and every arm must be either the fork
|
|
266
|
+
* comparison itself or `FORK_GUARD_COMPANION_ARM`. `true`, `always()` and a
|
|
267
|
+
* parenthesised negation are all arms that match neither, so each is named
|
|
268
|
+
* rather than tolerated.
|
|
269
|
+
*
|
|
270
|
+
* **Both patterns are anchored, so each accepts exactly ONE spelling of its
|
|
271
|
+
* arm and refuses every equivalent rewrite.** Say what is tolerated rather
|
|
272
|
+
* than listing what is not, because the list of rewrites is open and the
|
|
273
|
+
* tolerance is closed. Measured, not inferred:
|
|
274
|
+
*
|
|
275
|
+
* clean github.event_name == 'workflow_dispatch' || <fork comparison>
|
|
276
|
+
* clean extra inner whitespace around either `==`
|
|
277
|
+
* clean the fork comparison with its operands reversed
|
|
278
|
+
* FLAGGED (github.event_name == 'workflow_dispatch') || (<fork comparison>)
|
|
279
|
+
* FLAGGED github.event_name == "workflow_dispatch" || <fork comparison>
|
|
280
|
+
* FLAGGED github.event_name == 'workflow_dispatch' && github.actor == 'x'
|
|
281
|
+
*
|
|
282
|
+
* Whitespace and operand order are the whole of the tolerance. A
|
|
283
|
+
* parenthesised arm, a double-quoted event name and a narrowing `&&` are all
|
|
284
|
+
* refused, and all three are SAFE conditions — the `&&` one runs on a strict
|
|
285
|
+
* subset of what the bare arm runs on. So these are false positives, never
|
|
286
|
+
* bypasses: the direction `.claude/rules/checks-must-be-able-to-fail.md`
|
|
287
|
+
* says to be wrong in. The cost is a confusing refusal for somebody writing
|
|
288
|
+
* a legitimate variant; the cost of the other direction is deciding whether
|
|
289
|
+
* an arbitrary rewrite narrows or widens, which means evaluating GitHub's
|
|
290
|
+
* expression language, and a guard that reasons about what it cannot
|
|
291
|
+
* evaluate is the substring search this function replaced.
|
|
292
|
+
*
|
|
293
|
+
* AC-26 in `test/claude-review-executable-prompt.test.ts` holds every row of
|
|
294
|
+
* that table. Two successive revisions of this comment got it wrong and
|
|
295
|
+
* nothing contradicted either: the first claimed a narrowing `&&` was
|
|
296
|
+
* tolerated (#1614, round 8), and the fix for that named `&&` alone while
|
|
297
|
+
* parens and double quotes behaved identically (#1614, round 9). The table
|
|
298
|
+
* is stated as a tolerance precisely so the next equivalent spelling nobody
|
|
299
|
+
* has thought of is already covered by it.
|
|
300
|
+
*
|
|
301
|
+
* This is deliberately a CLOSED set. Widening it is how the check dies: the
|
|
302
|
+
* next arm somebody wants is likelier to be the bypass than the exception,
|
|
303
|
+
* and an allowlist that grows on request is a substring search with extra
|
|
304
|
+
* steps.
|
|
305
|
+
*/
|
|
306
|
+
export function forkGuardDefect(condition: string): string | null {
|
|
307
|
+
const flat = condition
|
|
308
|
+
.replace(/^\s*if:\s*(?:[>|][-+]?)?/, " ")
|
|
309
|
+
.replace(/\s+/g, " ")
|
|
310
|
+
.trim();
|
|
311
|
+
if (flat === "") return "the job has no `if:` condition at all";
|
|
312
|
+
const arms = flat.split("||").map(a => a.trim());
|
|
313
|
+
if (!arms.some(a => FORK_GUARD_COMPARISON.test(a))) {
|
|
314
|
+
return (
|
|
315
|
+
"the job's condition mentions both terms but no `||` arm of it IS the " +
|
|
316
|
+
"comparison — a comparison wrapped in a negation, or buried inside a " +
|
|
317
|
+
"larger expression, is not the predicate that decides whether the job runs"
|
|
318
|
+
);
|
|
319
|
+
}
|
|
320
|
+
const stray = arms.filter(
|
|
321
|
+
a => !FORK_GUARD_COMPARISON.test(a) && !FORK_GUARD_COMPANION_ARM.test(a),
|
|
322
|
+
);
|
|
323
|
+
if (stray.length > 0) {
|
|
324
|
+
return (
|
|
325
|
+
`the job's condition compares the two terms, but it is one arm of a ` +
|
|
326
|
+
`disjunction whose other arm is ${stray.map(a => `\`${a}\``).join(", ")} — ` +
|
|
327
|
+
`an arm that can be true on a fork makes the comparison beside it decide ` +
|
|
328
|
+
`nothing. The only arm that may sit beside it is ` +
|
|
329
|
+
`\`github.event_name == '<e>'\` for e in ${FORK_GUARD_COMPANION_EVENTS.join(", ")} — ` +
|
|
330
|
+
`events that carry no pull_request context, so the comparison cannot serve them`
|
|
331
|
+
);
|
|
332
|
+
}
|
|
333
|
+
return null;
|
|
334
|
+
}
|
|
335
|
+
|
|
103
336
|
/**
|
|
104
337
|
* Tools that can put a human-readable finding on a pull request. The property
|
|
105
338
|
* AC-4 needs is "a comment naming the defect appears", so this is the set the
|
|
@@ -261,11 +494,18 @@ function quotedListAfter(claudeArgs: string, flag: string): string[] | null {
|
|
|
261
494
|
*/
|
|
262
495
|
export function reviewWorkflowRegions(source: string): {
|
|
263
496
|
triggerBlock: string;
|
|
497
|
+
jobHeader: string;
|
|
264
498
|
reviewStep: string;
|
|
265
499
|
prompt: string;
|
|
266
500
|
claudeArgs: string;
|
|
267
501
|
} {
|
|
268
502
|
const triggerBlock = structuralCut(source, "\non:", { endAnchor: "\npermissions:" });
|
|
503
|
+
// Everything the job declares ABOUT itself — `runs-on`, `timeout-minutes`,
|
|
504
|
+
// `if:` — and none of what it runs. Cut separately from the steps because a
|
|
505
|
+
// job-level condition is the only place the fork decision for an entity
|
|
506
|
+
// trigger can live, and searching the whole document for it would be
|
|
507
|
+
// satisfied by this file's own header discussing it.
|
|
508
|
+
const jobHeader = structuralCut(source, "\njobs:", { endAnchor: "\n steps:" });
|
|
269
509
|
const reviewStep = blockUnder(source, "- name: Review");
|
|
270
510
|
|
|
271
511
|
// The prompt is a YAML block scalar: `prompt: |` and everything indented
|
|
@@ -279,7 +519,7 @@ export function reviewWorkflowRegions(source: string): {
|
|
|
279
519
|
|
|
280
520
|
const claudeArgs = blockUnder(reviewStep, "claude_args:");
|
|
281
521
|
|
|
282
|
-
return { triggerBlock, reviewStep, prompt, claudeArgs };
|
|
522
|
+
return { triggerBlock, jobHeader, reviewStep, prompt, claudeArgs };
|
|
283
523
|
}
|
|
284
524
|
|
|
285
525
|
/**
|
|
@@ -289,7 +529,8 @@ export function reviewWorkflowRegions(source: string): {
|
|
|
289
529
|
* cannot accidentally ask the question of the wrong slice.
|
|
290
530
|
*/
|
|
291
531
|
export function reviewToolAgreement(source: string): ReviewToolViolation[] {
|
|
292
|
-
const { triggerBlock, reviewStep, prompt, claudeArgs } =
|
|
532
|
+
const { triggerBlock, jobHeader, reviewStep, prompt, claudeArgs } =
|
|
533
|
+
reviewWorkflowRegions(source);
|
|
293
534
|
|
|
294
535
|
const allowed = quotedListAfter(claudeArgs, "allowedTools") ?? [];
|
|
295
536
|
const denied = quotedListAfter(claudeArgs, "disallowedTools") ?? [];
|
|
@@ -335,11 +576,58 @@ export function reviewToolAgreement(source: string): ReviewToolViolation[] {
|
|
|
335
576
|
|
|
336
577
|
// 3. The door nothing in the prompt can show: a grant whose server the
|
|
337
578
|
// pinned action never starts under this workflow's triggers.
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
579
|
+
//
|
|
580
|
+
// PER-TRIGGER, not over the intersection. The first revision asked
|
|
581
|
+
// whether EVERY trigger was automation-only, which was the same question
|
|
582
|
+
// while this file had exactly one trigger — and silently became a weaker
|
|
583
|
+
// one when #631/#675 added `pull_request` beside `workflow_dispatch`.
|
|
584
|
+
// **The reviewer caught that too, on the pull request that made the
|
|
585
|
+
// change**: with a mixed trigger set the check went silent, even though
|
|
586
|
+
// a `workflow_dispatch` run of the same job still gets the automation
|
|
587
|
+
// classification and still has no entity-only server. A grant that works
|
|
588
|
+
// on one of two triggers is #732 reintroduced for the other one, and the
|
|
589
|
+
// property degraded from "never exists" to "does not exist on the
|
|
590
|
+
// intersection of all triggers" without the name or the comment moving.
|
|
591
|
+
// HOW THE TRIGGER NAMES ARE READ, and why an empty reading REFUSES
|
|
592
|
+
// (#1614, round 10). The first spelling of this was
|
|
593
|
+
// `/^\s{2}([a-z_]+):/gm` — exactly two leading spaces, block style only.
|
|
594
|
+
// Every other valid YAML spelling of the same trigger set returned `[]`,
|
|
595
|
+
// and `[]` made BOTH checks below silent rather than loud. Measured on
|
|
596
|
+
// the live file with only the `on:` block swapped:
|
|
597
|
+
//
|
|
598
|
+
// on:\n pull_request_target: → ["pull_request_target"], caught
|
|
599
|
+
// on: {pull_request_target: } → [], SILENT
|
|
600
|
+
// on:\n pull_request_target: → [], SILENT
|
|
601
|
+
//
|
|
602
|
+
// A workflow granting a write token on a fork's pull request therefore
|
|
603
|
+
// passed, which is the fail-open shape
|
|
604
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` calls *a detector
|
|
605
|
+
// narrower than what it detects*.
|
|
606
|
+
//
|
|
607
|
+
// Two changes, and the second is the load-bearing one. Widening the
|
|
608
|
+
// pattern closes the spellings we thought of; refusing an EMPTY reading
|
|
609
|
+
// closes the ones we did not. The set of valid YAML spellings is open
|
|
610
|
+
// and the set of things this function can parse is closed, so the only
|
|
611
|
+
// safe thing to do with a block it cannot read is say so — an absent
|
|
612
|
+
// reading is UNMEASURED, never a clean one.
|
|
613
|
+
const triggers = triggerNames(source);
|
|
614
|
+
if (triggers.length === 0) {
|
|
615
|
+
v.push({
|
|
616
|
+
kind: "TRIGGERS_UNMEASURED",
|
|
617
|
+
detail:
|
|
618
|
+
"the `on:` block was found but no trigger name could be read out of it, so the " +
|
|
619
|
+
"pull_request_target and fork-guard checks below have nothing to decide on. That is " +
|
|
620
|
+
"UNMEASURED, not clean: a workflow with no readable triggers is one this check cannot " +
|
|
621
|
+
"speak about. Either the block uses a YAML spelling `triggerNames` does not cover — " +
|
|
622
|
+
"teach it that spelling and add a row to AC-27 — or the workflow genuinely " +
|
|
623
|
+
"declares no triggers, in which case it never runs",
|
|
624
|
+
});
|
|
625
|
+
}
|
|
626
|
+
const automationTriggers = triggers.filter(t =>
|
|
627
|
+
(AUTOMATION_ONLY_TRIGGERS as readonly string[]).includes(t),
|
|
628
|
+
);
|
|
629
|
+
if (automationTriggers.length > 0) {
|
|
630
|
+
const everyTriggerIsAutomation = automationTriggers.length === triggers.length;
|
|
343
631
|
for (const tool of allowed) {
|
|
344
632
|
const server = mcpServerOf(tool);
|
|
345
633
|
const why = server ? ENTITY_ONLY_MCP_SERVERS[server] : undefined;
|
|
@@ -348,13 +636,74 @@ export function reviewToolAgreement(source: string): ReviewToolViolation[] {
|
|
|
348
636
|
kind: "ALLOWED_TOOL_CANNOT_EXIST_ON_THIS_TRIGGER",
|
|
349
637
|
detail:
|
|
350
638
|
`--allowedTools grants ${tool}, whose MCP server is installed only under an entity ` +
|
|
351
|
-
`event (${why}).
|
|
352
|
-
|
|
639
|
+
`event (${why}). ` +
|
|
640
|
+
(everyTriggerIsAutomation
|
|
641
|
+
? `This workflow's triggers are ${triggers.join(", ")}, all of which the action ` +
|
|
642
|
+
`classifies as automation events, so the tool never exists`
|
|
643
|
+
: `This workflow also triggers on ${automationTriggers.join(", ")}, which the ` +
|
|
644
|
+
`action classifies as an automation event, so a run started that way has no ` +
|
|
645
|
+
`such server and the tool does not exist in it. The grant works on ` +
|
|
646
|
+
`${triggers.filter(t => !automationTriggers.includes(t)).join(", ")} and ` +
|
|
647
|
+
`silently does nothing on the rest`),
|
|
353
648
|
});
|
|
354
649
|
}
|
|
355
650
|
}
|
|
356
651
|
}
|
|
357
652
|
|
|
653
|
+
// 3b. The trigger promotion's own door (#631/#675). An entity trigger means
|
|
654
|
+
// the job fires on pull requests opened by people who are not
|
|
655
|
+
// collaborators, and on a public repository that is most of them. The
|
|
656
|
+
// fork decision then has to exist somewhere a reader can point at.
|
|
657
|
+
//
|
|
658
|
+
// Read from the JOB HEADER, never the document: every revision of
|
|
659
|
+
// `claude-review.yml` discusses forks in its header at length, and a
|
|
660
|
+
// whole-file search would be satisfied by the prose explaining why the
|
|
661
|
+
// guard matters — `.claude/rules/checks-must-be-able-to-fail.md`,
|
|
662
|
+
// "search the slice, not the document", which is the defect the
|
|
663
|
+
// reviewer found in this very module on #746.
|
|
664
|
+
//
|
|
665
|
+
// Silent on an automation-only workflow, which is why the pre-#732
|
|
666
|
+
// fixture does not report it: a dispatch cannot be opened by a
|
|
667
|
+
// stranger, and a guard against a case that cannot arise is one more
|
|
668
|
+
// thing to keep true for nothing.
|
|
669
|
+
const entityTriggers = triggers.filter(t => (ENTITY_TRIGGERS as readonly string[]).includes(t));
|
|
670
|
+
if (triggers.includes("pull_request_target")) {
|
|
671
|
+
v.push({
|
|
672
|
+
kind: "PULL_REQUEST_TARGET_TRIGGER",
|
|
673
|
+
detail:
|
|
674
|
+
"the workflow triggers on pull_request_target, which runs this job with a WRITE token " +
|
|
675
|
+
"against a fork's code. For a job that hands a diff to an agent that is the egress sink " +
|
|
676
|
+
"this file's header describes, with the credential handed over deliberately — use " +
|
|
677
|
+
"pull_request, whose fork runs are read-only",
|
|
678
|
+
});
|
|
679
|
+
}
|
|
680
|
+
if (entityTriggers.length > 0) {
|
|
681
|
+
// The `if:` block, not the job header. A `name:` or an `env:` value
|
|
682
|
+
// carrying both terms would satisfy a header-wide search, and an absent
|
|
683
|
+
// `if:` is reported as the missing guard it is rather than throwing.
|
|
684
|
+
let condition = "";
|
|
685
|
+
try {
|
|
686
|
+
condition = withoutComments(blockUnder(jobHeader, "if:"));
|
|
687
|
+
} catch {
|
|
688
|
+
condition = "";
|
|
689
|
+
}
|
|
690
|
+
const missing = FORK_GUARD_TERMS.filter(term => !condition.includes(term));
|
|
691
|
+
const why =
|
|
692
|
+
missing.length > 0
|
|
693
|
+
? `the job's condition names neither ${missing.join(" nor ")}`
|
|
694
|
+
: forkGuardDefect(condition);
|
|
695
|
+
if (why !== null) {
|
|
696
|
+
v.push({
|
|
697
|
+
kind: "ENTITY_TRIGGER_WITHOUT_A_FORK_GUARD",
|
|
698
|
+
detail:
|
|
699
|
+
`the workflow triggers on ${entityTriggers.join(", ")}, so it runs on pull requests ` +
|
|
700
|
+
`from forks, and ${why}. A fork run holds a read-only token and no id-token: write, ` +
|
|
701
|
+
`so every step after auth fails — and a job that fails on every fork pull request is ` +
|
|
702
|
+
`a red check nobody can act on`,
|
|
703
|
+
});
|
|
704
|
+
}
|
|
705
|
+
}
|
|
706
|
+
|
|
358
707
|
// 4. Nothing on the allowlist can write a finding anywhere a human will see.
|
|
359
708
|
if (!allowed.some(a => (POSTING_TOOLS as readonly string[]).includes(a))) {
|
|
360
709
|
v.push({
|
|
@@ -130,6 +130,7 @@ import {
|
|
|
130
130
|
AI_REVIEW_REQUIRED_EXIT,
|
|
131
131
|
AI_REVIEW_SEVERITIES,
|
|
132
132
|
AI_REVIEW_SEVERITY_KEY,
|
|
133
|
+
AI_REVIEW_THREAD_KEY_MARKER,
|
|
133
134
|
AI_REVIEW_VERDICT_KEY,
|
|
134
135
|
SEVERITY_RANK,
|
|
135
136
|
type Severity,
|
|
@@ -836,6 +837,172 @@ export function findingPathScope(
|
|
|
836
837
|
return touched.has(named) ? "IN_DIFF" : "PRE_EXISTING";
|
|
837
838
|
}
|
|
838
839
|
|
|
840
|
+
/**
|
|
841
|
+
* One inline review comment, as the REST API wants it minus the parts only
|
|
842
|
+
* the caller knows (`commit_id`, the pull request number, the token).
|
|
843
|
+
*
|
|
844
|
+
* `line` is `null` when the finding named no line this reader could use. That
|
|
845
|
+
* is a FILE-LEVEL comment — `POST /pulls/{n}/comments` documents `line` as
|
|
846
|
+
* "Required unless using subject_type:file" — and not a finding to drop.
|
|
847
|
+
*/
|
|
848
|
+
export interface AiReviewThreadRequest {
|
|
849
|
+
/** Repository-relative, in the spelling the finding wrote. */
|
|
850
|
+
path: string;
|
|
851
|
+
line: number | null;
|
|
852
|
+
body: string;
|
|
853
|
+
}
|
|
854
|
+
|
|
855
|
+
/**
|
|
856
|
+
* The comments a reading should become — the whole of the decision, in one
|
|
857
|
+
* binding, with no network in it.
|
|
858
|
+
*
|
|
859
|
+
* Measured 2026-10-25 across every merged pull request on the consumer that
|
|
860
|
+
* runs this: zero review threads, ever. The review's output has only ever
|
|
861
|
+
* been a GitHub Actions annotation, which lives as long as the run log and
|
|
862
|
+
* is not something `required_conversation_resolution` can read. So a repo
|
|
863
|
+
* that switches that protection on gets a gate with no producer — satisfied
|
|
864
|
+
* by construction, because nothing it governs is ever created.
|
|
865
|
+
*
|
|
866
|
+
* Three decisions are worth stating, because each has a cheaper wrong answer:
|
|
867
|
+
*
|
|
868
|
+
* **`unlocatableReported` is subtracted, and `null` subtracts nothing.** A
|
|
869
|
+
* finding naming a file the pull request does not touch has no line in this
|
|
870
|
+
* diff to hang off, so the API would refuse it. `null` is the scope check not
|
|
871
|
+
* having run — see `AiReviewFindingsReading.unlocatableReported` — and a
|
|
872
|
+
* reading that could not locate anything must not be read as one that located
|
|
873
|
+
* everything. Membership is by IDENTITY, not by a key rebuilt from the
|
|
874
|
+
* finding's fields: the field set is caller-supplied and two findings can
|
|
875
|
+
* share every value in it, and `unlocatableReported` is already a subset of
|
|
876
|
+
* `reported` by reference.
|
|
877
|
+
*
|
|
878
|
+
* **`normaliseRepoPath` decides whether a path is readable and never supplies
|
|
879
|
+
* the value.** It lowercases, deliberately, because its job is to make two
|
|
880
|
+
* spellings of one path compare equal. The API's job is the opposite: `path`
|
|
881
|
+
* is matched against the diff exactly and a case difference is a 422. Those
|
|
882
|
+
* two requirements fit in one function only if you never notice they are
|
|
883
|
+
* different.
|
|
884
|
+
*
|
|
885
|
+
* **An unreadable line demotes rather than drops.** Being in the changed set
|
|
886
|
+
* makes a finding locatable to a FILE; it does not prove the line sits inside
|
|
887
|
+
* a hunk, which is a separate 422 the caller has to be able to fall back
|
|
888
|
+
* from. Dropping here would silently lose findings whose only defect is that
|
|
889
|
+
* the reviewer wrote no line number.
|
|
890
|
+
*/
|
|
891
|
+
export function reviewThreadRequests(
|
|
892
|
+
reading: AiReviewFindingsReading,
|
|
893
|
+
keyFor?: (finding: Record<string, unknown>) => string | null,
|
|
894
|
+
): AiReviewThreadRequest[] {
|
|
895
|
+
const f = AI_REVIEW_FINDING_FIELDS;
|
|
896
|
+
if (reading.reported === null) return [];
|
|
897
|
+
const unlocatable = new Set(reading.unlocatableReported ?? []);
|
|
898
|
+
|
|
899
|
+
const requests: AiReviewThreadRequest[] = [];
|
|
900
|
+
for (const item of reading.reported) {
|
|
901
|
+
if (unlocatable.has(item)) continue;
|
|
902
|
+
if (typeof item !== "object" || item === null) continue;
|
|
903
|
+
const finding = item as Record<string, unknown>;
|
|
904
|
+
|
|
905
|
+
const raw = finding[f.file];
|
|
906
|
+
// Readability is asked of the normalised spelling; the answer is carried
|
|
907
|
+
// by the raw one. A `:line` suffix is the one edit applied to it, because
|
|
908
|
+
// `src/a.ts:88` is not a path the API can match and the number in it is
|
|
909
|
+
// the only line the finding gave.
|
|
910
|
+
if (normaliseRepoPath(raw) === null) continue;
|
|
911
|
+
const suffixed = String(raw).trim().replace(/\\/g, "/").match(/^(.*?):(\d+)(?::\d+)?$/);
|
|
912
|
+
const path = suffixed ? suffixed[1]! : String(raw).trim().replace(/\\/g, "/");
|
|
913
|
+
|
|
914
|
+
const declared = finding[f.line];
|
|
915
|
+
const line =
|
|
916
|
+
typeof declared === "number" && Number.isInteger(declared) && declared > 0
|
|
917
|
+
? declared
|
|
918
|
+
: suffixed
|
|
919
|
+
? Number(suffixed[2])
|
|
920
|
+
: null;
|
|
921
|
+
|
|
922
|
+
requests.push({ path, line, body: threadBody(finding, keyFor?.(finding)) });
|
|
923
|
+
}
|
|
924
|
+
return requests;
|
|
925
|
+
}
|
|
926
|
+
|
|
927
|
+
/**
|
|
928
|
+
* What one comment says.
|
|
929
|
+
*
|
|
930
|
+
* The failure scenario is carried whenever the finding wrote one. It is the
|
|
931
|
+
* half a reader acts on — a summary alone is a label — and the annotation
|
|
932
|
+
* path has never had room for it, which is part of why the annotations were
|
|
933
|
+
* worth so little.
|
|
934
|
+
*/
|
|
935
|
+
/**
|
|
936
|
+
* The thread a finding becomes, with the identity it was raised under
|
|
937
|
+
* appended when the caller could form one.
|
|
938
|
+
*
|
|
939
|
+
* `key` is a parameter and not something read here, for the reason
|
|
940
|
+
* `suppressRepeats` states about its own prior set: only the caller can
|
|
941
|
+
* reach the checkout to read the text at the cited line, and a function that
|
|
942
|
+
* fetches its own evidence cannot be given a negative control. It is also
|
|
943
|
+
* why `carryKey` is not imported — this module is copied ALONE into a
|
|
944
|
+
* scratch directory by several mutation batteries, and a relative import
|
|
945
|
+
* added to it resolves to nothing, so the mutant fails to LOAD and reads as
|
|
946
|
+
* a behavioural difference on every row.
|
|
947
|
+
*
|
|
948
|
+
* `null`, `undefined` and `""` all emit NO marker, and that is deliberate.
|
|
949
|
+
* A caller that could not key the finding has not recorded an empty key; it
|
|
950
|
+
* has recorded nothing, and the two must not be the same bytes.
|
|
951
|
+
*/
|
|
952
|
+
export function threadBody(finding: Record<string, unknown>, key?: string | null): string {
|
|
953
|
+
const f = AI_REVIEW_FINDING_FIELDS;
|
|
954
|
+
const severity = finding[f.severity] !== undefined ? String(finding[f.severity]) : null;
|
|
955
|
+
const summary =
|
|
956
|
+
finding[f.summary] !== undefined ? String(finding[f.summary]) : "(no summary recorded)";
|
|
957
|
+
const scenario =
|
|
958
|
+
finding[f.failureScenario] !== undefined ? String(finding[f.failureScenario]) : null;
|
|
959
|
+
|
|
960
|
+
const head = severity === null ? summary : `**${severity}** — ${summary}`;
|
|
961
|
+
const prose = scenario === null ? head : `${head}\n\n${scenario}`;
|
|
962
|
+
if (typeof key !== "string" || key === "") return prose;
|
|
963
|
+
const payload = Buffer.from(key, "utf-8").toString("base64");
|
|
964
|
+
return `${prose}\n\n<!-- ${AI_REVIEW_THREAD_KEY_MARKER} ${payload} -->`;
|
|
965
|
+
}
|
|
966
|
+
|
|
967
|
+
/**
|
|
968
|
+
* Recover the key a thread was posted under, or `null`.
|
|
969
|
+
*
|
|
970
|
+
* `null` means THIS THREAD CANNOT BE SHOWN TO BE A REPEAT, and every way of
|
|
971
|
+
* failing collapses to it: no marker, a marker this version does not know, a
|
|
972
|
+
* payload that is not base64, a payload that does not decode to the bytes it
|
|
973
|
+
* encoded. That collapse is safe in exactly one direction — a thread read as
|
|
974
|
+
* unkeyed is re-posted, which is loud and self-correcting, whereas a thread
|
|
975
|
+
* read under the WRONG key suppresses a live finding silently and
|
|
976
|
+
* permanently.
|
|
977
|
+
*
|
|
978
|
+
* The round-trip check is why a corrupt payload cannot become a key by
|
|
979
|
+
* accident: `Buffer.from` is lenient and will decode almost any string to
|
|
980
|
+
* SOME bytes, so re-encoding and comparing is the only reading that
|
|
981
|
+
* distinguishes a payload this writer produced from one it did not.
|
|
982
|
+
*/
|
|
983
|
+
export function threadKeyFrom(body: unknown): string | null {
|
|
984
|
+
if (typeof body !== "string") return null;
|
|
985
|
+
const at = body.lastIndexOf(`<!-- ${AI_REVIEW_THREAD_KEY_MARKER} `);
|
|
986
|
+
if (at === -1) return null;
|
|
987
|
+
const rest = body.slice(at + `<!-- ${AI_REVIEW_THREAD_KEY_MARKER} `.length);
|
|
988
|
+
const end = rest.indexOf("-->");
|
|
989
|
+
if (end === -1) return null;
|
|
990
|
+
const payload = rest.slice(0, end).trim();
|
|
991
|
+
if (payload === "") return null;
|
|
992
|
+
let decoded: string;
|
|
993
|
+
try {
|
|
994
|
+
decoded = Buffer.from(payload, "base64").toString("utf-8");
|
|
995
|
+
} catch {
|
|
996
|
+
return null;
|
|
997
|
+
}
|
|
998
|
+
if (decoded === "") return null;
|
|
999
|
+
// THE CONTROL ON THE DECODE. Without it `@@@not base64@@@` decodes to
|
|
1000
|
+
// mojibake and is returned as a key, so every corrupt thread becomes a
|
|
1001
|
+
// repeat of every other corrupt thread.
|
|
1002
|
+
if (Buffer.from(decoded, "utf-8").toString("base64") !== payload) return null;
|
|
1003
|
+
return decoded;
|
|
1004
|
+
}
|
|
1005
|
+
|
|
839
1006
|
/**
|
|
840
1007
|
* CRC-B7's tag for one finding — `Important`, `Nit` or `Pre-existing`.
|
|
841
1008
|
*
|