rungate 0.8.3 → 0.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -131,6 +131,8 @@ import {
131
131
  AI_REVIEW_SEVERITIES,
132
132
  AI_REVIEW_SEVERITY_KEY,
133
133
  AI_REVIEW_VERDICT_KEY,
134
+ SEVERITY_RANK,
135
+ type Severity,
134
136
  } from "./ai-review-step";
135
137
 
136
138
  export {
@@ -142,7 +144,9 @@ export {
142
144
  AI_REVIEW_SEVERITIES,
143
145
  AI_REVIEW_SEVERITY_KEY,
144
146
  AI_REVIEW_VERDICT_KEY,
147
+ SEVERITY_RANK,
145
148
  };
149
+ export type { Severity };
146
150
 
147
151
  /**
148
152
  * Percent-encode a value before it is interpolated into a workflow command.
@@ -176,8 +180,25 @@ export const AI_REVIEW_DETAIL_MAX = 300;
176
180
  * site in `main()`, because two escapers applied in sequence turn `%` into
177
181
  * `%2525` and the bug that produces is invisible until someone reads a log.
178
182
  * One rule, one binding, applied last.
183
+ *
184
+ * `tag` is CRC-B7's Important / Nit / Pre-existing, appended AFTER the cap
185
+ * rather than before it. A tag inside the capped region is a tag a long
186
+ * summary deletes, and the one finding whose attribution a reader most needs
187
+ * is the verbose one — "this is not your bug" truncated away reads as "this
188
+ * is your bug". `null` renders nothing at all, because a finding whose
189
+ * severity the contract does not declare has no tag, and an empty bracket
190
+ * would read as one.
191
+ *
192
+ * The INDEX is the payload index and stays the payload index whatever the
193
+ * display order is. The refusal and the advisory notice share this numbering
194
+ * (#1178), so a sort that renumbered would make `finding 3` mean two
195
+ * different findings in two annotations about the same run.
179
196
  */
180
- export function renderFinding(index: number, finding: Record<string, unknown>): string {
197
+ export function renderFinding(
198
+ index: number,
199
+ finding: Record<string, unknown>,
200
+ tag: Severity | null = null,
201
+ ): string {
181
202
  const f = AI_REVIEW_FINDING_FIELDS;
182
203
  const where = finding[f.file] !== undefined
183
204
  ? `${String(finding[f.file])}:${String(finding[f.line] ?? "?")}`
@@ -186,7 +207,9 @@ export function renderFinding(index: number, finding: Record<string, unknown>):
186
207
  ? String(finding[f.summary])
187
208
  : "(no summary recorded)";
188
209
  const line = `finding ${index} is ${String(finding[f.severity])} at ${where}: ${what}`;
189
- return line.length > AI_REVIEW_DETAIL_MAX ? `${line.slice(0, AI_REVIEW_DETAIL_MAX)}…` : line;
210
+ const body =
211
+ line.length > AI_REVIEW_DETAIL_MAX ? `${line.slice(0, AI_REVIEW_DETAIL_MAX)}…` : line;
212
+ return tag === null ? body : `${body} [${tag}]`;
190
213
  }
191
214
 
192
215
  /**
@@ -217,12 +240,22 @@ export function renderFinding(index: number, finding: Record<string, unknown>):
217
240
  * arm is unreachable from `aiReviewRefusal`. It exists because the function
218
241
  * is exported and `unknown[]` is what it is handed: a renderer that throws
219
242
  * on a shape it was told it would never see is a refusal nobody can read.
243
+ *
244
+ * The result is indexed BY PAYLOAD INDEX and is deliberately not sorted here.
245
+ * Callers that display it order it with `tagOrder`, and they have to: this
246
+ * array is subscripted by `advisoryNotice` (`all[i]`, where `i` is the item's
247
+ * position in `reported`), so a sort applied inside would silently re-point
248
+ * every one of those lookups at a different finding. Rendering and ordering
249
+ * are separate jobs and the bug that merges them is invisible.
220
250
  */
221
- export function renderCountedFindings(reported: unknown[] | null): string[] {
251
+ export function renderCountedFindings(
252
+ reported: unknown[] | null,
253
+ tags: readonly (Severity | null)[] | null = null,
254
+ ): string[] {
222
255
  if (reported === null) return [];
223
256
  return reported.map((item, i) =>
224
257
  item !== null && typeof item === "object" && !Array.isArray(item)
225
- ? renderFinding(i, item as Record<string, unknown>)
258
+ ? renderFinding(i, item as Record<string, unknown>, tags?.[i] ?? null)
226
259
  : `finding ${i} is ${JSON.stringify(item)}`,
227
260
  );
228
261
  }
@@ -242,6 +275,12 @@ export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
242
275
  */
243
276
  export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
244
277
 
278
+ /** CRC-N4 (#1586). Repeats that were dropped, named rather than counted. */
279
+ export const AI_REVIEW_SUPPRESSED_TITLE = "AI review repeats not reported again";
280
+
281
+ /** CRC-N4 (#1586). The history could not be compared — not "no repeats". */
282
+ export const AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE = "AI review repeat check UNMEASURED";
283
+
245
284
  /**
246
285
  * A stable identity for one finding, so an answer can name it.
247
286
  *
@@ -384,9 +423,17 @@ export function advisoryNotice(reading: AiReviewFindingsReading): string | null
384
423
  // out of the full render means this notice and the contradiction arm's list
385
424
  // come from one call of one function, which is what keeps them from drifting.
386
425
  const reported = reading.reported ?? [];
387
- const all = renderCountedFindings(reported);
388
- const rendered = advisory.map(item => {
389
- const i = reported.indexOf(item);
426
+ const all = renderCountedFindings(reported, reading.findingTags);
427
+ // CRC-B7's sort, applied to the DISPLAY and not to the payload. `all` stays
428
+ // subscripted by payload index — `tagOrder` returns indices into it — so
429
+ // every line still says `finding <payload index>` and still agrees with the
430
+ // refusal's numbering. Reordering `advisory` itself and re-rendering would
431
+ // renumber the tail from zero, which AD-2 reds on.
432
+ const rendered = tagOrder(
433
+ reading.findingTags,
434
+ advisory.map(item => reported.indexOf(item)),
435
+ ).map(i => {
436
+ const item = reported[i];
390
437
  const key =
391
438
  item !== null && typeof item === "object" && !Array.isArray(item)
392
439
  ? ` [key ${advisoryKey(item as Record<string, unknown>)}]`
@@ -395,7 +442,8 @@ export function advisoryNotice(reading: AiReviewFindingsReading): string | null
395
442
  });
396
443
 
397
444
  return (
398
- `${advisory.length} advisory finding(s) were counted and block nothing. ` +
445
+ `${advisory.length} advisory finding(s) were counted and block nothing, ` +
446
+ `in Important / Pre-existing / Nit order. ` +
399
447
  `${rendered.join("; ")}. ` +
400
448
  `Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
401
449
  `resolved with a reason, or filed, and this annotation is the only place ` +
@@ -690,6 +738,48 @@ export interface AiReviewFindingsReading {
690
738
  * Substitution*, in the place it decides a required check.
691
739
  */
692
740
  scopeDropped: string[] | null;
741
+ /**
742
+ * CRC-B7's tag for each entry of `reported`, BY PAYLOAD INDEX, or `null`
743
+ * when there was no payload to tag.
744
+ *
745
+ * Parallel to `reported` rather than keyed, for the reason
746
+ * `AiReviewJuryGate.wouldWithhold` is positional: a map from a finding
747
+ * identity would be a second derivation of that identity over a list
748
+ * already produced in order, and two findings sharing a key would share a
749
+ * tag. An entry is `null` when the finding's severity is one the contract
750
+ * does not declare — unclassified, which is not the same as `Nit`.
751
+ *
752
+ * Computed ONCE, during the payload pass, where `touched` exists. A
753
+ * renderer that re-derived it would have to rebuild the changed-path set,
754
+ * which is a second normaliser over the one input `partitionChangedFiles`
755
+ * already reduced.
756
+ */
757
+ findingTags: (Severity | null)[] | null;
758
+ /**
759
+ * Findings an earlier round already raised, DROPPED from this round's
760
+ * report (CRC-N4, #1586) — raw, named, in payload order.
761
+ *
762
+ * Never a count. "Three repeats were dropped" and "these three were
763
+ * dropped" differ exactly when somebody wants to know whether the drop was
764
+ * right, which is the only question anybody asks of a drop.
765
+ *
766
+ * `[]` means the reader ran and found no repeat. There is no `null`
767
+ * case — a run with no repeat reader simply suppresses nothing, and
768
+ * `suppressionUnmeasured` is what says the prior state could not be read.
769
+ */
770
+ suppressedReported: unknown[];
771
+ /** One line per entry in `suppressedReported`, in the same order. */
772
+ suppressionReasons: string[];
773
+ /**
774
+ * Why the prior state could not be established, or `null`.
775
+ *
776
+ * `null` with an empty `suppressedReported` is "the reader ran and nothing
777
+ * was a repeat". A sentence here is "nothing could be compared", and those
778
+ * are different facts — the second one means this round's report is a
779
+ * complete list that was never checked against the history, which is the
780
+ * distinction #1568 cost three rounds of #1569 to learn.
781
+ */
782
+ suppressionUnmeasured: string | null;
693
783
  }
694
784
 
695
785
  /**
@@ -704,15 +794,235 @@ export function severityBlocks(severity: unknown): boolean | null {
704
794
  return blocks === undefined ? null : blocks;
705
795
  }
706
796
 
797
+ /**
798
+ * Whether a finding names code this pull request touched. FOUR states, and
799
+ * the first two are the ones a boolean would destroy.
800
+ *
801
+ * `NOT_CHECKED` is "nobody handed this run a changed-file list", and
802
+ * `UNDECIDABLE` is "a list was read and this finding's path could not be
803
+ * compared to it". Neither is `PRE_EXISTING`, and collapsing either into it
804
+ * is the fail-open CRC-B7's first cut shipped: a spelling the comparison
805
+ * cannot read is never in the set, so every unreadable input demoted a
806
+ * `critical` to CLEAN. The direction this stage is allowed to be wrong in is
807
+ * toward blocking.
808
+ *
809
+ * **ONE binding, and the only place the question is answered.** `readPayload`
810
+ * asks it to decide whether a blocking finding is demoted; `findingTag` asks
811
+ * it to decide what the finding is labelled. Two sites answering it
812
+ * separately would be the fourth shape in
813
+ * `.claude/rules/checks-must-be-able-to-fail.md` — behaviourally one decider,
814
+ * of which a mutation leaves the other holding every case up — and they would
815
+ * be free to disagree, which is a run whose annotation says `Pre-existing`
816
+ * about a finding that blocked it.
817
+ *
818
+ * Both sides of the comparison go through `normaliseRepoPath`, which is also
819
+ * what makes the drop in `partitionChangedFiles` safe: an entry is dropped
820
+ * exactly when it normalises to `null`, and a finding naming that same path
821
+ * answers `UNDECIDABLE` here.
822
+ */
823
+ export type FindingPathScope = "NOT_CHECKED" | "UNDECIDABLE" | "IN_DIFF" | "PRE_EXISTING";
824
+
825
+ export function findingPathScope(
826
+ finding: Record<string, unknown>,
827
+ touched: ReadonlySet<string> | null,
828
+ ): FindingPathScope {
829
+ if (touched === null) return "NOT_CHECKED";
830
+ // `normaliseRepoPath` answers `null` for a non-string as well as for a
831
+ // string it cannot read, so there is no separate type test here. Whether a
832
+ // non-string `file` is additionally a CONTRACT violation is a different
833
+ // question with a different answer per severity, and `readPayload` owns it.
834
+ const named = normaliseRepoPath(finding[AI_REVIEW_FINDING_FIELDS.file]);
835
+ if (named === null) return "UNDECIDABLE";
836
+ return touched.has(named) ? "IN_DIFF" : "PRE_EXISTING";
837
+ }
838
+
839
+ /**
840
+ * CRC-B7's tag for one finding — `Important`, `Nit` or `Pre-existing`.
841
+ *
842
+ * A COMPOSITION of the two deciders that already exist, and not a third
843
+ * table. Attribution is asked first because it outranks magnitude: a defect
844
+ * the change did not introduce is `Pre-existing` whether it is `critical` or
845
+ * `info`, which is the whole of "a pre-existing bug does not read as the
846
+ * author's fault". Below that the tag is `severityBlocks`' own answer
847
+ * re-spelt — blocking is `Important`, advisory is `Nit` — read from
848
+ * `AI_REVIEW_SEVERITIES` rather than from a second list of severity words.
849
+ *
850
+ * `null` for a severity the contract does not declare. That reading is
851
+ * already UNMEASURED by the time anything displays it, and a guessed
852
+ * `Important` would be the module inventing the classification it refuses the
853
+ * payload for omitting.
854
+ *
855
+ * Applied to EVERY finding, advisory ones included, which is wider than the
856
+ * demotion in `readPayload` and deliberately so: the demotion changes what
857
+ * blocks and must only ever touch findings that would block, while the tag
858
+ * changes what a maintainer reads and an `info` about code on `main` is
859
+ * misattributed exactly as badly as a `critical` is. It decides nothing —
860
+ * `aiReviewExitCode` never sees it.
861
+ */
862
+ export function findingTag(
863
+ finding: Record<string, unknown>,
864
+ touched: ReadonlySet<string> | null,
865
+ ): Severity | null {
866
+ if (findingPathScope(finding, touched) === "PRE_EXISTING") return "Pre-existing";
867
+ const blocks = severityBlocks(finding[AI_REVIEW_SEVERITY_KEY]);
868
+ return blocks === null ? null : blocks ? "Important" : "Nit";
869
+ }
870
+
871
+ /**
872
+ * The rank an untagged finding sorts at — below every declared tag, derived
873
+ * from the table rather than written as a literal, so a fourth tag does not
874
+ * leave this number sitting in the middle of the order.
875
+ */
876
+ export const UNTAGGED_RANK = Object.keys(SEVERITY_RANK).length;
877
+
878
+ /**
879
+ * CRC-B7's sort: payload indices, in the order they should be DISPLAYED.
880
+ *
881
+ * Indices rather than rendered strings, because the index is the one thing
882
+ * the display order must not change. `renderFinding` prints `finding
883
+ * <payload index>` and the blocking annotation and the advisory notice share
884
+ * that numbering, so this reorders the lines and renumbers nothing —
885
+ * `test/ai-review-advisory-findings.test.ts` AD-2 reds on the other
886
+ * arrangement, correctly.
887
+ *
888
+ * **ONE comparator, exported, and the only ordering in this module.** The
889
+ * ties break on the payload index rather than on `Array.prototype.sort`'s
890
+ * stability, so the order is a total function of the input: a run that
891
+ * printed findings in one order and a re-run that printed them in another
892
+ * would be two readings of one payload.
893
+ */
894
+ export function tagOrder(
895
+ tags: readonly (Severity | null)[] | null,
896
+ indices: readonly number[],
897
+ ): number[] {
898
+ const rankOf = (i: number): number => {
899
+ const tag = tags?.[i] ?? null;
900
+ return tag === null ? UNTAGGED_RANK : SEVERITY_RANK[tag];
901
+ };
902
+ return [...indices].sort((a, b) => rankOf(a) - rankOf(b) || a - b);
903
+ }
904
+
905
+ /**
906
+ * Every finding's tag, by payload index. Non-objects tag `null`: they are
907
+ * already a `FINDING_NOT_AN_OBJECT` reason, and a shape with no severity has
908
+ * no tag to carry.
909
+ */
910
+ function tagsForPayload(
911
+ list: readonly unknown[],
912
+ touched: ReadonlySet<string> | null,
913
+ ): (Severity | null)[] {
914
+ return list.map(item =>
915
+ item !== null && typeof item === "object" && !Array.isArray(item)
916
+ ? findingTag(item as Record<string, unknown>, touched)
917
+ : null,
918
+ );
919
+ }
920
+
921
+ /**
922
+ * Findings that are reported on EVERY round, whatever an earlier round said.
923
+ *
924
+ * ## This is the whole of CRC-N4's safety, and it is named for what it protects
925
+ *
926
+ * The deployed reviewer prompt (`buildReviewPrompt`) tells the reviewer:
927
+ *
928
+ * > CHECK EACH CARRIED FINDING AGAINST THE CODE AND RE-REPORT THE ONES THAT
929
+ * > ARE STILL TRUE … A carried finding you silently leave out is a finding
930
+ * > that has stopped being reported, and that is how a live defect reaches a
931
+ * > green check.
932
+ *
933
+ * So on every round after the first, a live unresolved finding is **supposed**
934
+ * to be in the payload, and it is key-identical to the one the ledger
935
+ * recorded. Subtracting it is therefore not a de-duplication: it is the
936
+ * deletion of the one signal the gate has. MEASURED on the real functions
937
+ * before this was written — a round-1 blocking finding, re-reported on round 2
938
+ * exactly as instructed, run through `suppressRepeats` with the ledger's keys:
939
+ *
940
+ * ```
941
+ * kept: 0 suppressed: 1 severity of what survives: []
942
+ * ```
943
+ *
944
+ * `blocking.length === 0` → `blocked: false` → `CLEAN`, which is a green
945
+ * required check over a defect a previous round blocked on. That is
946
+ * SUCCESS.md claim 4 failing inside this repository's own merge gate.
947
+ *
948
+ * ## Unclassified is protected too, and that is the three-state reading
949
+ *
950
+ * `severityBlocks` answers `true`, `false`, or `null` for a severity the
951
+ * table does not declare. Only an explicit `false` — a severity this module
952
+ * knows and knows does not block — is ever offered for suppression. `null`
953
+ * is not "does not block"; it is "nobody classified this", and dropping it
954
+ * would let an unrecognised severity become the way round the exemption.
955
+ *
956
+ * ## Widening this is a decision about the merge gate
957
+ *
958
+ * Anything that makes this return `false` more often lets a repeat stop
959
+ * blocking. `test/ai-review-suppression.test.ts` mutates it to a constant
960
+ * `false` and asserts the verdict flips from BLOCKED to CLEAN — the count
961
+ * alone is not the assertion, because a count can stay right while the
962
+ * verdict moves, and the verdict is the thing that gates.
963
+ *
964
+ * Recorded as a declared deviation from `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`
965
+ * line 480, which says the adjudicator should drop any finding matching an
966
+ * earlier round's key. The prompt above is the newer artefact and the correct
967
+ * one; the deviations table carries the reasoning so a reader finds it there.
968
+ */
969
+ export function findingMustAlwaysBeReported(finding: unknown): boolean {
970
+ if (finding === null || typeof finding !== "object" || Array.isArray(finding)) return true;
971
+ const severity = (finding as Record<string, unknown>)[AI_REVIEW_FINDING_FIELDS.severity];
972
+ return severityBlocks(severity) !== false;
973
+ }
974
+
975
+ /**
976
+ * The cross-round repeat reader, INJECTED exactly as `AiReviewJuryGate` is
977
+ * and for the same mechanical reason: three mutation batteries copy this
978
+ * module into a scratch directory carrying only `./ai-review-step`, and
979
+ * `lib/ai-review-suppression.ts` pulls `lib/ai-review-rounds.ts` behind it.
980
+ * A mutant that died on module resolution would report zero findings, which
981
+ * reads exactly like a guard behaving differently.
982
+ *
983
+ * **It never sees a blocking finding.** The caller filters with
984
+ * `findingMustAlwaysBeReported` before offering anything, so the exemption is
985
+ * structural rather than a rule the gate is trusted to follow.
986
+ *
987
+ * **Positional, like the ballot.** A map keyed by a finding's identity would
988
+ * be a SECOND derivation of that identity over a list already produced in
989
+ * order, and two findings sharing a key would share a verdict.
990
+ */
991
+ export interface AiReviewSuppressionGate {
992
+ (candidates: readonly unknown[]): {
993
+ /**
994
+ * One entry per candidate, IN INPUT ORDER: the sentence saying an earlier
995
+ * round already raised it, or `null` to report it.
996
+ */
997
+ repeat: readonly (string | null)[];
998
+ /**
999
+ * Why the prior state could not be established, or `null` when it was.
1000
+ * An unmeasured prior suppresses NOTHING — the direction this is allowed
1001
+ * to be wrong in is toward reporting a repeat twice, never toward
1002
+ * dropping something live.
1003
+ */
1004
+ unmeasured: string | null;
1005
+ };
1006
+ }
1007
+
707
1008
  function unmeasured(
708
1009
  reasons: AiReviewUnmeasuredReason[],
709
1010
  detail: string[],
710
1011
  reported: unknown[] | null = null,
1012
+ findingTags: (Severity | null)[] | null = null,
711
1013
  ): AiReviewFindingsReading {
712
1014
  return {
713
1015
  outcome: "UNMEASURED",
714
1016
  blocked: null,
715
1017
  reported,
1018
+ // Empty rather than null, and that is not the usual three-state reading
1019
+ // being skipped: `suppressionUnmeasured` is the field that says the
1020
+ // prior state was not established, and on an UNMEASURED payload it is
1021
+ // `readAiReviewFindings` that fills both from what `readPayload`
1022
+ // appended. Nothing was dropped on any path that reaches here.
1023
+ suppressedReported: [],
1024
+ suppressionReasons: [],
1025
+ suppressionUnmeasured: null,
716
1026
  blockingReported: null,
717
1027
  verdict: null,
718
1028
  unmeasuredReasons: reasons,
@@ -720,6 +1030,7 @@ function unmeasured(
720
1030
  scope: scopeNotSupplied(),
721
1031
  unlocatableReported: null,
722
1032
  scopeDropped: null,
1033
+ findingTags,
723
1034
  };
724
1035
  }
725
1036
 
@@ -748,6 +1059,7 @@ function withScope(
748
1059
  [...reading.unmeasuredReasons, scope.reason],
749
1060
  [...reading.detail, scope.detail],
750
1061
  reading.reported,
1062
+ reading.findingTags,
751
1063
  )
752
1064
  : reading;
753
1065
  return { ...merged, scope, unlocatableReported, scopeDropped };
@@ -796,24 +1108,39 @@ function withScope(
796
1108
  export function readAiReviewFindings(
797
1109
  raw: string | null,
798
1110
  scope: AiReviewScopeReading = scopeNotSupplied(),
1111
+ suppress: AiReviewSuppressionGate | null = null,
799
1112
  ): AiReviewFindingsReading {
800
1113
  const preExisting: unknown[] = [];
801
1114
  // Appended to by `readPayload`, for the same reason `preExisting` is: the
802
1115
  // entries belong to the reading its caller composes, and every early return
803
1116
  // in there is a state in which the split had not happened yet.
804
1117
  const dropped: string[] = [];
1118
+ // #1586, by the same arrangement and for the same reason.
1119
+ const suppressed: unknown[] = [];
1120
+ const suppression: { reasons: string[]; unmeasured: string | null } = {
1121
+ reasons: [],
1122
+ unmeasured: null,
1123
+ };
805
1124
  const base = readPayload(
806
1125
  raw,
807
1126
  scope.status === "MEASURED" ? scope.files : undefined,
808
1127
  preExisting,
809
1128
  dropped,
1129
+ suppress,
1130
+ suppressed,
1131
+ suppression,
810
1132
  );
811
- return withScope(
812
- base,
813
- scope,
814
- scope.status === "MEASURED" ? preExisting : null,
815
- scope.status === "MEASURED" ? dropped : null,
816
- );
1133
+ return {
1134
+ ...withScope(
1135
+ base,
1136
+ scope,
1137
+ scope.status === "MEASURED" ? preExisting : null,
1138
+ scope.status === "MEASURED" ? dropped : null,
1139
+ ),
1140
+ suppressedReported: suppressed,
1141
+ suppressionReasons: suppression.reasons,
1142
+ suppressionUnmeasured: suppression.unmeasured,
1143
+ };
817
1144
  }
818
1145
 
819
1146
  /**
@@ -831,6 +1158,9 @@ function readPayload(
831
1158
  changedFiles: readonly string[] | undefined,
832
1159
  preExisting: unknown[],
833
1160
  dropped: string[],
1161
+ suppress: AiReviewSuppressionGate | null,
1162
+ suppressedOut: unknown[],
1163
+ suppressionOut: { reasons: string[]; unmeasured: string | null },
834
1164
  ): AiReviewFindingsReading {
835
1165
  if (raw === null) {
836
1166
  return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
@@ -923,7 +1253,65 @@ function readPayload(
923
1253
  /** How many findings CRC-B7 demoted. See the `agreed` computation below. */
924
1254
  let demoted = 0;
925
1255
 
1256
+ // ── CRC-N4, and the ONE site a repeat is dropped (#1586) ───────────────
1257
+ //
1258
+ // BEFORE the classification below, so a suppressed finding is absent from
1259
+ // `reported`, from the annotation and from the ledger alike — "dropped
1260
+ // everywhere or nowhere". A finding filtered out of one projection and
1261
+ // left in another is two answers to one question.
1262
+ //
1263
+ // Only findings `findingMustAlwaysBeReported` declines to protect are ever
1264
+ // OFFERED. The exemption is therefore structural: there is no argument the
1265
+ // gate can return that drops a blocking finding, because a blocking
1266
+ // finding is never in the list it is handed. See that predicate for the
1267
+ // measurement that made this the design.
1268
+ const offered: unknown[] = [];
1269
+ const offeredAt: number[] = [];
926
1270
  list.forEach((item, i) => {
1271
+ if (!findingMustAlwaysBeReported(item)) {
1272
+ offered.push(item);
1273
+ offeredAt.push(i);
1274
+ }
1275
+ });
1276
+ /** Per-index reason, or null to report. Positional, never keyed. */
1277
+ const repeatOf: (string | null)[] = list.map(() => null);
1278
+ let suppressionUnmeasured: string | null = null;
1279
+ if (suppress !== null && offered.length > 0) {
1280
+ try {
1281
+ const verdict = suppress(offered);
1282
+ suppressionUnmeasured = verdict.unmeasured;
1283
+ // A gate that answered about a different number of findings than it
1284
+ // was handed has lost the positional join, and a misaligned verdict
1285
+ // suppresses the wrong finding. Refuse the whole reading rather than
1286
+ // apply part of it.
1287
+ if (verdict.repeat.length !== offered.length) {
1288
+ suppressionUnmeasured =
1289
+ `the repeat reader answered about ${verdict.repeat.length} finding(s) and was handed ` +
1290
+ `${offered.length}, so no answer could be matched to a finding and nothing was ` +
1291
+ `suppressed. Every finding this round raised is reported.`;
1292
+ } else {
1293
+ verdict.repeat.forEach((why, k) => {
1294
+ if (typeof why === "string") repeatOf[offeredAt[k]!] = why;
1295
+ });
1296
+ }
1297
+ } catch (e) {
1298
+ // FAIL TOWARD REPORTING. A reader that threw has established nothing,
1299
+ // and the cost of being wrong here is one advisory printed twice —
1300
+ // against a live finding dropped, which is silent and permanent.
1301
+ suppressionUnmeasured =
1302
+ `the repeat reader threw and nothing was suppressed: ${(e as Error).message}. Every ` +
1303
+ `finding this round raised is reported, including any an earlier round already raised.`;
1304
+ }
1305
+ }
1306
+ // Appended rather than returned, for `preExisting`'s reason: these belong
1307
+ // to the reading the caller composes, and every early return above is a
1308
+ // state in which no suppression had happened yet.
1309
+ suppressedOut.push(...list.filter((_, i) => repeatOf[i] !== null));
1310
+ suppressionOut.reasons.push(...repeatOf.filter((r): r is string => r !== null));
1311
+ suppressionOut.unmeasured = suppressionUnmeasured;
1312
+ const kept = list.filter((_, i) => repeatOf[i] === null);
1313
+
1314
+ kept.forEach((item, i) => {
927
1315
  if (item === null || typeof item !== "object" || Array.isArray(item)) {
928
1316
  reasons.push("FINDING_NOT_AN_OBJECT");
929
1317
  detail.push(`finding ${i} is not an object`);
@@ -989,17 +1377,19 @@ function readPayload(
989
1377
  );
990
1378
  return;
991
1379
  }
992
- const named = normaliseRepoPath(declared);
1380
+ // THE one decider, shared with `findingTag`. Re-reading the path
1381
+ // here would let the demotion and the tag disagree about one finding.
1382
+ const scoped = findingPathScope(finding, touched);
993
1383
  // Undecidable is NOT pre-existing. The finding is well-formed and
994
1384
  // this reader simply cannot resolve its path, so it keeps blocking —
995
1385
  // the direction this stage is allowed to be wrong in.
996
- if (named === null) {
1386
+ if (scoped === "UNDECIDABLE") {
997
1387
  detail.push(
998
1388
  `finding ${i} declares ${JSON.stringify(declared)}, which could not be read as a ` +
999
1389
  `repository path, so it could not be compared to the changed-file list. It ` +
1000
1390
  `keeps blocking: undecidable is not pre-existing`,
1001
1391
  );
1002
- } else if (!touched.has(named)) {
1392
+ } else if (scoped === "PRE_EXISTING") {
1003
1393
  demoted += 1;
1004
1394
  // #1204's half that survived the merge: WHICH findings were
1005
1395
  // demoted, not just how many. The scope line reports it, so a
@@ -1033,7 +1423,12 @@ function readPayload(
1033
1423
  // for the ledger and the annotation; this list is untouched by it.
1034
1424
  // See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
1035
1425
  blocking.push(item);
1036
- detail.push(renderFinding(i, finding));
1426
+ // Tagged through the same binding every other render uses. By here the
1427
+ // tag is `Important` by construction — the severity blocks and the
1428
+ // finding is not Pre-existing, or the branch above would have returned
1429
+ // — so this list is not re-ordered: a sort over one rank reorders
1430
+ // nothing, and applying one would be a comparator no case could redden.
1431
+ detail.push(renderFinding(i, finding, findingTag(finding, touched)));
1037
1432
  }
1038
1433
  });
1039
1434
 
@@ -1054,7 +1449,14 @@ function readPayload(
1054
1449
  }
1055
1450
  }
1056
1451
 
1057
- if (reasons.length > 0) return unmeasured(reasons, detail, list);
1452
+ // Over `kept`, not over `list` (#1586). `findingTags` is parallel to
1453
+ // `reported` by index, and `reported` is now the payload MINUS the repeats
1454
+ // this round suppressed — tagging the unfiltered list would shift every tag
1455
+ // by the number of findings dropped before it, so a `Nit` would be printed
1456
+ // against an `Important`. The two have to be derived from one array.
1457
+ const tags = tagsForPayload(kept, touched);
1458
+
1459
+ if (reasons.length > 0) return unmeasured(reasons, detail, kept, tags);
1058
1460
 
1059
1461
  // The decision, and the only place it is made. `verdict` is compared to it
1060
1462
  // afterwards; it never contributes to it.
@@ -1077,17 +1479,24 @@ function readPayload(
1077
1479
  return {
1078
1480
  outcome,
1079
1481
  blocked,
1080
- reported: list,
1482
+ reported: kept,
1081
1483
  blockingReported: blocking,
1082
1484
  verdict,
1083
1485
  unmeasuredReasons: [],
1084
1486
  detail,
1487
+ // `readAiReviewFindings` owns these three, the way `withScope` owns the
1488
+ // two below: `readPayload` appended them to the arrays it was handed,
1489
+ // and a value here would be a second statement about the same input.
1490
+ suppressedReported: [],
1491
+ suppressionReasons: [],
1492
+ suppressionUnmeasured: null,
1085
1493
  // Both of these are `withScope`'s to set, and it is the only site that
1086
1494
  // sets either. A value here would be a second statement about the same
1087
1495
  // input, and the two could disagree.
1088
1496
  scope: scopeNotSupplied(),
1089
1497
  unlocatableReported: null,
1090
1498
  scopeDropped: null,
1499
+ findingTags: tags,
1091
1500
  };
1092
1501
  }
1093
1502
 
@@ -1230,6 +1639,7 @@ export function partitionChangedFiles(
1230
1639
  export function readAiReviewFindingsFile(
1231
1640
  path: string,
1232
1641
  scope: AiReviewScopeReading = scopeNotSupplied(),
1642
+ suppress: AiReviewSuppressionGate | null = null,
1233
1643
  ): AiReviewFindingsReading {
1234
1644
  let raw: string;
1235
1645
  try {
@@ -1254,7 +1664,7 @@ export function readAiReviewFindingsFile(
1254
1664
  null,
1255
1665
  );
1256
1666
  }
1257
- return readAiReviewFindings(raw, scope);
1667
+ return readAiReviewFindings(raw, scope, suppress);
1258
1668
  }
1259
1669
 
1260
1670
  /** The sentence a refusal prints, or `null` when there is nothing to refuse. */
@@ -1295,9 +1705,16 @@ export function aiReviewRefusal(reading: AiReviewFindingsReading): string | null
1295
1705
  // Used INSTEAD of `detail` rather than appended to it. The two overlap
1296
1706
  // exactly on the blocking findings, so appending would print those
1297
1707
  // twice, and a duplicate reads as two findings.
1298
- const counted = renderCountedFindings(reading.reported);
1299
- const payload = counted.length > 0
1300
- ? `${counted.join("; ")}. `
1708
+ const counted = renderCountedFindings(reading.reported, reading.findingTags);
1709
+ // Same sort, same binding, same payload numbering. The contradiction
1710
+ // arm is the one place every counted finding is printed together, so
1711
+ // it is where an unordered list costs the most.
1712
+ const ordered = tagOrder(
1713
+ reading.findingTags,
1714
+ counted.map((_, i) => i),
1715
+ ).map(i => counted[i]);
1716
+ const payload = ordered.length > 0
1717
+ ? `${ordered.join("; ")}. `
1301
1718
  : `The payload records no findings at all. `;
1302
1719
  return (
1303
1720
  `The AI review's verdict ${JSON.stringify(reading.verdict)} contradicts its ` +
@@ -1484,7 +1901,7 @@ export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
1484
1901
  * outcome line and the scope line, because the generated step reads the
1485
1902
  * outcome line before it reads the exit code.
1486
1903
  */
1487
- function readArgv(argv: string[]): AiReviewFindingsReading {
1904
+ function readArgv(argv: string[], suppress: AiReviewSuppressionGate | null): AiReviewFindingsReading {
1488
1905
  const extra = argumentsBeyondTheContract(argv);
1489
1906
  if (extra.length > 0) {
1490
1907
  // Scope is NOT read here. The argv is already known to be a shape this
@@ -1517,7 +1934,7 @@ function readArgv(argv: string[]): AiReviewFindingsReading {
1517
1934
  null,
1518
1935
  null,
1519
1936
  )
1520
- : readAiReviewFindingsFile(path, scope);
1937
+ : readAiReviewFindingsFile(path, scope, suppress);
1521
1938
  }
1522
1939
 
1523
1940
  /**
@@ -1527,8 +1944,12 @@ function readArgv(argv: string[]): AiReviewFindingsReading {
1527
1944
  * Returns the exit code rather than calling `process.exit`, so a test can run
1528
1945
  * it in-process as well as spawn it.
1529
1946
  */
1530
- export function main(argv: string[], jury: AiReviewJuryGate | null = null): number {
1531
- const reading = readArgv(argv);
1947
+ export function main(
1948
+ argv: string[],
1949
+ jury: AiReviewJuryGate | null = null,
1950
+ suppress: AiReviewSuppressionGate | null = null,
1951
+ ): number {
1952
+ const reading = readArgv(argv, suppress);
1532
1953
 
1533
1954
  // CRC-B4, AFTER the reading and feeding nothing back into it.
1534
1955
  //
@@ -1642,6 +2063,42 @@ export function main(argv: string[], jury: AiReviewJuryGate | null = null): numb
1642
2063
  console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
1643
2064
  }
1644
2065
 
2066
+ // CRC-N4's reading, on its own title (#1586). A `::notice`, because a
2067
+ // repeat that was dropped is the mechanism working and nothing about it
2068
+ // is a problem with the pull request.
2069
+ //
2070
+ // It NAMES them. A count cannot be argued with and cannot be audited: the
2071
+ // only question anybody asks of a suppression is whether it was right,
2072
+ // and that question needs the finding. These are advisory by construction
2073
+ // — `findingMustAlwaysBeReported` never offers a blocking finding — so
2074
+ // this annotation is the entire record that they existed.
2075
+ if (reading.suppressedReported.length > 0) {
2076
+ console.log(
2077
+ `::notice title=${AI_REVIEW_SUPPRESSED_TITLE}::${escapeAnnotation(
2078
+ `${reading.suppressedReported.length} advisory finding(s) were raised on an earlier ` +
2079
+ `round of this pull request and are not reported again: ` +
2080
+ `${reading.suppressionReasons.join("; ")}. A BLOCKING finding is never suppressed, ` +
2081
+ `on any round, at any key — it is re-reported and it blocks exactly as it did the ` +
2082
+ `first time.`,
2083
+ )}`,
2084
+ );
2085
+ }
2086
+
2087
+ // A `::warning`, and the state is NAMED, for `AI_REVIEW_JURY_UNMEASURED`'s
2088
+ // reason. An unreadable history that printed nothing would make "no
2089
+ // repeats were found" and "the history could not be compared" the same
2090
+ // observation, which is #1568 arriving one subsystem over.
2091
+ if (reading.suppressionUnmeasured !== null) {
2092
+ console.log(
2093
+ `::warning title=${AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE}::${escapeAnnotation(
2094
+ `What earlier rounds of this pull request raised could not be established: ` +
2095
+ `${reading.suppressionUnmeasured}. Nothing was suppressed, so this round's report ` +
2096
+ `is complete and was simply never compared against the history. No finding's ` +
2097
+ `status changed either way.`,
2098
+ )}`,
2099
+ );
2100
+ }
2101
+
1645
2102
  // The quorum's own reading, on its own title, and emitted whatever the
1646
2103
  // outcome was. The ledger row is the durable record and it lives on the
1647
2104
  // runner, which dies with the job; this annotation is the only part of