@intentius/chant 0.124.108 → 0.124.110

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 (342) hide show
  1. package/dist/__golden__/wave-loop/fan-out-applied.json +12 -6
  2. package/dist/__golden__/wave-loop/fan-out-apply-fails.json +8 -4
  3. package/dist/__golden__/wave-loop/fan-out-gated.json +4 -2
  4. package/dist/__golden__/wave-loop/fan-out-no-members.json +16 -8
  5. package/dist/__golden__/wave-loop/fan-out-plan-fails.json +8 -4
  6. package/dist/__golden__/wave-loop/fan-out-same-root.json +4 -2
  7. package/dist/agent-facts.d.ts +130 -0
  8. package/dist/agent-facts.js +196 -0
  9. package/dist/change-risk.d.ts +216 -0
  10. package/dist/change-risk.js +304 -0
  11. package/dist/change-set.d.ts +8 -0
  12. package/dist/ci-agent-alert.d.ts +139 -0
  13. package/dist/ci-agent-alert.js +342 -0
  14. package/dist/ci-agent-triggers.d.ts +152 -0
  15. package/dist/ci-agent-triggers.js +232 -0
  16. package/dist/ci-agent-verify-failed.d.ts +149 -0
  17. package/dist/ci-agent-verify-failed.js +191 -0
  18. package/dist/ci-agent.d.ts +136 -8
  19. package/dist/ci-agent.js +353 -26
  20. package/dist/ci-comment-commands.d.ts +8 -0
  21. package/dist/ci-comment-commands.js +17 -1
  22. package/dist/ci-comment-reject.d.ts +70 -0
  23. package/dist/ci-comment-reject.js +135 -0
  24. package/dist/ci-comment-replies.d.ts +3 -1
  25. package/dist/ci-comment-replies.js +6 -0
  26. package/dist/ci-estate/delivery.d.ts +25 -3
  27. package/dist/ci-estate/delivery.js +28 -9
  28. package/dist/ci-estate/page.d.ts +7 -3
  29. package/dist/ci-estate/page.js +19 -4
  30. package/dist/ci-estate/rows.d.ts +14 -2
  31. package/dist/ci-estate/rows.js +9 -1
  32. package/dist/ci-estate.d.ts +5 -2
  33. package/dist/ci-estate.js +3 -2
  34. package/dist/ci-handover.d.ts +2 -7
  35. package/dist/ci-handover.js +3 -20
  36. package/dist/ci-jobs.d.ts +6 -0
  37. package/dist/ci-jobs.js +17 -0
  38. package/dist/ci-note-commands.d.ts +2 -0
  39. package/dist/ci-note-commands.js +12 -1
  40. package/dist/ci-product-words.d.ts +151 -1
  41. package/dist/ci-product-words.js +1390 -3
  42. package/dist/ci-product.d.ts +100 -4
  43. package/dist/ci-product.js +99 -3
  44. package/dist/ci-respond-run.d.ts +9 -0
  45. package/dist/ci-respond-run.js +35 -4
  46. package/dist/ci-respond-summary-env.d.ts +56 -0
  47. package/dist/ci-respond-summary-env.js +81 -0
  48. package/dist/ci-respond-summary.d.ts +103 -0
  49. package/dist/ci-respond-summary.js +243 -0
  50. package/dist/ci-respond.d.ts +4 -2
  51. package/dist/ci-respond.js +4 -2
  52. package/dist/cli/command-group.js +1 -1
  53. package/dist/cli/commands/lint.js +21 -3
  54. package/dist/cli/handlers/agent.js +49 -4
  55. package/dist/cli/handlers/approve.js +3 -1
  56. package/dist/cli/handlers/build.d.ts +97 -1
  57. package/dist/cli/handlers/build.js +251 -3
  58. package/dist/cli/handlers/fan-out.js +55 -0
  59. package/dist/cli/handlers/graph.d.ts +14 -0
  60. package/dist/cli/handlers/graph.js +58 -3
  61. package/dist/cli/handlers/lifecycle-health.d.ts +7 -0
  62. package/dist/cli/handlers/lifecycle-health.js +47 -9
  63. package/dist/cli/handlers/lifecycle.js +4 -1
  64. package/dist/cli/handlers/notify-relay.d.ts +2 -2
  65. package/dist/cli/handlers/notify-relay.js +67 -7
  66. package/dist/cli/handlers/pipeline-agent.d.ts +30 -0
  67. package/dist/cli/handlers/pipeline-agent.js +255 -0
  68. package/dist/cli/handlers/pipeline-artifacts.d.ts +39 -0
  69. package/dist/cli/handlers/pipeline-artifacts.js +203 -0
  70. package/dist/cli/handlers/pipeline.d.ts +16 -0
  71. package/dist/cli/handlers/pipeline.js +112 -0
  72. package/dist/cli/handlers/pr-comment.js +4 -0
  73. package/dist/cli/handlers/pr-notes.js +4 -1
  74. package/dist/cli/handlers/pr.d.ts +20 -0
  75. package/dist/cli/handlers/pr.js +114 -11
  76. package/dist/cli/handlers/promote.js +792 -47
  77. package/dist/cli/handlers/reject.d.ts +84 -0
  78. package/dist/cli/handlers/reject.js +216 -0
  79. package/dist/cli/handlers/release.js +4 -2
  80. package/dist/cli/handlers/replan.d.ts +54 -0
  81. package/dist/cli/handlers/replan.js +177 -0
  82. package/dist/cli/handlers/run-generate.d.ts +5 -0
  83. package/dist/cli/handlers/run-generate.js +31 -4
  84. package/dist/cli/handlers/run-wave.js +15 -2
  85. package/dist/cli/handlers/run.js +4 -2
  86. package/dist/cli/handlers/stage.d.ts +35 -0
  87. package/dist/cli/handlers/stage.js +90 -0
  88. package/dist/cli/lsp/server.js +4 -0
  89. package/dist/cli/main.js +88 -8
  90. package/dist/cli/parse-args.js +35 -2
  91. package/dist/cli/registry.d.ts +12 -0
  92. package/dist/components/auto-release.d.ts +2 -0
  93. package/dist/components/auto-release.js +1 -0
  94. package/dist/components/capability.d.ts +40 -0
  95. package/dist/components/cli-support.d.ts +21 -1
  96. package/dist/components/cli-support.js +28 -6
  97. package/dist/components/component.d.ts +23 -4
  98. package/dist/components/component.schema.json +28 -0
  99. package/dist/components/declared-reads.d.ts +44 -4
  100. package/dist/components/declared-reads.js +80 -3
  101. package/dist/components/discover.d.ts +8 -0
  102. package/dist/components/discover.js +1 -1
  103. package/dist/components/driver.d.ts +13 -0
  104. package/dist/components/driver.js +23 -2
  105. package/dist/components/environment-sets.d.ts +229 -0
  106. package/dist/components/environment-sets.js +338 -0
  107. package/dist/components/fan-out-canary.d.ts +47 -0
  108. package/dist/components/fan-out-canary.js +58 -0
  109. package/dist/components/fan-out-run.d.ts +17 -0
  110. package/dist/components/fan-out-run.js +14 -1
  111. package/dist/components/fan-out-support.d.ts +7 -0
  112. package/dist/components/fan-out-support.js +1 -1
  113. package/dist/components/groups.d.ts +8 -1
  114. package/dist/components/groups.js +19 -1
  115. package/dist/components/index.d.ts +5 -2
  116. package/dist/components/index.js +4 -1
  117. package/dist/components/pr-cost.d.ts +28 -0
  118. package/dist/components/pr-cost.js +53 -0
  119. package/dist/components/pr-pipeline.d.ts +33 -0
  120. package/dist/components/pr-pipeline.js +32 -5
  121. package/dist/components/pr-policy.d.ts +33 -2
  122. package/dist/components/pr-policy.js +5 -2
  123. package/dist/components/pr-risk.d.ts +42 -0
  124. package/dist/components/pr-risk.js +74 -0
  125. package/dist/components/product-pipeline.d.ts +43 -0
  126. package/dist/components/product-pipeline.js +67 -1
  127. package/dist/components/promote.d.ts +6 -0
  128. package/dist/components/promote.js +13 -0
  129. package/dist/components/release-compile.js +3 -1
  130. package/dist/components/release-gate.d.ts +6 -1
  131. package/dist/components/release-gate.js +10 -2
  132. package/dist/components/step-environments.d.ts +236 -0
  133. package/dist/components/step-environments.js +392 -0
  134. package/dist/components/upstream-replan.d.ts +201 -0
  135. package/dist/components/upstream-replan.js +249 -0
  136. package/dist/components/verify-step.d.ts +30 -0
  137. package/dist/components/verify-step.js +27 -0
  138. package/dist/components/wave-plan.js +6 -2
  139. package/dist/config-environments.d.ts +4 -2
  140. package/dist/control/dispatch.d.ts +15 -0
  141. package/dist/control/dispatch.js +28 -4
  142. package/dist/cost-estimate.d.ts +188 -0
  143. package/dist/cost-estimate.js +363 -0
  144. package/dist/drift-record.d.ts +36 -0
  145. package/dist/drift-record.js +44 -0
  146. package/dist/engine-facts.d.ts +105 -0
  147. package/dist/engine-facts.js +111 -0
  148. package/dist/exit-codes.d.ts +4 -3
  149. package/dist/exit-codes.js +4 -3
  150. package/dist/flag-params.d.ts +2 -2
  151. package/dist/flag-params.js +9 -4
  152. package/dist/floor-table.data.js +53 -0
  153. package/dist/forge-token-vars.d.ts +12 -0
  154. package/dist/forge-token-vars.js +25 -0
  155. package/dist/gate-decision.d.ts +3 -1
  156. package/dist/gate-decision.js +3 -1
  157. package/dist/gated-waves.d.ts +2 -0
  158. package/dist/gated-waves.js +1 -0
  159. package/dist/graph-ir.d.ts +30 -0
  160. package/dist/graph-ir.js +33 -1
  161. package/dist/graph-refs.d.ts +26 -0
  162. package/dist/graph-refs.js +34 -3
  163. package/dist/graph-schema/graph.schema.json +136 -0
  164. package/dist/health.d.ts +65 -0
  165. package/dist/health.js +62 -0
  166. package/dist/lexicon.d.ts +188 -1
  167. package/dist/lifecycle/disruption.d.ts +14 -1
  168. package/dist/lifecycle/disruption.js +5 -1
  169. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  170. package/dist/lifecycle/gate-change-set.js +2 -1
  171. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  172. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  173. package/dist/lifecycle/gate-rejection.js +93 -0
  174. package/dist/lifecycle/gate-seal.d.ts +3 -3
  175. package/dist/lifecycle/gate-seal.js +5 -5
  176. package/dist/lifecycle/observe.d.ts +17 -0
  177. package/dist/lifecycle/observe.js +10 -1
  178. package/dist/lifecycle/release-cut.js +4 -0
  179. package/dist/lifecycle/release-ledger.d.ts +8 -0
  180. package/dist/lifecycle/release-risk.d.ts +137 -0
  181. package/dist/lifecycle/release-risk.js +214 -0
  182. package/dist/lifecycle/release-store.d.ts +9 -0
  183. package/dist/lifecycle/release-store.js +4 -0
  184. package/dist/lifecycle/stage-log.d.ts +85 -0
  185. package/dist/lifecycle/stage-log.js +141 -0
  186. package/dist/lint/canary-checks.d.ts +31 -0
  187. package/dist/lint/canary-checks.js +45 -0
  188. package/dist/lint/rule.d.ts +1 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  190. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  191. package/dist/lint/rules/index.d.ts +1 -0
  192. package/dist/lint/rules/index.js +3 -0
  193. package/dist/notify-relay-repo.d.ts +54 -0
  194. package/dist/notify-relay-repo.js +84 -0
  195. package/dist/notify-relay.d.ts +53 -3
  196. package/dist/notify-relay.js +96 -3
  197. package/dist/notify.d.ts +57 -1
  198. package/dist/notify.js +7 -1
  199. package/dist/notify.schema.json +61 -3
  200. package/dist/observation.d.ts +34 -0
  201. package/dist/observation.js +14 -1
  202. package/dist/op/activities/review-agent.d.ts +39 -2
  203. package/dist/op/activities/review-agent.js +88 -5
  204. package/dist/op/agent-permit.d.ts +88 -0
  205. package/dist/op/agent-permit.js +97 -0
  206. package/dist/op/gate-approval-base.d.ts +8 -0
  207. package/dist/op/gate-approval-base.js +9 -0
  208. package/dist/op/gate-approval.d.ts +30 -1
  209. package/dist/op/gate-approval.js +23 -2
  210. package/dist/op/gate-quorum.d.ts +114 -8
  211. package/dist/op/gate-quorum.js +198 -21
  212. package/dist/op/gate-reject.d.ts +79 -0
  213. package/dist/op/gate-reject.js +96 -0
  214. package/dist/op/gate-summary.js +1 -1
  215. package/dist/op/gate.d.ts +28 -3
  216. package/dist/op/gate.js +55 -13
  217. package/dist/op/generate-pipeline.d.ts +15 -1
  218. package/dist/op/generate-pipeline.js +32 -5
  219. package/dist/op/index.d.ts +11 -6
  220. package/dist/op/index.js +10 -5
  221. package/dist/op/local-executor.d.ts +2 -0
  222. package/dist/op/local-executor.js +23 -4
  223. package/dist/op/op-waves-after-plan.d.ts +23 -0
  224. package/dist/op/op-waves-after-plan.js +12 -1
  225. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  226. package/dist/op/op-waves-capability-spec.js +46 -6
  227. package/dist/op/op-waves-capability.d.ts +21 -13
  228. package/dist/op/op-waves-capability.js +22 -59
  229. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  230. package/dist/op/op-waves-environment-sets.js +82 -0
  231. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  232. package/dist/op/op-waves-quorum-warnings.js +90 -0
  233. package/dist/op/op-waves-release-port.d.ts +7 -0
  234. package/dist/op/op-waves-release-port.js +15 -3
  235. package/dist/op/op-waves-release.d.ts +15 -0
  236. package/dist/op/op-waves-release.js +15 -0
  237. package/dist/op/op-waves-run.d.ts +37 -3
  238. package/dist/op/op-waves-run.js +141 -18
  239. package/dist/op/op-waves-soak.d.ts +57 -0
  240. package/dist/op/op-waves-soak.js +111 -0
  241. package/dist/op/op-waves-split.d.ts +4 -0
  242. package/dist/op/op-waves-split.js +4 -0
  243. package/dist/op/op-waves.d.ts +67 -4
  244. package/dist/op/op-waves.js +71 -3
  245. package/dist/pipeline/agent-ajv.d.ts +4 -0
  246. package/dist/pipeline/agent-ajv.js +14 -0
  247. package/dist/pipeline/agent-steps.d.ts +329 -0
  248. package/dist/pipeline/agent-steps.js +602 -0
  249. package/dist/pipeline/artifacts.d.ts +264 -0
  250. package/dist/pipeline/artifacts.js +425 -0
  251. package/dist/pipeline/diff.d.ts +45 -0
  252. package/dist/pipeline/diff.js +177 -0
  253. package/dist/pipeline/fold.d.ts +43 -0
  254. package/dist/pipeline/fold.js +140 -0
  255. package/dist/pipeline/generate.d.ts +52 -0
  256. package/dist/pipeline/generate.js +120 -0
  257. package/dist/pipeline/product.d.ts +225 -0
  258. package/dist/pipeline/product.js +257 -0
  259. package/dist/pipeline/promote.d.ts +404 -0
  260. package/dist/pipeline/promote.js +694 -0
  261. package/dist/pipeline/read.d.ts +37 -0
  262. package/dist/pipeline/read.js +58 -0
  263. package/dist/pipeline/rendered.d.ts +25 -0
  264. package/dist/pipeline/rendered.js +53 -0
  265. package/dist/pipeline/soak-checks.d.ts +80 -0
  266. package/dist/pipeline/soak-checks.js +254 -0
  267. package/dist/pipeline/soak-gate.d.ts +97 -0
  268. package/dist/pipeline/soak-gate.js +176 -0
  269. package/dist/pipeline/soak-sources.d.ts +17 -0
  270. package/dist/pipeline/soak-sources.js +42 -0
  271. package/dist/pipeline/soak.d.ts +260 -0
  272. package/dist/pipeline/soak.js +378 -0
  273. package/dist/pipeline/spec.d.ts +724 -0
  274. package/dist/pipeline/spec.js +567 -0
  275. package/dist/pipeline/stage-ledger.d.ts +187 -0
  276. package/dist/pipeline/stage-ledger.js +185 -0
  277. package/dist/pipeline/stage-waves.d.ts +114 -0
  278. package/dist/pipeline/stage-waves.js +161 -0
  279. package/dist/pipeline/stages.d.ts +64 -0
  280. package/dist/pipeline/stages.js +174 -0
  281. package/dist/pipeline/verify-rollback.d.ts +277 -0
  282. package/dist/pipeline/verify-rollback.js +393 -0
  283. package/dist/pipeline.d.ts +142 -0
  284. package/dist/pipeline.js +143 -0
  285. package/dist/pr-loop.d.ts +22 -0
  286. package/dist/pr-loop.js +8 -0
  287. package/dist/pr-plan-note.d.ts +15 -1
  288. package/dist/pr-plan-note.js +8 -0
  289. package/dist/pr-post.d.ts +31 -0
  290. package/dist/pr-post.js +89 -0
  291. package/dist/release-floors.d.ts +1 -1
  292. package/dist/release-floors.js +1 -1
  293. package/dist/report-store/audit.schema.json +50 -0
  294. package/dist/report-store/dora.schema.json +331 -0
  295. package/dist/report-store/estate.schema.json +96 -0
  296. package/dist/report-store/run.schema.json +14 -0
  297. package/dist/report-store.d.ts +151 -0
  298. package/dist/report-store.js +344 -0
  299. package/dist/run-event.d.ts +7 -2
  300. package/dist/wave-runtime.mjs +458 -404
  301. package/dist/workspace/catalog-edges.js +3 -3
  302. package/dist/workspace/change-set.schema.json +4 -0
  303. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  304. package/dist/workspace/ci-cloud-identity.js +30 -0
  305. package/dist/workspace/ci-run.js +17 -2
  306. package/dist/workspace/ci-secrets.d.ts +3 -1
  307. package/dist/workspace/ci-secrets.js +7 -1
  308. package/dist/workspace/compose-graph.d.ts +1 -1
  309. package/dist/workspace/compose-graph.js +3 -1
  310. package/dist/workspace/declaration.d.ts +27 -0
  311. package/dist/workspace/declaration.js +35 -0
  312. package/dist/workspace/declaration.schema.json +56 -0
  313. package/dist/workspace/graph-cli.js +26 -0
  314. package/dist/workspace/graph.schema.json +5 -1
  315. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  316. package/dist/workspace/identity-gate-rule.js +2 -2
  317. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  318. package/dist/workspace/identity-reject-rule.js +24 -0
  319. package/dist/workspace/identity.d.ts +3 -0
  320. package/dist/workspace/identity.js +2 -1
  321. package/dist/workspace/nested-graph.js +2 -0
  322. package/dist/workspace/pr-report.schema.json +65 -0
  323. package/dist/workspace/promotion-order.d.ts +19 -4
  324. package/dist/workspace/promotion-order.js +26 -4
  325. package/dist/workspace/release-train.d.ts +14 -0
  326. package/dist/workspace/release-train.js +32 -0
  327. package/dist/workspace/run-event.schema.json +2 -2
  328. package/dist/workspace/stack-read-edges.d.ts +19 -0
  329. package/dist/workspace/stack-read-edges.js +54 -0
  330. package/dist/workspace/status-gates.d.ts +51 -1
  331. package/dist/workspace/status-gates.js +60 -0
  332. package/dist/workspace/status-stages.d.ts +223 -0
  333. package/dist/workspace/status-stages.js +279 -0
  334. package/dist/workspace/status.d.ts +45 -1
  335. package/dist/workspace/status.js +109 -5
  336. package/dist/workspace/status.schema.json +283 -2
  337. package/dist/workspace/train-cut.js +5 -2
  338. package/dist/workspace/train-shell.d.ts +18 -0
  339. package/dist/workspace/train-shell.js +43 -0
  340. package/dist/workspace/trust/seal.d.ts +7 -0
  341. package/dist/workspace/trust/seal.js +9 -0
  342. package/package.json +5 -1
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Reading a member's pipeline (#5324): from its working tree, for builds and
3
+ * for showing the order, and from a commit, for the gates. A gate folds the
4
+ * file as it stood at the base commit, as an op wave reads its spec there,
5
+ * so a change cannot loosen the gate it is judged by. Folding runs nothing,
6
+ * so reading the change's own file is safe too (the plan note's diff).
7
+ */
8
+ import { type PipelineFinding } from "./fold.js";
9
+ import { type PipelineSpec } from "./spec.js";
10
+ /** A member's pipeline as read: absent, folded, or refused with its finding. */
11
+ export type PipelineRead = {
12
+ status: "absent";
13
+ } | {
14
+ status: "folded";
15
+ file: string;
16
+ spec: PipelineSpec;
17
+ } | {
18
+ status: "refused";
19
+ file: string;
20
+ finding: PipelineFinding;
21
+ line: string;
22
+ };
23
+ /** The pipeline in member directory `dir`'s working tree. */
24
+ export declare function readMemberPipeline(dir: string): PipelineRead;
25
+ /** The file's text at `commit` in the repository holding `cwd`, or null when that commit has none. `file` is relative to `cwd`. */
26
+ export type PipelineShow = (commit: string, file: string, cwd: string) => string | null;
27
+ /** {@link PipelineShow} through git. */
28
+ export declare const gitShowPipeline: PipelineShow;
29
+ /** The member's pipeline as it stood at `commit`: absent when the commit has no pipeline file. */
30
+ export declare function readPipelineAt(commit: string, cwd: string, show?: PipelineShow): PipelineRead;
31
+ /**
32
+ * The commit a promote reads its gates at: the default branch as the
33
+ * remote has it (`origin/HEAD`, else `origin/main`, else `origin/master`),
34
+ * else `HEAD` when the repository has no remote. A promote run from a
35
+ * branch with an edited pipeline is still judged by the merged one.
36
+ */
37
+ export declare function promoteBase(cwd: string): string | undefined;
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Reading a member's pipeline (#5324): from its working tree, for builds and
3
+ * for showing the order, and from a commit, for the gates. A gate folds the
4
+ * file as it stood at the base commit, as an op wave reads its spec there,
5
+ * so a change cannot loosen the gate it is judged by. Folding runs nothing,
6
+ * so reading the change's own file is safe too (the plan note's diff).
7
+ */
8
+ import { execFileSync } from "node:child_process";
9
+ import { existsSync, readFileSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { foldPipelineSource, pipelineFindingLine } from "./fold.js";
12
+ import { PIPELINE_FILE } from "./spec.js";
13
+ function fromText(text, file) {
14
+ const folded = foldPipelineSource(text, file);
15
+ if ("spec" in folded)
16
+ return { status: "folded", file, spec: folded.spec };
17
+ return { status: "refused", file, finding: folded.finding, line: pipelineFindingLine(file, folded.finding) };
18
+ }
19
+ /** The pipeline in member directory `dir`'s working tree. */
20
+ export function readMemberPipeline(dir) {
21
+ const path = join(dir, PIPELINE_FILE);
22
+ if (!existsSync(path))
23
+ return { status: "absent" };
24
+ return fromText(readFileSync(path, "utf-8"), PIPELINE_FILE);
25
+ }
26
+ /** {@link PipelineShow} through git. */
27
+ export const gitShowPipeline = (commit, file, cwd) => {
28
+ try {
29
+ return execFileSync("git", ["show", `${commit}:./${file}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
30
+ }
31
+ catch {
32
+ return null;
33
+ }
34
+ };
35
+ /** The member's pipeline as it stood at `commit`: absent when the commit has no pipeline file. */
36
+ export function readPipelineAt(commit, cwd, show = gitShowPipeline) {
37
+ const text = show(commit, PIPELINE_FILE, cwd);
38
+ return text === null ? { status: "absent" } : fromText(text, `${PIPELINE_FILE} at ${commit.slice(0, 12)}`);
39
+ }
40
+ /**
41
+ * The commit a promote reads its gates at: the default branch as the
42
+ * remote has it (`origin/HEAD`, else `origin/main`, else `origin/master`),
43
+ * else `HEAD` when the repository has no remote. A promote run from a
44
+ * branch with an edited pipeline is still judged by the merged one.
45
+ */
46
+ export function promoteBase(cwd) {
47
+ for (const ref of ["refs/remotes/origin/HEAD", "refs/remotes/origin/main", "refs/remotes/origin/master", "HEAD"]) {
48
+ try {
49
+ const sha = execFileSync("git", ["rev-parse", "--verify", "-q", `${ref}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
50
+ if (sha)
51
+ return sha;
52
+ }
53
+ catch {
54
+ // Try the next.
55
+ }
56
+ }
57
+ return undefined;
58
+ }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * A spec a wave job renders at run time (`renderSpec`, #4982), checked
3
+ * against the fold's schema (#5324).
4
+ *
5
+ * A product that has not moved to `.chant/pipeline.ts` keeps printing its
6
+ * spec from its config. The job reads that output with the schema a folded
7
+ * pipeline's stage has: an op-waves spec is checked as each stage's derived
8
+ * spec is (`assertOpWavesSpec`, with a wave's `failureTolerance`), and a
9
+ * folded pipeline document (`kind: "chant.pipeline/v1"`) is checked with
10
+ * `pipelineSpecProblems` and runs the stage `CHANT_PIPELINE_STAGE` names,
11
+ * or its first. Either way a spec the fold could not have produced fails
12
+ * the job before anything is planned.
13
+ */
14
+ import { type OpWavesSpec } from "../op/op-waves.js";
15
+ /** The job variable naming the stage a rendered pipeline document runs. */
16
+ export declare const PIPELINE_STAGE_ENV = "CHANT_PIPELINE_STAGE";
17
+ /**
18
+ * Check a rendered spec's text and hand back the op-waves spec's text the
19
+ * job runs. A pipeline document becomes its stage's spec; an op-waves spec
20
+ * is checked and passed on as printed. `parse` reads an op-waves spec's
21
+ * text (`parseOpWavesSpec`). Throws on a spec the fold could not produce.
22
+ */
23
+ export declare function checkRenderedWavesSpec(text: string, where: string, parse: (text: string, where: string) => OpWavesSpec, env?: NodeJS.ProcessEnv): string;
24
+ /** A render (`OpWavesSpecRender`) whose every output goes through {@link checkRenderedWavesSpec}. */
25
+ export declare function checkedRender(render: (sha: string) => string | null, parse: (text: string, where: string) => OpWavesSpec, env?: NodeJS.ProcessEnv): (sha: string) => string | null;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * A spec a wave job renders at run time (`renderSpec`, #4982), checked
3
+ * against the fold's schema (#5324).
4
+ *
5
+ * A product that has not moved to `.chant/pipeline.ts` keeps printing its
6
+ * spec from its config. The job reads that output with the schema a folded
7
+ * pipeline's stage has: an op-waves spec is checked as each stage's derived
8
+ * spec is (`assertOpWavesSpec`, with a wave's `failureTolerance`), and a
9
+ * folded pipeline document (`kind: "chant.pipeline/v1"`) is checked with
10
+ * `pipelineSpecProblems` and runs the stage `CHANT_PIPELINE_STAGE` names,
11
+ * or its first. Either way a spec the fold could not have produced fails
12
+ * the job before anything is planned.
13
+ */
14
+ import { assertOpWavesSpec } from "../op/op-waves.js";
15
+ import { asPipelineSpec, isPipelineSpecDocument } from "./spec.js";
16
+ import { stageWavesSpec } from "./stages.js";
17
+ /** The job variable naming the stage a rendered pipeline document runs. */
18
+ export const PIPELINE_STAGE_ENV = "CHANT_PIPELINE_STAGE";
19
+ /**
20
+ * Check a rendered spec's text and hand back the op-waves spec's text the
21
+ * job runs. A pipeline document becomes its stage's spec; an op-waves spec
22
+ * is checked and passed on as printed. `parse` reads an op-waves spec's
23
+ * text (`parseOpWavesSpec`). Throws on a spec the fold could not produce.
24
+ */
25
+ export function checkRenderedWavesSpec(text, where, parse, env = process.env) {
26
+ let doc;
27
+ try {
28
+ doc = JSON.parse(text);
29
+ }
30
+ catch {
31
+ parse(text, where);
32
+ return text;
33
+ }
34
+ if (isPipelineSpecDocument(doc)) {
35
+ const spec = asPipelineSpec(doc, where);
36
+ return `${JSON.stringify(stageWavesSpec(spec, env[PIPELINE_STAGE_ENV] || spec.stages[0].name), null, 2)}\n`;
37
+ }
38
+ const spec = parse(text, where);
39
+ try {
40
+ assertOpWavesSpec(spec);
41
+ }
42
+ catch (err) {
43
+ throw new Error(`${where} does not check against the pipeline's schema: ${err instanceof Error ? err.message : String(err)}`);
44
+ }
45
+ return text;
46
+ }
47
+ /** A render (`OpWavesSpecRender`) whose every output goes through {@link checkRenderedWavesSpec}. */
48
+ export function checkedRender(render, parse, env = process.env) {
49
+ return (sha) => {
50
+ const text = render(sha);
51
+ return text === null ? null : checkRenderedWavesSpec(text, `the spec rendered at ${sha.slice(0, 12)}`, parse, env);
52
+ };
53
+ }
@@ -0,0 +1,80 @@
1
+ /**
2
+ * The soak's check readers (#5326): what each check kind reads, from
3
+ * sources a caller hands in, so a test touches no network, no forge and no
4
+ * ledger.
5
+ *
6
+ * - `http`: the URL's status, and its body against a regular expression.
7
+ * - `prometheus`: an instant query's samples against `min` and `max`.
8
+ * - `cloudwatch-alarm`: the alarm's state, through `aws cloudwatch
9
+ * describe-alarms`; only `OK` passes.
10
+ * - `command`: the command's exit code; only 0 passes.
11
+ * - `health`: `chant lifecycle health <env> --json`; every resource in scope
12
+ * must be healthy, and unknown, unread and undeployed resources fail.
13
+ * - `drift`: the environment's open drift issue (`./drift-issue.ts`'s, one
14
+ * per environment) names none of the member's targets in a code span.
15
+ * - `apply`: the newest apply of each target did not fail.
16
+ * - `policy`: no target's newest policy denial is at or after the clock start.
17
+ *
18
+ * A source a caller does not give reads `unknown`, which holds.
19
+ */
20
+ import type { OpRunRecord } from "../op/runtime.js";
21
+ import { type SoakCheckReader, type SoakCheckResult } from "./soak.js";
22
+ /** An apply's outcome for one target. */
23
+ export type SoakApplyState = "success" | "failure" | "pending";
24
+ /** A policy denial of one target, as the ledger recorded it. */
25
+ export interface SoakDenial {
26
+ target: string;
27
+ /** When it was recorded, ISO 8601. */
28
+ at: string;
29
+ rules: string[];
30
+ }
31
+ /** What a command run gave. */
32
+ export interface SoakExecResult {
33
+ status: number | null;
34
+ stdout: string;
35
+ stderr: string;
36
+ error?: string;
37
+ }
38
+ /** Where the readers read from. Each one is optional; a check whose source is missing reads `unknown`. */
39
+ export interface SoakSources {
40
+ fetch?: (url: string, init: {
41
+ signal?: AbortSignal;
42
+ headers?: Record<string, string>;
43
+ }) => Promise<{
44
+ status: number;
45
+ text(): Promise<string>;
46
+ }>;
47
+ exec?: (argv: readonly string[], options: {
48
+ timeoutMs: number;
49
+ }) => SoakExecResult | Promise<SoakExecResult>;
50
+ /** The body of the environment's open drift issue for `member`, null when none is open. */
51
+ driftIssue?: (environment: string, member: string | undefined) => Promise<{
52
+ body: string;
53
+ url?: string;
54
+ } | null>;
55
+ /** The newest apply of each of `targets`; a target left out has none on record. */
56
+ applies?: (environment: string, member: string | undefined, targets: readonly string[]) => Promise<Record<string, SoakApplyState>>;
57
+ /** The policy denials of `targets`, in any order. */
58
+ denials?: (environment: string, member: string | undefined, targets: readonly string[]) => Promise<SoakDenial[]>;
59
+ /** The argv that prints `chant lifecycle health <env> --json`. Default `["chant", "lifecycle", "health", env, "--json"]`. */
60
+ healthCommand?: (environment: string) => string[];
61
+ }
62
+ /** The targets a drift issue's body names: those written in a code span, whole. */
63
+ export declare function driftNamedTargets(body: string, targets: readonly string[]): string[];
64
+ /** A {@link SoakCheckReader} over `sources`. */
65
+ export declare function soakCheckReader(sources: SoakSources): SoakCheckReader;
66
+ /**
67
+ * The verdict of a `chant lifecycle health --json` document (`chant-health/v1`)
68
+ * for a health check: every resource in scope healthy. `covers` scopes it to
69
+ * resources whose name or type a glob matches. Nothing in scope fails: a
70
+ * soak never passes on what nobody observed.
71
+ */
72
+ export declare function healthVerdict(doc: unknown, covers?: readonly string[]): SoakCheckResult;
73
+ /**
74
+ * The apply and policy sources read from op wave run records (#4551, #4614):
75
+ * a target's newest record that applied or failed it, and the denials its
76
+ * planned runs' policy rows carry, at the record's end.
77
+ */
78
+ export declare function runRecordSoakSources(records: readonly OpRunRecord[]): Pick<SoakSources, "applies" | "denials">;
79
+ /** `exec` through `spawnSync`, for a job. */
80
+ export declare function spawnSoakExec(cwd?: string): NonNullable<SoakSources["exec"]>;
@@ -0,0 +1,254 @@
1
+ /**
2
+ * The soak's check readers (#5326): what each check kind reads, from
3
+ * sources a caller hands in, so a test touches no network, no forge and no
4
+ * ledger.
5
+ *
6
+ * - `http`: the URL's status, and its body against a regular expression.
7
+ * - `prometheus`: an instant query's samples against `min` and `max`.
8
+ * - `cloudwatch-alarm`: the alarm's state, through `aws cloudwatch
9
+ * describe-alarms`; only `OK` passes.
10
+ * - `command`: the command's exit code; only 0 passes.
11
+ * - `health`: `chant lifecycle health <env> --json`; every resource in scope
12
+ * must be healthy, and unknown, unread and undeployed resources fail.
13
+ * - `drift`: the environment's open drift issue (`./drift-issue.ts`'s, one
14
+ * per environment) names none of the member's targets in a code span.
15
+ * - `apply`: the newest apply of each target did not fail.
16
+ * - `policy`: no target's newest policy denial is at or after the clock start.
17
+ *
18
+ * A source a caller does not give reads `unknown`, which holds.
19
+ */
20
+ import { spawnSync } from "node:child_process";
21
+ import { soakGlobMatch } from "./soak.js";
22
+ /** The targets a drift issue's body names: those written in a code span, whole. */
23
+ export function driftNamedTargets(body, targets) {
24
+ return targets.filter((t) => body.includes(`\`${t}\``));
25
+ }
26
+ const unknown = (detail) => ({ status: "unknown", detail });
27
+ /** A {@link SoakCheckReader} over `sources`. */
28
+ export function soakCheckReader(sources) {
29
+ return async (check, ctx) => {
30
+ try {
31
+ return await readCheck(sources, check, ctx);
32
+ }
33
+ catch (err) {
34
+ return unknown(`the check could not be read: ${err instanceof Error ? err.message : String(err)}`);
35
+ }
36
+ };
37
+ }
38
+ async function withTimeout(seconds, run) {
39
+ const controller = new AbortController();
40
+ const timer = setTimeout(() => controller.abort(), (seconds ?? 10) * 1000);
41
+ try {
42
+ return await run(controller.signal);
43
+ }
44
+ finally {
45
+ clearTimeout(timer);
46
+ }
47
+ }
48
+ async function readCheck(sources, check, ctx) {
49
+ switch (check.kind) {
50
+ case "http": {
51
+ if (!sources.fetch)
52
+ return unknown("no HTTP client was given");
53
+ const res = await withTimeout(check.timeoutSeconds, (signal) => sources.fetch(check.url, { signal }));
54
+ const want = check.status === undefined ? [200] : Array.isArray(check.status) ? check.status : [check.status];
55
+ if (!want.includes(res.status))
56
+ return { status: "failed", detail: `${check.url} answered ${res.status}, not ${want.join(" or ")}` };
57
+ if (check.body !== undefined) {
58
+ const text = await res.text();
59
+ if (!new RegExp(check.body).test(text))
60
+ return { status: "failed", detail: `${check.url}'s body does not match /${check.body}/` };
61
+ }
62
+ return { status: "passed", detail: `${check.url} answered ${res.status}` };
63
+ }
64
+ case "prometheus": {
65
+ if (!sources.fetch)
66
+ return unknown("no HTTP client was given");
67
+ const url = `${check.url.replace(/\/+$/, "")}/api/v1/query?query=${encodeURIComponent(check.query)}`;
68
+ const res = await withTimeout(check.timeoutSeconds, (signal) => sources.fetch(url, { signal, headers: { accept: "application/json" } }));
69
+ if (res.status !== 200)
70
+ return unknown(`Prometheus answered ${res.status}`);
71
+ const doc = JSON.parse(await res.text());
72
+ if (doc.status !== "success")
73
+ return unknown("Prometheus did not answer the query");
74
+ const values = samplesOf(doc.data?.resultType, doc.data?.result);
75
+ if (values.length === 0)
76
+ return unknown(`the query ${check.query} returned no sample`);
77
+ const bad = values.filter((v) => Number.isNaN(v) || (check.max !== undefined && v > check.max) || (check.min !== undefined && v < check.min));
78
+ if (bad.length > 0)
79
+ return { status: "failed", detail: `the query ${check.query} returned ${bad.join(", ")}, outside ${bounds(check.min, check.max)}` };
80
+ return { status: "passed", detail: `the query ${check.query} stays within ${bounds(check.min, check.max)}` };
81
+ }
82
+ case "cloudwatch-alarm": {
83
+ if (!sources.exec)
84
+ return unknown("no command runner was given");
85
+ const argv = ["aws", "cloudwatch", "describe-alarms", "--alarm-names", check.alarm, "--output", "json", ...(check.region ? ["--region", check.region] : [])];
86
+ const r = await sources.exec(argv, { timeoutMs: 30000 });
87
+ if (r.status !== 0)
88
+ return unknown(`aws cloudwatch describe-alarms failed: ${oneLine(r.error ?? r.stderr) || `exit ${r.status}`}`);
89
+ const doc = JSON.parse(r.stdout);
90
+ const state = [...(doc.MetricAlarms ?? []), ...(doc.CompositeAlarms ?? [])][0]?.StateValue;
91
+ if (state === undefined)
92
+ return unknown(`no alarm named ${check.alarm} was found`);
93
+ if (state === "OK")
94
+ return { status: "passed", detail: `the alarm ${check.alarm} is OK` };
95
+ return state === "ALARM" ? { status: "failed", detail: `the alarm ${check.alarm} is in ALARM` } : unknown(`the alarm ${check.alarm} is ${state}`);
96
+ }
97
+ case "command": {
98
+ if (!sources.exec)
99
+ return unknown("no command runner was given");
100
+ const r = await sources.exec(check.command, { timeoutMs: (check.timeoutSeconds ?? 300) * 1000 });
101
+ if (r.status === 0)
102
+ return { status: "passed", detail: `${check.command.join(" ")} exited 0` };
103
+ if (r.status === null)
104
+ return unknown(`${check.command.join(" ")} did not finish: ${oneLine(r.error ?? r.stderr)}`);
105
+ return { status: "failed", detail: `${check.command.join(" ")} exited ${r.status}${r.stderr.trim() ? `: ${oneLine(r.stderr)}` : ""}` };
106
+ }
107
+ case "health": {
108
+ if (!sources.exec)
109
+ return unknown("no command runner was given");
110
+ const argv = sources.healthCommand?.(ctx.environment) ?? ["chant", "lifecycle", "health", ctx.environment, "--json"];
111
+ const r = await sources.exec(argv, { timeoutMs: 600000 });
112
+ if (r.status !== 0)
113
+ return unknown(`lifecycle health ${ctx.environment} failed: ${oneLine(r.stderr) || `exit ${r.status}`}`);
114
+ return healthVerdict(JSON.parse(r.stdout), check.covers);
115
+ }
116
+ case "drift": {
117
+ if (!sources.driftIssue)
118
+ return unknown("no drift issue reader was given");
119
+ const issue = await sources.driftIssue(ctx.environment, ctx.member);
120
+ const named = issue ? driftNamedTargets(issue.body, ctx.targets) : [];
121
+ if (named.length === 0)
122
+ return { status: "passed", detail: issue ? "the open drift issue names none of the targets" : "no drift issue is open" };
123
+ return { status: "failed", targets: named, detail: `the drift issue${issue.url ? ` ${issue.url}` : ""} is open and names ${named.join(", ")}` };
124
+ }
125
+ case "apply": {
126
+ if (!sources.applies)
127
+ return unknown("no apply reader was given");
128
+ const states = await sources.applies(ctx.environment, ctx.member, ctx.targets);
129
+ const failed = ctx.targets.filter((t) => states[t] === "failure");
130
+ if (failed.length === 0)
131
+ return { status: "passed", detail: "no newest apply failed" };
132
+ return { status: "failed", targets: failed, detail: `the newest apply failed for ${failed.join(", ")}` };
133
+ }
134
+ case "policy": {
135
+ if (!sources.denials)
136
+ return unknown("no policy denial reader was given");
137
+ const since = Date.parse(ctx.since);
138
+ const newest = new Map();
139
+ for (const d of await sources.denials(ctx.environment, ctx.member, ctx.targets)) {
140
+ const had = newest.get(d.target);
141
+ if (!had || Date.parse(d.at) > Date.parse(had.at))
142
+ newest.set(d.target, d);
143
+ }
144
+ const denied = ctx.targets.map((t) => newest.get(t)).filter((d) => d !== undefined && Date.parse(d.at) >= since);
145
+ if (denied.length === 0)
146
+ return { status: "passed", detail: "policy denied none of the targets since the clock started" };
147
+ const rules = [...new Set(denied.flatMap((d) => d.rules))];
148
+ return { status: "failed", targets: denied.map((d) => d.target), detail: `policy denied ${denied.map((d) => d.target).join(", ")} since the clock started${rules.length > 0 ? ` (${rules.join(", ")})` : ""}` };
149
+ }
150
+ }
151
+ }
152
+ function bounds(min, max) {
153
+ if (min !== undefined && max !== undefined)
154
+ return `${min} to ${max}`;
155
+ return min !== undefined ? `${min} or more` : `${max} or less`;
156
+ }
157
+ function samplesOf(type, result) {
158
+ if (type === "scalar" && Array.isArray(result))
159
+ return [Number(result[1])];
160
+ if (type === "vector" && Array.isArray(result))
161
+ return result.map((s) => Number(s.value?.[1]));
162
+ return [];
163
+ }
164
+ function oneLine(text) {
165
+ return text.trim().split("\n").filter(Boolean).slice(-1)[0]?.slice(0, 300) ?? "";
166
+ }
167
+ /**
168
+ * The verdict of a `chant lifecycle health --json` document (`chant-health/v1`)
169
+ * for a health check: every resource in scope healthy. `covers` scopes it to
170
+ * resources whose name or type a glob matches. Nothing in scope fails: a
171
+ * soak never passes on what nobody observed.
172
+ */
173
+ export function healthVerdict(doc, covers) {
174
+ const d = doc;
175
+ if (d?.schema !== "chant-health/v1")
176
+ return unknown("lifecycle health printed no chant-health/v1 document");
177
+ const reads = d.lexicons ? Object.values(d.lexicons) : Object.values(d.stacks ?? {}).flatMap((s) => Object.values(s));
178
+ const inScope = (name, type) => !covers || covers.some((g) => soakGlobMatch(g, name) || (type !== undefined && soakGlobMatch(g, type)));
179
+ let seen = 0;
180
+ const bad = [];
181
+ for (const r of reads) {
182
+ for (const [name, e] of Object.entries(r.entities ?? {})) {
183
+ if (!inScope(name, e.type))
184
+ continue;
185
+ seen++;
186
+ if (e.state !== "healthy")
187
+ bad.push(`${name} is ${e.state ?? "unknown"}`);
188
+ }
189
+ for (const [name, h] of Object.entries(r.unobserved ?? {})) {
190
+ if (!inScope(name, h.type))
191
+ continue;
192
+ seen++;
193
+ bad.push(`${name} was not read (${h.reason ?? "unknown reason"})`);
194
+ }
195
+ for (const name of r.absent ?? []) {
196
+ if (!inScope(name, undefined))
197
+ continue;
198
+ seen++;
199
+ bad.push(`${name} is not deployed`);
200
+ }
201
+ }
202
+ if (seen === 0)
203
+ return unknown(covers ? `no resource matches ${covers.join(", ")}` : "no resource has a health read");
204
+ if (bad.length === 0)
205
+ return { status: "passed", detail: `${seen} resource${seen === 1 ? "" : "s"} healthy` };
206
+ const shown = bad.slice(0, 5).join("; ") + (bad.length > 5 ? `; and ${bad.length - 5} more` : "");
207
+ // Unhealthy or not deployed is a failure; a resource only unknown or unread is unknown. Both hold.
208
+ return { status: bad.some((b) => b.endsWith(" is unhealthy") || b.endsWith(" is not deployed")) ? "failed" : "unknown", detail: shown };
209
+ }
210
+ /**
211
+ * The apply and policy sources read from op wave run records (#4551, #4614):
212
+ * a target's newest record that applied or failed it, and the denials its
213
+ * planned runs' policy rows carry, at the record's end.
214
+ */
215
+ export function runRecordSoakSources(records) {
216
+ const sorted = [...records].sort((a, b) => Date.parse(a.ended) - Date.parse(b.ended));
217
+ return {
218
+ async applies(_env, _member, targets) {
219
+ const out = {};
220
+ for (const r of sorted) {
221
+ const w = r.wave;
222
+ if (!w)
223
+ continue;
224
+ for (const t of targets) {
225
+ if (w.failed.includes(t))
226
+ out[t] = "failure";
227
+ else if (w.applied.includes(t))
228
+ out[t] = "success";
229
+ }
230
+ }
231
+ return out;
232
+ },
233
+ async denials(_env, _member, targets) {
234
+ const out = [];
235
+ for (const r of sorted) {
236
+ for (const [t, plan] of Object.entries(r.wave?.plans ?? {})) {
237
+ if (!targets.includes(t))
238
+ continue;
239
+ const rows = (plan.policy ?? []).filter((p) => p.result === "denied");
240
+ if (rows.length > 0)
241
+ out.push({ target: t, at: r.ended, rules: [...new Set(rows.flatMap((p) => p.rules))].sort() });
242
+ }
243
+ }
244
+ return out;
245
+ },
246
+ };
247
+ }
248
+ /** `exec` through `spawnSync`, for a job. */
249
+ export function spawnSoakExec(cwd = process.cwd()) {
250
+ return (argv, { timeoutMs }) => {
251
+ const r = spawnSync(argv[0], argv.slice(1), { cwd, encoding: "utf-8", timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
252
+ return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", ...(r.error ? { error: r.error.message } : {}) };
253
+ };
254
+ }
@@ -0,0 +1,97 @@
1
+ /**
2
+ * The soak at a gate (#5326): what a promote into the next stage, and the
3
+ * next wave's job, run before their own gate.
4
+ *
5
+ * The soak has a gate of its own on the gate ledger: `<stage>-soak` under
6
+ * the pipeline's op for a stage, `<gate>-wave-<k>-soak` under the spec's op
7
+ * for wave `k`. Its approval is how a person ends the soak early, bound to
8
+ * the release's digest (or the wave's). A product maps its own comment,
9
+ * such as `/terragucci skip-soak`, onto that approval. The approval names
10
+ * who, and the promote records it as spent on `_gates/<op>/applied.jsonl`.
11
+ *
12
+ * A soak that holds records the gate's pending fact with the soak's state
13
+ * on it (`soak`: the clock, the time left, the holds, the checks that
14
+ * failed), and the run exits 3. The next run reads that state back: a
15
+ * `restart` check that failed and now passes starts the clock over.
16
+ *
17
+ * Ending a soak early, or a soak passing, opens nothing by itself: the next
18
+ * stage's gate, or the next wave's, still waits for its approval. A soak
19
+ * only ever adds a wait.
20
+ *
21
+ * A check that starts failing also records a `verify-failed` fact for the
22
+ * agent (#5339, `../ci-agent-verify-failed.ts`), when the job's
23
+ * `CHANT_AGENT_FACTS` names `verify-failed` and it holds the relay key. The
24
+ * fact is read from the same change the notice is sent for, and the soak's
25
+ * outcome is the same with or without it.
26
+ */
27
+ import { type GateLedgerPort } from "../op/gate.js";
28
+ import type { GateQuorumNode } from "../op/gate-quorum.js";
29
+ import type { PendingGateRecord } from "../lifecycle/gate-ledger.js";
30
+ import { type NotifyConfig, type NotifyEvent } from "../notify.js";
31
+ import { type Soak, type SoakCheckReader, type SoakDecision, type SoakSubject } from "./soak.js";
32
+ /** How long a soak's pending fact stands before a run records it again. Longer than any soak a stage declares in practice. */
33
+ export declare const SOAK_FACT_EXPIRY = "30d";
34
+ /** The gate a stage's soak is ended early through. */
35
+ export declare function stageSoakGate(stage: string): string;
36
+ /** The gate wave `k`'s soak is ended early through, from the wave's own gate name. */
37
+ export declare function waveSoakGate(waveGate: string): string;
38
+ export interface SoakGateInput {
39
+ /** The op the soak's gate is recorded under: the pipeline's name, or the op-waves spec's op. */
40
+ op: string;
41
+ /** The soak's gate: {@link stageSoakGate} or {@link waveSoakGate}. */
42
+ gate: string;
43
+ soak: Soak | undefined;
44
+ /** The environment that soaks: the stage's name, or the wave's environment. */
45
+ stage: string;
46
+ /** What the soak holds, as the output names it: `stage staging`, `wave 3 (prod)`. */
47
+ holds: string;
48
+ /** On a stage's soak: the stage promoted into. On a wave's: the wave that soaks. */
49
+ to?: string;
50
+ wave?: number;
51
+ /** The digest an early end binds: the release's, or the promoted digests', or the wave's. */
52
+ digest: string;
53
+ releaseDigest?: string;
54
+ /** The members that applied, with when. */
55
+ subjects: readonly SoakSubject[];
56
+ /** The approval rules an early end takes. Absent: one approval. */
57
+ quorum?: GateQuorumNode[];
58
+ port: GateLedgerPort;
59
+ read: SoakCheckReader;
60
+ now: Date;
61
+ gitSha?: string;
62
+ /** Where a failed check's notice goes. Absent: none is sent. */
63
+ notify?: {
64
+ config: NotifyConfig | undefined;
65
+ source: string;
66
+ project?: string;
67
+ send?: (config: NotifyConfig | undefined, event: NotifyEvent) => Promise<unknown>;
68
+ };
69
+ /**
70
+ * Where a failing check's `verify-failed` fact is recorded (#5339): the
71
+ * job's variables (default the process's), the checkout, and where the
72
+ * line it logs goes (default stderr). Without `CHANT_AGENT_FACTS` naming
73
+ * `verify-failed`, nothing is recorded.
74
+ */
75
+ agentFacts?: {
76
+ env?: Record<string, string | undefined>;
77
+ cwd?: string;
78
+ say?: (line: string) => void;
79
+ };
80
+ }
81
+ /** What {@link soakAtGate} decided: passed, with what it says, or held with exit 3. */
82
+ export type SoakGateOutcome = {
83
+ passed: true;
84
+ lines: string[];
85
+ decision: SoakDecision;
86
+ } | {
87
+ passed: false;
88
+ exitCode: 3;
89
+ code: "pipeline-soak-waiting";
90
+ message: string;
91
+ hint: string;
92
+ lines: string[];
93
+ decision: SoakDecision;
94
+ recorded?: PendingGateRecord;
95
+ };
96
+ /** Decide the soak in front of a gate, read and record its fact, and notify a failed check. See the module comment. */
97
+ export declare function soakAtGate(input: SoakGateInput): Promise<SoakGateOutcome>;