rungate 0.8.4 → 0.8.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/gates/.gate-salt +1 -1
- package/lib/ai-review-suppression.ts +295 -0
- package/lib/finding-jury.ts +9 -2
- package/lib/scaffold/ai-review-findings.ts +268 -14
- package/lib/scaffold/ai-review-step.ts +121 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +45 -2
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
d12afb85b5ce604fa58cf050d86b431d8f5d26e9e0dc5f33320e97f7bf51bbc3
|
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CRC-N4's suppression gate — the production caller `suppressRepeats` never
|
|
3
|
+
* had (#1586).
|
|
4
|
+
*
|
|
5
|
+
* `lib/ai-review-rounds.ts` has exported `carryKey → suppressRepeats` since
|
|
6
|
+
* #1351 and nothing called either. #1381 shipped the WALKER — the generated
|
|
7
|
+
* `ai-review-carry` step reads the ledger and hands the reviewer the
|
|
8
|
+
* unresolved set — so a repeat became *marked* rather than *dropped*. This is
|
|
9
|
+
* the half that drops it.
|
|
10
|
+
*
|
|
11
|
+
* ## Why the prior state arrives as a file and not as a fetch
|
|
12
|
+
*
|
|
13
|
+
* The generated job runs `ai-review-carry` → the reviewer →
|
|
14
|
+
* `ai-review-persist`, **which upserts this round into the ledger comment** →
|
|
15
|
+
* `ai-review-run`, which invokes the adjudicator. A gate that fetched the
|
|
16
|
+
* ledger itself would read a comment that already contains the payload it is
|
|
17
|
+
* deciding about: every finding would match a "prior" key that is its own,
|
|
18
|
+
* every round would suppress everything, and the outcome would be CLEAN
|
|
19
|
+
* forever. The carry step is the last position holding the state as it was
|
|
20
|
+
* before the reviewer ran, so it writes a snapshot and this reads it.
|
|
21
|
+
*
|
|
22
|
+
* ## Two files, because one of them cannot say why it is absent
|
|
23
|
+
*
|
|
24
|
+
* The snapshot carries BYTES and exists only on the READ path. The carry file
|
|
25
|
+
* carries the STATE and is written on every path by the single `carry_state`
|
|
26
|
+
* site. An absent snapshot therefore never means "no earlier findings" — the
|
|
27
|
+
* carry file says which of `AI_REVIEW_CARRY_READ`, `AI_REVIEW_CARRY_ABSENT`
|
|
28
|
+
* and `AI_REVIEW_CARRY_UNMEASURED` produced it. Collapsing those is #1568, in
|
|
29
|
+
* the half that decides a required check.
|
|
30
|
+
*
|
|
31
|
+
* ## Every refusal suppresses NOTHING
|
|
32
|
+
*
|
|
33
|
+
* There is one direction of error this module is allowed to make. Re-posting
|
|
34
|
+
* an advisory that was already answered is loud, cheap and self-correcting;
|
|
35
|
+
* dropping a finding that is still live is silent and permanent. So an
|
|
36
|
+
* unreadable carry file, an unreadable snapshot, a stale snapshot, an
|
|
37
|
+
* unrecognised identity rule and a ledger that will not parse all produce the
|
|
38
|
+
* same behaviour — report everything — and each produces a DIFFERENT sentence
|
|
39
|
+
* saying so, because "nothing was a repeat" and "nothing could be compared"
|
|
40
|
+
* are different facts about this round's report.
|
|
41
|
+
*
|
|
42
|
+
* ## It never sees a blocking finding
|
|
43
|
+
*
|
|
44
|
+
* `findingMustAlwaysBeReported` in `lib/scaffold/ai-review-findings.ts`
|
|
45
|
+
* filters before anything reaches this gate. The exemption is structural, not
|
|
46
|
+
* a rule this module is trusted to follow — see that predicate for the
|
|
47
|
+
* measurement, and for the declared deviation from the spec it rests on.
|
|
48
|
+
*/
|
|
49
|
+
import { readFileSync } from "fs";
|
|
50
|
+
import { isAbsolute, resolve, sep } from "path";
|
|
51
|
+
|
|
52
|
+
import {
|
|
53
|
+
AI_REVIEW_PRIOR_MEASURED,
|
|
54
|
+
carryKey,
|
|
55
|
+
priorFindings,
|
|
56
|
+
readLedger,
|
|
57
|
+
type ReviewFinding,
|
|
58
|
+
} from "./ai-review-rounds";
|
|
59
|
+
import {
|
|
60
|
+
AI_REVIEW_CARRY_ABSENT,
|
|
61
|
+
AI_REVIEW_CARRY_READ,
|
|
62
|
+
AI_REVIEW_CARRY_STATE_KEY,
|
|
63
|
+
AI_REVIEW_CARRY_UNMEASURED,
|
|
64
|
+
AI_REVIEW_SNAPSHOT_ROUND_KEY,
|
|
65
|
+
} from "./scaffold/ai-review-step";
|
|
66
|
+
import type { AiReviewSuppressionGate } from "./scaffold/ai-review-findings";
|
|
67
|
+
|
|
68
|
+
/** What the gate reads, so a test can drive it without a filesystem. */
|
|
69
|
+
export interface SuppressionInputs {
|
|
70
|
+
/** The carry file's contents, or `null` when it could not be read. */
|
|
71
|
+
carry: string | null;
|
|
72
|
+
/** The snapshot's contents, or `null` when it could not be read. */
|
|
73
|
+
snapshot: string | null;
|
|
74
|
+
/** The text at a finding's cited line NOW, or `undefined`. */
|
|
75
|
+
lineTextFor: (finding: ReviewFinding) => string | undefined;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** A prior set that was established, or the sentence saying it was not. */
|
|
79
|
+
export type PriorKeys =
|
|
80
|
+
| { status: "MEASURED"; keys: string[] }
|
|
81
|
+
| { status: "UNMEASURED"; reason: string };
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The carry file's first line, which is the one site that decided the state.
|
|
85
|
+
*
|
|
86
|
+
* Read rather than re-derived: the walker already made this decision against
|
|
87
|
+
* the live API, and a second reading here would be a second decider over the
|
|
88
|
+
* same question — which is the shape #1568 cost three rounds of #1569.
|
|
89
|
+
*/
|
|
90
|
+
export function carryStateOf(carry: string | null): string | null {
|
|
91
|
+
if (carry === null) return null;
|
|
92
|
+
const first = carry.split("\n", 1)[0] ?? "";
|
|
93
|
+
const prefix = `${AI_REVIEW_CARRY_STATE_KEY}=`;
|
|
94
|
+
return first.startsWith(prefix) ? first.slice(prefix.length).trim() : null;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Split the snapshot into the round it precedes and the ledger body.
|
|
99
|
+
*
|
|
100
|
+
* `round` is `null` when the header is missing or not an integer, and that is
|
|
101
|
+
* a REFUSAL rather than a default: a snapshot that cannot say which round it
|
|
102
|
+
* precedes cannot be shown to predate this one.
|
|
103
|
+
*/
|
|
104
|
+
export function readSnapshot(snapshot: string): { round: number | null; body: string } {
|
|
105
|
+
const at = snapshot.indexOf("\n");
|
|
106
|
+
const head = at === -1 ? snapshot : snapshot.slice(0, at);
|
|
107
|
+
const body = at === -1 ? "" : snapshot.slice(at + 1);
|
|
108
|
+
const prefix = `${AI_REVIEW_SNAPSHOT_ROUND_KEY}=`;
|
|
109
|
+
if (!head.startsWith(prefix)) return { round: null, body };
|
|
110
|
+
const raw = head.slice(prefix.length).trim();
|
|
111
|
+
return { round: /^\d+$/.test(raw) ? Number(raw) : null, body };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Turn the two files into the keys earlier rounds raised, or the sentence
|
|
116
|
+
* saying they could not be established.
|
|
117
|
+
*
|
|
118
|
+
* Exported and pure so the battery can drive every refusal without a
|
|
119
|
+
* filesystem, and so there is one place to mutate.
|
|
120
|
+
*/
|
|
121
|
+
export function priorKeysFrom(carry: string | null, snapshot: string | null): PriorKeys {
|
|
122
|
+
const state = carryStateOf(carry);
|
|
123
|
+
if (state === null) {
|
|
124
|
+
return {
|
|
125
|
+
status: "UNMEASURED",
|
|
126
|
+
reason:
|
|
127
|
+
"the carry step's own reading could not be read, so whether this pull request has " +
|
|
128
|
+
"earlier rounds is unknown",
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
if (state === AI_REVIEW_CARRY_UNMEASURED) {
|
|
132
|
+
return {
|
|
133
|
+
status: "UNMEASURED",
|
|
134
|
+
reason: "the carry step reported that the pull request's history could not be read",
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
// A complete reading, and the answer is that there is nothing to compare
|
|
138
|
+
// against. MEASURED with no keys, which is not the same statement as the
|
|
139
|
+
// branch above and must not print the same sentence.
|
|
140
|
+
if (state === AI_REVIEW_CARRY_ABSENT) return { status: "MEASURED", keys: [] };
|
|
141
|
+
if (state !== AI_REVIEW_CARRY_READ) {
|
|
142
|
+
return {
|
|
143
|
+
status: "UNMEASURED",
|
|
144
|
+
reason: `the carry step reported a state this reader does not know (${JSON.stringify(state)})`,
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
if (snapshot === null) {
|
|
149
|
+
return {
|
|
150
|
+
status: "UNMEASURED",
|
|
151
|
+
reason:
|
|
152
|
+
"the carry step read the pull request's history and the copy it left for this step " +
|
|
153
|
+
"could not be read",
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
const { round, body } = readSnapshot(snapshot);
|
|
157
|
+
if (round === null) {
|
|
158
|
+
return {
|
|
159
|
+
status: "UNMEASURED",
|
|
160
|
+
reason:
|
|
161
|
+
"the history copy does not say which round it precedes, so it cannot be shown to " +
|
|
162
|
+
"predate this round's own findings",
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
const reading = priorFindings(readLedger(body));
|
|
167
|
+
if (reading.status !== AI_REVIEW_PRIOR_MEASURED) {
|
|
168
|
+
return { status: "UNMEASURED", reason: reading.reason };
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// THE ORDERING GUARD. A snapshot taken after the persist step is the same
|
|
172
|
+
// comment fetched the same way and is byte-shaped like a correct one; the
|
|
173
|
+
// only tell is that it already holds this round. Without this, the wrong
|
|
174
|
+
// ordering suppresses the entire payload and reports CLEAN every round.
|
|
175
|
+
const stale = reading.prior.filter(p => typeof p.round === "number" && p.round >= round);
|
|
176
|
+
if (stale.length > 0) {
|
|
177
|
+
return {
|
|
178
|
+
status: "UNMEASURED",
|
|
179
|
+
reason:
|
|
180
|
+
`the history copy holds ${stale.length} finding(s) from round ${round} or later, so it ` +
|
|
181
|
+
`was taken AFTER this round was recorded rather than before it. Suppressing against it ` +
|
|
182
|
+
`would drop this round's own findings`,
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
// `unmeasuredRounds` and `unkeyableRounds` are deliberately NOT a refusal.
|
|
187
|
+
// Both mean the key set is INCOMPLETE, and an incomplete key set suppresses
|
|
188
|
+
// less than a complete one — the direction this module is allowed to be
|
|
189
|
+
// wrong in. Refusing on them would turn a partially readable history into
|
|
190
|
+
// no history at all, which is the same report with a worse sentence.
|
|
191
|
+
return { status: "MEASURED", keys: reading.keys };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* Build the gate the adjudicator is handed, or `null` when nothing is plumbed.
|
|
196
|
+
*
|
|
197
|
+
* `null` rather than a gate that answers "no repeats": a consumer that has
|
|
198
|
+
* not re-scaffolded gets exactly the reading it had before #1586, and "no
|
|
199
|
+
* repeat reader" is a state that cannot be confused with "the reader found
|
|
200
|
+
* nothing".
|
|
201
|
+
*/
|
|
202
|
+
export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSuppressionGate {
|
|
203
|
+
return (candidates: readonly unknown[]) => {
|
|
204
|
+
const prior = priorKeysFrom(inputs.carry, inputs.snapshot);
|
|
205
|
+
if (prior.status === "UNMEASURED") {
|
|
206
|
+
return { repeat: candidates.map(() => null), unmeasured: prior.reason };
|
|
207
|
+
}
|
|
208
|
+
// `suppressRepeats` is not called here, and that is deliberate: it
|
|
209
|
+
// returns partitioned LISTS, and the adjudicator's contract is
|
|
210
|
+
// positional. Re-deriving the position from a list would be a second
|
|
211
|
+
// identity derivation over findings already in order — the fault
|
|
212
|
+
// `AiReviewJuryGate`'s docblock names. `carryKey` is the shared rule and
|
|
213
|
+
// the within-round half is the growing `seen` set, exactly as
|
|
214
|
+
// `suppressRepeats` spells it.
|
|
215
|
+
const seen = new Set<string>(prior.keys);
|
|
216
|
+
const repeat = candidates.map(c => {
|
|
217
|
+
const key = carryKey(c, inputs.lineTextFor(c as ReviewFinding));
|
|
218
|
+
// Unkeyable CARRIES. It cannot be shown to be a repeat, and the
|
|
219
|
+
// direction this is allowed to be wrong in is toward reporting.
|
|
220
|
+
if (key === null) return null;
|
|
221
|
+
if (!seen.has(key)) {
|
|
222
|
+
seen.add(key);
|
|
223
|
+
return null;
|
|
224
|
+
}
|
|
225
|
+
const f = c as ReviewFinding;
|
|
226
|
+
return (
|
|
227
|
+
`${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
|
|
228
|
+
`raised on an earlier round of this pull request, so it is not raised again`
|
|
229
|
+
);
|
|
230
|
+
});
|
|
231
|
+
return { repeat, unmeasured: null };
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* THE KEY-SYMMETRY HALF. The text at a finding's cited line, read out of the
|
|
237
|
+
* checkout.
|
|
238
|
+
*
|
|
239
|
+
* `carryKey` anchors on the TEXT of the cited line and falls back to the line
|
|
240
|
+
* NUMBER when no text is supplied — so a caller that supplies nothing is not
|
|
241
|
+
* computing a weaker version of the same key, it is computing keys in a
|
|
242
|
+
* DIFFERENT NAMESPACE from the ledger's. The ledger records `recordedText`
|
|
243
|
+
* and keys `t:<text>`; a text-less caller keys `n:<line>`; the two never
|
|
244
|
+
* collide, so the dedupe silently suppresses nothing and every round looks
|
|
245
|
+
* like a round with no repeats. Measured before this landed: `kept: 1,
|
|
246
|
+
* suppressed: 0` on a planted exact repeat.
|
|
247
|
+
*
|
|
248
|
+
* A line that cannot be read yields `undefined` and the finding falls back to
|
|
249
|
+
* the number anchor — asymmetric again, for that one finding, and therefore
|
|
250
|
+
* reported rather than dropped.
|
|
251
|
+
*
|
|
252
|
+
* `root` bounds it. A payload is written by the reviewer and names its own
|
|
253
|
+
* paths, so `../../etc/passwd` is an input this must handle; `resolve`
|
|
254
|
+
* normalises the `..` away, which is why the containment test is on the
|
|
255
|
+
* RESOLVED path and not on the spelling.
|
|
256
|
+
*/
|
|
257
|
+
export function checkoutLineText(root: string): (finding: ReviewFinding) => string | undefined {
|
|
258
|
+
const base = resolve(root);
|
|
259
|
+
const cache = new Map<string, string[] | null>();
|
|
260
|
+
return (finding: ReviewFinding) => {
|
|
261
|
+
const file = finding.file;
|
|
262
|
+
const line = finding.line;
|
|
263
|
+
if (typeof file !== "string" || file === "") return undefined;
|
|
264
|
+
if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
|
|
265
|
+
if (isAbsolute(file)) return undefined;
|
|
266
|
+
const path = resolve(base, file);
|
|
267
|
+
if (path !== base && !path.startsWith(base + sep)) return undefined;
|
|
268
|
+
if (!cache.has(path)) {
|
|
269
|
+
try {
|
|
270
|
+
cache.set(path, readFileSync(path, "utf-8").split("\n"));
|
|
271
|
+
} catch {
|
|
272
|
+
cache.set(path, null);
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
const lines = cache.get(path) ?? null;
|
|
276
|
+
if (lines === null) return undefined;
|
|
277
|
+
const text = lines[line - 1];
|
|
278
|
+
return typeof text === "string" && text.trim() !== "" ? text : undefined;
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* Read a path, or `null`. Absent and unreadable collapse HERE and only here,
|
|
284
|
+
* because the caller's three-state reading comes from the carry file's
|
|
285
|
+
* contents rather than from its presence — and every `null` reaching
|
|
286
|
+
* `priorKeysFrom` produces an UNMEASURED sentence rather than an empty set.
|
|
287
|
+
*/
|
|
288
|
+
export function readOrNull(path: string | undefined): string | null {
|
|
289
|
+
if (path === undefined || path === "") return null;
|
|
290
|
+
try {
|
|
291
|
+
return readFileSync(path, "utf-8");
|
|
292
|
+
} catch {
|
|
293
|
+
return null;
|
|
294
|
+
}
|
|
295
|
+
}
|
package/lib/finding-jury.ts
CHANGED
|
@@ -223,8 +223,15 @@ export function classifyCategory(finding: Pick<Finding, "title" | "body">): Find
|
|
|
223
223
|
* nothing reachable from CI could name it. Its docblock there carries the
|
|
224
224
|
* input on which this and `AI_REVIEW_SEVERITIES` must disagree.
|
|
225
225
|
*
|
|
226
|
-
* Re-exported rather than moved outright so `severityOf
|
|
227
|
-
*
|
|
226
|
+
* Re-exported rather than moved outright so `severityOf` and the three
|
|
227
|
+
* modules that name the vocabulary keep naming it here:
|
|
228
|
+
* `lib/finding-arbiter.ts`, `lib/ai-review-jury.ts` and
|
|
229
|
+
* `lib/issue-filing-gate.ts`. Measured 2026-10-24, not copied: #1587's own
|
|
230
|
+
* brief and the spec listed `lib/failure-intake.ts` and
|
|
231
|
+
* `hooks/VerifyPhaseLock.hook.ts` among them and NEITHER imports this module,
|
|
232
|
+
* directly or transitively. `scripts/arbitrate-finding.ts` does import from
|
|
233
|
+
* here — `parseVotes`, `renderComment`, `VerifierVote` — but never names
|
|
234
|
+
* `Severity` or `SEVERITY_RANK` itself.
|
|
228
235
|
*/
|
|
229
236
|
export { SEVERITY_RANK };
|
|
230
237
|
export type { Severity };
|
|
@@ -275,6 +275,12 @@ export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
|
|
|
275
275
|
*/
|
|
276
276
|
export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
|
|
277
277
|
|
|
278
|
+
/** CRC-N4 (#1586). Repeats that were dropped, named rather than counted. */
|
|
279
|
+
export const AI_REVIEW_SUPPRESSED_TITLE = "AI review repeats not reported again";
|
|
280
|
+
|
|
281
|
+
/** CRC-N4 (#1586). The history could not be compared — not "no repeats". */
|
|
282
|
+
export const AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE = "AI review repeat check UNMEASURED";
|
|
283
|
+
|
|
278
284
|
/**
|
|
279
285
|
* A stable identity for one finding, so an answer can name it.
|
|
280
286
|
*
|
|
@@ -749,6 +755,31 @@ export interface AiReviewFindingsReading {
|
|
|
749
755
|
* already reduced.
|
|
750
756
|
*/
|
|
751
757
|
findingTags: (Severity | null)[] | null;
|
|
758
|
+
/**
|
|
759
|
+
* Findings an earlier round already raised, DROPPED from this round's
|
|
760
|
+
* report (CRC-N4, #1586) — raw, named, in payload order.
|
|
761
|
+
*
|
|
762
|
+
* Never a count. "Three repeats were dropped" and "these three were
|
|
763
|
+
* dropped" differ exactly when somebody wants to know whether the drop was
|
|
764
|
+
* right, which is the only question anybody asks of a drop.
|
|
765
|
+
*
|
|
766
|
+
* `[]` means the reader ran and found no repeat. There is no `null`
|
|
767
|
+
* case — a run with no repeat reader simply suppresses nothing, and
|
|
768
|
+
* `suppressionUnmeasured` is what says the prior state could not be read.
|
|
769
|
+
*/
|
|
770
|
+
suppressedReported: unknown[];
|
|
771
|
+
/** One line per entry in `suppressedReported`, in the same order. */
|
|
772
|
+
suppressionReasons: string[];
|
|
773
|
+
/**
|
|
774
|
+
* Why the prior state could not be established, or `null`.
|
|
775
|
+
*
|
|
776
|
+
* `null` with an empty `suppressedReported` is "the reader ran and nothing
|
|
777
|
+
* was a repeat". A sentence here is "nothing could be compared", and those
|
|
778
|
+
* are different facts — the second one means this round's report is a
|
|
779
|
+
* complete list that was never checked against the history, which is the
|
|
780
|
+
* distinction #1568 cost three rounds of #1569 to learn.
|
|
781
|
+
*/
|
|
782
|
+
suppressionUnmeasured: string | null;
|
|
752
783
|
}
|
|
753
784
|
|
|
754
785
|
/**
|
|
@@ -887,6 +918,93 @@ function tagsForPayload(
|
|
|
887
918
|
);
|
|
888
919
|
}
|
|
889
920
|
|
|
921
|
+
/**
|
|
922
|
+
* Findings that are reported on EVERY round, whatever an earlier round said.
|
|
923
|
+
*
|
|
924
|
+
* ## This is the whole of CRC-N4's safety, and it is named for what it protects
|
|
925
|
+
*
|
|
926
|
+
* The deployed reviewer prompt (`buildReviewPrompt`) tells the reviewer:
|
|
927
|
+
*
|
|
928
|
+
* > CHECK EACH CARRIED FINDING AGAINST THE CODE AND RE-REPORT THE ONES THAT
|
|
929
|
+
* > ARE STILL TRUE … A carried finding you silently leave out is a finding
|
|
930
|
+
* > that has stopped being reported, and that is how a live defect reaches a
|
|
931
|
+
* > green check.
|
|
932
|
+
*
|
|
933
|
+
* So on every round after the first, a live unresolved finding is **supposed**
|
|
934
|
+
* to be in the payload, and it is key-identical to the one the ledger
|
|
935
|
+
* recorded. Subtracting it is therefore not a de-duplication: it is the
|
|
936
|
+
* deletion of the one signal the gate has. MEASURED on the real functions
|
|
937
|
+
* before this was written — a round-1 blocking finding, re-reported on round 2
|
|
938
|
+
* exactly as instructed, run through `suppressRepeats` with the ledger's keys:
|
|
939
|
+
*
|
|
940
|
+
* ```
|
|
941
|
+
* kept: 0 suppressed: 1 severity of what survives: []
|
|
942
|
+
* ```
|
|
943
|
+
*
|
|
944
|
+
* `blocking.length === 0` → `blocked: false` → `CLEAN`, which is a green
|
|
945
|
+
* required check over a defect a previous round blocked on. That is
|
|
946
|
+
* SUCCESS.md claim 4 failing inside this repository's own merge gate.
|
|
947
|
+
*
|
|
948
|
+
* ## Unclassified is protected too, and that is the three-state reading
|
|
949
|
+
*
|
|
950
|
+
* `severityBlocks` answers `true`, `false`, or `null` for a severity the
|
|
951
|
+
* table does not declare. Only an explicit `false` — a severity this module
|
|
952
|
+
* knows and knows does not block — is ever offered for suppression. `null`
|
|
953
|
+
* is not "does not block"; it is "nobody classified this", and dropping it
|
|
954
|
+
* would let an unrecognised severity become the way round the exemption.
|
|
955
|
+
*
|
|
956
|
+
* ## Widening this is a decision about the merge gate
|
|
957
|
+
*
|
|
958
|
+
* Anything that makes this return `false` more often lets a repeat stop
|
|
959
|
+
* blocking. `test/ai-review-suppression.test.ts` mutates it to a constant
|
|
960
|
+
* `false` and asserts the verdict flips from BLOCKED to CLEAN — the count
|
|
961
|
+
* alone is not the assertion, because a count can stay right while the
|
|
962
|
+
* verdict moves, and the verdict is the thing that gates.
|
|
963
|
+
*
|
|
964
|
+
* Recorded as a declared deviation from `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`
|
|
965
|
+
* line 480, which says the adjudicator should drop any finding matching an
|
|
966
|
+
* earlier round's key. The prompt above is the newer artefact and the correct
|
|
967
|
+
* one; the deviations table carries the reasoning so a reader finds it there.
|
|
968
|
+
*/
|
|
969
|
+
export function findingMustAlwaysBeReported(finding: unknown): boolean {
|
|
970
|
+
if (finding === null || typeof finding !== "object" || Array.isArray(finding)) return true;
|
|
971
|
+
const severity = (finding as Record<string, unknown>)[AI_REVIEW_FINDING_FIELDS.severity];
|
|
972
|
+
return severityBlocks(severity) !== false;
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
/**
|
|
976
|
+
* The cross-round repeat reader, INJECTED exactly as `AiReviewJuryGate` is
|
|
977
|
+
* and for the same mechanical reason: three mutation batteries copy this
|
|
978
|
+
* module into a scratch directory carrying only `./ai-review-step`, and
|
|
979
|
+
* `lib/ai-review-suppression.ts` pulls `lib/ai-review-rounds.ts` behind it.
|
|
980
|
+
* A mutant that died on module resolution would report zero findings, which
|
|
981
|
+
* reads exactly like a guard behaving differently.
|
|
982
|
+
*
|
|
983
|
+
* **It never sees a blocking finding.** The caller filters with
|
|
984
|
+
* `findingMustAlwaysBeReported` before offering anything, so the exemption is
|
|
985
|
+
* structural rather than a rule the gate is trusted to follow.
|
|
986
|
+
*
|
|
987
|
+
* **Positional, like the ballot.** A map keyed by a finding's identity would
|
|
988
|
+
* be a SECOND derivation of that identity over a list already produced in
|
|
989
|
+
* order, and two findings sharing a key would share a verdict.
|
|
990
|
+
*/
|
|
991
|
+
export interface AiReviewSuppressionGate {
|
|
992
|
+
(candidates: readonly unknown[]): {
|
|
993
|
+
/**
|
|
994
|
+
* One entry per candidate, IN INPUT ORDER: the sentence saying an earlier
|
|
995
|
+
* round already raised it, or `null` to report it.
|
|
996
|
+
*/
|
|
997
|
+
repeat: readonly (string | null)[];
|
|
998
|
+
/**
|
|
999
|
+
* Why the prior state could not be established, or `null` when it was.
|
|
1000
|
+
* An unmeasured prior suppresses NOTHING — the direction this is allowed
|
|
1001
|
+
* to be wrong in is toward reporting a repeat twice, never toward
|
|
1002
|
+
* dropping something live.
|
|
1003
|
+
*/
|
|
1004
|
+
unmeasured: string | null;
|
|
1005
|
+
};
|
|
1006
|
+
}
|
|
1007
|
+
|
|
890
1008
|
function unmeasured(
|
|
891
1009
|
reasons: AiReviewUnmeasuredReason[],
|
|
892
1010
|
detail: string[],
|
|
@@ -897,6 +1015,14 @@ function unmeasured(
|
|
|
897
1015
|
outcome: "UNMEASURED",
|
|
898
1016
|
blocked: null,
|
|
899
1017
|
reported,
|
|
1018
|
+
// Empty rather than null, and that is not the usual three-state reading
|
|
1019
|
+
// being skipped: `suppressionUnmeasured` is the field that says the
|
|
1020
|
+
// prior state was not established, and on an UNMEASURED payload it is
|
|
1021
|
+
// `readAiReviewFindings` that fills both from what `readPayload`
|
|
1022
|
+
// appended. Nothing was dropped on any path that reaches here.
|
|
1023
|
+
suppressedReported: [],
|
|
1024
|
+
suppressionReasons: [],
|
|
1025
|
+
suppressionUnmeasured: null,
|
|
900
1026
|
blockingReported: null,
|
|
901
1027
|
verdict: null,
|
|
902
1028
|
unmeasuredReasons: reasons,
|
|
@@ -982,24 +1108,39 @@ function withScope(
|
|
|
982
1108
|
export function readAiReviewFindings(
|
|
983
1109
|
raw: string | null,
|
|
984
1110
|
scope: AiReviewScopeReading = scopeNotSupplied(),
|
|
1111
|
+
suppress: AiReviewSuppressionGate | null = null,
|
|
985
1112
|
): AiReviewFindingsReading {
|
|
986
1113
|
const preExisting: unknown[] = [];
|
|
987
1114
|
// Appended to by `readPayload`, for the same reason `preExisting` is: the
|
|
988
1115
|
// entries belong to the reading its caller composes, and every early return
|
|
989
1116
|
// in there is a state in which the split had not happened yet.
|
|
990
1117
|
const dropped: string[] = [];
|
|
1118
|
+
// #1586, by the same arrangement and for the same reason.
|
|
1119
|
+
const suppressed: unknown[] = [];
|
|
1120
|
+
const suppression: { reasons: string[]; unmeasured: string | null } = {
|
|
1121
|
+
reasons: [],
|
|
1122
|
+
unmeasured: null,
|
|
1123
|
+
};
|
|
991
1124
|
const base = readPayload(
|
|
992
1125
|
raw,
|
|
993
1126
|
scope.status === "MEASURED" ? scope.files : undefined,
|
|
994
1127
|
preExisting,
|
|
995
1128
|
dropped,
|
|
1129
|
+
suppress,
|
|
1130
|
+
suppressed,
|
|
1131
|
+
suppression,
|
|
996
1132
|
);
|
|
997
|
-
return
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1133
|
+
return {
|
|
1134
|
+
...withScope(
|
|
1135
|
+
base,
|
|
1136
|
+
scope,
|
|
1137
|
+
scope.status === "MEASURED" ? preExisting : null,
|
|
1138
|
+
scope.status === "MEASURED" ? dropped : null,
|
|
1139
|
+
),
|
|
1140
|
+
suppressedReported: suppressed,
|
|
1141
|
+
suppressionReasons: suppression.reasons,
|
|
1142
|
+
suppressionUnmeasured: suppression.unmeasured,
|
|
1143
|
+
};
|
|
1003
1144
|
}
|
|
1004
1145
|
|
|
1005
1146
|
/**
|
|
@@ -1017,6 +1158,9 @@ function readPayload(
|
|
|
1017
1158
|
changedFiles: readonly string[] | undefined,
|
|
1018
1159
|
preExisting: unknown[],
|
|
1019
1160
|
dropped: string[],
|
|
1161
|
+
suppress: AiReviewSuppressionGate | null,
|
|
1162
|
+
suppressedOut: unknown[],
|
|
1163
|
+
suppressionOut: { reasons: string[]; unmeasured: string | null },
|
|
1020
1164
|
): AiReviewFindingsReading {
|
|
1021
1165
|
if (raw === null) {
|
|
1022
1166
|
return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
|
|
@@ -1109,7 +1253,65 @@ function readPayload(
|
|
|
1109
1253
|
/** How many findings CRC-B7 demoted. See the `agreed` computation below. */
|
|
1110
1254
|
let demoted = 0;
|
|
1111
1255
|
|
|
1256
|
+
// ── CRC-N4, and the ONE site a repeat is dropped (#1586) ───────────────
|
|
1257
|
+
//
|
|
1258
|
+
// BEFORE the classification below, so a suppressed finding is absent from
|
|
1259
|
+
// `reported`, from the annotation and from the ledger alike — "dropped
|
|
1260
|
+
// everywhere or nowhere". A finding filtered out of one projection and
|
|
1261
|
+
// left in another is two answers to one question.
|
|
1262
|
+
//
|
|
1263
|
+
// Only findings `findingMustAlwaysBeReported` declines to protect are ever
|
|
1264
|
+
// OFFERED. The exemption is therefore structural: there is no argument the
|
|
1265
|
+
// gate can return that drops a blocking finding, because a blocking
|
|
1266
|
+
// finding is never in the list it is handed. See that predicate for the
|
|
1267
|
+
// measurement that made this the design.
|
|
1268
|
+
const offered: unknown[] = [];
|
|
1269
|
+
const offeredAt: number[] = [];
|
|
1112
1270
|
list.forEach((item, i) => {
|
|
1271
|
+
if (!findingMustAlwaysBeReported(item)) {
|
|
1272
|
+
offered.push(item);
|
|
1273
|
+
offeredAt.push(i);
|
|
1274
|
+
}
|
|
1275
|
+
});
|
|
1276
|
+
/** Per-index reason, or null to report. Positional, never keyed. */
|
|
1277
|
+
const repeatOf: (string | null)[] = list.map(() => null);
|
|
1278
|
+
let suppressionUnmeasured: string | null = null;
|
|
1279
|
+
if (suppress !== null && offered.length > 0) {
|
|
1280
|
+
try {
|
|
1281
|
+
const verdict = suppress(offered);
|
|
1282
|
+
suppressionUnmeasured = verdict.unmeasured;
|
|
1283
|
+
// A gate that answered about a different number of findings than it
|
|
1284
|
+
// was handed has lost the positional join, and a misaligned verdict
|
|
1285
|
+
// suppresses the wrong finding. Refuse the whole reading rather than
|
|
1286
|
+
// apply part of it.
|
|
1287
|
+
if (verdict.repeat.length !== offered.length) {
|
|
1288
|
+
suppressionUnmeasured =
|
|
1289
|
+
`the repeat reader answered about ${verdict.repeat.length} finding(s) and was handed ` +
|
|
1290
|
+
`${offered.length}, so no answer could be matched to a finding and nothing was ` +
|
|
1291
|
+
`suppressed. Every finding this round raised is reported.`;
|
|
1292
|
+
} else {
|
|
1293
|
+
verdict.repeat.forEach((why, k) => {
|
|
1294
|
+
if (typeof why === "string") repeatOf[offeredAt[k]!] = why;
|
|
1295
|
+
});
|
|
1296
|
+
}
|
|
1297
|
+
} catch (e) {
|
|
1298
|
+
// FAIL TOWARD REPORTING. A reader that threw has established nothing,
|
|
1299
|
+
// and the cost of being wrong here is one advisory printed twice —
|
|
1300
|
+
// against a live finding dropped, which is silent and permanent.
|
|
1301
|
+
suppressionUnmeasured =
|
|
1302
|
+
`the repeat reader threw and nothing was suppressed: ${(e as Error).message}. Every ` +
|
|
1303
|
+
`finding this round raised is reported, including any an earlier round already raised.`;
|
|
1304
|
+
}
|
|
1305
|
+
}
|
|
1306
|
+
// Appended rather than returned, for `preExisting`'s reason: these belong
|
|
1307
|
+
// to the reading the caller composes, and every early return above is a
|
|
1308
|
+
// state in which no suppression had happened yet.
|
|
1309
|
+
suppressedOut.push(...list.filter((_, i) => repeatOf[i] !== null));
|
|
1310
|
+
suppressionOut.reasons.push(...repeatOf.filter((r): r is string => r !== null));
|
|
1311
|
+
suppressionOut.unmeasured = suppressionUnmeasured;
|
|
1312
|
+
const kept = list.filter((_, i) => repeatOf[i] === null);
|
|
1313
|
+
|
|
1314
|
+
kept.forEach((item, i) => {
|
|
1113
1315
|
if (item === null || typeof item !== "object" || Array.isArray(item)) {
|
|
1114
1316
|
reasons.push("FINDING_NOT_AN_OBJECT");
|
|
1115
1317
|
detail.push(`finding ${i} is not an object`);
|
|
@@ -1247,9 +1449,14 @@ function readPayload(
|
|
|
1247
1449
|
}
|
|
1248
1450
|
}
|
|
1249
1451
|
|
|
1250
|
-
|
|
1452
|
+
// Over `kept`, not over `list` (#1586). `findingTags` is parallel to
|
|
1453
|
+
// `reported` by index, and `reported` is now the payload MINUS the repeats
|
|
1454
|
+
// this round suppressed — tagging the unfiltered list would shift every tag
|
|
1455
|
+
// by the number of findings dropped before it, so a `Nit` would be printed
|
|
1456
|
+
// against an `Important`. The two have to be derived from one array.
|
|
1457
|
+
const tags = tagsForPayload(kept, touched);
|
|
1251
1458
|
|
|
1252
|
-
if (reasons.length > 0) return unmeasured(reasons, detail,
|
|
1459
|
+
if (reasons.length > 0) return unmeasured(reasons, detail, kept, tags);
|
|
1253
1460
|
|
|
1254
1461
|
// The decision, and the only place it is made. `verdict` is compared to it
|
|
1255
1462
|
// afterwards; it never contributes to it.
|
|
@@ -1272,11 +1479,17 @@ function readPayload(
|
|
|
1272
1479
|
return {
|
|
1273
1480
|
outcome,
|
|
1274
1481
|
blocked,
|
|
1275
|
-
reported:
|
|
1482
|
+
reported: kept,
|
|
1276
1483
|
blockingReported: blocking,
|
|
1277
1484
|
verdict,
|
|
1278
1485
|
unmeasuredReasons: [],
|
|
1279
1486
|
detail,
|
|
1487
|
+
// `readAiReviewFindings` owns these three, the way `withScope` owns the
|
|
1488
|
+
// two below: `readPayload` appended them to the arrays it was handed,
|
|
1489
|
+
// and a value here would be a second statement about the same input.
|
|
1490
|
+
suppressedReported: [],
|
|
1491
|
+
suppressionReasons: [],
|
|
1492
|
+
suppressionUnmeasured: null,
|
|
1280
1493
|
// Both of these are `withScope`'s to set, and it is the only site that
|
|
1281
1494
|
// sets either. A value here would be a second statement about the same
|
|
1282
1495
|
// input, and the two could disagree.
|
|
@@ -1426,6 +1639,7 @@ export function partitionChangedFiles(
|
|
|
1426
1639
|
export function readAiReviewFindingsFile(
|
|
1427
1640
|
path: string,
|
|
1428
1641
|
scope: AiReviewScopeReading = scopeNotSupplied(),
|
|
1642
|
+
suppress: AiReviewSuppressionGate | null = null,
|
|
1429
1643
|
): AiReviewFindingsReading {
|
|
1430
1644
|
let raw: string;
|
|
1431
1645
|
try {
|
|
@@ -1450,7 +1664,7 @@ export function readAiReviewFindingsFile(
|
|
|
1450
1664
|
null,
|
|
1451
1665
|
);
|
|
1452
1666
|
}
|
|
1453
|
-
return readAiReviewFindings(raw, scope);
|
|
1667
|
+
return readAiReviewFindings(raw, scope, suppress);
|
|
1454
1668
|
}
|
|
1455
1669
|
|
|
1456
1670
|
/** The sentence a refusal prints, or `null` when there is nothing to refuse. */
|
|
@@ -1687,7 +1901,7 @@ export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
|
|
|
1687
1901
|
* outcome line and the scope line, because the generated step reads the
|
|
1688
1902
|
* outcome line before it reads the exit code.
|
|
1689
1903
|
*/
|
|
1690
|
-
function readArgv(argv: string[]): AiReviewFindingsReading {
|
|
1904
|
+
function readArgv(argv: string[], suppress: AiReviewSuppressionGate | null): AiReviewFindingsReading {
|
|
1691
1905
|
const extra = argumentsBeyondTheContract(argv);
|
|
1692
1906
|
if (extra.length > 0) {
|
|
1693
1907
|
// Scope is NOT read here. The argv is already known to be a shape this
|
|
@@ -1720,7 +1934,7 @@ function readArgv(argv: string[]): AiReviewFindingsReading {
|
|
|
1720
1934
|
null,
|
|
1721
1935
|
null,
|
|
1722
1936
|
)
|
|
1723
|
-
: readAiReviewFindingsFile(path, scope);
|
|
1937
|
+
: readAiReviewFindingsFile(path, scope, suppress);
|
|
1724
1938
|
}
|
|
1725
1939
|
|
|
1726
1940
|
/**
|
|
@@ -1730,8 +1944,12 @@ function readArgv(argv: string[]): AiReviewFindingsReading {
|
|
|
1730
1944
|
* Returns the exit code rather than calling `process.exit`, so a test can run
|
|
1731
1945
|
* it in-process as well as spawn it.
|
|
1732
1946
|
*/
|
|
1733
|
-
export function main(
|
|
1734
|
-
|
|
1947
|
+
export function main(
|
|
1948
|
+
argv: string[],
|
|
1949
|
+
jury: AiReviewJuryGate | null = null,
|
|
1950
|
+
suppress: AiReviewSuppressionGate | null = null,
|
|
1951
|
+
): number {
|
|
1952
|
+
const reading = readArgv(argv, suppress);
|
|
1735
1953
|
|
|
1736
1954
|
// CRC-B4, AFTER the reading and feeding nothing back into it.
|
|
1737
1955
|
//
|
|
@@ -1845,6 +2063,42 @@ export function main(argv: string[], jury: AiReviewJuryGate | null = null): numb
|
|
|
1845
2063
|
console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
|
|
1846
2064
|
}
|
|
1847
2065
|
|
|
2066
|
+
// CRC-N4's reading, on its own title (#1586). A `::notice`, because a
|
|
2067
|
+
// repeat that was dropped is the mechanism working and nothing about it
|
|
2068
|
+
// is a problem with the pull request.
|
|
2069
|
+
//
|
|
2070
|
+
// It NAMES them. A count cannot be argued with and cannot be audited: the
|
|
2071
|
+
// only question anybody asks of a suppression is whether it was right,
|
|
2072
|
+
// and that question needs the finding. These are advisory by construction
|
|
2073
|
+
// — `findingMustAlwaysBeReported` never offers a blocking finding — so
|
|
2074
|
+
// this annotation is the entire record that they existed.
|
|
2075
|
+
if (reading.suppressedReported.length > 0) {
|
|
2076
|
+
console.log(
|
|
2077
|
+
`::notice title=${AI_REVIEW_SUPPRESSED_TITLE}::${escapeAnnotation(
|
|
2078
|
+
`${reading.suppressedReported.length} advisory finding(s) were raised on an earlier ` +
|
|
2079
|
+
`round of this pull request and are not reported again: ` +
|
|
2080
|
+
`${reading.suppressionReasons.join("; ")}. A BLOCKING finding is never suppressed, ` +
|
|
2081
|
+
`on any round, at any key — it is re-reported and it blocks exactly as it did the ` +
|
|
2082
|
+
`first time.`,
|
|
2083
|
+
)}`,
|
|
2084
|
+
);
|
|
2085
|
+
}
|
|
2086
|
+
|
|
2087
|
+
// A `::warning`, and the state is NAMED, for `AI_REVIEW_JURY_UNMEASURED`'s
|
|
2088
|
+
// reason. An unreadable history that printed nothing would make "no
|
|
2089
|
+
// repeats were found" and "the history could not be compared" the same
|
|
2090
|
+
// observation, which is #1568 arriving one subsystem over.
|
|
2091
|
+
if (reading.suppressionUnmeasured !== null) {
|
|
2092
|
+
console.log(
|
|
2093
|
+
`::warning title=${AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE}::${escapeAnnotation(
|
|
2094
|
+
`What earlier rounds of this pull request raised could not be established: ` +
|
|
2095
|
+
`${reading.suppressionUnmeasured}. Nothing was suppressed, so this round's report ` +
|
|
2096
|
+
`is complete and was simply never compared against the history. No finding's ` +
|
|
2097
|
+
`status changed either way.`,
|
|
2098
|
+
)}`,
|
|
2099
|
+
);
|
|
2100
|
+
}
|
|
2101
|
+
|
|
1848
2102
|
// The quorum's own reading, on its own title, and emitted whatever the
|
|
1849
2103
|
// outcome was. The ledger row is the durable record and it lives on the
|
|
1850
2104
|
// runner, which dies with the job; this annotation is the only part of
|
|
@@ -1752,6 +1752,75 @@ export const AI_REVIEW_CARRY_PATH_VAR = "AI_REVIEW_CARRY_PATH";
|
|
|
1752
1752
|
/** The basename inside the findings directory. One spelling. */
|
|
1753
1753
|
export const AI_REVIEW_CARRY_BASENAME = "ai-review-carried.txt";
|
|
1754
1754
|
|
|
1755
|
+
/**
|
|
1756
|
+
* Where the carry step leaves the ledger comment's BODY, verbatim, for the
|
|
1757
|
+
* adjudicator to re-read in TypeScript (CRC-N4, #1586).
|
|
1758
|
+
*
|
|
1759
|
+
* ## Why a snapshot and not a fetch at adjudication time
|
|
1760
|
+
*
|
|
1761
|
+
* The step order is `AI_REVIEW_CARRY_STEP_ID` → the reviewer →
|
|
1762
|
+
* `AI_REVIEW_PERSIST_STEP_ID`, which upserts THIS round into the ledger
|
|
1763
|
+
* comment → `AI_REVIEW_RUN_STEP_ID`, which adjudicates. An adjudicator
|
|
1764
|
+
* that fetched the ledger itself would read a comment that already contains
|
|
1765
|
+
* the payload it is deciding about, so every finding would match a "prior"
|
|
1766
|
+
* key that is its own, and the suppression would empty the payload on every
|
|
1767
|
+
* round while looking like it worked. The prior state has to be the one that
|
|
1768
|
+
* existed BEFORE the reviewer ran, and the carry step is the only position
|
|
1769
|
+
* that holds it.
|
|
1770
|
+
*
|
|
1771
|
+
* ## Why the raw body rather than the keys
|
|
1772
|
+
*
|
|
1773
|
+
* `carryKey` is not restated in jq. The carry script reaches the body and
|
|
1774
|
+
* stops; `readLedger → priorFindings` forms every key in TypeScript, so
|
|
1775
|
+
* there is ONE decider for what a finding's identity is. A second
|
|
1776
|
+
* implementation in jq would be the #1568 shape again — two readers of the
|
|
1777
|
+
* same bytes, disagreeing on a case neither author thought to name.
|
|
1778
|
+
*
|
|
1779
|
+
* ## Written on the READ path only, and that is not a conflation
|
|
1780
|
+
*
|
|
1781
|
+
* An absent snapshot does not mean "no prior findings": the state is read
|
|
1782
|
+
* from `AI_REVIEW_CARRY_BASENAME`, which is written on EVERY path and is
|
|
1783
|
+
* the single site that decides it. UNMEASURED and ABSENT both reach the
|
|
1784
|
+
* adjudicator as "suppress nothing", but only one of them says the record
|
|
1785
|
+
* could not be read, and the adjudicator reports which.
|
|
1786
|
+
*/
|
|
1787
|
+
export const AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR = "AI_REVIEW_LEDGER_SNAPSHOT_PATH";
|
|
1788
|
+
|
|
1789
|
+
/** The basename inside the findings directory. One spelling. */
|
|
1790
|
+
export const AI_REVIEW_LEDGER_SNAPSHOT_BASENAME = "ai-review-ledger-snapshot.txt";
|
|
1791
|
+
|
|
1792
|
+
/**
|
|
1793
|
+
* The round the snapshot was taken BEFORE, handed to the carry step so the
|
|
1794
|
+
* snapshot can carry its own provenance (#1586).
|
|
1795
|
+
*
|
|
1796
|
+
* ## What this exists to make falsifiable
|
|
1797
|
+
*
|
|
1798
|
+
* A snapshot taken at `AI_REVIEW_PERSIST_STEP_ID` instead of at the carry
|
|
1799
|
+
* step is byte-shaped exactly like a correct one — it is the same comment,
|
|
1800
|
+
* fetched the same way, by the same selector. The only thing that
|
|
1801
|
+
* distinguishes them is that the later one already contains THIS round, so
|
|
1802
|
+
* every finding in the payload matches a "prior" key that is its own and the
|
|
1803
|
+
* adjudicator suppresses the entire round. That failure reports as a clean
|
|
1804
|
+
* review on every round forever, which is the reading that looks most like
|
|
1805
|
+
* success.
|
|
1806
|
+
*
|
|
1807
|
+
* So the snapshot states the round it precedes, and the reader refuses a
|
|
1808
|
+
* snapshot containing a round at or past it. The refusal is UNMEASURED and
|
|
1809
|
+
* suppresses nothing, so the wrong-ordering mutant fails toward reporting.
|
|
1810
|
+
*/
|
|
1811
|
+
export const AI_REVIEW_SNAPSHOT_ROUND_VAR = "AI_REVIEW_SNAPSHOT_ROUND";
|
|
1812
|
+
|
|
1813
|
+
/**
|
|
1814
|
+
* The snapshot's first line: `taken_before_round=<N>`. Everything after the
|
|
1815
|
+
* first newline is the ledger comment's body, verbatim and unescaped.
|
|
1816
|
+
*
|
|
1817
|
+
* A single header line rather than a JSON envelope, because the body is
|
|
1818
|
+
* arbitrary text that must survive byte-for-byte: `readLedger` is the one
|
|
1819
|
+
* decider for what it means, and re-encoding it here would be a second
|
|
1820
|
+
* format for that reader to disagree with.
|
|
1821
|
+
*/
|
|
1822
|
+
export const AI_REVIEW_SNAPSHOT_ROUND_KEY = "taken_before_round";
|
|
1823
|
+
|
|
1755
1824
|
/** The annotation title every carry warning is filed under. */
|
|
1756
1825
|
export const AI_REVIEW_CARRY_TITLE = "AI review carry-forward";
|
|
1757
1826
|
|
|
@@ -4696,6 +4765,37 @@ if ! carried_count=\$(printf '%s' "\${carried}" | jq 'length'); then
|
|
|
4696
4765
|
fi
|
|
4697
4766
|
|
|
4698
4767
|
carry_state '${AI_REVIEW_CARRY_READ}'
|
|
4768
|
+
|
|
4769
|
+
# The ledger's own bytes, for the adjudicator to key in TypeScript (#1586).
|
|
4770
|
+
#
|
|
4771
|
+
# HERE and not at adjudication time: the persist step upserts THIS round into
|
|
4772
|
+
# that same comment before the adjudicator runs, so a later fetch would read
|
|
4773
|
+
# the payload it is deciding about as its own prior and suppress all of it.
|
|
4774
|
+
#
|
|
4775
|
+
# ON THE READ PATH ONLY, and after the parse above succeeded. The state the
|
|
4776
|
+
# adjudicator gates on lives in the carry file, which \`carry_state\` writes on
|
|
4777
|
+
# every path — so an absent snapshot is never read as "no earlier findings",
|
|
4778
|
+
# it is read as whichever of the three states that one site recorded.
|
|
4779
|
+
#
|
|
4780
|
+
# A failed write is a WARNING and not a refusal: the carry itself succeeded
|
|
4781
|
+
# and the reviewer's copy is already on disk. The adjudicator seeing no
|
|
4782
|
+
# snapshot suppresses nothing, which is the direction this is allowed to be
|
|
4783
|
+
# wrong in — a repeat gets posted twice, rather than a live finding dropped.
|
|
4784
|
+
if [ -n "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}:-}" ]; then
|
|
4785
|
+
# The provenance line FIRST, then the body verbatim. The reader refuses a
|
|
4786
|
+
# snapshot holding a round at or past this number, which is the only thing
|
|
4787
|
+
# that tells a snapshot taken here from one taken after the persist step —
|
|
4788
|
+
# they are otherwise the same comment fetched by the same selector, and the
|
|
4789
|
+
# later one suppresses the whole round it is deciding about.
|
|
4790
|
+
if ! {
|
|
4791
|
+
printf '%s=%s\\n' '${AI_REVIEW_SNAPSHOT_ROUND_KEY}' "\${${AI_REVIEW_SNAPSHOT_ROUND_VAR}:-}"
|
|
4792
|
+
printf '%s' "\${selected}" | jq -r '.body // ""'
|
|
4793
|
+
} > "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"; then
|
|
4794
|
+
rm -f "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"
|
|
4795
|
+
carry_note "the ledger's own text could not be written for the adjudicator, so repeats will not be suppressed on this round. Every finding this round raises is reported, including any an earlier round already raised."
|
|
4796
|
+
fi
|
|
4797
|
+
fi
|
|
4798
|
+
|
|
4699
4799
|
{
|
|
4700
4800
|
printf 'carried_count=%s\\n' "\${carried_count}"
|
|
4701
4801
|
printf 'unmeasured_rounds=%s\\n' "\${unmeasured_rounds}"
|
|
@@ -10152,6 +10252,15 @@ export function buildReviewRunStep(
|
|
|
10152
10252
|
// Composed from the prepare step's output rather than spelled again, so
|
|
10153
10253
|
// there is one declaration of where that directory is.
|
|
10154
10254
|
` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
|
|
10255
|
+
// #1586. The same directory and the same composition rule. This step is
|
|
10256
|
+
// the WRITER of the snapshot; the adjudicator step below names the same
|
|
10257
|
+
// path from the same prepare-step output, so the two agree by
|
|
10258
|
+
// construction rather than through an output this step might not reach.
|
|
10259
|
+
` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
|
|
10260
|
+
// The round this snapshot precedes, so it carries its own provenance.
|
|
10261
|
+
// Unset is not fatal: the reader refuses an unreadable provenance the
|
|
10262
|
+
// same way it refuses a stale one, by suppressing nothing.
|
|
10263
|
+
` ${AI_REVIEW_SNAPSHOT_ROUND_VAR}: \${{ steps.${AI_REVIEW_ROUNDS_STEP_ID}.outputs.${AI_REVIEW_ROUND_OUTPUT} }}`,
|
|
10155
10264
|
` run: |`,
|
|
10156
10265
|
...buildCarryScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
|
|
10157
10266
|
];
|
|
@@ -10300,6 +10409,18 @@ export function buildReviewRunStep(
|
|
|
10300
10409
|
// when the writer did not reach it, the file is simply absent, which is
|
|
10301
10410
|
// `CHANGED_FILES_UNREADABLE` and not a green check.
|
|
10302
10411
|
` ${AI_REVIEW_CHANGED_FILES_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CHANGED_FILES_BASENAME}`,
|
|
10412
|
+
// #1586, and restated here for #826's reason like the line above: a
|
|
10413
|
+
// step's `env:` does not carry to a later step. The carry step WROTE the
|
|
10414
|
+
// snapshot; these are the adjudicator's own copies, composed from the
|
|
10415
|
+
// same prepare output so the reader cannot be pointed at a path the
|
|
10416
|
+
// writer did not use.
|
|
10417
|
+
//
|
|
10418
|
+
// BOTH paths, and that is the point. The snapshot alone cannot say why
|
|
10419
|
+
// it is absent, and an absent snapshot read as "no earlier findings" is
|
|
10420
|
+
// the #1568 conflation arriving in the half that decides a required
|
|
10421
|
+
// check. The carry file carries the state; this one carries the bytes.
|
|
10422
|
+
` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
|
|
10423
|
+
` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
|
|
10303
10424
|
` ${AI_REVIEW_EXECUTION_FILE_VAR}: \${{ steps.${AI_REVIEW_ACTION_STEP_ID}.outputs.execution_file }}`,
|
|
10304
10425
|
// CRC-B1. The PATH, so the read-check can look for that exact string in
|
|
10305
10426
|
// the transcript. #826 is why this is restated rather than inherited: a
|
package/package.json
CHANGED
|
@@ -66,10 +66,42 @@
|
|
|
66
66
|
* here rather than refused, because the reader never learns a path it has
|
|
67
67
|
* no gate for. `test/ai-review-findings-command.test.ts` holds this file
|
|
68
68
|
* to supplying the gate when the variable is set.
|
|
69
|
+
*
|
|
70
|
+
* ## The second thing it supplies (CRC-N4, #1586)
|
|
71
|
+
*
|
|
72
|
+
* `aiReviewSuppressionGate` — the "no repeats" subtraction. Same reasoning
|
|
73
|
+
* as the jury, twice over: `lib/ai-review-suppression.ts` pulls
|
|
74
|
+
* `lib/ai-review-rounds.ts` behind it, which the batteries do not copy, and
|
|
75
|
+
* it reads the CHECKOUT, which a reader running from a scratch directory
|
|
76
|
+
* does not have.
|
|
77
|
+
*
|
|
78
|
+
* It takes TWO paths, and that is the part worth not collapsing. The carry
|
|
79
|
+
* file holds the carry step's own three-state reading and is written on
|
|
80
|
+
* every path; the snapshot holds the ledger's bytes and exists only on the
|
|
81
|
+
* READ path. An absent snapshot is therefore not "no prior findings" — the
|
|
82
|
+
* carry file says which. Unset either and the gate is `null`: a consumer on
|
|
83
|
+
* an older scaffold gets the pre-#1586 reading, not a silent "nothing was a
|
|
84
|
+
* repeat".
|
|
85
|
+
*
|
|
86
|
+
* **A blocking finding never reaches this gate.**
|
|
87
|
+
* `findingMustAlwaysBeReported` filters first, inside the reader, so no
|
|
88
|
+
* answer the gate could give can drop one. That is a structural exemption
|
|
89
|
+
* rather than a rule the gate is trusted with, and it is a declared
|
|
90
|
+
* deviation from CRC-N4 as written — see the deviations table in
|
|
91
|
+
* `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`.
|
|
69
92
|
*/
|
|
70
93
|
import { aiReviewJuryGate } from "../lib/ai-review-jury";
|
|
94
|
+
import {
|
|
95
|
+
aiReviewSuppressionGate,
|
|
96
|
+
checkoutLineText,
|
|
97
|
+
readOrNull,
|
|
98
|
+
} from "../lib/ai-review-suppression";
|
|
71
99
|
import { main } from "../lib/scaffold/ai-review-findings";
|
|
72
|
-
import {
|
|
100
|
+
import {
|
|
101
|
+
AI_REVIEW_BALLOT_DIR_ENV,
|
|
102
|
+
AI_REVIEW_CARRY_PATH_VAR,
|
|
103
|
+
AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR,
|
|
104
|
+
} from "../lib/scaffold/ai-review-step";
|
|
73
105
|
|
|
74
106
|
const ballotDir = process.env[AI_REVIEW_BALLOT_DIR_ENV];
|
|
75
107
|
const jury =
|
|
@@ -77,9 +109,20 @@ const jury =
|
|
|
77
109
|
? null
|
|
78
110
|
: (blocking: readonly unknown[]) => aiReviewJuryGate(blocking, ballotDir);
|
|
79
111
|
|
|
112
|
+
const carryPath = process.env[AI_REVIEW_CARRY_PATH_VAR];
|
|
113
|
+
const snapshotPath = process.env[AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR];
|
|
114
|
+
const suppress =
|
|
115
|
+
carryPath === undefined || carryPath === ""
|
|
116
|
+
? null
|
|
117
|
+
: aiReviewSuppressionGate({
|
|
118
|
+
carry: readOrNull(carryPath),
|
|
119
|
+
snapshot: readOrNull(snapshotPath),
|
|
120
|
+
lineTextFor: checkoutLineText(process.cwd()),
|
|
121
|
+
});
|
|
122
|
+
|
|
80
123
|
// One line, and `process.exit(main(` is load-bearing text: AC-4 in
|
|
81
124
|
// `test/ai-review-findings-command.test.ts` reads it to prove this file
|
|
82
125
|
// declares no exit code of its own. Wrapping the call across lines makes
|
|
83
126
|
// that case red for a formatting reason, which is worth knowing before
|
|
84
127
|
// reformatting it.
|
|
85
|
-
process.exit(main(process.argv.slice(2), jury));
|
|
128
|
+
process.exit(main(process.argv.slice(2), jury, suppress));
|