crysk 0.0.0 → 0.3.1

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.
Files changed (233) hide show
  1. package/LICENSE +176 -0
  2. package/README.md +611 -3
  3. package/bin/pr-hero.js +166 -0
  4. package/config/models/anthropic.json +5 -0
  5. package/dist/SKILL-7e3725zn.md +496 -0
  6. package/dist/SKILL-7q35wcaz.md +66 -0
  7. package/dist/SKILL-9at22381.md +74 -0
  8. package/dist/SKILL-ex2hxxh3.md +134 -0
  9. package/dist/SKILL-y8rv8msh.md +134 -0
  10. package/dist/SKILL-ygka1bs0.md +515 -0
  11. package/dist/adjudicator-dtg2axnh.md +86 -0
  12. package/dist/admission-config.example-a9vqmmad.json +9 -0
  13. package/dist/ci-admission-camfbx2b.md +122 -0
  14. package/dist/ci-admission-qk9r9taq.md +124 -0
  15. package/dist/cli.js +42501 -0
  16. package/dist/consolidate-ac0mnfyj.md +24 -0
  17. package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
  18. package/dist/deep-review-logic-a6b1gczf.md +156 -0
  19. package/dist/deep-review-parity-0ec904db.md +120 -0
  20. package/dist/deep-review-reliability-qyakbjb9.md +125 -0
  21. package/dist/deep-review-resilience-3tz8y26e.md +118 -0
  22. package/dist/index.js +20190 -0
  23. package/dist/opencode-ci-7b0be64p.md +141 -0
  24. package/dist/review-refuter-j4e9gezy.md +71 -0
  25. package/dist/scout-yvp153q7.md +140 -0
  26. package/dist/summarizer-zca44nxa.md +18 -0
  27. package/dist/workflow-w1g9szna.yml +151 -0
  28. package/package.json +81 -4
  29. package/prompts/consolidate.md +24 -0
  30. package/prompts/default/PROVENANCE.md +18 -0
  31. package/prompts/default/deep-review-lifecycle.md +362 -0
  32. package/prompts/default/deep-review-logic.md +156 -0
  33. package/prompts/default/deep-review-parity.md +120 -0
  34. package/prompts/default/deep-review-reliability.md +125 -0
  35. package/prompts/default/deep-review-resilience.md +118 -0
  36. package/prompts/default/review-refuter.md +71 -0
  37. package/prompts/scout.md +140 -0
  38. package/prompts/summarizer.md +18 -0
  39. package/skills/crysk/SKILL.md +74 -0
  40. package/skills/crysk-ci-setup/SKILL.md +134 -0
  41. package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
  42. package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
  43. package/skills/crysk-ci-setup/references/ci-admission.md +124 -0
  44. package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
  45. package/skills/crysk-loop/SKILL.md +515 -0
  46. package/skills/crysk-loop/adjudicator.md +86 -0
  47. package/skills/crysk-pr/SKILL.md +66 -0
  48. package/src/agent-env.ts +1084 -0
  49. package/src/asset-manifest.ts +83 -0
  50. package/src/assets.d.ts +6 -0
  51. package/src/assets.ts +183 -0
  52. package/src/brand-paths.ts +155 -0
  53. package/src/brand.ts +255 -0
  54. package/src/ci/admission-ledger.ts +350 -0
  55. package/src/ci/classify-error.ts +73 -0
  56. package/src/ci/cli-record.ts +271 -0
  57. package/src/ci/force-comment.ts +39 -0
  58. package/src/ci/gates.ts +945 -0
  59. package/src/ci/outcome.ts +2181 -0
  60. package/src/ci/override.ts +187 -0
  61. package/src/ci/publish.ts +1639 -0
  62. package/src/ci/reporter.ts +626 -0
  63. package/src/ci/review-admission.ts +910 -0
  64. package/src/ci/review-levels.ts +310 -0
  65. package/src/ci/review-policy.ts +18 -0
  66. package/src/ci/review-risk.ts +184 -0
  67. package/src/ci/setup.ts +844 -0
  68. package/src/ci/trigger.ts +1353 -0
  69. package/src/cli.ts +348 -0
  70. package/src/commands/activity.ts +67 -0
  71. package/src/commands/ci-setup-questions.ts +397 -0
  72. package/src/commands/ci-setup.ts +381 -0
  73. package/src/commands/config.ts +99 -0
  74. package/src/commands/doctor.ts +108 -0
  75. package/src/commands/init.ts +139 -0
  76. package/src/commands/mcp.ts +10 -0
  77. package/src/commands/menu.ts +129 -0
  78. package/src/commands/post.ts +302 -0
  79. package/src/commands/skills.ts +83 -0
  80. package/src/commands/status.ts +173 -0
  81. package/src/commands/triage.ts +342 -0
  82. package/src/commands/uninstall.ts +37 -0
  83. package/src/commands/upgrade.ts +214 -0
  84. package/src/commands/usage.ts +98 -0
  85. package/src/compare/compare.ts +28 -0
  86. package/src/compare/floor-test.ts +471 -0
  87. package/src/compare/martian-adapter.ts +80 -0
  88. package/src/config/config.ts +267 -0
  89. package/src/corpus/corpus.ts +1094 -0
  90. package/src/corpus/preflight.ts +1789 -0
  91. package/src/diversity/accounting.ts +90 -0
  92. package/src/diversity/adjudication.ts +145 -0
  93. package/src/diversity/admission.ts +60 -0
  94. package/src/diversity/benchmark.ts +195 -0
  95. package/src/diversity/clustering.ts +285 -0
  96. package/src/diversity/errors.ts +7 -0
  97. package/src/diversity/identity.ts +285 -0
  98. package/src/diversity/index.ts +11 -0
  99. package/src/diversity/pipeline-integration.ts +448 -0
  100. package/src/diversity/projection.ts +57 -0
  101. package/src/diversity/self-contained.ts +68 -0
  102. package/src/diversity/target-validation.ts +179 -0
  103. package/src/doctor-migration.ts +209 -0
  104. package/src/doctor.ts +723 -0
  105. package/src/errors.ts +83 -0
  106. package/src/execution/admission.ts +75 -0
  107. package/src/execution/atomic-write.ts +35 -0
  108. package/src/execution/attempt-evidence.ts +415 -0
  109. package/src/execution/bucket-id.ts +136 -0
  110. package/src/execution/concurrency-limiter.ts +175 -0
  111. package/src/execution/contracts.ts +443 -0
  112. package/src/execution/failure-classification.ts +42 -0
  113. package/src/execution/failure-policy.ts +240 -0
  114. package/src/execution/harness.ts +2548 -0
  115. package/src/execution/settlement.ts +348 -0
  116. package/src/execution/spawned-process.ts +66 -0
  117. package/src/execution/spend-limiter.ts +424 -0
  118. package/src/execution/step-artifacts.ts +55 -0
  119. package/src/execution/usage-normalized.ts +469 -0
  120. package/src/git/git.ts +396 -0
  121. package/src/git/identity.ts +64 -0
  122. package/src/git/refs.ts +140 -0
  123. package/src/home-preflight.ts +443 -0
  124. package/src/home.ts +243 -0
  125. package/src/ignore-file.ts +336 -0
  126. package/src/ignore-read.ts +118 -0
  127. package/src/index.ts +34 -0
  128. package/src/legacy-launchd.ts +29 -0
  129. package/src/mcp/mcp.ts +150 -0
  130. package/src/mcp/preflight.ts +407 -0
  131. package/src/menu-context.ts +192 -0
  132. package/src/model/catalog.ts +251 -0
  133. package/src/model/exec-snapshots.ts +390 -0
  134. package/src/model/free-discovery.ts +302 -0
  135. package/src/model/provider-capabilities.ts +814 -0
  136. package/src/model/routing.ts +600 -0
  137. package/src/pr/admission.ts +984 -0
  138. package/src/pr/answered-findings.ts +169 -0
  139. package/src/pr/ci-admission-gate.ts +743 -0
  140. package/src/pr/ci-publish.ts +76 -0
  141. package/src/pr/discovery.ts +432 -0
  142. package/src/pr/inline.ts +507 -0
  143. package/src/pr/plan.ts +366 -0
  144. package/src/pr/posting.ts +115 -0
  145. package/src/pr/pr-status.ts +845 -0
  146. package/src/pr/pr.ts +3642 -0
  147. package/src/pr/preflight.ts +1031 -0
  148. package/src/pr/publish-outcome.ts +361 -0
  149. package/src/pr/range.ts +119 -0
  150. package/src/pr/reverts-preflight.ts +606 -0
  151. package/src/pr/reverts.ts +377 -0
  152. package/src/pr/review-pr.ts +927 -0
  153. package/src/pr/status.ts +154 -0
  154. package/src/pr/target.ts +388 -0
  155. package/src/pr/teardown.ts +437 -0
  156. package/src/pr/worktree-setup.ts +60 -0
  157. package/src/production-runtime.ts +1877 -0
  158. package/src/progress.ts +487 -0
  159. package/src/rereview/adjudicate.ts +89 -0
  160. package/src/rereview/classify.ts +362 -0
  161. package/src/rereview/identity.ts +211 -0
  162. package/src/rereview/plan.ts +308 -0
  163. package/src/rereview/prepare.ts +1025 -0
  164. package/src/rereview/state.ts +767 -0
  165. package/src/rereview/verify.ts +241 -0
  166. package/src/review/boundary.ts +105 -0
  167. package/src/review/consolidate.ts +246 -0
  168. package/src/review/dedupe.ts +368 -0
  169. package/src/review/drafts.ts +448 -0
  170. package/src/review/findings-conformance.ts +120 -0
  171. package/src/review/findings.ts +714 -0
  172. package/src/review/pipeline.ts +3977 -0
  173. package/src/review/preflight.ts +3575 -0
  174. package/src/review/prompt-set.ts +177 -0
  175. package/src/review/proof-refs.ts +187 -0
  176. package/src/review/report.ts +1821 -0
  177. package/src/review/review.ts +490 -0
  178. package/src/review/root-cause.ts +120 -0
  179. package/src/review/route-preflight.ts +289 -0
  180. package/src/review/run.ts +601 -0
  181. package/src/review/scout.ts +323 -0
  182. package/src/review/size-gate.ts +595 -0
  183. package/src/review/spec.ts +235 -0
  184. package/src/review/step-runner.ts +233 -0
  185. package/src/runner-authority.ts +596 -0
  186. package/src/security/binding-policy.ts +115 -0
  187. package/src/security/credential-broker.ts +773 -0
  188. package/src/security/evidence-redaction.ts +62 -0
  189. package/src/security/execution-authority.ts +27 -0
  190. package/src/security/redact.ts +71 -0
  191. package/src/security/workspace-read-broker.ts +466 -0
  192. package/src/server/client.ts +190 -0
  193. package/src/server/preflight.ts +217 -0
  194. package/src/server/server.ts +327 -0
  195. package/src/signal-handler.ts +50 -0
  196. package/src/store/activity.ts +413 -0
  197. package/src/store/backfill-preflight.ts +49 -0
  198. package/src/store/backfill.ts +141 -0
  199. package/src/store/gc-preflight.ts +206 -0
  200. package/src/store/gc.ts +424 -0
  201. package/src/store/metrics-preflight.ts +229 -0
  202. package/src/store/metrics.ts +236 -0
  203. package/src/store/preflight.ts +748 -0
  204. package/src/store/store.ts +693 -0
  205. package/src/system-tools.ts +355 -0
  206. package/src/transport-registry.ts +1124 -0
  207. package/src/transports/claude-code-cli.ts +1348 -0
  208. package/src/transports/opencode-admission.ts +515 -0
  209. package/src/transports/opencode-client.ts +3328 -0
  210. package/src/transports/opencode-evidence.ts +557 -0
  211. package/src/transports/opencode-mcp.ts +248 -0
  212. package/src/transports/opencode-sdk.ts +2294 -0
  213. package/src/transports/opencode-server.ts +535 -0
  214. package/src/triage/adjudication.ts +113 -0
  215. package/src/triage/reply.ts +125 -0
  216. package/src/triage/triage.ts +255 -0
  217. package/src/ui/activity.ts +173 -0
  218. package/src/ui/config-edit.ts +816 -0
  219. package/src/ui/config.ts +462 -0
  220. package/src/ui/menu.ts +1325 -0
  221. package/src/ui/plan.ts +1039 -0
  222. package/src/ui/primitives.ts +300 -0
  223. package/src/ui/progress.ts +298 -0
  224. package/src/ui/result.ts +552 -0
  225. package/src/ui/review-menu.ts +312 -0
  226. package/src/ui/select.ts +528 -0
  227. package/src/ui/tree.ts +178 -0
  228. package/src/uninstaller.ts +479 -0
  229. package/src/updater.ts +836 -0
  230. package/src/usage.ts +77 -0
  231. package/src/watch/preflight.ts +1389 -0
  232. package/src/watch/watch.ts +1235 -0
  233. package/src/wizard.ts +877 -0
