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.
@@ -75,13 +75,14 @@
75
75
  * it reads the CHECKOUT, which a reader running from a scratch directory
76
76
  * does not have.
77
77
  *
78
- * It takes TWO paths, and that is the part worth not collapsing. The carry
79
- * file holds the carry step's own three-state reading and is written on
80
- * every path; the snapshot holds the ledger's bytes and exists only on the
81
- * READ path. An absent snapshot is therefore not "no prior findings" — the
82
- * carry file says which. Unset either and the gate is `null`: a consumer on
83
- * an older scaffold gets the pre-#1586 reading, not a silent "nothing was a
84
- * repeat".
78
+ * Since AC-1 it takes ONE path, and the collapse from two is not a loss.
79
+ * The ledger needed a pair — bytes, plus a state file saying why the bytes
80
+ * were absent — because an absent snapshot could mean three different
81
+ * things. The thread list is itself the reading: it is written only when the
82
+ * fetch completed, so absent means exactly "not read", and the adjudicator
83
+ * names that rather than suppressing nothing in silence. Unset the variable
84
+ * and the gate is `null`: a consumer on an older scaffold gets the
85
+ * pre-#1586 reading, not a quiet "nothing was a repeat".
85
86
  *
86
87
  * **A blocking finding never reaches this gate.**
87
88
  * `findingMustAlwaysBeReported` filters first, inside the reader, so no
@@ -97,11 +98,7 @@ import {
97
98
  readOrNull,
98
99
  } from "../lib/ai-review-suppression";
99
100
  import { main } from "../lib/scaffold/ai-review-findings";
100
- import {
101
- AI_REVIEW_BALLOT_DIR_ENV,
102
- AI_REVIEW_CARRY_PATH_VAR,
103
- AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR,
104
- } from "../lib/scaffold/ai-review-step";
101
+ import { AI_REVIEW_BALLOT_DIR_ENV, AI_REVIEW_THREADS_PATH_VAR } from "../lib/scaffold/ai-review-step";
105
102
 
106
103
  const ballotDir = process.env[AI_REVIEW_BALLOT_DIR_ENV];
107
104
  const jury =
@@ -109,14 +106,12 @@ const jury =
109
106
  ? null
110
107
  : (blocking: readonly unknown[]) => aiReviewJuryGate(blocking, ballotDir);
111
108
 
112
- const carryPath = process.env[AI_REVIEW_CARRY_PATH_VAR];
113
- const snapshotPath = process.env[AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR];
109
+ const threadsPath = process.env[AI_REVIEW_THREADS_PATH_VAR];
114
110
  const suppress =
115
- carryPath === undefined || carryPath === ""
111
+ threadsPath === undefined || threadsPath === ""
116
112
  ? null
117
113
  : aiReviewSuppressionGate({
118
- carry: readOrNull(carryPath),
119
- snapshot: readOrNull(snapshotPath),
114
+ threads: readOrNull(threadsPath),
120
115
  lineTextFor: checkoutLineText(process.cwd()),
121
116
  });
122
117
 
