rungate 0.8.7 → 0.8.10
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/hooks/StaleTTLCleanup.hook.ts +13 -5
- package/hooks/VerifyPhaseLock.hook.ts +8 -0
- package/hooks/lib/findWorkflow.ts +19 -3
- package/lib/active-workflow.ts +57 -0
- package/lib/ai-review-rounds.ts +223 -10
- package/lib/ai-review-suppression.ts +80 -127
- package/lib/ai-review-threads.ts +182 -6
- package/lib/board-mirror.ts +438 -0
- package/lib/cli-commands.ts +133 -0
- package/lib/config-readers.ts +34 -0
- package/lib/crc-reading.ts +655 -0
- package/lib/criterion-issue-census.ts +325 -0
- package/lib/filing-plan.ts +381 -0
- package/lib/generators/agents-md.ts +15 -11
- package/lib/git-isolation.ts +32 -0
- package/lib/github.ts +66 -0
- package/lib/issue-decomposition.ts +523 -0
- package/lib/issue-filing-gate.ts +304 -19
- package/lib/issue-repair.ts +225 -0
- package/lib/live-issues.ts +442 -0
- package/lib/project-state-shape.ts +30 -0
- package/lib/prose-self-distance.ts +414 -0
- package/lib/review-tool-agreement.ts +364 -15
- package/lib/sc-ids.ts +31 -1
- package/lib/scaffold/ai-review-findings.ts +64 -3
- package/lib/scaffold/ai-review-step.ts +501 -82
- package/lib/scaffold/owned-files.ts +60 -2
- package/lib/scaffold/steps.ts +130 -4
- package/lib/spec-deps.ts +257 -0
- package/lib/spec-evidence.ts +479 -0
- package/lib/spec-placement.ts +430 -0
- package/lib/spec-template.ts +206 -0
- package/lib/stage-ladder.ts +628 -0
- package/lib/worktree-cleanup.ts +438 -3
- package/package.json +12 -4
- package/scripts/ai-review-findings.ts +12 -17
- package/scripts/ai-review-threads.ts +51 -3
- package/scripts/audit-spec-evidence.ts +246 -0
- package/scripts/audit-specs.ts +27 -0
- package/scripts/board-conformance.ts +765 -0
- package/scripts/board-mirror.ts +344 -0
- package/scripts/board-snapshot.ts +459 -0
- package/scripts/create-spec.ts +8 -34
- package/scripts/criterion-inventory.ts +649 -0
- package/scripts/extract-constraints.ts +108 -9
- package/scripts/plan-deps.ts +378 -0
- package/scripts/plan-issues.ts +701 -0
- package/scripts/plan-spec.ts +371 -0
|
@@ -0,0 +1,655 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CRC-M11's convergence reading, as a program rather than a shell recipe.
|
|
3
|
+
*
|
|
4
|
+
* Covers CRC-M11 (specs/CODE-REVIEW-CONVERGENCE-SPEC.md). The spec's
|
|
5
|
+
* measurement section was four hand-run commands and a hand-typed table, and
|
|
6
|
+
* the reviewer named that as the structural cause three rounds running on
|
|
7
|
+
* #1632. This module is the reading those commands were approximating; the
|
|
8
|
+
* table in the spec is rendered from a stored row rather than retyped.
|
|
9
|
+
*
|
|
10
|
+
* ## What the jq recipe could not do, and why that is the reason this exists
|
|
11
|
+
*
|
|
12
|
+
* **Per-pull-request refusal.** `jq` walks a list with one filter: a ledger
|
|
13
|
+
* whose JSON is truncated, or whose object has no `rounds` key, aborts the
|
|
14
|
+
* whole pipeline and **the entire range is lost**, not the one pull request.
|
|
15
|
+
* That is the same *Silent Default Substitution* shape the rest of this
|
|
16
|
+
* measurement is careful about, arriving as a stack trace instead of a
|
|
17
|
+
* number. Here a bad ledger is one `UNMEASURED LEDGER_UNREADABLE` line and
|
|
18
|
+
* the other forty-five still score.
|
|
19
|
+
*
|
|
20
|
+
* **A fence rule that survives its own payload.** The recipe cut the ledger
|
|
21
|
+
* with `split("```json")[1] | split("```")[0]`. On 2026-10-27 that cut a
|
|
22
|
+
* 27,252-character ledger at 18,021 characters, and the text at the cut was a
|
|
23
|
+
* reviewer quoting the recipe itself into a finding. **The recipe cut itself
|
|
24
|
+
* in half on any pull request whose review quoted it.** `ledgerRawRounds` and
|
|
25
|
+
* `readLedger` use `indexOf`, which does not.
|
|
26
|
+
*
|
|
27
|
+
* ## Two columns, and they answer different questions
|
|
28
|
+
*
|
|
29
|
+
* ALL-ROUNDS counts every round the ledger recorded, whether or not a review
|
|
30
|
+
* came out of it. MEASURED-ONLY counts only rounds whose `findings` is an
|
|
31
|
+
* array. The gap between them is the share of rounds in which no review
|
|
32
|
+
* happened, which on the readings so far is the larger half of the problem.
|
|
33
|
+
*
|
|
34
|
+
* **`findings != null` is the predicate, never `unmeasured == null`.** A
|
|
35
|
+
* ledger round is written twice: `lib/scaffold/ai-review-step.ts` emits it
|
|
36
|
+
* with no `unmeasured` key at all, and `lib/ai-review-unmeasured.ts` adds one
|
|
37
|
+
* in a second pass. So `unmeasured == null` asks whether the second pass ran,
|
|
38
|
+
* and a round the recorder never reached would score as measured.
|
|
39
|
+
*
|
|
40
|
+
* ## Both columns use the same denominators, and that is a change
|
|
41
|
+
*
|
|
42
|
+
* `lib/rounds-to-pass.ts` puts the mean and the one-round rate over the pull
|
|
43
|
+
* requests that PASSED, and the five-or-more tail over ALL measured ones,
|
|
44
|
+
* because *"a tail measured on survivors only has had its tail cut off"*. The
|
|
45
|
+
* hand-run measured-only column put all three over merged pull requests. This
|
|
46
|
+
* module applies the `rounds-to-pass` convention to both columns, so the
|
|
47
|
+
* measured-only tail now carries still-open pull requests that have at least
|
|
48
|
+
* one measured round. That moves the published 2026-10-27 figure and the
|
|
49
|
+
* numerators are printed so a reader can see which way.
|
|
50
|
+
*/
|
|
51
|
+
|
|
52
|
+
import {
|
|
53
|
+
AI_REVIEW_LEDGER_READ,
|
|
54
|
+
AI_REVIEW_TRUNCATION_STATED,
|
|
55
|
+
ledgerRawRounds,
|
|
56
|
+
readLedger,
|
|
57
|
+
type LedgerTruncation,
|
|
58
|
+
} from "./ai-review-rounds";
|
|
59
|
+
import {
|
|
60
|
+
AI_REVIEW_UNMEASURED_NOT_RECORDED,
|
|
61
|
+
readRecordedUnmeasuredState,
|
|
62
|
+
} from "./ai-review-unmeasured";
|
|
63
|
+
import { LONG_REVIEW_ROUNDS, roundsTaken } from "./rounds-to-pass";
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* One pull request as the fetch produced it.
|
|
67
|
+
*
|
|
68
|
+
* `truncated` is the comment page's own statement that it did not carry every
|
|
69
|
+
* comment — it is a property of the FETCH and nothing downstream can
|
|
70
|
+
* reconstruct it, which is why it rides along rather than being inferred.
|
|
71
|
+
*/
|
|
72
|
+
export interface CrcEntry {
|
|
73
|
+
readonly number: number;
|
|
74
|
+
/** Merged. Named `passed` because `rounds-to-pass` is deliberately agnostic. */
|
|
75
|
+
readonly passed: boolean;
|
|
76
|
+
readonly truncated: boolean;
|
|
77
|
+
readonly body: string | null;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** A fetched page that cannot answer whether a ledger exists. */
|
|
81
|
+
export const CRC_PREMISE_UNRESOLVABLE_ABSENCE = "UNRESOLVABLE_ABSENCE";
|
|
82
|
+
|
|
83
|
+
/** The page did not reach both ends of the range that was asked for. */
|
|
84
|
+
export const CRC_PREMISE_RANGE_NOT_COVERED = "RANGE_NOT_COVERED";
|
|
85
|
+
|
|
86
|
+
/** An entry is outside `[lo, hi]`, so the cohort is not the one named. */
|
|
87
|
+
export const CRC_PREMISE_OUT_OF_RANGE = "ENTRY_OUT_OF_RANGE";
|
|
88
|
+
|
|
89
|
+
/** The same pull request appears twice, which doubles its weight. */
|
|
90
|
+
export const CRC_PREMISE_DUPLICATE = "DUPLICATE_ENTRY";
|
|
91
|
+
|
|
92
|
+
export interface PremiseViolation {
|
|
93
|
+
readonly kind:
|
|
94
|
+
| typeof CRC_PREMISE_UNRESOLVABLE_ABSENCE
|
|
95
|
+
| typeof CRC_PREMISE_RANGE_NOT_COVERED
|
|
96
|
+
| typeof CRC_PREMISE_OUT_OF_RANGE
|
|
97
|
+
| typeof CRC_PREMISE_DUPLICATE;
|
|
98
|
+
readonly detail: string;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* THE SINGLE DECISION SITE for whether the fetched page can be scored at all.
|
|
103
|
+
*
|
|
104
|
+
* Both guards are about the FETCH, not the ledgers, and neither can be
|
|
105
|
+
* recovered downstream — which is why they refuse rather than warn.
|
|
106
|
+
*
|
|
107
|
+
* The first is narrow on purpose. The ledger is one upserted comment, so its
|
|
108
|
+
* position in a creation-ordered connection is fixed when round 1 writes it
|
|
109
|
+
* and no later volume pushes it past the hundredth. A full page WITH a ledger
|
|
110
|
+
* is therefore fine, and a short page with no ledger is a real absence. The
|
|
111
|
+
* only unresolvable reading is a full page with no ledger found, where absent
|
|
112
|
+
* and not-fetched are the same bytes.
|
|
113
|
+
*
|
|
114
|
+
* The second catches an under-sized `first:N`, which silently returns a
|
|
115
|
+
* PREFIX of the range and whose figures are internally consistent and about
|
|
116
|
+
* the wrong cohort. An empty list fails it too: there is no `min` to equal
|
|
117
|
+
* `lo`, and a reading over nothing must not pass a range check.
|
|
118
|
+
*
|
|
119
|
+
* **The third and fourth exist because a min and a max do not describe a
|
|
120
|
+
* set.** #1633 round 3: `fetchEntries` filters to `[lo, hi]` and the
|
|
121
|
+
* `--from` loader does not, so a stale or hand-edited entries file reaches
|
|
122
|
+
* the scorer unfiltered and inflates the pull-request count, the round
|
|
123
|
+
* total and both columns' denominators — which `--record --write-spec` then
|
|
124
|
+
* lands in the store and in the spec.
|
|
125
|
+
*
|
|
126
|
+
* **They are not equally severe and the difference is worth stating.** An
|
|
127
|
+
* out-of-range number cannot evade the min/max check; it necessarily moves
|
|
128
|
+
* one of them. What it could do was arrive MISDIAGNOSED, because the only
|
|
129
|
+
* message said the page spans the wrong thing and told the reader to *raise
|
|
130
|
+
* the page size* — the opposite of the fix, for a file carrying too many
|
|
131
|
+
* rows. A **duplicate** is the one that was genuinely invisible: it changes
|
|
132
|
+
* neither min nor max, and it weights one pull request twice in the round
|
|
133
|
+
* total and in both columns.
|
|
134
|
+
*
|
|
135
|
+
* Both are checked HERE rather than fixed in the loader, deliberately.
|
|
136
|
+
* Filtering the file down to `[lo, hi]` would silently trim a stale input,
|
|
137
|
+
* which is the same class of problem one layer along: a file that disagrees
|
|
138
|
+
* with the range it was handed is a file nobody should score.
|
|
139
|
+
*/
|
|
140
|
+
export function premiseViolations(
|
|
141
|
+
entries: readonly CrcEntry[],
|
|
142
|
+
lo: number,
|
|
143
|
+
hi: number,
|
|
144
|
+
): PremiseViolation[] {
|
|
145
|
+
const out: PremiseViolation[] = [];
|
|
146
|
+
|
|
147
|
+
const unresolvable = entries.filter(e => e.body === null && e.truncated).map(e => e.number);
|
|
148
|
+
if (unresolvable.length > 0) {
|
|
149
|
+
out.push({
|
|
150
|
+
kind: CRC_PREMISE_UNRESOLVABLE_ABSENCE,
|
|
151
|
+
detail:
|
|
152
|
+
`${unresolvable.length} pull request(s) returned a FULL comment page and no ledger: ` +
|
|
153
|
+
`${unresolvable.map(n => `#${n}`).join(", ")}. On those, "no ledger" and "the page ` +
|
|
154
|
+
`did not reach it" are the same bytes, so the absence cannot be scored either way.`,
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
const numbers = entries.map(e => e.number);
|
|
159
|
+
const min = numbers.length === 0 ? null : Math.min(...numbers);
|
|
160
|
+
const max = numbers.length === 0 ? null : Math.max(...numbers);
|
|
161
|
+
if (min !== lo || max !== hi) {
|
|
162
|
+
out.push({
|
|
163
|
+
kind: CRC_PREMISE_RANGE_NOT_COVERED,
|
|
164
|
+
detail:
|
|
165
|
+
`the fetched page spans ${min === null ? "nothing" : `#${min}–#${max}`} and the range ` +
|
|
166
|
+
`asked for is #${lo}–#${hi}. An under-sized page returns a PREFIX of the range, whose ` +
|
|
167
|
+
`figures are internally consistent and about a different cohort — raise the page size.`,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
const outside = numbers.filter(n => n < lo || n > hi);
|
|
172
|
+
if (outside.length > 0) {
|
|
173
|
+
out.push({
|
|
174
|
+
kind: CRC_PREMISE_OUT_OF_RANGE,
|
|
175
|
+
detail:
|
|
176
|
+
`${outside.length} pull request(s) fall outside #${lo}–#${hi}: ` +
|
|
177
|
+
`${outside.map(n => `#${n}`).join(", ")}. A min and a max that line up do not make the ` +
|
|
178
|
+
`set the range it is labelled with, and every one of these inflates a denominator.`,
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
const seen = new Set<number>();
|
|
183
|
+
const duplicates = [...new Set(numbers.filter(n => (seen.has(n) ? true : (seen.add(n), false))))];
|
|
184
|
+
if (duplicates.length > 0) {
|
|
185
|
+
out.push({
|
|
186
|
+
kind: CRC_PREMISE_DUPLICATE,
|
|
187
|
+
detail:
|
|
188
|
+
`${duplicates.length} pull request(s) appear more than once: ` +
|
|
189
|
+
`${duplicates.map(n => `#${n}`).join(", ")}. A repeated entry is counted twice in the ` +
|
|
190
|
+
`round total and in both columns, which is a weighting nobody chose.`,
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
return out;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Why one pull request could not be scored in a column. */
|
|
197
|
+
export interface CrcRefusal {
|
|
198
|
+
readonly number: number;
|
|
199
|
+
readonly refusal: string;
|
|
200
|
+
readonly detail: string;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** One pull request's round count in one column, or its refusal. */
|
|
204
|
+
export type CrcRoundCount = { readonly rounds: number } | CrcRefusal;
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* How many rounds this pull request had, counting every round.
|
|
208
|
+
*
|
|
209
|
+
* Delegates to `roundsTaken`, which is `lib/rounds-to-pass.ts`'s own single
|
|
210
|
+
* decision site, so the truncation refusal and the `rounds.length + dropped`
|
|
211
|
+
* arithmetic are not restated here. A second copy of that rule is a second
|
|
212
|
+
* decider that would drift, and the drift direction is flattering.
|
|
213
|
+
*/
|
|
214
|
+
export function allRoundsFor(entry: CrcEntry): CrcRoundCount {
|
|
215
|
+
const taken = roundsTaken({
|
|
216
|
+
number: entry.number,
|
|
217
|
+
passed: entry.passed,
|
|
218
|
+
ledger: readLedger(entry.body),
|
|
219
|
+
});
|
|
220
|
+
if ("refusal" in taken) {
|
|
221
|
+
return { number: entry.number, refusal: taken.refusal, detail: taken.detail };
|
|
222
|
+
}
|
|
223
|
+
return taken;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* The ONLY refusal the measured-only column is allowed to score through.
|
|
228
|
+
*
|
|
229
|
+
* Every other refusal `roundsTaken` can make is a fact about the ledger —
|
|
230
|
+
* absent, unreadable, an eviction count that is not a number, no rounds at
|
|
231
|
+
* all — and a fact about the ledger is true in both columns or neither. This
|
|
232
|
+
* set is the closed statement of where the two columns may disagree, in one
|
|
233
|
+
* direction; `ZERO_MEASURED_ROUNDS` is the disagreement in the other, and
|
|
234
|
+
* there is no third. `test/crc-reading.test.ts` runs the pair over every
|
|
235
|
+
* ledger shape in this file and fails on any divergence not named here, so a
|
|
236
|
+
* refusal added to `rounds-to-pass.ts` later cannot quietly join this set.
|
|
237
|
+
*/
|
|
238
|
+
const MEASURED_ONLY_SCORES_ANYWAY: ReadonlySet<string> = new Set(["ROUNDS_TRUNCATION_UNKNOWN"]);
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* How many of this pull request's rounds produced a review.
|
|
242
|
+
*
|
|
243
|
+
* A pull request whose every round was refused by the review system has no
|
|
244
|
+
* rounds-to-pass in this column and is UNMEASURED, not zero. That single
|
|
245
|
+
* decision is worth thirteen points: the first published measured-only column
|
|
246
|
+
* scored twelve never-reviewed pull requests as one-round passes and reported
|
|
247
|
+
* 62.8% where the refusing rule reports 48.4%.
|
|
248
|
+
*
|
|
249
|
+
* Truncation is NOT refused here and the difference from `allRoundsFor` is
|
|
250
|
+
* deliberate. An evicted round's kind is unrecoverable — it may have been
|
|
251
|
+
* measured or not — so a ledger that evicted rounds yields a **lower bound**
|
|
252
|
+
* on its measured count. Refusing it would drop the longest histories, which
|
|
253
|
+
* is the direction this metric is already biased in; the bound is reported
|
|
254
|
+
* instead.
|
|
255
|
+
*
|
|
256
|
+
* **The reading is returned whole, as `LedgerTruncation`, not flattened to a
|
|
257
|
+
* number.** #1633 round 2: it used to return `evicted: 0` for both a ledger
|
|
258
|
+
* STATING zero evictions and a legacy bare-array ledger whose eviction count
|
|
259
|
+
* is unknowable — and the module's own test demonstrated it, with
|
|
260
|
+
* `allRoundsFor` refusing that input as `ROUNDS_TRUNCATION_UNKNOWN` while
|
|
261
|
+
* this one answered `evicted: 0` on the same bytes. A range of open pull
|
|
262
|
+
* requests on the legacy format would then have suppressed the LOWER BOUND
|
|
263
|
+
* banner entirely. `LedgerTruncation` has no number to reach for without
|
|
264
|
+
* narrowing the status first, which is why it is that type upstream.
|
|
265
|
+
*/
|
|
266
|
+
export function measuredRoundsFor(
|
|
267
|
+
entry: CrcEntry,
|
|
268
|
+
): ({ readonly rounds: number; readonly truncation: LedgerTruncation } | CrcRefusal) {
|
|
269
|
+
const reading = readLedger(entry.body);
|
|
270
|
+
|
|
271
|
+
// Both columns ask `roundsTaken` FIRST, so every refusal that is a fact
|
|
272
|
+
// about the LEDGER — absent, unreadable, no rounds at all — is decided in
|
|
273
|
+
// one place and the two columns cannot disagree about it. Only
|
|
274
|
+
// `MEASURED_ONLY_SCORES_ANYWAY` is allowed to differ, and it is listed
|
|
275
|
+
// rather than implied. #1633 round 4 found the divergence this closes: an
|
|
276
|
+
// empty ledger was ROUNDS_EMPTY through `allRoundsFor` and
|
|
277
|
+
// ZERO_MEASURED_ROUNDS here, so a pull request the reviewer never ran on
|
|
278
|
+
// was listed beside ones it ran on and produced nothing — and a ledger
|
|
279
|
+
// whose eviction count is not a number reached the eviction SUM.
|
|
280
|
+
const taken = roundsTaken({ number: entry.number, passed: entry.passed, ledger: reading });
|
|
281
|
+
if ("refusal" in taken && !MEASURED_ONLY_SCORES_ANYWAY.has(taken.refusal)) {
|
|
282
|
+
return { number: entry.number, refusal: taken.refusal, detail: taken.detail };
|
|
283
|
+
}
|
|
284
|
+
if (reading.status !== AI_REVIEW_LEDGER_READ) {
|
|
285
|
+
/* c8 ignore next 2 — unreachable: a non-READ reading always refuses above. */
|
|
286
|
+
return { number: entry.number, refusal: "LEDGER_UNREADABLE", detail: "unreachable" };
|
|
287
|
+
}
|
|
288
|
+
const measured = reading.rounds.filter(r => r.measured).length;
|
|
289
|
+
if (measured === 0) {
|
|
290
|
+
return {
|
|
291
|
+
number: entry.number,
|
|
292
|
+
refusal: "ZERO_MEASURED_ROUNDS",
|
|
293
|
+
detail:
|
|
294
|
+
`${reading.rounds.length} round(s) recorded and not one produced a review. A pull ` +
|
|
295
|
+
`request the reviewer never read once has no rounds-to-pass; scoring it as a ` +
|
|
296
|
+
`one-round pass is the most favourable thing this reading could say about a pull ` +
|
|
297
|
+
`request the review system refused.`,
|
|
298
|
+
};
|
|
299
|
+
}
|
|
300
|
+
return { rounds: measured, truncation: reading.truncation };
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/** One scored column — the three figures, each with its own numerator. */
|
|
304
|
+
export interface CrcColumn {
|
|
305
|
+
/** Pull requests that scored, passed or not. The tail's denominator. */
|
|
306
|
+
readonly measured: number;
|
|
307
|
+
/** Of those, the ones that passed. The mean's and one-round's denominator. */
|
|
308
|
+
readonly passed: number;
|
|
309
|
+
/** Rounds spent by the ones that passed. The mean's numerator. */
|
|
310
|
+
readonly passedRounds: number;
|
|
311
|
+
readonly mean: number | null;
|
|
312
|
+
readonly oneRound: number | null;
|
|
313
|
+
readonly fiveOrMore: number | null;
|
|
314
|
+
readonly refusals: readonly CrcRefusal[];
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
interface Scored {
|
|
318
|
+
readonly passed: boolean;
|
|
319
|
+
readonly rounds: number;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* The three figures over one column's scored pull requests.
|
|
324
|
+
*
|
|
325
|
+
* Null, never zero, when there is nothing to average. A mean of nothing is
|
|
326
|
+
* not 0 and a rate over nothing is not 0%, and both of those read as perfect
|
|
327
|
+
* on the table this feeds.
|
|
328
|
+
*/
|
|
329
|
+
export function scoreColumn(scored: readonly Scored[], refusals: readonly CrcRefusal[]): CrcColumn {
|
|
330
|
+
const passed = scored.filter(s => s.passed);
|
|
331
|
+
const passedRounds = passed.reduce((a, s) => a + s.rounds, 0);
|
|
332
|
+
return {
|
|
333
|
+
measured: scored.length,
|
|
334
|
+
passed: passed.length,
|
|
335
|
+
passedRounds,
|
|
336
|
+
mean: passed.length === 0 ? null : passedRounds / passed.length,
|
|
337
|
+
oneRound: passed.length === 0 ? null : passed.filter(s => s.rounds === 1).length,
|
|
338
|
+
// Whole measured population, passed or not — `lib/rounds-to-pass.ts`'s
|
|
339
|
+
// choice, applied to both columns so the two are read the same way.
|
|
340
|
+
fiveOrMore:
|
|
341
|
+
scored.length === 0 ? null : scored.filter(s => s.rounds >= LONG_REVIEW_ROUNDS).length,
|
|
342
|
+
refusals,
|
|
343
|
+
};
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
/** Rounds by what came out of them, over every pull request in the range. */
|
|
347
|
+
export interface CrcSplit {
|
|
348
|
+
readonly total: number;
|
|
349
|
+
/** State name -> rounds. `measured` plus whatever the recorder wrote. */
|
|
350
|
+
readonly kinds: Readonly<Record<string, number>>;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/** The split's name for a round that produced a review. */
|
|
354
|
+
export const CRC_ROUND_MEASURED = "measured";
|
|
355
|
+
|
|
356
|
+
/**
|
|
357
|
+
* The round-kind split, over ALL pull requests in the range, merged or not.
|
|
358
|
+
*
|
|
359
|
+
* This reading needs BOTH views of each round and takes each from its own
|
|
360
|
+
* owner. **Whether the round was measured comes from `readLedger`** —
|
|
361
|
+
* `toLedgerRound` already computes `Array.isArray(findings)` and that is the
|
|
362
|
+
* only place in the tree allowed to decide it, so the split's `measured`
|
|
363
|
+
* total and `measuredRoundsFor`'s per-pull-request counts cannot drift.
|
|
364
|
+
* **Which KIND of unmeasured comes from the raw entry**, because
|
|
365
|
+
* `LedgerRound` has no slot for the `unmeasured` discriminator.
|
|
366
|
+
*
|
|
367
|
+
* The first draft restated the measured predicate inline, hardcoding the
|
|
368
|
+
* string `"findings"` beside a docblock arguing against exactly that. A
|
|
369
|
+
* reviewer caught it on #1633 and was right: tightening `toLedgerRound`'s
|
|
370
|
+
* rule would have moved one column and not the other, silently.
|
|
371
|
+
*
|
|
372
|
+
* The two views are `readLedger(body).rounds` and `ledgerRawRounds(body)`,
|
|
373
|
+
* which are the same array — one mapped, one not — so they align by index.
|
|
374
|
+
* That is asserted rather than assumed: a length mismatch means one of the
|
|
375
|
+
* two parsers changed and the pull request is skipped rather than zipped
|
|
376
|
+
* against the wrong entries.
|
|
377
|
+
*
|
|
378
|
+
* A ledger that refuses contributes nothing and is not counted as zero
|
|
379
|
+
* rounds. Its pull request is already named in both columns' refusals.
|
|
380
|
+
*/
|
|
381
|
+
export function splitRoundKinds(entries: readonly CrcEntry[]): CrcSplit {
|
|
382
|
+
const kinds: Record<string, number> = {};
|
|
383
|
+
let total = 0;
|
|
384
|
+
for (const entry of entries) {
|
|
385
|
+
const reading = readLedger(entry.body);
|
|
386
|
+
const raw = ledgerRawRounds(entry.body);
|
|
387
|
+
if (reading.status !== AI_REVIEW_LEDGER_READ || raw === null) continue;
|
|
388
|
+
if (raw.length !== reading.rounds.length) continue;
|
|
389
|
+
for (let i = 0; i < raw.length; i++) {
|
|
390
|
+
total++;
|
|
391
|
+
const kind = reading.rounds[i].measured
|
|
392
|
+
? CRC_ROUND_MEASURED
|
|
393
|
+
: readRecordedUnmeasuredState(raw[i]);
|
|
394
|
+
kinds[kind] = (kinds[kind] ?? 0) + 1;
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
return { total, kinds };
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
/** One dated reading, as it is stored and as the spec renders it. */
|
|
401
|
+
export interface CrcReadingRow {
|
|
402
|
+
/** ISO day the reading was taken. */
|
|
403
|
+
readonly date: string;
|
|
404
|
+
readonly lo: number;
|
|
405
|
+
readonly hi: number;
|
|
406
|
+
readonly pullRequests: number;
|
|
407
|
+
readonly allRounds: CrcColumn;
|
|
408
|
+
readonly measuredOnly: CrcColumn;
|
|
409
|
+
/**
|
|
410
|
+
* Rounds the scored ledgers STATED they evicted. Above zero means the
|
|
411
|
+
* measured-only figures are a LOWER BOUND by at least this much.
|
|
412
|
+
*/
|
|
413
|
+
readonly measuredOnlyEvicted: number;
|
|
414
|
+
/**
|
|
415
|
+
* Scored pull requests whose eviction count could not be established at
|
|
416
|
+
* all — a different fact from zero, and the one a single number hid.
|
|
417
|
+
* Non-empty also means LOWER BOUND, by an amount nobody can state.
|
|
418
|
+
*/
|
|
419
|
+
readonly measuredOnlyEvictionUnknown: readonly number[];
|
|
420
|
+
readonly split: CrcSplit;
|
|
421
|
+
/** Pull requests whose every round was refused by the review system. */
|
|
422
|
+
readonly zeroMeasured: readonly number[];
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
/** Take the whole reading. Premises are the caller's to check first. */
|
|
426
|
+
export function takeCrcReading(
|
|
427
|
+
entries: readonly CrcEntry[],
|
|
428
|
+
lo: number,
|
|
429
|
+
hi: number,
|
|
430
|
+
date: string,
|
|
431
|
+
): CrcReadingRow {
|
|
432
|
+
const allScored: Scored[] = [];
|
|
433
|
+
const allRefusals: CrcRefusal[] = [];
|
|
434
|
+
const measuredScored: Scored[] = [];
|
|
435
|
+
const measuredRefusals: CrcRefusal[] = [];
|
|
436
|
+
const zeroMeasured: number[] = [];
|
|
437
|
+
const measuredOnlyEvictionUnknown: number[] = [];
|
|
438
|
+
let measuredOnlyEvicted = 0;
|
|
439
|
+
|
|
440
|
+
for (const entry of entries) {
|
|
441
|
+
const all = allRoundsFor(entry);
|
|
442
|
+
if ("refusal" in all) allRefusals.push(all);
|
|
443
|
+
else allScored.push({ passed: entry.passed, rounds: all.rounds });
|
|
444
|
+
|
|
445
|
+
const only = measuredRoundsFor(entry);
|
|
446
|
+
if ("refusal" in only) {
|
|
447
|
+
measuredRefusals.push(only);
|
|
448
|
+
if (only.refusal === "ZERO_MEASURED_ROUNDS") zeroMeasured.push(entry.number);
|
|
449
|
+
} else {
|
|
450
|
+
measuredScored.push({ passed: entry.passed, rounds: only.rounds });
|
|
451
|
+
// Narrowed, not defaulted. An unknown eviction count has no number to
|
|
452
|
+
// add and is recorded as its own fact instead of folded into zero.
|
|
453
|
+
if (only.truncation.status === AI_REVIEW_TRUNCATION_STATED) {
|
|
454
|
+
measuredOnlyEvicted += only.truncation.dropped;
|
|
455
|
+
} else {
|
|
456
|
+
measuredOnlyEvictionUnknown.push(entry.number);
|
|
457
|
+
}
|
|
458
|
+
}
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
return {
|
|
462
|
+
date,
|
|
463
|
+
lo,
|
|
464
|
+
hi,
|
|
465
|
+
pullRequests: entries.length,
|
|
466
|
+
allRounds: scoreColumn(allScored, allRefusals),
|
|
467
|
+
measuredOnly: scoreColumn(measuredScored, measuredRefusals),
|
|
468
|
+
measuredOnlyEvicted,
|
|
469
|
+
measuredOnlyEvictionUnknown: measuredOnlyEvictionUnknown.sort((a, b) => a - b),
|
|
470
|
+
split: splitRoundKinds(entries),
|
|
471
|
+
zeroMeasured: zeroMeasured.sort((a, b) => a - b),
|
|
472
|
+
};
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
const pct = (n: number | null, d: number): string =>
|
|
476
|
+
n === null || d === 0 ? "UNMEASURED" : `${((n / d) * 100).toFixed(1)}%`;
|
|
477
|
+
const num = (v: number | null): string => (v === null ? "UNMEASURED" : v.toFixed(2));
|
|
478
|
+
|
|
479
|
+
/** `12 / 43`, or `UNMEASURED` — the numerator belongs in the table. */
|
|
480
|
+
const over = (n: number | null, d: number): string => (n === null ? "—" : `${n} / ${d}`);
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* The reading as the markdown the spec carries.
|
|
484
|
+
*
|
|
485
|
+
* Every denominator is printed beside its numerator, because two cells in one
|
|
486
|
+
* row can have different ones and a reader who cannot reproduce a percentage
|
|
487
|
+
* from the counts beside it has to rerun the whole thing to check it.
|
|
488
|
+
*/
|
|
489
|
+
export function renderCrcReading(row: CrcReadingRow): string[] {
|
|
490
|
+
const a = row.allRounds;
|
|
491
|
+
const m = row.measuredOnly;
|
|
492
|
+
const lines = [
|
|
493
|
+
`Read over **#${row.lo}–#${row.hi}** on ${row.date} — ${row.pullRequests} pull requests, ` +
|
|
494
|
+
`${row.split.total} rounds.`,
|
|
495
|
+
"",
|
|
496
|
+
"| | all rounds | numerator | measured rounds only | numerator |",
|
|
497
|
+
"|---|---|---|---|---|",
|
|
498
|
+
`| mean rounds to pass | ${num(a.mean)} | ${a.passedRounds} / ${a.passed} | ` +
|
|
499
|
+
`${num(m.mean)} | ${m.passedRounds} / ${m.passed} |`,
|
|
500
|
+
`| passed after one round | ${pct(a.oneRound, a.passed)} | ${over(a.oneRound, a.passed)} | ` +
|
|
501
|
+
`${pct(m.oneRound, m.passed)} | ${over(m.oneRound, m.passed)} |`,
|
|
502
|
+
`| ${LONG_REVIEW_ROUNDS} or more rounds | ${pct(a.fiveOrMore, a.measured)} | ` +
|
|
503
|
+
`${over(a.fiveOrMore, a.measured)} | ${pct(m.fiveOrMore, m.measured)} | ` +
|
|
504
|
+
`${over(m.fiveOrMore, m.measured)} |`,
|
|
505
|
+
"",
|
|
506
|
+
"The five-or-more row's denominator is ALL measured pull requests and the two above it " +
|
|
507
|
+
"are over the ones that PASSED, in both columns — a tail measured on survivors only " +
|
|
508
|
+
"has had its tail cut off.",
|
|
509
|
+
"",
|
|
510
|
+
"| round outcome | rounds | share |",
|
|
511
|
+
"|---|---|---|",
|
|
512
|
+
];
|
|
513
|
+
for (const [kind, n] of Object.entries(row.split.kinds).sort((x, y) => y[1] - x[1])) {
|
|
514
|
+
lines.push(`| \`${kind}\` | ${n} | ${pct(n, row.split.total)} |`);
|
|
515
|
+
}
|
|
516
|
+
lines.push("");
|
|
517
|
+
const unknown = row.measuredOnlyEvictionUnknown;
|
|
518
|
+
if (row.measuredOnlyEvicted > 0 || unknown.length > 0) {
|
|
519
|
+
const stated =
|
|
520
|
+
row.measuredOnlyEvicted > 0
|
|
521
|
+
? `${row.measuredOnlyEvicted} round(s) were evicted from ledgers that scored in it, and ` +
|
|
522
|
+
"an evicted round's kind is unrecoverable"
|
|
523
|
+
: null;
|
|
524
|
+
const unknowable =
|
|
525
|
+
unknown.length > 0
|
|
526
|
+
? `${unknown.length} scored pull request(s) cannot say how many rounds they evicted ` +
|
|
527
|
+
`(${unknown.map(n => `#${n}`).join(", ")}), so the shortfall there is not even a ` +
|
|
528
|
+
"number — which is a different fact from zero and is why this line exists"
|
|
529
|
+
: null;
|
|
530
|
+
lines.push(
|
|
531
|
+
`**The measured-only column is a LOWER BOUND.** ${[stated, unknowable]
|
|
532
|
+
.filter(Boolean)
|
|
533
|
+
.join(". ")}.`,
|
|
534
|
+
"",
|
|
535
|
+
);
|
|
536
|
+
}
|
|
537
|
+
lines.push(
|
|
538
|
+
row.zeroMeasured.length === 0
|
|
539
|
+
? "**Every pull request in the range had at least one measured round.**"
|
|
540
|
+
: `**${row.zeroMeasured.length} pull request(s) had zero measured rounds in their ` +
|
|
541
|
+
`entire lives** and are UNMEASURED in the measured-only column rather than scored ` +
|
|
542
|
+
`as one-round passes: ${row.zeroMeasured.map(n => `#${n}`).join(", ")}.`,
|
|
543
|
+
);
|
|
544
|
+
return lines;
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
const signed = (v: number, digits: number): string =>
|
|
548
|
+
`${v >= 0 ? "+" : "−"}${Math.abs(v).toFixed(digits)}`;
|
|
549
|
+
|
|
550
|
+
function deltaRow(label: string, before: number | null, after: number | null): string {
|
|
551
|
+
if (before === null || after === null) return ` ${label}: UNMEASURED on one side`;
|
|
552
|
+
return ` ${label}: ${before.toFixed(2)} → ${after.toFixed(2)} (${signed(after - before, 2)})`;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
function rateRow(
|
|
556
|
+
label: string,
|
|
557
|
+
before: CrcColumn,
|
|
558
|
+
after: CrcColumn,
|
|
559
|
+
pick: (c: CrcColumn) => { n: number | null; d: number },
|
|
560
|
+
): string {
|
|
561
|
+
const b = pick(before);
|
|
562
|
+
const c = pick(after);
|
|
563
|
+
if (b.n === null || c.n === null || b.d === 0 || c.d === 0) {
|
|
564
|
+
return ` ${label}: UNMEASURED on one side`;
|
|
565
|
+
}
|
|
566
|
+
const bp = (b.n / b.d) * 100;
|
|
567
|
+
const cp = (c.n / c.d) * 100;
|
|
568
|
+
return (
|
|
569
|
+
` ${label}: ${bp.toFixed(1)}% (${b.n}/${b.d}) → ${cp.toFixed(1)}% (${c.n}/${c.d})` +
|
|
570
|
+
` (${signed(cp - bp, 1)}pt)`
|
|
571
|
+
);
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
/**
|
|
575
|
+
* The delta against the previous row — and it names BOTH ranges first.
|
|
576
|
+
*
|
|
577
|
+
* A delta between two differently-ranged readings is a comparison of two
|
|
578
|
+
* cohorts, not a measurement of change, and the only honest form of it says
|
|
579
|
+
* so in the same breath as the numbers. The ranges are on the first line for
|
|
580
|
+
* the reason the unmeasured count is on `formatRoundsToPass`'s first line: a
|
|
581
|
+
* reader quotes what they saw first.
|
|
582
|
+
*/
|
|
583
|
+
export function deltaLines(previous: CrcReadingRow | null, row: CrcReadingRow): string[] {
|
|
584
|
+
if (previous === null) {
|
|
585
|
+
return [
|
|
586
|
+
`delta: NONE — #${row.lo}–#${row.hi} on ${row.date} is the first row in the store.`,
|
|
587
|
+
];
|
|
588
|
+
}
|
|
589
|
+
const shared =
|
|
590
|
+
Math.min(previous.hi, row.hi) - Math.max(previous.lo, row.lo) + 1;
|
|
591
|
+
const lines = [
|
|
592
|
+
`delta: #${previous.lo}–#${previous.hi} (${previous.date}) → #${row.lo}–#${row.hi} ` +
|
|
593
|
+
`(${row.date}) — ${shared > 0 ? `${shared} pull request numbers in common` : "DISJOINT ranges"}.` +
|
|
594
|
+
(previous.lo === row.lo && previous.hi === row.hi
|
|
595
|
+
? ""
|
|
596
|
+
: " These are different cohorts; the figures below are a comparison, not a change."),
|
|
597
|
+
];
|
|
598
|
+
for (const [name, b, a] of [
|
|
599
|
+
["all rounds", previous.allRounds, row.allRounds],
|
|
600
|
+
["measured only", previous.measuredOnly, row.measuredOnly],
|
|
601
|
+
] as const) {
|
|
602
|
+
lines.push(`${name}:`);
|
|
603
|
+
lines.push(deltaRow("mean rounds to pass ", b.mean, a.mean));
|
|
604
|
+
lines.push(rateRow("passed after one round", b, a, c => ({ n: c.oneRound, d: c.passed })));
|
|
605
|
+
lines.push(
|
|
606
|
+
rateRow(`${LONG_REVIEW_ROUNDS} or more rounds `, b, a, c => ({
|
|
607
|
+
n: c.fiveOrMore,
|
|
608
|
+
d: c.measured,
|
|
609
|
+
})),
|
|
610
|
+
);
|
|
611
|
+
}
|
|
612
|
+
const un = (s: CrcSplit) => s.total - (s.kinds[CRC_ROUND_MEASURED] ?? 0);
|
|
613
|
+
lines.push(
|
|
614
|
+
`unmeasured rounds: ${pct(un(previous.split), previous.split.total)} ` +
|
|
615
|
+
`(${un(previous.split)}/${previous.split.total}) → ${pct(un(row.split), row.split.total)} ` +
|
|
616
|
+
`(${un(row.split)}/${row.split.total})`,
|
|
617
|
+
);
|
|
618
|
+
return lines;
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
/** Rounds nothing classified — present only on ledgers older than #1486. */
|
|
622
|
+
export function notRecordedRounds(split: CrcSplit): number {
|
|
623
|
+
return split.kinds[AI_REVIEW_UNMEASURED_NOT_RECORDED] ?? 0;
|
|
624
|
+
}
|
|
625
|
+
|
|
626
|
+
/** Where the rendered block starts in the spec. */
|
|
627
|
+
export const CRC_BLOCK_BEGIN =
|
|
628
|
+
"<!-- crc-reading:begin — generated by `bun scripts/crc-reading.ts`; do not edit by hand -->";
|
|
629
|
+
|
|
630
|
+
/** Where it ends. */
|
|
631
|
+
export const CRC_BLOCK_END = "<!-- crc-reading:end -->";
|
|
632
|
+
|
|
633
|
+
/**
|
|
634
|
+
* Put the rendered reading between the markers.
|
|
635
|
+
*
|
|
636
|
+
* THE SINGLE SITE for the splice, so the script that writes the block and
|
|
637
|
+
* the test that checks it cannot disagree about where the block is. Two
|
|
638
|
+
* implementations of "find the markers" is the shape
|
|
639
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` calls *two deciders*: the
|
|
640
|
+
* check would go green against its own idea of the boundary.
|
|
641
|
+
*
|
|
642
|
+
* `null` when either marker is missing or they are the wrong way round — a
|
|
643
|
+
* document that cannot say where its generated block goes must refuse, not
|
|
644
|
+
* get one appended somewhere plausible.
|
|
645
|
+
*/
|
|
646
|
+
export function spliceCrcBlock(document: string, row: CrcReadingRow): string | null {
|
|
647
|
+
const begin = document.indexOf(CRC_BLOCK_BEGIN);
|
|
648
|
+
const end = document.indexOf(CRC_BLOCK_END, begin);
|
|
649
|
+
if (begin === -1 || end === -1) return null;
|
|
650
|
+
return (
|
|
651
|
+
document.slice(0, begin + CRC_BLOCK_BEGIN.length) +
|
|
652
|
+
`\n\n${renderCrcReading(row).join("\n")}\n\n` +
|
|
653
|
+
document.slice(end)
|
|
654
|
+
);
|
|
655
|
+
}
|