rungate 0.8.0 → 0.8.2
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 -0
- package/gates/SCHEMA-GUIDE.md +485 -0
- package/gates/ac-quality.test.ts +106 -0
- package/gates/adversarial.test.ts +283 -0
- package/gates/brief-assembler.test.ts +487 -0
- package/gates/brief-assembler.ts +448 -0
- package/gates/bunfig.toml +2 -0
- package/gates/chain.test.ts +91 -0
- package/gates/e2e-smoke.test.ts +234 -0
- package/gates/error-classifier.test.ts +250 -0
- package/gates/error-classifier.ts +99 -0
- package/gates/gate-executor.ts +3071 -0
- package/gates/orchestrator.test.ts +968 -0
- package/gates/orchestrator.ts +827 -0
- package/gates/preload.ts +89 -0
- package/gates/prompts/ac-adversary.md +20 -0
- package/gates/prompts/evidence-validator.md +22 -0
- package/gates/prompts/prove-reproducer.md +53 -0
- package/gates/prompts.sha256 +3 -0
- package/gates/prove.test.ts +164 -0
- package/gates/rook-state.test.ts +108 -0
- package/gates/run-attribution.ts +290 -0
- package/gates/run-gate.ts +163 -0
- package/gates/schema-parity.test.ts +378 -0
- package/gates/schema.ts +1209 -0
- package/gates/self-heal.test.ts +511 -0
- package/gates/self-heal.ts +125 -0
- package/gates/ship-orchestrator.test.ts +399 -0
- package/gates/ship-orchestrator.ts +384 -0
- package/gates/spec-compliance-probe.ts +159 -0
- package/gates/test-fixtures/broken-no-environments.json +110 -0
- package/gates/test-fixtures/consumer-directory-layout.json +90 -0
- package/gates/test-fixtures/valid-standard.json +91 -0
- package/gates/test-utils.ts +43 -0
- package/gates/typecheck-gate.ts +111 -0
- package/gates/witness.ts +349 -0
- package/gates/workflow.test.ts +2018 -0
- package/hooks/BashWriteGuard.hook.ts +19 -0
- package/hooks/GateResultProtection.hook.ts +27 -1
- package/hooks/VerifyPhaseLock.hook.ts +51 -11
- package/hooks/WorkflowStateGuard.hook.ts +24 -0
- package/lib/ai-review-rounds.ts +462 -0
- package/lib/bash-file-read.ts +17 -3
- package/lib/bash-write-guard.ts +1285 -50
- package/lib/distribution-standing.ts +75 -4
- package/lib/failure-intake.ts +12 -4
- package/lib/file-extensions.ts +81 -0
- package/lib/finding-arbiter.ts +1015 -0
- package/lib/finding-jury.ts +537 -0
- package/lib/gate-enforcement.ts +171 -43
- package/lib/gate-result-protection.ts +12 -2
- package/lib/generators/code-map.ts +55 -4
- package/lib/generators/types.ts +27 -1
- package/lib/github.ts +55 -0
- package/lib/interpreters.ts +64 -0
- package/lib/issue-create-override.ts +69 -8
- package/lib/issue-filing-gate.ts +605 -0
- package/lib/js-top-level-code.ts +20 -2
- package/lib/junit-checks.ts +239 -1
- package/lib/package-closure.ts +114 -0
- package/lib/publish-window.ts +287 -0
- package/lib/scaffold/ai-review-findings.ts +142 -3
- package/lib/scaffold/ai-review-step.ts +1012 -18
- package/lib/scaffold/managed-workflow.ts +163 -4
- package/lib/scaffold/steps.ts +498 -22
- package/lib/scanner.ts +13 -4
- package/lib/ticked-sc-symbols.ts +361 -0
- package/lib/transcript-checker.ts +6 -0
- package/lib/workflow-actions.ts +18 -0
- package/package.json +3 -1
- package/scripts/arbitrate-finding.ts +224 -0
- package/scripts/generate-code-map.ts +18 -10
- package/scripts/sync-sc-status.ts +82 -8
|
@@ -0,0 +1,537 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The verifier jury: who agrees a finding is real, what kind it is, and where
|
|
3
|
+
* it goes (#1187).
|
|
4
|
+
*
|
|
5
|
+
* ## The topology this implements, and the one it replaces
|
|
6
|
+
*
|
|
7
|
+
* #1187 was filed asking which findings are worth **filing**. That framing is
|
|
8
|
+
* wrong, and the correction is the point of this module. The published design
|
|
9
|
+
* it was inspired by files nothing at all:
|
|
10
|
+
*
|
|
11
|
+
* > Several agents look for bugs at the same time. Then a separate group votes
|
|
12
|
+
* > on each finding, and it only gets posted if enough of them agree it's
|
|
13
|
+
* > real. Findings that are only about style, diagnostics, or cleanup get
|
|
14
|
+
* > dropped. We A/B tested those filters on our own PRs before keeping them.
|
|
15
|
+
* > What's left shows up as inline comments sorted by severity. Each is tagged
|
|
16
|
+
* > Important, Nit, or Pre-existing.
|
|
17
|
+
*
|
|
18
|
+
* So the pipeline is **hunters → a separate verifier group votes → quorum →
|
|
19
|
+
* category filter → severity sort → inline PR comments that block merge until
|
|
20
|
+
* answered.** A finding is resolved by being fixed or by the thread being
|
|
21
|
+
* closed with a reason. Nothing becomes a tracker issue, which is why that
|
|
22
|
+
* pipeline has no backlog and ours regenerates: we added a filing step it does
|
|
23
|
+
* not have. Measured on this tracker on 2026-10-22, **23 of 27 open issues
|
|
24
|
+
* were created the same day and 10 of them name one subsystem.**
|
|
25
|
+
*
|
|
26
|
+
* `DEFAULT_DISPOSITION` is therefore `COMMENT`, and `ISSUE` is reachable only
|
|
27
|
+
* by an explicit, reasoned declaration from the caller — see `adjudicate`.
|
|
28
|
+
*
|
|
29
|
+
* ## What this module owns, and what it does not
|
|
30
|
+
*
|
|
31
|
+
* It owns the **gate**, not the agents. Spawning hunters and verifiers is the
|
|
32
|
+
* orchestrator's job; a library that spawned them could not be tested without
|
|
33
|
+
* a model in the loop, and `lib/rule-promotion.ts` already set the precedent —
|
|
34
|
+
* it owns the ranking and the budget and nothing that produces candidates.
|
|
35
|
+
*
|
|
36
|
+
* So a caller hands in `VerifierVote[]` and this counts them.
|
|
37
|
+
*
|
|
38
|
+
* ## WHAT THIS DOES NOT COVER
|
|
39
|
+
*
|
|
40
|
+
* - **Whether the verifiers are independent.** Three votes from one agent run
|
|
41
|
+
* three times is not a group, and the only shape of that this can see is a
|
|
42
|
+
* repeated `verifier` id, which it refuses. Three genuinely separate agents
|
|
43
|
+
* given the same prompt and the same context are correlated in a way nothing
|
|
44
|
+
* here can read.
|
|
45
|
+
* - **Whether the category a verifier reports is the right one.**
|
|
46
|
+
* `classifyCategory` is a keyword fallback and a measuring instrument, not
|
|
47
|
+
* an adjudicator. Its error direction is deliberately toward KEEP.
|
|
48
|
+
* - **Whether a dropped finding was real.** A dropped finding leaves a reason
|
|
49
|
+
* and a category on the reading; nothing re-examines it later.
|
|
50
|
+
*/
|
|
51
|
+
|
|
52
|
+
import type { Finding } from "./finding-arbiter";
|
|
53
|
+
|
|
54
|
+
// ── Cardinalities ────────────────────────────────────────────────────────
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* How many verifiers vote on each finding.
|
|
58
|
+
*
|
|
59
|
+
* **Three, and this is a default rather than a derivation.** The published
|
|
60
|
+
* design gives the topology and publishes no cardinality — not the number of
|
|
61
|
+
* hunters, not the number of verifiers, not the quorum. Writing a number into
|
|
62
|
+
* the code as though it had been measured would be the worst of both.
|
|
63
|
+
*
|
|
64
|
+
* What can be argued for three:
|
|
65
|
+
*
|
|
66
|
+
* - It is the smallest group in which **one voter does not decide the
|
|
67
|
+
* outcome**. At two, a single dissent either deadlocks or wins.
|
|
68
|
+
* - It is odd, so a majority always exists and no tie-break rule is needed —
|
|
69
|
+
* and a tie-break rule is a second decider over the same input
|
|
70
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
71
|
+
* - Each verifier is a full agent context. Five-of-three costs 67% more per
|
|
72
|
+
* finding and buys tolerance of **two** dissenters, which is only worth
|
|
73
|
+
* paying once a measured single-dissent rate shows it is common.
|
|
74
|
+
*
|
|
75
|
+
* What would derive it: the disagreement rate between independent verifiers on
|
|
76
|
+
* one finding. **That cannot be measured in this repository today**, because
|
|
77
|
+
* nothing records a finding before it is filed — every artefact on this
|
|
78
|
+
* tracker and in `.claude/` is already post-filter. Recording the pre-filter
|
|
79
|
+
* population is the prerequisite, not a tuning pass.
|
|
80
|
+
*/
|
|
81
|
+
export const VERIFIER_GROUP_SIZE = 3;
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* How many of them must agree a finding is real for it to be posted.
|
|
85
|
+
*
|
|
86
|
+
* Two of three: the weakest threshold that still means *agreement* rather than
|
|
87
|
+
* *anyone*. `juryReading` refuses a configured quorum that is not a strict
|
|
88
|
+
* majority — see `NON_MAJORITY_QUORUM` — because a "quorum" of one is a group
|
|
89
|
+
* with no gate in it, and that failure is invisible from the outcome.
|
|
90
|
+
*/
|
|
91
|
+
export const VERIFIER_QUORUM = 2;
|
|
92
|
+
|
|
93
|
+
export const INCOMPLETE_GROUP = "the ballot's size does not match the declared group size: an absent vote is neither agreement nor dissent, and an extra one is not a larger group";
|
|
94
|
+
export const REPEATED_VERIFIER = "one verifier voted more than once, so the votes are not independent";
|
|
95
|
+
export const NON_MAJORITY_QUORUM = "the configured quorum is not a strict majority of the group";
|
|
96
|
+
|
|
97
|
+
// ── Categories ───────────────────────────────────────────────────────────
|
|
98
|
+
|
|
99
|
+
export type FindingCategory =
|
|
100
|
+
| "correctness"
|
|
101
|
+
| "security"
|
|
102
|
+
| "performance"
|
|
103
|
+
| "style"
|
|
104
|
+
| "diagnostics"
|
|
105
|
+
| "cleanup"
|
|
106
|
+
/** No signal either way. Kept, never dropped. */
|
|
107
|
+
| "unclassified";
|
|
108
|
+
|
|
109
|
+
/** Dropped outright. The three the source design names, and no others. */
|
|
110
|
+
export const DROPPED_CATEGORIES: ReadonlySet<FindingCategory> = new Set<FindingCategory>([
|
|
111
|
+
"style",
|
|
112
|
+
"diagnostics",
|
|
113
|
+
"cleanup",
|
|
114
|
+
]);
|
|
115
|
+
|
|
116
|
+
const KEEP_SIGNALS: Array<[Exclude<FindingCategory, "style" | "diagnostics" | "cleanup" | "unclassified">, RegExp]> = [
|
|
117
|
+
[
|
|
118
|
+
"security",
|
|
119
|
+
/\b(secret|credential|token|api key|injection|traversal|privilege|sandbox escape|arbitrary (read|write|code)|unauthenticated|spoof)\b/i,
|
|
120
|
+
],
|
|
121
|
+
[
|
|
122
|
+
"correctness",
|
|
123
|
+
/\b(bug|defect|regression|incorrect|wrong|broken|crash|throws|race|deadlock|off.by.one|silently|never fires|cannot fail|false (positive|negative)|fails? (open|closed|to)|returns the wrong|mismatch|data loss|corrupt|does not (match|fire|run|refuse|catch))\b/i,
|
|
124
|
+
],
|
|
125
|
+
["performance", /\b(timeout|unbounded|memory leak|leaks? (memory|descriptors)|hangs?|exhaust)\b/i],
|
|
126
|
+
];
|
|
127
|
+
|
|
128
|
+
const DROP_SIGNALS: Array<[Extract<FindingCategory, "style" | "diagnostics" | "cleanup">, RegExp]> = [
|
|
129
|
+
["style", /\b(nit|typo|formatting|indentation|naming convention|rename (it|this|the variable)|readability|capitalisation|capitalization|whitespace)\b/i],
|
|
130
|
+
["diagnostics", /\b(error message|log(ging| line| statement)|warning text|annotation text|stack trace|observability|console\.log|more helpful message)\b/i],
|
|
131
|
+
["cleanup", /\b(unused (import|variable|export|function)|commented.out|refactor|tidy|house ?keeping|nitpick|cosmetic|delete the comment|redundant comment)\b/i],
|
|
132
|
+
];
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* A keyword reading of what kind of finding this is.
|
|
136
|
+
*
|
|
137
|
+
* **This is a fallback and a measuring instrument, not an adjudicator.** In
|
|
138
|
+
* production the category comes from the verifier vote, which is a model
|
|
139
|
+
* reading the finding; this runs only when no verifier supplied one, and it is
|
|
140
|
+
* what `adjudicate` reports so the category is never silently absent.
|
|
141
|
+
*
|
|
142
|
+
* ## The error direction, chosen deliberately
|
|
143
|
+
*
|
|
144
|
+
* A drop category is returned **only when a drop signal matched and no keep
|
|
145
|
+
* signal did.** So the cheap way for this to be wrong is to keep a nit, which
|
|
146
|
+
* costs one comment thread; the expensive way — dropping a real bug — requires
|
|
147
|
+
* a finding that uses none of the correctness, security or performance
|
|
148
|
+
* vocabulary while using the style, diagnostics or cleanup vocabulary.
|
|
149
|
+
*
|
|
150
|
+
* ## THE SCOPE IS THE TITLE, AND THAT IS THE WHOLE RULE
|
|
151
|
+
*
|
|
152
|
+
* **A finding's title states what it is about; its body argues, and an
|
|
153
|
+
* argument quotes the vocabulary of the thing it is not.**
|
|
154
|
+
*
|
|
155
|
+
* Measured, not asserted. Over the 385 issues on this tracker closed as
|
|
156
|
+
* COMPLETED, reading the whole text drops **8**, and all eight are that
|
|
157
|
+
* failure: `prose` inside `refs(c.branch) || prose(c.subject)` (#900), inside
|
|
158
|
+
* "template prose" (#515), inside "entries carried prose" (#611) — and #781,
|
|
159
|
+
* whose body contains the sentence *"the reason this is not just a wording
|
|
160
|
+
* fix"*. Scoping to the title drops **0** of the same 385.
|
|
161
|
+
*
|
|
162
|
+
* Three terms were then removed from the signal lists, and this is a fit to
|
|
163
|
+
* this corpus rather than a forecast, so it is stated as one: `prose` and
|
|
164
|
+
* `wording` are **domain vocabulary here** — this project argues about prose
|
|
165
|
+
* versus mechanism constantly — and `dead code` is how a reachability defect
|
|
166
|
+
* is *described* (#1110's title calls an unreachable blocking branch "dead
|
|
167
|
+
* code"), not a request to tidy. They would be reasonable signals in a
|
|
168
|
+
* codebase that did not talk this way.
|
|
169
|
+
*
|
|
170
|
+
* ## Measured backwards, before the filter shipped
|
|
171
|
+
*
|
|
172
|
+
* The source design A/B tested its filters before keeping them. The
|
|
173
|
+
* backwards-equivalent available here is to run the filter over findings whose
|
|
174
|
+
* outcome is already known: closed as COMPLETED means a merged PR fixed it, so
|
|
175
|
+
* it was real.
|
|
176
|
+
*
|
|
177
|
+
* | population | n | dropped |
|
|
178
|
+
* |---|---|---|
|
|
179
|
+
* | closed COMPLETED — real, somebody wrote the fix | 385 | **0** |
|
|
180
|
+
* | closed NOT_PLANNED | 15 | **0** |
|
|
181
|
+
* | open on 2026-10-22 | 27 | **0** |
|
|
182
|
+
* | planted: one style, one diagnostics, one cleanup, one correctness control | 4 | **3** |
|
|
183
|
+
*
|
|
184
|
+
* **Read the fourth row before the first three.** Zero drops over 427 real
|
|
185
|
+
* issues would otherwise be indistinguishable from a filter that cannot fire
|
|
186
|
+
* — the inert-knob shape in `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
187
|
+
* The planted row is in `test/finding-jury.test.ts` under `JURY-4` and it is
|
|
188
|
+
* what separates those two readings.
|
|
189
|
+
*
|
|
190
|
+
* **And read the first three as safety, not as usefulness.** The filter is
|
|
191
|
+
* inert on this corpus because what this tracker carries is already almost
|
|
192
|
+
* entirely correctness-shaped (278 of 385 by this same classifier). Its real
|
|
193
|
+
* population is raw hunter output *before* anybody decided to file, and
|
|
194
|
+
* **this repository does not record that population anywhere** — which is the
|
|
195
|
+
* same gap that makes the quorum cardinality above a default rather than a
|
|
196
|
+
* derivation. So: safe to ship, not yet shown to earn its place.
|
|
197
|
+
*/
|
|
198
|
+
export function classifyCategory(finding: Pick<Finding, "title" | "body">): FindingCategory {
|
|
199
|
+
const scope = finding.title;
|
|
200
|
+
for (const [category, signal] of KEEP_SIGNALS) {
|
|
201
|
+
if (signal.test(scope)) return category;
|
|
202
|
+
}
|
|
203
|
+
for (const [category, signal] of DROP_SIGNALS) {
|
|
204
|
+
if (signal.test(scope)) return category;
|
|
205
|
+
}
|
|
206
|
+
return "unclassified";
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// ── Severity ─────────────────────────────────────────────────────────────
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* The three tags the source design posts, and no fourth.
|
|
213
|
+
*
|
|
214
|
+
* `Pre-existing` is the one that matters most here and the one we had no way
|
|
215
|
+
* to say: a finding about code the change never touched is not the author's
|
|
216
|
+
* defect and should not be priced like one.
|
|
217
|
+
*/
|
|
218
|
+
export type Severity = "Important" | "Nit" | "Pre-existing";
|
|
219
|
+
|
|
220
|
+
/** Sort order for the posted comments. A pre-existing bug is still a bug. */
|
|
221
|
+
export const SEVERITY_RANK: Record<Severity, number> = { Important: 0, "Pre-existing": 1, Nit: 2 };
|
|
222
|
+
|
|
223
|
+
// ── The vote ─────────────────────────────────────────────────────────────
|
|
224
|
+
|
|
225
|
+
export interface VerifierVote {
|
|
226
|
+
/** Which verifier cast it. Two votes under one id is not a group. */
|
|
227
|
+
verifier: string;
|
|
228
|
+
/** The one question a vote answers: is this real? */
|
|
229
|
+
real: boolean;
|
|
230
|
+
reason: string;
|
|
231
|
+
category?: FindingCategory;
|
|
232
|
+
severity?: Severity;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Every category name, bound to the union by the compiler.
|
|
237
|
+
*
|
|
238
|
+
* A `Record<FindingCategory, true>` is exhaustive: add a member to the union
|
|
239
|
+
* and this object fails to typecheck until it carries it. That is the point —
|
|
240
|
+
* a hand-written array would quietly stop recognising the new category and
|
|
241
|
+
* `parseVotes` would start refusing a vote that is in fact well-formed.
|
|
242
|
+
*/
|
|
243
|
+
const CATEGORY_MEMBERS: Record<FindingCategory, true> = {
|
|
244
|
+
correctness: true,
|
|
245
|
+
security: true,
|
|
246
|
+
performance: true,
|
|
247
|
+
style: true,
|
|
248
|
+
diagnostics: true,
|
|
249
|
+
cleanup: true,
|
|
250
|
+
unclassified: true,
|
|
251
|
+
};
|
|
252
|
+
|
|
253
|
+
/** What a malformed entry is called in the refusal. One string, one binding. */
|
|
254
|
+
export const UNREADABLE_VOTE = "a vote nobody can read is UNMEASURED, not a dissent";
|
|
255
|
+
|
|
256
|
+
/** `"a string"`, `3`, `null` — enough to identify the entry without echoing a body. */
|
|
257
|
+
function shapeOf(value: unknown): string {
|
|
258
|
+
if (value === null) return "null";
|
|
259
|
+
if (Array.isArray(value)) return "an array";
|
|
260
|
+
return typeof value === "string" ? `the string ${JSON.stringify(value)}` : `a ${typeof value}`;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* Read an untrusted ballot, or refuse it.
|
|
265
|
+
*
|
|
266
|
+
* **This is the boundary, and it is the whole of #1235.** `readVotes` in
|
|
267
|
+
* `scripts/arbitrate-finding.ts` checked that the parsed JSON was an array and
|
|
268
|
+
* then cast it — `parsed as VerifierVote[]` — so nothing ever looked at an
|
|
269
|
+
* entry. `juryReading` counts agreement with `votes.filter(v => v.real)`, a
|
|
270
|
+
* truthy test, and **the string `"false"` is truthy**. A verifier who wrote
|
|
271
|
+
* `"real": "false"` was counted as agreeing with the finding they rejected.
|
|
272
|
+
* Measured before the fix: three votes, all three rejecting, two of them
|
|
273
|
+
* spelling it `"false"`, returned `MEASURED passed=true` at `2 of 3`.
|
|
274
|
+
*
|
|
275
|
+
* ## Why this refuses the ballot instead of coercing the vote
|
|
276
|
+
*
|
|
277
|
+
* The cheap repair is to read `"false"` as `false`. It fixes the headline case
|
|
278
|
+
* and is wrong in the same direction: it invents a dissent. A vote that cannot
|
|
279
|
+
* be read is not a vote that was cast, and counting it as a no is a second
|
|
280
|
+
* reading nobody took — `.claude/rules/config-access.md`'s *Silent Default
|
|
281
|
+
* Substitution*. One unreadable entry among two genuine yeses still clears a
|
|
282
|
+
* 2-of-3 quorum under coercion, and `test/finding-arbiter.test.ts`'s `AR-16`
|
|
283
|
+
* case `B` is that input.
|
|
284
|
+
*
|
|
285
|
+
* Nor is the entry dropped. A two-vote ballot against a declared group of
|
|
286
|
+
* three refuses as `INCOMPLETE_GROUP` — "a verifier did not report" — when in
|
|
287
|
+
* fact it reported unreadably. Both refuse; only one names what happened.
|
|
288
|
+
*
|
|
289
|
+
* ## Why here and not in `juryReading`
|
|
290
|
+
*
|
|
291
|
+
* `juryReading` owns the *group* properties — `INCOMPLETE_GROUP`,
|
|
292
|
+
* `REPEATED_VERIFIER`, `NON_MAJORITY_QUORUM` — and should keep owning only
|
|
293
|
+
* those. They are facts about a ballot already known to be made of votes. This
|
|
294
|
+
* is the question of whether it is, and it belongs where the JSON enters.
|
|
295
|
+
*
|
|
296
|
+
* Validating the whole declared interface rather than only `real` is
|
|
297
|
+
* deliberate: the cast asserted every field, so every field was unchecked, and
|
|
298
|
+
* two of the others carry the same defect. An unrecognised `category` is not
|
|
299
|
+
* in `DROPPED_CATEGORIES`, so it reads to `juryCategory` as a keep category.
|
|
300
|
+
* An unrecognised `severity` indexes `SEVERITY_RANK` to `undefined`, making
|
|
301
|
+
* the sort comparator in `severityOf` return `NaN`.
|
|
302
|
+
*
|
|
303
|
+
* **`Object.hasOwn`, never the `in` operator**, and this is not a style
|
|
304
|
+
* preference. `in` walks the prototype chain, so `"constructor" in
|
|
305
|
+
* CATEGORY_MEMBERS` is `true` and a vote claiming `category: "constructor"`
|
|
306
|
+
* was accepted — an accepted-but-unrecognised category is absent from
|
|
307
|
+
* `DROPPED_CATEGORIES` and so reads as a **keep**, which is this function's
|
|
308
|
+
* own defect reintroduced inside its fix. Eight values were wrongly accepted
|
|
309
|
+
* across the two fields; `JURY-6` runs five of them against both.
|
|
310
|
+
*
|
|
311
|
+
* @throws if the ballot is not an array, or any entry is not a well-formed vote.
|
|
312
|
+
*/
|
|
313
|
+
export function parseVotes(parsed: unknown): readonly VerifierVote[] {
|
|
314
|
+
if (!Array.isArray(parsed)) {
|
|
315
|
+
throw new Error(`the ballot is ${shapeOf(parsed)}, not a JSON array of votes`);
|
|
316
|
+
}
|
|
317
|
+
return parsed.map((entry, at): VerifierVote => {
|
|
318
|
+
const where = `vote ${at} of the ballot`;
|
|
319
|
+
if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
|
|
320
|
+
throw new Error(`${where} is ${shapeOf(entry)}, not an object: ${UNREADABLE_VOTE}`);
|
|
321
|
+
}
|
|
322
|
+
const v = entry as Record<string, unknown>;
|
|
323
|
+
if (typeof v.verifier !== "string" || v.verifier === "") {
|
|
324
|
+
throw new Error(
|
|
325
|
+
`${where} has no \`verifier\` id (${shapeOf(v.verifier)}): an anonymous vote cannot be ` +
|
|
326
|
+
`checked for independence, so ${UNREADABLE_VOTE}`,
|
|
327
|
+
);
|
|
328
|
+
}
|
|
329
|
+
if (typeof v.real !== "boolean") {
|
|
330
|
+
throw new Error(
|
|
331
|
+
`${where}, from \`${v.verifier}\`, has a non-boolean \`real\` (${shapeOf(v.real)}): ` +
|
|
332
|
+
`agreement is counted by truthiness, so this would read as a yes — ${UNREADABLE_VOTE}`,
|
|
333
|
+
);
|
|
334
|
+
}
|
|
335
|
+
if (typeof v.reason !== "string") {
|
|
336
|
+
throw new Error(`${where}, from \`${v.verifier}\`, has no \`reason\` (${shapeOf(v.reason)}): ${UNREADABLE_VOTE}`);
|
|
337
|
+
}
|
|
338
|
+
if (v.category !== undefined && !(typeof v.category === "string" && Object.hasOwn(CATEGORY_MEMBERS, v.category))) {
|
|
339
|
+
throw new Error(
|
|
340
|
+
`${where}, from \`${v.verifier}\`, names an unknown \`category\` (${shapeOf(v.category)}): ` +
|
|
341
|
+
`an unrecognised category is not a dropped one, so it would read as a keep — ${UNREADABLE_VOTE}`,
|
|
342
|
+
);
|
|
343
|
+
}
|
|
344
|
+
if (v.severity !== undefined && !(typeof v.severity === "string" && Object.hasOwn(SEVERITY_RANK, v.severity))) {
|
|
345
|
+
throw new Error(
|
|
346
|
+
`${where}, from \`${v.verifier}\`, names an unknown \`severity\` (${shapeOf(v.severity)}): ` +
|
|
347
|
+
`it has no rank, so the severity sort would compare against NaN — ${UNREADABLE_VOTE}`,
|
|
348
|
+
);
|
|
349
|
+
}
|
|
350
|
+
return {
|
|
351
|
+
verifier: v.verifier,
|
|
352
|
+
real: v.real,
|
|
353
|
+
reason: v.reason,
|
|
354
|
+
...(v.category !== undefined ? { category: v.category as FindingCategory } : {}),
|
|
355
|
+
...(v.severity !== undefined ? { severity: v.severity as Severity } : {}),
|
|
356
|
+
};
|
|
357
|
+
});
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
export interface JuryConfig {
|
|
361
|
+
groupSize?: number;
|
|
362
|
+
quorum?: number;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
export interface JuryReading {
|
|
366
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
367
|
+
/** `true` only under a MEASURED reading that cleared the quorum. */
|
|
368
|
+
passed: boolean;
|
|
369
|
+
votes: number;
|
|
370
|
+
agree: number;
|
|
371
|
+
quorum: number;
|
|
372
|
+
groupSize: number;
|
|
373
|
+
unmeasuredReasons: string[];
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* Count the votes.
|
|
378
|
+
*
|
|
379
|
+
* Three ways this refuses rather than deciding, all of them the same doctrine
|
|
380
|
+
* #1187 states for the arbiter — **UNMEASURED fails, it never skips:**
|
|
381
|
+
*
|
|
382
|
+
* - **Fewer votes than the group size.** A verifier that did not report is not
|
|
383
|
+
* a "no" and not a "yes". Treating a short group as a complete one is how a
|
|
384
|
+
* quorum of three becomes a quorum of however many happened to answer, and
|
|
385
|
+
* the outcome looks identical either way.
|
|
386
|
+
* - **A repeated verifier id.** One agent run three times is one opinion.
|
|
387
|
+
* - **A quorum that is not a strict majority.** A configuration error that is
|
|
388
|
+
* undetectable from any single outcome.
|
|
389
|
+
*
|
|
390
|
+
* **The ballot size must EQUAL the declared group size, not merely reach it.**
|
|
391
|
+
* Accepting an over-size ballot was wrong in the same direction as everything
|
|
392
|
+
* else this module guards: with the 3/2 defaults, five votes of which two
|
|
393
|
+
* agree returned `passed: true` — 2 of 5, which is not a majority of anything,
|
|
394
|
+
* because the quorum was being compared against the *declaration* rather than
|
|
395
|
+
* against the ballot actually counted. A ballot whose cardinality disagrees
|
|
396
|
+
* with its declaration is UNMEASURED, not a smaller or a larger reading. A
|
|
397
|
+
* caller who genuinely convened five verifiers says `groupSize: 5`.
|
|
398
|
+
*/
|
|
399
|
+
export function juryReading(votes: readonly VerifierVote[], config: JuryConfig = {}): JuryReading {
|
|
400
|
+
const groupSize = config.groupSize ?? VERIFIER_GROUP_SIZE;
|
|
401
|
+
const quorum = config.quorum ?? VERIFIER_QUORUM;
|
|
402
|
+
const agree = votes.filter(v => v.real).length;
|
|
403
|
+
const base = { votes: votes.length, agree, quorum, groupSize };
|
|
404
|
+
const unmeasuredReasons: string[] = [];
|
|
405
|
+
|
|
406
|
+
if (quorum * 2 <= groupSize || quorum < 1) {
|
|
407
|
+
unmeasuredReasons.push(`${NON_MAJORITY_QUORUM}: ${quorum} of ${groupSize}`);
|
|
408
|
+
}
|
|
409
|
+
if (votes.length !== groupSize) {
|
|
410
|
+
unmeasuredReasons.push(`${INCOMPLETE_GROUP}: ${votes.length} of ${groupSize}`);
|
|
411
|
+
}
|
|
412
|
+
if (new Set(votes.map(v => v.verifier)).size !== votes.length) {
|
|
413
|
+
unmeasuredReasons.push(REPEATED_VERIFIER);
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
if (unmeasuredReasons.length > 0) {
|
|
417
|
+
return { ...base, reading: "UNMEASURED", passed: false, unmeasuredReasons };
|
|
418
|
+
}
|
|
419
|
+
return { ...base, reading: "MEASURED", passed: agree >= quorum, unmeasuredReasons };
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/**
|
|
423
|
+
* The category the jury reports.
|
|
424
|
+
*
|
|
425
|
+
* **A DROP category requires an outright majority of the real votes; a keep
|
|
426
|
+
* category needs only a plurality.** The asymmetry is the whole function, and
|
|
427
|
+
* it was measured rather than reasoned: under a plain plurality, a group of
|
|
428
|
+
* three that unanimously called a finding real, with **one** member tagging
|
|
429
|
+
* it `cleanup` and two tagging nothing, returned `cleanup` — one voice
|
|
430
|
+
* suppressing a finding the group passed.
|
|
431
|
+
*
|
|
432
|
+
* The source design drops style, diagnostics and cleanup because *the group*
|
|
433
|
+
* said so. A plurality of one is not the group, and the cost of the two error
|
|
434
|
+
* directions is not symmetric: wrongly keeping costs one comment thread,
|
|
435
|
+
* wrongly dropping withholds a real bug and leaves no artefact behind to find
|
|
436
|
+
* it by. So ties resolve toward keep, and a drop that cannot command a
|
|
437
|
+
* majority falls back to the best keep category the verifiers named, and only
|
|
438
|
+
* then to the keyword classifier.
|
|
439
|
+
*/
|
|
440
|
+
export function juryCategory(
|
|
441
|
+
finding: Pick<Finding, "title" | "body">,
|
|
442
|
+
votes: readonly VerifierVote[],
|
|
443
|
+
): FindingCategory {
|
|
444
|
+
const real = votes.filter(v => v.real);
|
|
445
|
+
const tally = new Map<FindingCategory, number>();
|
|
446
|
+
for (const v of real) {
|
|
447
|
+
if (v.category) tally.set(v.category, (tally.get(v.category) ?? 0) + 1);
|
|
448
|
+
}
|
|
449
|
+
const ranked = [...tally.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
|
|
450
|
+
const keep = ranked.find(([category]) => !DROPPED_CATEGORIES.has(category));
|
|
451
|
+
|
|
452
|
+
for (const [category, count] of ranked) {
|
|
453
|
+
if (!DROPPED_CATEGORIES.has(category)) return category;
|
|
454
|
+
// A drop needs a strict majority of the real votes, and must not merely
|
|
455
|
+
// tie with a keep category.
|
|
456
|
+
if (count * 2 > real.length && count > (keep?.[1] ?? 0)) return category;
|
|
457
|
+
break;
|
|
458
|
+
}
|
|
459
|
+
return keep?.[0] ?? classifyCategory(finding);
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
/**
|
|
463
|
+
* The severity tag.
|
|
464
|
+
*
|
|
465
|
+
* **`Pre-existing` is decided mechanically and beats any vote**, because it is
|
|
466
|
+
* the one tag of the three that is a fact about the diff rather than a
|
|
467
|
+
* judgement about the defect: a finding whose cited files are all absent from
|
|
468
|
+
* the change is about code the change never touched. Letting a verifier
|
|
469
|
+
* override that would put a judgement in front of a measurement.
|
|
470
|
+
*
|
|
471
|
+
* `changedFiles` absent means the diff was not read, so the pre-existing axis
|
|
472
|
+
* is simply not available — the votes decide, and with no votes carrying a
|
|
473
|
+
* tag the answer is `null` rather than a guessed `Important`.
|
|
474
|
+
*/
|
|
475
|
+
export function severityOf(
|
|
476
|
+
finding: Pick<Finding, "title" | "body">,
|
|
477
|
+
votes: readonly VerifierVote[],
|
|
478
|
+
changedFiles?: readonly string[],
|
|
479
|
+
): Severity | null {
|
|
480
|
+
if (changedFiles !== undefined) {
|
|
481
|
+
const changed = new Set(changedFiles.map(f => f.toLowerCase()));
|
|
482
|
+
const cited = citedPaths(finding);
|
|
483
|
+
if (cited.length > 0 && !cited.some(p => changed.has(p))) return "Pre-existing";
|
|
484
|
+
}
|
|
485
|
+
const tally = new Map<Severity, number>();
|
|
486
|
+
for (const v of votes) {
|
|
487
|
+
if (v.real && v.severity) tally.set(v.severity, (tally.get(v.severity) ?? 0) + 1);
|
|
488
|
+
}
|
|
489
|
+
const ranked = [...tally.entries()].sort((a, b) => b[1] - a[1] || SEVERITY_RANK[a[0]] - SEVERITY_RANK[b[0]]);
|
|
490
|
+
return ranked.length > 0 ? ranked[0][0] : null;
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
/** Repository-shaped paths a finding names, lowercased. Shared with the arbiter's key. */
|
|
494
|
+
function citedPaths(finding: Pick<Finding, "title" | "body">): string[] {
|
|
495
|
+
const out = new Set<string>();
|
|
496
|
+
for (const m of `${finding.title}\n${finding.body}`.matchAll(
|
|
497
|
+
/(?:[\w.@-]+\/)+[\w.-]+\.(?:ts|tsx|js|mjs|cjs|md|json|ya?ml|sh)\b/g,
|
|
498
|
+
)) {
|
|
499
|
+
out.add(m[0].toLowerCase());
|
|
500
|
+
}
|
|
501
|
+
return [...out];
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
// ── Where it goes ────────────────────────────────────────────────────────
|
|
505
|
+
|
|
506
|
+
/**
|
|
507
|
+
* What to do with a finding.
|
|
508
|
+
*
|
|
509
|
+
* `COMMENT` is the default and `ISSUE` is the exception. That is the inversion
|
|
510
|
+
* of what #1187 asked for, and it is the whole correction: a tracker issue is
|
|
511
|
+
* a thing nobody has to answer, so it accumulates; an inline comment blocks
|
|
512
|
+
* the merge until it is fixed or closed with a reason, so it does not.
|
|
513
|
+
*/
|
|
514
|
+
export type Disposition = "COMMENT" | "ISSUE" | "DROP";
|
|
515
|
+
|
|
516
|
+
export const DEFAULT_DISPOSITION: Disposition = "COMMENT";
|
|
517
|
+
|
|
518
|
+
/**
|
|
519
|
+
* The line that makes a comment a gate rather than a remark.
|
|
520
|
+
*
|
|
521
|
+
* The source design's whole mechanism for having no backlog is that **every
|
|
522
|
+
* finding has to be answered** — fixed, or the thread closed with a reason —
|
|
523
|
+
* and the PR cannot merge while one is open. A comment that carries no such
|
|
524
|
+
* obligation is a tracker issue with extra steps.
|
|
525
|
+
*/
|
|
526
|
+
export const MUST_BE_ANSWERED =
|
|
527
|
+
"Answer this before merge: fix it, or resolve this thread with a reason. " +
|
|
528
|
+
"A reason closes a finding; silence does not.";
|
|
529
|
+
|
|
530
|
+
/** The inline comment a surviving finding becomes. */
|
|
531
|
+
export function renderComment(
|
|
532
|
+
finding: Pick<Finding, "title" | "body">,
|
|
533
|
+
severity: Severity,
|
|
534
|
+
category: FindingCategory,
|
|
535
|
+
): string {
|
|
536
|
+
return `**${severity}** · _${category}_ — ${finding.title}\n\n${finding.body}\n\n${MUST_BE_ANSWERED}`;
|
|
537
|
+
}
|