rungate 0.8.6 → 0.8.7

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
+ aa2a5af1b31b712c5702035b4740c14f591f59fdcbed342e791976869850bfd2
@@ -0,0 +1,188 @@
1
+ /**
2
+ * lib/ai-review-threads.ts — posting a review's findings onto the diff.
3
+ *
4
+ * #1612. Measured 2026-10-25 across every merged pull request on the
5
+ * consumer that runs the generated `ai-review` job: zero review threads,
6
+ * ever. The job's only output has been a GitHub Actions annotation, which
7
+ * lives as long as the run log. A repository that switches
8
+ * `required_conversation_resolution` on against that gets a gate whose
9
+ * population is always empty — satisfied by construction.
10
+ *
11
+ * This module owns the half `reviewThreadRequests` does not: what happened
12
+ * when the comments were sent. That matters because **zero comments posted
13
+ * is the same observation in four different situations** — the review found
14
+ * nothing, the review could not run, the token could not write, or this code
15
+ * is broken. One channel, four mechanisms, which is the sixth shape in
16
+ * `.claude/rules/checks-must-be-able-to-fail.md`. Collapsing them into a
17
+ * boolean is how a producer stays dead without anybody noticing, which is
18
+ * precisely the history being fixed here.
19
+ *
20
+ * So the outcome is NAMED, and exactly one of the names is a refusal.
21
+ *
22
+ * The HTTP call is injected rather than performed. Every decision below is
23
+ * therefore reachable from a test over a recorded response, including the
24
+ * two that only a live fork or a line outside a hunk would otherwise produce.
25
+ */
26
+ import { reviewThreadRequests, type AiReviewFindingsReading } from "./scaffold/ai-review-findings";
27
+ import type { AiReviewThreadRequest } from "./scaffold/ai-review-findings";
28
+
29
+ /**
30
+ * The single non-zero exit. Declared once, so a mutant can set it to `0` and
31
+ * a case can observe the refusal disappearing — `.claude/rules/checks-must-be-able-to-fail.md`,
32
+ * *For a script whose job is to exit non-zero*. A `process.exit(1)` or a
33
+ * second literal anywhere in this module would bypass that mutation and the
34
+ * case would go green over a refusal it never witnessed.
35
+ */
36
+ export const AI_REVIEW_THREADS_REFUSAL = 1;
37
+
38
+ /**
39
+ * What a posting round was, in the words that distinguish the four ways it
40
+ * can produce no comments.
41
+ *
42
+ * | Outcome | Comments | Refusal | What it means |
43
+ * |---|---|---|---|
44
+ * | `POSTED` | ≥ 1 | no | the producer works |
45
+ * | `NOTHING_TO_POST` | 0 | no | the review located nothing to anchor |
46
+ * | `UNMEASURED` | 0 | no | there was no reading to post FROM |
47
+ * | `DEGRADED_NO_WRITE` | 0 | no | the token cannot write; see below |
48
+ * | `FAILED` | any | **yes** | the producer is broken |
49
+ *
50
+ * `UNMEASURED` is not a quieter `NOTHING_TO_POST`. A review that did not run
51
+ * has not found zero findings, and a tree that cannot tell those apart is the
52
+ * *Silent Default Substitution* anti-pattern in `.claude/rules/config-access.md`.
53
+ */
54
+ export type AiReviewThreadOutcome =
55
+ | "POSTED"
56
+ | "NOTHING_TO_POST"
57
+ | "UNMEASURED"
58
+ | "DEGRADED_NO_WRITE"
59
+ | "FAILED";
60
+
61
+ /** What the API said. `status` is `null` for a failure that never got one. */
62
+ export type AiReviewThreadResponse =
63
+ | { ok: true }
64
+ | { ok: false; status: number | null; message: string };
65
+
66
+ /** Sends one comment. The only thing in this module that touches a network. */
67
+ export type AiReviewThreadPoster = (
68
+ request: AiReviewThreadRequest,
69
+ ) => Promise<AiReviewThreadResponse>;
70
+
71
+ export interface AiReviewThreadsResult {
72
+ outcome: AiReviewThreadOutcome;
73
+ /** Comments this round meant to create. */
74
+ attempted: number;
75
+ /** Comments the API accepted. */
76
+ posted: number;
77
+ /** Of those, how many only succeeded after dropping to file level. */
78
+ demoted: number;
79
+ /** One sentence per thing worth reading, in the order it happened. */
80
+ detail: string[];
81
+ }
82
+
83
+ /** HTTP 422 — the documented answer to a `line` outside a diff hunk. */
84
+ const UNPROCESSABLE = 422;
85
+ /** HTTP 403 — the documented answer to a token without `pull-requests: write`. */
86
+ const FORBIDDEN = 403;
87
+
88
+ /**
89
+ * Post every comment a reading calls for, and say which of the four
90
+ * no-comment states this was if none appeared.
91
+ *
92
+ * Three behaviours are worth stating because each has a cheaper wrong answer:
93
+ *
94
+ * **An UNMEASURED reading posts nothing and attempts nothing.** Not because
95
+ * posting would fail, but because there is no reading to post from, and a
96
+ * round that posted a guess would put the reviewer's absence on the diff as
97
+ * though it were a finding.
98
+ *
99
+ * **A 422 demotes before it fails.** `line` is documented as "Required
100
+ * unless using subject_type:file", and a line outside a hunk is refused with
101
+ * 422. Being in the changed-file set locates a finding to a FILE and never
102
+ * to a hunk, so this response is EXPECTED on a correct request and the
103
+ * retry is part of the contract rather than error recovery. Only a 422 that
104
+ * survives the demotion is a defect.
105
+ *
106
+ * **A 403 degrades and does not refuse — but only when it is the whole
107
+ * story.** For a `pull_request` from a forked repository GitHub downgrades
108
+ * write permissions to read regardless of what the workflow declares, unless
109
+ * an admin enabled *Send write tokens to workflows from pull requests*. So on
110
+ * a fork this producer cannot run, the adjudicator's annotation is still
111
+ * produced, and failing here would red every fork pull request for something
112
+ * the contributor cannot fix. What that must NOT do is become a blanket
113
+ * excuse: a round that saw a 403 AND some other failure is `FAILED`, because
114
+ * a broken producer hiding behind a fork is the fail-open this whole module
115
+ * exists to prevent.
116
+ */
117
+ export async function postReviewThreads(
118
+ reading: AiReviewFindingsReading,
119
+ post: AiReviewThreadPoster,
120
+ ): Promise<AiReviewThreadsResult> {
121
+ const detail: string[] = [];
122
+
123
+ if (reading.outcome === "UNMEASURED") {
124
+ detail.push(
125
+ "the review produced no usable reading, so there was nothing to post — this is not a review that found nothing",
126
+ );
127
+ return { outcome: "UNMEASURED", attempted: 0, posted: 0, demoted: 0, detail };
128
+ }
129
+
130
+ const requests = reviewThreadRequests(reading);
131
+ if (requests.length === 0) {
132
+ detail.push("the reading located no finding that could be anchored to a path in this diff");
133
+ return { outcome: "NOTHING_TO_POST", attempted: 0, posted: 0, demoted: 0, detail };
134
+ }
135
+
136
+ let posted = 0;
137
+ let demoted = 0;
138
+ let forbidden = 0;
139
+ let failed = 0;
140
+
141
+ for (const request of requests) {
142
+ const where = request.line === null ? request.path : `${request.path}:${request.line}`;
143
+ let answer = await post(request);
144
+
145
+ // The demotion, and only from a line. A file-level request that is
146
+ // refused has nothing left to drop.
147
+ if (!answer.ok && answer.status === UNPROCESSABLE && request.line !== null) {
148
+ detail.push(`${where}: line refused (422), retrying as a file-level comment`);
149
+ answer = await post({ ...request, line: null });
150
+ if (answer.ok) demoted += 1;
151
+ }
152
+
153
+ if (answer.ok) {
154
+ posted += 1;
155
+ continue;
156
+ }
157
+ if (answer.status === FORBIDDEN) {
158
+ forbidden += 1;
159
+ detail.push(
160
+ `${where}: 403 — this token cannot write pull-request comments. A pull_request run from a ` +
161
+ `fork is handed a read-only token whatever the workflow declares.`,
162
+ );
163
+ continue;
164
+ }
165
+ failed += 1;
166
+ detail.push(`${where}: ${answer.status ?? "no status"} — ${answer.message}`);
167
+ }
168
+
169
+ // Order matters. A real failure outranks the fork excuse, and both outrank
170
+ // a partial success — a round that posted three of four comments has lost
171
+ // a finding and must say so.
172
+ if (failed > 0) {
173
+ return { outcome: "FAILED", attempted: requests.length, posted, demoted, detail };
174
+ }
175
+ if (forbidden > 0) {
176
+ return { outcome: "DEGRADED_NO_WRITE", attempted: requests.length, posted, demoted, detail };
177
+ }
178
+ detail.push(
179
+ `posted ${posted} review ${posted === 1 ? "comment" : "comments"}` +
180
+ (demoted === 0 ? "" : `, ${demoted} at file level after a line was refused`),
181
+ );
182
+ return { outcome: "POSTED", attempted: requests.length, posted, demoted, detail };
183
+ }
184
+
185
+ /** The exit code a round's outcome earns. Only `FAILED` refuses. */
186
+ export function aiReviewThreadsExitCode(result: AiReviewThreadsResult): number {
187
+ return result.outcome === "FAILED" ? AI_REVIEW_THREADS_REFUSAL : 0;
188
+ }
@@ -166,6 +166,27 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
166
166
  // project tree at all — it talks to the GitHub API about a repository it