@@ -0,0 +1,1031 @@
1
+ // Everything PR mode (ROADMAP B1) must decide beyond what local mode already
2
+ // decides, expressed as pure functions so it is all testable offline — same
3
+ // contract as review/preflight.ts: nothing here touches the filesystem, git, gh, or
4
+ // the network. cli.ts and pr/pr.ts are the I/O shells that act on these.
5
+ //
6
+ // PR mode splits "the repo" into two roots, and every decision below names
7
+ // the one it serves:
8
+ // - the OPERATOR root: the --repo checkout. Owns .prhero/ trust
9
+ // (config+gotchas) and gh. Never reviewed. Worktree add/fetch and the
10
+ // default run dir now hang off the global ~/.prhero/ home (W3 / #24),
11
+ // keyed by origin, with one git-dir owner per remote.
12
+ // - the REVIEW root: a detached worktree at the PR's head. The pipeline's
13
+ // cwd, the tree the codegraph index describes. Never trusted for config.
14
+
15
+ import { createHash } from "node:crypto";
16
+ import { existsSync } from "node:fs";
17
+ import { mkdir } from "node:fs/promises";
18
+ import path from "node:path";
19
+ import { CANCELLED_STATUS_DESCRIPTION } from "#ci/publish";
20
+ import { isFullCommitId } from "#git/refs";
21
+ import {
22
+ assertOutsideRepo,
23
+ type CliOptions,
24
+ type NumstatDiffStat,
25
+ type NumstatFile,
26
+ } from "#review/preflight";
27
+ import {
28
+ evaluateSizeGate,
29
+ evaluateSizeGateAggregate,
30
+ type SizeGateConfig,
31
+ type SizeGateVerdict,
32
+ } from "#review/size-gate";
33
+ import {
34
+ isLegacyStatusContext,
35
+ isStatusContext,
36
+ LOCAL_STATUS_CONTEXT,
37
+ MARKER_OPEN,
38
+ matchMarkerPrefix,
39
+ STATUS_CONTEXT,
40
+ } from "../brand";
41
+ import { CliError, CliUsageError } from "../errors";
42
+
43
+ export type PrState = "OPEN" | "CLOSED" | "MERGED";
44
+
45
+ // Where the base rev came from. Printed in the plan for the same reason
46
+ // BaseRefResolution.source exists: a base derived from the merge commit and
47
+ // one read off the base branch carry very different guarantees.
48
+ export type PrBaseSource = "merge-commit-parent" | "base-branch";
49
+
50
+ export interface PrTarget {
51
+ number: number;
52
+ title: string;
53
+ state: PrState;
54
+ headSha: string;
55
+ // A rev EXPRESSION, not always a sha: for a merged PR it is
56
+ // `<mergeCommit>^1`, canonicalized to a full sha by the shell's rev-parse
57
+ // helper after the fetch.
58
+ baseRef: string;
59
+ // The branch the PR targets. The fetch needs it by name (see fetchPrRefs
60
+ // in pr/pr.ts), so it rides along with the resolved rev.
61
+ baseRefName: string;
62
+ baseSource: PrBaseSource;
63
+ // GitHub's own counters projected into the numstat shape, so a --dry-run
64
+ // can print a cost band before anything is fetched.
65
+ ghDiffStat: NumstatDiffStat;
66
+ }
67
+
68
+ // Parses the raw stdout of `gh pr view <n> --json number,title,state,
69
+ // headRefOid,baseRefName,baseRefOid,mergeCommit,additions,deletions,
70
+ // changedFiles`. Every field is validated loudly and names itself when it is
71
+ // missing or mistyped: a PR record read wrong reviews a range nobody asked
72
+ // for, and gh's output is still input from outside this process.
73
+ export function resolvePrTarget(raw: string): PrTarget {
74
+ let parsed: unknown;
75
+ try {
76
+ parsed = JSON.parse(raw);
77
+ } catch (error) {
78
+ throw new CliUsageError(
79
+ `gh pr view returned invalid JSON: ${(error as Error).message}`,
80
+ );
81
+ }
82
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
83
+ throw new CliUsageError("gh pr view must return a single JSON object");
84
+ }
85
+ const record = parsed as Record<string, unknown>;
86
+ const number = readCount(record, "number");
87
+ if (number < 1) {
88
+ throw new CliUsageError(
89
+ `gh pr view "number" must be positive, got: ${number}`,
90
+ );
91
+ }
92
+ const title = readString(record, "title");
93
+ const state = readString(record, "state");
94
+ if (state !== "OPEN" && state !== "CLOSED" && state !== "MERGED") {
95
+ throw new CliUsageError(
96
+ `gh pr view "state" must be OPEN, CLOSED or MERGED, got: ` +
97
+ JSON.stringify(state),
98
+ );
99
+ }
100
+ const headSha = readSha(record, "headRefOid");
101
+ const baseRefName = readString(record, "baseRefName");
102
+ const ghDiffStat: NumstatDiffStat = {
103
+ files: readCount(record, "changedFiles"),
104
+ insertions: readCount(record, "additions"),
105
+ deletions: readCount(record, "deletions"),
106
+ };
107
+
108
+ if (state === "MERGED") {
109
+ // WHY the merge commit's FIRST PARENT and never baseRefOid: for a merged
110
+ // PR, baseRefOid is the base branch tip as it stands TODAY — it has
111
+ // moved past the merge, and diffing from it reproduces exactly the
112
+ // reversed-range bug the merge-base default fixed (see resolveDiffFrom
113
+ // in cli.ts). `mergeCommit^1` is base as it was when the PR landed, for
114
+ // merge, squash, and rebase merges alike.
115
+ const mergeOid = readMergeCommitOid(record);
116
+ if (mergeOid === null) {
117
+ // Should not happen. Guessing a base here would silently review a
118
+ // range GitHub never showed anyone, so refuse instead.
119
+ throw new CliError(
120
+ `PR ${number} is MERGED but gh reports no mergeCommit — cannot ` +
121
+ "derive the base it was merged into; refusing to guess",
122
+ );
123
+ }
124
+ return {
125
+ number,
126
+ title,
127
+ state,
128
+ headSha,
129
+ baseRef: `${mergeOid}^1`,
130
+ baseRefName,
131
+ baseSource: "merge-commit-parent",
132
+ ghDiffStat,
133
+ };
134
+ }
135
+ // OPEN, or CLOSED without merging: the base tip recorded on the PR is the
136
+ // honest endpoint, and the merge-base step downstream trims it to the
137
+ // branch point exactly as local mode does.
138
+ return {
139
+ number,
140
+ title,
141
+ state,
142
+ headSha,
143
+ baseRef: readSha(record, "baseRefOid"),
144
+ baseRefName,
145
+ baseSource: "base-branch",
146
+ ghDiffStat,
147
+ };
148
+ }
149
+
150
+ // Parses the stdout of the NO-ARGUMENT `gh pr view --json number`, which gh
151
+ // resolves against the checkout's current branch — the call behind bare
152
+ // `--pr`. Same loud register as resolvePrTarget: a mis-read number would
153
+ // review a PR nobody is standing on.
154
+ export function resolveCurrentPrNumber(raw: string): number {
155
+ let parsed: unknown;
156
+ try {
157
+ parsed = JSON.parse(raw);
158
+ } catch (error) {
159
+ throw new CliUsageError(
160
+ `gh pr view returned invalid JSON: ${(error as Error).message}`,
161
+ );
162
+ }
163
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
164
+ throw new CliUsageError("gh pr view must return a single JSON object");
165
+ }
166
+ const number = (parsed as Record<string, unknown>).number;
167
+ if (typeof number !== "number" || !Number.isInteger(number) || number < 1) {
168
+ throw new CliUsageError(
169
+ `gh pr view "number" must be a positive integer, got: ` +
170
+ JSON.stringify(number),
171
+ );
172
+ }
173
+ return number;
174
+ }
175
+
176
+ function readString(record: Record<string, unknown>, field: string): string {
177
+ const value = record[field];
178
+ if (typeof value !== "string" || value.length === 0) {
179
+ throw new CliUsageError(
180
+ `gh pr view "${field}" must be a non-empty string, got: ` +
181
+ JSON.stringify(value),
182
+ );
183
+ }
184
+ return value;
185
+ }
186
+
187
+ function readSha(record: Record<string, unknown>, field: string): string {
188
+ const value = readString(record, field);
189
+ if (!isFullCommitId(value)) {
190
+ throw new CliUsageError(
191
+ `gh pr view "${field}" must be a full 40-hex commit id, got: ` +
192
+ JSON.stringify(value),
193
+ );
194
+ }
195
+ return value;
196
+ }
197
+
198
+ function readCount(record: Record<string, unknown>, field: string): number {
199
+ const value = record[field];
200
+ if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
201
+ throw new CliUsageError(
202
+ `gh pr view "${field}" must be a non-negative integer, got: ` +
203
+ JSON.stringify(value),
204
+ );
205
+ }
206
+ return value;
207
+ }
208
+
209
+ function readMergeCommitOid(record: Record<string, unknown>): string | null {
210
+ const value = record.mergeCommit;
211
+ if (value === null || value === undefined) return null;
212
+ if (typeof value !== "object" || Array.isArray(value)) {
213
+ throw new CliUsageError(
214
+ 'gh pr view "mergeCommit" must be null or an object with "oid"',
215
+ );
216
+ }
217
+ const oid = (value as Record<string, unknown>).oid;
218
+ if (typeof oid !== "string" || !isFullCommitId(oid)) {
219
+ throw new CliUsageError(
220
+ `gh pr view "mergeCommit.oid" must be a full 40-hex commit id, got: ` +
221
+ JSON.stringify(oid),
222
+ );
223
+ }
224
+ return oid;
225
+ }
226
+
227
+ // PR-mode variant of runDirCandidate: the PR number leads so runs of the
228
+ // same PR sort together, and the head sha still pins WHICH bytes the run
229
+ // reviewed — a re-review after a force-push gets a new name, never a
230
+ // collision with the old evidence.
231
+ export function prRunDirCandidate(
232
+ root: string,
233
+ pr: number,
234
+ headSha: string,
235
+ n: number,
236
+ ): string {
237
+ return path.join(root, `pr-${pr}-${headSha.slice(0, 8)}-${n}`);
238
+ }
239
+
240
+ // PR-mode twin of createRunDir, differing in exactly two ways: the candidate
241
+ // carries the PR number, and the outside-the-repo assertion runs against
242
+ // BOTH roots — artifacts inside either tree would contaminate a review.
243
+ export async function createPrRunDir(
244
+ options: CliOptions,
245
+ operatorRoot: string,
246
+ worktreePath: string,
247
+ runsRoot: string,
248
+ prNumber: number,
249
+ headSha: string,
250
+ ): Promise<string> {
251
+ const dir = predictPrRunDir(
252
+ options,
253
+ operatorRoot,
254
+ worktreePath,
255
+ runsRoot,
256
+ prNumber,
257
+ headSha,
258
+ );
259
+ await mkdir(dir, { recursive: true });
260
+ return dir;
261
+ }
262
+
263
+ // The same resolution WITHOUT the mkdir, because a PR-mode --dry-run must
264
+ // create nothing at all (local mode's dry run does create its run dir; PR
265
+ // mode deliberately does not) — yet the plan should still print the exact
266
+ // dir a confirmed run would use, and an --out that violates the containment
267
+ // rule should still fail inside the free dry run.
268
+ export function predictPrRunDir(
269
+ options: CliOptions,
270
+ operatorRoot: string,
271
+ worktreePath: string,
272
+ runsRoot: string,
273
+ prNumber: number,
274
+ headSha: string,
275
+ ): string {
276
+ if (options.out) {
277
+ const explicit = path.resolve(options.out);
278
+ assertOutsideRepo(explicit, operatorRoot);
279
+ assertOutsideRepo(explicit, worktreePath);
280
+ return explicit;
281
+ }
282
+ const root = runsRoot;
283
+ // Smallest unused integer, same reason as createRunDir: a run that cost
284
+ // money is evidence and must never be overwritten.
285
+ for (let n = 1; ; n++) {
286
+ const candidate = prRunDirCandidate(root, prNumber, headSha, n);
287
+ if (existsSync(candidate)) continue;
288
+ assertOutsideRepo(candidate, operatorRoot);
289
+ assertOutsideRepo(candidate, worktreePath);
290
+ return candidate;
291
+ }
292
+ }
293
+
294
+ export interface PrDryRunSizeGateResult {
295
+ verdict: SizeGateVerdict;
296
+ note: string;
297
+ }
298
+
299
+ // PR1b Addition 1 (#5557): the PR `--dry-run` size-gate estimate, fixed to
300
+ // use per-file data when it is trustworthy — pure, so the truncation-guard
301
+ // branching is unit-testable without a live `gh` call.
302
+ //
303
+ // Ported from watch/watch.ts's tier-2 pattern, not rewritten: the aggregate path
304
+ // (`{files, insertions, deletions}`, no paths) cannot express exclusions at
305
+ // all, so `.cryskignore` widens what was already a "wrong in the
306
+ // conservative direction" gap (see the WHY this replaces at the call site)
307
+ // from tens of lines (lockfiles) to potentially thousands (a whole ignored
308
+ // directory) — a gate that SKIPs a PR the real per-file run happily accepts
309
+ // reads as a broken tool, not a conservative estimate.
310
+ //
311
+ // `perFile: null` is the caller's signal that gh's own `files` list was
312
+ // truncated or unavailable — see watch/watch.ts:322-327's identical guard: a SHORT
313
+ // list under-counts, and under-counting here would falsely RESCUE exactly
314
+ // the monster this gate exists to stop, so an untrustworthy list is never
315
+ // used to compute a passing verdict.
316
+ export function resolvePrDryRunSizeGate(input: {
317
+ ghDiffStat: NumstatDiffStat;
318
+ perFile: NumstatFile[] | null;
319
+ gateConfig: SizeGateConfig;
320
+ }): PrDryRunSizeGateResult {
321
+ if (input.perFile !== null) {
322
+ return {
323
+ verdict: evaluateSizeGate(input.perFile, input.gateConfig),
324
+ note:
325
+ "(estimate from gh's per-file list; `.cryskignore` exclusions " +
326
+ "apply, but the count is still not whitespace-adjusted — GitHub's " +
327
+ "counters carry no whitespace information)",
328
+ };
329
+ }
330
+ return {
331
+ verdict: evaluateSizeGateAggregate(input.ghDiffStat, input.gateConfig),
332
+ note:
333
+ "(estimate from GitHub's aggregate counters; gh's per-file list was " +
334
+ "truncated or unavailable, so exclusions are not applied and the " +
335
+ "count is not whitespace-adjusted)",
336
+ };
337
+ }
338
+
339
+ // `git status --porcelain` over the REVIEW worktree, reduced to one bit.
340
+ // `.codegraph/` entries are ignored: the index is built INTO the worktree by
341
+ // design and is always untracked there, so without this filter every
342
+ // reusable worktree would read dirty and reuse would never happen. Anything
343
+ // else — a tracked file edited during finding-verification, a stray
344
+ // untracked file — makes the tree dirty and forces a recreate: B0's
345
+ // dirty-tree lesson applied to the reuse path (uncommitted bytes would be
346
+ // reviewed but never reported).
347
+ export function worktreeDirty(porcelain: string): boolean {
348
+ for (const line of porcelain.split("\n")) {
349
+ if (line.trim().length === 0) continue;
350
+ // Porcelain v1: two status characters, a space, then the path.
351
+ const entry = line.slice(3);
352
+ if (entry === ".codegraph" || entry.startsWith(".codegraph/")) continue;
353
+ return true;
354
+ }
355
+ return false;
356
+ }
357
+
358
+ export type WorktreeAction = "create" | "reuse" | "recreate";
359
+
360
+ export interface WorktreeDecision {
361
+ action: WorktreeAction;
362
+ // Printed next to the action: a "recreate" without its cause reads as
363
+ // churn, and the two causes call for different reactions from a human.
364
+ reason: string;
365
+ }
366
+
367
+ // The reuse gate, stated once as a table so it is arguable. Recreate over
368
+ // repair on every mismatch: a worktree is disposable by construction, and
369
+ // checkout/clean surgery inside one saves nothing worth the risk of
370
+ // reviewing bytes nobody fetched.
371
+ export function decideWorktree(input: {
372
+ exists: boolean;
373
+ headMatches: boolean;
374
+ dirty: boolean;
375
+ }): WorktreeDecision {
376
+ if (!input.exists) {
377
+ return { action: "create", reason: "no worktree for this PR yet" };
378
+ }
379
+ if (!input.headMatches) {
380
+ return {
381
+ action: "recreate",
382
+ reason:
383
+ "its HEAD is not the PR's head (the PR was updated or force-pushed " +
384
+ "since the last review)",
385
+ };
386
+ }
387
+ if (input.dirty) {
388
+ return {
389
+ action: "recreate",
390
+ reason:
391
+ "it has uncommitted changes beyond .codegraph/ (edits made while " +
392
+ "verifying findings must not leak into a review)",
393
+ };
394
+ }
395
+ return {
396
+ action: "reuse",
397
+ reason: "HEAD matches the PR head and the tree is clean",
398
+ };
399
+ }
400
+
401
+ // The tag that makes posting idempotent (ROADMAP B2): the FIRST line of
402
+ // every comment pr-hero publishes. An HTML comment renders invisibly on
403
+ // GitHub, so readers see the report and the machine sees the tag.
404
+ // renderPrComment (report.ts) writes it; findMarkedCommentId reads it.
405
+ //
406
+ // B3 added the head declaration: the emitted marker carries the FULL head
407
+ // sha the posted review describes, so the watch guard (watch/preflight.ts)
408
+ // can tell from the comment alone whether THIS head was already reviewed on
409
+ // another machine. Matching, though, stays on the bare prefix — comments
410
+ // already in the wild carry the old headless `<!-- pr-hero-report -->`, and
411
+ // a matcher that required the head (or the closing `-->` right after the
412
+ // name) would orphan every one of them, so --post would stack a second
413
+ // comment instead of updating. The trailing space in the prefix is
414
+ // deliberate: both formats continue with a space (` -->` / ` head=`), while
415
+ // a foreign lookalike marker such as `<!-- pr-hero-reporter -->` does not.
416
+ export const PR_COMMENT_MARKER_PREFIX = `${MARKER_OPEN}report `;
417
+
418
+ // The re-review closing comment (pr/pr.ts's postInlineFindings). A re-review
419
+ // only PATCHes the summary, and GitHub neither notifies on an edit nor moves
420
+ // the comment down the timeline, so a clean re-review used to leave the PR
421
+ // looking untouched. This marker tags the short comment that closes the run.
422
+ // Its own `pr-hero-<noun>` namespace, so findMarkedCommentId's summary lookup
423
+ // (prefix `pr-hero-report `) can never mistake it for the summary.
424
+ export const PR_REREVIEW_CLOSED_MARKER_PREFIX = `${MARKER_OPEN}rereview-closed `;
425
+
426
+ // Rereview-coverage fix (GitHub #42's re-review half, MusiveTech/musive
427
+ // #1823): a PARTIAL run (some hunters or the refuter failed, but not all —
428
+ // `sessionFailed` false) used to post the exact same marker a COMPLETE run
429
+ // posts. The next `pr-hero review --pr N` on the same head then trusted
430
+ // L===H and skipped discovery entirely, so the missing hunters never ran
431
+ // and the failed refuter never re-verified anything — silently, forever,
432
+ // until a genuinely new push arrived. This token is the fix's whole wire
433
+ // contract: named once, spelled once, consulted by exact match only (see
434
+ // parsePrCommentMarker in watch/preflight.ts).
435
+ export const PR_COMMENT_COVERAGE_PARTIAL_TOKEN = "coverage=partial";
436
+
437
+ // `complete` defaults to `true` so every pre-existing one-argument call —
438
+ // every already-posted comment, every test in this codebase — stays
439
+ // BYTE-IDENTICAL to the marker this function emitted before this fix. Only
440
+ // `renderPrComment` (report.ts), which actually knows `doc.run_status`,
441
+ // passes `false`.
442
+ export function prCommentMarker(headSha: string, complete = true): string {
443
+ return complete
444
+ ? `${PR_COMMENT_MARKER_PREFIX}head=${headSha} -->`
445
+ : `${PR_COMMENT_MARKER_PREFIX}head=${headSha} ${PR_COMMENT_COVERAGE_PARTIAL_TOKEN} -->`;
446
+ }
447
+
448
+ // Finds the comment a --post run should update. A comment matches only when
449
+ // its body STARTS WITH the marker prefix: a marker quoted mid-body (someone
450
+ // replying with the report pasted in) must never be treated as ours. The
451
+ // LAST match wins — the API returns oldest→newest, so last is newest — and
452
+ // idempotency is find-and-update, never stack: if legacy duplicates exist we
453
+ // update the newest and leave history alone. None → null (the caller
454
+ // creates).
455
+ // `prefix` defaults to the summary comment's own marker, so every existing
456
+ // caller stays byte-identical. Parameterized (ROADMAP Pillar 3) so
457
+ // pr/pr.ts's postPrComment can reuse this exact find-or-update logic for a CI
458
+ // gate-skip comment under its own marker (ci/gates.ts's
459
+ // SKIP_SIZE_COMMENT_MARKER / SKIP_BUDGET_COMMENT_MARKER) — the same
460
+ // idempotency the summary comment already gets, so a repeat CI run on the
461
+ // same still-failing PR updates the existing skip comment instead of
462
+ // stacking a new one on every push.
463
+ export function findMarkedCommentId(
464
+ comments: { id: number; body: string }[],
465
+ prefix: string = PR_COMMENT_MARKER_PREFIX,
466
+ ): number | null {
467
+ let found: number | null = null;
468
+ for (const comment of comments) {
469
+ if (typeof comment?.body !== "string") continue;
470
+ if (matchMarkerPrefix(comment.body, prefix) === undefined) continue;
471
+ found = comment.id;
472
+ }
473
+ return found;
474
+ }
475
+
476
+ // ---------------------------------------------------------------------------
477
+ // Per-finding identity marker (ROADMAP B6) — the FIRST line of every inline
478
+ // review comment and un-anchorable issue comment pr-hero posts. It exists so
479
+ // a second run on the same PR can tell "I already posted this finding" from
480
+ // "this is new", without trusting `dedupe_key` or `root_cause_id`: both are
481
+ // derived by the hunter/dedupe pipeline fresh each run and are NOT stable
482
+ // across runs (a re-run can renumber or re-merge findings that describe the
483
+ // exact same defect). Identity here is LOCATION + OWNERSHIP — the marker
484
+ // prefix names the comment as ours, and path+line is what pr/inline.ts's
485
+ // matcher keys on.
486
+ //
487
+ // WHY the path is percent-encoded, stated exactly: c717fe4 (size-gate.ts)
488
+ // fixed a bug from the SAME failure family — git C-quotes any path with a
489
+ // space or non-ASCII byte (`core.quotepath`), and one code path unquoted
490
+ // while a sibling did not, so a file silently vanished from one side of a
491
+ // count that was supposed to agree with the other. A raw path pasted into an
492
+ // HTML comment attribute has the identical exposure: it can contain spaces,
493
+ // `=`, `--`, or bytes that break naive re-parsing of the marker's own fields.
494
+ // Percent-encoding removes the ambiguity at the source — the SAME reason
495
+ // resolveNumstatPath/diffRecordPath route every path through unquotePath —
496
+ // rather than adding another ad-hoc unescaper that could drift from the
497
+ // encoder the way the two unquote call sites once did.
498
+ //
499
+ // `c` (first 12 hex of sha256 over the normalized claim) is a TIE-BREAKER
500
+ // only, never a requirement: claim text is regenerated by an LLM every run
501
+ // and is not expected to be byte-stable, so parseFindingMarker must still
502
+ // treat a marker with a mismatched or absent `c` as parseable — matching on
503
+ // it is pr/inline.ts's business, not this parser's.
504
+ //
505
+ // Disjoint from PR_COMMENT_MARKER_PREFIX on purpose: both markers now live
506
+ // in the same issue-comment stream (the summary comment and per-finding
507
+ // issue comments post to the same PR), and a matcher that could mistake one
508
+ // marker family for the other would either orphan the summary comment or
509
+ // treat a per-finding comment as the summary. See the prefix-disjointness
510
+ // test in test/pr/preflight.test.ts.
511
+ export const PR_FINDING_MARKER_PREFIX = `${MARKER_OPEN}finding `;
512
+
513
+ export interface FindingMarkerFields {
514
+ path: string;
515
+ line: number;
516
+ headSha: string;
517
+ // Normalized claim text this marker's `c` was derived from. Optional on
518
+ // the encode side's caller convenience is not needed — findingMarker
519
+ // always requires it, since `c` has no meaning without the claim it was
520
+ // computed over.
521
+ claim: string;
522
+ }
523
+
524
+ // First 12 hex chars of sha256(claim.trim()) — enough entropy to break a tie
525
+ // between two candidates at the same distance, nowhere near enough (nor
526
+ // intended) to be a content-addressed identity on its own. Exported so
527
+ // pr/inline.ts's matcher can derive the SAME fingerprint over a current-run
528
+ // finding's claim to compare against a posted marker's `c` — design D3's
529
+ // tie-breaker only works if both sides compute it identically.
530
+ export function claimFingerprint(claim: string): string {
531
+ return new Bun.CryptoHasher("sha256")
532
+ .update(claim.trim())
533
+ .digest("hex")
534
+ .slice(0, 12);
535
+ }
536
+
537
+ export function findingMarker(fields: FindingMarkerFields): string {
538
+ const path = encodeURIComponent(fields.path);
539
+ const c = claimFingerprint(fields.claim);
540
+ return (
541
+ `${PR_FINDING_MARKER_PREFIX}path=${path} line=${fields.line} ` +
542
+ `head=${fields.headSha} c=${c} -->`
543
+ );
544
+ }
545
+
546
+ export interface ParsedFindingMarker {
547
+ path: string;
548
+ line: number;
549
+ headSha: string;
550
+ // The `c` tie-breaker as stored in the marker, verbatim (not re-derived —
551
+ // this parser has no access to the finding it once matched).
552
+ c: string;
553
+ }
554
+
555
+ // Parses ONLY the first line of a comment body, mirroring
556
+ // findMarkedCommentId's exact-prefix contract: a marker quoted mid-body
557
+ // (someone replying with the comment pasted in) must never parse as ours.
558
+ // Returns null for anything that is not a well-formed marker rather than
559
+ // throwing — a malformed or foreign marker-shaped line is a match failure,
560
+ // not a fatal error, and the caller (the matcher) treats "unparseable" the
561
+ // same as "no prior comment": it posts fresh rather than guess.
562
+ export function parseFindingMarker(body: string): ParsedFindingMarker | null {
563
+ const prefix = matchMarkerPrefix(body, PR_FINDING_MARKER_PREFIX);
564
+ if (prefix === undefined) return null;
565
+ const firstLine = body.split("\n", 1)[0] ?? "";
566
+ if (!firstLine.endsWith(" -->")) return null;
567
+ const fields = firstLine.slice(
568
+ prefix.length,
569
+ firstLine.length - " -->".length,
570
+ );
571
+ const parts = new Map<string, string>();
572
+ for (const token of fields.split(" ")) {
573
+ if (token.length === 0) continue;
574
+ const eq = token.indexOf("=");
575
+ if (eq === -1) continue;
576
+ parts.set(token.slice(0, eq), token.slice(eq + 1));
577
+ }
578
+ const rawPath = parts.get("path");
579
+ const rawLine = parts.get("line");
580
+ const headSha = parts.get("head");
581
+ const c = parts.get("c");
582
+ if (
583
+ rawPath === undefined ||
584
+ rawLine === undefined ||
585
+ headSha === undefined ||
586
+ c === undefined
587
+ ) {
588
+ return null;
589
+ }
590
+ const line = Number.parseInt(rawLine, 10);
591
+ if (!Number.isInteger(line)) return null;
592
+ let path: string;
593
+ try {
594
+ path = decodeURIComponent(rawPath);
595
+ } catch {
596
+ return null;
597
+ }
598
+ return { path, line, headSha, c };
599
+ }
600
+
601
+ // ---------------------------------------------------------------------------
602
+ // Commit status (in-flight signal on the PR head). GitHub Check Runs need a
603
+ // GitHub App; this CLI posts as the operator via `gh`, so the write path is
604
+ // the Commit Statuses API. Same yellow/green dot in the merge box, no
605
+ // Conversation comment. context is stable so the CI admission gate can read
606
+ // the latest `crysk` status back as the cross-machine in-flight lock.
607
+ //
608
+ // Every status is published on this name AND, for one version, on the legacy
609
+ // `pr-hero` one (postCommitStatus): users have `pr-hero` as a required check in
610
+ // branch protection, and a head that stops getting it blocks forever. The
611
+ // constants below name the new context; the readers here take a row on either
612
+ // name as the same context (isStatusContext).
613
+
614
+ // The gate. The required check reads this name, and only an explicit `--ci`
615
+ // run writes it (T3 S7): the author's agent, a local run and the watcher can
616
+ // never move the gate, so their statuses go to LOCAL_COMMIT_STATUS_CONTEXT.
617
+ export const COMMIT_STATUS_CONTEXT = STATUS_CONTEXT;
618
+
619
+ // Every non-CI run posts here: a local `review --pr`, the watcher's child, and
620
+ // CI=1 without --ci. Advisory states and descriptions only, so a local run
621
+ // that finishes with blocking findings cannot overwrite a red gate on the same
622
+ // head. A different context, not a different state set, is what keeps the gate
623
+ // safe: the posting code is shared and only the context name differs.
624
+ export const LOCAL_COMMIT_STATUS_CONTEXT = LOCAL_STATUS_CONTEXT;
625
+
626
+ export type CommitStatusContext =
627
+ | typeof COMMIT_STATUS_CONTEXT
628
+ | typeof LOCAL_COMMIT_STATUS_CONTEXT;
629
+
630
+ // Every context a run's status can sit on. The watcher and local runs (no --ci)
631
+ // read all of them: neither may start a review of a head that CI or another
632
+ // local run is already reviewing. A `--ci` run reads only COMMIT_STATUS_CONTEXT:
633
+ // it stands down for CI, never for a local run whose result the gate cannot see
634
+ // (ci-admission-gate.ts yieldToInFlightReview picks the set by posture).
635
+ export const RUN_STATUS_CONTEXTS: readonly CommitStatusContext[] = [
636
+ COMMIT_STATUS_CONTEXT,
637
+ LOCAL_COMMIT_STATUS_CONTEXT,
638
+ ];
639
+
640
+ // The contexts a run's in-flight yield reads (ci-admission-gate.ts
641
+ // yieldToInFlightReview). A `--ci` run reads only the gate; every other run reads
642
+ // all of them. Kept here, beside the constants, so the admission gate never names
643
+ // the gate context itself (test/pr/status-context.test.ts pins who may).
644
+ export function inFlightContextsFor(
645
+ statusContext: CommitStatusContext,
646
+ ): readonly CommitStatusContext[] {
647
+ return statusContext === COMMIT_STATUS_CONTEXT
648
+ ? [COMMIT_STATUS_CONTEXT]
649
+ : RUN_STATUS_CONTEXTS;
650
+ }
651
+
652
+ // DEFAULT_PIPELINE_TIMEOUT_MS is 75 min (pipeline.ts). A TTL inside that
653
+ // window would double-launch a slow live run still inside its watchdog.
654
+ export const IN_FLIGHT_TTL_MS = 90 * 60 * 1000;
655
+
656
+ // Same bound as GH_PR_VIEW_TIMEOUT_MS (store/gc-preflight.ts): a hung statuses
657
+ // API must not pin watch.lock or delay a pipeline that already confirmed.
658
+ export const COMMIT_STATUS_TIMEOUT_MS = 15_000;
659
+
660
+ // The cancellation settle runs inside a signal handler, and the runner
661
+ // SIGKILLs shortly after the signal. Two attempts at COMMIT_STATUS_TIMEOUT_MS
662
+ // outlive that grace window, and a settle that outlives SIGKILL is no settle
663
+ // at all — so the cancellation path trades the retry for landing in time.
664
+ export const CANCELLATION_COMMIT_STATUS_TIMEOUT_MS = 5_000;
665
+
666
+ // GitHub's commit-status description is a short field (historically 140).
667
+ export const COMMIT_STATUS_DESCRIPTION_MAX = 140;
668
+
669
+ export type CommitStatusState = "pending" | "success" | "failure" | "error";
670
+
671
+ // S4. `gate` (the CI default): the crysk commit status, which is the
672
+ // required check, goes red on blocking findings, a size or budget skip, and a
673
+ // crash. `advisory`: today's posture, a finished review is always green. Only
674
+ // CI runs have a mode; a local run is always advisory (see resolveCiMode).
675
+ export type CiMode = "gate" | "advisory";
676
+
677
+ // The mode a run actually uses. Only an explicit `--ci` run has a mode, and
678
+ // `ci` is that flag, never the CI/GITHUB_ACTIONS environment: a developer shell
679
+ // that exports CI=1 is not the gate, and a local `review --pr` that posted
680
+ // `failure` would turn a required check red for a reason its operator did not
681
+ // ask for. `ciMode` is undefined when --ci-mode was not given; gate is the
682
+ // default for an explicit CI run.
683
+ export function resolveCiMode(ciMode: CiMode | undefined, ci: boolean): CiMode {
684
+ if (!ci) return "advisory";
685
+ return ciMode ?? "gate";
686
+ }
687
+
688
+ // The one posture a run resolves from its own flags: the mode and the context
689
+ // its statuses post on. Both key on `--ci` alone, so no path can pair the
690
+ // gate's context with an advisory local run, and reviewPr resolves once and
691
+ // threads both values down (T3 S7).
692
+ export function resolveCiPosture(options: { ci?: boolean; ciMode?: CiMode }): {
693
+ ciMode: CiMode;
694
+ statusContext: CommitStatusContext;
695
+ } {
696
+ const ci = options.ci === true;
697
+ return {
698
+ ciMode: resolveCiMode(options.ciMode, ci),
699
+ statusContext: ci ? COMMIT_STATUS_CONTEXT : LOCAL_COMMIT_STATUS_CONTEXT,
700
+ };
701
+ }
702
+
703
+ export interface CommitStatusFact {
704
+ state: string;
705
+ context: string;
706
+ created_at: string;
707
+ // The status's description, read only where an override must be told apart from
708
+ // a review's own status (teardown.ts overrideStandsOverRun). Absent when the
709
+ // reader did not return it, which is never taken as an override.
710
+ description?: string | null;
711
+ // The run URL the status links to. Read only by `pr-hero status`, which names the run
712
+ // that wrote the gate. Absent when the reader did not return it.
713
+ target_url?: string | null;
714
+ }
715
+
716
+ export interface CommitStatusRequest {
717
+ state: CommitStatusState;
718
+ // The POST writes this context, so it is the request's to choose: a non-CI
719
+ // run's request names the local context, and only a `--ci` run's names pr-hero.
720
+ context: CommitStatusContext;
721
+ description: string;
722
+ targetUrl: string | undefined;
723
+ }
724
+
725
+ export function clipStatusDescription(text: string): string {
726
+ if (text.length <= COMMIT_STATUS_DESCRIPTION_MAX) return text;
727
+ return text.slice(0, COMMIT_STATUS_DESCRIPTION_MAX);
728
+ }
729
+
730
+ // `posted` only changes the success description: "review posted" when this
731
+ // run published a comment, "review complete" when it did not (--post off,
732
+ // or posting never ran). This is the advisory vocabulary and the crash/pending
733
+ // vocabulary: it never builds `failure`. A blocking finding turns red only
734
+ // through blockingCommitStatusRequest, and only in gate mode.
735
+ export function commitStatusRequest(input: {
736
+ phase: "pending" | "success" | "error";
737
+ posted: boolean;
738
+ targetUrl: string | undefined;
739
+ context: CommitStatusContext;
740
+ }): CommitStatusRequest {
741
+ const description =
742
+ input.phase === "pending"
743
+ ? `${STATUS_CONTEXT} reviewing`
744
+ : input.phase === "error"
745
+ ? "review did not finish"
746
+ : input.posted
747
+ ? "review posted"
748
+ : "review complete";
749
+ return {
750
+ state: input.phase === "pending" ? "pending" : input.phase,
751
+ context: input.context,
752
+ description: clipStatusDescription(description),
753
+ targetUrl: input.targetUrl,
754
+ };
755
+ }
756
+
757
+ // S4, gate mode: a finished review with unresolved blocking findings. The count
758
+ // is the gate's own (rereview/state.ts): this run's blocking survivors plus every
759
+ // live blocking prior that a verifier verdict or a deletion did not clear. A
760
+ // same-head `/pr-hero review` re-runs that same count, so it stays red. The
761
+ // ways to green are a fix that the re-review verifies gone, or
762
+ // `/pr-hero override`. A triage reply never lowers the count on its own (S7).
763
+ // Gate-only: the only caller is a gate-mode settle, which is always a `--ci` run.
764
+ // The context defaults to LOCAL so a caller that forgets it cannot reach the
765
+ // gate; the gate's callers pass COMMIT_STATUS_CONTEXT explicitly.
766
+ export function blockingCommitStatusRequest(input: {
767
+ blockingCount: number;
768
+ targetUrl: string | undefined;
769
+ context?: CommitStatusContext;
770
+ }): CommitStatusRequest {
771
+ return {
772
+ state: "failure",
773
+ context: input.context ?? LOCAL_COMMIT_STATUS_CONTEXT,
774
+ description: clipStatusDescription(
775
+ `${STATUS_CONTEXT}: ${input.blockingCount} blocking finding(s) — fix and push, or /pr-hero override`,
776
+ ),
777
+ targetUrl: input.targetUrl,
778
+ };
779
+ }
780
+
781
+ // S4, gate mode: a size or budget skip is red, so an unreviewed head cannot
782
+ // read as a clean one. `/pr-hero review` force-runs the review past both
783
+ // gates, which is the unlock the description names.
784
+ // Gate-only, like blockingCommitStatusRequest: the context defaults to LOCAL, and
785
+ // the one production caller (the admission gate's publishCiSkip) passes the gate's context.
786
+ export function skipCommitStatusRequest(input: {
787
+ kind: "size" | "budget";
788
+ targetUrl: string | undefined;
789
+ context?: CommitStatusContext;
790
+ }): CommitStatusRequest {
791
+ const reason =
792
+ input.kind === "size"
793
+ ? "diff over the size gate"
794
+ : "estimated cost over the CI budget";
795
+ return {
796
+ state: "failure",
797
+ context: input.context ?? LOCAL_COMMIT_STATUS_CONTEXT,
798
+ description: clipStatusDescription(
799
+ `${STATUS_CONTEXT} skipped the review: ${reason}. /pr-hero review reviews it anyway`,
800
+ ),
801
+ targetUrl: input.targetUrl,
802
+ };
803
+ }
804
+
805
+ // What settling an abandoned run needs, and nothing else. The process that
806
+ // posted the pending is the only one that knows all three, and by the time a
807
+ // signal arrives reviewPr's scope is unreachable — so this is what the
808
+ // module-level lock in cli.ts carries across that gap.
809
+ export interface HeldCommitStatusLock {
810
+ operatorRoot: string;
811
+ sha: string;
812
+ targetUrl: string | undefined;
813
+ // The context the held pending was posted on, so the signal settle clears
814
+ // that pending and no other. Absent means local: the settle then never names
815
+ // the gate, so a lock taken without one cannot overwrite a CI verdict (T3 S7).
816
+ context?: CommitStatusContext;
817
+ }
818
+
819
+ // The pure half of the cancellation settle: lock in, the exact three
820
+ // arguments postCommitStatus takes out. `phase: "error"` is reused verbatim
821
+ // — its description, "review did not finish", is already the honest sentence
822
+ // for a cancelled run, so no new vocabulary enters the status contract.
823
+ //
824
+ // The SHA is the load-bearing field. It is the head the pending was posted
825
+ // on, captured at publish time; resolving the head again inside a signal
826
+ // handler could name a different commit and leave the real lock standing.
827
+ export function settleRequestForCancellation(
828
+ lock: HeldCommitStatusLock | null,
829
+ ): { operatorRoot: string; sha: string; request: CommitStatusRequest } | null {
830
+ if (lock === null) return null;
831
+ // WHY PRH-CANCELLED and not "review did not finish": a signal is a cancel, and the
832
+ // action's cancel-settle step writes the same text when this settle does not land
833
+ // first (src/ci/publish.ts runCancelSettle). Either writer leaves one coded status.
834
+ return {
835
+ operatorRoot: lock.operatorRoot,
836
+ sha: lock.sha,
837
+ request: {
838
+ ...commitStatusRequest({
839
+ phase: "error",
840
+ posted: false,
841
+ targetUrl: lock.targetUrl,
842
+ context: lock.context ?? LOCAL_COMMIT_STATUS_CONTEXT,
843
+ }),
844
+ description: clipStatusDescription(CANCELLED_STATUS_DESCRIPTION),
845
+ },
846
+ };
847
+ }
848
+
849
+ // The finally-block matrix. A finished pipeline that is not sessionFailed is
850
+ // success even if --post threw (the review ran; the comment is a separate
851
+ // write). Anything else — crash before pipeline return, or every hunter dead —
852
+ // is error in both modes.
853
+ //
854
+ // S4 adds one red verdict on top, gate only: a finished review with blocking
855
+ // findings is failure, and the count rides along for the description. Advisory
856
+ // never reads the count, so it keeps the two-state matrix exactly. An unknown
857
+ // count (publishRunOutcome threw before the findings doc existed) is error in
858
+ // gate: a gate cannot call a review it never read clean.
859
+ export type CommitStatusCompletion =
860
+ | { phase: "success" | "error" }
861
+ | { phase: "failure"; blockingCount: number }
862
+ // set is absent when no failed-hunter names were read: hashing an empty list would
863
+ // give every such verdict one shared key, and two of them would read as the same set.
864
+ | { phase: "partial"; failed: number; total: number; set?: string };
865
+
866
+ // W4-R363 S1: the failed hunters' identity, not only their count. A different hunter failing with the same
867
+ // N of M reads as a different partial verdict. Six hex of sha256 over the sorted unique names is enough to
868
+ // tell two failed sets apart on a status line; it is a comparison key, never a secret.
869
+ export function hunterFailureSetKey(names: readonly string[]): string {
870
+ const sorted = [...new Set(names)].sort();
871
+ return createHash("sha256")
872
+ .update(sorted.join(","))
873
+ .digest("hex")
874
+ .slice(0, 6);
875
+ }
876
+
877
+ // The set key rides right after the counts. Absent only for a text written before the key existed.
878
+ function partialCountsSuffix(set: string | undefined): string {
879
+ return set === undefined ? "" : `, set ${set}`;
880
+ }
881
+
882
+ // S1, gate mode: a finished review where some hunters failed but not all, and no blocking
883
+ // finding survived. The gate cannot call that green: a reviewer that never ran may have been
884
+ // the one that would have blocked. `/pr-hero review` runs the head again, which is the unlock.
885
+ // The variable parts are the failed count (N) and the hunters that ran (M).
886
+ export function partialReviewDescription(
887
+ failed: number,
888
+ total: number,
889
+ set?: string,
890
+ ): string {
891
+ return clipStatusDescription(
892
+ `${STATUS_CONTEXT}: review partial (${failed} of ${total} hunters failed${partialCountsSuffix(set)}) — /pr-hero review retries it`,
893
+ );
894
+ }
895
+
896
+ // W3-PARTIAL S1: the repeat of a partial review, the same N of M failure set on the head's previous
897
+ // verdict. The unlock names the route fix or the override, because a retry already ran and failed.
898
+ export function partialReviewAgainDescription(
899
+ failed: number,
900
+ total: number,
901
+ set?: string,
902
+ ): string {
903
+ return clipStatusDescription(
904
+ `${STATUS_CONTEXT}: review partial again (${failed} of ${total} hunters failed${partialCountsSuffix(set)}) — fix the failing route or /pr-hero override`,
905
+ );
906
+ }
907
+
908
+ export function partialReviewCommitStatusRequest(input: {
909
+ failed: number;
910
+ total: number;
911
+ set?: string;
912
+ targetUrl: string | undefined;
913
+ context: CommitStatusContext;
914
+ // W3-PARTIAL S1: the head's previous verdict was this same partial, so the repeat text is written.
915
+ repeat?: boolean;
916
+ }): CommitStatusRequest {
917
+ return {
918
+ state: "failure",
919
+ context: input.context,
920
+ description:
921
+ input.repeat === true
922
+ ? partialReviewAgainDescription(input.failed, input.total, input.set)
923
+ : partialReviewDescription(input.failed, input.total, input.set),
924
+ targetUrl: input.targetUrl,
925
+ };
926
+ }
927
+
928
+ export function commitStatusCompletion(input: {
929
+ pipelineFinished: boolean;
930
+ sessionFailed: boolean;
931
+ ciMode: CiMode;
932
+ blockingCount: number | null;
933
+ // S4: M and N. Absent means no hunter counts were read, which is never a partial review.
934
+ hunterCount?: number;
935
+ hunterFailures?: number;
936
+ // W4-R363 S1: the names of the failed hunters, which the partial verdict's set key is made of.
937
+ hunterFailureNames?: readonly string[];
938
+ // The pipeline's own statement that no hunter ran on a run meant to review
939
+ // (PipelineResult.noReviewerRan). Absent reads as false.
940
+ noReviewerRan?: boolean;
941
+ }): CommitStatusCompletion {
942
+ if (!input.pipelineFinished || input.sessionFailed) return { phase: "error" };
943
+ if (input.ciMode === "advisory") return { phase: "success" };
944
+ if (input.blockingCount === null) return { phase: "error" };
945
+ // WHY a blocking count wins over a partial review: a blocking finding is more actionable
946
+ // than a retry. The author has a concrete fix to push, and the description keeps that text.
947
+ if (input.blockingCount > 0) {
948
+ return { phase: "failure", blockingCount: input.blockingCount };
949
+ }
950
+ // WHY a review in which no reviewer ran is not green: the budget ceiling or an unusable
951
+ // gotchas file can stop the run before any hunter starts, and sessionFailed stays false
952
+ // because no hunter failed. The gate cannot call that clean, so it reads as a review
953
+ // that did not finish. The pipeline says so itself (noReviewerRan): a zero hunter count
954
+ // alone is also a re-review that skipped discovery on purpose, which is a finished review.
955
+ if (input.noReviewerRan === true) return { phase: "error" };
956
+ // A missing count on either side reads as no partial review: a failed count without its M
957
+ // is not a verdict the gate can word.
958
+ const failed = input.hunterFailures ?? 0;
959
+ const total = input.hunterCount ?? 0;
960
+ if (failed >= 1 && total >= failed) {
961
+ const names = input.hunterFailureNames ?? [];
962
+ return {
963
+ phase: "partial",
964
+ failed,
965
+ total,
966
+ ...(names.length === 0 ? {} : { set: hunterFailureSetKey(names) }),
967
+ };
968
+ }
969
+ return { phase: "success" };
970
+ }
971
+
972
+ export function prHtmlUrl(
973
+ repoUrl: string | undefined,
974
+ pr: number,
975
+ ): string | undefined {
976
+ if (repoUrl === undefined || repoUrl.trim() === "") return undefined;
977
+ if (!Number.isInteger(pr) || pr < 1) return undefined;
978
+ const url = `${repoUrl.replace(/\/$/, "")}/pull/${pr}`;
979
+ return URL.canParse(url) ? url : undefined;
980
+ }
981
+
982
+ // The newest row of one context by created_at, across both of its names (crysk and the legacy
983
+ // pr-hero): an override an older action posted only on `pr-hero` is the gate when it is newer
984
+ // than this version's `crysk` verdict. A tie within one name goes to the later row in the list
985
+ // (`>=`); a tie across the names goes to the crysk row, because the pair a run writes has one
986
+ // content on both and the answer must not depend on the order of the list.
987
+ export function latestStatusInContext(
988
+ statuses: readonly CommitStatusFact[],
989
+ context: CommitStatusContext,
990
+ ): CommitStatusFact | null {
991
+ let latest: CommitStatusFact | null = null;
992
+ let latestMs = Number.NEGATIVE_INFINITY;
993
+ for (const status of statuses) {
994
+ if (!isStatusContext(status.context, context)) continue;
995
+ const createdMs = Date.parse(status.created_at);
996
+ if (Number.isNaN(createdMs)) continue;
997
+ const keepsLatest =
998
+ createdMs === latestMs &&
999
+ latest !== null &&
1000
+ !isLegacyStatusContext(latest.context) &&
1001
+ isLegacyStatusContext(status.context);
1002
+ if (createdMs >= latestMs && !keepsLatest) {
1003
+ latest = status;
1004
+ latestMs = createdMs;
1005
+ }
1006
+ }
1007
+ return latest;
1008
+ }
1009
+
1010
+ // Latest status for our context, by created_at — GitHub's list is usually
1011
+ // newest-first, but the watcher must not depend on that. A pending older
1012
+ // than the TTL is NOT in-flight: the process likely died, and the next tick
1013
+ // must be allowed to launch.
1014
+ // In-flight in ANY of the given contexts: each context's own latest status is
1015
+ // judged, so a fresh pending on one never hides behind a settled one on another.
1016
+ // The default reads the gate alone, which is a `--ci` run's yield. A non-CI run
1017
+ // passes RUN_STATUS_CONTEXTS, so it also stands down for a local pending.
1018
+ export function isInFlightCommitStatus(
1019
+ statuses: readonly CommitStatusFact[],
1020
+ nowMs: number,
1021
+ ttlMs: number = IN_FLIGHT_TTL_MS,
1022
+ contexts: readonly CommitStatusContext[] = [COMMIT_STATUS_CONTEXT],
1023
+ ): boolean {
1024
+ return contexts.some((context) => {
1025
+ const latest = latestStatusInContext(statuses, context);
1026
+ if (latest === null || latest.state !== "pending") return false;
1027
+ const createdMs = Date.parse(latest.created_at);
1028
+ if (Number.isNaN(createdMs)) return false;
1029
+ return nowMs - createdMs < ttlMs;
1030
+ });
1031
+ }