rungate 0.8.2 → 0.8.3
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/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- 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/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- 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 +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -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 +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -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 +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- 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 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +11 -0
|
@@ -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
|
|
@@ -185,6 +230,182 @@ export function renderCountedFindings(reported: unknown[] | null): string[] {
|
|
|
185
230
|
/** The annotation title the script prints its refusal under. */
|
|
186
231
|
export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
|
|
187
232
|
|
|
233
|
+
/**
|
|
234
|
+
* The annotation title the advisory tail is printed under.
|
|
235
|
+
*
|
|
236
|
+
* A SEPARATE title from `AI_REVIEW_FINDINGS_TITLE`, deliberately. The refusal
|
|
237
|
+
* is a thing somebody has to act on before the pull request moves; this is a
|
|
238
|
+
* thing somebody has to answer before it merges, and GitHub groups
|
|
239
|
+
* annotations by title. One title for both would make the advisory tail
|
|
240
|
+
* read, in the checks UI, as part of the refusal — which is the misattribution
|
|
241
|
+
* `blockingContractViolations` is about, arriving from the other direction.
|
|
242
|
+
*/
|
|
243
|
+
export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* A stable identity for one finding, so an answer can name it.
|
|
247
|
+
*
|
|
248
|
+
* @identity file+summary — whitespace-collapsed and case-folded, FNV-1a, 8
|
|
249
|
+
* hex characters. Total: every finding gets a key, and it is never `null`.
|
|
250
|
+
*
|
|
251
|
+
* **This is the ADJUDICATION key** — "has this advisory already been counted
|
|
252
|
+
* on this run". Within one payload there is only one version of the file, so
|
|
253
|
+
* the line genuinely does not matter, and keying on it would split one
|
|
254
|
+
* finding into two across a reformat.
|
|
255
|
+
*
|
|
256
|
+
* Its sibling is `carryKey` in `lib/ai-review-rounds.ts`, which is the
|
|
257
|
+
* PERSISTENCE key — "is the thing this round raised the thing the last round
|
|
258
|
+
* raised" — over `file` + the cited line's TEXT + `summary`, and partial: it
|
|
259
|
+
* returns `null` for a finding it cannot key, which this hash cannot do. The
|
|
260
|
+
* two were both called `findingKey` until #1398. They answer different
|
|
261
|
+
* questions and the collapse loses one; neither can quietly become the
|
|
262
|
+
* other, which was measured rather than assumed, but while they shared a
|
|
263
|
+
* name no call site could say which it had asked.
|
|
264
|
+
*
|
|
265
|
+
* CRC-B8 asks that every finding be answered — fixed, or resolved with a
|
|
266
|
+
* stated reason — and an answer has to name what it answers. The line number
|
|
267
|
+
* cannot be that name: the same finding moves line between rounds, which is
|
|
268
|
+
* exactly what #1319 measured (`bash-write-guard.ts:90 → :97` across two
|
|
269
|
+
* rounds of #1213 was *one* finding). So the key is over the file and the
|
|
270
|
+
* summary, whitespace-collapsed and case-folded, and it is deliberately NOT
|
|
271
|
+
* over the severity either — a reviewer that re-rates the same observation
|
|
272
|
+
* has not produced a second finding.
|
|
273
|
+
*
|
|
274
|
+
* FNV-1a, written out, rather than `node:crypto`. Not a preference: this
|
|
275
|
+
* module is copied into a temp directory by the mutation battery in
|
|
276
|
+
* `test/ai-review-advisory-findings.test.ts`, and every import it carries has
|
|
277
|
+
* to be carried with it. The property wanted is determinism and a short
|
|
278
|
+
* printable token, not collision resistance against an adversary.
|
|
279
|
+
*
|
|
280
|
+
* ## WHAT A COLLISION COSTS, and it is no longer only an annotation
|
|
281
|
+
*
|
|
282
|
+
* This docblock used to end *"a finding that forged another finding's key
|
|
283
|
+
* would buy the forger an answer on the wrong row, which is a worse
|
|
284
|
+
* annotation and not a bypass of anything."* That stopped being true the
|
|
285
|
+
* moment CRC-B4 made the verifier quorum read a ballot filed under this
|
|
286
|
+
* key: a collision between two BLOCKING findings would let one group's vote
|
|
287
|
+
* decide both. The sentence is corrected rather than deleted because a
|
|
288
|
+
* comment asserting a property the code no longer has is the reason nobody
|
|
289
|
+
* checks it — `lib/cli-commands.ts` carried *"runs every command for real"*
|
|
290
|
+
* over a test that ran one command of ten.
|
|
291
|
+
*
|
|
292
|
+
* What holds instead, and it is a property of the CALLER rather than of
|
|
293
|
+
* this hash: `juryGate` derives the identity once over the whole blocking
|
|
294
|
+
* set, refuses a key two of them share, and carries its decision back to
|
|
295
|
+
* the reader **by position**. So a collision is seen and both findings keep
|
|
296
|
+
* blocking; it cannot silently credit one finding's vote to another. The
|
|
297
|
+
* hash is still not adversary-resistant and is not asked to be — nothing
|
|
298
|
+
* downstream of it decides anything a collision could not already be
|
|
299
|
+
* refused for.
|
|
300
|
+
*/
|
|
301
|
+
export function advisoryKey(finding: Record<string, unknown>): string {
|
|
302
|
+
const f = AI_REVIEW_FINDING_FIELDS;
|
|
303
|
+
const normalise = (v: unknown): string =>
|
|
304
|
+
String(v ?? "").trim().replace(/\s+/g, " ").toLowerCase();
|
|
305
|
+
const subject = `${normalise(finding[f.file])}\u0000${normalise(finding[f.summary])}`;
|
|
306
|
+
let hash = 0x811c9dc5;
|
|
307
|
+
for (let i = 0; i < subject.length; i++) {
|
|
308
|
+
hash ^= subject.charCodeAt(i);
|
|
309
|
+
hash = Math.imul(hash, 0x01000193) >>> 0;
|
|
310
|
+
}
|
|
311
|
+
return hash.toString(16).padStart(8, "0");
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* The findings this reading counted and did NOT act on — the advisory tail.
|
|
316
|
+
*
|
|
317
|
+
* `null`, never `[]`, when the complement cannot be taken. Under UNMEASURED
|
|
318
|
+
* `blockingReported` is `null` — a withheld decision, not an empty one — so
|
|
319
|
+
* subtracting it from `reported` would manufacture an advisory set out of
|
|
320
|
+
* findings nobody classified. Those are different facts and this module's
|
|
321
|
+
* whole philosophy is that they stay different.
|
|
322
|
+
*
|
|
323
|
+
* Computed by identity against `blockingReported` rather than by re-reading
|
|
324
|
+
* the severities. Re-reading them here would be a second decider over the one
|
|
325
|
+
* question `severityBlocks` already answers — the fourth shape in
|
|
326
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
|
|
327
|
+
* would leave the other holding every case up.
|
|
328
|
+
*/
|
|
329
|
+
export function advisoryReported(reading: AiReviewFindingsReading): unknown[] | null {
|
|
330
|
+
if (reading.reported === null || reading.blockingReported === null) return null;
|
|
331
|
+
const blocking = new Set(reading.blockingReported);
|
|
332
|
+
return reading.reported.filter(item => !blocking.has(item));
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* The sentence naming every advisory finding, or `null` when there is nothing
|
|
337
|
+
* to name.
|
|
338
|
+
*
|
|
339
|
+
* ## The silent drop this closes (CRC-B8)
|
|
340
|
+
*
|
|
341
|
+
* `AI_REVIEW_SEVERITIES` declares `medium`, `low` and `info` as advisory, and
|
|
342
|
+
* until this function existed a reading counted them and then dropped them.
|
|
343
|
+
* `detail` is populated inside `if (blocks)`; `aiReviewRefusal` returns `null`
|
|
344
|
+
* for CLEAN and lists only `detail` for BLOCKED. So `main()` printed the
|
|
345
|
+
* outcome line and nothing else, and a payload carrying seven `medium`
|
|
346
|
+
* findings produced **byte-identical output** to a payload carrying none.
|
|
347
|
+
* The payload itself lives under `$RUNNER_TEMP`, is uploaded nowhere (#1319
|
|
348
|
+
* measured zero artifacts) and dies with the runner, so the finding was not
|
|
349
|
+
* merely unreported — it was unrecoverable the moment the job ended.
|
|
350
|
+
*
|
|
351
|
+
* That is CRC-B8's second sentence failing in the live path: *a finding is
|
|
352
|
+
* never silently dropped*. It is also the reason the tail could not be
|
|
353
|
+
* answered rather than filed — you cannot resolve on the pull request a
|
|
354
|
+
* finding the pull request never shows you.
|
|
355
|
+
*
|
|
356
|
+
* ## Why CONTRADICTION returns null here
|
|
357
|
+
*
|
|
358
|
+
* The contradiction arm of `aiReviewRefusal` already prints EVERY counted
|
|
359
|
+
* finding, advisory ones included, through `renderCountedFindings` — #1178,
|
|
360
|
+
* and for a reason that still holds. Emitting this notice alongside it would
|
|
361
|
+
* print the advisory tail twice, and that module's own comment says why that
|
|
362
|
+
* is worse than printing it once: *a duplicate reads as two findings*. The
|
|
363
|
+
* rule lives here, in one function, rather than as a condition at the call
|
|
364
|
+
* site, so there is one binding to mutate.
|
|
365
|
+
*
|
|
366
|
+
* ## What this does NOT do
|
|
367
|
+
*
|
|
368
|
+
* It decides nothing. `aiReviewExitCode` is untouched and reads only the
|
|
369
|
+
* outcome, so an advisory finding does not block and cannot be made to block
|
|
370
|
+
* from here. Surfacing a finding and adjudicating one are different jobs, and
|
|
371
|
+
* this module already holds the second; a notice that quietly became a
|
|
372
|
+
* refusal would be a severity table nobody declared.
|
|
373
|
+
*/
|
|
374
|
+
export function advisoryNotice(reading: AiReviewFindingsReading): string | null {
|
|
375
|
+
if (reading.outcome === "CONTRADICTION") return null;
|
|
376
|
+
const advisory = advisoryReported(reading);
|
|
377
|
+
if (advisory === null || advisory.length === 0) return null;
|
|
378
|
+
|
|
379
|
+
// Rendered through `renderCountedFindings` over the WHOLE list and then
|
|
380
|
+
// selected, rather than over the filtered list. Two reasons, and the second
|
|
381
|
+
// is the one that bites: the renderer numbers what it is given, so rendering
|
|
382
|
+
// the tail alone would renumber it from zero and `finding 3` in this notice
|
|
383
|
+
// would be a different finding from `finding 3` in a refusal. And selecting
|
|
384
|
+
// out of the full render means this notice and the contradiction arm's list
|
|
385
|
+
// come from one call of one function, which is what keeps them from drifting.
|
|
386
|
+
const reported = reading.reported ?? [];
|
|
387
|
+
const all = renderCountedFindings(reported);
|
|
388
|
+
const rendered = advisory.map(item => {
|
|
389
|
+
const i = reported.indexOf(item);
|
|
390
|
+
const key =
|
|
391
|
+
item !== null && typeof item === "object" && !Array.isArray(item)
|
|
392
|
+
? ` [key ${advisoryKey(item as Record<string, unknown>)}]`
|
|
393
|
+
: "";
|
|
394
|
+
return `${all[i]}${key}`;
|
|
395
|
+
});
|
|
396
|
+
|
|
397
|
+
return (
|
|
398
|
+
`${advisory.length} advisory finding(s) were counted and block nothing. ` +
|
|
399
|
+
`${rendered.join("; ")}. ` +
|
|
400
|
+
`Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
|
|
401
|
+
`resolved with a reason, or filed, and this annotation is the only place ` +
|
|
402
|
+
`it survives the job — the payload lives under the runner's temp directory ` +
|
|
403
|
+
`and is uploaded nowhere. Answer each one on this pull request (fix it, or ` +
|
|
404
|
+
`say in a comment why it stands), naming its key. Filing an issue is the ` +
|
|
405
|
+
`exception, not the default.`
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
|
|
188
409
|
/** The four states a reading can be in. Exactly one is reached per run. */
|
|
189
410
|
export type AiReviewOutcome = "CLEAN" | "BLOCKED" | "CONTRADICTION" | "UNMEASURED";
|
|
190
411
|
|
|
@@ -200,8 +421,29 @@ export type AiReviewUnmeasuredReason =
|
|
|
200
421
|
| "SEVERITY_ABSENT"
|
|
201
422
|
| "SEVERITY_UNRECOGNISED"
|
|
202
423
|
| "BLOCKING_FINDING_INCOMPLETE"
|
|
424
|
+
// `BLOCKING_FINDING_UNLOCATABLE` was here and is gone with the merge of
|
|
425
|
+
// #1204 into CRC-B7. Nothing produces it: a blocking finding naming a file
|
|
426
|
+
// outside the diff is DEMOTED to `Pre-existing` and the run stays readable,
|
|
427
|
+
// rather than refusing the whole reading. A member nothing emits is a state
|
|
428
|
+
// no test can reach, and `not.toContain` against it passes vacuously for
|
|
429
|
+
// ever — which is how a deleted check goes on looking guarded.
|
|
430
|
+
| "ARGUMENTS_UNREADABLE"
|
|
203
431
|
| "VERDICT_ABSENT"
|
|
204
|
-
| "VERDICT_UNRECOGNISED"
|
|
432
|
+
| "VERDICT_UNRECOGNISED"
|
|
433
|
+
/**
|
|
434
|
+
* A changed-file list was supplied and was EMPTY. A pull request always
|
|
435
|
+
* touches something, so `[]` is a reading that failed rather than a pull
|
|
436
|
+
* request that changed nothing — and taken at face value it would tag every
|
|
437
|
+
* finding `Pre-existing` and block none of them, which is the fail-open this
|
|
438
|
+
* module exists to refuse.
|
|
439
|
+
*/
|
|
440
|
+
| "CHANGED_FILES_EMPTY"
|
|
441
|
+
/**
|
|
442
|
+
* A changed-file list entry could not be read as a repository path.
|
|
443
|
+
* Comparing against a list the reader cannot normalise would demote every
|
|
444
|
+
* finding, so the list being unreadable is a reading that failed.
|
|
445
|
+
*/
|
|
446
|
+
| "CHANGED_FILES_UNREADABLE";
|
|
205
447
|
|
|
206
448
|
/**
|
|
207
449
|
* The fields a BLOCKING finding must carry, derived from the one contract map
|
|
@@ -247,6 +489,164 @@ export function blockingContractViolations(finding: Record<string, unknown>): st
|
|
|
247
489
|
});
|
|
248
490
|
}
|
|
249
491
|
|
|
492
|
+
// `AI_REVIEW_CHANGED_FILES_FLAG` lived here and is gone. #1204 argued for a
|
|
493
|
+
// FLAG over a second positional, citing #675: `--project-root <cwd>` "would
|
|
494
|
+
// arrive as a second positional and be read as a second payload".
|
|
495
|
+
//
|
|
496
|
+
// That hazard was CHECKED before the constant was removed, not waved away.
|
|
497
|
+
// `bin/rungate.ts` appends `--project-root` only when a command declares
|
|
498
|
+
// `projectRootFlag`, and `ai-review-findings` declares none — which is the
|
|
499
|
+
// very fact #1204 cited. So nothing injects a stray positional into THIS
|
|
500
|
+
// command, and the argument does not reach it.
|
|
501
|
+
//
|
|
502
|
+
// The positional wins because the deployed workflow passes one and #1356
|
|
503
|
+
// builds on that. Two spellings for one argument would be two deciders, and
|
|
504
|
+
// the spelling the generated step does not use is the one that would rot.
|
|
505
|
+
|
|
506
|
+
/**
|
|
507
|
+
* The prefix of the line recording how the scope reading was taken.
|
|
508
|
+
*
|
|
509
|
+
* Distinct from `AI_REVIEW_OUTCOME_LINE`, which the generated step lifts its
|
|
510
|
+
* verdict out of by parameter expansion on the FIRST occurrence of that
|
|
511
|
+
* marker. This line is printed after it and contains neither that marker nor
|
|
512
|
+
* a newline, so nothing about the verdict extraction moves.
|
|
513
|
+
*/
|
|
514
|
+
export const AI_REVIEW_SCOPE_LINE = "ai-review findings scope:";
|
|
515
|
+
|
|
516
|
+
/** Whether the pull request's changed-file list was read, and if not, why. */
|
|
517
|
+
export type AiReviewScopeStatus = "MEASURED" | "NOT_SUPPLIED" | "UNMEASURED";
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* The changed-file reading. One discriminator, `status`, and the producing
|
|
521
|
+
* code's own sentence beside it.
|
|
522
|
+
*
|
|
523
|
+
* `NOT_SUPPLIED` and `UNMEASURED` are different facts with different fixes.
|
|
524
|
+
* Nobody handed this run a list is a property of the workflow that invoked
|
|
525
|
+
* it; a list that could not be read is a property of this run. Collapsing
|
|
526
|
+
* them would make a release in which the input does not exist yet look like
|
|
527
|
+
* a `git diff` that failed.
|
|
528
|
+
*/
|
|
529
|
+
export type AiReviewScopeReading =
|
|
530
|
+
| { status: "NOT_SUPPLIED"; files: null; detail: string; reason: null }
|
|
531
|
+
| { status: "MEASURED"; files: string[]; detail: string; reason: null }
|
|
532
|
+
| {
|
|
533
|
+
status: "UNMEASURED";
|
|
534
|
+
files: null;
|
|
535
|
+
detail: string;
|
|
536
|
+
reason: Extract<
|
|
537
|
+
AiReviewUnmeasuredReason,
|
|
538
|
+
"CHANGED_FILES_UNREADABLE" | "CHANGED_FILES_EMPTY"
|
|
539
|
+
>;
|
|
540
|
+
};
|
|
541
|
+
|
|
542
|
+
/** The reading for a run nobody handed a changed-file list. */
|
|
543
|
+
export function scopeNotSupplied(): AiReviewScopeReading {
|
|
544
|
+
return {
|
|
545
|
+
status: "NOT_SUPPLIED",
|
|
546
|
+
files: null,
|
|
547
|
+
reason: null,
|
|
548
|
+
detail:
|
|
549
|
+
`no changed-file list was given (second positional argument), so whether ` +
|
|
550
|
+
`a blocking finding names a file this pull request touches was not checked. ` +
|
|
551
|
+
`This is a reading, not a pass: the generated job does not supply the list yet`,
|
|
552
|
+
};
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
/**
|
|
556
|
+
* The reading for a run whose changed-file list was supplied directly rather
|
|
557
|
+
* than read from disk.
|
|
558
|
+
*
|
|
559
|
+
* Exists so a caller holding an array does not have to spell the discriminated
|
|
560
|
+
* union by hand. `files` is carried raw; `readPayload` normalises.
|
|
561
|
+
*
|
|
562
|
+
* An EMPTY array is still MEASURED here and is refused downstream, on purpose:
|
|
563
|
+
* "a list was supplied and it was empty" is a fact this type can represent and
|
|
564
|
+
* `readAiReviewChangedFiles` cannot produce, so the refusal lives where every
|
|
565
|
+
* caller passes through rather than only on the disk path.
|
|
566
|
+
*/
|
|
567
|
+
export function scopeMeasured(files: readonly string[]): AiReviewScopeReading {
|
|
568
|
+
return {
|
|
569
|
+
status: "MEASURED",
|
|
570
|
+
files: [...files],
|
|
571
|
+
reason: null,
|
|
572
|
+
detail: `${files.length} changed path(s) supplied directly`,
|
|
573
|
+
};
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
/**
|
|
577
|
+
* Read the changed-file list from disk. Three states, each its own fact.
|
|
578
|
+
*
|
|
579
|
+
* A list that could not be read REFUSES and must never produce an empty list:
|
|
580
|
+
* an empty changed set makes every blocking finding unlocatable, which is the
|
|
581
|
+
* loud direction and loud for the wrong reason — it reads as the reviewer
|
|
582
|
+
* having hallucinated every finding it wrote.
|
|
583
|
+
*
|
|
584
|
+
* A list that WAS read and names no paths refuses too, under its own reason.
|
|
585
|
+
* A pull request that changes nothing is not a state this input can honestly
|
|
586
|
+
* be in, so an empty file is a diff that was lost rather than a diff that was
|
|
587
|
+
* empty — and the two reasons are kept apart because the fixes differ.
|
|
588
|
+
*
|
|
589
|
+
* The list must be taken from the RESTORED tree, before the reviewer could
|
|
590
|
+
* have written to the checkout. That is why this function is handed a path
|
|
591
|
+
* and never takes the diff itself: this module runs after the review, from
|
|
592
|
+
* the payload's own directory, so a diff computed here is one the subject of
|
|
593
|
+
* the review had an opportunity to edit.
|
|
594
|
+
*/
|
|
595
|
+
export function readAiReviewChangedFiles(path: string | undefined): AiReviewScopeReading {
|
|
596
|
+
if (path === undefined || path === "") return scopeNotSupplied();
|
|
597
|
+
|
|
598
|
+
let raw: string;
|
|
599
|
+
try {
|
|
600
|
+
raw = readFileSync(path, "utf-8");
|
|
601
|
+
} catch (e) {
|
|
602
|
+
return {
|
|
603
|
+
status: "UNMEASURED",
|
|
604
|
+
files: null,
|
|
605
|
+
reason: "CHANGED_FILES_UNREADABLE",
|
|
606
|
+
detail:
|
|
607
|
+
`the changed-file list at ${path} could not be read: ${(e as Error).message}. ` +
|
|
608
|
+
`A diff that could not be taken is not a pull request that touches nothing`,
|
|
609
|
+
};
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
// Entries are carried RAW, trimmed only. This function decides whether the
|
|
613
|
+
// list is a reading; `readPayload` decides what each path means, through
|
|
614
|
+
// `normaliseRepoPath`. Normalising here too would be two normalisers over
|
|
615
|
+
// one input — and the weaker one would win silently, because it runs first.
|
|
616
|
+
// `normaliseRepoPath` collapses dot segments, strips a `:line` suffix and
|
|
617
|
+
// refuses git's C-quoted form; stripping `./` is the only thing the reader
|
|
618
|
+
// that used to live here could do.
|
|
619
|
+
const files = raw.split("\n").map(l => l.trim()).filter(p => p.length > 0);
|
|
620
|
+
if (files.length === 0) {
|
|
621
|
+
return {
|
|
622
|
+
status: "UNMEASURED",
|
|
623
|
+
files: null,
|
|
624
|
+
reason: "CHANGED_FILES_EMPTY",
|
|
625
|
+
detail:
|
|
626
|
+
`the changed-file list at ${path} names no paths at all. A pull request that ` +
|
|
627
|
+
`changes nothing is not a state this input can be in, so the diff was taken and ` +
|
|
628
|
+
`lost rather than taken and empty — and reading it as empty would report every ` +
|
|
629
|
+
`blocking finding as naming a file outside the pull request`,
|
|
630
|
+
};
|
|
631
|
+
}
|
|
632
|
+
|
|
633
|
+
return {
|
|
634
|
+
status: "MEASURED",
|
|
635
|
+
files,
|
|
636
|
+
reason: null,
|
|
637
|
+
detail: `${files.length} changed path(s) read from ${path}`,
|
|
638
|
+
};
|
|
639
|
+
}
|
|
640
|
+
|
|
641
|
+
// `unlocatableBlockingFinding` lived here and is gone. It was #1204's
|
|
642
|
+
// refusal predicate, and the merge with CRC-B7 retired the refusal; the
|
|
643
|
+
// comparison it performed now happens inside `readPayload` against
|
|
644
|
+
// `normaliseRepoPath`, which is the stronger reader. Deleted rather than
|
|
645
|
+
// left exported with no caller — `lib/ai-review-rounds.ts` (CRC-N4) and
|
|
646
|
+
// `lib/finding-jury.ts` (CRC-B4) are both open issues about exactly that,
|
|
647
|
+
// and adding a third would be the cheapest way to pretend this merge kept
|
|
648
|
+
// more than it did.
|
|
649
|
+
|
|
250
650
|
export interface AiReviewFindingsReading {
|
|
251
651
|
/** The single discriminator. Everything else is a projection of the same pass. */
|
|
252
652
|
outcome: AiReviewOutcome;
|
|
@@ -265,6 +665,31 @@ export interface AiReviewFindingsReading {
|
|
|
265
665
|
unmeasuredReasons: AiReviewUnmeasuredReason[];
|
|
266
666
|
/** The producing code's own sentences, one per reason or blocking finding. */
|
|
267
667
|
detail: string[];
|
|
668
|
+
/** How the pull request's changed-file list was read, and whether it was. */
|
|
669
|
+
scope: AiReviewScopeReading;
|
|
670
|
+
/**
|
|
671
|
+
* Blocking findings naming a file the pull request does not touch — CARRIED,
|
|
672
|
+
* never dropped, and `null` when the scope check did not run.
|
|
673
|
+
*
|
|
674
|
+
* `null` rather than `[]` for the did-not-run case on purpose: an empty list
|
|
675
|
+
* and a check nobody performed are the states this module exists to keep
|
|
676
|
+
* apart. `scope.status` is the discriminator; this is a projection of it.
|
|
677
|
+
*/
|
|
678
|
+
unlocatableReported: unknown[] | null;
|
|
679
|
+
/**
|
|
680
|
+
* Changed-file entries this reader could not normalise and DROPPED from the
|
|
681
|
+
* comparison set (#1472) — RAW, named, in list order.
|
|
682
|
+
*
|
|
683
|
+
* Three states, and the middle one is the reason this is not a count.
|
|
684
|
+
* `null` is "no list was supplied, so nothing was read in full or in part";
|
|
685
|
+
* `[]` is "a list was read and every entry of it was comparable"; a
|
|
686
|
+
* non-empty list is "a list was read and these entries were not", which is
|
|
687
|
+
* a reading over a NARROWER set than the pull request actually touched. A
|
|
688
|
+
* reading that narrowed itself and did not say so is indistinguishable from
|
|
689
|
+
* a complete one — `.claude/rules/config-access.md`'s *Silent Default
|
|
690
|
+
* Substitution*, in the place it decides a required check.
|
|
691
|
+
*/
|
|
692
|
+
scopeDropped: string[] | null;
|
|
268
693
|
}
|
|
269
694
|
|
|
270
695
|
/**
|
|
@@ -292,21 +717,167 @@ function unmeasured(
|
|
|
292
717
|
verdict: null,
|
|
293
718
|
unmeasuredReasons: reasons,
|
|
294
719
|
detail,
|
|
720
|
+
scope: scopeNotSupplied(),
|
|
721
|
+
unlocatableReported: null,
|
|
722
|
+
scopeDropped: null,
|
|
295
723
|
};
|
|
296
724
|
}
|
|
297
725
|
|
|
726
|
+
/**
|
|
727
|
+
* The ONE place a scope reading meets a payload reading.
|
|
728
|
+
*
|
|
729
|
+
* Every reading is built carrying the NOT_SUPPLIED default and passes through
|
|
730
|
+
* here. A second site that set `scope`, or that raised a reading on a refused
|
|
731
|
+
* scope, would be a second statement about the same input and the two could
|
|
732
|
+
* disagree.
|
|
733
|
+
*
|
|
734
|
+
* A scope reading that REFUSES raises the whole reading, carrying the
|
|
735
|
+
* payload's own reasons and findings with it rather than replacing them:
|
|
736
|
+
* "the diff could not be taken" and "the payload is not JSON" are both true
|
|
737
|
+
* of such a run, and a reader fixing one needs to see the other.
|
|
738
|
+
*/
|
|
739
|
+
function withScope(
|
|
740
|
+
reading: AiReviewFindingsReading,
|
|
741
|
+
scope: AiReviewScopeReading,
|
|
742
|
+
unlocatableReported: unknown[] | null,
|
|
743
|
+
scopeDropped: string[] | null,
|
|
744
|
+
): AiReviewFindingsReading {
|
|
745
|
+
const merged =
|
|
746
|
+
scope.status === "UNMEASURED"
|
|
747
|
+
? unmeasured(
|
|
748
|
+
[...reading.unmeasuredReasons, scope.reason],
|
|
749
|
+
[...reading.detail, scope.detail],
|
|
750
|
+
reading.reported,
|
|
751
|
+
)
|
|
752
|
+
: reading;
|
|
753
|
+
return { ...merged, scope, unlocatableReported, scopeDropped };
|
|
754
|
+
}
|
|
755
|
+
|
|
298
756
|
/**
|
|
299
757
|
* Read a findings payload and decide what it means.
|
|
300
758
|
*
|
|
301
759
|
* `raw` is `null` for "there was no payload at all", which is a reading and
|
|
302
760
|
* not an error: a job whose reviewer never wrote anything has not passed a
|
|
303
761
|
* review, it has not had one.
|
|
762
|
+
*
|
|
763
|
+
* `scope` is the pull request's changed-file reading, and what this function
|
|
764
|
+
* DOES with it is CRC-B7 (CODE-REVIEW-CONVERGENCE-SPEC): a finding naming no
|
|
765
|
+
* file this pull request touched is tagged `Pre-existing` and does not block,
|
|
766
|
+
* so a bug that was already on `main` does not read as the change's fault.
|
|
767
|
+
* `ai-review` reads the MERGE REF, so without this every defect on `main` is
|
|
768
|
+
* reported against whichever pull request is standing closest — nine of them
|
|
769
|
+
* at once on 2026-10-23.
|
|
770
|
+
*
|
|
771
|
+
* ## #1204 and CRC-B7 answered the same question and this merge picked one
|
|
772
|
+
*
|
|
773
|
+
* Both asked *does this finding apply to this pull request?* over the same
|
|
774
|
+
* input. #1204 refused — `BLOCKING_FINDING_UNLOCATABLE`, a red required
|
|
775
|
+
* check. CRC-B7 demotes. **CRC-B7 owns the case**, because #1204's answer
|
|
776
|
+
* makes its own motivating measurement worse: under it each of those nine
|
|
777
|
+
* findings becomes a REFUSING required check, so every pull request standing
|
|
778
|
+
* near a defect on `main` is unmergeable until somebody fixes `main`. That is
|
|
779
|
+
* worse than the state it was fixing. CRC-B7 also grades the error direction,
|
|
780
|
+
* which the refusal does not: an undecidable path keeps blocking, and a
|
|
781
|
+
* non-string path is a contract violation rather than a demotion input.
|
|
782
|
+
*
|
|
783
|
+
* What #1204 keeps is the INPUT layer — `scope`, three states as a type
|
|
784
|
+
* rather than as conventions over a nullable array. It is the only side that
|
|
785
|
+
* can tell "nobody handed this run a list" from "every finding was
|
|
786
|
+
* locatable", and those are the two readings a green check must not conflate.
|
|
787
|
+
* It defaults to NOT_SUPPLIED, under which nothing is demoted and the reading
|
|
788
|
+
* is exactly what it was before any of this existed.
|
|
789
|
+
*
|
|
790
|
+
* The finding's DECLARED `file` is the input, not a path mined out of its
|
|
791
|
+
* prose. `blockingContractViolations` already refuses a blocking finding that
|
|
792
|
+
* carries none, and `lib/finding-jury.ts`'s `citedPaths` text-mines only
|
|
793
|
+
* because the arbiter's findings arrive as prose. Mining a field the payload
|
|
794
|
+
* declares would be a second decider for a question already answered.
|
|
795
|
+
*/
|
|
796
|
+
export function readAiReviewFindings(
|
|
797
|
+
raw: string | null,
|
|
798
|
+
scope: AiReviewScopeReading = scopeNotSupplied(),
|
|
799
|
+
): AiReviewFindingsReading {
|
|
800
|
+
const preExisting: unknown[] = [];
|
|
801
|
+
// Appended to by `readPayload`, for the same reason `preExisting` is: the
|
|
802
|
+
// entries belong to the reading its caller composes, and every early return
|
|
803
|
+
// in there is a state in which the split had not happened yet.
|
|
804
|
+
const dropped: string[] = [];
|
|
805
|
+
const base = readPayload(
|
|
806
|
+
raw,
|
|
807
|
+
scope.status === "MEASURED" ? scope.files : undefined,
|
|
808
|
+
preExisting,
|
|
809
|
+
dropped,
|
|
810
|
+
);
|
|
811
|
+
return withScope(
|
|
812
|
+
base,
|
|
813
|
+
scope,
|
|
814
|
+
scope.status === "MEASURED" ? preExisting : null,
|
|
815
|
+
scope.status === "MEASURED" ? dropped : null,
|
|
816
|
+
);
|
|
817
|
+
}
|
|
818
|
+
|
|
819
|
+
/**
|
|
820
|
+
* The payload pass itself. `preExisting` is appended to rather than returned,
|
|
821
|
+
* because the findings it collects belong to the reading its caller composes
|
|
822
|
+
* and every early return here is a state in which none were collected.
|
|
823
|
+
*
|
|
824
|
+
* It holds the findings CRC-B7 demoted. A COUNT would not do: "three were
|
|
825
|
+
* demoted" and "these three were demoted" differ exactly when somebody wants
|
|
826
|
+
* to know whether the demotion was right, which is the only question anybody
|
|
827
|
+
* asks of a demotion.
|
|
304
828
|
*/
|
|
305
|
-
|
|
829
|
+
function readPayload(
|
|
830
|
+
raw: string | null,
|
|
831
|
+
changedFiles: readonly string[] | undefined,
|
|
832
|
+
preExisting: unknown[],
|
|
833
|
+
dropped: string[],
|
|
834
|
+
): AiReviewFindingsReading {
|
|
306
835
|
if (raw === null) {
|
|
307
836
|
return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
|
|
308
837
|
}
|
|
309
838
|
|
|
839
|
+
if (changedFiles !== undefined && changedFiles.length === 0) {
|
|
840
|
+
return unmeasured(
|
|
841
|
+
["CHANGED_FILES_EMPTY"],
|
|
842
|
+
[
|
|
843
|
+
"a changed-file list was supplied and was empty. A pull request always touches " +
|
|
844
|
+
"something, so this is a reading that failed rather than a pull request that " +
|
|
845
|
+
"changed nothing — and taken at face value every finding would be tagged " +
|
|
846
|
+
"Pre-existing and none would block.",
|
|
847
|
+
],
|
|
848
|
+
);
|
|
849
|
+
}
|
|
850
|
+
let touched: Set<string> | null = null;
|
|
851
|
+
if (changedFiles !== undefined) {
|
|
852
|
+
// #1472. ONE unnormalisable entry used to refuse the WHOLE reading, so a
|
|
853
|
+
// repository holding a single tracked path with a space in it could never
|
|
854
|
+
// obtain a scope reading at all — `docs/my file.md` was enough, and the
|
|
855
|
+
// remedy the refusal named (`-z`, `core.quotePath=false`) does not apply,
|
|
856
|
+
// because git emits a space literally and the regex rejects it literally.
|
|
857
|
+
//
|
|
858
|
+
// The comparison is PER FINDING, so one bad entry says nothing about the
|
|
859
|
+
// others. The entry is dropped, the drop is NAMED, and the findings over
|
|
860
|
+
// normalisable paths are adjudicated as before.
|
|
861
|
+
const { readable, dropped: unreadable } = partitionChangedFiles(changedFiles);
|
|
862
|
+
dropped.push(...unreadable);
|
|
863
|
+
// The refusal is NARROWED, not deleted. With nothing readable left,
|
|
864
|
+
// `touched` is empty, every finding is tagged Pre-existing and the run
|
|
865
|
+
// reports a green check for a review that found something — which is the
|
|
866
|
+
// one input the original refusal was right about.
|
|
867
|
+
if (readable.length === 0) {
|
|
868
|
+
return unmeasured(
|
|
869
|
+
["CHANGED_FILES_UNREADABLE"],
|
|
870
|
+
[
|
|
871
|
+
`all ${unreadable.length} changed-file entr(ies) could not be read as a repository ` +
|
|
872
|
+
`path: ${unreadable.map(p => JSON.stringify(p)).join(", ")}. ` +
|
|
873
|
+
`Comparing against a list with nothing readable left in it would tag every ` +
|
|
874
|
+
`finding Pre-existing. Produce the list with -z or core.quotePath=false`,
|
|
875
|
+
],
|
|
876
|
+
);
|
|
877
|
+
}
|
|
878
|
+
touched = new Set(readable);
|
|
879
|
+
}
|
|
880
|
+
|
|
310
881
|
let doc: unknown;
|
|
311
882
|
try {
|
|
312
883
|
doc = JSON.parse(raw);
|
|
@@ -349,6 +920,8 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
349
920
|
const reasons: AiReviewUnmeasuredReason[] = [];
|
|
350
921
|
const detail: string[] = [];
|
|
351
922
|
const blocking: unknown[] = [];
|
|
923
|
+
/** How many findings CRC-B7 demoted. See the `agreed` computation below. */
|
|
924
|
+
let demoted = 0;
|
|
352
925
|
|
|
353
926
|
list.forEach((item, i) => {
|
|
354
927
|
if (item === null || typeof item !== "object" || Array.isArray(item)) {
|
|
@@ -390,6 +963,75 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
390
963
|
);
|
|
391
964
|
return;
|
|
392
965
|
}
|
|
966
|
+
// CRC-B7, and AFTER the contract check rather than before it. A finding
|
|
967
|
+
// with no declared `file` cannot be tagged either way, and it has
|
|
968
|
+
// already been refused as incomplete one branch up — so by here `file`
|
|
969
|
+
// is known present, and the tag is decidable rather than guessed.
|
|
970
|
+
//
|
|
971
|
+
// It DEMOTES, it does not drop (CRC-B8). The finding stays in
|
|
972
|
+
// `reported`, so `advisoryReported` carries it into the notice and a
|
|
973
|
+
// maintainer still sees it; it simply stops reddening a required check
|
|
974
|
+
// over a defect the diff did not introduce and cannot fix.
|
|
975
|
+
if (touched !== null) {
|
|
976
|
+
const declared = finding[AI_REVIEW_FINDING_FIELDS.file];
|
|
977
|
+
// A non-string `file` is a CONTRACT violation, not a demotion input.
|
|
978
|
+
// `blockingContractViolations` refuses `undefined`, `null` and the
|
|
979
|
+
// empty string and lets a number or an object through, so without
|
|
980
|
+
// this a finding declaring `file: {}` stringifies to
|
|
981
|
+
// `[object Object]`, matches nothing, and demotes itself.
|
|
982
|
+
if (typeof declared !== "string") {
|
|
983
|
+
reasons.push("BLOCKING_FINDING_INCOMPLETE");
|
|
984
|
+
detail.push(
|
|
985
|
+
`finding ${i} blocks and declares a non-string ` +
|
|
986
|
+
`'${AI_REVIEW_FINDING_FIELDS.file}' (${typeof declared}). A path that is not a ` +
|
|
987
|
+
`string cannot be compared to the changed-file list, and a comparison that ` +
|
|
988
|
+
`cannot be made is not a finding that is pre-existing`,
|
|
989
|
+
);
|
|
990
|
+
return;
|
|
991
|
+
}
|
|
992
|
+
const named = normaliseRepoPath(declared);
|
|
993
|
+
// Undecidable is NOT pre-existing. The finding is well-formed and
|
|
994
|
+
// this reader simply cannot resolve its path, so it keeps blocking —
|
|
995
|
+
// the direction this stage is allowed to be wrong in.
|
|
996
|
+
if (named === null) {
|
|
997
|
+
detail.push(
|
|
998
|
+
`finding ${i} declares ${JSON.stringify(declared)}, which could not be read as a ` +
|
|
999
|
+
`repository path, so it could not be compared to the changed-file list. It ` +
|
|
1000
|
+
`keeps blocking: undecidable is not pre-existing`,
|
|
1001
|
+
);
|
|
1002
|
+
} else if (!touched.has(named)) {
|
|
1003
|
+
demoted += 1;
|
|
1004
|
+
// #1204's half that survived the merge: WHICH findings were
|
|
1005
|
+
// demoted, not just how many. The scope line reports it, so a
|
|
1006
|
+
// reader can ask whether a demotion was right — the only question
|
|
1007
|
+
// anybody asks of one.
|
|
1008
|
+
preExisting.push(item);
|
|
1009
|
+
detail.push(
|
|
1010
|
+
`finding ${i} is Pre-existing: it names ${JSON.stringify(
|
|
1011
|
+
finding[AI_REVIEW_FINDING_FIELDS.file],
|
|
1012
|
+
)}, which this pull request does not touch. It is reported and does not block — ` +
|
|
1013
|
+
`ai-review reads the merge ref, so a defect already on the base branch is ` +
|
|
1014
|
+
`adjudicated against whichever pull request is standing closest to it`,
|
|
1015
|
+
);
|
|
1016
|
+
return;
|
|
1017
|
+
}
|
|
1018
|
+
}
|
|
1019
|
+
// CRC-B4's verifier quorum does NOT appear here, and its absence is
|
|
1020
|
+
// the decision rather than an omission.
|
|
1021
|
+
//
|
|
1022
|
+
// A quorum that subtracts from this list is a gate whose input is the
|
|
1023
|
+
// thing it gates: the verifier reads the cited file at the HEAD
|
|
1024
|
+
// checkout, so code that argues itself clean would be voting on the
|
|
1025
|
+
// finding about itself. And the group that would cast those votes is
|
|
1026
|
+
// not independent — `AI_REVIEW_ALLOWED_TOOLS` grants
|
|
1027
|
+
// `Read,Grep,Glob,Write` and `AI_REVIEW_DENY_RULES` denies `Task`, so
|
|
1028
|
+
// a verifier step cannot spawn anything and N votes from one
|
|
1029
|
+
// invocation are one opinion written down N times.
|
|
1030
|
+
//
|
|
1031
|
+
// Until both are fixed — structural independence, and a base-ref read
|
|
1032
|
+
// — the ballot is RECORDED and never acted on. `main` runs the gate
|
|
1033
|
+
// for the ledger and the annotation; this list is untouched by it.
|
|
1034
|
+
// See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
|
|
393
1035
|
blocking.push(item);
|
|
394
1036
|
detail.push(renderFinding(i, finding));
|
|
395
1037
|
}
|
|
@@ -417,7 +1059,19 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
417
1059
|
// The decision, and the only place it is made. `verdict` is compared to it
|
|
418
1060
|
// afterwards; it never contributes to it.
|
|
419
1061
|
const blocked = blocking.length > 0;
|
|
420
|
-
|
|
1062
|
+
// The agreement is measured BEFORE CRC-B7's demotion, not after it.
|
|
1063
|
+
//
|
|
1064
|
+
// The reviewer is not given the pull request's file list, so it cannot know
|
|
1065
|
+
// a finding is pre-existing and its `BLOCK` over one is honest. Comparing
|
|
1066
|
+
// its word against the post-demotion count would turn every successful
|
|
1067
|
+
// demotion into a CONTRADICTION — the arm would fire on the mechanism
|
|
1068
|
+
// working, which is the loudest possible way to be wrong.
|
|
1069
|
+
//
|
|
1070
|
+
// The real contradiction #1178 exists for is untouched: a `BLOCK` over a
|
|
1071
|
+
// payload whose findings are ALL advisory has `demoted === 0`, so it still
|
|
1072
|
+
// fires. Measured at roughly 6 of 20 runs when that was written.
|
|
1073
|
+
const wouldBlock = blocked || demoted > 0;
|
|
1074
|
+
const agreed = verdict === (wouldBlock ? AI_REVIEW_BLOCK_VERDICT : AI_REVIEW_PASS_VERDICT);
|
|
421
1075
|
const outcome: AiReviewOutcome = !agreed ? "CONTRADICTION" : blocked ? "BLOCKED" : "CLEAN";
|
|
422
1076
|
|
|
423
1077
|
return {
|
|
@@ -428,25 +1082,179 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
|
|
|
428
1082
|
verdict,
|
|
429
1083
|
unmeasuredReasons: [],
|
|
430
1084
|
detail,
|
|
1085
|
+
// Both of these are `withScope`'s to set, and it is the only site that
|
|
1086
|
+
// sets either. A value here would be a second statement about the same
|
|
1087
|
+
// input, and the two could disagree.
|
|
1088
|
+
scope: scopeNotSupplied(),
|
|
1089
|
+
unlocatableReported: null,
|
|
1090
|
+
scopeDropped: null,
|
|
431
1091
|
};
|
|
432
1092
|
}
|
|
433
1093
|
|
|
1094
|
+
/**
|
|
1095
|
+
* The pull request's changed files, read from a newline-delimited file.
|
|
1096
|
+
*
|
|
1097
|
+
* `null` means the path was given and could not be read, which the caller
|
|
1098
|
+
* must NOT collapse into "no list was supplied" — see `readAiReviewFindings`
|
|
1099
|
+
* on why `undefined` and `[]` are different facts. This returns the third
|
|
1100
|
+
* one, and it is the same distinction a third time.
|
|
1101
|
+
*
|
|
1102
|
+
* Blank lines are dropped before the emptiness test, so a file containing
|
|
1103
|
+
* only whitespace reads as empty rather than as one unnamed file.
|
|
1104
|
+
*/
|
|
1105
|
+
/**
|
|
1106
|
+
* One repository path, in the one spelling both sides of CRC-B7's comparison
|
|
1107
|
+
* are reduced to — or `null` for "this cannot be read as a repository path".
|
|
1108
|
+
*
|
|
1109
|
+
* **`null` is the important return.** The first cut of CRC-B7 compared
|
|
1110
|
+
* `String(finding.file).toLowerCase()` against a raw list, and every input
|
|
1111
|
+
* the comparison could not read demoted a `critical` to CLEAN, because a
|
|
1112
|
+
* spelling that is never in the set is indistinguishable from a file the
|
|
1113
|
+
* pull request did not touch. Measured against a list holding `lib/mine.ts`:
|
|
1114
|
+
*
|
|
1115
|
+
* ```
|
|
1116
|
+
* CLEAN 0 blocking {} 123 "./lib/mine.ts" "lib/mine.ts:12"
|
|
1117
|
+
* CLEAN 0 blocking "lib\mine.ts" "/lib/mine.ts"
|
|
1118
|
+
* ```
|
|
1119
|
+
*
|
|
1120
|
+
* Six for six, five of them the SAME FILE spelt differently. `./x`, `/x`,
|
|
1121
|
+
* `x` and `x:12` are one file and four strings, and an equality test over
|
|
1122
|
+
* raw strings answers a different question from the one being asked.
|
|
1123
|
+
*
|
|
1124
|
+
* So both sides go through here, and a `null` on either side is a refusal
|
|
1125
|
+
* rather than a mismatch. The git C-quoted form — `"lib/\303\251.ts"`, which
|
|
1126
|
+
* git emits for a non-ASCII path unless `core.quotePath=false` — is
|
|
1127
|
+
* deliberately `null` rather than unescaped here: decoding octal escapes to
|
|
1128
|
+
* compare a path is a second parser, and the right repair is to produce the
|
|
1129
|
+
* list with `-z` or `core.quotePath=false` in the first place.
|
|
1130
|
+
*/
|
|
1131
|
+
export function normaliseRepoPath(value: unknown): string | null {
|
|
1132
|
+
if (typeof value !== "string") return null;
|
|
1133
|
+
let p = value.trim().replace(/\\/g, "/");
|
|
1134
|
+
// git's C-quoted spelling. Not comparable without a second unescaper.
|
|
1135
|
+
if (p.startsWith('"') && p.endsWith('"')) return null;
|
|
1136
|
+
p = p.replace(/^\/+/, "").replace(/:\d+(?::\d+)?$/, "");
|
|
1137
|
+
|
|
1138
|
+
// Dot segments are COLLAPSED, not stripped once. `.replace(/^\.\//, "")`
|
|
1139
|
+
// removes one leading `./` and leaves `././lib/a.ts` as `./lib/a.ts`, which
|
|
1140
|
+
// the shape test below accepts — `.` and `..` are both legal matches for
|
|
1141
|
+
// `[\w.@+-]+`. Measured on this file before the fix:
|
|
1142
|
+
//
|
|
1143
|
+
// "././lib/mine.ts" -> "./lib/mine.ts"
|
|
1144
|
+
// "lib/./mine.ts" -> "lib/./mine.ts"
|
|
1145
|
+
// "lib/../lib/mine.ts" -> "lib/../lib/mine.ts"
|
|
1146
|
+
//
|
|
1147
|
+
// Each compares unequal to `lib/mine.ts`, so a blocking finding naming the
|
|
1148
|
+
// file in one of those spellings was demoted to Pre-existing against a
|
|
1149
|
+
// change list that contained it — the same fail-open round one shipped,
|
|
1150
|
+
// in a narrower spelling. Found by the push review on this branch.
|
|
1151
|
+
//
|
|
1152
|
+
// A `..` that would leave the repository root is refused rather than
|
|
1153
|
+
// clamped: `../outside.ts` is not a repository-relative path, and turning
|
|
1154
|
+
// it into `outside.ts` invents a file this change may well have touched.
|
|
1155
|
+
const out: string[] = [];
|
|
1156
|
+
for (const segment of p.split("/")) {
|
|
1157
|
+
if (segment === "" || segment === ".") continue;
|
|
1158
|
+
if (segment === "..") {
|
|
1159
|
+
if (out.pop() === undefined) return null;
|
|
1160
|
+
continue;
|
|
1161
|
+
}
|
|
1162
|
+
out.push(segment);
|
|
1163
|
+
}
|
|
1164
|
+
p = out.join("/");
|
|
1165
|
+
if (p === "") return null;
|
|
1166
|
+
|
|
1167
|
+
return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p.toLowerCase() : null;
|
|
1168
|
+
}
|
|
1169
|
+
|
|
1170
|
+
/** What a changed-file list reduced to, split by whether it could be read. */
|
|
1171
|
+
export interface ChangedFilePartition {
|
|
1172
|
+
/**
|
|
1173
|
+
* The entries that normalised, in the one spelling both sides of the
|
|
1174
|
+
* comparison are reduced to. This is what `touched` is built from.
|
|
1175
|
+
*/
|
|
1176
|
+
readable: string[];
|
|
1177
|
+
/**
|
|
1178
|
+
* The entries that did not, RAW and in list order — so the reader can be
|
|
1179
|
+
* NAMED to whoever has to fix the tree, rather than counted at them.
|
|
1180
|
+
*/
|
|
1181
|
+
dropped: string[];
|
|
1182
|
+
}
|
|
1183
|
+
|
|
1184
|
+
/**
|
|
1185
|
+
* Split a changed-file list into the part this reader can compare against and
|
|
1186
|
+
* the part it cannot (#1472).
|
|
1187
|
+
*
|
|
1188
|
+
* **One exported binding, and the only place the split is decided.** A second
|
|
1189
|
+
* site answering "is this entry readable" would be two deciders over one
|
|
1190
|
+
* input, and a mutation of either would leave the other holding every case up
|
|
1191
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape). It is
|
|
1192
|
+
* exported so a battery has one thing to short-circuit.
|
|
1193
|
+
*
|
|
1194
|
+
* **Dropping is safe here and it is not an optimistic reading.** A narrower
|
|
1195
|
+
* `touched` can only demote MORE findings, never fewer — and the findings a
|
|
1196
|
+
* dropped entry could falsely demote are none at all, because BOTH sides of
|
|
1197
|
+
* the comparison go through `normaliseRepoPath`: an entry is dropped exactly
|
|
1198
|
+
* when it normalises to `null`, and a finding naming that same path
|
|
1199
|
+
* normalises to `null` too, which `readPayload` answers with *"it keeps
|
|
1200
|
+
* blocking: undecidable is not pre-existing"*. The set the drop could reach
|
|
1201
|
+
* and the set the drop cannot decide are the same set.
|
|
1202
|
+
*
|
|
1203
|
+
* What a drop must never be is SILENT. The caller carries `dropped` onto the
|
|
1204
|
+
* reading as `scopeDropped` and `aiReviewScopeLine` prints it on every run:
|
|
1205
|
+
* "this list was read in full" and "this list was read in part" are different
|
|
1206
|
+
* facts, and a reading over a narrowed set that does not say it was narrowed
|
|
1207
|
+
* is Silent Default Substitution (`.claude/rules/config-access.md`).
|
|
1208
|
+
*/
|
|
1209
|
+
export function partitionChangedFiles(
|
|
1210
|
+
changedFiles: readonly string[],
|
|
1211
|
+
): ChangedFilePartition {
|
|
1212
|
+
const readable: string[] = [];
|
|
1213
|
+
const dropped: string[] = [];
|
|
1214
|
+
for (const entry of changedFiles) {
|
|
1215
|
+
const normalised = normaliseRepoPath(entry);
|
|
1216
|
+
if (normalised === null) dropped.push(entry);
|
|
1217
|
+
else readable.push(normalised);
|
|
1218
|
+
}
|
|
1219
|
+
return { readable, dropped };
|
|
1220
|
+
}
|
|
1221
|
+
|
|
1222
|
+
// `readChangedFiles` lived here and is gone. It returned `null` for BOTH an
|
|
1223
|
+
// unreadable file and — via its caller — an empty one, and `main` reported
|
|
1224
|
+
// that single `null` as `CHANGED_FILES_EMPTY`. A failed `git diff` writes no
|
|
1225
|
+
// file at all, so that collapsed "the diff was lost" into "the diff was
|
|
1226
|
+
// empty", which are different facts with different repairs.
|
|
1227
|
+
// `readAiReviewChangedFiles` replaces it and keeps them apart.
|
|
1228
|
+
|
|
434
1229
|
/** Read the payload from disk. An absent file and an unreadable one differ. */
|
|
435
|
-
export function readAiReviewFindingsFile(
|
|
1230
|
+
export function readAiReviewFindingsFile(
|
|
1231
|
+
path: string,
|
|
1232
|
+
scope: AiReviewScopeReading = scopeNotSupplied(),
|
|
1233
|
+
): AiReviewFindingsReading {
|
|
436
1234
|
let raw: string;
|
|
437
1235
|
try {
|
|
438
1236
|
raw = readFileSync(path, "utf-8");
|
|
439
1237
|
} catch (e) {
|
|
440
1238
|
const code = (e as NodeJS.ErrnoException).code;
|
|
441
1239
|
if (code === "ENOENT") {
|
|
442
|
-
return
|
|
1240
|
+
return withScope(
|
|
1241
|
+
unmeasured(["FINDINGS_FILE_ABSENT"], [`no findings payload at ${path}`]),
|
|
1242
|
+
scope,
|
|
1243
|
+
null,
|
|
1244
|
+
null,
|
|
1245
|
+
);
|
|
443
1246
|
}
|
|
444
|
-
return
|
|
445
|
-
|
|
446
|
-
|
|
1247
|
+
return withScope(
|
|
1248
|
+
unmeasured(
|
|
1249
|
+
["FINDINGS_FILE_UNREADABLE"],
|
|
1250
|
+
[`the findings payload at ${path} could not be read: ${(e as Error).message}`],
|
|
1251
|
+
),
|
|
1252
|
+
scope,
|
|
1253
|
+
null,
|
|
1254
|
+
null,
|
|
447
1255
|
);
|
|
448
1256
|
}
|
|
449
|
-
return readAiReviewFindings(raw);
|
|
1257
|
+
return readAiReviewFindings(raw, scope);
|
|
450
1258
|
}
|
|
451
1259
|
|
|
452
1260
|
/** The sentence a refusal prints, or `null` when there is nothing to refuse. */
|
|
@@ -509,21 +1317,293 @@ export function aiReviewExitCode(reading: AiReviewFindingsReading): number {
|
|
|
509
1317
|
return reading.outcome === "CLEAN" ? 0 : AI_REVIEW_REQUIRED_EXIT;
|
|
510
1318
|
}
|
|
511
1319
|
|
|
1320
|
+
/** The annotation title the verifier quorum's own reading is printed under. */
|
|
1321
|
+
export const AI_REVIEW_JURY_NOTICE_TITLE = "AI review verifier quorum";
|
|
1322
|
+
|
|
512
1323
|
/**
|
|
513
|
-
* The
|
|
1324
|
+
* The title the quorum's UNMEASURED state is named under.
|
|
514
1325
|
*
|
|
515
|
-
*
|
|
516
|
-
*
|
|
1326
|
+
* A SEPARATE title, because it is a different fact with a different fix: a
|
|
1327
|
+
* group that met and disagreed is a reading, and a group that did not meet
|
|
1328
|
+
* is not one. GitHub groups annotations by title, so one title for both
|
|
1329
|
+
* would make the absence read as part of the vote.
|
|
1330
|
+
*/
|
|
1331
|
+
export const AI_REVIEW_JURY_UNMEASURED_TITLE = "AI review verifier quorum UNMEASURED";
|
|
1332
|
+
|
|
1333
|
+
/**
|
|
1334
|
+
* The verifier quorum, as `main` consumes it (CRC-B4).
|
|
1335
|
+
*
|
|
1336
|
+
* **Injected, not imported**, and the reason is mechanical rather than
|
|
1337
|
+
* stylistic. This module is copied into a scratch directory by three
|
|
1338
|
+
* mutation batteries, which carry its one relative dependency —
|
|
1339
|
+
* `./ai-review-step`, which has none — along with it. `lib/ai-review-jury.ts`
|
|
1340
|
+
* pulls in the finding arbiter and the filing gate behind it, and a mutant
|
|
1341
|
+
* that dies on module resolution reports zero findings, which reads exactly
|
|
1342
|
+
* like a guard behaving differently
|
|
1343
|
+
* (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
|
|
1344
|
+
*
|
|
1345
|
+
* **The gate decides nothing.** It is consulted after the reading is
|
|
1346
|
+
* complete, its answer reaches an annotation and the finding ledger, and
|
|
1347
|
+
* `reading` is not rebuilt from it.
|
|
1348
|
+
*
|
|
1349
|
+
* So a gate that is absent, unreadable, malformed **or throwing** leaves
|
|
1350
|
+
* the verdict alone — and the last of those four is enforced by a `try`
|
|
1351
|
+
* at the call site rather than by this sentence. It is listed explicitly
|
|
1352
|
+
* because the first draft of this docblock claimed all four while only
|
|
1353
|
+
* three held: the call was outside any `catch`, so a throwing gate
|
|
1354
|
+
* propagated out of `main` and killed the process above the outcome
|
|
1355
|
+
* marker. A comment asserting a property the code lacks is the reason
|
|
1356
|
+
* nobody checks it — the instance this repository keeps is
|
|
1357
|
+
* `lib/cli-commands.ts`'s "runs every command for real" over a test that
|
|
1358
|
+
* ran one command of ten. `JG-6h` is now the assertion.
|
|
1359
|
+
*
|
|
1360
|
+
* That is the only honest arrangement while the group casting the votes
|
|
1361
|
+
* is not yet structurally independent. See `AI_REVIEW_JURY_NOTICE_TITLE`.
|
|
1362
|
+
*
|
|
1363
|
+
* **It takes the findings and nothing else.** The ballot directory is
|
|
1364
|
+
* bound by whoever supplies the gate, so this module never learns a path
|
|
1365
|
+
* and the CLI's argv contract — two positionals, `argv[2]` and up refused
|
|
1366
|
+
* — is untouched. A gate that is `null` is the whole of "no ballot".
|
|
1367
|
+
*/
|
|
1368
|
+
export interface AiReviewJuryGate {
|
|
1369
|
+
(blocking: readonly unknown[]): {
|
|
1370
|
+
/**
|
|
1371
|
+
* One entry per blocking finding, **in input order** — the sentence
|
|
1372
|
+
* saying the group would have withheld it, or `null`.
|
|
1373
|
+
*
|
|
1374
|
+
* Positional rather than keyed, and that is the contract rather than a
|
|
1375
|
+
* convenience. A map from a finding identity would be a SECOND
|
|
1376
|
+
* derivation of that identity over a list already produced in order,
|
|
1377
|
+
* and two findings sharing a key would share a vote.
|
|
1378
|
+
* `lib/finding-arbiter.ts`'s `SHARED_BALLOT` refuses exactly that one
|
|
1379
|
+
* level down — *"a vote is about a finding"*.
|
|
1380
|
+
*
|
|
1381
|
+
* **"Would have".** Nothing here subtracts: the entry is recorded and
|
|
1382
|
+
* announced, and the finding blocks exactly as it did before the group
|
|
1383
|
+
* met.
|
|
1384
|
+
*/
|
|
1385
|
+
wouldWithhold: readonly (string | null)[];
|
|
1386
|
+
/** Non-null when the ballot source could not be read. Never fatal. */
|
|
1387
|
+
unmeasured: string | null;
|
|
1388
|
+
/** One sentence per finding voted on. */
|
|
1389
|
+
detail: readonly string[];
|
|
1390
|
+
};
|
|
1391
|
+
}
|
|
1392
|
+
|
|
1393
|
+
/**
|
|
1394
|
+
* The line recording how the scope reading was taken, and the two counts a
|
|
1395
|
+
* reader needs to see differ when the gate fires (#1204).
|
|
1396
|
+
*
|
|
1397
|
+
* The number of findings PRODUCED and the number ALLOWED TO BLOCK are both
|
|
1398
|
+
* printed, because a review that quietly demoted a finding and a review that
|
|
1399
|
+
* never had one are otherwise the same output. The blocking count is
|
|
1400
|
+
* `withheld` under an UNMEASURED reading rather than `0` — the decision is
|
|
1401
|
+
* withheld there, and printing a number would be inventing one.
|
|
1402
|
+
*
|
|
1403
|
+
* It also reports its own COVERAGE of the changed-file list (#1472): a scan
|
|
1404
|
+
* that reports a verdict should say how much of its input it read. An entry
|
|
1405
|
+
* this reader could not normalise is dropped from the comparison rather than
|
|
1406
|
+
* refusing the whole run, so `dropped` is what keeps "the list was read in
|
|
1407
|
+
* full" apart from "the list was read in part" — and the entries are NAMED,
|
|
1408
|
+
* because a warning that does not say what was missing is a warning nobody
|
|
1409
|
+
* can act on. `not checked`, `0` and a named list are three facts, not one.
|
|
1410
|
+
*/
|
|
1411
|
+
export function aiReviewScopeLine(reading: AiReviewFindingsReading): string {
|
|
1412
|
+
const produced = reading.reported?.length ?? 0;
|
|
1413
|
+
const blocking =
|
|
1414
|
+
reading.blockingReported === null ? "withheld" : String(reading.blockingReported.length);
|
|
1415
|
+
const unlocatable =
|
|
1416
|
+
reading.unlocatableReported === null ? "not checked" : String(reading.unlocatableReported.length);
|
|
1417
|
+
const drops = reading.scopeDropped;
|
|
1418
|
+
const dropped =
|
|
1419
|
+
drops === null
|
|
1420
|
+
? "not checked"
|
|
1421
|
+
: drops.length === 0
|
|
1422
|
+
? "0"
|
|
1423
|
+
: `${drops.length} (${drops.map(p => JSON.stringify(p)).join(", ")}), ` +
|
|
1424
|
+
`so this comparison ran over a NARROWER set than the pull request touched`;
|
|
1425
|
+
return (
|
|
1426
|
+
`${AI_REVIEW_SCOPE_LINE} ${reading.scope.status} — findings reported: ${produced}, ` +
|
|
1427
|
+
`allowed to block: ${blocking}, unlocatable: ${unlocatable}, ` +
|
|
1428
|
+
`changed-file entries dropped: ${dropped}. ${reading.scope.detail}`
|
|
1429
|
+
);
|
|
1430
|
+
}
|
|
1431
|
+
|
|
1432
|
+
// `parseFindingsArgv` and `AiReviewFindingsArgv` lived here and are gone.
|
|
1433
|
+
// The parser refused a SECOND POSITIONAL argument by design, which is
|
|
1434
|
+
// exactly the invocation CRC-B7 deploys, so the flag CLI and the
|
|
1435
|
+
// positional one could not both stand. See `main` below.
|
|
1436
|
+
//
|
|
1437
|
+
// What the parser ALSO did is kept, in `argumentsBeyondTheContract`: it
|
|
1438
|
+
// refused an argument nothing reads, rather than dropping it. Deleting the
|
|
1439
|
+
// parser silently took that with it — measured, not assumed, on the merged
|
|
1440
|
+
// tree: `main([payload, list, "extra"])` returned 0 and printed CLEAN. A
|
|
1441
|
+
// dropped argument is a caller asking for something that did not happen,
|
|
1442
|
+
// which is the same fault as a skipped check wearing different clothes.
|
|
1443
|
+
|
|
1444
|
+
/**
|
|
1445
|
+
* The arguments past the two this CLI reads. One exported binding, so the
|
|
1446
|
+
* refusal has a single site to mutate (`checks-must-be-able-to-fail.md`).
|
|
1447
|
+
*
|
|
1448
|
+
* It returns the arguments rather than a boolean because the refusal names
|
|
1449
|
+
* them: "an argument was ignored" is not something an operator can act on,
|
|
1450
|
+
* and the failing invocation is usually a workflow line nobody can see from
|
|
1451
|
+
* the log.
|
|
1452
|
+
*/
|
|
1453
|
+
export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
|
|
1454
|
+
return argv.slice(2);
|
|
1455
|
+
}
|
|
1456
|
+
|
|
1457
|
+
/**
|
|
1458
|
+
* The CLI the generated workflow step runs: the payload's path, and
|
|
1459
|
+
* optionally a second POSITIONAL path to the pull request's changed files.
|
|
1460
|
+
*
|
|
1461
|
+
* Positional, not a `--changed-files` flag. #1204 wrote the flag and CRC-B7
|
|
1462
|
+
* wrote the positional; the generated step passes positionally and #1356
|
|
1463
|
+
* builds on that, so the flag is the spelling that goes. Two spellings for
|
|
1464
|
+
* one argument would be two deciders over the same input, and the one the
|
|
1465
|
+
* deployed workflow does not use is the one that would rot.
|
|
1466
|
+
*
|
|
1467
|
+
* The second argument is optional: a caller that does not pass one gets
|
|
1468
|
+
* exactly the reading this module gave before any of this was wired, which
|
|
1469
|
+
* is what keeps every existing consumer working unchanged.
|
|
1470
|
+
*
|
|
1471
|
+
* An unreadable list is NOT silently treated as absent, and `readAiReview-
|
|
1472
|
+
* ChangedFiles` is what keeps those apart — `CHANGED_FILES_UNREADABLE` for a
|
|
1473
|
+
* list that was named and could not be read, `CHANGED_FILES_EMPTY` for one
|
|
1474
|
+
* that was read and names nothing. A failed `git diff` writes no file at
|
|
1475
|
+
* all, so collapsing the two would report a diff that was lost as a diff
|
|
1476
|
+
* that was taken.
|
|
1477
|
+
*
|
|
1478
|
+
* An argument past those two REFUSES. Nothing reads it, and a CLI that
|
|
1479
|
+
* accepts an argument it ignores reports success for an invocation that did
|
|
1480
|
+
* not happen.
|
|
1481
|
+
*
|
|
1482
|
+
* Separate from `main` so the argv contract is decided in one place and
|
|
1483
|
+
* `main` is only the printing. A refusal reached here still prints the
|
|
1484
|
+
* outcome line and the scope line, because the generated step reads the
|
|
1485
|
+
* outcome line before it reads the exit code.
|
|
517
1486
|
*/
|
|
518
|
-
|
|
1487
|
+
function readArgv(argv: string[]): AiReviewFindingsReading {
|
|
1488
|
+
const extra = argumentsBeyondTheContract(argv);
|
|
1489
|
+
if (extra.length > 0) {
|
|
1490
|
+
// Scope is NOT read here. The argv is already known to be a shape this
|
|
1491
|
+
// CLI does not accept, so which file argv[1] names is a question about
|
|
1492
|
+
// an invocation that is being refused.
|
|
1493
|
+
return withScope(
|
|
1494
|
+
unmeasured(
|
|
1495
|
+
["ARGUMENTS_UNREADABLE"],
|
|
1496
|
+
[
|
|
1497
|
+
`${extra.length} argument(s) past the findings payload and the changed-file ` +
|
|
1498
|
+
`list were given and nothing reads them: ${extra.map(a => JSON.stringify(a)).join(", ")}. ` +
|
|
1499
|
+
`Usage: <path-to-findings.json> [<path-to-changed-files.txt>]`,
|
|
1500
|
+
],
|
|
1501
|
+
),
|
|
1502
|
+
scopeNotSupplied(),
|
|
1503
|
+
null,
|
|
1504
|
+
null,
|
|
1505
|
+
);
|
|
1506
|
+
}
|
|
1507
|
+
|
|
519
1508
|
const path = argv[0];
|
|
520
|
-
const
|
|
521
|
-
|
|
522
|
-
|
|
1509
|
+
const scope = readAiReviewChangedFiles(argv[1]);
|
|
1510
|
+
return path === undefined || path === ""
|
|
1511
|
+
? withScope(
|
|
1512
|
+
unmeasured(
|
|
523
1513
|
["FINDINGS_FILE_ABSENT"],
|
|
524
1514
|
["no findings payload path was given to the findings reader"],
|
|
525
|
-
)
|
|
526
|
-
|
|
1515
|
+
),
|
|
1516
|
+
scope,
|
|
1517
|
+
null,
|
|
1518
|
+
null,
|
|
1519
|
+
)
|
|
1520
|
+
: readAiReviewFindingsFile(path, scope);
|
|
1521
|
+
}
|
|
1522
|
+
|
|
1523
|
+
/**
|
|
1524
|
+
* The CLI entry point. `readArgv` above decides what the arguments mean;
|
|
1525
|
+
* everything here is emission.
|
|
1526
|
+
*
|
|
1527
|
+
* Returns the exit code rather than calling `process.exit`, so a test can run
|
|
1528
|
+
* it in-process as well as spawn it.
|
|
1529
|
+
*/
|
|
1530
|
+
export function main(argv: string[], jury: AiReviewJuryGate | null = null): number {
|
|
1531
|
+
const reading = readArgv(argv);
|
|
1532
|
+
|
|
1533
|
+
// CRC-B4, AFTER the reading and feeding nothing back into it.
|
|
1534
|
+
//
|
|
1535
|
+
// The group votes on `blockingReported` — the existing decider's own
|
|
1536
|
+
// answer to "which of these block", never a list re-derived from the
|
|
1537
|
+
// severities, which is the criterion's first clause: a quorum over the
|
|
1538
|
+
// advisory tail spends a full agent context per nit.
|
|
1539
|
+
//
|
|
1540
|
+
// WHAT IT DOES NOT DO IS SUBTRACT, and that is a decision with two
|
|
1541
|
+
// reasons, both of them properties of the tree rather than of this
|
|
1542
|
+
// function:
|
|
1543
|
+
//
|
|
1544
|
+
// - **The group is not independent yet.** `AI_REVIEW_ALLOWED_TOOLS`
|
|
1545
|
+
// grants the review action `Read,Grep,Glob,Write` and
|
|
1546
|
+
// `AI_REVIEW_DENY_RULES` denies `Task`, so one invocation cannot spawn
|
|
1547
|
+
// verifiers. Independence has to be a property of the WORKFLOW — one
|
|
1548
|
+
// action invocation per verifier — and a ballot that subtracts before
|
|
1549
|
+
// that holds is a quorum wired to a constant: populated, plausible,
|
|
1550
|
+
// and filtering nothing. That is the counterfeit CRC-B4 names.
|
|
1551
|
+
// - **The verifier reads the head checkout.** A subtracting ballot would
|
|
1552
|
+
// make the branch under review an input to the gate on the branch
|
|
1553
|
+
// under review.
|
|
1554
|
+
//
|
|
1555
|
+
// So the votes are counted, written to the finding ledger at decision
|
|
1556
|
+
// time, and announced. Nothing below reads `gate` except the annotation.
|
|
1557
|
+
// CRC-B4's *"surfaced only if enough agree"* clause is therefore NOT
|
|
1558
|
+
// satisfied, and the spec says so rather than this comment alone.
|
|
1559
|
+
//
|
|
1560
|
+
// **The ballot directory is NOT a third positional argument**, and that
|
|
1561
|
+
// is deliberate rather than incidental. `argumentsBeyondTheContract`
|
|
1562
|
+
// refuses `argv[2]` and up, and one of the invocations it catches is a
|
|
1563
|
+
// changed-file path containing a space that an unquoted expansion
|
|
1564
|
+
// word-split into two — `test/ai-review-changed-files-step.test.ts`
|
|
1565
|
+
// CF-6 names that case. Widening the contract by one slot to carry a
|
|
1566
|
+
// ballot would turn that refusal into an accepted argv whose second
|
|
1567
|
+
// half is read as a ballot directory. So the directory binds at the
|
|
1568
|
+
// wrapper, which closes over it and hands this function a gate or
|
|
1569
|
+
// `null`; "no ballot" and "a ballot nothing reads" collapse into one
|
|
1570
|
+
// state that cannot be reached.
|
|
1571
|
+
let juryDetail: readonly string[] = [];
|
|
1572
|
+
let juryUnmeasured: string | null = null;
|
|
1573
|
+
if (jury !== null && reading.blockingReported !== null && reading.blockingReported.length > 0) {
|
|
1574
|
+
try {
|
|
1575
|
+
const gate = jury(reading.blockingReported);
|
|
1576
|
+
juryDetail = gate.detail;
|
|
1577
|
+
juryUnmeasured = gate.unmeasured;
|
|
1578
|
+
} catch (e) {
|
|
1579
|
+
// A FAIL-OPEN, DELIBERATELY, and this is the one arrangement where
|
|
1580
|
+
// that is the correct choice rather than the first thing
|
|
1581
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` tells you to
|
|
1582
|
+
// distrust. Its warning is about a guard that converts its own
|
|
1583
|
+
// breakage into "no problems found". This gate finds no problems
|
|
1584
|
+
// and gates nothing: the verdict is `aiReviewExitCode(reading)`
|
|
1585
|
+
// either way, so catching here cannot hide a finding — it can only
|
|
1586
|
+
// stop an advisory recorder from deciding a review it has no vote
|
|
1587
|
+
// in. The day the ballot is allowed to subtract, this catch must
|
|
1588
|
+
// become a refusal, and that is the line to change.
|
|
1589
|
+
//
|
|
1590
|
+
// Without it the throw propagates out of `main`, so
|
|
1591
|
+
// `process.exit(main(...))` never runs and a CLEAN review dies
|
|
1592
|
+
// non-zero. Worse than the exit code: this block sits ABOVE the
|
|
1593
|
+
// `AI_REVIEW_OUTCOME_LINE` print, which the generated step greps
|
|
1594
|
+
// for before it will read an exit code as a verdict, so the step
|
|
1595
|
+
// sees an adjudicator that could not run rather than a verdict.
|
|
1596
|
+
//
|
|
1597
|
+
// Three things inside the real gate are outside any catch of their
|
|
1598
|
+
// own — `juryReading`, `advisoryKey` over a hostile payload, and
|
|
1599
|
+
// all of `juryLedgerRow`. `JG-6h` is this case.
|
|
1600
|
+
juryUnmeasured =
|
|
1601
|
+
`the verifier quorum threw and was not counted, so no vote was recorded for this ` +
|
|
1602
|
+
`run: ${(e as Error).message}. The verdict below is the adjudicator's own and is ` +
|
|
1603
|
+
`unchanged — the group decides nothing this round — but the votes for these findings ` +
|
|
1604
|
+
`are lost rather than merely unfavourable, and the ledger has no row to recover`;
|
|
1605
|
+
}
|
|
1606
|
+
}
|
|
527
1607
|
|
|
528
1608
|
// FIRST, and before any branch below can return. The generated workflow step
|
|
529
1609
|
// greps its own output for this prefix and will not read the exit code as a
|
|
@@ -531,6 +1611,16 @@ export function main(argv: string[]): number {
|
|
|
531
1611
|
// refused both exit non-zero, and only this line tells them apart.
|
|
532
1612
|
console.log(`${AI_REVIEW_OUTCOME_LINE} ${reading.outcome}`);
|
|
533
1613
|
|
|
1614
|
+
// AFTER the outcome line, and never instead of it. The generated step lifts
|
|
1615
|
+
// its verdict from the FIRST occurrence of that marker, so this line cannot
|
|
1616
|
+
// move it. Printed on EVERY run, including the one where no list was
|
|
1617
|
+
// supplied: an absent input that nothing reports is Silent Default
|
|
1618
|
+
// Substitution, and this line is the whole of what makes the skip a
|
|
1619
|
+
// reading. Escaped at emission like the annotation below — a path arriving
|
|
1620
|
+
// on the command line reaches a stream GitHub parses workflow commands out
|
|
1621
|
+
// of, and this module escapes exactly once, at the point of emission.
|
|
1622
|
+
console.log(escapeAnnotation(aiReviewScopeLine(reading)));
|
|
1623
|
+
|
|
534
1624
|
// The ONE place a value reaches a workflow command. Everything upstream of
|
|
535
1625
|
// here — `renderFinding`, every `detail` sentence, `aiReviewRefusal` — builds
|
|
536
1626
|
// plain text and leaves escaping alone, so there is one binding to mutate and
|
|
@@ -540,6 +1630,55 @@ export function main(argv: string[]): number {
|
|
|
540
1630
|
console.error(`::error title=${AI_REVIEW_FINDINGS_TITLE}::${escapeAnnotation(refusal)}`);
|
|
541
1631
|
}
|
|
542
1632
|
|
|
1633
|
+
// AFTER the refusal and BEFORE the exit code, and on its own title. A
|
|
1634
|
+
// `::notice` rather than a `::warning` or an `::error`: the advisory tail
|
|
1635
|
+
// does not block, and a notice is what GitHub records against the check run
|
|
1636
|
+
// without changing its conclusion. It goes through the same single escaper
|
|
1637
|
+
// the refusal does — this is a new value reaching a workflow command, and
|
|
1638
|
+
// `escapeAnnotation`'s own docblock has the measured instance of what an
|
|
1639
|
+
// unescaped one can do to a verdict.
|
|
1640
|
+
const advisory = advisoryNotice(reading);
|
|
1641
|
+
if (advisory !== null) {
|
|
1642
|
+
console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
|
|
1643
|
+
}
|
|
1644
|
+
|
|
1645
|
+
// The quorum's own reading, on its own title, and emitted whatever the
|
|
1646
|
+
// outcome was. The ledger row is the durable record and it lives on the
|
|
1647
|
+
// runner, which dies with the job; this annotation is the only part of
|
|
1648
|
+
// the vote that outlives the run, so it carries the whole reading rather
|
|
1649
|
+
// than a count.
|
|
1650
|
+
//
|
|
1651
|
+
// A `::notice`, never an `::error`. The ballot decides nothing this round
|
|
1652
|
+
// and an annotation that reddened a check would be a gate arriving by the
|
|
1653
|
+
// back door — see the block above `juryDetail`.
|
|
1654
|
+
if (juryDetail.length > 0) {
|
|
1655
|
+
console.log(
|
|
1656
|
+
`::notice title=${AI_REVIEW_JURY_NOTICE_TITLE}::${escapeAnnotation(
|
|
1657
|
+
`A separate verifier group voted on the ${juryDetail.length} finding(s) that would ` +
|
|
1658
|
+
`otherwise block. ${juryDetail.join("; ")}. THE VOTE IS RECORDED AND CHANGES ` +
|
|
1659
|
+
`NOTHING: every finding above blocks exactly as it would have without it. The ` +
|
|
1660
|
+
`group is not yet structurally independent and reads the head checkout, so acting ` +
|
|
1661
|
+
`on it would be a gate whose input is the thing it gates.`,
|
|
1662
|
+
)}`,
|
|
1663
|
+
);
|
|
1664
|
+
}
|
|
1665
|
+
|
|
1666
|
+
// A `::warning`, and the state is NAMED. An absent or unreadable ballot
|
|
1667
|
+
// exiting 0 with no output is the Silent Default Substitution
|
|
1668
|
+
// `.claude/rules/config-access.md` forbids: `0`, `{}` and `null` are
|
|
1669
|
+
// indistinguishable from success and UNMEASURED is not. It does not
|
|
1670
|
+
// refuse, because the consumer decides whether an unmeasured quorum is
|
|
1671
|
+
// fatal and the honest default for a mechanism with no readings yet is an
|
|
1672
|
+
// annotation rather than a red pipeline.
|
|
1673
|
+
if (juryUnmeasured !== null) {
|
|
1674
|
+
console.log(
|
|
1675
|
+
`::warning title=${AI_REVIEW_JURY_UNMEASURED_TITLE}::${escapeAnnotation(
|
|
1676
|
+
`The verifier quorum is UNMEASURED for this run: ${juryUnmeasured}. No finding's ` +
|
|
1677
|
+
`status changed either way.`,
|
|
1678
|
+
)}`,
|
|
1679
|
+
);
|
|
1680
|
+
}
|
|
1681
|
+
|
|
543
1682
|
return aiReviewExitCode(reading);
|
|
544
1683
|
}
|
|
545
1684
|
|