@@ -0,0 +1,211 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Post an AI review's findings onto the pull request's diff (#1612).
4
+ *
5
+ * Usage:
6
+ * bunx rungate ai-review-threads <findings.json> --repo owner/name --pr 12 --commit <sha>
7
+ * bun bin/rungate.ts ai-review-threads <path> --repo owner/name --pr 12 --commit <sha>
8
+ *
9
+ * Optional: `--changed-files <path>` — the pull request's changed-path list,
10
+ * one per line. Supplying it is what lets a finding naming a file this pull
11
+ * request does not touch be held back rather than sent and refused.
12
+ *
13
+ * ## Why this is a separate command from `ai-review-findings`
14
+ *
15
+ * The adjudicator EXITS NON-ZERO on a blocking finding. That is its whole
16
+ * contract. A poster sharing that entry point would inherit the refusal and
17
+ * could never run on the review it most needs to run on — the one that found
18
+ * something. So the reading is taken twice, by the same reader, in two
19
+ * processes with two different jobs.
20
+ *
21
+ * The exit code is `lib/ai-review-threads.ts`'s, routed through
22
+ * `AI_REVIEW_THREADS_REFUSAL`, for the reason `scripts/ai-review-findings.ts`
23
+ * gives at length: a `process.exit(1)` written here would be a second
24
+ * non-zero exit that a mutation of the constant cannot reach.
25
+ *
26
+ * ## It does not adjudicate, and must not
27
+ *
28
+ * A blocking finding is the adjudicator's to refuse. If this file also
29
+ * refused, the two would be a pair of deciders that always agree — the
30
+ * fourth shape in `.claude/rules/checks-must-be-able-to-fail.md` — and no
31
+ * behavioural test could tell which of them was holding the gate up.
32
+ */
33
+ import { createGitHubClient } from "../lib/github";
34
+ import {
35
+ aiReviewThreadsExitCode,
36
+ postReviewThreads,
37
+ type AiReviewThreadPoster,
38
+ type AiReviewThreadResponse,
39
+ } from "../lib/ai-review-threads";
40
+ import {
41
+ readAiReviewChangedFiles,
42
+ readAiReviewFindingsFile,
43
+ } from "../lib/scaffold/ai-review-findings";
44
+ import { carryKey } from "../lib/ai-review-rounds";
45
+ import {
46
+ aiReviewSuppressionGate,
47
+ checkoutLineText,
48
+ readOrNull,
49
+ } from "../lib/ai-review-suppression";
50
+ import { AI_REVIEW_THREADS_PATH_VAR } from "../lib/scaffold/ai-review-step";
51
+
52
+ const COMMAND = "ai-review-threads";
53
+
54
+ /** Every `--name value` pair this command takes. Anything else is positional. */
55
+ const FLAGS = ["repo", "pr", "commit", "changed-files"] as const;
56
+
57
+ function flag(argv: string[], name: string): string | undefined {
58
+ const at = argv.indexOf(`--${name}`);
59
+ return at === -1 ? undefined : argv[at + 1];
60
+ }
61
+
62
+ /**
63
+ * The positionals, walked rather than filtered.
64
+ *
65
+ * A `argv.filter(a => !a.startsWith("--"))` reads a flag's VALUE as a
66
+ * positional — `--repo owner/name` would hand back `owner/name` as the
67
+ * findings path, and the run would go looking for a payload at a repository
68
+ * slug. Pairs are consumed explicitly instead.
69
+ */
70
+ function positionals(argv: string[]): string[] {
71
+ const rest: string[] = [];
72
+ for (let i = 0; i < argv.length; i += 1) {
73
+ const a = argv[i]!;
74
+ if (a.startsWith("--")) {
75
+ if (FLAGS.includes(a.slice(2) as (typeof FLAGS)[number])) i += 1;
76
+ continue;
77
+ }
78
+ rest.push(a);
79
+ }
80
+ return rest;
81
+ }
82
+
83
+ /** Everything the run needs, or the sentence saying what was missing. */
84
+ function parse(argv: string[]):
85
+ | { ok: true; findings: string; owner: string; repo: string; pr: number; commit: string; changed: string | undefined }
86
+ | { ok: false; error: string } {
87
+ const rest = positionals(argv);
88
+ if (rest.length === 0) return { ok: false, error: "no findings payload given" };
89
+ if (rest.length > 1) {
90
+ return { ok: false, error: `expected one findings payload, got ${rest.length}: ${rest.join(" ")}` };
91
+ }
92
+ const findings = rest[0]!;
93
+
94
+ const slug = flag(argv, "repo");
95
+ if (slug === undefined || !slug.includes("/")) {
96
+ return { ok: false, error: "--repo <owner/name> is required" };
97
+ }
98
+ const [owner, repo] = slug.split("/", 2) as [string, string];
99
+
100
+ const prRaw = flag(argv, "pr");
101
+ const pr = Number(prRaw);
102
+ if (prRaw === undefined || !Number.isInteger(pr) || pr <= 0) {
103
+ return { ok: false, error: "--pr <number> is required" };
104
+ }
105
+
106
+ const commit = flag(argv, "commit");
107
+ if (commit === undefined || commit === "") {
108
+ return { ok: false, error: "--commit <sha> is required — a review comment is anchored to one" };
109
+ }
110
+
111
+ return { ok: true, findings, owner, repo, pr, commit, changed: flag(argv, "changed-files") };
112
+ }
113
+
114
+ const parsed = parse(process.argv.slice(2));
115
+ if (!parsed.ok) {
116
+ // UNMEASURED, not a refusal. A step invoked wrongly has not discovered that
117
+ // a review produced no threads; it has not looked. Exiting non-zero here
118
+ // would red the job for a reason that says nothing about the review.
119
+ console.log(`::warning title=AI review threads::${COMMAND}: ${parsed.error} — UNMEASURED, nothing was posted`);
120
+ process.exit(0);
121
+ }
122
+
123
+ // AC-3, and it is the half AC-1 alone does not reach. `reviewThreadRequests`
124
+ // posts `reading.reported`, and until now this reader was handed NO
125
+ // suppression gate — so the adjudicator could drop a repeat from its
126
+ // annotation while this step posted a thread for it anyway. Measured on
127
+ // #1616: 11 threads for 3 distinct findings, one new copy per push.
128
+ //
129
+ // The gate is the same function the adjudicator builds, over the same file,
130
+ // which is what makes "already raised" one decision rather than two that
131
+ // agree until they do not. This step runs BEFORE the adjudicator in the
132
+ // emitted job, so it cannot be handed the adjudicator's answer — it has to
133
+ // form its own from the same input.
134
+ const threadsPath = process.env[AI_REVIEW_THREADS_PATH_VAR];
135
+ const suppress =
136
+ threadsPath === undefined || threadsPath === ""
137
+ ? null
138
+ : aiReviewSuppressionGate({
139
+ threads: readOrNull(threadsPath),
140
+ lineTextFor: checkoutLineText(process.cwd()),
141
+ });
142
+
143
+ const reading = readAiReviewFindingsFile(
144
+ parsed.findings,
145
+ readAiReviewChangedFiles(parsed.changed),
146
+ suppress,
147
+ );
148
+
149
+ const client = createGitHubClient();
150
+ const post: AiReviewThreadPoster = async request => {
151
+ try {
152
+ await client.rest.pulls.createReviewComment({
153
+ owner: parsed.owner,
154
+ repo: parsed.repo,
155
+ pull_number: parsed.pr,
156
+ commit_id: parsed.commit,
157
+ path: request.path,
158
+ body: request.body,
159
+ // `line` is omitted entirely rather than sent as null — the API
160
+ // documents it as "Required unless using subject_type:file", and the
161
+ // two spellings are not interchangeable.
162
+ ...(request.line === null ? { subject_type: "file" as const } : { line: request.line }),
163
+ });
164
+ return { ok: true };
165
+ } catch (e) {
166
+ const err = e as { status?: number; message?: string };
167
+ return {
168
+ ok: false,
169
+ status: typeof err.status === "number" ? err.status : null,
170
+ message: err.message ?? String(e),
171
+ } satisfies AiReviewThreadResponse;
172
+ }
173
+ };
174
+
175
+ // THE KEY-SYMMETRY HALF, on the producing side. The thread carries the key
176
+ // a later round's suppression gate will form for the same finding, so the
177
+ // text anchor must be read the same way both sides read it — which is why
178
+ // this is `checkoutLineText` and not a second line reader. A caller that
179
+ // supplied no text would key `n:<line>` while the gate keys `t:<text>`, and
180
+ // the two namespaces never collide: the gate would suppress nothing and
181
+ // every round would re-post every thread.
182
+ const lineTextFor = checkoutLineText(process.cwd());
183
+ const result = await postReviewThreads(reading, post, f => carryKey(f, lineTextFor(f)));
184
+ for (const line of result.detail) console.log(`${COMMAND}: ${line}`);
185
+ console.log(
186
+ `${COMMAND}: ${result.outcome} — attempted ${result.attempted}, posted ${result.posted}, ` +
187
+ `demoted ${result.demoted}`,
188
+ );
189
+
190
+ // The outcome reaches the run summary as an annotation only when it is worth
191
+ // a reader's attention. A POSTED round already shows up as comments on the
192
+ // diff, which is a louder channel than an annotation and the entire point.
193
+ if (result.outcome === "FAILED") {
194
+ console.log(
195
+ `::error title=AI review threads::The review found something and this job could not put it on ` +
196
+ `the diff. ${result.posted} of ${result.attempted} posted.`,
197
+ );
198
+ } else if (result.outcome === "DEGRADED_NO_WRITE") {
199
+ console.log(
200
+ `::warning title=AI review threads::No review threads were created: this token cannot write ` +
201
+ `pull-request comments. A pull_request run from a fork is handed a read-only token whatever ` +
202
+ `the workflow declares. The findings are in this run's annotations.`,
203
+ );
204
+ } else if (result.outcome === "UNMEASURED") {
205
+ console.log(
206
+ `::warning title=AI review threads::UNMEASURED — there was no usable reading to post from. ` +
207
+ `This is not a review that found nothing.`,
208
+ );
209
+ }
210
+
211
+ process.exit(aiReviewThreadsExitCode(result));