167
167
  // is told the name of, so an appended `--project-root <cwd>` would be
168
168
  // refused by `parseArgs` as an unknown argument.
169
+ // Registered for the same reachability reason as the two around it
170
+ // (#1612): the generated `ai-review` job runs in a consumer's repository,
171
+ // which holds no copy of rungate's sources at any path a workflow could
172
+ // name. This registry is that path.
173
+ //
174
+ // SEPARATE from `ai-review-findings` on purpose. That command exits
175
+ // non-zero on a blocking finding — so a poster sharing its entry point
176
+ // could never run on the review that actually found something, which is
177
+ // the only review worth posting.
178
+ //
179
+ // No `projectRootFlag`: the payload lives outside the checkout in
180
+ // `RUNNER_TEMP`, everything else is a flag, and an appended
181
+ // `--project-root <cwd>` would arrive as a second positional, which
182
+ // `parse` refuses by name rather than silently reading as the payload.
183
+ "ai-review-threads": {
184
+ script: "scripts/ai-review-threads.ts",
185
+ summary: "Post an AI review's findings onto the pull request's diff as review threads",
186
+ usage:
187
+ "rungate ai-review-threads <path-to-findings.json> --repo <owner/name> " +
188
+ "--pr <n> --commit <sha> [--changed-files <path>]",
189
+ },
169
190
  "record-ai-review-unmeasured": {
170
191
  script: "scripts/record-ai-review-unmeasured.ts",
171
192
  summary: "Record WHICH kind of unmeasured each unmeasured AI-review round was",
package/lib/github.ts CHANGED
@@ -42,6 +42,31 @@ export interface GitHubClient {
42
42
  get: (params: { owner: string; repo: string; pull_number: number }) => Promise<{ data: any }>;
43
43
  update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
44
44
  list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
45
+ /**
46
+ * One INLINE review comment, anchored to the diff (#1612).
47
+ *
48
+ * Not `issues.createComment`, which is the other endpoint and the one
49
+ * the findings ledger uses. The difference is not cosmetic: only a
50
+ * comment created here opens a review THREAD, and a review thread is
51
+ * the only thing `required_conversation_resolution` can read. A
52
+ * repository that turns that protection on while its reviewer posts
53
+ * issue comments has a required gate over an always-empty population.
54
+ *
55
+ * `line` is omitted and `subject_type: "file"` sent in its place when
56
+ * the finding could not be anchored to a line — the API documents
57
+ * `line` as "Required unless using subject_type:file", and answers 422
58
+ * for a line outside a diff hunk.
59
+ */
60
+ createReviewComment: (params: {
61
+ owner: string;
62
+ repo: string;
63
+ pull_number: number;
64
+ body: string;
65
+ commit_id: string;
66
+ path: string;
67
+ line?: number;
68
+ subject_type?: "line" | "file";
69
+ }) => Promise<{ data: any }>;
45
70
  };
46
71
  repos: {
47
72
  /** Repository metadata. `owner.type` and `default_branch` are what PROTECT-1 reads (#909). */
@@ -836,6 +836,112 @@ export function findingPathScope(
836
836
  return touched.has(named) ? "IN_DIFF" : "PRE_EXISTING";
837
837
  }
838
838
 
839
+ /**
840
+ * One inline review comment, as the REST API wants it minus the parts only
841
+ * the caller knows (`commit_id`, the pull request number, the token).
842
+ *
843
+ * `line` is `null` when the finding named no line this reader could use. That
844
+ * is a FILE-LEVEL comment — `POST /pulls/{n}/comments` documents `line` as
845
+ * "Required unless using subject_type:file" — and not a finding to drop.
846
+ */
847
+ export interface AiReviewThreadRequest {
848
+ /** Repository-relative, in the spelling the finding wrote. */
849
+ path: string;
850
+ line: number | null;
851
+ body: string;
852
+ }
853
+
854
+ /**
855
+ * The comments a reading should become — the whole of the decision, in one
856
+ * binding, with no network in it.
857
+ *
858
+ * Measured 2026-10-25 across every merged pull request on the consumer that
859
+ * runs this: zero review threads, ever. The review's output has only ever
860
+ * been a GitHub Actions annotation, which lives as long as the run log and
861
+ * is not something `required_conversation_resolution` can read. So a repo
862
+ * that switches that protection on gets a gate with no producer — satisfied
863
+ * by construction, because nothing it governs is ever created.
864
+ *
865
+ * Three decisions are worth stating, because each has a cheaper wrong answer:
866
+ *
867
+ * **`unlocatableReported` is subtracted, and `null` subtracts nothing.** A
868
+ * finding naming a file the pull request does not touch has no line in this
869
+ * diff to hang off, so the API would refuse it. `null` is the scope check not
870
+ * having run — see `AiReviewFindingsReading.unlocatableReported` — and a
871
+ * reading that could not locate anything must not be read as one that located
872
+ * everything. Membership is by IDENTITY, not by a key rebuilt from the
873
+ * finding's fields: the field set is caller-supplied and two findings can
874
+ * share every value in it, and `unlocatableReported` is already a subset of
875
+ * `reported` by reference.
876
+ *
877
+ * **`normaliseRepoPath` decides whether a path is readable and never supplies
878
+ * the value.** It lowercases, deliberately, because its job is to make two
879
+ * spellings of one path compare equal. The API's job is the opposite: `path`
880
+ * is matched against the diff exactly and a case difference is a 422. Those
881
+ * two requirements fit in one function only if you never notice they are
882
+ * different.
883
+ *
884
+ * **An unreadable line demotes rather than drops.** Being in the changed set
885
+ * makes a finding locatable to a FILE; it does not prove the line sits inside
886
+ * a hunk, which is a separate 422 the caller has to be able to fall back
887
+ * from. Dropping here would silently lose findings whose only defect is that
888
+ * the reviewer wrote no line number.
889
+ */
890
+ export function reviewThreadRequests(
891
+ reading: AiReviewFindingsReading,
892
+ ): AiReviewThreadRequest[] {
893
+ const f = AI_REVIEW_FINDING_FIELDS;
894
+ if (reading.reported === null) return [];
895
+ const unlocatable = new Set(reading.unlocatableReported ?? []);
896
+
897
+ const requests: AiReviewThreadRequest[] = [];
898
+ for (const item of reading.reported) {
899
+ if (unlocatable.has(item)) continue;
900
+ if (typeof item !== "object" || item === null) continue;
901
+ const finding = item as Record<string, unknown>;
902
+
903
+ const raw = finding[f.file];
904
+ // Readability is asked of the normalised spelling; the answer is carried
905
+ // by the raw one. A `:line` suffix is the one edit applied to it, because
906
+ // `src/a.ts:88` is not a path the API can match and the number in it is
907
+ // the only line the finding gave.
908
+ if (normaliseRepoPath(raw) === null) continue;
909
+ const suffixed = String(raw).trim().replace(/\\/g, "/").match(/^(.*?):(\d+)(?::\d+)?$/);
910
+ const path = suffixed ? suffixed[1]! : String(raw).trim().replace(/\\/g, "/");
911
+
912
+ const declared = finding[f.line];
913
+ const line =
914
+ typeof declared === "number" && Number.isInteger(declared) && declared > 0
915
+ ? declared
916
+ : suffixed
917
+ ? Number(suffixed[2])
918
+ : null;
919
+
920
+ requests.push({ path, line, body: threadBody(finding) });
921
+ }
922
+ return requests;
923
+ }
924
+
925
+ /**
926
+ * What one comment says.
927
+ *
928
+ * The failure scenario is carried whenever the finding wrote one. It is the
929
+ * half a reader acts on — a summary alone is a label — and the annotation
930
+ * path has never had room for it, which is part of why the annotations were
931
+ * worth so little.
932
+ */
933
+ function threadBody(finding: Record<string, unknown>): string {
934
+ const f = AI_REVIEW_FINDING_FIELDS;
935
+ const severity = finding[f.severity] !== undefined ? String(finding[f.severity]) : null;
936
+ const summary =
937
+ finding[f.summary] !== undefined ? String(finding[f.summary]) : "(no summary recorded)";
938
+ const scenario =
939
+ finding[f.failureScenario] !== undefined ? String(finding[f.failureScenario]) : null;
940
+
941
+ const head = severity === null ? summary : `**${severity}** — ${summary}`;
942
+ return scenario === null ? head : `${head}\n\n${scenario}`;
943
+ }
944
+
839
945
  /**
840
946
  * CRC-B7's tag for one finding — `Important`, `Nit` or `Pre-existing`.
841
947
  *
@@ -3102,6 +3102,141 @@ export const AI_REVIEW_PERSIST_STEP_ID = "ai-review-persist";
3102
3102
 
3103
3103
  export const AI_REVIEW_PERSIST_STEP_NAME = "Persist this round's findings to the pull request";
3104
3104
 
3105
+ /**
3106
+ * The step that puts the findings ON THE DIFF, as review threads (#1612).
3107
+ *
3108
+ * ## Why this is not what the persist step already does
3109
+ *
3110
+ * The persist step upserts the findings LEDGER, and a ledger is an issue
3111
+ * comment: `POST /repos/{o}/{r}/issues/{n}/comments`. A review thread comes
3112
+ * from a different endpoint — `POST /repos/{o}/{r}/pulls/{n}/comments` — and
3113
+ * the difference is not presentational. `required_conversation_resolution`
3114
+ * reads review threads and nothing else, so a repository that switches that
3115
+ * protection on while its reviewer posts issue comments has a required gate
3116
+ * over a population that is always empty: green by construction, forever.
3117
+ *
3118
+ * Measured 2026-10-25 across every merged pull request on the first consumer
3119
+ * to run this job: zero review threads. The reviewer's entire output has been
3120
+ * a GitHub Actions annotation, which lives as long as the run log and cannot
3121
+ * be replied to, resolved, or found again from the pull request.
3122
+ *
3123
+ * ## Position: BETWEEN the reviewer and the adjudicator
3124
+ *
3125
+ * The same slot the persist step occupies, for the same reason stated there.
3126
+ * The payload exists by here, and the adjudicator — which exits non-zero on a
3127
+ * blocking finding — has not run yet. So this step needs no `if:`, which
3128
+ * matters because `aiReviewAuthScript` in `lib/conformity.ts` refuses an
3129
+ * `if:` on any step in this job for every consumer: a step skipped by a
3130
+ * condition reports `skipped`, and a skipped required check can be configured
3131
+ * to count as satisfied.
3132
+ *
3133
+ * Putting it AFTER the adjudicator would need exactly that forbidden `if:`,
3134
+ * and would post comments only on reviews that found nothing.
3135
+ *
3136
+ * ## It does not decide the pull request's fate
3137
+ *
3138
+ * The adjudicator does. This step refuses only when it HAD comments to post
3139
+ * and could not post them — its own job failing, which is a different fact
3140
+ * from a finding. A fork pull request, whose token GitHub downgrades to
3141
+ * read-only whatever this workflow declares, degrades with a warning instead:
3142
+ * the annotation still carries the review, and reddening every fork for
3143
+ * something a contributor cannot fix would teach everyone to ignore the red.
3144
+ */
3145
+ export const AI_REVIEW_THREADS_STEP_ID = "ai-review-threads";
3146
+
3147
+ export const AI_REVIEW_THREADS_STEP_NAME = "Post this round's findings onto the diff";
3148
+
3149
+ /** The registered CLI name. One declaration, read by the generator and the tests. */
3150
+ export const AI_REVIEW_THREADS_COMMAND = "ai-review-threads";
3151
+
3152
+ export const AI_REVIEW_THREADS_PR_VAR = "AI_REVIEW_THREADS_PR";
3153
+ export const AI_REVIEW_THREADS_REPO_VAR = "AI_REVIEW_THREADS_REPO";
3154
+ export const AI_REVIEW_THREADS_SHA_VAR = "AI_REVIEW_THREADS_SHA";
3155
+ export const AI_REVIEW_THREADS_TOKEN_VAR = "AI_REVIEW_THREADS_TOKEN";
3156
+
3157
+ /**
3158
+ * The script the threads step runs.
3159
+ *
3160
+ * Everything it decides, it decides in the shell and not in an `if:`, for the
3161
+ * reason the step id documents. Two of those decisions are worth naming:
3162
+ *
3163
+ * **No pull request means nothing to post, and that is not a failure.** A
3164
+ * `merge_group` run carries no `github.event.pull_request`, so the variable
3165
+ * arrives empty. The same reading the ledger step takes, rather than a second
3166
+ * `github.event_name` test, so there is one decider.
3167
+ *
3168
+ * **An absent payload is UNMEASURED and exits 0.** A review that wrote
3169
+ * nothing has not found nothing. The adjudicator is the step that turns that
3170
+ * into a verdict; this one says what it saw and gets out of the way, because
3171
+ * two steps refusing over the same reading are a pair of deciders no
3172
+ * behavioural test can tell apart.
3173
+ *
3174
+ * **A pin that predates the command is UNMEASURED, and is told apart from a
3175
+ * failure.** The generated job runs `bunx rungate@<version>`, a PUBLISHED
3176
+ * version, and this YAML reaches every consumer the moment it is merged —
3177
+ * while the npm release happens later, from a tag. So there is a window in
3178
+ * which the live workflow asks a published package for a subcommand it does
3179
+ * not have. `bin/rungate.ts` answers that with exit 1 and the exact string
3180
+ * `unknown command "<name>"`, which is the one signal that separates *the
3181
+ * release has not landed yet* from *the producer is broken* — and they are
3182
+ * otherwise the same non-zero exit. Without this branch, merging this file
3183
+ * reds every pull request in every consumer until a release ships.
3184
+ *
3185
+ * The capture consumes its own status with a top-level `|| threads_code=$?`,
3186
+ * which is #1110's lesson and the form the rest of this file uses. A
3187
+ * generated `run:` block executes under `bash -e`, so an assignment whose
3188
+ * command substitution fails aborts the step before the next line — and the
3189
+ * branch above would be dead code that reads as live.
3190
+ *
3191
+ * `set +e` would also work and is the wrong answer twice over: AC-2 in
3192
+ * `test/ai-review-runner-shell-parity.test.ts` is textual and cannot see it,
3193
+ * so the guard against this exact defect would go quiet; and an `-e`
3194
+ * suspension at a distance is the kind of line a later edit deletes without
3195
+ * knowing what depended on it. The initialiser above the assignment is what
3196
+ * keeps `set -u` happy on the success path.
3197
+ */
3198
+ export function buildThreadsScript(version: string): string {
3199
+ const poster =
3200
+ `bunx ${AI_REVIEW_ADJUDICATOR_PACKAGE}@${version} ${AI_REVIEW_THREADS_COMMAND}`;
3201
+ // Matched with `grep -qF` inside SINGLE quotes, where a double quote is
3202
+ // literal and needs no escaping. The quotes are part of the signal:
3203
+ // `bin/rungate.ts` prints the name quoted, and an unquoted match would
3204
+ // also hit a findings summary that happened to mention the command.
3205
+ const skew = `unknown command "${AI_REVIEW_THREADS_COMMAND}"`;
3206
+ return [
3207
+ `set -uo pipefail`,
3208
+ ``,
3209
+ `if [ -z "\${${AI_REVIEW_THREADS_PR_VAR}:-}" ]; then`,
3210
+ ` echo "${AI_REVIEW_THREADS_COMMAND}: no pull request on this event (merge_group), nothing to post"`,
3211
+ ` exit 0`,
3212
+ `fi`,
3213
+ ``,
3214
+ `if [ ! -s "\${${AI_REVIEW_FINDINGS_PATH_VAR}:-}" ]; then`,
3215
+ ` echo "::warning title=AI review threads::UNMEASURED - no findings payload was written, so no review threads were posted. This is not a review that found nothing."`,
3216
+ ` exit 0`,
3217
+ `fi`,
3218
+ ``,
3219
+ `# \`run:\` is \`bash -e\`, so the assignment consumes its own status with a`,
3220
+ `# top-level \`||\` — see buildThreadsScript. Without it the step aborts`,
3221
+ `# here and the version-skew branch below never runs.`,
3222
+ `threads_code=0`,
3223
+ `threads_out="$(GITHUB_TOKEN="\${${AI_REVIEW_THREADS_TOKEN_VAR}}" ${poster} \\`,
3224
+ ` "\${${AI_REVIEW_FINDINGS_PATH_VAR}}" \\`,
3225
+ ` --repo "\${${AI_REVIEW_THREADS_REPO_VAR}}" \\`,
3226
+ ` --pr "\${${AI_REVIEW_THREADS_PR_VAR}}" \\`,
3227
+ ` --commit "\${${AI_REVIEW_THREADS_SHA_VAR}}" \\`,
3228
+ ` --changed-files "\${${AI_REVIEW_CHANGED_FILES_PATH_VAR}}" 2>&1)" || threads_code=$?`,
3229
+ `printf '%s\\n' "$threads_out"`,
3230
+ ``,
3231
+ `if [ "$threads_code" -ne 0 ] && printf '%s' "$threads_out" | grep -qF '${skew}'; then`,
3232
+ ` echo "::warning title=AI review threads::UNMEASURED - rungate@${version} does not carry the ${AI_REVIEW_THREADS_COMMAND} command yet, so no review threads were posted. This workflow is ahead of the published package; it resolves itself on the next release."`,
3233
+ ` exit 0`,
3234
+ `fi`,
3235
+ ``,
3236
+ `exit "$threads_code"`,
3237
+ ].join("\n");
3238
+ }
3239
+
3105
3240
  /**
3106
3241
  * ## The witness on the UNMEASURED route (#1307)
3107
3242
  *
@@ -11023,6 +11158,41 @@ export function buildReviewRunStep(
11023
11158
  ...buildPersistScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
11024
11159
  ];
11025
11160
 
11161
+ // #1612. BESIDE the persist step and in the same slot, for the same
11162
+ // reason — see `AI_REVIEW_THREADS_STEP_ID`. The reviewer has written its
11163
+ // payload by here and the adjudicator has not run, so this needs no `if:`,
11164
+ // which `lib/conformity.ts` would refuse.
11165
+ //
11166
+ // It posts to a DIFFERENT endpoint from the persist step beside it:
11167
+ // `pulls/{n}/comments` opens a review thread, `issues/{n}/comments` does
11168
+ // not, and only the former is a thing `required_conversation_resolution`
11169
+ // can read.
11170
+ const threads = [
11171
+ `- name: ${AI_REVIEW_THREADS_STEP_NAME}`,
11172
+ ` id: ${AI_REVIEW_THREADS_STEP_ID}`,
11173
+ ` env:`,
11174
+ ` ${AI_REVIEW_FINDINGS_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.path }}`,
11175
+ // The prepare step's directory, not the changed-files step's output —
11176
+ // the writer and the reader then agree by construction rather than
11177
+ // through a step output the writer might not have reached. Same binding
11178
+ // the adjudicator takes, and restated rather than inherited because a
11179
+ // step's `env:` does not carry to a later step (#826).
11180
+ ` ${AI_REVIEW_CHANGED_FILES_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CHANGED_FILES_BASENAME}`,
11181
+ // Empty on a merge_group run, which is how the script knows there is no
11182
+ // pull request to comment on. Read from the event rather than from a
11183
+ // second `github.event_name` test, so there is one decider.
11184
+ ` ${AI_REVIEW_THREADS_PR_VAR}: \${{ github.event.pull_request.number }}`,
11185
+ // The HEAD sha, because `commit_id` anchors a review comment and a
11186
+ // comment anchored to the wrong commit is 422 or, worse, lands outdated.
11187
+ // Not `GITHUB_SHA`: on a `pull_request` event that is the merge ref, not
11188
+ // the head the diff is against.
11189
+ ` ${AI_REVIEW_THREADS_SHA_VAR}: \${{ github.event.pull_request.head.sha }}`,
11190
+ ` ${AI_REVIEW_THREADS_REPO_VAR}: \${{ github.repository }}`,
11191
+ ` ${AI_REVIEW_THREADS_TOKEN_VAR}: \${{ secrets.GITHUB_TOKEN }}`,
11192
+ ` run: |`,
11193
+ ...buildThreadsScript(version).trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
11194
+ ];
11195
+
11026
11196
  // #1242. The consequence of a waiver, and LAST for that reason — see
11027
11197
  // `AI_REVIEW_DISARM_STEP_ID`. It carries no `if:`, like every other step in
11028
11198
  // this job: the waived marker is resolved inside `run:` so the step reports
@@ -11077,6 +11247,11 @@ export function buildReviewRunStep(
11077
11247
  indented(baseline, indent) +
11078
11248
  indented(review, indent) +
11079
11249
  indented(persist, indent) +
11250
+ // #1612. After the ledger and before the report, for the reason
11251
+ // `AI_REVIEW_THREADS_STEP_ID` gives: the payload exists, the adjudicator
11252
+ // has not refused yet, and a step placed after the refusal would need an
11253
+ // `if:` the conformity suite forbids.
11254
+ indented(threads, indent) +
11080
11255
  // #1307. Both BEFORE the report step — see `stageExecution` for why the
11081
11256
  // obvious ordering is not available.
11082
11257
  indented(stageExecution, indent) +
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.6",
3
+ "version": "0.8.7",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -30,6 +30,7 @@
30
30
  "scripts/create-success.ts",
31
31
  "scripts/create-sc.ts",
32
32
  "scripts/ai-review-findings.ts",
33
+ "scripts/ai-review-threads.ts",
33
34
  "scripts/record-ai-review-unmeasured.ts",
34
35
  "scripts/arbitrate-finding.ts",
35
36
  "scripts/split-spec.ts",
@@ -0,0 +1,172 @@
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
+
45
+ const COMMAND = "ai-review-threads";
46
+
47
+ /** Every `--name value` pair this command takes. Anything else is positional. */
48
+ const FLAGS = ["repo", "pr", "commit", "changed-files"] as const;
49
+
50
+ function flag(argv: string[], name: string): string | undefined {
51
+ const at = argv.indexOf(`--${name}`);
52
+ return at === -1 ? undefined : argv[at + 1];
53
+ }
54
+
55
+ /**
56
+ * The positionals, walked rather than filtered.
57
+ *
58
+ * A `argv.filter(a => !a.startsWith("--"))` reads a flag's VALUE as a
59
+ * positional — `--repo owner/name` would hand back `owner/name` as the
60
+ * findings path, and the run would go looking for a payload at a repository
61
+ * slug. Pairs are consumed explicitly instead.
62
+ */
63
+ function positionals(argv: string[]): string[] {
64
+ const rest: string[] = [];
65
+ for (let i = 0; i < argv.length; i += 1) {
66
+ const a = argv[i]!;
67
+ if (a.startsWith("--")) {
68
+ if (FLAGS.includes(a.slice(2) as (typeof FLAGS)[number])) i += 1;
69
+ continue;
70
+ }
71
+ rest.push(a);
72
+ }
73
+ return rest;
74
+ }
75
+
76
+ /** Everything the run needs, or the sentence saying what was missing. */
77
+ function parse(argv: string[]):
78
+ | { ok: true; findings: string; owner: string; repo: string; pr: number; commit: string; changed: string | undefined }
79
+ | { ok: false; error: string } {
80
+ const rest = positionals(argv);
81
+ if (rest.length === 0) return { ok: false, error: "no findings payload given" };
82
+ if (rest.length > 1) {
83
+ return { ok: false, error: `expected one findings payload, got ${rest.length}: ${rest.join(" ")}` };
84
+ }
85
+ const findings = rest[0]!;
86
+
87
+ const slug = flag(argv, "repo");
88
+ if (slug === undefined || !slug.includes("/")) {
89
+ return { ok: false, error: "--repo <owner/name> is required" };
90
+ }
91
+ const [owner, repo] = slug.split("/", 2) as [string, string];
92
+
93
+ const prRaw = flag(argv, "pr");
94
+ const pr = Number(prRaw);
95
+ if (prRaw === undefined || !Number.isInteger(pr) || pr <= 0) {
96
+ return { ok: false, error: "--pr <number> is required" };
97
+ }
98
+
99
+ const commit = flag(argv, "commit");
100
+ if (commit === undefined || commit === "") {
101
+ return { ok: false, error: "--commit <sha> is required — a review comment is anchored to one" };
102
+ }
103
+
104
+ return { ok: true, findings, owner, repo, pr, commit, changed: flag(argv, "changed-files") };
105
+ }
106
+
107
+ const parsed = parse(process.argv.slice(2));
108
+ if (!parsed.ok) {
109
+ // UNMEASURED, not a refusal. A step invoked wrongly has not discovered that
110
+ // a review produced no threads; it has not looked. Exiting non-zero here
111
+ // would red the job for a reason that says nothing about the review.
112
+ console.log(`::warning title=AI review threads::${COMMAND}: ${parsed.error} — UNMEASURED, nothing was posted`);
113
+ process.exit(0);
114
+ }
115
+
116
+ const reading = readAiReviewFindingsFile(parsed.findings, readAiReviewChangedFiles(parsed.changed));
117
+
118
+ const client = createGitHubClient();
119
+ const post: AiReviewThreadPoster = async request => {
120
+ try {
121
+ await client.rest.pulls.createReviewComment({
122
+ owner: parsed.owner,
123
+ repo: parsed.repo,
124
+ pull_number: parsed.pr,
125
+ commit_id: parsed.commit,
126
+ path: request.path,
127
+ body: request.body,
128
+ // `line` is omitted entirely rather than sent as null — the API
129
+ // documents it as "Required unless using subject_type:file", and the
130
+ // two spellings are not interchangeable.
131
+ ...(request.line === null ? { subject_type: "file" as const } : { line: request.line }),
132
+ });
133
+ return { ok: true };
134
+ } catch (e) {
135
+ const err = e as { status?: number; message?: string };
136
+ return {
137
+ ok: false,
138
+ status: typeof err.status === "number" ? err.status : null,
139
+ message: err.message ?? String(e),
140
+ } satisfies AiReviewThreadResponse;
141
+ }
142
+ };
143
+
144
+ const result = await postReviewThreads(reading, post);
145
+ for (const line of result.detail) console.log(`${COMMAND}: ${line}`);
146
+ console.log(
147
+ `${COMMAND}: ${result.outcome} — attempted ${result.attempted}, posted ${result.posted}, ` +
148
+ `demoted ${result.demoted}`,
149
+ );
150
+
151
+ // The outcome reaches the run summary as an annotation only when it is worth
152
+ // a reader's attention. A POSTED round already shows up as comments on the
153
+ // diff, which is a louder channel than an annotation and the entire point.
154
+ if (result.outcome === "FAILED") {
155
+ console.log(
156
+ `::error title=AI review threads::The review found something and this job could not put it on ` +
157
+ `the diff. ${result.posted} of ${result.attempted} posted.`,
158
+ );
159
+ } else if (result.outcome === "DEGRADED_NO_WRITE") {
160
+ console.log(
161
+ `::warning title=AI review threads::No review threads were created: this token cannot write ` +
162
+ `pull-request comments. A pull_request run from a fork is handed a read-only token whatever ` +
163
+ `the workflow declares. The findings are in this run's annotations.`,
164
+ );
165
+ } else if (result.outcome === "UNMEASURED") {
166
+ console.log(
167
+ `::warning title=AI review threads::UNMEASURED — there was no usable reading to post from. ` +
168
+ `This is not a review that found nothing.`,
169
+ );
170
+ }
171
+
172
+ process.exit(aiReviewThreadsExitCode(result));