rungate 0.8.5 → 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.
@@ -108,8 +108,15 @@ export type LaunchBaseReading =
108
108
  */
109
109
  | { reading: "UNMEASURED"; cwd: string; projectRoot: string; refusal: string };
110
110
 
111
- /** `git -C <dir> rev-parse --show-toplevel`, or `null`. */
112
- function toplevel(dir: string): string | null {
111
+ /**
112
+ * `git -C <dir> rev-parse --show-toplevel`, or `null`.
113
+ *
114
+ * Exported since #1595 so the filing chokepoint identifies the RUN a filing
115
+ * came from through this binding rather than a second `rev-parse` of its
116
+ * own. Two spellings of "which checkout is this" would be two deciders for
117
+ * one question, and the cap's whole content is a count over that answer.
118
+ */
119
+ export function toplevel(dir: string): string | null {
113
120
  if (typeof dir !== "string" || !dir.trim()) return null;
114
121
  const got = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
115
122
  timeout: 10_000,
@@ -120,8 +127,16 @@ function toplevel(dir: string): string | null {
120
127
  return out === "" ? null : out;
121
128
  }
122
129
 
123
- /** `git -C <dir> rev-parse --abbrev-ref HEAD`, or `null`. */
124
- function branchOf(dir: string): string | null {
130
+ /**
131
+ * `git -C <dir> rev-parse --abbrev-ref HEAD`, or `null`.
132
+ *
133
+ * Exported since #1595 so the filing chokepoint names the branch a comment
134
+ * should go on through this binding rather than a second `rev-parse` of its
135
+ * own. `HEAD` — a detached checkout — is a real answer here and is filtered
136
+ * by the caller that cares, because "which branch" and "is this a branch"
137
+ * are different questions and only one of them belongs in a git wrapper.
138
+ */
139
+ export function branchOf(dir: string): string | null {
125
140
  const got = spawnSync("git", ["-C", dir, "rev-parse", "--abbrev-ref", "HEAD"], {
126
141
  timeout: 10_000,
127
142
  encoding: "utf-8",
@@ -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
  *