rungate 0.8.2 → 0.8.4
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/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/BunTestPathGuard.hook.ts +106 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/TopLevelCdGuard.hook.ts +38 -6
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/bun-test-paths.ts +253 -0
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +17 -1
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +61 -5
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +646 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +21 -1
- package/lib/project-state-shape.ts +56 -5
- package/lib/release-preflight.ts +90 -1
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +218 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1369 -27
- package/lib/scaffold/ai-review-step.ts +4095 -119
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +100 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +22 -2
- package/lib/spec-write-ast.ts +728 -0
- package/lib/spec-write-sweep.ts +470 -0
- package/lib/test-suite-lock.ts +127 -13
- package/lib/ts-ast.ts +26 -0
- package/lib/validators/spec-validators.ts +36 -7
- package/lib/write-spec.ts +138 -0
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -24
- package/scripts/convert-spec.ts +7 -2
- package/scripts/create-sc.ts +14 -2
- package/scripts/create-spec.ts +5 -2
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +17 -4
- package/scripts/sync-sc-status.ts +14 -2
|
@@ -50,6 +50,51 @@
|
|
|
50
50
|
* reads as clean, and the derived decision is WITHHELD rather than defaulted:
|
|
51
51
|
* `blocked` is `null` under an UNMEASURED reading.
|
|
52
52
|
*
|
|
53
|
+
* ## Where a finding points, and why that is not a question about whether it
|
|
54
|
+
* is right (#1204)
|
|
55
|
+
*
|
|
56
|
+
* A blocking finding may name a file the pull request never touched. #1166
|
|
57
|
+
* made a finding missing `file`, `line`, `summary` or `failure_scenario` its
|
|
58
|
+
* own reading; that is a check on whether the payload is SELF-consistent, and
|
|
59
|
+
* the payload is all it needs. "The file is not in the diff" compares the
|
|
60
|
+
* payload against the PULL REQUEST, so it needs a second input — the list of
|
|
61
|
+
* paths the pull request changed — and the reading is withheld until it has
|
|
62
|
+
* one.
|
|
63
|
+
*
|
|
64
|
+
* **This is not a correctness filter and must never become one.** Nothing
|
|
65
|
+
* here asks whether a finding is RIGHT. A reviewer that is wrong about real
|
|
66
|
+
* code is a review problem, and suppressing findings on suspicion of being
|
|
67
|
+
* wrong is the fail-open this module exists against. The only question asked
|
|
68
|
+
* is whether the finding can be LOCATED, which is decidable from the diff
|
|
69
|
+
* without reading the claim at all.
|
|
70
|
+
*
|
|
71
|
+
* And an unlocatable finding is **demoted, never dropped**. The tempting
|
|
72
|
+
* repair is to filter it out of the blocking list and let the run go green —
|
|
73
|
+
* which makes a review that discarded a finding byte-indistinguishable from a
|
|
74
|
+
* review that found nothing. So CRC-B7 tags it `Pre-existing`: the finding is
|
|
75
|
+
* carried in `reported` and in `unlocatableReported`, named in the
|
|
76
|
+
* annotation, counted on the scope line, and does not get to block on its
|
|
77
|
+
* own.
|
|
78
|
+
*
|
|
79
|
+
* #1204 wrote that refusal as `BLOCKING_FINDING_UNLOCATABLE`, a red required
|
|
80
|
+
* check. CRC-B7's demotion satisfies #1204's own stated criterion — the
|
|
81
|
+
* finding is not DROPPED — and does not redden a pull request over a defect
|
|
82
|
+
* that was already on main, so the refusal is gone and the demotion is what
|
|
83
|
+
* ships. The two were written against the same input on different branches;
|
|
84
|
+
* this is the resolution, not an accident of the merge.
|
|
85
|
+
*
|
|
86
|
+
* The second input is NOT SUPPLIED by any generated job yet, and the absent
|
|
87
|
+
* state is named rather than silently skipped — `scope.status` is
|
|
88
|
+
* `NOT_SUPPLIED`, `main` prints it on every run, and the verdict is exactly
|
|
89
|
+
* what it was before. That is deliberately the third option, against the two
|
|
90
|
+
* #1204 tabulated: skipping silently is Silent Default Substitution, and
|
|
91
|
+
* refusing an absent list would redden consumers for a reason about our
|
|
92
|
+
* release rather than about their code. The generated step runs
|
|
93
|
+
* `bunx rungate@<generating version>`, so a consumer's workflow and its
|
|
94
|
+
* adjudicator always come from the SAME release and cannot skew apart; the
|
|
95
|
+
* absent state is reachable from a hand-run CLI and from a workflow older
|
|
96
|
+
* than the half that supplies the list.
|
|
97
|
+
*
|
|
53
98
|
* ## The exit code
|
|
54
99
|
*
|
|
55
100
|
* Every refusal routes through `AI_REVIEW_REQUIRED_EXIT`, imported from
|
|
@@ -86,6 +131,8 @@ import {
|
|
|
86
131
|
AI_REVIEW_SEVERITIES,
|
|
87
132
|
AI_REVIEW_SEVERITY_KEY,
|
|
88
133
|
AI_REVIEW_VERDICT_KEY,
|
|
134
|
+
SEVERITY_RANK,
|
|
135
|
+
type Severity,
|
|
89
136
|
} from "./ai-review-step";
|
|
90
137
|
|
|
91
138
|
export {
|
|
@@ -97,7 +144,9 @@ export {
|
|
|
97
144
|
AI_REVIEW_SEVERITIES,
|
|
98
145
|
AI_REVIEW_SEVERITY_KEY,
|
|
99
146
|
AI_REVIEW_VERDICT_KEY,
|
|
147
|
+
SEVERITY_RANK,
|
|
100
148
|
};
|
|
149
|
+
export type { Severity };
|
|
101
150
|
|
|
102
151
|
/**
|
|
103
152
|
* Percent-encode a value before it is interpolated into a workflow command.
|
|
@@ -131,8 +180,25 @@ export const AI_REVIEW_DETAIL_MAX = 300;
|
|
|
131
180
|
* site in `main()`, because two escapers applied in sequence turn `%` into
|
|
132
181
|
* `%2525` and the bug that produces is invisible until someone reads a log.
|
|
133
182
|
* One rule, one binding, applied last.
|
|
183
|
+
*
|
|
184
|
+
* `tag` is CRC-B7's Important / Nit / Pre-existing, appended AFTER the cap
|
|
185
|
+
* rather than before it. A tag inside the capped region is a tag a long
|
|
186
|
+
* summary deletes, and the one finding whose attribution a reader most needs
|
|
187
|
+
* is the verbose one — "this is not your bug" truncated away reads as "this
|
|
188
|
+
* is your bug". `null` renders nothing at all, because a finding whose
|
|
189
|
+
* severity the contract does not declare has no tag, and an empty bracket
|
|
190
|
+
* would read as one.
|
|
191
|
+
*
|
|
192
|
+
* The INDEX is the payload index and stays the payload index whatever the
|
|
193
|
+
* display order is. The refusal and the advisory notice share this numbering
|
|
194
|
+
* (#1178), so a sort that renumbered would make `finding 3` mean two
|
|
195
|
+
* different findings in two annotations about the same run.
|
|
134
196
|
*/
|
|
135
|
-
export function renderFinding(
|
|
197
|
+
export function renderFinding(
|
|
198
|
+
index: number,
|
|
199
|
+
finding: Record<string, unknown>,
|
|
200
|
+
tag: Severity | null = null,
|
|
201
|
+
): string {
|
|
136
202
|
const f = AI_REVIEW_FINDING_FIELDS;
|
|
137
203
|
const where = finding[f.file] !== undefined
|
|
138
204
|
? `${String(finding[f.file])}:${String(finding[f.line] ?? "?")}`
|
|
@@ -141,7 +207,9 @@ export function renderFinding(index: number, finding: Record<string, unknown>):
|
|
|
141
207
|
? String(finding[f.summary])
|
|
142
208
|
: "(no summary recorded)";
|
|
143
209
|
const line = `finding ${index} is ${String(finding[f.severity])} at ${where}: ${what}`;
|
|
144
|
-
|
|
210
|
+
const body =
|
|
211
|
+
line.length > AI_REVIEW_DETAIL_MAX ? `${line.slice(0, AI_REVIEW_DETAIL_MAX)}…` : line;
|
|
212
|
+
return tag === null ? body : `${body} [${tag}]`;
|
|
145
213
|
}
|
|
146
214
|
|
|
147
215
|
/**
|
|
@@ -172,12 +240,22 @@ export function renderFinding(index: number, finding: Record<string, unknown>):
|
|
|
172
240
|
* arm is unreachable from `aiReviewRefusal`. It exists because the function
|
|
173
241
|
* is exported and `unknown[]` is what it is handed: a renderer that throws
|
|
174
242
|
* on a shape it was told it would never see is a refusal nobody can read.
|
|
243
|
+
*
|
|
244
|
+
* The result is indexed BY PAYLOAD INDEX and is deliberately not sorted here.
|
|
245
|
+
* Callers that display it order it with `tagOrder`, and they have to: this
|
|
246
|
+
* array is subscripted by `advisoryNotice` (`all[i]`, where `i` is the item's
|
|
247
|
+
* position in `reported`), so a sort applied inside would silently re-point
|
|
248
|
+
* every one of those lookups at a different finding. Rendering and ordering
|
|
249
|
+
* are separate jobs and the bug that merges them is invisible.
|
|
175
250
|
*/
|
|
176
|
-
export function renderCountedFindings(
|
|
251
|
+
export function renderCountedFindings(
|
|
252
|
+
reported: unknown[] | null,
|
|
253
|
+
tags: readonly (Severity | null)[] | null = null,
|
|
254
|
+
): string[] {
|
|
177
255
|
if (reported === null) return [];
|
|
178
256
|
return reported.map((item, i) =>
|
|
179
257
|
item !== null && typeof item === "object" && !Array.isArray(item)
|
|
180
|
-
? renderFinding(i, item as Record<string, unknown
|
|
258
|
+
? renderFinding(i, item as Record<string, unknown>, tags?.[i] ?? null)
|
|
181
259
|
: `finding ${i} is ${JSON.stringify(item)}`,
|
|
182
260
|
);
|
|
183
261
|
}
|
|
@@ -185,6 +263,191 @@ export function renderCountedFindings(reported: unknown[] | null): string[] {
|
|
|
185
263
|
/** The annotation title the script prints its refusal under. */
|
|
186
264
|
export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
|
|
187
265
|
|
|
266
|
+
/**
|
|
267
|
+
* The annotation title the advisory tail is printed under.
|
|
268
|
+
*
|
|
269
|
+
* A SEPARATE title from `AI_REVIEW_FINDINGS_TITLE`, deliberately. The refusal
|
|
270
|
+
* is a thing somebody has to act on before the pull request moves; this is a
|
|
271
|
+
* thing somebody has to answer before it merges, and GitHub groups
|
|
272
|
+
* annotations by title. One title for both would make the advisory tail
|
|
273
|
+
* read, in the checks UI, as part of the refusal — which is the misattribution
|
|
274
|
+
* `blockingContractViolations` is about, arriving from the other direction.
|
|
275
|
+
*/
|
|
276
|
+
export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* A stable identity for one finding, so an answer can name it.
|
|
280
|
+
*
|
|
281
|
+
* @identity file+summary — whitespace-collapsed and case-folded, FNV-1a, 8
|
|
282
|
+
* hex characters. Total: every finding gets a key, and it is never `null`.
|
|
283
|
+
*
|
|
284
|
+
* **This is the ADJUDICATION key** — "has this advisory already been counted
|
|
285
|
+
* on this run". Within one payload there is only one version of the file, so
|
|
286
|
+
* the line genuinely does not matter, and keying on it would split one
|
|
287
|
+
* finding into two across a reformat.
|
|
288
|
+
*
|
|
289
|
+
* Its sibling is `carryKey` in `lib/ai-review-rounds.ts`, which is the
|
|
290
|
+
* PERSISTENCE key — "is the thing this round raised the thing the last round
|
|
291
|
+
* raised" — over `file` + the cited line's TEXT + `summary`, and partial: it
|
|
292
|
+
* returns `null` for a finding it cannot key, which this hash cannot do. The
|
|
293
|
+
* two were both called `findingKey` until #1398. They answer different
|
|
294
|
+
* questions and the collapse loses one; neither can quietly become the
|
|
295
|
+
* other, which was measured rather than assumed, but while they shared a
|
|
296
|
+
* name no call site could say which it had asked.
|
|
297
|
+
*
|
|
298
|
+
* CRC-B8 asks that every finding be answered — fixed, or resolved with a
|
|
299
|
+
* stated reason — and an answer has to name what it answers. The line number
|
|
300
|
+
* cannot be that name: the same finding moves line between rounds, which is
|
|
301
|
+
* exactly what #1319 measured (`bash-write-guard.ts:90 → :97` across two
|
|
302
|
+
* rounds of #1213 was *one* finding). So the key is over the file and the
|
|
303
|
+
* summary, whitespace-collapsed and case-folded, and it is deliberately NOT
|
|
304
|
+
* over the severity either — a reviewer that re-rates the same observation
|
|
305
|
+
* has not produced a second finding.
|
|
306
|
+
*
|
|
307
|
+
* FNV-1a, written out, rather than `node:crypto`. Not a preference: this
|
|
308
|
+
* module is copied into a temp directory by the mutation battery in
|
|
309
|
+
* `test/ai-review-advisory-findings.test.ts`, and every import it carries has
|
|
310
|
+
* to be carried with it. The property wanted is determinism and a short
|
|
311
|
+
* printable token, not collision resistance against an adversary.
|
|
312
|
+
*
|
|
313
|
+
* ## WHAT A COLLISION COSTS, and it is no longer only an annotation
|
|
314
|
+
*
|
|
315
|
+
* This docblock used to end *"a finding that forged another finding's key
|
|
316
|
+
* would buy the forger an answer on the wrong row, which is a worse
|
|
317
|
+
* annotation and not a bypass of anything."* That stopped being true the
|
|
318
|
+
* moment CRC-B4 made the verifier quorum read a ballot filed under this
|
|
319
|
+
* key: a collision between two BLOCKING findings would let one group's vote
|
|
320
|
+
* decide both. The sentence is corrected rather than deleted because a
|
|
321
|
+
* comment asserting a property the code no longer has is the reason nobody
|
|
322
|
+
* checks it — `lib/cli-commands.ts` carried *"runs every command for real"*
|
|
323
|
+
* over a test that ran one command of ten.
|
|
324
|
+
*
|
|
325
|
+
* What holds instead, and it is a property of the CALLER rather than of
|
|
326
|
+
* this hash: `juryGate` derives the identity once over the whole blocking
|
|
327
|
+
* set, refuses a key two of them share, and carries its decision back to
|
|
328
|
+
* the reader **by position**. So a collision is seen and both findings keep
|
|
329
|
+
* blocking; it cannot silently credit one finding's vote to another. The
|
|
330
|
+
* hash is still not adversary-resistant and is not asked to be — nothing
|
|
331
|
+
* downstream of it decides anything a collision could not already be
|
|
332
|
+
* refused for.
|
|
333
|
+
*/
|
|
334
|
+
export function advisoryKey(finding: Record<string, unknown>): string {
|
|
335
|
+
const f = AI_REVIEW_FINDING_FIELDS;
|
|
336
|
+
const normalise = (v: unknown): string =>
|
|
337
|
+
String(v ?? "").trim().replace(/\s+/g, " ").toLowerCase();
|
|
338
|
+
const subject = `${normalise(finding[f.file])}\u0000${normalise(finding[f.summary])}`;
|
|
339
|
+
let hash = 0x811c9dc5;
|
|
340
|
+
for (let i = 0; i < subject.length; i++) {
|
|
341
|
+
hash ^= subject.charCodeAt(i);
|
|
342
|
+
hash = Math.imul(hash, 0x01000193) >>> 0;
|
|
343
|
+
}
|
|
344
|
+
return hash.toString(16).padStart(8, "0");
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
/**
|
|
348
|
+
* The findings this reading counted and did NOT act on — the advisory tail.
|
|
349
|
+
*
|
|
350
|
+
* `null`, never `[]`, when the complement cannot be taken. Under UNMEASURED
|
|
351
|
+
* `blockingReported` is `null` — a withheld decision, not an empty one — so
|
|
352
|
+
* subtracting it from `reported` would manufacture an advisory set out of
|
|
353
|
+
* findings nobody classified. Those are different facts and this module's
|
|
354
|
+
* whole philosophy is that they stay different.
|
|
355
|
+
*
|
|
356
|
+
* Computed by identity against `blockingReported` rather than by re-reading
|
|
357
|
+
* the severities. Re-reading them here would be a second decider over the one
|
|
358
|
+
* question `severityBlocks` already answers — the fourth shape in
|
|
359
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
|
|
360
|
+
* would leave the other holding every case up.
|
|
361
|
+
*/
|
|
362
|
+
export function advisoryReported(reading: AiReviewFindingsReading): unknown[] | null {
|
|
363
|
+
if (reading.reported === null || reading.blockingReported === null) return null;
|
|
364
|
+
const blocking = new Set(reading.blockingReported);
|
|
365
|
+
return reading.reported.filter(item => !blocking.has(item));
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* The sentence naming every advisory finding, or `null` when there is nothing
|
|
370
|
+
* to name.
|
|
371
|
+
*
|
|
372
|
+
* ## The silent drop this closes (CRC-B8)
|
|
373
|
+
*
|
|
374
|
+
* `AI_REVIEW_SEVERITIES` declares `medium`, `low` and `info` as advisory, and
|
|
375
|
+
* until this function existed a reading counted them and then dropped them.
|
|
376
|
+
* `detail` is populated inside `if (blocks)`; `aiReviewRefusal` returns `null`
|
|
377
|
+
* for CLEAN and lists only `detail` for BLOCKED. So `main()` printed the
|
|
378
|
+
* outcome line and nothing else, and a payload carrying seven `medium`
|
|
379
|
+
* findings produced **byte-identical output** to a payload carrying none.
|
|
380
|
+
* The payload itself lives under `$RUNNER_TEMP`, is uploaded nowhere (#1319
|
|
381
|
+
* measured zero artifacts) and dies with the runner, so the finding was not
|
|
382
|
+
* merely unreported — it was unrecoverable the moment the job ended.
|
|
383
|
+
*
|
|
384
|
+
* That is CRC-B8's second sentence failing in the live path: *a finding is
|
|
385
|
+
* never silently dropped*. It is also the reason the tail could not be
|
|
386
|
+
* answered rather than filed — you cannot resolve on the pull request a
|
|
387
|
+
* finding the pull request never shows you.
|
|
388
|
+
*
|
|
389
|
+
* ## Why CONTRADICTION returns null here
|
|
390
|
+
*
|
|
391
|
+
* The contradiction arm of `aiReviewRefusal` already prints EVERY counted
|
|
392
|
+
* finding, advisory ones included, through `renderCountedFindings` — #1178,
|
|
393
|
+
* and for a reason that still holds. Emitting this notice alongside it would
|
|
394
|
+
* print the advisory tail twice, and that module's own comment says why that
|
|
395
|
+
* is worse than printing it once: *a duplicate reads as two findings*. The
|
|
396
|
+
* rule lives here, in one function, rather than as a condition at the call
|
|
397
|
+
* site, so there is one binding to mutate.
|
|
398
|
+
*
|
|
399
|
+
* ## What this does NOT do
|
|
400
|
+
*
|
|
401
|
+
* It decides nothing. `aiReviewExitCode` is untouched and reads only the
|
|
402
|
+
* outcome, so an advisory finding does not block and cannot be made to block
|
|
403
|
+
* from here. Surfacing a finding and adjudicating one are different jobs, and
|
|
404
|
+
* this module already holds the second; a notice that quietly became a
|
|
405
|
+
* refusal would be a severity table nobody declared.
|
|
406
|
+
*/
|
|
407
|
+
export function advisoryNotice(reading: AiReviewFindingsReading): string | null {
|
|
408
|
+
if (reading.outcome === "CONTRADICTION") return null;
|
|
409
|
+
const advisory = advisoryReported(reading);
|
|
410
|
+
if (advisory === null || advisory.length === 0) return null;
|
|
411
|
+
|
|
412
|
+
// Rendered through `renderCountedFindings` over the WHOLE list and then
|
|
413
|
+
// selected, rather than over the filtered list. Two reasons, and the second
|
|
414
|
+
// is the one that bites: the renderer numbers what it is given, so rendering
|
|
415
|
+
// the tail alone would renumber it from zero and `finding 3` in this notice
|
|
416
|
+
// would be a different finding from `finding 3` in a refusal. And selecting
|
|
417
|
+
// out of the full render means this notice and the contradiction arm's list
|
|
418
|
+
// come from one call of one function, which is what keeps them from drifting.
|
|
419
|
+
const reported = reading.reported ?? [];
|
|
420
|
+
const all = renderCountedFindings(reported, reading.findingTags);
|
|
421
|
+
// CRC-B7's sort, applied to the DISPLAY and not to the payload. `all` stays
|
|
422
|
+
// subscripted by payload index — `tagOrder` returns indices into it — so
|
|
423
|
+
// every line still says `finding <payload index>` and still agrees with the
|
|
424
|
+
// refusal's numbering. Reordering `advisory` itself and re-rendering would
|
|
425
|
+
// renumber the tail from zero, which AD-2 reds on.
|
|
426
|
+
const rendered = tagOrder(
|
|
427
|
+
reading.findingTags,
|
|
428
|
+
advisory.map(item => reported.indexOf(item)),
|
|
429
|
+
).map(i => {
|
|
430
|
+
const item = reported[i];
|
|
431
|
+
const key =
|
|
432
|
+
item !== null && typeof item === "object" && !Array.isArray(item)
|
|
433
|
+
? ` [key ${advisoryKey(item as Record<string, unknown>)}]`
|
|
434
|
+
: "";
|
|
435
|
+
return `${all[i]}${key}`;
|
|
436
|
+
});
|
|
437
|
+
|
|
438
|
+
return (
|
|
439
|
+
`${advisory.length} advisory finding(s) were counted and block nothing, ` +
|
|
440
|
+
`in Important / Pre-existing / Nit order. ` +
|
|
441
|
+
`${rendered.join("; ")}. ` +
|
|
442
|
+
`Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
|
|
443
|
+
`resolved with a reason, or filed, and this annotation is the only place ` +
|
|
444
|
+
`it survives the job — the payload lives under the runner's temp directory ` +
|
|
445
|
+
`and is uploaded nowhere. Answer each one on this pull request (fix it, or ` +
|
|
446
|
+
`say in a comment why it stands), naming its key. Filing an issue is the ` +
|
|
447
|
+
`exception, not the default.`
|
|
448
|
+
);
|
|
449
|
+
}
|
|
450
|
+
|
|
188
451
|
/** The four states a reading can be in. Exactly one is reached per run. */
|
|
189
452
|
export type AiReviewOutcome = "CLEAN" | "BLOCKED" | "CONTRADICTION" | "UNMEASURED";
|
|
190
453
|
|
|
@@ -200,8 +463,29 @@ export type AiReviewUnmeasuredReason =
|
|
|
200
463
|
| "SEVERITY_ABSENT"
|
|
201
464
|
| "SEVERITY_UNRECOGNISED"
|
|
202
465
|
| "BLOCKING_FINDING_INCOMPLETE"
|
|
466
|
+
// `BLOCKING_FINDING_UNLOCATABLE` was here and is gone with the merge of
|
|
467
|
+
// #1204 into CRC-B7. Nothing produces it: a blocking finding naming a file
|
|
468
|
+
// outside the diff is DEMOTED to `Pre-existing` and the run stays readable,
|
|
469
|
+
// rather than refusing the whole reading. A member nothing emits is a state
|
|
470
|
+
// no test can reach, and `not.toContain` against it passes vacuously for
|
|
471
|
+
// ever — which is how a deleted check goes on looking guarded.
|
|
472
|
+
| "ARGUMENTS_UNREADABLE"
|
|
203
473
|
| "VERDICT_ABSENT"
|
|
204
|
-
| "VERDICT_UNRECOGNISED"
|
|
474
|
+
| "VERDICT_UNRECOGNISED"
|
|
475
|
+
/**
|
|
476
|
+
* A changed-file list was supplied and was EMPTY. A pull request always
|
|
477
|
+
* touches something, so `[]` is a reading that failed rather than a pull
|
|
478
|
+
* request that changed nothing — and taken at face value it would tag every
|
|
479
|
+
* finding `Pre-existing` and block none of them, which is the fail-open this
|
|
480
|
+
* module exists to refuse.
|
|
481
|
+
*/
|
|
482
|
+
| "CHANGED_FILES_EMPTY"
|
|
483
|
+
/**
|
|
484
|
+
* A changed-file list entry could not be read as a repository path.
|
|
485
|
+
* Comparing against a list the reader cannot normalise would demote every
|
|
486
|
+
* finding, so the list being unreadable is a reading that failed.
|
|
487
|
+
*/
|
|
488
|
+
| "CHANGED_FILES_UNREADABLE";
|
|
205
489
|
|
|
206
490
|
/**
|
|
207
491
|
* The fields a BLOCKING finding must carry, derived from the one contract map
|
|
@@ -247,6 +531,164 @@ export function blockingContractViolations(finding: Record<string, unknown>): st
|
|
|
247
531
|
});
|
|
248
532
|
}
|
|
249
533
|
|
|
534
|
+
// `AI_REVIEW_CHANGED_FILES_FLAG` lived here and is gone. #1204 argued for a
|
|
535
|
+
// FLAG over a second positional, citing #675: `--project-root <cwd>` "would
|
|
536
|
+
// arrive as a second positional and be read as a second payload".
|
|
537
|
+
//
|
|
538
|
+
// That hazard was CHECKED before the constant was removed, not waved away.
|
|
539
|
+
// `bin/rungate.ts` appends `--project-root` only when a command declares
|
|
540
|
+
// `projectRootFlag`, and `ai-review-findings` declares none — which is the
|
|
541
|
+
// very fact #1204 cited. So nothing injects a stray positional into THIS
|
|
542
|
+
// command, and the argument does not reach it.
|
|
543
|
+
//
|
|
544
|
+
// The positional wins because the deployed workflow passes one and #1356
|
|
545
|
+
// builds on that. Two spellings for one argument would be two deciders, and
|
|
546
|
+
// the spelling the generated step does not use is the one that would rot.
|
|
547
|
+
|
|
548
|
+
/**
|
|
549
|
+
* The prefix of the line recording how the scope reading was taken.
|
|
550
|
+
*
|
|
551
|
+
* Distinct from `AI_REVIEW_OUTCOME_LINE`, which the generated step lifts its
|
|
552
|
+
* verdict out of by parameter expansion on the FIRST occurrence of that
|
|
553
|
+
* marker. This line is printed after it and contains neither that marker nor
|
|
554
|
+
* a newline, so nothing about the verdict extraction moves.
|
|
555
|
+
*/
|
|
556
|
+
export const AI_REVIEW_SCOPE_LINE = "ai-review findings scope:";
|
|
557
|
+
|
|
558
|
+
/** Whether the pull request's changed-file list was read, and if not, why. */
|
|
559
|
+
export type AiReviewScopeStatus = "MEASURED" | "NOT_SUPPLIED" | "UNMEASURED";
|
|
560
|
+
|
|
561
|
+
/**
|
|
562
|
+
* The changed-file reading. One discriminator, `status`, and the producing
|
|
563
|
+
* code's own sentence beside it.
|
|
564
|
+
*
|
|
565
|
+
* `NOT_SUPPLIED` and `UNMEASURED` are different facts with different fixes.
|
|
566
|
+
* Nobody handed this run a list is a property of the workflow that invoked
|
|
567
|
+
* it; a list that could not be read is a property of this run. Collapsing
|
|
568
|
+
* them would make a release in which the input does not exist yet look like
|
|
569
|
+
* a `git diff` that failed.
|
|
570
|
+
*/
|
|
571
|
+
export type AiReviewScopeReading =
|
|
572
|
+
| { status: "NOT_SUPPLIED"; files: null; detail: string; reason: null }
|
|
573
|
+
| { status: "MEASURED"; files: string[]; detail: string; reason: null }
|
|
574
|
+
| {
|
|
575
|
+
status: "UNMEASURED";
|
|
576
|
+
files: null;
|
|
577
|
+
detail: string;
|
|
578
|
+
reason: Extract<
|
|
579
|
+
AiReviewUnmeasuredReason,
|
|
580
|
+
"CHANGED_FILES_UNREADABLE" | "CHANGED_FILES_EMPTY"
|
|
581
|
+
>;
|
|
582
|
+
};
|
|
583
|
+
|
|
584
|
+
/** The reading for a run nobody handed a changed-file list. */
|
|
585
|
+
export function scopeNotSupplied(): AiReviewScopeReading {
|
|
586
|
+
return {
|
|
587
|
+
status: "NOT_SUPPLIED",
|
|
588
|
+
files: null,
|
|
589
|
+
reason: null,
|
|
590
|
+
detail:
|
|
591
|
+
`no changed-file list was given (second positional argument), so whether ` +
|
|
592
|
+
`a blocking finding names a file this pull request touches was not checked. ` +
|
|
593
|
+
`This is a reading, not a pass: the generated job does not supply the list yet`,
|
|
594
|
+
};
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
/**
|
|
598
|
+
* The reading for a run whose changed-file list was supplied directly rather
|
|
599
|
+
* than read from disk.
|
|
600
|
+
*
|
|
601
|
+
* Exists so a caller holding an array does not have to spell the discriminated
|
|
602
|
+
* union by hand. `files` is carried raw; `readPayload` normalises.
|
|
603
|
+
*
|
|
604
|
+
* An EMPTY array is still MEASURED here and is refused downstream, on purpose:
|
|
605
|
+
* "a list was supplied and it was empty" is a fact this type can represent and
|
|
606
|
+
* `readAiReviewChangedFiles` cannot produce, so the refusal lives where every
|
|
607
|
+
* caller passes through rather than only on the disk path.
|
|
608
|
+
*/
|
|
609
|
+
export function scopeMeasured(files: readonly string[]): AiReviewScopeReading {
|
|
610
|
+
return {
|
|
611
|
+
status: "MEASURED",
|
|
612
|
+
files: [...files],
|
|
613
|
+
reason: null,
|
|
614
|
+
detail: `${files.length} changed path(s) supplied directly`,
|
|
615
|
+
};
|
|
616
|
+
}
|
|
617
|
+
|
|
618
|
+
/**
|
|
619
|
+
* Read the changed-file list from disk. Three states, each its own fact.
|
|
620
|
+
*
|
|
621
|
+
* A list that could not be read REFUSES and must never produce an empty list:
|
|
622
|
+
* an empty changed set makes every blocking finding unlocatable, which is the
|
|
623
|
+
* loud direction and loud for the wrong reason — it reads as the reviewer
|
|
624
|
+
* having hallucinated every finding it wrote.
|
|
625
|
+
*
|
|
626
|
+
* A list that WAS read and names no paths refuses too, under its own reason.
|
|
627
|
+
* A pull request that changes nothing is not a state this input can honestly
|
|
628
|
+
* be in, so an empty file is a diff that was lost rather than a diff that was
|
|
629
|
+
* empty — and the two reasons are kept apart because the fixes differ.
|
|
630
|
+
*
|
|
631
|
+
* The list must be taken from the RESTORED tree, before the reviewer could
|
|
632
|
+
* have written to the checkout. That is why this function is handed a path
|
|
633
|
+
* and never takes the diff itself: this module runs after the review, from
|
|
634
|
+
* the payload's own directory, so a diff computed here is one the subject of
|
|
635
|
+
* the review had an opportunity to edit.
|
|
636
|
+
*/
|
|
637
|
+
export function readAiReviewChangedFiles(path: string | undefined): AiReviewScopeReading {
|
|
638
|
+
if (path === undefined || path === "") return scopeNotSupplied();
|
|
639
|
+
|
|
640
|
+
let raw: string;
|
|
641
|
+
try {
|
|
642
|
+
raw = readFileSync(path, "utf-8");
|
|
643
|
+
} catch (e) {
|
|
644
|
+
return {
|
|
645
|
+
status: "UNMEASURED",
|
|
646
|
+
files: null,
|
|
647
|
+
reason: "CHANGED_FILES_UNREADABLE",
|
|
648
|
+
detail:
|
|
649
|
+
`the changed-file list at ${path} could not be read: ${(e as Error).message}. ` +
|
|
650
|
+
`A diff that could not be taken is not a pull request that touches nothing`,
|
|
651
|
+
};
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
// Entries are carried RAW, trimmed only. This function decides whether the
|
|
655
|
+
// list is a reading; `readPayload` decides what each path means, through
|
|
656
|
+
// `normaliseRepoPath`. Normalising here too would be two normalisers over
|
|
657
|
+
// one input — and the weaker one would win silently, because it runs first.
|
|
658
|
+
// `normaliseRepoPath` collapses dot segments, strips a `:line` suffix and
|
|
659
|
+
// refuses git's C-quoted form; stripping `./` is the only thing the reader
|
|
660
|
+
// that used to live here could do.
|
|
661
|
+
const files = raw.split("\n").map(l => l.trim()).filter(p => p.length > 0);
|
|
662
|
+
if (files.length === 0) {
|
|
663
|
+
return {
|
|
664
|
+
status: "UNMEASURED",
|
|
665
|
+
files: null,
|
|
666
|
+
reason: "CHANGED_FILES_EMPTY",
|
|
667
|
+
detail:
|
|
668
|
+
`the changed-file list at ${path} names no paths at all. A pull request that ` +
|
|
669
|
+
`changes nothing is not a state this input can be in, so the diff was taken and ` +
|
|
670
|
+
`lost rather than taken and empty — and reading it as empty would report every ` +
|
|
671
|
+
`blocking finding as naming a file outside the pull request`,
|
|
672
|
+
};
|
|
673
|
+
}
|
|
674
|
+
|
|
675
|
+
return {
|
|
676
|
+
status: "MEASURED",
|
|
677
|
+
files,
|
|
678
|
+
reason: null,
|
|
679
|
+
detail: `${files.length} changed path(s) read from ${path}`,
|
|
680
|
+
};
|
|
681
|
+
}
|
|
682
|
+
|
|
683
|
+
// `unlocatableBlockingFinding` lived here and is gone. It was #1204's
|
|
684
|
+
// refusal predicate, and the merge with CRC-B7 retired the refusal; the
|
|
685
|
+
// comparison it performed now happens inside `readPayload` against
|
|
686
|
+
// `normaliseRepoPath`, which is the stronger reader. Deleted rather than
|
|
687
|
+
// left exported with no caller — `lib/ai-review-rounds.ts` (CRC-N4) and
|
|
688
|
+
// `lib/finding-jury.ts` (CRC-B4) are both open issues about exactly that,
|
|
689
|
+
// and adding a third would be the cheapest way to pretend this merge kept
|
|
690
|
+
// more than it did.
|
|
691
|
+
|
|
250
692
|
export interface AiReviewFindingsReading {
|
|
251
693
|
/** The single discriminator. Everything else is a projection of the same pass. */
|
|
252
694
|
outcome: AiReviewOutcome;
|
|
@@ -265,6 +707,48 @@ export interface AiReviewFindingsReading {
|
|
|
265
707
|
unmeasuredReasons: AiReviewUnmeasuredReason[];
|
|
266
708
|
/** The producing code's own sentences, one per reason or blocking finding. */
|
|
267
709
|
detail: string[];
|
|
710
|
+
/** How the pull request's changed-file list was read, and whether it was. */
|
|
711
|
+
scope: AiReviewScopeReading;
|
|
712
|
+
/**
|
|
713
|
+
* Blocking findings naming a file the pull request does not touch — CARRIED,
|
|
714
|
+
* never dropped, and `null` when the scope check did not run.
|
|
715
|
+
*
|
|
716
|
+
* `null` rather than `[]` for the did-not-run case on purpose: an empty list
|
|
717
|
+
* and a check nobody performed are the states this module exists to keep
|
|
718
|
+
* apart. `scope.status` is the discriminator; this is a projection of it.
|
|
719
|
+
*/
|
|
720
|
+
unlocatableReported: unknown[] | null;
|
|
721
|
+
/**
|
|
722
|
+
* Changed-file entries this reader could not normalise and DROPPED from the
|
|
723
|
+
* comparison set (#1472) — RAW, named, in list order.
|
|
724
|
+
*
|
|
725
|
+
* Three states, and the middle one is the reason this is not a count.
|
|
726
|
+
* `null` is "no list was supplied, so nothing was read in full or in part";
|
|
727
|
+
* `[]` is "a list was read and every entry of it was comparable"; a
|
|
728
|
+
* non-empty list is "a list was read and these entries were not", which is
|
|
729
|
+
* a reading over a NARROWER set than the pull request actually touched. A
|
|
730
|
+
* reading that narrowed itself and did not say so is indistinguishable from
|
|
731
|
+
* a complete one — `.claude/rules/config-access.md`'s *Silent Default
|
|
732
|
+
* Substitution*, in the place it decides a required check.
|
|
733
|
+
*/
|
|
734
|
+
scopeDropped: string[] | null;
|
|
735
|
+
/**
|
|
736
|
+
* CRC-B7's tag for each entry of `reported`, BY PAYLOAD INDEX, or `null`
|
|
737
|
+
* when there was no payload to tag.
|
|
738
|
+
*
|
|
739
|
+
* Parallel to `reported` rather than keyed, for the reason
|
|
740
|
+
* `AiReviewJuryGate.wouldWithhold` is positional: a map from a finding
|
|
741
|
+
* identity would be a second derivation of that identity over a list
|
|
742
|
+
* already produced in order, and two findings sharing a key would share a
|
|
743
|
+
* tag. An entry is `null` when the finding's severity is one the contract
|
|
744
|
+
* does not declare — unclassified, which is not the same as `Nit`.
|
|
745
|
+
*
|
|
746
|
+
* Computed ONCE, during the payload pass, where `touched` exists. A
|
|
747
|
+
* renderer that re-derived it would have to rebuild the changed-path set,
|
|
748
|
+
* which is a second normaliser over the one input `partitionChangedFiles`
|
|
749
|
+
* already reduced.
|
|
750
|
+
*/
|
|
751
|
+
findingTags: (Severity | null)[] | null;
|
|
268
752
|
}
|
|
269
753
|
|
|
270
754
|
/**
|
|
@@ -279,10 +763,135 @@ export function severityBlocks(severity: unknown): boolean | null {
|
|
|
279
763
|
return blocks === undefined ? null : blocks;
|
|
280
764
|
}
|
|
281
765
|
|
|
766
|
+
/**
|
|
767
|
+
* Whether a finding names code this pull request touched. FOUR states, and
|
|
768
|
+
* the first two are the ones a boolean would destroy.
|
|
769
|
+
*
|
|
770
|
+
* `NOT_CHECKED` is "nobody handed this run a changed-file list", and
|
|
771
|
+
* `UNDECIDABLE` is "a list was read and this finding's path could not be
|
|
772
|
+
* compared to it". Neither is `PRE_EXISTING`, and collapsing either into it
|
|
773
|
+
* is the fail-open CRC-B7's first cut shipped: a spelling the comparison
|
|
774
|
+
* cannot read is never in the set, so every unreadable input demoted a
|
|
775
|
+
* `critical` to CLEAN. The direction this stage is allowed to be wrong in is
|
|
776
|
+
* toward blocking.
|
|
777
|
+
*
|
|
778
|
+
* **ONE binding, and the only place the question is answered.** `readPayload`
|
|
779
|
+
* asks it to decide whether a blocking finding is demoted; `findingTag` asks
|
|
780
|
+
* it to decide what the finding is labelled. Two sites answering it
|
|
781
|
+
* separately would be the fourth shape in
|
|
782
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — behaviourally one decider,
|
|
783
|
+
* of which a mutation leaves the other holding every case up — and they would
|
|
784
|
+
* be free to disagree, which is a run whose annotation says `Pre-existing`
|
|
785
|
+
* about a finding that blocked it.
|
|
786
|
+
*
|
|
787
|
+
* Both sides of the comparison go through `normaliseRepoPath`, which is also
|
|
788
|
+
* what makes the drop in `partitionChangedFiles` safe: an entry is dropped
|
|
789
|
+
* exactly when it normalises to `null`, and a finding naming that same path
|
|
790
|
+
* answers `UNDECIDABLE` here.
|
|
791
|
+
*/
|
|
792
|
+
export type FindingPathScope = "NOT_CHECKED" | "UNDECIDABLE" | "IN_DIFF" | "PRE_EXISTING";
|
|
793
|
+
|
|
794
|
+
export function findingPathScope(
|
|
795
|
+
finding: Record<string, unknown>,
|
|
796
|
+
touched: ReadonlySet<string> | null,
|
|
797
|
+
): FindingPathScope {
|
|
798
|
+
if (touched === null) return "NOT_CHECKED";
|
|
799
|
+
// `normaliseRepoPath` answers `null` for a non-string as well as for a
|
|
800
|
+
// string it cannot read, so there is no separate type test here. Whether a
|
|
801
|
+
// non-string `file` is additionally a CONTRACT violation is a different
|
|
802
|
+
// question with a different answer per severity, and `readPayload` owns it.
|
|
803
|
+
const named = normaliseRepoPath(finding[AI_REVIEW_FINDING_FIELDS.file]);
|
|
804
|
+
if (named === null) return "UNDECIDABLE";
|
|
805
|
+
return touched.has(named) ? "IN_DIFF" : "PRE_EXISTING";
|
|
806
|
+
}
|
|
807
|
+
|
|
808
|
+
/**
|
|
809
|
+
* CRC-B7's tag for one finding — `Important`, `Nit` or `Pre-existing`.
|
|
810
|
+
*
|
|
811
|
+
* A COMPOSITION of the two deciders that already exist, and not a third
|
|
812
|
+
* table. Attribution is asked first because it outranks magnitude: a defect
|
|
813
|
+
* the change did not introduce is `Pre-existing` whether it is `critical` or
|
|
814
|
+
* `info`, which is the whole of "a pre-existing bug does not read as the
|
|
815
|
+
* author's fault". Below that the tag is `severityBlocks`' own answer
|
|
816
|
+
* re-spelt — blocking is `Important`, advisory is `Nit` — read from
|
|
817
|
+
* `AI_REVIEW_SEVERITIES` rather than from a second list of severity words.
|
|
818
|
+
*
|
|
819
|
+
* `null` for a severity the contract does not declare. That reading is
|
|
820
|
+
* already UNMEASURED by the time anything displays it, and a guessed
|
|
821
|
+
* `Important` would be the module inventing the classification it refuses the
|
|
822
|
+
* payload for omitting.
|
|
823
|
+
*
|
|
824
|
+
* Applied to EVERY finding, advisory ones included, which is wider than the
|
|
825
|
+
* demotion in `readPayload` and deliberately so: the demotion changes what
|
|
826
|
+
* blocks and must only ever touch findings that would block, while the tag
|
|
827
|
+
* changes what a maintainer reads and an `info` about code on `main` is
|
|
828
|
+
* misattributed exactly as badly as a `critical` is. It decides nothing —
|
|
829
|
+
* `aiReviewExitCode` never sees it.
|
|
830
|
+
*/
|
|
831
|
+
export function findingTag(
|
|
832
|
+
finding: Record<string, unknown>,
|
|
833
|
+
touched: ReadonlySet<string> | null,
|
|
834
|
+
): Severity | null {
|
|
835
|
+
if (findingPathScope(finding, touched) === "PRE_EXISTING") return "Pre-existing";
|
|
836
|
+
const blocks = severityBlocks(finding[AI_REVIEW_SEVERITY_KEY]);
|
|
837
|
+
return blocks === null ? null : blocks ? "Important" : "Nit";
|
|
838
|
+
}
|
|
839
|
+
|
|
840
|
+
/**
|
|
841
|
+
* The rank an untagged finding sorts at — below every declared tag, derived
|
|
842
|
+
* from the table rather than written as a literal, so a fourth tag does not
|
|
843
|
+
* leave this number sitting in the middle of the order.
|
|
844
|
+
*/
|
|
845
|
+
export const UNTAGGED_RANK = Object.keys(SEVERITY_RANK).length;
|
|
846
|
+
|
|
847
|
+
/**
|
|
848
|
+
* CRC-B7's sort: payload indices, in the order they should be DISPLAYED.
|
|
849
|
+
*
|
|
850
|
+
* Indices rather than rendered strings, because the index is the one thing
|
|
851
|
+
* the display order must not change. `renderFinding` prints `finding
|
|
852
|
+
* <payload index>` and the blocking annotation and the advisory notice share
|
|
853
|
+
* that numbering, so this reorders the lines and renumbers nothing —
|
|
854
|
+
* `test/ai-review-advisory-findings.test.ts` AD-2 reds on the other
|
|
855
|
+
* arrangement, correctly.
|
|
856
|
+
*
|
|
857
|
+
* **ONE comparator, exported, and the only ordering in this module.** The
|
|
858
|
+
* ties break on the payload index rather than on `Array.prototype.sort`'s
|
|
859
|
+
* stability, so the order is a total function of the input: a run that
|
|
860
|
+
* printed findings in one order and a re-run that printed them in another
|
|
861
|
+
* would be two readings of one payload.
|
|
862
|
+
*/
|
|
863
|
+
export function tagOrder(
|
|
864
|
+
tags: readonly (Severity | null)[] | null,
|
|
865
|
+
indices: readonly number[],
|
|
866
|
+
): number[] {
|
|
867
|
+
const rankOf = (i: number): number => {
|
|
868
|
+
const tag = tags?.[i] ?? null;
|
|
869
|
+
return tag === null ? UNTAGGED_RANK : SEVERITY_RANK[tag];
|
|
870
|
+
};
|
|
871
|
+
return [...indices].sort((a, b) => rankOf(a) - rankOf(b) || a - b);
|
|
872
|
+
}
|
|
873
|
+
|
|
874
|
+
/**
|
|
875
|
+
* Every finding's tag, by payload index. Non-objects tag `null`: they are
|
|
876
|
+
* already a `FINDING_NOT_AN_OBJECT` reason, and a shape with no severity has
|
|
877
|
+
* no tag to carry.
|
|
878
|
+
*/
|
|
879
|
+
function tagsForPayload(
|
|
880
|
+
list: readonly unknown[],
|
|
881
|
+
touched: ReadonlySet<string> | null,
|
|
882
|
+
): (Severity | null)[] {
|
|
883
|
+
return list.map(item =>
|
|
884
|
+
item !== null && typeof item === "object" && !Array.isArray(item)
|
|
885
|
+
? findingTag(item as Record<string, unknown>, touched)
|
|
886
|
+
: null,
|
|
887
|
+
);
|
|
888
|
+
}
|
|
889
|
+
|
|
282
890
|
function unmeasured(
|
|
283
891
|
reasons: AiReviewUnmeasuredReason[],
|
|
284
892
|
detail: string[],
|
|
285
893
|
reported: unknown[] | null = null,
|
|
894
|
+
findingTags: (Severity | null)[] | null = null,
|
|
286
895
|
): AiReviewFindingsReading {
|
|
287
896
|
return {
|
|
288
897
|
outcome: "UNMEASURED",
|
|
@@ -292,21 +901,169 @@ function unmeasured(
|
|
|
292
901
|
verdict: null,
|
|
293
902
|
unmeasuredReasons: reasons,
|
|
294
903
|
detail,
|
|
904
|
+
scope: scopeNotSupplied(),
|
|
905
|
+
unlocatableReported: null,
|
|
906
|
+
scopeDropped: null,
|
|
907
|
+
findingTags,
|
|
295
908
|
};
|
|
296
909
|
}
|
|
297
910
|
|
|
911
|
+
/**
|
|
912
|
+
* The ONE place a scope reading meets a payload reading.
|
|
913
|
+
*
|
|
914
|
+
* Every reading is built carrying the NOT_SUPPLIED default and passes through
|
|
915
|
+
* here. A second site that set `scope`, or that raised a reading on a refused
|
|
916
|
+
* scope, would be a second statement about the same input and the two could
|
|
917
|
+
* disagree.
|
|
918
|
+
*
|
|
919
|
+
* A scope reading that REFUSES raises the whole reading, carrying the
|
|
920
|
+
* payload's own reasons and findings with it rather than replacing them:
|
|
921
|
+
* "the diff could not be taken" and "the payload is not JSON" are both true
|
|
922
|
+
* of such a run, and a reader fixing one needs to see the other.
|
|
923
|
+
*/
|
|
924
|
+
function withScope(
|
|
925
|
+
reading: AiReviewFindingsReading,
|
|
926
|
+
scope: AiReviewScopeReading,
|
|
927
|
+
unlocatableReported: unknown[] | null,
|
|
928
|
+
scopeDropped: string[] | null,
|
|
929
|
+
): AiReviewFindingsReading {
|
|
930
|
+
const merged =
|
|
931
|
+
scope.status === "UNMEASURED"
|
|
932
|
+
? unmeasured(
|
|
933
|
+
[...reading.unmeasuredReasons, scope.reason],
|
|
934
|
+
[...reading.detail, scope.detail],
|
|
935
|
+
reading.reported,
|
|
936
|
+
reading.findingTags,
|
|
937
|
+
)
|
|
938
|
+
: reading;
|
|
939
|
+
return { ...merged, scope, unlocatableReported, scopeDropped };
|
|
940
|
+
}
|
|
941
|
+
|
|
298
942
|
/**
|
|
299
943
|
* Read a findings payload and decide what it means.
|
|
300
944
|
*
|
|
301
945
|
* `raw` is `null` for "there was no payload at all", which is a reading and
|
|
302
946
|
* not an error: a job whose reviewer never wrote anything has not passed a
|
|
303
947
|
* review, it has not had one.
|
|
948
|
+
*
|
|
949
|
+
* `scope` is the pull request's changed-file reading, and what this function
|
|
950
|
+
* DOES with it is CRC-B7 (CODE-REVIEW-CONVERGENCE-SPEC): a finding naming no
|
|
951
|
+
* file this pull request touched is tagged `Pre-existing` and does not block,
|
|
952
|
+
* so a bug that was already on `main` does not read as the change's fault.
|
|
953
|
+
* `ai-review` reads the MERGE REF, so without this every defect on `main` is
|
|
954
|
+
* reported against whichever pull request is standing closest — nine of them
|
|
955
|
+
* at once on 2026-10-23.
|
|
956
|
+
*
|
|
957
|
+
* ## #1204 and CRC-B7 answered the same question and this merge picked one
|
|
958
|
+
*
|
|
959
|
+
* Both asked *does this finding apply to this pull request?* over the same
|
|
960
|
+
* input. #1204 refused — `BLOCKING_FINDING_UNLOCATABLE`, a red required
|
|
961
|
+
* check. CRC-B7 demotes. **CRC-B7 owns the case**, because #1204's answer
|
|
962
|
+
* makes its own motivating measurement worse: under it each of those nine
|
|
963
|
+
* findings becomes a REFUSING required check, so every pull request standing
|
|
964
|
+
* near a defect on `main` is unmergeable until somebody fixes `main`. That is
|
|
965
|
+
* worse than the state it was fixing. CRC-B7 also grades the error direction,
|
|
966
|
+
* which the refusal does not: an undecidable path keeps blocking, and a
|
|
967
|
+
* non-string path is a contract violation rather than a demotion input.
|
|
968
|
+
*
|
|
969
|
+
* What #1204 keeps is the INPUT layer — `scope`, three states as a type
|
|
970
|
+
* rather than as conventions over a nullable array. It is the only side that
|
|
971
|
+
* can tell "nobody handed this run a list" from "every finding was
|
|
972
|
+
* locatable", and those are the two readings a green check must not conflate.
|
|
973
|
+
* It defaults to NOT_SUPPLIED, under which nothing is demoted and the reading
|
|
974
|
+
* is exactly what it was before any of this existed.
|
|
975
|
+
*
|
|
976
|
+
* The finding's DECLARED `file` is the input, not a path mined out of its
|
|
977
|
+
* prose. `blockingContractViolations` already refuses a blocking finding that
|
|
978
|
+
* carries none, and `lib/finding-jury.ts`'s `citedPaths` text-mines only
|
|
979
|
+
* because the arbiter's findings arrive as prose. Mining a field the payload
|
|
980
|
+
* declares would be a second decider for a question already answered.
|
|
304
981
|
*/
|
|
305
|
-
export function readAiReviewFindings(
|
|
982
|
+
export function readAiReviewFindings(
|
|
983
|
+
raw: string | null,
|
|
984
|
+
scope: AiReviewScopeReading = scopeNotSupplied(),
|
|
985
|
+
): AiReviewFindingsReading {
|
|
986
|
+
const preExisting: unknown[] = [];
|
|
987
|
+
// Appended to by `readPayload`, for the same reason `preExisting` is: the
|
|
988
|
+
// entries belong to the reading its caller composes, and every early return
|
|
989
|
+
// in there is a state in which the split had not happened yet.
|
|
990
|
+
const dropped: string[] = [];
|
|
991
|
+
const base = readPayload(
|
|
992
|
+
raw,
|
|
993
|
+
scope.status === "MEASURED" ? scope.files : undefined,
|
|
994
|
+
preExisting,
|
|
995
|
+
dropped,
|
|
996
|
+
);
|
|
997
|
+
return withScope(
|
|
998
|
+
base,
|
|
999
|
+
scope,
|
|
1000
|
+
scope.status === "MEASURED" ? preExisting : null,
|
|
1001
|
+
scope.status === "MEASURED" ? dropped : null,
|
|
1002
|
+
);
|
|
1003
|
+
}
|
|
1004
|
+
|
|
1005
|
+
/**
|
|
1006
|
+
* The payload pass itself. `preExisting` is appended to rather than returned,
|
|
1007
|
+
* because the findings it collects belong to the reading its caller composes
|
|
1008
|
+
* and every early return here is a state in which none were collected.
|
|
1009
|
+
*
|
|
1010
|
+
* It holds the findings CRC-B7 demoted. A COUNT would not do: "three were
|
|
1011
|
+
* demoted" and "these three were demoted" differ exactly when somebody wants
|
|
1012
|
+
* to know whether the demotion was right, which is the only question anybody
|
|
1013
|
+
* asks of a demotion.
|
|
1014
|
+
*/
|
|
1015
|
+
function readPayload(
|
|
1016
|
+
raw: string | null,
|
|
1017
|
+
changedFiles: readonly string[] | undefined,
|
|
1018
|
+
preExisting: unknown[],
|
|
1019
|
+
dropped: string[],
|
|
1020
|
+
): AiReviewFindingsReading {
|
|
306
1021
|
if (raw === null) {
|
|
307
1022
|
return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
|
|
308
1023
|
}
|
|
309
1024
|
|
|
1025
|
+
if (changedFiles !== undefined && changedFiles.length === 0) {
|
|
1026
|
+
return unmeasured(
|
|
1027
|
+
["CHANGED_FILES_EMPTY"],
|
|
1028
|
+
[
|
|
1029
|
+
"a changed-file list was supplied and was empty. A pull request always touches " +
|
|
1030
|
+
"something, so this is a reading that failed rather than a pull request that " +
|
|
1031
|
+
"changed nothing — and taken at face value every finding would be tagged " +
|
|
1032
|
+
"Pre-existing and none would block.",
|
|
1033
|
+
],
|
|
1034
|
+
);
|
|
1035
|
+
}
|
|
1036
|
+
let touched: Set<string> | null = null;
|
|
1037
|
+
if (changedFiles !== undefined) {
|
|
1038
|
+
// #1472. ONE unnormalisable entry used to refuse the WHOLE reading, so a
|
|
1039
|
+
// repository holding a single tracked path with a space in it could never
|
|
1040
|
+
// obtain a scope reading at all — `docs/my file.md` was enough, and the
|
|
1041
|
+
// remedy the refusal named (`-z`, `core.quotePath=false`) does not apply,
|
|
1042
|
+
// because git emits a space literally and the regex rejects it literally.
|
|
1043
|
+
//
|
|
1044
|
+
// The comparison is PER FINDING, so one bad entry says nothing about the
|
|
1045
|
+
// others. The entry is dropped, the drop is NAMED, and the findings over
|
|
1046
|
+
// normalisable paths are adjudicated as before.
|
|
1047
|
+
const { readable, dropped: unreadable } = partitionChangedFiles(changedFiles);
|
|
1048
|
+
dropped.push(...unreadable);
|
|
1049
|
+
// The refusal is NARROWED, not deleted. With nothing readable left,
|
|
1050
|
+
// `touched` is empty, every finding is tagged Pre-existing and the run
|
|
1051
|
+
// reports a green check for a review that found something — which is the
|
|
1052
|
+
// one input the original refusal was right about.
|
|
1053
|
+
if (readable.length === 0) {
|
|
1054
|
+
return unmeasured(
|
|
1055
|
+
["CHANGED_FILES_UNREADABLE"],
|
|
1056
|
+
[
|
|
1057
|
+
`all ${unreadable.length} changed-file entr(ies) could not be read as a repository ` +
|
|
1058
|
+
`path: ${unreadable.map(p => JSON.stringify(p)).join(", ")}. ` +
|
|
1059
|
+
`Comparing against a list with nothing readable left in it would tag every ` +
|
|
1060
|
+
`finding Pre-existing. Produce the list with -z or core.quotePath=false`,
|
|
1061
|
+
],
|
|
1062
|
+
);
|
|
1063
|
+
}
|
|
1064
|
+
touched = new Set(readable);
|
|
1065
|
+
}
|
|
1066
|
+
|
|
310
1067
|
let doc: unknown;
|
|
311
1068
|
try {
|
|
312
1069
|
doc = JSON.parse(raw);
|
|
@@ -349,6 +1106,8 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
349
1106
|
const reasons: AiReviewUnmeasuredReason[] = [];
|
|
350
1107
|
const detail: string[] = [];
|
|
351
1108
|
const blocking: unknown[] = [];
|
|
1109
|
+
/** How many findings CRC-B7 demoted. See the `agreed` computation below. */
|
|
1110
|
+
let demoted = 0;
|
|
352
1111
|
|
|
353
1112
|
list.forEach((item, i) => {
|
|
354
1113
|
if (item === null || typeof item !== "object" || Array.isArray(item)) {
|
|
@@ -390,8 +1149,84 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
390
1149
|
);
|
|
391
1150
|
return;
|
|
392
1151
|
}
|
|
1152
|
+
// CRC-B7, and AFTER the contract check rather than before it. A finding
|
|
1153
|
+
// with no declared `file` cannot be tagged either way, and it has
|
|
1154
|
+
// already been refused as incomplete one branch up — so by here `file`
|
|
1155
|
+
// is known present, and the tag is decidable rather than guessed.
|
|
1156
|
+
//
|
|
1157
|
+
// It DEMOTES, it does not drop (CRC-B8). The finding stays in
|
|
1158
|
+
// `reported`, so `advisoryReported` carries it into the notice and a
|
|
1159
|
+
// maintainer still sees it; it simply stops reddening a required check
|
|
1160
|
+
// over a defect the diff did not introduce and cannot fix.
|
|
1161
|
+
if (touched !== null) {
|
|
1162
|
+
const declared = finding[AI_REVIEW_FINDING_FIELDS.file];
|
|
1163
|
+
// A non-string `file` is a CONTRACT violation, not a demotion input.
|
|
1164
|
+
// `blockingContractViolations` refuses `undefined`, `null` and the
|
|
1165
|
+
// empty string and lets a number or an object through, so without
|
|
1166
|
+
// this a finding declaring `file: {}` stringifies to
|
|
1167
|
+
// `[object Object]`, matches nothing, and demotes itself.
|
|
1168
|
+
if (typeof declared !== "string") {
|
|
1169
|
+
reasons.push("BLOCKING_FINDING_INCOMPLETE");
|
|
1170
|
+
detail.push(
|
|
1171
|
+
`finding ${i} blocks and declares a non-string ` +
|
|
1172
|
+
`'${AI_REVIEW_FINDING_FIELDS.file}' (${typeof declared}). A path that is not a ` +
|
|
1173
|
+
`string cannot be compared to the changed-file list, and a comparison that ` +
|
|
1174
|
+
`cannot be made is not a finding that is pre-existing`,
|
|
1175
|
+
);
|
|
1176
|
+
return;
|
|
1177
|
+
}
|
|
1178
|
+
// THE one decider, shared with `findingTag`. Re-reading the path
|
|
1179
|
+
// here would let the demotion and the tag disagree about one finding.
|
|
1180
|
+
const scoped = findingPathScope(finding, touched);
|
|
1181
|
+
// Undecidable is NOT pre-existing. The finding is well-formed and
|
|
1182
|
+
// this reader simply cannot resolve its path, so it keeps blocking —
|
|
1183
|
+
// the direction this stage is allowed to be wrong in.
|
|
1184
|
+
if (scoped === "UNDECIDABLE") {
|
|
1185
|
+
detail.push(
|
|
1186
|
+
`finding ${i} declares ${JSON.stringify(declared)}, which could not be read as a ` +
|
|
1187
|
+
`repository path, so it could not be compared to the changed-file list. It ` +
|
|
1188
|
+
`keeps blocking: undecidable is not pre-existing`,
|
|
1189
|
+
);
|
|
1190
|
+
} else if (scoped === "PRE_EXISTING") {
|
|
1191
|
+
demoted += 1;
|
|
1192
|
+
// #1204's half that survived the merge: WHICH findings were
|
|
1193
|
+
// demoted, not just how many. The scope line reports it, so a
|
|
1194
|
+
// reader can ask whether a demotion was right — the only question
|
|
1195
|
+
// anybody asks of one.
|
|
1196
|
+
preExisting.push(item);
|
|
1197
|
+
detail.push(
|
|
1198
|
+
`finding ${i} is Pre-existing: it names ${JSON.stringify(
|
|
1199
|
+
finding[AI_REVIEW_FINDING_FIELDS.file],
|
|
1200
|
+
)}, which this pull request does not touch. It is reported and does not block — ` +
|
|
1201
|
+
`ai-review reads the merge ref, so a defect already on the base branch is ` +
|
|
1202
|
+
`adjudicated against whichever pull request is standing closest to it`,
|
|
1203
|
+
);
|
|
1204
|
+
return;
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1207
|
+
// CRC-B4's verifier quorum does NOT appear here, and its absence is
|
|
1208
|
+
// the decision rather than an omission.
|
|
1209
|
+
//
|
|
1210
|
+
// A quorum that subtracts from this list is a gate whose input is the
|
|
1211
|
+
// thing it gates: the verifier reads the cited file at the HEAD
|
|
1212
|
+
// checkout, so code that argues itself clean would be voting on the
|
|
1213
|
+
// finding about itself. And the group that would cast those votes is
|
|
1214
|
+
// not independent — `AI_REVIEW_ALLOWED_TOOLS` grants
|
|
1215
|
+
// `Read,Grep,Glob,Write` and `AI_REVIEW_DENY_RULES` denies `Task`, so
|
|
1216
|
+
// a verifier step cannot spawn anything and N votes from one
|
|
1217
|
+
// invocation are one opinion written down N times.
|
|
1218
|
+
//
|
|
1219
|
+
// Until both are fixed — structural independence, and a base-ref read
|
|
1220
|
+
// — the ballot is RECORDED and never acted on. `main` runs the gate
|
|
1221
|
+
// for the ledger and the annotation; this list is untouched by it.
|
|
1222
|
+
// See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
|
|
393
1223
|
blocking.push(item);
|
|
394
|
-
|
|
1224
|
+
// Tagged through the same binding every other render uses. By here the
|
|
1225
|
+
// tag is `Important` by construction — the severity blocks and the
|
|
1226
|
+
// finding is not Pre-existing, or the branch above would have returned
|
|
1227
|
+
// — so this list is not re-ordered: a sort over one rank reorders
|
|
1228
|
+
// nothing, and applying one would be a comparator no case could redden.
|
|
1229
|
+
detail.push(renderFinding(i, finding, findingTag(finding, touched)));
|
|
395
1230
|
}
|
|
396
1231
|
});
|
|
397
1232
|
|
|
@@ -412,12 +1247,26 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
412
1247
|
}
|
|
413
1248
|
}
|
|
414
1249
|
|
|
415
|
-
|
|
1250
|
+
const tags = tagsForPayload(list, touched);
|
|
1251
|
+
|
|
1252
|
+
if (reasons.length > 0) return unmeasured(reasons, detail, list, tags);
|
|
416
1253
|
|
|
417
1254
|
// The decision, and the only place it is made. `verdict` is compared to it
|
|
418
1255
|
// afterwards; it never contributes to it.
|
|
419
1256
|
const blocked = blocking.length > 0;
|
|
420
|
-
|
|
1257
|
+
// The agreement is measured BEFORE CRC-B7's demotion, not after it.
|
|
1258
|
+
//
|
|
1259
|
+
// The reviewer is not given the pull request's file list, so it cannot know
|
|
1260
|
+
// a finding is pre-existing and its `BLOCK` over one is honest. Comparing
|
|
1261
|
+
// its word against the post-demotion count would turn every successful
|
|
1262
|
+
// demotion into a CONTRADICTION — the arm would fire on the mechanism
|
|
1263
|
+
// working, which is the loudest possible way to be wrong.
|
|
1264
|
+
//
|
|
1265
|
+
// The real contradiction #1178 exists for is untouched: a `BLOCK` over a
|
|
1266
|
+
// payload whose findings are ALL advisory has `demoted === 0`, so it still
|
|
1267
|
+
// fires. Measured at roughly 6 of 20 runs when that was written.
|
|
1268
|
+
const wouldBlock = blocked || demoted > 0;
|
|
1269
|
+
const agreed = verdict === (wouldBlock ? AI_REVIEW_BLOCK_VERDICT : AI_REVIEW_PASS_VERDICT);
|
|
421
1270
|
const outcome: AiReviewOutcome = !agreed ? "CONTRADICTION" : blocked ? "BLOCKED" : "CLEAN";
|
|
422
1271
|
|
|
423
1272
|
return {
|
|
@@ -428,25 +1277,180 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
428
1277
|
verdict,
|
|
429
1278
|
unmeasuredReasons: [],
|
|
430
1279
|
detail,
|
|
1280
|
+
// Both of these are `withScope`'s to set, and it is the only site that
|
|
1281
|
+
// sets either. A value here would be a second statement about the same
|
|
1282
|
+
// input, and the two could disagree.
|
|
1283
|
+
scope: scopeNotSupplied(),
|
|
1284
|
+
unlocatableReported: null,
|
|
1285
|
+
scopeDropped: null,
|
|
1286
|
+
findingTags: tags,
|
|
431
1287
|
};
|
|
432
1288
|
}
|
|
433
1289
|
|
|
1290
|
+
/**
|
|
1291
|
+
* The pull request's changed files, read from a newline-delimited file.
|
|
1292
|
+
*
|
|
1293
|
+
* `null` means the path was given and could not be read, which the caller
|
|
1294
|
+
* must NOT collapse into "no list was supplied" — see `readAiReviewFindings`
|
|
1295
|
+
* on why `undefined` and `[]` are different facts. This returns the third
|
|
1296
|
+
* one, and it is the same distinction a third time.
|
|
1297
|
+
*
|
|
1298
|
+
* Blank lines are dropped before the emptiness test, so a file containing
|
|
1299
|
+
* only whitespace reads as empty rather than as one unnamed file.
|
|
1300
|
+
*/
|
|
1301
|
+
/**
|
|
1302
|
+
* One repository path, in the one spelling both sides of CRC-B7's comparison
|
|
1303
|
+
* are reduced to — or `null` for "this cannot be read as a repository path".
|
|
1304
|
+
*
|
|
1305
|
+
* **`null` is the important return.** The first cut of CRC-B7 compared
|
|
1306
|
+
* `String(finding.file).toLowerCase()` against a raw list, and every input
|
|
1307
|
+
* the comparison could not read demoted a `critical` to CLEAN, because a
|
|
1308
|
+
* spelling that is never in the set is indistinguishable from a file the
|
|
1309
|
+
* pull request did not touch. Measured against a list holding `lib/mine.ts`:
|
|
1310
|
+
*
|
|
1311
|
+
* ```
|
|
1312
|
+
* CLEAN 0 blocking {} 123 "./lib/mine.ts" "lib/mine.ts:12"
|
|
1313
|
+
* CLEAN 0 blocking "lib\mine.ts" "/lib/mine.ts"
|
|
1314
|
+
* ```
|
|
1315
|
+
*
|
|
1316
|
+
* Six for six, five of them the SAME FILE spelt differently. `./x`, `/x`,
|
|
1317
|
+
* `x` and `x:12` are one file and four strings, and an equality test over
|
|
1318
|
+
* raw strings answers a different question from the one being asked.
|
|
1319
|
+
*
|
|
1320
|
+
* So both sides go through here, and a `null` on either side is a refusal
|
|
1321
|
+
* rather than a mismatch. The git C-quoted form — `"lib/\303\251.ts"`, which
|
|
1322
|
+
* git emits for a non-ASCII path unless `core.quotePath=false` — is
|
|
1323
|
+
* deliberately `null` rather than unescaped here: decoding octal escapes to
|
|
1324
|
+
* compare a path is a second parser, and the right repair is to produce the
|
|
1325
|
+
* list with `-z` or `core.quotePath=false` in the first place.
|
|
1326
|
+
*/
|
|
1327
|
+
export function normaliseRepoPath(value: unknown): string | null {
|
|
1328
|
+
if (typeof value !== "string") return null;
|
|
1329
|
+
let p = value.trim().replace(/\\/g, "/");
|
|
1330
|
+
// git's C-quoted spelling. Not comparable without a second unescaper.
|
|
1331
|
+
if (p.startsWith('"') && p.endsWith('"')) return null;
|
|
1332
|
+
p = p.replace(/^\/+/, "").replace(/:\d+(?::\d+)?$/, "");
|
|
1333
|
+
|
|
1334
|
+
// Dot segments are COLLAPSED, not stripped once. `.replace(/^\.\//, "")`
|
|
1335
|
+
// removes one leading `./` and leaves `././lib/a.ts` as `./lib/a.ts`, which
|
|
1336
|
+
// the shape test below accepts — `.` and `..` are both legal matches for
|
|
1337
|
+
// `[\w.@+-]+`. Measured on this file before the fix:
|
|
1338
|
+
//
|
|
1339
|
+
// "././lib/mine.ts" -> "./lib/mine.ts"
|
|
1340
|
+
// "lib/./mine.ts" -> "lib/./mine.ts"
|
|
1341
|
+
// "lib/../lib/mine.ts" -> "lib/../lib/mine.ts"
|
|
1342
|
+
//
|
|
1343
|
+
// Each compares unequal to `lib/mine.ts`, so a blocking finding naming the
|
|
1344
|
+
// file in one of those spellings was demoted to Pre-existing against a
|
|
1345
|
+
// change list that contained it — the same fail-open round one shipped,
|
|
1346
|
+
// in a narrower spelling. Found by the push review on this branch.
|
|
1347
|
+
//
|
|
1348
|
+
// A `..` that would leave the repository root is refused rather than
|
|
1349
|
+
// clamped: `../outside.ts` is not a repository-relative path, and turning
|
|
1350
|
+
// it into `outside.ts` invents a file this change may well have touched.
|
|
1351
|
+
const out: string[] = [];
|
|
1352
|
+
for (const segment of p.split("/")) {
|
|
1353
|
+
if (segment === "" || segment === ".") continue;
|
|
1354
|
+
if (segment === "..") {
|
|
1355
|
+
if (out.pop() === undefined) return null;
|
|
1356
|
+
continue;
|
|
1357
|
+
}
|
|
1358
|
+
out.push(segment);
|
|
1359
|
+
}
|
|
1360
|
+
p = out.join("/");
|
|
1361
|
+
if (p === "") return null;
|
|
1362
|
+
|
|
1363
|
+
return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p.toLowerCase() : null;
|
|
1364
|
+
}
|
|
1365
|
+
|
|
1366
|
+
/** What a changed-file list reduced to, split by whether it could be read. */
|
|
1367
|
+
export interface ChangedFilePartition {
|
|
1368
|
+
/**
|
|
1369
|
+
* The entries that normalised, in the one spelling both sides of the
|
|
1370
|
+
* comparison are reduced to. This is what `touched` is built from.
|
|
1371
|
+
*/
|
|
1372
|
+
readable: string[];
|
|
1373
|
+
/**
|
|
1374
|
+
* The entries that did not, RAW and in list order — so the reader can be
|
|
1375
|
+
* NAMED to whoever has to fix the tree, rather than counted at them.
|
|
1376
|
+
*/
|
|
1377
|
+
dropped: string[];
|
|
1378
|
+
}
|
|
1379
|
+
|
|
1380
|
+
/**
|
|
1381
|
+
* Split a changed-file list into the part this reader can compare against and
|
|
1382
|
+
* the part it cannot (#1472).
|
|
1383
|
+
*
|
|
1384
|
+
* **One exported binding, and the only place the split is decided.** A second
|
|
1385
|
+
* site answering "is this entry readable" would be two deciders over one
|
|
1386
|
+
* input, and a mutation of either would leave the other holding every case up
|
|
1387
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape). It is
|
|
1388
|
+
* exported so a battery has one thing to short-circuit.
|
|
1389
|
+
*
|
|
1390
|
+
* **Dropping is safe here and it is not an optimistic reading.** A narrower
|
|
1391
|
+
* `touched` can only demote MORE findings, never fewer — and the findings a
|
|
1392
|
+
* dropped entry could falsely demote are none at all, because BOTH sides of
|
|
1393
|
+
* the comparison go through `normaliseRepoPath`: an entry is dropped exactly
|
|
1394
|
+
* when it normalises to `null`, and a finding naming that same path
|
|
1395
|
+
* normalises to `null` too, which `readPayload` answers with *"it keeps
|
|
1396
|
+
* blocking: undecidable is not pre-existing"*. The set the drop could reach
|
|
1397
|
+
* and the set the drop cannot decide are the same set.
|
|
1398
|
+
*
|
|
1399
|
+
* What a drop must never be is SILENT. The caller carries `dropped` onto the
|
|
1400
|
+
* reading as `scopeDropped` and `aiReviewScopeLine` prints it on every run:
|
|
1401
|
+
* "this list was read in full" and "this list was read in part" are different
|
|
1402
|
+
* facts, and a reading over a narrowed set that does not say it was narrowed
|
|
1403
|
+
* is Silent Default Substitution (`.claude/rules/config-access.md`).
|
|
1404
|
+
*/
|
|
1405
|
+
export function partitionChangedFiles(
|
|
1406
|
+
changedFiles: readonly string[],
|
|
1407
|
+
): ChangedFilePartition {
|
|
1408
|
+
const readable: string[] = [];
|
|
1409
|
+
const dropped: string[] = [];
|
|
1410
|
+
for (const entry of changedFiles) {
|
|
1411
|
+
const normalised = normaliseRepoPath(entry);
|
|
1412
|
+
if (normalised === null) dropped.push(entry);
|
|
1413
|
+
else readable.push(normalised);
|
|
1414
|
+
}
|
|
1415
|
+
return { readable, dropped };
|
|
1416
|
+
}
|
|
1417
|
+
|
|
1418
|
+
// `readChangedFiles` lived here and is gone. It returned `null` for BOTH an
|
|
1419
|
+
// unreadable file and — via its caller — an empty one, and `main` reported
|
|
1420
|
+
// that single `null` as `CHANGED_FILES_EMPTY`. A failed `git diff` writes no
|
|
1421
|
+
// file at all, so that collapsed "the diff was lost" into "the diff was
|
|
1422
|
+
// empty", which are different facts with different repairs.
|
|
1423
|
+
// `readAiReviewChangedFiles` replaces it and keeps them apart.
|
|
1424
|
+
|
|
434
1425
|
/** Read the payload from disk. An absent file and an unreadable one differ. */
|
|
435
|
-
export function readAiReviewFindingsFile(
|
|
1426
|
+
export function readAiReviewFindingsFile(
|
|
1427
|
+
path: string,
|
|
1428
|
+
scope: AiReviewScopeReading = scopeNotSupplied(),
|
|
1429
|
+
): AiReviewFindingsReading {
|
|
436
1430
|
let raw: string;
|
|
437
1431
|
try {
|
|
438
1432
|
raw = readFileSync(path, "utf-8");
|
|
439
1433
|
} catch (e) {
|
|
440
1434
|
const code = (e as NodeJS.ErrnoException).code;
|
|
441
1435
|
if (code === "ENOENT") {
|
|
442
|
-
return
|
|
1436
|
+
return withScope(
|
|
1437
|
+
unmeasured(["FINDINGS_FILE_ABSENT"], [`no findings payload at ${path}`]),
|
|
1438
|
+
scope,
|
|
1439
|
+
null,
|
|
1440
|
+
null,
|
|
1441
|
+
);
|
|
443
1442
|
}
|
|
444
|
-
return
|
|
445
|
-
|
|
446
|
-
|
|
1443
|
+
return withScope(
|
|
1444
|
+
unmeasured(
|
|
1445
|
+
["FINDINGS_FILE_UNREADABLE"],
|
|
1446
|
+
[`the findings payload at ${path} could not be read: ${(e as Error).message}`],
|
|
1447
|
+
),
|
|
1448
|
+
scope,
|
|
1449
|
+
null,
|
|
1450
|
+
null,
|
|
447
1451
|
);
|
|
448
1452
|
}
|
|
449
|
-
return readAiReviewFindings(raw);
|
|
1453
|
+
return readAiReviewFindings(raw, scope);
|
|
450
1454
|
}
|
|
451
1455
|
|
|
452
1456
|
/** The sentence a refusal prints, or `null` when there is nothing to refuse. */
|
|
@@ -487,9 +1491,16 @@ export function aiReviewRefusal(reading: AiReviewFindingsReading): string | null
|
|
|
487
1491
|
// Used INSTEAD of `detail` rather than appended to it. The two overlap
|
|
488
1492
|
// exactly on the blocking findings, so appending would print those
|
|
489
1493
|
// twice, and a duplicate reads as two findings.
|
|
490
|
-
const counted = renderCountedFindings(reading.reported);
|
|
491
|
-
|
|
492
|
-
|
|
1494
|
+
const counted = renderCountedFindings(reading.reported, reading.findingTags);
|
|
1495
|
+
// Same sort, same binding, same payload numbering. The contradiction
|
|
1496
|
+
// arm is the one place every counted finding is printed together, so
|
|
1497
|
+
// it is where an unordered list costs the most.
|
|
1498
|
+
const ordered = tagOrder(
|
|
1499
|
+
reading.findingTags,
|
|
1500
|
+
counted.map((_, i) => i),
|
|
1501
|
+
).map(i => counted[i]);
|
|
1502
|
+
const payload = ordered.length > 0
|
|
1503
|
+
? `${ordered.join("; ")}. `
|
|
493
1504
|
: `The payload records no findings at all. `;
|
|
494
1505
|
return (
|
|
495
1506
|
`The AI review's verdict ${JSON.stringify(reading.verdict)} contradicts its ` +
|
|
@@ -509,21 +1520,293 @@ export function aiReviewExitCode(reading: AiReviewFindingsReading): number {
|
|
|
509
1520
|
return reading.outcome === "CLEAN" ? 0 : AI_REVIEW_REQUIRED_EXIT;
|
|
510
1521
|
}
|
|
511
1522
|
|
|
1523
|
+
/** The annotation title the verifier quorum's own reading is printed under. */
|
|
1524
|
+
export const AI_REVIEW_JURY_NOTICE_TITLE = "AI review verifier quorum";
|
|
1525
|
+
|
|
512
1526
|
/**
|
|
513
|
-
* The
|
|
1527
|
+
* The title the quorum's UNMEASURED state is named under.
|
|
514
1528
|
*
|
|
515
|
-
*
|
|
516
|
-
*
|
|
1529
|
+
* A SEPARATE title, because it is a different fact with a different fix: a
|
|
1530
|
+
* group that met and disagreed is a reading, and a group that did not meet
|
|
1531
|
+
* is not one. GitHub groups annotations by title, so one title for both
|
|
1532
|
+
* would make the absence read as part of the vote.
|
|
517
1533
|
*/
|
|
518
|
-
export
|
|
1534
|
+
export const AI_REVIEW_JURY_UNMEASURED_TITLE = "AI review verifier quorum UNMEASURED";
|
|
1535
|
+
|
|
1536
|
+
/**
|
|
1537
|
+
* The verifier quorum, as `main` consumes it (CRC-B4).
|
|
1538
|
+
*
|
|
1539
|
+
* **Injected, not imported**, and the reason is mechanical rather than
|
|
1540
|
+
* stylistic. This module is copied into a scratch directory by three
|
|
1541
|
+
* mutation batteries, which carry its one relative dependency —
|
|
1542
|
+
* `./ai-review-step`, which has none — along with it. `lib/ai-review-jury.ts`
|
|
1543
|
+
* pulls in the finding arbiter and the filing gate behind it, and a mutant
|
|
1544
|
+
* that dies on module resolution reports zero findings, which reads exactly
|
|
1545
|
+
* like a guard behaving differently
|
|
1546
|
+
* (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
|
|
1547
|
+
*
|
|
1548
|
+
* **The gate decides nothing.** It is consulted after the reading is
|
|
1549
|
+
* complete, its answer reaches an annotation and the finding ledger, and
|
|
1550
|
+
* `reading` is not rebuilt from it.
|
|
1551
|
+
*
|
|
1552
|
+
* So a gate that is absent, unreadable, malformed **or throwing** leaves
|
|
1553
|
+
* the verdict alone — and the last of those four is enforced by a `try`
|
|
1554
|
+
* at the call site rather than by this sentence. It is listed explicitly
|
|
1555
|
+
* because the first draft of this docblock claimed all four while only
|
|
1556
|
+
* three held: the call was outside any `catch`, so a throwing gate
|
|
1557
|
+
* propagated out of `main` and killed the process above the outcome
|
|
1558
|
+
* marker. A comment asserting a property the code lacks is the reason
|
|
1559
|
+
* nobody checks it — the instance this repository keeps is
|
|
1560
|
+
* `lib/cli-commands.ts`'s "runs every command for real" over a test that
|
|
1561
|
+
* ran one command of ten. `JG-6h` is now the assertion.
|
|
1562
|
+
*
|
|
1563
|
+
* That is the only honest arrangement while the group casting the votes
|
|
1564
|
+
* is not yet structurally independent. See `AI_REVIEW_JURY_NOTICE_TITLE`.
|
|
1565
|
+
*
|
|
1566
|
+
* **It takes the findings and nothing else.** The ballot directory is
|
|
1567
|
+
* bound by whoever supplies the gate, so this module never learns a path
|
|
1568
|
+
* and the CLI's argv contract — two positionals, `argv[2]` and up refused
|
|
1569
|
+
* — is untouched. A gate that is `null` is the whole of "no ballot".
|
|
1570
|
+
*/
|
|
1571
|
+
export interface AiReviewJuryGate {
|
|
1572
|
+
(blocking: readonly unknown[]): {
|
|
1573
|
+
/**
|
|
1574
|
+
* One entry per blocking finding, **in input order** — the sentence
|
|
1575
|
+
* saying the group would have withheld it, or `null`.
|
|
1576
|
+
*
|
|
1577
|
+
* Positional rather than keyed, and that is the contract rather than a
|
|
1578
|
+
* convenience. A map from a finding identity would be a SECOND
|
|
1579
|
+
* derivation of that identity over a list already produced in order,
|
|
1580
|
+
* and two findings sharing a key would share a vote.
|
|
1581
|
+
* `lib/finding-arbiter.ts`'s `SHARED_BALLOT` refuses exactly that one
|
|
1582
|
+
* level down — *"a vote is about a finding"*.
|
|
1583
|
+
*
|
|
1584
|
+
* **"Would have".** Nothing here subtracts: the entry is recorded and
|
|
1585
|
+
* announced, and the finding blocks exactly as it did before the group
|
|
1586
|
+
* met.
|
|
1587
|
+
*/
|
|
1588
|
+
wouldWithhold: readonly (string | null)[];
|
|
1589
|
+
/** Non-null when the ballot source could not be read. Never fatal. */
|
|
1590
|
+
unmeasured: string | null;
|
|
1591
|
+
/** One sentence per finding voted on. */
|
|
1592
|
+
detail: readonly string[];
|
|
1593
|
+
};
|
|
1594
|
+
}
|
|
1595
|
+
|
|
1596
|
+
/**
|
|
1597
|
+
* The line recording how the scope reading was taken, and the two counts a
|
|
1598
|
+
* reader needs to see differ when the gate fires (#1204).
|
|
1599
|
+
*
|
|
1600
|
+
* The number of findings PRODUCED and the number ALLOWED TO BLOCK are both
|
|
1601
|
+
* printed, because a review that quietly demoted a finding and a review that
|
|
1602
|
+
* never had one are otherwise the same output. The blocking count is
|
|
1603
|
+
* `withheld` under an UNMEASURED reading rather than `0` — the decision is
|
|
1604
|
+
* withheld there, and printing a number would be inventing one.
|
|
1605
|
+
*
|
|
1606
|
+
* It also reports its own COVERAGE of the changed-file list (#1472): a scan
|
|
1607
|
+
* that reports a verdict should say how much of its input it read. An entry
|
|
1608
|
+
* this reader could not normalise is dropped from the comparison rather than
|
|
1609
|
+
* refusing the whole run, so `dropped` is what keeps "the list was read in
|
|
1610
|
+
* full" apart from "the list was read in part" — and the entries are NAMED,
|
|
1611
|
+
* because a warning that does not say what was missing is a warning nobody
|
|
1612
|
+
* can act on. `not checked`, `0` and a named list are three facts, not one.
|
|
1613
|
+
*/
|
|
1614
|
+
export function aiReviewScopeLine(reading: AiReviewFindingsReading): string {
|
|
1615
|
+
const produced = reading.reported?.length ?? 0;
|
|
1616
|
+
const blocking =
|
|
1617
|
+
reading.blockingReported === null ? "withheld" : String(reading.blockingReported.length);
|
|
1618
|
+
const unlocatable =
|
|
1619
|
+
reading.unlocatableReported === null ? "not checked" : String(reading.unlocatableReported.length);
|
|
1620
|
+
const drops = reading.scopeDropped;
|
|
1621
|
+
const dropped =
|
|
1622
|
+
drops === null
|
|
1623
|
+
? "not checked"
|
|
1624
|
+
: drops.length === 0
|
|
1625
|
+
? "0"
|
|
1626
|
+
: `${drops.length} (${drops.map(p => JSON.stringify(p)).join(", ")}), ` +
|
|
1627
|
+
`so this comparison ran over a NARROWER set than the pull request touched`;
|
|
1628
|
+
return (
|
|
1629
|
+
`${AI_REVIEW_SCOPE_LINE} ${reading.scope.status} — findings reported: ${produced}, ` +
|
|
1630
|
+
`allowed to block: ${blocking}, unlocatable: ${unlocatable}, ` +
|
|
1631
|
+
`changed-file entries dropped: ${dropped}. ${reading.scope.detail}`
|
|
1632
|
+
);
|
|
1633
|
+
}
|
|
1634
|
+
|
|
1635
|
+
// `parseFindingsArgv` and `AiReviewFindingsArgv` lived here and are gone.
|
|
1636
|
+
// The parser refused a SECOND POSITIONAL argument by design, which is
|
|
1637
|
+
// exactly the invocation CRC-B7 deploys, so the flag CLI and the
|
|
1638
|
+
// positional one could not both stand. See `main` below.
|
|
1639
|
+
//
|
|
1640
|
+
// What the parser ALSO did is kept, in `argumentsBeyondTheContract`: it
|
|
1641
|
+
// refused an argument nothing reads, rather than dropping it. Deleting the
|
|
1642
|
+
// parser silently took that with it — measured, not assumed, on the merged
|
|
1643
|
+
// tree: `main([payload, list, "extra"])` returned 0 and printed CLEAN. A
|
|
1644
|
+
// dropped argument is a caller asking for something that did not happen,
|
|
1645
|
+
// which is the same fault as a skipped check wearing different clothes.
|
|
1646
|
+
|
|
1647
|
+
/**
|
|
1648
|
+
* The arguments past the two this CLI reads. One exported binding, so the
|
|
1649
|
+
* refusal has a single site to mutate (`checks-must-be-able-to-fail.md`).
|
|
1650
|
+
*
|
|
1651
|
+
* It returns the arguments rather than a boolean because the refusal names
|
|
1652
|
+
* them: "an argument was ignored" is not something an operator can act on,
|
|
1653
|
+
* and the failing invocation is usually a workflow line nobody can see from
|
|
1654
|
+
* the log.
|
|
1655
|
+
*/
|
|
1656
|
+
export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
|
|
1657
|
+
return argv.slice(2);
|
|
1658
|
+
}
|
|
1659
|
+
|
|
1660
|
+
/**
|
|
1661
|
+
* The CLI the generated workflow step runs: the payload's path, and
|
|
1662
|
+
* optionally a second POSITIONAL path to the pull request's changed files.
|
|
1663
|
+
*
|
|
1664
|
+
* Positional, not a `--changed-files` flag. #1204 wrote the flag and CRC-B7
|
|
1665
|
+
* wrote the positional; the generated step passes positionally and #1356
|
|
1666
|
+
* builds on that, so the flag is the spelling that goes. Two spellings for
|
|
1667
|
+
* one argument would be two deciders over the same input, and the one the
|
|
1668
|
+
* deployed workflow does not use is the one that would rot.
|
|
1669
|
+
*
|
|
1670
|
+
* The second argument is optional: a caller that does not pass one gets
|
|
1671
|
+
* exactly the reading this module gave before any of this was wired, which
|
|
1672
|
+
* is what keeps every existing consumer working unchanged.
|
|
1673
|
+
*
|
|
1674
|
+
* An unreadable list is NOT silently treated as absent, and `readAiReview-
|
|
1675
|
+
* ChangedFiles` is what keeps those apart — `CHANGED_FILES_UNREADABLE` for a
|
|
1676
|
+
* list that was named and could not be read, `CHANGED_FILES_EMPTY` for one
|
|
1677
|
+
* that was read and names nothing. A failed `git diff` writes no file at
|
|
1678
|
+
* all, so collapsing the two would report a diff that was lost as a diff
|
|
1679
|
+
* that was taken.
|
|
1680
|
+
*
|
|
1681
|
+
* An argument past those two REFUSES. Nothing reads it, and a CLI that
|
|
1682
|
+
* accepts an argument it ignores reports success for an invocation that did
|
|
1683
|
+
* not happen.
|
|
1684
|
+
*
|
|
1685
|
+
* Separate from `main` so the argv contract is decided in one place and
|
|
1686
|
+
* `main` is only the printing. A refusal reached here still prints the
|
|
1687
|
+
* outcome line and the scope line, because the generated step reads the
|
|
1688
|
+
* outcome line before it reads the exit code.
|
|
1689
|
+
*/
|
|
1690
|
+
function readArgv(argv: string[]): AiReviewFindingsReading {
|
|
1691
|
+
const extra = argumentsBeyondTheContract(argv);
|
|
1692
|
+
if (extra.length > 0) {
|
|
1693
|
+
// Scope is NOT read here. The argv is already known to be a shape this
|
|
1694
|
+
// CLI does not accept, so which file argv[1] names is a question about
|
|
1695
|
+
// an invocation that is being refused.
|
|
1696
|
+
return withScope(
|
|
1697
|
+
unmeasured(
|
|
1698
|
+
["ARGUMENTS_UNREADABLE"],
|
|
1699
|
+
[
|
|
1700
|
+
`${extra.length} argument(s) past the findings payload and the changed-file ` +
|
|
1701
|
+
`list were given and nothing reads them: ${extra.map(a => JSON.stringify(a)).join(", ")}. ` +
|
|
1702
|
+
`Usage: <path-to-findings.json> [<path-to-changed-files.txt>]`,
|
|
1703
|
+
],
|
|
1704
|
+
),
|
|
1705
|
+
scopeNotSupplied(),
|
|
1706
|
+
null,
|
|
1707
|
+
null,
|
|
1708
|
+
);
|
|
1709
|
+
}
|
|
1710
|
+
|
|
519
1711
|
const path = argv[0];
|
|
520
|
-
const
|
|
521
|
-
|
|
522
|
-
|
|
1712
|
+
const scope = readAiReviewChangedFiles(argv[1]);
|
|
1713
|
+
return path === undefined || path === ""
|
|
1714
|
+
? withScope(
|
|
1715
|
+
unmeasured(
|
|
523
1716
|
["FINDINGS_FILE_ABSENT"],
|
|
524
1717
|
["no findings payload path was given to the findings reader"],
|
|
525
|
-
)
|
|
526
|
-
|
|
1718
|
+
),
|
|
1719
|
+
scope,
|
|
1720
|
+
null,
|
|
1721
|
+
null,
|
|
1722
|
+
)
|
|
1723
|
+
: readAiReviewFindingsFile(path, scope);
|
|
1724
|
+
}
|
|
1725
|
+
|
|
1726
|
+
/**
|
|
1727
|
+
* The CLI entry point. `readArgv` above decides what the arguments mean;
|
|
1728
|
+
* everything here is emission.
|
|
1729
|
+
*
|
|
1730
|
+
* Returns the exit code rather than calling `process.exit`, so a test can run
|
|
1731
|
+
* it in-process as well as spawn it.
|
|
1732
|
+
*/
|
|
1733
|
+
export function main(argv: string[], jury: AiReviewJuryGate | null = null): number {
|
|
1734
|
+
const reading = readArgv(argv);
|
|
1735
|
+
|
|
1736
|
+
// CRC-B4, AFTER the reading and feeding nothing back into it.
|
|
1737
|
+
//
|
|
1738
|
+
// The group votes on `blockingReported` — the existing decider's own
|
|
1739
|
+
// answer to "which of these block", never a list re-derived from the
|
|
1740
|
+
// severities, which is the criterion's first clause: a quorum over the
|
|
1741
|
+
// advisory tail spends a full agent context per nit.
|
|
1742
|
+
//
|
|
1743
|
+
// WHAT IT DOES NOT DO IS SUBTRACT, and that is a decision with two
|
|
1744
|
+
// reasons, both of them properties of the tree rather than of this
|
|
1745
|
+
// function:
|
|
1746
|
+
//
|
|
1747
|
+
// - **The group is not independent yet.** `AI_REVIEW_ALLOWED_TOOLS`
|
|
1748
|
+
// grants the review action `Read,Grep,Glob,Write` and
|
|
1749
|
+
// `AI_REVIEW_DENY_RULES` denies `Task`, so one invocation cannot spawn
|
|
1750
|
+
// verifiers. Independence has to be a property of the WORKFLOW — one
|
|
1751
|
+
// action invocation per verifier — and a ballot that subtracts before
|
|
1752
|
+
// that holds is a quorum wired to a constant: populated, plausible,
|
|
1753
|
+
// and filtering nothing. That is the counterfeit CRC-B4 names.
|
|
1754
|
+
// - **The verifier reads the head checkout.** A subtracting ballot would
|
|
1755
|
+
// make the branch under review an input to the gate on the branch
|
|
1756
|
+
// under review.
|
|
1757
|
+
//
|
|
1758
|
+
// So the votes are counted, written to the finding ledger at decision
|
|
1759
|
+
// time, and announced. Nothing below reads `gate` except the annotation.
|
|
1760
|
+
// CRC-B4's *"surfaced only if enough agree"* clause is therefore NOT
|
|
1761
|
+
// satisfied, and the spec says so rather than this comment alone.
|
|
1762
|
+
//
|
|
1763
|
+
// **The ballot directory is NOT a third positional argument**, and that
|
|
1764
|
+
// is deliberate rather than incidental. `argumentsBeyondTheContract`
|
|
1765
|
+
// refuses `argv[2]` and up, and one of the invocations it catches is a
|
|
1766
|
+
// changed-file path containing a space that an unquoted expansion
|
|
1767
|
+
// word-split into two — `test/ai-review-changed-files-step.test.ts`
|
|
1768
|
+
// CF-6 names that case. Widening the contract by one slot to carry a
|
|
1769
|
+
// ballot would turn that refusal into an accepted argv whose second
|
|
1770
|
+
// half is read as a ballot directory. So the directory binds at the
|
|
1771
|
+
// wrapper, which closes over it and hands this function a gate or
|
|
1772
|
+
// `null`; "no ballot" and "a ballot nothing reads" collapse into one
|
|
1773
|
+
// state that cannot be reached.
|
|
1774
|
+
let juryDetail: readonly string[] = [];
|
|
1775
|
+
let juryUnmeasured: string | null = null;
|
|
1776
|
+
if (jury !== null && reading.blockingReported !== null && reading.blockingReported.length > 0) {
|
|
1777
|
+
try {
|
|
1778
|
+
const gate = jury(reading.blockingReported);
|
|
1779
|
+
juryDetail = gate.detail;
|
|
1780
|
+
juryUnmeasured = gate.unmeasured;
|
|
1781
|
+
} catch (e) {
|
|
1782
|
+
// A FAIL-OPEN, DELIBERATELY, and this is the one arrangement where
|
|
1783
|
+
// that is the correct choice rather than the first thing
|
|
1784
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` tells you to
|
|
1785
|
+
// distrust. Its warning is about a guard that converts its own
|
|
1786
|
+
// breakage into "no problems found". This gate finds no problems
|
|
1787
|
+
// and gates nothing: the verdict is `aiReviewExitCode(reading)`
|
|
1788
|
+
// either way, so catching here cannot hide a finding — it can only
|
|
1789
|
+
// stop an advisory recorder from deciding a review it has no vote
|
|
1790
|
+
// in. The day the ballot is allowed to subtract, this catch must
|
|
1791
|
+
// become a refusal, and that is the line to change.
|
|
1792
|
+
//
|
|
1793
|
+
// Without it the throw propagates out of `main`, so
|
|
1794
|
+
// `process.exit(main(...))` never runs and a CLEAN review dies
|
|
1795
|
+
// non-zero. Worse than the exit code: this block sits ABOVE the
|
|
1796
|
+
// `AI_REVIEW_OUTCOME_LINE` print, which the generated step greps
|
|
1797
|
+
// for before it will read an exit code as a verdict, so the step
|
|
1798
|
+
// sees an adjudicator that could not run rather than a verdict.
|
|
1799
|
+
//
|
|
1800
|
+
// Three things inside the real gate are outside any catch of their
|
|
1801
|
+
// own — `juryReading`, `advisoryKey` over a hostile payload, and
|
|
1802
|
+
// all of `juryLedgerRow`. `JG-6h` is this case.
|
|
1803
|
+
juryUnmeasured =
|
|
1804
|
+
`the verifier quorum threw and was not counted, so no vote was recorded for this ` +
|
|
1805
|
+
`run: ${(e as Error).message}. The verdict below is the adjudicator's own and is ` +
|
|
1806
|
+
`unchanged — the group decides nothing this round — but the votes for these findings ` +
|
|
1807
|
+
`are lost rather than merely unfavourable, and the ledger has no row to recover`;
|
|
1808
|
+
}
|
|
1809
|
+
}
|
|
527
1810
|
|
|
528
1811
|
// FIRST, and before any branch below can return. The generated workflow step
|
|
529
1812
|
// greps its own output for this prefix and will not read the exit code as a
|
|
@@ -531,6 +1814,16 @@ export function main(argv: string[]): number {
|
|
|
531
1814
|
// refused both exit non-zero, and only this line tells them apart.
|
|
532
1815
|
console.log(`${AI_REVIEW_OUTCOME_LINE} ${reading.outcome}`);
|
|
533
1816
|
|
|
1817
|
+
// AFTER the outcome line, and never instead of it. The generated step lifts
|
|
1818
|
+
// its verdict from the FIRST occurrence of that marker, so this line cannot
|
|
1819
|
+
// move it. Printed on EVERY run, including the one where no list was
|
|
1820
|
+
// supplied: an absent input that nothing reports is Silent Default
|
|
1821
|
+
// Substitution, and this line is the whole of what makes the skip a
|
|
1822
|
+
// reading. Escaped at emission like the annotation below — a path arriving
|
|
1823
|
+
// on the command line reaches a stream GitHub parses workflow commands out
|
|
1824
|
+
// of, and this module escapes exactly once, at the point of emission.
|
|
1825
|
+
console.log(escapeAnnotation(aiReviewScopeLine(reading)));
|
|
1826
|
+
|
|
534
1827
|
// The ONE place a value reaches a workflow command. Everything upstream of
|
|
535
1828
|
// here — `renderFinding`, every `detail` sentence, `aiReviewRefusal` — builds
|
|
536
1829
|
// plain text and leaves escaping alone, so there is one binding to mutate and
|
|
@@ -540,6 +1833,55 @@ export function main(argv: string[]): number {
|
|
|
540
1833
|
console.error(`::error title=${AI_REVIEW_FINDINGS_TITLE}::${escapeAnnotation(refusal)}`);
|
|
541
1834
|
}
|
|
542
1835
|
|
|
1836
|
+
// AFTER the refusal and BEFORE the exit code, and on its own title. A
|
|
1837
|
+
// `::notice` rather than a `::warning` or an `::error`: the advisory tail
|
|
1838
|
+
// does not block, and a notice is what GitHub records against the check run
|
|
1839
|
+
// without changing its conclusion. It goes through the same single escaper
|
|
1840
|
+
// the refusal does — this is a new value reaching a workflow command, and
|
|
1841
|
+
// `escapeAnnotation`'s own docblock has the measured instance of what an
|
|
1842
|
+
// unescaped one can do to a verdict.
|
|
1843
|
+
const advisory = advisoryNotice(reading);
|
|
1844
|
+
if (advisory !== null) {
|
|
1845
|
+
console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
|
|
1846
|
+
}
|
|
1847
|
+
|
|
1848
|
+
// The quorum's own reading, on its own title, and emitted whatever the
|
|
1849
|
+
// outcome was. The ledger row is the durable record and it lives on the
|
|
1850
|
+
// runner, which dies with the job; this annotation is the only part of
|
|
1851
|
+
// the vote that outlives the run, so it carries the whole reading rather
|
|
1852
|
+
// than a count.
|
|
1853
|
+
//
|
|
1854
|
+
// A `::notice`, never an `::error`. The ballot decides nothing this round
|
|
1855
|
+
// and an annotation that reddened a check would be a gate arriving by the
|
|
1856
|
+
// back door — see the block above `juryDetail`.
|
|
1857
|
+
if (juryDetail.length > 0) {
|
|
1858
|
+
console.log(
|
|
1859
|
+
`::notice title=${AI_REVIEW_JURY_NOTICE_TITLE}::${escapeAnnotation(
|
|
1860
|
+
`A separate verifier group voted on the ${juryDetail.length} finding(s) that would ` +
|
|
1861
|
+
`otherwise block. ${juryDetail.join("; ")}. THE VOTE IS RECORDED AND CHANGES ` +
|
|
1862
|
+
`NOTHING: every finding above blocks exactly as it would have without it. The ` +
|
|
1863
|
+
`group is not yet structurally independent and reads the head checkout, so acting ` +
|
|
1864
|
+
`on it would be a gate whose input is the thing it gates.`,
|
|
1865
|
+
)}`,
|
|
1866
|
+
);
|
|
1867
|
+
}
|
|
1868
|
+
|
|
1869
|
+
// A `::warning`, and the state is NAMED. An absent or unreadable ballot
|
|
1870
|
+
// exiting 0 with no output is the Silent Default Substitution
|
|
1871
|
+
// `.claude/rules/config-access.md` forbids: `0`, `{}` and `null` are
|
|
1872
|
+
// indistinguishable from success and UNMEASURED is not. It does not
|
|
1873
|
+
// refuse, because the consumer decides whether an unmeasured quorum is
|
|
1874
|
+
// fatal and the honest default for a mechanism with no readings yet is an
|
|
1875
|
+
// annotation rather than a red pipeline.
|
|
1876
|
+
if (juryUnmeasured !== null) {
|
|
1877
|
+
console.log(
|
|
1878
|
+
`::warning title=${AI_REVIEW_JURY_UNMEASURED_TITLE}::${escapeAnnotation(
|
|
1879
|
+
`The verifier quorum is UNMEASURED for this run: ${juryUnmeasured}. No finding's ` +
|
|
1880
|
+
`status changed either way.`,
|
|
1881
|
+
)}`,
|
|
1882
|
+
);
|
|
1883
|
+
}
|
|
1884
|
+
|
|
543
1885
|
return aiReviewExitCode(reading);
|
|
544
1886
|
}
|
|
545
1887
|
|