rungate 0.8.3 → 0.8.4

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
  }
@@ -384,9 +417,17 @@ export function advisoryNotice(reading: AiReviewFindingsReading): string | null
384
417
  // out of the full render means this notice and the contradiction arm's list
385
418
  // come from one call of one function, which is what keeps them from drifting.
386
419
  const reported = reading.reported ?? [];
387
- const all = renderCountedFindings(reported);
388
- const rendered = advisory.map(item => {
389
- const i = reported.indexOf(item);
420
+ const all = renderCountedFindings(reported, reading.findingTags);
421
+ // CRC-B7's sort, applied to the DISPLAY and not to the payload. `all` stays
422
+ // subscripted by payload index — `tagOrder` returns indices into it — so
423
+ // every line still says `finding <payload index>` and still agrees with the
424
+ // refusal's numbering. Reordering `advisory` itself and re-rendering would
425
+ // renumber the tail from zero, which AD-2 reds on.
426
+ const rendered = tagOrder(
427
+ reading.findingTags,
428
+ advisory.map(item => reported.indexOf(item)),
429
+ ).map(i => {
430
+ const item = reported[i];
390
431
  const key =
391
432
  item !== null && typeof item === "object" && !Array.isArray(item)
392
433
  ? ` [key ${advisoryKey(item as Record<string, unknown>)}]`
@@ -395,7 +436,8 @@ export function advisoryNotice(reading: AiReviewFindingsReading): string | null
395
436
  });
396
437
 
397
438
  return (
398
- `${advisory.length} advisory finding(s) were counted and block nothing. ` +
439
+ `${advisory.length} advisory finding(s) were counted and block nothing, ` +
440
+ `in Important / Pre-existing / Nit order. ` +
399
441
  `${rendered.join("; ")}. ` +
400
442
  `Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
401
443
  `resolved with a reason, or filed, and this annotation is the only place ` +
@@ -690,6 +732,23 @@ export interface AiReviewFindingsReading {
690
732
  * Substitution*, in the place it decides a required check.
691
733
  */
692
734
  scopeDropped: string[] | null;
735
+ /**
736
+ * CRC-B7's tag for each entry of `reported`, BY PAYLOAD INDEX, or `null`
737
+ * when there was no payload to tag.
738
+ *
739
+ * Parallel to `reported` rather than keyed, for the reason
740
+ * `AiReviewJuryGate.wouldWithhold` is positional: a map from a finding
741
+ * identity would be a second derivation of that identity over a list
742
+ * already produced in order, and two findings sharing a key would share a
743
+ * tag. An entry is `null` when the finding's severity is one the contract
744
+ * does not declare — unclassified, which is not the same as `Nit`.
745
+ *
746
+ * Computed ONCE, during the payload pass, where `touched` exists. A
747
+ * renderer that re-derived it would have to rebuild the changed-path set,
748
+ * which is a second normaliser over the one input `partitionChangedFiles`
749
+ * already reduced.
750
+ */
751
+ findingTags: (Severity | null)[] | null;
693
752
  }
694
753
 
695
754
  /**
@@ -704,10 +763,135 @@ export function severityBlocks(severity: unknown): boolean | null {
704
763
  return blocks === undefined ? null : blocks;
705
764
  }
706
765
 
766
+ /**
767
+ * Whether a finding names code this pull request touched. FOUR states, and
768
+ * the first two are the ones a boolean would destroy.
769
+ *
770
+ * `NOT_CHECKED` is "nobody handed this run a changed-file list", and
771
+ * `UNDECIDABLE` is "a list was read and this finding's path could not be
772
+ * compared to it". Neither is `PRE_EXISTING`, and collapsing either into it
773
+ * is the fail-open CRC-B7's first cut shipped: a spelling the comparison
774
+ * cannot read is never in the set, so every unreadable input demoted a
775
+ * `critical` to CLEAN. The direction this stage is allowed to be wrong in is
776
+ * toward blocking.
777
+ *
778
+ * **ONE binding, and the only place the question is answered.** `readPayload`
779
+ * asks it to decide whether a blocking finding is demoted; `findingTag` asks
780
+ * it to decide what the finding is labelled. Two sites answering it
781
+ * separately would be the fourth shape in
782
+ * `.claude/rules/checks-must-be-able-to-fail.md` — behaviourally one decider,
783
+ * of which a mutation leaves the other holding every case up — and they would
784
+ * be free to disagree, which is a run whose annotation says `Pre-existing`
785
+ * about a finding that blocked it.
786
+ *
787
+ * Both sides of the comparison go through `normaliseRepoPath`, which is also
788
+ * what makes the drop in `partitionChangedFiles` safe: an entry is dropped
789
+ * exactly when it normalises to `null`, and a finding naming that same path
790
+ * answers `UNDECIDABLE` here.
791
+ */
792
+ export type FindingPathScope = "NOT_CHECKED" | "UNDECIDABLE" | "IN_DIFF" | "PRE_EXISTING";
793
+
794
+ export function findingPathScope(
795
+ finding: Record<string, unknown>,
796
+ touched: ReadonlySet<string> | null,
797
+ ): FindingPathScope {
798
+ if (touched === null) return "NOT_CHECKED";
799
+ // `normaliseRepoPath` answers `null` for a non-string as well as for a
800
+ // string it cannot read, so there is no separate type test here. Whether a
801
+ // non-string `file` is additionally a CONTRACT violation is a different
802
+ // question with a different answer per severity, and `readPayload` owns it.
803
+ const named = normaliseRepoPath(finding[AI_REVIEW_FINDING_FIELDS.file]);
804
+ if (named === null) return "UNDECIDABLE";
805
+ return touched.has(named) ? "IN_DIFF" : "PRE_EXISTING";
806
+ }
807
+
808
+ /**
809
+ * CRC-B7's tag for one finding — `Important`, `Nit` or `Pre-existing`.
810
+ *
811
+ * A COMPOSITION of the two deciders that already exist, and not a third
812
+ * table. Attribution is asked first because it outranks magnitude: a defect
813
+ * the change did not introduce is `Pre-existing` whether it is `critical` or
814
+ * `info`, which is the whole of "a pre-existing bug does not read as the
815
+ * author's fault". Below that the tag is `severityBlocks`' own answer
816
+ * re-spelt — blocking is `Important`, advisory is `Nit` — read from
817
+ * `AI_REVIEW_SEVERITIES` rather than from a second list of severity words.
818
+ *
819
+ * `null` for a severity the contract does not declare. That reading is
820
+ * already UNMEASURED by the time anything displays it, and a guessed
821
+ * `Important` would be the module inventing the classification it refuses the
822
+ * payload for omitting.
823
+ *
824
+ * Applied to EVERY finding, advisory ones included, which is wider than the
825
+ * demotion in `readPayload` and deliberately so: the demotion changes what
826
+ * blocks and must only ever touch findings that would block, while the tag
827
+ * changes what a maintainer reads and an `info` about code on `main` is
828
+ * misattributed exactly as badly as a `critical` is. It decides nothing —
829
+ * `aiReviewExitCode` never sees it.
830
+ */
831
+ export function findingTag(
832
+ finding: Record<string, unknown>,
833
+ touched: ReadonlySet<string> | null,
834
+ ): Severity | null {
835
+ if (findingPathScope(finding, touched) === "PRE_EXISTING") return "Pre-existing";
836
+ const blocks = severityBlocks(finding[AI_REVIEW_SEVERITY_KEY]);
837
+ return blocks === null ? null : blocks ? "Important" : "Nit";
838
+ }
839
+
840
+ /**
841
+ * The rank an untagged finding sorts at — below every declared tag, derived
842
+ * from the table rather than written as a literal, so a fourth tag does not
843
+ * leave this number sitting in the middle of the order.
844
+ */
845
+ export const UNTAGGED_RANK = Object.keys(SEVERITY_RANK).length;
846
+
847
+ /**
848
+ * CRC-B7's sort: payload indices, in the order they should be DISPLAYED.
849
+ *
850
+ * Indices rather than rendered strings, because the index is the one thing
851
+ * the display order must not change. `renderFinding` prints `finding
852
+ * <payload index>` and the blocking annotation and the advisory notice share
853
+ * that numbering, so this reorders the lines and renumbers nothing —
854
+ * `test/ai-review-advisory-findings.test.ts` AD-2 reds on the other
855
+ * arrangement, correctly.
856
+ *
857
+ * **ONE comparator, exported, and the only ordering in this module.** The
858
+ * ties break on the payload index rather than on `Array.prototype.sort`'s
859
+ * stability, so the order is a total function of the input: a run that
860
+ * printed findings in one order and a re-run that printed them in another
861
+ * would be two readings of one payload.
862
+ */
863
+ export function tagOrder(
864
+ tags: readonly (Severity | null)[] | null,
865
+ indices: readonly number[],
866
+ ): number[] {
867
+ const rankOf = (i: number): number => {
868
+ const tag = tags?.[i] ?? null;
869
+ return tag === null ? UNTAGGED_RANK : SEVERITY_RANK[tag];
870
+ };
871
+ return [...indices].sort((a, b) => rankOf(a) - rankOf(b) || a - b);
872
+ }
873
+
874
+ /**
875
+ * Every finding's tag, by payload index. Non-objects tag `null`: they are
876
+ * already a `FINDING_NOT_AN_OBJECT` reason, and a shape with no severity has
877
+ * no tag to carry.
878
+ */
879
+ function tagsForPayload(
880
+ list: readonly unknown[],
881
+ touched: ReadonlySet<string> | null,
882
+ ): (Severity | null)[] {
883
+ return list.map(item =>
884
+ item !== null && typeof item === "object" && !Array.isArray(item)
885
+ ? findingTag(item as Record<string, unknown>, touched)
886
+ : null,
887
+ );
888
+ }
889
+
707
890
  function unmeasured(
708
891
  reasons: AiReviewUnmeasuredReason[],
709
892
  detail: string[],
710
893
  reported: unknown[] | null = null,
894
+ findingTags: (Severity | null)[] | null = null,
711
895
  ): AiReviewFindingsReading {
712
896
  return {
713
897
  outcome: "UNMEASURED",
@@ -720,6 +904,7 @@ function unmeasured(
720
904
  scope: scopeNotSupplied(),
721
905
  unlocatableReported: null,
722
906
  scopeDropped: null,
907
+ findingTags,
723
908
  };
724
909
  }
725
910
 
@@ -748,6 +933,7 @@ function withScope(
748
933
  [...reading.unmeasuredReasons, scope.reason],
749
934
  [...reading.detail, scope.detail],
750
935
  reading.reported,
936
+ reading.findingTags,
751
937
  )
752
938
  : reading;
753
939
  return { ...merged, scope, unlocatableReported, scopeDropped };
@@ -989,17 +1175,19 @@ function readPayload(
989
1175
  );
990
1176
  return;
991
1177
  }
992
- const named = normaliseRepoPath(declared);
1178
+ // THE one decider, shared with `findingTag`. Re-reading the path
1179
+ // here would let the demotion and the tag disagree about one finding.
1180
+ const scoped = findingPathScope(finding, touched);
993
1181
  // Undecidable is NOT pre-existing. The finding is well-formed and
994
1182
  // this reader simply cannot resolve its path, so it keeps blocking —
995
1183
  // the direction this stage is allowed to be wrong in.
996
- if (named === null) {
1184
+ if (scoped === "UNDECIDABLE") {
997
1185
  detail.push(
998
1186
  `finding ${i} declares ${JSON.stringify(declared)}, which could not be read as a ` +
999
1187
  `repository path, so it could not be compared to the changed-file list. It ` +
1000
1188
  `keeps blocking: undecidable is not pre-existing`,
1001
1189
  );
1002
- } else if (!touched.has(named)) {
1190
+ } else if (scoped === "PRE_EXISTING") {
1003
1191
  demoted += 1;
1004
1192
  // #1204's half that survived the merge: WHICH findings were
1005
1193
  // demoted, not just how many. The scope line reports it, so a
@@ -1033,7 +1221,12 @@ function readPayload(
1033
1221
  // for the ledger and the annotation; this list is untouched by it.
1034
1222
  // See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
1035
1223
  blocking.push(item);
1036
- detail.push(renderFinding(i, finding));
1224
+ // Tagged through the same binding every other render uses. By here the
1225
+ // tag is `Important` by construction — the severity blocks and the
1226
+ // finding is not Pre-existing, or the branch above would have returned
1227
+ // — so this list is not re-ordered: a sort over one rank reorders
1228
+ // nothing, and applying one would be a comparator no case could redden.
1229
+ detail.push(renderFinding(i, finding, findingTag(finding, touched)));
1037
1230
  }
1038
1231
  });
1039
1232
 
@@ -1054,7 +1247,9 @@ function readPayload(
1054
1247
  }
1055
1248
  }
1056
1249
 
1057
- if (reasons.length > 0) return unmeasured(reasons, detail, list);
1250
+ const tags = tagsForPayload(list, touched);
1251
+
1252
+ if (reasons.length > 0) return unmeasured(reasons, detail, list, tags);
1058
1253
 
1059
1254
  // The decision, and the only place it is made. `verdict` is compared to it
1060
1255
  // afterwards; it never contributes to it.
@@ -1088,6 +1283,7 @@ function readPayload(
1088
1283
  scope: scopeNotSupplied(),
1089
1284
  unlocatableReported: null,
1090
1285
  scopeDropped: null,
1286
+ findingTags: tags,
1091
1287
  };
1092
1288
  }
1093
1289
 
@@ -1295,9 +1491,16 @@ export function aiReviewRefusal(reading: AiReviewFindingsReading): string | null
1295
1491
  // Used INSTEAD of `detail` rather than appended to it. The two overlap
1296
1492
  // exactly on the blocking findings, so appending would print those
1297
1493
  // twice, and a duplicate reads as two findings.
1298
- const counted = renderCountedFindings(reading.reported);
1299
- const payload = counted.length > 0
1300
- ? `${counted.join("; ")}. `
1494
+ const counted = renderCountedFindings(reading.reported, reading.findingTags);
1495
+ // Same sort, same binding, same payload numbering. The contradiction
1496
+ // arm is the one place every counted finding is printed together, so
1497
+ // it is where an unordered list costs the most.
1498
+ const ordered = tagOrder(
1499
+ reading.findingTags,
1500
+ counted.map((_, i) => i),
1501
+ ).map(i => counted[i]);
1502
+ const payload = ordered.length > 0
1503
+ ? `${ordered.join("; ")}. `
1301
1504
  : `The payload records no findings at all. `;
1302
1505
  return (
1303
1506
  `The AI review's verdict ${JSON.stringify(reading.verdict)} contradicts its ` +