rungate 0.8.6 → 0.8.8

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 CHANGED
@@ -1 +1 @@
1
- 992b213550a26275dd43d4fe59d078dddc39bbe7a25e60d9981b66fb913d049a
1
+ aa5de92c18a7ad774cc3515f189890d60c365654621a8966ece5b0a3d5dff616
@@ -514,9 +514,25 @@ export interface ReviewFinding {
514
514
  * Case and whitespace only. Not punctuation, and not stemming: two findings
515
515
  * that differ in a word are two findings, and a key that erases the
516
516
  * difference suppresses a real one.
517
+ *
518
+ * **The case fold is ASCII-only on purpose, and `.toLowerCase()` is wrong
519
+ * here.** This is one half of a pair: the generated jq re-derives the same key
520
+ * from a thread body with its own `norm`, which folds case with
521
+ * `ascii_downcase`. jq exposes no Unicode-aware downcase to match — its
522
+ * `builtins` carry `ascii_downcase` and `ascii_upcase` and nothing else — so
523
+ * the agreement can only be bought on this side. `.toLowerCase()` is
524
+ * Unicode-aware, so it folded `É` to `é` where jq left it alone, the two
525
+ * engines keyed one thread two ways, and a thread a human had resolved could
526
+ * never answer its finding. `test/ai-review-carry-forward.test.ts` (AC-C9)
527
+ * drives both engines and holds them to the same verdict.
528
+ *
529
+ * The whitespace half needs no such care: jq's `[[:space:]]+` and JS's `\s+`
530
+ * were measured to agree on NBSP, U+2028 and U+3000.
517
531
  */
518
532
  function normalise(v: unknown): string {
519
- return typeof v === "string" ? v.trim().toLowerCase().replace(/\s+/g, " ") : "";
533
+ return typeof v === "string"
534
+ ? v.trim().replace(/[A-Z]/g, c => c.toLowerCase()).replace(/\s+/g, " ")
535
+ : "";
520
536
  }
521
537
 
522
538
  /**
@@ -691,6 +707,110 @@ export function carryForward(
691
707
  return out;
692
708
  }
693
709
 
710
+ /* ──────────────── the same question, asked of the review threads ──────────
711
+ *
712
+ * `carryForward` above decides "is this finding still live" by comparing the
713
+ * TEXT at its cited line against the text recorded when it was raised. That
714
+ * is a heuristic over a moving document and #1601 is what it costs when it is
715
+ * wrong: a required check reported CLEAN over a live blocker for two rounds,
716
+ * because unrelated edits shifted the file and every finding read as
717
+ * resolved.
718
+ *
719
+ * A review thread answers the same question authoritatively. `isResolved` is
720
+ * a thing a PERSON did, on the finding itself, and no edit elsewhere in the
721
+ * file can forge it. #1618 is what makes the match possible at all: a posted
722
+ * thread now carries, base64 in an HTML comment, the key the finding was
723
+ * raised under.
724
+ *
725
+ * ## The two readings disagree, and the disagreement is the point
726
+ *
727
+ * Text-resolution says "the code moved". Thread-resolution says "a human
728
+ * accepted the answer". Only the second is a decision. The first is the one
729
+ * that re-raised one observation on #1614 twelve times across fifteen rounds,
730
+ * because the line numbers moved under it each round while the finding did
731
+ * not.
732
+ */
733
+
734
+ /** One review thread, reduced to the two facts the decision needs. */
735
+ export interface CarryThread {
736
+ /** The finding key the thread was posted under, per `threadKeyFrom`. */
737
+ key: string;
738
+ isResolved: boolean;
739
+ }
740
+
741
+ /**
742
+ * What was learned about the pull request's review threads.
743
+ *
744
+ * **Evidence is a PARAMETER, never fetched in here.** The decision has to be
745
+ * runnable against a reading that is empty, a reading that is wrong, and a
746
+ * reading that could not be taken — and a function that fetches its own
747
+ * evidence can only ever be tested against whatever the network returned.
748
+ */
749
+ export type ThreadReading =
750
+ | { status: "MEASURED"; threads: readonly CarryThread[] }
751
+ | { status: "UNMEASURED"; reason: string };
752
+
753
+ /**
754
+ * Carry forward every prior finding no review thread shows was ANSWERED.
755
+ *
756
+ * @returns `carried` — the findings still live — and `unmeasured`, the reason
757
+ * the thread list could not be read, or `null` when it was read. The two are
758
+ * reported separately on purpose: an empty `carried` after a failed fetch and
759
+ * an empty `carried` after a clean read are the same list and completely
760
+ * different facts.
761
+ *
762
+ * ## Every undecidable case CARRIES
763
+ *
764
+ * An unreadable thread list, a finding this caller cannot key, and a key no
765
+ * thread holds all carry. Re-raising something already dealt with is loud,
766
+ * cheap and self-correcting. Dropping a live finding is silent and permanent.
767
+ *
768
+ * ## A finding with any OPEN thread is unanswered
769
+ *
770
+ * Not "the first thread found", and not "any resolved thread". One
771
+ * observation produced twelve threads on #1614, so a reader that stops at the
772
+ * first key match answers a live finding by coincidence of the API's
773
+ * ordering. Every thread carrying the key must be resolved before the finding
774
+ * is.
775
+ */
776
+ export function carryForwardFromThreads(
777
+ prior: readonly CarriedFinding[],
778
+ reading: ThreadReading,
779
+ keyFor: (f: ReviewFinding) => string | null,
780
+ ): { carried: ReviewFinding[]; unmeasured: string | null } {
781
+ if (reading.status !== "MEASURED") {
782
+ return { carried: prior.map(e => e.finding), unmeasured: reading.reason };
783
+ }
784
+
785
+ // Fold the threads into one verdict per key BEFORE deciding anything, so
786
+ // the decision cannot depend on where a key's threads sat in the list.
787
+ const allResolved = new Map<string, boolean>();
788
+ for (const t of reading.threads) {
789
+ allResolved.set(t.key, (allResolved.get(t.key) ?? true) && t.isResolved === true);
790
+ }
791
+ // The empty key is refused on the FINDING side only, below, and once. It
792
+ // was refused here too until a battery showed neither guard alone could be
793
+ // made to fail: two deciders answering one question are behaviourally one,
794
+ // and no test can say which of them is live
795
+ // (`.claude/rules/checks-must-be-able-to-fail.md`). The surviving one is
796
+ // the stronger — it also refuses the `null` that `keyFor` returns, which a
797
+ // guard over `t.key` cannot see.
798
+
799
+ // ONE decider, and `!== true` is the whole of it. An unkeyable finding, a
800
+ // key no thread holds, and a key whose threads are not all resolved are
801
+ // three different reasons and one outcome, and they share a line so that a
802
+ // mutation of it moves all three. Spelling them as three branches would be
803
+ // three deciders agreeing — no behavioural test could tell which was live,
804
+ // and two of them would be dead (`.claude/rules/checks-must-be-able-to-fail.md`).
805
+ const carried: ReviewFinding[] = [];
806
+ for (const entry of prior) {
807
+ const key = keyFor(entry.finding);
808
+ const answered = typeof key === "string" && key !== "" && allResolved.get(key) === true;
809
+ if (!answered) carried.push(entry.finding);
810
+ }
811
+ return { carried, unmeasured: null };
812
+ }
813
+
694
814
  /* ───────────────── reading the ledger a previous round wrote ──────────────
695
815
  *
696
816
  * `lib/scaffold/ai-review-step.ts` upserts ONE comment per pull request
@@ -8,36 +8,41 @@
8
8
  * unresolved set — so a repeat became *marked* rather than *dropped*. This is
9
9
  * the half that drops it.
10
10
  *
11
- * ## Why the prior state arrives as a file and not as a fetch
11
+ * ## Since AC-1 the prior set is the pull request's review threads
12
+ *
13
+ * The ledger keyed a repeat by `file + cited line text + summary`, which a
14
+ * reformat moves — measured on #1616 as 11 threads for 3 findings. A thread
15
+ * is GitHub's own answer to the same question, so AC-1 moved the gate onto
16
+ * it: `priorKeysFrom` reads the list the carry step fetched and nothing else.
17
+ * The ledger reader is kept as `ledgerPriorKeysFrom`, called by no production
18
+ * path, until AC-5 stops writing the snapshot it parses.
12
19
  *
13
- * The generated job runs `ai-review-carry` → the reviewer →
14
- * `ai-review-persist`, **which upserts this round into the ledger comment** →
15
- * `ai-review-run`, which invokes the adjudicator. A gate that fetched the
16
- * ledger itself would read a comment that already contains the payload it is
17
- * deciding about: every finding would match a "prior" key that is its own,
18
- * every round would suppress everything, and the outcome would be CLEAN
19
- * forever. The carry step is the last position holding the state as it was
20
- * before the reviewer ran, so it writes a snapshot and this reads it.
20
+ * ## Why the prior state arrives as a file and not as a fetch
21
21
  *
22
- * ## Two files, because one of them cannot say why it is absent
22
+ * Unchanged, and for a sharper reason than before. The generated job runs
23
+ * `ai-review-carry` → the reviewer → `ai-review-threads` (the poster, **which
24
+ * posts this round's threads**) → `ai-review-run` (this gate). So a fetch
25
+ * here would not be safe at all: by the time this gate runs, the poster has
26
+ * already opened this round's threads, and a live fetch would read them as
27
+ * prior, suppress the entire payload and report CLEAN forever.
23
28
  *
24
- * The snapshot carries BYTES and exists only on the READ path. The carry file
25
- * carries the STATE and is written on every path by the single `carry_state`
26
- * site. An absent snapshot therefore never means "no earlier findings" — the
27
- * carry file says which of `AI_REVIEW_CARRY_READ`, `AI_REVIEW_CARRY_ABSENT`
28
- * and `AI_REVIEW_CARRY_UNMEASURED` produced it. Collapsing those is #1568, in
29
- * the half that decides a required check.
29
+ * The file is what makes the gate correct, and it does not depend on where in
30
+ * a YAML file somebody put a step. The carry step runs before the reviewer,
31
+ * so the list it writes cannot contain this round's work whatever the later
32
+ * order becomes. `test/ai-review-suppression.test.ts` (AS-4) asserts the
33
+ * ordering that matters — `ai-review-carry` precedes both the poster and this
34
+ * gate — rather than the one this comment used to assert.
30
35
  *
31
36
  * ## Every refusal suppresses NOTHING
32
37
  *
33
38
  * There is one direction of error this module is allowed to make. Re-posting
34
39
  * an advisory that was already answered is loud, cheap and self-correcting;
35
- * dropping a finding that is still live is silent and permanent. So an
36
- * unreadable carry file, an unreadable snapshot, a stale snapshot, an
37
- * unrecognised identity rule and a ledger that will not parse all produce the
38
- * same behaviour — report everything — and each produces a DIFFERENT sentence
39
- * saying so, because "nothing was a repeat" and "nothing could be compared"
40
- * are different facts about this round's report.
40
+ * dropping a finding that is still live is silent and permanent. So a thread
41
+ * list that was never fetched, one that was cut off mid-write, and one that
42
+ * parsed into something that is not a list all produce the same behaviour —
43
+ * report everything — and each produces a DIFFERENT sentence saying so
44
+ * (AC-4), because "nothing was a repeat" and "nothing could be compared" are
45
+ * different facts about this round's report.
41
46
  *
42
47
  * ## It never sees a blocking finding
43
48
  *
@@ -56,6 +61,7 @@ import {
56
61
  readLedger,
57
62
  type ReviewFinding,
58
63
  } from "./ai-review-rounds";
64
+ import { threadReadingFromJson } from "./ai-review-threads";
59
65
  import {
60
66
  AI_REVIEW_CARRY_ABSENT,
61
67
  AI_REVIEW_CARRY_READ,
@@ -67,10 +73,12 @@ import type { AiReviewSuppressionGate } from "./scaffold/ai-review-findings";
67
73
 
68
74
  /** What the gate reads, so a test can drive it without a filesystem. */
69
75
  export interface SuppressionInputs {
70
- /** The carry file's contents, or `null` when it could not be read. */
71
- carry: string | null;
72
- /** The snapshot's contents, or `null` when it could not be read. */
73
- snapshot: string | null;
76
+ /**
77
+ * The review-thread list the carry step fetched, or `null` when the file
78
+ * was not there. Since AC-1 this is the ONLY thing the gate decides from —
79
+ * see `priorKeysFrom`.
80
+ */
81
+ threads: string | null;
74
82
  /** The text at a finding's cited line NOW, or `undefined`. */
75
83
  lineTextFor: (finding: ReviewFinding) => string | undefined;
76
84
  }
@@ -81,114 +89,59 @@ export type PriorKeys =
81
89
  | { status: "UNMEASURED"; reason: string };
82
90
 
83
91
  /**
84
- * The carry file's first line, which is the one site that decided the state.
92
+ * THE PRIOR SET, read from the pull request's own review threads (AC-1).
85
93
  *
86
- * Read rather than re-derived: the walker already made this decision against
87
- * the live API, and a second reading here would be a second decider over the
88
- * same question — which is the shape #1568 cost three rounds of #1569.
89
- */
90
- export function carryStateOf(carry: string | null): string | null {
91
- if (carry === null) return null;
92
- const first = carry.split("\n", 1)[0] ?? "";
93
- const prefix = `${AI_REVIEW_CARRY_STATE_KEY}=`;
94
- return first.startsWith(prefix) ? first.slice(prefix.length).trim() : null;
95
- }
96
-
97
- /**
98
- * Split the snapshot into the round it precedes and the ledger body.
94
+ * ## Why a thread and not the ledger
99
95
  *
100
- * `round` is `null` when the header is missing or not an integer, and that is
101
- * a REFUSAL rather than a default: a snapshot that cannot say which round it
102
- * precedes cannot be shown to predate this one.
103
- */
104
- export function readSnapshot(snapshot: string): { round: number | null; body: string } {
105
- const at = snapshot.indexOf("\n");
106
- const head = at === -1 ? snapshot : snapshot.slice(0, at);
107
- const body = at === -1 ? "" : snapshot.slice(at + 1);
108
- const prefix = `${AI_REVIEW_SNAPSHOT_ROUND_KEY}=`;
109
- if (!head.startsWith(prefix)) return { round: null, body };
110
- const raw = head.slice(prefix.length).trim();
111
- return { round: /^\d+$/.test(raw) ? Number(raw) : null, body };
112
- }
113
-
114
- /**
115
- * Turn the two files into the keys earlier rounds raised, or the sentence
116
- * saying they could not be established.
96
+ * The ledger answers "was this raised before?" with a text heuristic —
97
+ * `file + the text at the cited line + summary` — and a reformat moves the
98
+ * key, so round 4 cannot tell it is re-raising round 1's finding. Measured on
99
+ * #1616: **11 threads for 3 distinct findings**, re-raised across four rounds
100
+ * while the line numbers moved under them. A thread is the authoritative
101
+ * answer to the same question: the comment is on the pull request, or it is
102
+ * not.
103
+ *
104
+ * ## A RESOLVED thread is still a prior key
105
+ *
106
+ * This is the one place this reader and `carryForwardFromThreads` deliberately
107
+ * disagree, and the difference is the question each is asking:
108
+ *
109
+ * | Reader | Question | Resolved thread |
110
+ * |---|---|---|
111
+ * | this gate | has this already been **raised**? | yes — do not post it twice |
112
+ * | carry-forward | is this still **unanswered**? | no — a human answered it |
113
+ *
114
+ * A gate that treated resolution as "not raised" would re-post a thread the
115
+ * moment someone resolved it, which is the duplicate-per-round failure the
116
+ * whole increment exists to prevent, aimed at the people who are doing the
117
+ * work.
118
+ *
119
+ * ## Self-suppression is prevented by WHERE THE LIST IS FETCHED, not by a guard
120
+ *
121
+ * The ledger reader needed a provenance header because the ledger is written
122
+ * *during* the job, before the adjudicator reads it. Threads are no better on
123
+ * that count — `ai-review-threads` posts this round's threads BEFORE
124
+ * `ai-review-run` adjudicates, so a list fetched at adjudication time would
125
+ * contain them.
126
+ *
127
+ * What rules self-suppression out is that the list is not fetched here. It is
128
+ * fetched by `ai-review-carry`, which runs before the reviewer and therefore
129
+ * before anything this round could have posted, and handed to this gate as a
130
+ * file. That property lives in the workflow's step order and is asserted
131
+ * there; see `test/ai-review-suppression.test.ts` (AS-4), which pins
132
+ * `ai-review-carry` ahead of both the poster and the adjudicator.
117
133
  *
118
134
  * Exported and pure so the battery can drive every refusal without a
119
135
  * filesystem, and so there is one place to mutate.
120
136
  */
121
- export function priorKeysFrom(carry: string | null, snapshot: string | null): PriorKeys {
122
- const state = carryStateOf(carry);
123
- if (state === null) {
124
- return {
125
- status: "UNMEASURED",
126
- reason:
127
- "the carry step's own reading could not be read, so whether this pull request has " +
128
- "earlier rounds is unknown",
129
- };
130
- }
131
- if (state === AI_REVIEW_CARRY_UNMEASURED) {
132
- return {
133
- status: "UNMEASURED",
134
- reason: "the carry step reported that the pull request's history could not be read",
135
- };
136
- }
137
- // A complete reading, and the answer is that there is nothing to compare
138
- // against. MEASURED with no keys, which is not the same statement as the
139
- // branch above and must not print the same sentence.
140
- if (state === AI_REVIEW_CARRY_ABSENT) return { status: "MEASURED", keys: [] };
141
- if (state !== AI_REVIEW_CARRY_READ) {
142
- return {
143
- status: "UNMEASURED",
144
- reason: `the carry step reported a state this reader does not know (${JSON.stringify(state)})`,
145
- };
146
- }
147
-
148
- if (snapshot === null) {
149
- return {
150
- status: "UNMEASURED",
151
- reason:
152
- "the carry step read the pull request's history and the copy it left for this step " +
153
- "could not be read",
154
- };
155
- }
156
- const { round, body } = readSnapshot(snapshot);
157
- if (round === null) {
158
- return {
159
- status: "UNMEASURED",
160
- reason:
161
- "the history copy does not say which round it precedes, so it cannot be shown to " +
162
- "predate this round's own findings",
163
- };
164
- }
165
-
166
- const reading = priorFindings(readLedger(body));
167
- if (reading.status !== AI_REVIEW_PRIOR_MEASURED) {
137
+ export function priorKeysFrom(threads: string | null): PriorKeys {
138
+ const reading = threadReadingFromJson(threads);
139
+ if (reading.status !== "MEASURED") {
168
140
  return { status: "UNMEASURED", reason: reading.reason };
169
141
  }
170
-
171
- // THE ORDERING GUARD. A snapshot taken after the persist step is the same
172
- // comment fetched the same way and is byte-shaped like a correct one; the
173
- // only tell is that it already holds this round. Without this, the wrong
174
- // ordering suppresses the entire payload and reports CLEAN every round.
175
- const stale = reading.prior.filter(p => typeof p.round === "number" && p.round >= round);
176
- if (stale.length > 0) {
177
- return {
178
- status: "UNMEASURED",
179
- reason:
180
- `the history copy holds ${stale.length} finding(s) from round ${round} or later, so it ` +
181
- `was taken AFTER this round was recorded rather than before it. Suppressing against it ` +
182
- `would drop this round's own findings`,
183
- };
184
- }
185
-
186
- // `unmeasuredRounds` and `unkeyableRounds` are deliberately NOT a refusal.
187
- // Both mean the key set is INCOMPLETE, and an incomplete key set suppresses
188
- // less than a complete one — the direction this module is allowed to be
189
- // wrong in. Refusing on them would turn a partially readable history into
190
- // no history at all, which is the same report with a worse sentence.
191
- return { status: "MEASURED", keys: reading.keys };
142
+ // Open and resolved alike. The fold that distinguishes them belongs to
143
+ // carry-forward, for the reason tabled above.
144
+ return { status: "MEASURED", keys: reading.threads.map(t => t.key) };
192
145
  }
193
146
 
194
147
  /**
@@ -201,7 +154,7 @@ export function priorKeysFrom(carry: string | null, snapshot: string | null): Pr
201
154
  */
202
155
  export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSuppressionGate {
203
156
  return (candidates: readonly unknown[]) => {
204
- const prior = priorKeysFrom(inputs.carry, inputs.snapshot);
157
+ const prior = priorKeysFrom(inputs.threads);
205
158
  if (prior.status === "UNMEASURED") {
206
159
  return { repeat: candidates.map(() => null), unmeasured: prior.reason };
207
160
  }