rungate 0.8.1 → 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/BashWriteGuard.hook.ts +19 -0
- 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 +68 -11
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +1249 -0
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-file-read.ts +17 -3
- package/lib/bash-write-guard.ts +2165 -51
- 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/distribution-standing.ts +75 -4
- package/lib/failure-intake.ts +12 -4
- package/lib/file-claims.ts +335 -0
- package/lib/file-extensions.ts +81 -0
- package/lib/finding-arbiter.ts +1489 -0
- package/lib/finding-jury.ts +584 -0
- 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 +160 -0
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/interpreters.ts +64 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +122 -11
- package/lib/issue-filing-gate.ts +1602 -0
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/publish-window.ts +287 -0
- 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 +4672 -85
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/managed-workflow.ts +163 -4
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +462 -108
- package/lib/scanner.ts +10 -3
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/ticked-sc-symbols.ts +361 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/lib/workflow-actions.ts +18 -0
- package/package.json +3 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +542 -0
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/generate-code-map.ts +6 -3
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +93 -8
|
@@ -0,0 +1,1249 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bounding review rounds on an open pull request (#1168).
|
|
3
|
+
*
|
|
4
|
+
* `lib/security-verdict.ts` already decides all of this for rook inside a
|
|
5
|
+
* ship run: `reReviewDecision` caps rounds and fails closed on an unreadable
|
|
6
|
+
* budget, `reReviewScope` works out that a stale FAIL and a stale PASS need
|
|
7
|
+
* different re-review scopes, and `reviewIsCurrent` clears a finding when a
|
|
8
|
+
* later commit replaced the code it was about. None of it is reachable from
|
|
9
|
+
* CI, because it governs a ship run and the swarm bypasses ship.js.
|
|
10
|
+
*
|
|
11
|
+
* **This module does not reimplement any of it.** Every decision below
|
|
12
|
+
* delegates to that file. What is added here is the part that file has no
|
|
13
|
+
* opinion about: where a round NUMBER comes from on a pull request, and what
|
|
14
|
+
* the reviewer should be told once the budget is spent.
|
|
15
|
+
*
|
|
16
|
+
* ## The measurement this was built from
|
|
17
|
+
*
|
|
18
|
+
* Anthropic report that `git blame` over what their reviewer kept flagging on
|
|
19
|
+
* later rounds showed ~59% of it was code already present at the first pass —
|
|
20
|
+
* the reviewer was finding a few more OLD bugs each round, not new ones.
|
|
21
|
+
*
|
|
22
|
+
* Measured here on 2026-10-22 over all 524 `AI Review` runs this repository
|
|
23
|
+
* has ever had: the findings adjudicator has only existed since #1013, so the
|
|
24
|
+
* whole population of blocking findings is 8, across 6 branches, and exactly
|
|
25
|
+
* **2** of them are round-2-or-later. Both cite a line that was present at
|
|
26
|
+
* round 1:
|
|
27
|
+
*
|
|
28
|
+
* * `rg/1175`, round 2 flagged `lib/bash-write-guard.ts:375`
|
|
29
|
+
* (`LINK_CREATION`). The byte-identical line was at `:318` at round 1.
|
|
30
|
+
* * `fix/1129`, round 2 flagged `lib/launch-base.ts:184`
|
|
31
|
+
* (`canonical === given`). `git diff` between the two reviewed commits
|
|
32
|
+
* reports the file UNCHANGED.
|
|
33
|
+
*
|
|
34
|
+
* 2 of 2 is 100% on a denominator of 2. It is consistent with their 59% and
|
|
35
|
+
* it is not a replication of it, and this module does not claim one.
|
|
36
|
+
*
|
|
37
|
+
* ## What that measurement changed in the design
|
|
38
|
+
*
|
|
39
|
+
* **A finding fingerprint may not be keyed on a line number.** The first case
|
|
40
|
+
* above moved 318 → 375 between rounds while staying byte-identical, so a
|
|
41
|
+
* `file:line` key would have failed to suppress the one repeat we can
|
|
42
|
+
* actually observe. `carryKey` therefore keys on the file, the normalised
|
|
43
|
+
* TEXT of the cited line, and the normalised summary.
|
|
44
|
+
*
|
|
45
|
+
* **`git blame` is the wrong instrument for this question.** It attributed
|
|
46
|
+
* the first case to a commit that is not an ancestor of the round-1 head (the
|
|
47
|
+
* branch was rebased between rounds) and the second to the round-2 commit
|
|
48
|
+
* itself (the round-2 commit is an amend of the round-1 one). Blame would
|
|
49
|
+
* have scored BOTH of our stale findings as fresh. Content presence is the
|
|
50
|
+
* reading; authorship is not.
|
|
51
|
+
*
|
|
52
|
+
* ## Why diff-scoping a later round is not safe on its own
|
|
53
|
+
*
|
|
54
|
+
* Anthropic ship diff-only re-review after the first few passes. Applied
|
|
55
|
+
* directly here that is `46034035` — the `fail-open-security-gate` this
|
|
56
|
+
* repository found and reverted — because a diff against the flagged commit
|
|
57
|
+
* does not contain the flagged code, so a later round that reads only the
|
|
58
|
+
* diff says nothing about a finding raised earlier. Theirs is safe because
|
|
59
|
+
* their findings are inline comments that PERSIST on the pull request and
|
|
60
|
+
* block merge until they are answered; ours is a check-run annotation that
|
|
61
|
+
* the next run replaces wholesale, so a finding not re-raised simply
|
|
62
|
+
* disappears and the check goes green.
|
|
63
|
+
*
|
|
64
|
+
* So `reviewScopeForRound` delegates to `reReviewScope`, which refuses to
|
|
65
|
+
* diff-scope anything but a held PASS, and `carryForward` is what makes a
|
|
66
|
+
* diff-scoped round honest: the unresolved earlier findings are re-emitted by
|
|
67
|
+
* the ADJUDICATOR rather than re-discovered by the reviewer.
|
|
68
|
+
*/
|
|
69
|
+
|
|
70
|
+
import {
|
|
71
|
+
RE_REVIEW,
|
|
72
|
+
REVIEW_CURRENT,
|
|
73
|
+
REVIEW_SCOPE_DIFF,
|
|
74
|
+
REVIEW_SCOPE_FULL,
|
|
75
|
+
SECURITY_REREVIEW_EXHAUSTED,
|
|
76
|
+
reReviewDecision,
|
|
77
|
+
reReviewScope,
|
|
78
|
+
type ReviewScope,
|
|
79
|
+
} from "./security-verdict.ts";
|
|
80
|
+
|
|
81
|
+
export { REVIEW_SCOPE_DIFF, REVIEW_SCOPE_FULL, type ReviewScope };
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* How many review rounds a pull request gets before the reviewer is told to
|
|
85
|
+
* stop listing defects and assess the approach instead.
|
|
86
|
+
*
|
|
87
|
+
* Three, which is the number Anthropic shipped. Re-derived against this
|
|
88
|
+
* repository rather than adopted: over 294 merged pull requests that had an
|
|
89
|
+
* `AI Review` run, 22 (7.5%) went past three rounds, 13 (4.4%) reached five
|
|
90
|
+
* or more, and the mean was 1.738. So a cap of three leaves 92.5% of pull
|
|
91
|
+
* requests untouched and still reaches every run that has actually gone long.
|
|
92
|
+
*/
|
|
93
|
+
export const AI_REVIEW_ROUND_CAP = 3;
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The round from which a re-review may be scoped to the diff.
|
|
97
|
+
*
|
|
98
|
+
* Anthropic's "after the first few passes". Here it is the round AFTER the
|
|
99
|
+
* first, and it is a floor rather than the decision: `reviewScopeForRound`
|
|
100
|
+
* still refuses to diff-scope a round whose held verdict is not a PASS, which
|
|
101
|
+
* is `reReviewScope`'s rule and the whole of #244.
|
|
102
|
+
*/
|
|
103
|
+
export const AI_REVIEW_DIFF_SCOPE_FROM_ROUND = 3;
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The round budget could not be read, so this job does not know which round
|
|
107
|
+
* it is on.
|
|
108
|
+
*
|
|
109
|
+
* DECLARED ONCE, as an exported constant, for the reason
|
|
110
|
+
* `SECURITY_REREVIEW_EXHAUSTED` is: a second spelling is a second refusal
|
|
111
|
+
* path, reachable by code the first one's tests never visit.
|
|
112
|
+
*
|
|
113
|
+
* This is a REFUSAL and not a warning, and the reasoning is
|
|
114
|
+
* `reReviewDecision`'s own — a budget nobody can read is not a budget with
|
|
115
|
+
* room left in it. The specific fail-open it closes: an unreadable counter
|
|
116
|
+
* makes round 12 indistinguishable from round 1, and reading it as round 1
|
|
117
|
+
* resets the bound on every run, which is a cap that can never be reached.
|
|
118
|
+
*/
|
|
119
|
+
export const AI_REVIEW_ROUNDS_UNMEASURED = "AI_REVIEW_ROUNDS_UNMEASURED";
|
|
120
|
+
|
|
121
|
+
/** The review is within budget and reviews normally. */
|
|
122
|
+
export const AI_REVIEW_ROUND_OPEN = "AI_REVIEW_ROUND_OPEN";
|
|
123
|
+
/**
|
|
124
|
+
* The budget is spent. The reviewer still speaks — see `atCapInstruction` —
|
|
125
|
+
* it just stops enumerating defects and says something about the approach.
|
|
126
|
+
*/
|
|
127
|
+
export const AI_REVIEW_ROUND_AT_CAP = "AI_REVIEW_ROUND_AT_CAP";
|
|
128
|
+
|
|
129
|
+
export type RoundDecision =
|
|
130
|
+
| typeof AI_REVIEW_ROUND_OPEN
|
|
131
|
+
| typeof AI_REVIEW_ROUND_AT_CAP
|
|
132
|
+
| typeof AI_REVIEW_ROUNDS_UNMEASURED;
|
|
133
|
+
|
|
134
|
+
export interface RoundOutcome {
|
|
135
|
+
/** Exactly one of the three verdicts above. */
|
|
136
|
+
decision: RoundDecision;
|
|
137
|
+
/** The round this run is, or null when it could not be read. */
|
|
138
|
+
round: number | null;
|
|
139
|
+
/** Why the run is not in the ordinary state. Null — and only null — when it is. */
|
|
140
|
+
reason: string | null;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* A round number as it arrives from the workflow: a decimal string on stdout,
|
|
145
|
+
* or nothing.
|
|
146
|
+
*
|
|
147
|
+
* FAILS CLOSED. Anything that is not a positive decimal integer is null, and
|
|
148
|
+
* null is the refusal above. `Number()` is not used: it reads `""` as 0,
|
|
149
|
+
* `" 2 "` as 2 and `0x3` as 3, and a counter that accepts three spellings of
|
|
150
|
+
* a number accepts inputs nobody has decided about.
|
|
151
|
+
*
|
|
152
|
+
* Zero is refused along with the rest. A run that is happening is at least
|
|
153
|
+
* round 1, so a counter reporting 0 has not counted this run — which is a
|
|
154
|
+
* different defect from an unreadable one and not one to paper over by
|
|
155
|
+
* adding one to it.
|
|
156
|
+
*/
|
|
157
|
+
export function readRoundNumber(v: unknown): number | null {
|
|
158
|
+
if (typeof v === "number") {
|
|
159
|
+
return Number.isInteger(v) && v >= 1 ? v : null;
|
|
160
|
+
}
|
|
161
|
+
if (typeof v !== "string") return null;
|
|
162
|
+
const trimmed = v.trim();
|
|
163
|
+
if (!/^[0-9]+$/.test(trimmed)) return null;
|
|
164
|
+
const n = Number.parseInt(trimmed, 10);
|
|
165
|
+
return Number.isSafeInteger(n) && n >= 1 ? n : null;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Which state is this round in?
|
|
170
|
+
*
|
|
171
|
+
* The cap arithmetic is NOT done here. It is handed to `reReviewDecision`,
|
|
172
|
+
* which already answers "is there a round left in this budget" and already
|
|
173
|
+
* fails closed on an unreadable one — so the two cannot be changed apart, and
|
|
174
|
+
* a mutation of its `spent < cap` is observable through this function. The
|
|
175
|
+
* currency argument is the stale shape on purpose: a run that is reviewing is
|
|
176
|
+
* by definition reviewing something a previous round did not clear, so the
|
|
177
|
+
* only question left for that function is the budget one.
|
|
178
|
+
*
|
|
179
|
+
* `roundsSpent` is `round - 1` — the rounds that are already over. At round
|
|
180
|
+
* 4 with a cap of 3 that is 3 of 3 and the budget is gone, which is what
|
|
181
|
+
* makes round 4 the first capped round and rounds 1-3 the three the author
|
|
182
|
+
* gets.
|
|
183
|
+
*/
|
|
184
|
+
export function roundOutcome(raw: unknown, cap: unknown = AI_REVIEW_ROUND_CAP): RoundOutcome {
|
|
185
|
+
const round = readRoundNumber(raw);
|
|
186
|
+
if (round === null) {
|
|
187
|
+
return {
|
|
188
|
+
decision: AI_REVIEW_ROUNDS_UNMEASURED,
|
|
189
|
+
round: null,
|
|
190
|
+
reason:
|
|
191
|
+
`the review-round counter read ${describe(raw)}, which is not a round number — ` +
|
|
192
|
+
`this job cannot tell a first review from a twelfth, so the round budget is ` +
|
|
193
|
+
`unreadable and refusing is the only reading that is not a guess`,
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
const stale = {
|
|
198
|
+
current: false,
|
|
199
|
+
reason: `this is review round ${round} on this pull request`,
|
|
200
|
+
};
|
|
201
|
+
const outcome = reReviewDecision(stale, round - 1, cap);
|
|
202
|
+
|
|
203
|
+
if (outcome.decision === RE_REVIEW) {
|
|
204
|
+
return { decision: AI_REVIEW_ROUND_OPEN, round, reason: null };
|
|
205
|
+
}
|
|
206
|
+
// REVIEW_CURRENT cannot be reached: the currency handed in is always stale.
|
|
207
|
+
// Checked anyway rather than folded into the exhaustion branch, because the
|
|
208
|
+
// two mean opposite things and a later change to the currency above would
|
|
209
|
+
// otherwise report "nothing to review" as "out of rounds".
|
|
210
|
+
if (outcome.decision === REVIEW_CURRENT) {
|
|
211
|
+
return { decision: AI_REVIEW_ROUND_OPEN, round, reason: null };
|
|
212
|
+
}
|
|
213
|
+
return {
|
|
214
|
+
decision: AI_REVIEW_ROUND_AT_CAP,
|
|
215
|
+
round,
|
|
216
|
+
reason: outcome.reason,
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* The scope the reviewer should read on this round.
|
|
222
|
+
*
|
|
223
|
+
* Two gates, and BOTH must open. The round floor is Anthropic's "after the
|
|
224
|
+
* first few passes"; `reReviewScope` is #244's refusal to diff-scope anything
|
|
225
|
+
* but a held PASS. The second is the one that matters, and it is delegated
|
|
226
|
+
* rather than restated: a diff against the flagged commit does not contain
|
|
227
|
+
* the flagged code.
|
|
228
|
+
*
|
|
229
|
+
* FAILS CLOSED TOWARD READING MORE, in both halves. An unreadable round is a
|
|
230
|
+
* full review, not a skipped one.
|
|
231
|
+
*/
|
|
232
|
+
export function reviewScopeForRound(rawRound: unknown, heldVerdict: unknown): ReviewScope {
|
|
233
|
+
const round = readRoundNumber(rawRound);
|
|
234
|
+
if (round === null || round < AI_REVIEW_DIFF_SCOPE_FROM_ROUND) return REVIEW_SCOPE_FULL;
|
|
235
|
+
return reReviewScope(heldVerdict);
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** A finding as the payload contract spells it (`AI_REVIEW_FINDING_FIELDS`). */
|
|
239
|
+
export interface ReviewFinding {
|
|
240
|
+
severity?: unknown;
|
|
241
|
+
file?: unknown;
|
|
242
|
+
line?: unknown;
|
|
243
|
+
summary?: unknown;
|
|
244
|
+
failure_scenario?: unknown;
|
|
245
|
+
[k: string]: unknown;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* Collapse the incidental differences between two spellings of one sentence.
|
|
250
|
+
*
|
|
251
|
+
* Case and whitespace only. Not punctuation, and not stemming: two findings
|
|
252
|
+
* that differ in a word are two findings, and a key that erases the
|
|
253
|
+
* difference suppresses a real one.
|
|
254
|
+
*/
|
|
255
|
+
function normalise(v: unknown): string {
|
|
256
|
+
return typeof v === "string" ? v.trim().toLowerCase().replace(/\s+/g, " ") : "";
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* The identity of a finding, for deciding whether it has already been raised.
|
|
261
|
+
*
|
|
262
|
+
* @identity file+text+summary — `file`, the TEXT of the cited line (falling
|
|
263
|
+
* back to the line NUMBER when the text is not known), and `summary`.
|
|
264
|
+
* Partial: `null` for a finding it cannot key.
|
|
265
|
+
*
|
|
266
|
+
* **This is the PERSISTENCE key** — "is the thing this round raised the thing
|
|
267
|
+
* the last round raised". It is the one the ledger's anchors are recorded
|
|
268
|
+
* under ({@link AI_REVIEW_LEDGER_IDENTITY}) and the one that can refuse.
|
|
269
|
+
*
|
|
270
|
+
* Its sibling is `advisoryKey` in `lib/scaffold/ai-review-findings.ts`, which
|
|
271
|
+
* is the ADJUDICATION key — "has this advisory already been counted on this
|
|
272
|
+
* run" — over `file`+`summary` only, total, never `null`. The two were both
|
|
273
|
+
* called `findingKey` until #1398 and they are deliberately different: a
|
|
274
|
+
* line anchor here is what makes a re-summary of one file two findings
|
|
275
|
+
* rather than one, and a line anchor THERE would split a single finding in
|
|
276
|
+
* two across a reformat. Neither rule can quietly become the other —
|
|
277
|
+
* measured, and both unification mutants are caught — but a call site could
|
|
278
|
+
* not tell which question it was asking while they shared a name.
|
|
279
|
+
*
|
|
280
|
+
* `file` + the TEXT of the cited line + `summary`. **Not the line number**,
|
|
281
|
+
* and that is the measured part rather than a preference: the one repeat this
|
|
282
|
+
* repository can actually show moved from `:318` to `:375` between rounds
|
|
283
|
+
* while staying byte-identical, so a `file:line` key would have let it
|
|
284
|
+
* through. See this module's header.
|
|
285
|
+
*
|
|
286
|
+
* `lineText` is the content at the cited line, supplied by the caller because
|
|
287
|
+
* only the caller has the checkout. Absent or empty, the key falls back to
|
|
288
|
+
* the line NUMBER — which is weaker, and is the honest answer when the line
|
|
289
|
+
* cannot be read: a key that pretends to content it never saw would suppress
|
|
290
|
+
* on a collision of empty strings, and that suppresses everything.
|
|
291
|
+
*
|
|
292
|
+
* Returns null for a finding with no `file` and no `summary`. There is
|
|
293
|
+
* nothing to compare such a finding against, and giving it a key would make
|
|
294
|
+
* every one of them a repeat of the first.
|
|
295
|
+
*/
|
|
296
|
+
export function carryKey(finding: unknown, lineText?: unknown): string | null {
|
|
297
|
+
if (typeof finding !== "object" || finding === null || Array.isArray(finding)) return null;
|
|
298
|
+
const f = finding as ReviewFinding;
|
|
299
|
+
const file = normalise(f.file);
|
|
300
|
+
const summary = normalise(f.summary);
|
|
301
|
+
if (!file && !summary) return null;
|
|
302
|
+
const text = normalise(lineText);
|
|
303
|
+
const anchor = text !== ""
|
|
304
|
+
? `t:${text}`
|
|
305
|
+
: `n:${typeof f.line === "number" && Number.isInteger(f.line) ? f.line : ""}`;
|
|
306
|
+
return `${file}\u0000${anchor}\u0000${summary}`;
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
export interface SuppressionReading {
|
|
310
|
+
/** Findings this round may report. */
|
|
311
|
+
kept: ReviewFinding[];
|
|
312
|
+
/** Findings dropped because an earlier round already raised them. */
|
|
313
|
+
suppressed: ReviewFinding[];
|
|
314
|
+
/** One line per suppressed finding, for the annotation. */
|
|
315
|
+
reasons: string[];
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Drop findings an earlier round already raised.
|
|
320
|
+
*
|
|
321
|
+
* Keyed by `carryKey`, so a finding whose line number moved is still a
|
|
322
|
+
* repeat and a finding whose summary changed is not.
|
|
323
|
+
*
|
|
324
|
+
* **Within this round too.** A reviewer that lists the same defect twice in
|
|
325
|
+
* one payload is the same waste as one that lists it on two rounds, and the
|
|
326
|
+
* first occurrence is kept. An unkeyable finding (no file, no summary) is
|
|
327
|
+
* always kept: it cannot be shown to be a repeat, and the direction this is
|
|
328
|
+
* allowed to be wrong in is toward reporting.
|
|
329
|
+
*
|
|
330
|
+
* `priorKeys` is what earlier rounds raised. It is a parameter rather than
|
|
331
|
+
* something read here, because only the caller can reach the pull request's
|
|
332
|
+
* history, and a function that fetches its own evidence cannot be given a
|
|
333
|
+
* negative control.
|
|
334
|
+
*/
|
|
335
|
+
export function suppressRepeats(
|
|
336
|
+
fresh: unknown,
|
|
337
|
+
priorKeys: Iterable<string>,
|
|
338
|
+
lineTextFor?: (f: ReviewFinding) => string | undefined,
|
|
339
|
+
): SuppressionReading {
|
|
340
|
+
const seen = new Set<string>(priorKeys);
|
|
341
|
+
const kept: ReviewFinding[] = [];
|
|
342
|
+
const suppressed: ReviewFinding[] = [];
|
|
343
|
+
const reasons: string[] = [];
|
|
344
|
+
const list = Array.isArray(fresh) ? fresh : [];
|
|
345
|
+
|
|
346
|
+
for (const raw of list) {
|
|
347
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
348
|
+
kept.push(raw as ReviewFinding);
|
|
349
|
+
continue;
|
|
350
|
+
}
|
|
351
|
+
const f = raw as ReviewFinding;
|
|
352
|
+
const key = carryKey(f, lineTextFor?.(f));
|
|
353
|
+
if (key === null || !seen.has(key)) {
|
|
354
|
+
if (key !== null) seen.add(key);
|
|
355
|
+
kept.push(f);
|
|
356
|
+
continue;
|
|
357
|
+
}
|
|
358
|
+
suppressed.push(f);
|
|
359
|
+
reasons.push(
|
|
360
|
+
`${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
|
|
361
|
+
`raised on an earlier round of this pull request, so it is not raised again`,
|
|
362
|
+
);
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
return { kept, suppressed, reasons };
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* Which of an earlier round's findings are still unresolved at this commit?
|
|
370
|
+
*
|
|
371
|
+
* This is what makes a diff-scoped round honest. A diff-scoped reviewer never
|
|
372
|
+
* reads the code an earlier finding was about, so if the adjudicator does not
|
|
373
|
+
* re-emit the unresolved ones the finding vanishes and the check goes green —
|
|
374
|
+
* `46034035` arriving by a different door.
|
|
375
|
+
*
|
|
376
|
+
* A finding is RESOLVED when the line it names is no longer the line it named:
|
|
377
|
+
* `currentLineText` differs from the text recorded with the finding. It is
|
|
378
|
+
* UNRESOLVED when the text is unchanged. When the text cannot be read at all
|
|
379
|
+
* it is UNRESOLVED, because a finding nobody could check is not a finding
|
|
380
|
+
* anybody cleared — the direction `reviewIsCurrent` also fails in.
|
|
381
|
+
*
|
|
382
|
+
* **It is a CONTENT comparison and not `reviewIsCurrent`, deliberately.**
|
|
383
|
+
* That function compares two commit SHAs, which is the right reading for "is
|
|
384
|
+
* this whole review still about this branch" and the wrong one for "is this
|
|
385
|
+
* one finding still true". Measured on this repository's own two multi-round
|
|
386
|
+
* cases: on `rg/1175` the branch was rebased between rounds, so the commit
|
|
387
|
+
* that introduced the flagged line is not an ancestor of the round-1 head
|
|
388
|
+
* even though the line is byte-identical in it; on `fix/1129` the round-2
|
|
389
|
+
* commit is an amend of the round-1 one, so blame attributes a line to it
|
|
390
|
+
* that it did not touch. Both findings were stale and a SHA or ancestry
|
|
391
|
+
* reading calls both of them fresh. Content is the only reading that was
|
|
392
|
+
* right on both.
|
|
393
|
+
*/
|
|
394
|
+
export interface CarriedFinding {
|
|
395
|
+
finding: ReviewFinding;
|
|
396
|
+
/** The text at the cited line when the finding was raised. */
|
|
397
|
+
recordedText?: string;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
export function carryForward(
|
|
401
|
+
prior: readonly CarriedFinding[],
|
|
402
|
+
currentLineText: (f: ReviewFinding) => string | undefined,
|
|
403
|
+
): ReviewFinding[] {
|
|
404
|
+
const out: ReviewFinding[] = [];
|
|
405
|
+
for (const entry of prior) {
|
|
406
|
+
// NOTHING WAS RECORDED, so resolution is UNDECIDABLE — carry it.
|
|
407
|
+
//
|
|
408
|
+
// This branch is the whole of the reading half's first defect. Without
|
|
409
|
+
// it, `normalise(undefined)` is `""`, which differs from any real line,
|
|
410
|
+
// so a finding whose text was never recorded is read as RESOLVED and
|
|
411
|
+
// dropped — silently, every time. Measured against the ledger #1319
|
|
412
|
+
// actually writes, which recorded `{severity, file, line, summary}` and
|
|
413
|
+
// no text: one finding in, zero carried out. An absent reading is not a
|
|
414
|
+
// reading that cleared, and this is the same refusal `roundOutcome`
|
|
415
|
+
// makes about an unreadable budget.
|
|
416
|
+
if (typeof entry.recordedText !== "string") {
|
|
417
|
+
out.push(entry.finding);
|
|
418
|
+
continue;
|
|
419
|
+
}
|
|
420
|
+
const now = currentLineText(entry.finding);
|
|
421
|
+
if (typeof now !== "string") {
|
|
422
|
+
out.push(entry.finding);
|
|
423
|
+
continue;
|
|
424
|
+
}
|
|
425
|
+
if (normalise(now) !== normalise(entry.recordedText)) continue;
|
|
426
|
+
out.push(entry.finding);
|
|
427
|
+
}
|
|
428
|
+
return out;
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
/* ───────────────── reading the ledger a previous round wrote ──────────────
|
|
432
|
+
*
|
|
433
|
+
* `lib/scaffold/ai-review-step.ts` upserts ONE comment per pull request
|
|
434
|
+
* holding one JSON entry per review round (#1319). Everything above this line
|
|
435
|
+
* takes the prior rounds as a parameter, deliberately — a function that
|
|
436
|
+
* fetches its own evidence cannot be given a negative control. This is the
|
|
437
|
+
* part that turns that comment into the parameter.
|
|
438
|
+
*
|
|
439
|
+
* The two properties it exists to hold, both of which are easy to lose:
|
|
440
|
+
*
|
|
441
|
+
* 1. **Identity is stated, not assumed.** The ledger stamps the rule its
|
|
442
|
+
* anchors were recorded under. A reader that meets a rule it does not
|
|
443
|
+
* know refuses to form keys rather than keying under its own — because
|
|
444
|
+
* keying under the wrong rule does not fail, it silently compares two
|
|
445
|
+
* different things and suppresses live findings.
|
|
446
|
+
*
|
|
447
|
+
* 2. **"Nothing recorded" and "could not read what was recorded" are
|
|
448
|
+
* different facts.** `lib/config-loader.ts` makes the same distinction
|
|
449
|
+
* about an absent config versus a corrupt one, for the same reason: both
|
|
450
|
+
* yield nothing, and only one of them is a reading. Here the type carries
|
|
451
|
+
* it — an unmeasured reading does not HAVE a `keys` field, so a caller
|
|
452
|
+
* cannot reach for one without narrowing the status first.
|
|
453
|
+
*
|
|
454
|
+
* These four constants are declared again in `lib/scaffold/ai-review-step.ts`
|
|
455
|
+
* and must agree. They are not imported from there, and that file must not
|
|
456
|
+
* import this one: the mutation batteries build a mutant by copying that file
|
|
457
|
+
* alone into a scratch directory, so a relative import added to it resolves
|
|
458
|
+
* to nothing and the mutant fails to LOAD — which reads as a behavioural
|
|
459
|
+
* difference on every row (`.claude/rules/self-referential-tests.md`, Tier 1).
|
|
460
|
+
* `test/ai-review-ledger-read.test.ts` AC-R6 binds all four instead.
|
|
461
|
+
*/
|
|
462
|
+
|
|
463
|
+
/**
|
|
464
|
+
* The identity rule the ledger's recorded anchors were formed under.
|
|
465
|
+
*
|
|
466
|
+
* Versioned in the string itself. A reader meeting an identity it does not
|
|
467
|
+
* recognise carries the findings and declines to key them, so changing the
|
|
468
|
+
* rule is a safe, one-sided operation: old rounds stop suppressing, and
|
|
469
|
+
* nothing silently compares an old anchor against a new rule.
|
|
470
|
+
*/
|
|
471
|
+
export const AI_REVIEW_LEDGER_IDENTITY = "file+text+summary@v1";
|
|
472
|
+
|
|
473
|
+
/** The HTML comment that identifies the ledger comment. */
|
|
474
|
+
export const AI_REVIEW_LEDGER_COMMENT_MARKER = "<!-- rungate:ai-review-ledger:v1 -->";
|
|
475
|
+
|
|
476
|
+
/** The key the per-round findings array is recorded under. */
|
|
477
|
+
export const AI_REVIEW_LEDGER_FINDINGS_KEY = "findings";
|
|
478
|
+
|
|
479
|
+
/**
|
|
480
|
+
* The key the round array hangs off in the windowed ledger shape.
|
|
481
|
+
*
|
|
482
|
+
* The ledger's JSON block was originally the array itself. That shape has no
|
|
483
|
+
* position to say anything ABOUT the array, which is #1405: a ledger holding
|
|
484
|
+
* twelve rounds because twelve is all there have been, and a ledger holding
|
|
485
|
+
* twelve because it evicted eight, are byte-identical. The eviction is
|
|
486
|
+
* announced in a warning annotation that lives in the job log and expires.
|
|
487
|
+
*/
|
|
488
|
+
export const AI_REVIEW_LEDGER_ROUNDS_KEY = "rounds";
|
|
489
|
+
|
|
490
|
+
/** The key holding how many rounds the window has dropped off the front. */
|
|
491
|
+
export const AI_REVIEW_LEDGER_TRUNCATED_KEY = "truncated";
|
|
492
|
+
|
|
493
|
+
/** The key holding the text at the cited line when the finding was raised. */
|
|
494
|
+
export const AI_REVIEW_LEDGER_FINDING_TEXT = "text";
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* The key holding how many turns the reviewer spent on this round (#1380).
|
|
498
|
+
*
|
|
499
|
+
* #1380 measured 3 of 3 observable same-tree re-runs producing a DIFFERENT
|
|
500
|
+
* verdict, the strongest being merge commit `99d50fc` at round 5 both times,
|
|
501
|
+
* BLOCKED then CLEAN, at 51 turns and 52 against a cap of 80. The turn count
|
|
502
|
+
* is the only candidate mechanism anyone has for that, and it is the one
|
|
503
|
+
* thing about a round that nothing recorded.
|
|
504
|
+
*
|
|
505
|
+
* Mining the history cannot settle it: at the pre-#1198 26% payload rate,
|
|
506
|
+
* n=20 readable same-tree pairs needs ~290 re-runs and 28 exist. So the
|
|
507
|
+
* number has to be captured going forward or not at all, and this is the
|
|
508
|
+
* position that already records `sha`, `run`, `attempt`, `round` and
|
|
509
|
+
* `identity` per entry.
|
|
510
|
+
*/
|
|
511
|
+
export const AI_REVIEW_LEDGER_TURNS_KEY = "turns";
|
|
512
|
+
|
|
513
|
+
/**
|
|
514
|
+
* The key holding the commit the reviewer actually read (#1380).
|
|
515
|
+
*
|
|
516
|
+
* NOT the same fact as `sha`, and that is the whole reason it exists. `sha`
|
|
517
|
+
* is `github.event.pull_request.head.sha`; the review ran over whatever
|
|
518
|
+
* `actions/checkout` put in the tree, which on a `pull_request` event is the
|
|
519
|
+
* MERGE commit — head merged into the base as it stood when the run started.
|
|
520
|
+
*
|
|
521
|
+
* So two rounds sharing a `sha` are not two rounds over one tree: the base
|
|
522
|
+
* moves without the head moving, and the reviewer sees different bytes. A
|
|
523
|
+
* same-tree pair is two rounds sharing THIS field, and #1380's whole
|
|
524
|
+
* conditioning caveat — 28 same-tree pairs, 3 readable — was derived from
|
|
525
|
+
* merge commits off the Actions API because the ledger could not answer it.
|
|
526
|
+
*/
|
|
527
|
+
export const AI_REVIEW_LEDGER_MERGE_KEY = "merge";
|
|
528
|
+
|
|
529
|
+
/**
|
|
530
|
+
* The key holding the verdict WORD the reviewer wrote beside its findings
|
|
531
|
+
* (#1511).
|
|
532
|
+
*
|
|
533
|
+
* Not an adjudicated outcome and not derivable from `findings`. The payload
|
|
534
|
+
* contract asks the reviewer for a word, `lib/scaffold/ai-review-findings.ts`
|
|
535
|
+
* compares it to what the severities say, and a disagreement is a
|
|
536
|
+
* CONTRADICTION — #1178's shape, measured at roughly a third of runs. A
|
|
537
|
+
* reader handed findings alone can compute what the word SHOULD have been
|
|
538
|
+
* and cannot recover what it WAS, so the contradiction is unobservable
|
|
539
|
+
* through a ledger that does not record it.
|
|
540
|
+
*
|
|
541
|
+
* Which is what the ledger did until #1511, and why
|
|
542
|
+
* `evals/ai-review-control/` could reach `QUIET`, `FIRED` and `MISSED` and
|
|
543
|
+
* never `DETECTED`: every captured round scored `VERDICT_ABSENT`.
|
|
544
|
+
*
|
|
545
|
+
* Declared here and in `lib/scaffold/ai-review-step.ts` as
|
|
546
|
+
* `AI_REVIEW_VERDICT_KEY`, bound by `AC-R6` in
|
|
547
|
+
* `test/ai-review-ledger-read.test.ts` rather than by an import, because
|
|
548
|
+
* that module must stay import-free — the mutation batteries copy it into a
|
|
549
|
+
* temp directory where no relative specifier resolves.
|
|
550
|
+
*/
|
|
551
|
+
export const AI_REVIEW_LEDGER_VERDICT_KEY = "verdict";
|
|
552
|
+
|
|
553
|
+
/** The round predates #1511. Nobody tried to record a verdict word. */
|
|
554
|
+
export const AI_REVIEW_VERDICT_NOT_RECORDED = "AI_REVIEW_VERDICT_NOT_RECORDED";
|
|
555
|
+
|
|
556
|
+
/** The round tried to record a verdict word and found none to record. */
|
|
557
|
+
export const AI_REVIEW_VERDICT_UNREADABLE = "AI_REVIEW_VERDICT_UNREADABLE";
|
|
558
|
+
|
|
559
|
+
/** A verdict word was recorded. What it SAYS is the adjudicator's question. */
|
|
560
|
+
export const AI_REVIEW_VERDICT_RECORDED = "AI_REVIEW_VERDICT_RECORDED";
|
|
561
|
+
|
|
562
|
+
/**
|
|
563
|
+
* The verdict word a round recorded, or why there is none.
|
|
564
|
+
*
|
|
565
|
+
* Three states and not two, the same split `turns` carries one key over and
|
|
566
|
+
* for the same reason: a round written before #1511 has no key, and a round
|
|
567
|
+
* written after it always has one. Collapsing them makes a ledger that never
|
|
568
|
+
* recorded a verdict indistinguishable from a reviewer that wrote none.
|
|
569
|
+
*
|
|
570
|
+
* `word` is `unknown` and is **never validated here**. Whether `PASS` and
|
|
571
|
+
* `BLOCK` are the only legal words is
|
|
572
|
+
* `lib/scaffold/ai-review-findings.ts`' decision and it already makes it;
|
|
573
|
+
* a second gate here would be two deciders answering one question, of which
|
|
574
|
+
* a mutation leaves either one holding the case up. A ledger carrying
|
|
575
|
+
* `MAYBE` reports `MAYBE`, and the adjudicator calls it
|
|
576
|
+
* `VERDICT_UNRECOGNISED` — which is the truth about that round.
|
|
577
|
+
*/
|
|
578
|
+
export type LedgerVerdictReading =
|
|
579
|
+
| { status: typeof AI_REVIEW_VERDICT_NOT_RECORDED }
|
|
580
|
+
| { status: typeof AI_REVIEW_VERDICT_UNREADABLE }
|
|
581
|
+
| { status: typeof AI_REVIEW_VERDICT_RECORDED; word: unknown };
|
|
582
|
+
|
|
583
|
+
/**
|
|
584
|
+
* Read the verdict word off a ledger round.
|
|
585
|
+
*
|
|
586
|
+
* `undefined` — no key at all — is NOT_RECORDED. A JSON `null` is the
|
|
587
|
+
* writer saying it looked and found nothing, which is UNREADABLE. Anything
|
|
588
|
+
* else is carried through verbatim, including shapes no contract declares.
|
|
589
|
+
*/
|
|
590
|
+
export function readRoundVerdict(raw: unknown): LedgerVerdictReading {
|
|
591
|
+
if (raw === undefined) return { status: AI_REVIEW_VERDICT_NOT_RECORDED };
|
|
592
|
+
if (raw === null) return { status: AI_REVIEW_VERDICT_UNREADABLE };
|
|
593
|
+
return { status: AI_REVIEW_VERDICT_RECORDED, word: raw };
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
/** The round predates #1380. Nobody tried to read a turn count. */
|
|
597
|
+
export const AI_REVIEW_TURNS_NOT_RECORDED = "AI_REVIEW_TURNS_NOT_RECORDED";
|
|
598
|
+
|
|
599
|
+
/** This round tried to read a turn count and could not. */
|
|
600
|
+
export const AI_REVIEW_TURNS_UNREADABLE = "AI_REVIEW_TURNS_UNREADABLE";
|
|
601
|
+
|
|
602
|
+
/** The turn count was read. */
|
|
603
|
+
export const AI_REVIEW_TURNS_READ = "AI_REVIEW_TURNS_READ";
|
|
604
|
+
|
|
605
|
+
/**
|
|
606
|
+
* How many turns the reviewer spent, or why that is not known.
|
|
607
|
+
*
|
|
608
|
+
* The non-READ arms carry **no count field at all**, the construction
|
|
609
|
+
* `LedgerTruncation` and `PriorState` already use here: a caller cannot
|
|
610
|
+
* reach for a number without narrowing the status first, so "I could not
|
|
611
|
+
* tell" has no way to be read as zero. `0` is the answer that matters —
|
|
612
|
+
* a run whose execution file never arrived and a run that spent no turns
|
|
613
|
+
* are not the same event, and a `?? 0` makes them one.
|
|
614
|
+
*
|
|
615
|
+
* THREE STATES AND NOT TWO. Absent is NOT_RECORDED and `null` is
|
|
616
|
+
* UNREADABLE, which is the same split `findings` already carries one key
|
|
617
|
+
* over: every round written before #1380 has no key, and a round written
|
|
618
|
+
* after it always has one. Collapsing them would make a ledger that
|
|
619
|
+
* measured nothing indistinguishable from a ledger written last week.
|
|
620
|
+
*/
|
|
621
|
+
export type TurnReading =
|
|
622
|
+
| { status: typeof AI_REVIEW_TURNS_NOT_RECORDED }
|
|
623
|
+
| { status: typeof AI_REVIEW_TURNS_UNREADABLE }
|
|
624
|
+
| { status: typeof AI_REVIEW_TURNS_READ; turns: number };
|
|
625
|
+
|
|
626
|
+
/**
|
|
627
|
+
* Read the turn count off a ledger round.
|
|
628
|
+
*
|
|
629
|
+
* `undefined` — no key at all — is NOT_RECORDED. Anything that is not a
|
|
630
|
+
* non-negative integer is UNREADABLE rather than the nearest number: a
|
|
631
|
+
* `"51"` the writer never produces, a float, a negative, `null` itself.
|
|
632
|
+
* There is no branch that returns a count it had to repair.
|
|
633
|
+
*/
|
|
634
|
+
export function readRoundTurns(raw: unknown): TurnReading {
|
|
635
|
+
if (raw === undefined) return { status: AI_REVIEW_TURNS_NOT_RECORDED };
|
|
636
|
+
if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
|
|
637
|
+
return { status: AI_REVIEW_TURNS_UNREADABLE };
|
|
638
|
+
}
|
|
639
|
+
return { status: AI_REVIEW_TURNS_READ, turns: raw };
|
|
640
|
+
}
|
|
641
|
+
|
|
642
|
+
/** No ledger comment on this pull request. A MEASURED reading of nothing. */
|
|
643
|
+
export const AI_REVIEW_LEDGER_ABSENT = "AI_REVIEW_LEDGER_ABSENT";
|
|
644
|
+
|
|
645
|
+
/** A ledger is there and could not be read. NOT the same as absent. */
|
|
646
|
+
export const AI_REVIEW_LEDGER_UNREADABLE = "AI_REVIEW_LEDGER_UNREADABLE";
|
|
647
|
+
|
|
648
|
+
/** The ledger was read. */
|
|
649
|
+
export const AI_REVIEW_LEDGER_READ = "AI_REVIEW_LEDGER_READ";
|
|
650
|
+
|
|
651
|
+
/** Keyed on the file, the recorded TEXT of the cited line, and the summary. */
|
|
652
|
+
export const FINDING_IDENTITY_TEXT = "file+text+summary";
|
|
653
|
+
|
|
654
|
+
/**
|
|
655
|
+
* Keyed on the file, the cited line NUMBER, and the summary.
|
|
656
|
+
*
|
|
657
|
+
* Weaker, and recorded as such rather than passed off as the above: the one
|
|
658
|
+
* repeat this repository can demonstrate moved `:318` → `:375` between rounds
|
|
659
|
+
* while staying byte-identical, so this key would have missed it.
|
|
660
|
+
*/
|
|
661
|
+
export const FINDING_IDENTITY_LINE = "file+line+summary";
|
|
662
|
+
|
|
663
|
+
/** No key could be formed. The finding is carried and suppresses nothing. */
|
|
664
|
+
export const FINDING_IDENTITY_NONE = "unclassifiable";
|
|
665
|
+
|
|
666
|
+
export type FindingIdentity =
|
|
667
|
+
| typeof FINDING_IDENTITY_TEXT
|
|
668
|
+
| typeof FINDING_IDENTITY_LINE
|
|
669
|
+
| typeof FINDING_IDENTITY_NONE;
|
|
670
|
+
|
|
671
|
+
export interface LedgerRound {
|
|
672
|
+
/** The round number the entry recorded, or null if it recorded none. */
|
|
673
|
+
round: number | null;
|
|
674
|
+
/** The pull request's HEAD commit at the round. NOT the tree reviewed. */
|
|
675
|
+
sha: string;
|
|
676
|
+
/**
|
|
677
|
+
* The commit the reviewer actually read — see `AI_REVIEW_LEDGER_MERGE_KEY`.
|
|
678
|
+
* `""` when the entry recorded none, which is every round before #1380.
|
|
679
|
+
*/
|
|
680
|
+
mergeSha: string;
|
|
681
|
+
/** How many turns the reviewer spent, or why that is unknown (#1380). */
|
|
682
|
+
turns: TurnReading;
|
|
683
|
+
/** The verdict word the reviewer wrote, or why there is none (#1511). */
|
|
684
|
+
verdict: LedgerVerdictReading;
|
|
685
|
+
/** False when the entry recorded `findings: null`, or was not an object. */
|
|
686
|
+
measured: boolean;
|
|
687
|
+
/** True when the entry stamped the identity rule this reader knows. */
|
|
688
|
+
keyable: boolean;
|
|
689
|
+
findings: ReviewFinding[];
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
/** How many rounds fell off the front of the window could not be established. */
|
|
693
|
+
export const AI_REVIEW_TRUNCATION_UNKNOWN = "AI_REVIEW_TRUNCATION_UNKNOWN";
|
|
694
|
+
|
|
695
|
+
/** The ledger states how many rounds it has dropped. `0` is a statement. */
|
|
696
|
+
export const AI_REVIEW_TRUNCATION_STATED = "AI_REVIEW_TRUNCATION_STATED";
|
|
697
|
+
|
|
698
|
+
/**
|
|
699
|
+
* The round cap in force when every bare-array ledger in existence was
|
|
700
|
+
* written (#1447).
|
|
701
|
+
*
|
|
702
|
+
* **Deliberately not `AI_REVIEW_LEDGER_MAX_ROUNDS`, and deliberately not
|
|
703
|
+
* imported from it.** Two separate reasons, and they are both load-bearing:
|
|
704
|
+
*
|
|
705
|
+
* The derivation below — *a bare array shorter than its cap was never cut* —
|
|
706
|
+
* is only sound against the cap that was in force when that array was
|
|
707
|
+
* written. Binding it to the live cap would mean lowering the cap tomorrow
|
|
708
|
+
* silently re-reads ledgers written months ago as complete when they were
|
|
709
|
+
* truncated. It cannot do that here: the bare-array shape is CLOSED. #1405's
|
|
710
|
+
* writer migrates every ledger it touches to `{rounds, truncated}`, so no new
|
|
711
|
+
* bare array will ever be written and the population this constant describes
|
|
712
|
+
* is fixed. A fact about history is spelled as a historical constant.
|
|
713
|
+
*
|
|
714
|
+
* The value is 12 because `AI_REVIEW_LEDGER_MAX_ROUNDS` has been 12 since it
|
|
715
|
+
* was introduced in `41f2e93f` (#1168) and has never held another value —
|
|
716
|
+
* checked rather than assumed, because a cap that had once been lower would
|
|
717
|
+
* make every bare array between the old cap and 12 read as a complete history
|
|
718
|
+
* when it had been cut. That is the direction `lib/rounds-to-pass.ts` warns
|
|
719
|
+
* about in its own docblock: this metric's errors all flatter.
|
|
720
|
+
*
|
|
721
|
+
* And this module must gain no import. Mutation batteries copy it into a
|
|
722
|
+
* tmpdir, where a relative import dies on module resolution and the mutant
|
|
723
|
+
* reads as a refusal rather than as a guard that held —
|
|
724
|
+
* `.claude/rules/self-referential-tests.md`, Tier 1.
|
|
725
|
+
*/
|
|
726
|
+
export const AI_REVIEW_LEGACY_LEDGER_CAP = 12;
|
|
727
|
+
|
|
728
|
+
/**
|
|
729
|
+
* Whether the rounds in hand are the whole history.
|
|
730
|
+
*
|
|
731
|
+
* UNKNOWN carries **no count field at all**, the same construction
|
|
732
|
+
* `PriorState` uses: a caller cannot reach for a number without narrowing the
|
|
733
|
+
* status first, so "I could not tell" has no way to be read as zero. That is
|
|
734
|
+
* the defect this type exists to make unrepresentable — on #1396 an
|
|
735
|
+
* unreadable eviction count and "nothing was dropped" shared a `case` arm in
|
|
736
|
+
* the shell, and the ledger was written having evicted rounds it did not
|
|
737
|
+
* mention.
|
|
738
|
+
*
|
|
739
|
+
* A legacy ledger — the bare array, written before #1405 — is UNKNOWN and not
|
|
740
|
+
* zero. It may well be complete, and nothing in it says so.
|
|
741
|
+
*/
|
|
742
|
+
export type LedgerTruncation =
|
|
743
|
+
| { status: typeof AI_REVIEW_TRUNCATION_UNKNOWN; reason: string }
|
|
744
|
+
| { status: typeof AI_REVIEW_TRUNCATION_STATED; dropped: number };
|
|
745
|
+
|
|
746
|
+
/**
|
|
747
|
+
* The UNREADABLE arm, named so one construction site serves both a READING
|
|
748
|
+
* of a ledger body and a SELECTION among comments. Two literals would be two
|
|
749
|
+
* things to keep in step for one fact.
|
|
750
|
+
*/
|
|
751
|
+
export type LedgerUnreadable = {
|
|
752
|
+
status: typeof AI_REVIEW_LEDGER_UNREADABLE;
|
|
753
|
+
reason: string;
|
|
754
|
+
};
|
|
755
|
+
|
|
756
|
+
export type LedgerReading =
|
|
757
|
+
| { status: typeof AI_REVIEW_LEDGER_ABSENT }
|
|
758
|
+
| LedgerUnreadable
|
|
759
|
+
| {
|
|
760
|
+
status: typeof AI_REVIEW_LEDGER_READ;
|
|
761
|
+
rounds: LedgerRound[];
|
|
762
|
+
truncation: LedgerTruncation;
|
|
763
|
+
};
|
|
764
|
+
|
|
765
|
+
/**
|
|
766
|
+
* Say that the ledger could not be read, for a reason only the caller knows.
|
|
767
|
+
*
|
|
768
|
+
* The API call that lists a pull request's comments can fail, and when it
|
|
769
|
+
* does the caller has no body to hand to `readLedger`. Without this it would
|
|
770
|
+
* have to pass `null`, which reads as ABSENT — a failed fetch would then be
|
|
771
|
+
* indistinguishable from a pull request on its first round, and every earlier
|
|
772
|
+
* finding would silently stop being carried.
|
|
773
|
+
*/
|
|
774
|
+
export function ledgerUnreadable(reason: string): LedgerUnreadable {
|
|
775
|
+
return { status: AI_REVIEW_LEDGER_UNREADABLE, reason };
|
|
776
|
+
}
|
|
777
|
+
|
|
778
|
+
/**
|
|
779
|
+
* The login the ledger comment is written as, and the only one selected.
|
|
780
|
+
*
|
|
781
|
+
* **This clause is the load-bearing one, and the repository's own tracker is
|
|
782
|
+
* the counter-example that makes it so.** The rationale this selection used
|
|
783
|
+
* to carry said the conjunction was safe because *nothing else writes the
|
|
784
|
+
* marker*. Measured against the live API on 2026-10-24, pull requests #1319
|
|
785
|
+
* and #1386 each carry TWO comments containing
|
|
786
|
+
* `AI_REVIEW_LEDGER_COMMENT_MARKER`: the ledger, written by
|
|
787
|
+
* `github-actions[bot]`, and a `type: "User"` comment that quotes the marker
|
|
788
|
+
* while discussing it. The marker is a quotable string and uniqueness of a
|
|
789
|
+
* quotable string is not obtainable — so making the marker more exotic is
|
|
790
|
+
* not the answer, and the login clause is what separates the two today.
|
|
791
|
+
*
|
|
792
|
+
* `lib/scaffold/ai-review-step.ts` declares the same string as
|
|
793
|
+
* `AI_REVIEW_LEDGER_BOT_LOGIN` and `test/ai-review-ledger-selection.test.ts`
|
|
794
|
+
* binds the two, rather than importing: that module is copied into a tmpdir
|
|
795
|
+
* by mutation batteries, where a relative specifier dies on resolution.
|
|
796
|
+
*/
|
|
797
|
+
export const AI_REVIEW_LEDGER_BOT_LOGIN_NAME = "github-actions[bot]";
|
|
798
|
+
|
|
799
|
+
/**
|
|
800
|
+
* How many comments on one pull request may be the ledger. **One.**
|
|
801
|
+
*
|
|
802
|
+
* The single site every ambiguity refusal below is routed through, so a test
|
|
803
|
+
* can build a mutant copy of this module with the bound widened and watch
|
|
804
|
+
* the refusal stop happening. Raise it and `selectLedgerComment` returns the
|
|
805
|
+
* first match instead — which is the defect, performed and observed, rather
|
|
806
|
+
* than a sentence claiming the guard works
|
|
807
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
808
|
+
*/
|
|
809
|
+
export const AI_REVIEW_LEDGER_MAX_MATCHES = 1;
|
|
810
|
+
|
|
811
|
+
/**
|
|
812
|
+
* A pull-request comment, reduced to the four fields the selection reads.
|
|
813
|
+
*
|
|
814
|
+
* Every field is `unknown` because they arrive from an API response that a
|
|
815
|
+
* caller has at best parsed, never validated. A comment whose author block
|
|
816
|
+
* is missing is not a comment this selection may adopt.
|
|
817
|
+
*/
|
|
818
|
+
export interface LedgerCandidate {
|
|
819
|
+
id: unknown;
|
|
820
|
+
body: unknown;
|
|
821
|
+
login: unknown;
|
|
822
|
+
type: unknown;
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
/** A candidate that passed the selection — every field narrowed. */
|
|
826
|
+
export interface LedgerComment {
|
|
827
|
+
id: number;
|
|
828
|
+
body: string;
|
|
829
|
+
login: string;
|
|
830
|
+
type: string;
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
/**
|
|
834
|
+
* Which comment on a pull request IS the ledger, or why that is not knowable.
|
|
835
|
+
*
|
|
836
|
+
* Deliberately the same three statuses `LedgerReading` uses, because they are
|
|
837
|
+
* the same three facts one step earlier: there is no ledger here, there is
|
|
838
|
+
* something here that cannot be read as one, or here it is. A fourth status
|
|
839
|
+
* would be a second vocabulary for a question already answered.
|
|
840
|
+
*/
|
|
841
|
+
export type LedgerSelection =
|
|
842
|
+
| { status: typeof AI_REVIEW_LEDGER_ABSENT }
|
|
843
|
+
| LedgerUnreadable
|
|
844
|
+
| { status: typeof AI_REVIEW_LEDGER_READ; comment: LedgerComment };
|
|
845
|
+
|
|
846
|
+
/**
|
|
847
|
+
* Pick the ledger out of a pull request's comments, or REFUSE.
|
|
848
|
+
*
|
|
849
|
+
* **Two matches is not a reading, and the first of them is not an answer.**
|
|
850
|
+
* This is the whole of #1412: a reader handed more than one comment carrying
|
|
851
|
+
* the ledger marker has no way to tell which document it is about, and a
|
|
852
|
+
* wrong comment that parses is byte-indistinguishable from a right one — so
|
|
853
|
+
* every number computed off it (rounds-to-pass, the unmeasured split, the
|
|
854
|
+
* turn counts) would be read off a population nobody can name. Ambiguous and
|
|
855
|
+
* absent are different states and neither one is a ledger.
|
|
856
|
+
*
|
|
857
|
+
* Three readings, and they are kept apart on purpose:
|
|
858
|
+
*
|
|
859
|
+
* * **ABSENT** — no comment here was written by this bot carrying the
|
|
860
|
+
* marker. A MEASURED reading of nothing, correct and complete on round
|
|
861
|
+
* one, and the only one that licenses POSTing a first ledger.
|
|
862
|
+
* * **UNREADABLE** — more than one did. The reason names every id, because
|
|
863
|
+
* a refusal that does not say which documents collided is a refusal
|
|
864
|
+
* nobody can act on.
|
|
865
|
+
* * **READ** — exactly one, narrowed.
|
|
866
|
+
*
|
|
867
|
+
* A `type: "User"` comment quoting the marker is not a candidate and does
|
|
868
|
+
* not make the reading ambiguous either: it is not a ledger, so it is not
|
|
869
|
+
* one of the things that could be. See `AI_REVIEW_LEDGER_BOT_LOGIN_NAME` for
|
|
870
|
+
* why that clause — and not the marker's supposed uniqueness — is what makes
|
|
871
|
+
* this selection an identity.
|
|
872
|
+
*/
|
|
873
|
+
export function selectLedgerComment(
|
|
874
|
+
comments: readonly LedgerCandidate[],
|
|
875
|
+
): LedgerSelection {
|
|
876
|
+
const matches: LedgerComment[] = [];
|
|
877
|
+
for (const c of comments) {
|
|
878
|
+
if (c.type !== "Bot") continue;
|
|
879
|
+
if (c.login !== AI_REVIEW_LEDGER_BOT_LOGIN_NAME) continue;
|
|
880
|
+
if (typeof c.body !== "string") continue;
|
|
881
|
+
if (!c.body.includes(AI_REVIEW_LEDGER_COMMENT_MARKER)) continue;
|
|
882
|
+
if (typeof c.id !== "number" || !Number.isInteger(c.id)) {
|
|
883
|
+
return ledgerUnreadable(
|
|
884
|
+
`a comment written by ${AI_REVIEW_LEDGER_BOT_LOGIN_NAME} carries the ledger ` +
|
|
885
|
+
`marker and reports ${JSON.stringify(c.id)} as its id, which is not one, so ` +
|
|
886
|
+
"it cannot be addressed and is not being treated as absent",
|
|
887
|
+
);
|
|
888
|
+
}
|
|
889
|
+
matches.push({ id: c.id, body: c.body, login: c.login, type: c.type });
|
|
890
|
+
}
|
|
891
|
+
if (matches.length === 0) return { status: AI_REVIEW_LEDGER_ABSENT };
|
|
892
|
+
if (matches.length > AI_REVIEW_LEDGER_MAX_MATCHES) {
|
|
893
|
+
return ledgerUnreadable(
|
|
894
|
+
`${matches.length} comments on this pull request are written by ` +
|
|
895
|
+
`${AI_REVIEW_LEDGER_BOT_LOGIN_NAME} and carry the ledger marker (ids ` +
|
|
896
|
+
`${matches.map(m => m.id).join(", ")}), so which one is the ledger cannot be ` +
|
|
897
|
+
"established. Refusing to read the first: a wrong ledger that parses is " +
|
|
898
|
+
"indistinguishable from the right one afterwards",
|
|
899
|
+
);
|
|
900
|
+
}
|
|
901
|
+
return { status: AI_REVIEW_LEDGER_READ, comment: matches[0] };
|
|
902
|
+
}
|
|
903
|
+
|
|
904
|
+
/**
|
|
905
|
+
* Parse the ledger comment's body.
|
|
906
|
+
*
|
|
907
|
+
* `null`, `undefined` and a body without the marker are ABSENT: there is no
|
|
908
|
+
* ledger, which is the correct and complete reading on round one. A body that
|
|
909
|
+
* HAS the marker and whose JSON block is missing, truncated, unparseable or
|
|
910
|
+
* neither of the two round shapes is UNREADABLE — never an empty ledger,
|
|
911
|
+
* because treating a damaged ledger as empty discards every round it holds at
|
|
912
|
+
* exactly the moment nothing can tell that it happened.
|
|
913
|
+
*
|
|
914
|
+
* Two round shapes are accepted and the reading says which was found through
|
|
915
|
+
* `truncation`: a bare array, which is every ledger written before #1405 and
|
|
916
|
+
* is still live on open pull requests, and `{rounds, truncated}`, which can
|
|
917
|
+
* say how much of the history fell off the front of the window. Rejecting the
|
|
918
|
+
* bare array would discard the history of every pull request mid-flight at
|
|
919
|
+
* the moment the new writer merged.
|
|
920
|
+
*/
|
|
921
|
+
export function readLedger(body: unknown): LedgerReading {
|
|
922
|
+
if (typeof body !== "string") return { status: AI_REVIEW_LEDGER_ABSENT };
|
|
923
|
+
const marker = body.indexOf(AI_REVIEW_LEDGER_COMMENT_MARKER);
|
|
924
|
+
if (marker === -1) return { status: AI_REVIEW_LEDGER_ABSENT };
|
|
925
|
+
|
|
926
|
+
const fence = body.indexOf("```json", marker);
|
|
927
|
+
if (fence === -1) {
|
|
928
|
+
return ledgerUnreadable(
|
|
929
|
+
"the ledger comment is present and holds no ```json block, so the rounds it " +
|
|
930
|
+
"recorded cannot be read; it is not being treated as an empty ledger",
|
|
931
|
+
);
|
|
932
|
+
}
|
|
933
|
+
const start = body.indexOf("\n", fence);
|
|
934
|
+
const close = start === -1 ? -1 : body.indexOf("\n```", start);
|
|
935
|
+
if (close === -1) {
|
|
936
|
+
return ledgerUnreadable(
|
|
937
|
+
"the ledger comment's ```json block is not closed, so it was truncated in " +
|
|
938
|
+
"transit or in storage and the rounds it recorded cannot be read",
|
|
939
|
+
);
|
|
940
|
+
}
|
|
941
|
+
|
|
942
|
+
let parsed: unknown;
|
|
943
|
+
try {
|
|
944
|
+
parsed = JSON.parse(body.slice(start + 1, close));
|
|
945
|
+
} catch (e) {
|
|
946
|
+
return ledgerUnreadable(
|
|
947
|
+
`the ledger comment's JSON block could not be parsed (${
|
|
948
|
+
e instanceof Error ? e.message : String(e)
|
|
949
|
+
}), so the rounds it recorded cannot be read`,
|
|
950
|
+
);
|
|
951
|
+
}
|
|
952
|
+
// Two shapes, and the older one is still on every open pull request that
|
|
953
|
+
// has a ledger. A bare array is the pre-#1405 ledger: readable, and silent
|
|
954
|
+
// about whether it is the whole history — but not therefore unknowable.
|
|
955
|
+
if (Array.isArray(parsed)) {
|
|
956
|
+
return {
|
|
957
|
+
status: AI_REVIEW_LEDGER_READ,
|
|
958
|
+
rounds: parsed.map(toLedgerRound),
|
|
959
|
+
truncation: legacyTruncation(parsed.length),
|
|
960
|
+
};
|
|
961
|
+
}
|
|
962
|
+
if (typeof parsed !== "object" || parsed === null) {
|
|
963
|
+
return ledgerUnreadable(
|
|
964
|
+
`the ledger comment's JSON block is ${describe(parsed)} rather than an array of ` +
|
|
965
|
+
"rounds, so the rounds it recorded cannot be read",
|
|
966
|
+
);
|
|
967
|
+
}
|
|
968
|
+
const obj = parsed as Record<string, unknown>;
|
|
969
|
+
const rounds = obj[AI_REVIEW_LEDGER_ROUNDS_KEY];
|
|
970
|
+
if (!Array.isArray(rounds)) {
|
|
971
|
+
return ledgerUnreadable(
|
|
972
|
+
`the ledger comment's JSON block is an object whose \`${AI_REVIEW_LEDGER_ROUNDS_KEY}\` ` +
|
|
973
|
+
`is ${describe(rounds)} rather than an array, so the rounds it recorded cannot be read`,
|
|
974
|
+
);
|
|
975
|
+
}
|
|
976
|
+
return {
|
|
977
|
+
status: AI_REVIEW_LEDGER_READ,
|
|
978
|
+
rounds: rounds.map(toLedgerRound),
|
|
979
|
+
truncation: readTruncation(obj[AI_REVIEW_LEDGER_TRUNCATED_KEY]),
|
|
980
|
+
};
|
|
981
|
+
}
|
|
982
|
+
|
|
983
|
+
/**
|
|
984
|
+
* How deep a legacy bare-array ledger is, derived from its length (#1447).
|
|
985
|
+
*
|
|
986
|
+
* The list grows by exactly one entry per round and is only ever cut when it
|
|
987
|
+
* reaches the cap, so **a length below the cap means the cut never ran** and
|
|
988
|
+
* the array is the whole history. That is a derivation from the writer's
|
|
989
|
+
* behaviour, not an assumption about it, and #1405's writer already makes the
|
|
990
|
+
* identical one when it migrates such a ledger forward — this is the reader
|
|
991
|
+
* catching up to it, for the ledgers no future round will ever touch.
|
|
992
|
+
*
|
|
993
|
+
* At or above the cap the length is a LOWER BOUND and nothing more: this
|
|
994
|
+
* round's eviction is knowable and the ones before it are not, and writing
|
|
995
|
+
* the bound as a count would hand a caller a number it cannot tell from a
|
|
996
|
+
* total.
|
|
997
|
+
*
|
|
998
|
+
* The cheap wrong fix is to call every bare array complete. It passes every
|
|
999
|
+
* case below the cap and is wrong at it, which is why
|
|
1000
|
+
* `test/ai-review-ledger-read.test.ts` puts 11 and 12 adjacent.
|
|
1001
|
+
*/
|
|
1002
|
+
function legacyTruncation(length: number): LedgerTruncation {
|
|
1003
|
+
if (length < AI_REVIEW_LEGACY_LEDGER_CAP) {
|
|
1004
|
+
return { status: AI_REVIEW_TRUNCATION_STATED, dropped: 0 };
|
|
1005
|
+
}
|
|
1006
|
+
return {
|
|
1007
|
+
status: AI_REVIEW_TRUNCATION_UNKNOWN,
|
|
1008
|
+
reason:
|
|
1009
|
+
`the ledger's JSON block is a bare array of ${length} rounds, the shape written ` +
|
|
1010
|
+
`before the \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` count existed, and it is at or past ` +
|
|
1011
|
+
`the ${AI_REVIEW_LEGACY_LEDGER_CAP}-round cap those ledgers were written under. A ` +
|
|
1012
|
+
`shorter one could be derived complete — the list only grows by one per round and is ` +
|
|
1013
|
+
`only cut at the cap — but at the cap its length is a lower bound on the rounds it ` +
|
|
1014
|
+
`held and says nothing about how many fell off the front`,
|
|
1015
|
+
};
|
|
1016
|
+
}
|
|
1017
|
+
|
|
1018
|
+
/**
|
|
1019
|
+
* Read the dropped-round count off a windowed ledger.
|
|
1020
|
+
*
|
|
1021
|
+
* A malformed count is UNKNOWN, never zero, and never a reason to refuse the
|
|
1022
|
+
* whole ledger: the rounds in hand are still real and still carryable. What
|
|
1023
|
+
* the caller must not be able to do is report the history as complete on the
|
|
1024
|
+
* strength of a field it could not read — which is exactly what a `?? 0`
|
|
1025
|
+
* here would let it do.
|
|
1026
|
+
*/
|
|
1027
|
+
function readTruncation(raw: unknown): LedgerTruncation {
|
|
1028
|
+
if (raw === undefined) {
|
|
1029
|
+
return {
|
|
1030
|
+
status: AI_REVIEW_TRUNCATION_UNKNOWN,
|
|
1031
|
+
reason:
|
|
1032
|
+
`the ledger is an object and carries no \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` key, so ` +
|
|
1033
|
+
"it states nothing about rounds dropped off the front",
|
|
1034
|
+
};
|
|
1035
|
+
}
|
|
1036
|
+
if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
|
|
1037
|
+
return {
|
|
1038
|
+
status: AI_REVIEW_TRUNCATION_UNKNOWN,
|
|
1039
|
+
reason:
|
|
1040
|
+
`the ledger's \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` is ${describe(raw)} rather than a ` +
|
|
1041
|
+
"non-negative integer, so how many rounds it dropped cannot be established",
|
|
1042
|
+
};
|
|
1043
|
+
}
|
|
1044
|
+
return { status: AI_REVIEW_TRUNCATION_STATED, dropped: raw };
|
|
1045
|
+
}
|
|
1046
|
+
|
|
1047
|
+
function toLedgerRound(raw: unknown): LedgerRound {
|
|
1048
|
+
// An entry that is not an object is a round that was recorded and cannot be
|
|
1049
|
+
// read. It is counted, not skipped: a round that vanishes from the count
|
|
1050
|
+
// makes a three-round pull request look like a two-round one.
|
|
1051
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
1052
|
+
// An unreadable entry has not stated a turn count, and it has not failed
|
|
1053
|
+
// to read one either — nobody got as far as asking. NOT_RECORDED, which
|
|
1054
|
+
// is also what every pre-#1380 round reads as.
|
|
1055
|
+
return {
|
|
1056
|
+
round: null,
|
|
1057
|
+
sha: "",
|
|
1058
|
+
mergeSha: "",
|
|
1059
|
+
turns: { status: AI_REVIEW_TURNS_NOT_RECORDED },
|
|
1060
|
+
// Nobody got as far as asking, which is NOT_RECORDED for the same
|
|
1061
|
+
// reason the turn count above is: an entry that is not an object has
|
|
1062
|
+
// not stated a verdict and has not failed to state one.
|
|
1063
|
+
verdict: { status: AI_REVIEW_VERDICT_NOT_RECORDED },
|
|
1064
|
+
measured: false,
|
|
1065
|
+
keyable: false,
|
|
1066
|
+
findings: [],
|
|
1067
|
+
};
|
|
1068
|
+
}
|
|
1069
|
+
const e = raw as Record<string, unknown>;
|
|
1070
|
+
const list = e[AI_REVIEW_LEDGER_FINDINGS_KEY];
|
|
1071
|
+
const measured = Array.isArray(list);
|
|
1072
|
+
return {
|
|
1073
|
+
round: readRoundNumber(e.round),
|
|
1074
|
+
sha: typeof e.sha === "string" ? e.sha : "",
|
|
1075
|
+
mergeSha:
|
|
1076
|
+
typeof e[AI_REVIEW_LEDGER_MERGE_KEY] === "string"
|
|
1077
|
+
? (e[AI_REVIEW_LEDGER_MERGE_KEY] as string)
|
|
1078
|
+
: "",
|
|
1079
|
+
turns: readRoundTurns(e[AI_REVIEW_LEDGER_TURNS_KEY]),
|
|
1080
|
+
verdict: readRoundVerdict(e[AI_REVIEW_LEDGER_VERDICT_KEY]),
|
|
1081
|
+
measured,
|
|
1082
|
+
keyable: e.identity === AI_REVIEW_LEDGER_IDENTITY,
|
|
1083
|
+
findings: measured
|
|
1084
|
+
? (list as unknown[]).filter(
|
|
1085
|
+
(f): f is ReviewFinding => typeof f === "object" && f !== null && !Array.isArray(f),
|
|
1086
|
+
)
|
|
1087
|
+
: [],
|
|
1088
|
+
};
|
|
1089
|
+
}
|
|
1090
|
+
|
|
1091
|
+
/** The prior state could not be established at all. */
|
|
1092
|
+
export const AI_REVIEW_PRIOR_UNMEASURED = "AI_REVIEW_PRIOR_UNMEASURED";
|
|
1093
|
+
|
|
1094
|
+
/** The prior state was established — possibly as nothing. */
|
|
1095
|
+
export const AI_REVIEW_PRIOR_MEASURED = "AI_REVIEW_PRIOR_MEASURED";
|
|
1096
|
+
|
|
1097
|
+
export interface PriorFinding {
|
|
1098
|
+
finding: ReviewFinding;
|
|
1099
|
+
/**
|
|
1100
|
+
* The text at the cited line when the finding was raised. Absent when the
|
|
1101
|
+
* ledger did not record one — and absent is UNDECIDABLE in `carryForward`,
|
|
1102
|
+
* not resolved.
|
|
1103
|
+
*/
|
|
1104
|
+
recordedText?: string;
|
|
1105
|
+
/** Which rule formed this finding's key. Stated, so a caller can weigh it. */
|
|
1106
|
+
identity: FindingIdentity;
|
|
1107
|
+
/** The key, or null when no identity could be formed. */
|
|
1108
|
+
key: string | null;
|
|
1109
|
+
/** The round it was raised on, where the ledger recorded one. */
|
|
1110
|
+
round: number | null;
|
|
1111
|
+
}
|
|
1112
|
+
|
|
1113
|
+
export type PriorState =
|
|
1114
|
+
| { status: typeof AI_REVIEW_PRIOR_UNMEASURED; reason: string }
|
|
1115
|
+
| {
|
|
1116
|
+
status: typeof AI_REVIEW_PRIOR_MEASURED;
|
|
1117
|
+
/** Keys earlier rounds raised, for `suppressRepeats`. */
|
|
1118
|
+
keys: string[];
|
|
1119
|
+
/** Everything earlier rounds raised, for `carryForward`. */
|
|
1120
|
+
prior: PriorFinding[];
|
|
1121
|
+
/** Rounds recorded whose findings were never read. */
|
|
1122
|
+
unmeasuredRounds: number;
|
|
1123
|
+
/** Rounds read under an identity rule this reader does not know. */
|
|
1124
|
+
unkeyableRounds: number;
|
|
1125
|
+
};
|
|
1126
|
+
|
|
1127
|
+
/**
|
|
1128
|
+
* Turn a ledger reading into what `suppressRepeats` and `carryForward` take.
|
|
1129
|
+
*
|
|
1130
|
+
* `PriorFinding` is assignable to `CarriedFinding`, so `prior` goes straight
|
|
1131
|
+
* into `carryForward` with no adapter between them — that join is the point
|
|
1132
|
+
* of the shape.
|
|
1133
|
+
*
|
|
1134
|
+
* **An UNREADABLE ledger returns a state with no `keys` and no `prior`.** Not
|
|
1135
|
+
* empty ones: absent ones. A caller holding an unmeasured state cannot
|
|
1136
|
+
* suppress a finding or resolve one, and the type stops it reaching for the
|
|
1137
|
+
* fields that would let it, instead of trusting it to check a boolean nobody
|
|
1138
|
+
* has to read.
|
|
1139
|
+
*/
|
|
1140
|
+
export function priorFindings(reading: LedgerReading): PriorState {
|
|
1141
|
+
if (reading.status === AI_REVIEW_LEDGER_UNREADABLE) {
|
|
1142
|
+
return { status: AI_REVIEW_PRIOR_UNMEASURED, reason: reading.reason };
|
|
1143
|
+
}
|
|
1144
|
+
if (reading.status === AI_REVIEW_LEDGER_ABSENT) {
|
|
1145
|
+
return {
|
|
1146
|
+
status: AI_REVIEW_PRIOR_MEASURED,
|
|
1147
|
+
keys: [],
|
|
1148
|
+
prior: [],
|
|
1149
|
+
unmeasuredRounds: 0,
|
|
1150
|
+
unkeyableRounds: 0,
|
|
1151
|
+
};
|
|
1152
|
+
}
|
|
1153
|
+
|
|
1154
|
+
const keys: string[] = [];
|
|
1155
|
+
const prior: PriorFinding[] = [];
|
|
1156
|
+
let unmeasuredRounds = 0;
|
|
1157
|
+
let unkeyableRounds = 0;
|
|
1158
|
+
|
|
1159
|
+
for (const round of reading.rounds) {
|
|
1160
|
+
if (!round.measured) {
|
|
1161
|
+
unmeasuredRounds++;
|
|
1162
|
+
continue;
|
|
1163
|
+
}
|
|
1164
|
+
if (!round.keyable) unkeyableRounds++;
|
|
1165
|
+
for (const finding of round.findings) {
|
|
1166
|
+
const recorded = finding[AI_REVIEW_LEDGER_FINDING_TEXT];
|
|
1167
|
+
const recordedText = typeof recorded === "string" ? recorded : undefined;
|
|
1168
|
+
let identity: FindingIdentity = FINDING_IDENTITY_NONE;
|
|
1169
|
+
let key: string | null = null;
|
|
1170
|
+
// Only a round stamped with the rule this reader knows gets a key. An
|
|
1171
|
+
// unrecognised rule is carried, never dropped, and never keyed.
|
|
1172
|
+
if (round.keyable) {
|
|
1173
|
+
key = carryKey(finding, recordedText);
|
|
1174
|
+
if (key !== null) {
|
|
1175
|
+
identity = normalise(recordedText) !== "" ? FINDING_IDENTITY_TEXT : FINDING_IDENTITY_LINE;
|
|
1176
|
+
keys.push(key);
|
|
1177
|
+
}
|
|
1178
|
+
}
|
|
1179
|
+
prior.push({ finding, recordedText, identity, key, round: round.round });
|
|
1180
|
+
}
|
|
1181
|
+
}
|
|
1182
|
+
|
|
1183
|
+
return { status: AI_REVIEW_PRIOR_MEASURED, keys, prior, unmeasuredRounds, unkeyableRounds };
|
|
1184
|
+
}
|
|
1185
|
+
|
|
1186
|
+
/**
|
|
1187
|
+
* What the reviewer is told once the budget is spent.
|
|
1188
|
+
*
|
|
1189
|
+
* **A cap is not a silencer.** A reviewer that goes quiet at round 4 has
|
|
1190
|
+
* handed the author a green check on a pull request three reviews have failed
|
|
1191
|
+
* to settle, which is the outcome the cap exists to prevent, not the one it
|
|
1192
|
+
* is for. So the reviewer still runs and still writes a payload; what changes
|
|
1193
|
+
* is the question it is answering.
|
|
1194
|
+
*
|
|
1195
|
+
* Emitted at a NON-blocking severity by contract — the text says so — because
|
|
1196
|
+
* "this approach is not converging" is not a defect at a line and the payload
|
|
1197
|
+
* contract refuses a blocking finding that cannot name one. The round that
|
|
1198
|
+
* blocks is the one that found the bug; this one is advice.
|
|
1199
|
+
*/
|
|
1200
|
+
export function atCapInstruction(round: number, cap: number = AI_REVIEW_ROUND_CAP): string {
|
|
1201
|
+
return (
|
|
1202
|
+
`THIS IS REVIEW ROUND ${round}. This pull request has already had ${cap} rounds of ` +
|
|
1203
|
+
`review and has not settled, so do not spend this round listing more defects.\n` +
|
|
1204
|
+
`\n` +
|
|
1205
|
+
`Step back and say something about the APPROACH instead. Three rounds that each ` +
|
|
1206
|
+
`found something is evidence about the change, not about the reviewer: the usual ` +
|
|
1207
|
+
`causes are a change that is doing more than one thing, a defect class being fixed ` +
|
|
1208
|
+
`one line at a time, or a design that makes the defect easy to reintroduce. Say ` +
|
|
1209
|
+
`which of those you think this is and what you would do instead.\n` +
|
|
1210
|
+
`\n` +
|
|
1211
|
+
`Write ONE finding, at a non-blocking severity, whose summary is that assessment. ` +
|
|
1212
|
+
`Do not raise it to a blocking severity: the budget being spent is not itself a ` +
|
|
1213
|
+
`defect at a line, and a blocking finding that cannot name one makes the whole ` +
|
|
1214
|
+
`review unreadable. Stay silent and the author gets a green check on a pull ` +
|
|
1215
|
+
`request three reviews could not settle, which is worse than either.`
|
|
1216
|
+
);
|
|
1217
|
+
}
|
|
1218
|
+
|
|
1219
|
+
/**
|
|
1220
|
+
* The block appended to the prompt listing what has already been said.
|
|
1221
|
+
*
|
|
1222
|
+
* Handed to the reviewer as well as enforced by the adjudicator, and both on
|
|
1223
|
+
* purpose: the instruction saves the round, and the adjudicator makes the
|
|
1224
|
+
* saving checkable. An instruction nobody enforces is a request.
|
|
1225
|
+
*/
|
|
1226
|
+
export function noRepeatsInstruction(priorSummaries: readonly string[]): string {
|
|
1227
|
+
if (priorSummaries.length === 0) return "";
|
|
1228
|
+
const list = priorSummaries.map(s => ` - ${s}`).join("\n");
|
|
1229
|
+
return (
|
|
1230
|
+
`ALREADY RAISED ON AN EARLIER ROUND OF THIS PULL REQUEST. Do not report any of ` +
|
|
1231
|
+
`these again, at any severity, however you would word it:\n` +
|
|
1232
|
+
`${list}\n` +
|
|
1233
|
+
`\n` +
|
|
1234
|
+
`A later step drops a finding that matches one of these on the file, the text of ` +
|
|
1235
|
+
`the cited line and the summary — it does NOT match on the line number, so moving ` +
|
|
1236
|
+
`the same defect to a new line does not make it a new finding. Report what is new ` +
|
|
1237
|
+
`on this round, or report nothing.`
|
|
1238
|
+
);
|
|
1239
|
+
}
|
|
1240
|
+
|
|
1241
|
+
function describe(v: unknown): string {
|
|
1242
|
+
if (v === undefined) return "nothing";
|
|
1243
|
+
if (v === null) return "null";
|
|
1244
|
+
if (Array.isArray(v)) return `an array of ${v.length}`;
|
|
1245
|
+
if (typeof v === "object") return "an object";
|
|
1246
|
+
return JSON.stringify(v);
|
|
1247
|
+
}
|
|
1248
|
+
|
|
1249
|
+
export { SECURITY_REREVIEW_EXHAUSTED };
|