@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
@@ -47,6 +47,7 @@
47
47
  * A `wave` that throws follows the hook's `onFailure`, as `run` does.
48
48
  */
49
49
  import type { ChangeSetPart } from "../change-set.js";
50
+ import type { ChangeRisk } from "../change-risk.js";
50
51
  import type { OpRunPolicyRow } from "./runtime.js";
51
52
  import type { WaveMember } from "../wave-engine.js";
52
53
  import { type OpWaveHookFailure } from "./op-waves.js";
@@ -82,6 +83,17 @@ export interface OpWaveAnswerApproval {
82
83
  reviewers: string[];
83
84
  };
84
85
  }
86
+ /**
87
+ * The first chant whose after-plan hooks get the wave's change risk (#5422):
88
+ * `risk` on `OpWaveAfterPlanRun` and `OpWaveAfterPlanWave`, the record
89
+ * `input.risk` has in `holds.policy`, present when the wave's `holds.risk`
90
+ * scored it. A product feature-detects it on this name.
91
+ *
92
+ * The record is read-only context. A hook's answer has no field that changes
93
+ * it, and it keeps #5325's rules on this path: it adds approval requirements
94
+ * and never lets a plan apply without an approval.
95
+ */
96
+ export declare const OP_WAVE_AFTER_PLAN_RISK_FLOOR = "0.124.110";
85
97
  /** One planned run, as an after-plan hook in the job's process sees it (#4614). */
86
98
  export interface OpWaveAfterPlanRun {
87
99
  /** The spec's name and `op`. */
@@ -108,6 +120,15 @@ export interface OpWaveAfterPlanRun {
108
120
  destructive: boolean;
109
121
  /** The rows chant's `holds.policy` gave the run (source `ci.policy`), empty when no policy ran. */
110
122
  policy: OpRunPolicyRow[];
123
+ /**
124
+ * The wave's change risk (#5422), as `input.risk` gives it to `holds.policy`
125
+ * (#5325): the score, its level, each reason with its weight, and whether a
126
+ * threshold is crossed. Present when the wave's `holds.risk` scored it, the
127
+ * same record for every run of the wave. A product puts it on its plan
128
+ * report's `risk`, which the plan note's risk table reads. A copy: changing
129
+ * it changes nothing in the wave.
130
+ */
131
+ risk?: ChangeRisk;
111
132
  /** The job's directory. */
112
133
  cwd: string;
113
134
  }
@@ -129,6 +150,8 @@ export interface OpWaveAfterPlanWave {
129
150
  job: OpWaveAfterPlanRun["job"];
130
151
  /** The runs the hook is for, in the wave's order, as its `run` saw each. */
131
152
  runs: OpWaveAfterPlanRun[];
153
+ /** The wave's change risk (#5422), as on each of its runs: for the wave's own report. A copy. */
154
+ risk?: ChangeRisk;
132
155
  cwd: string;
133
156
  }
134
157
  /** What a hook adds to the wave as a whole (#4842). */
@@ -53,6 +53,17 @@ import { OP_WAVE_PENDING_RESERVED } from "./stage-hooks.js";
53
53
  export const OP_WAVE_AFTER_PLAN_WAVE_FLOOR = "0.124.79";
54
54
  /** The first chant whose wave answer takes `approvals`, recorded at the wave's gate before chant decides it (terragucci issue 1303). */
55
55
  export const OP_WAVE_ANSWER_APPROVALS_FLOOR = "0.124.80";
56
+ /**
57
+ * The first chant whose after-plan hooks get the wave's change risk (#5422):
58
+ * `risk` on `OpWaveAfterPlanRun` and `OpWaveAfterPlanWave`, the record
59
+ * `input.risk` has in `holds.policy`, present when the wave's `holds.risk`
60
+ * scored it. A product feature-detects it on this name.
61
+ *
62
+ * The record is read-only context. A hook's answer has no field that changes
63
+ * it, and it keeps #5325's rules on this path: it adds approval requirements
64
+ * and never lets a plan apply without an approval.
65
+ */
66
+ export const OP_WAVE_AFTER_PLAN_RISK_FLOOR = "0.124.110";
56
67
  const ROW_RESULTS = ["passed", "warned", "denied", "held"];
57
68
  /** What is wrong with `afterPlan`, empty when nothing is. */
58
69
  export function opWaveAfterPlanProblems(hooks) {
@@ -257,7 +268,7 @@ export async function runOpWaveAfterPlanHooks(hooks, runs, log) {
257
268
  let problem;
258
269
  let answer = undefined;
259
270
  try {
260
- answer = await hook.wave({ spec: first.spec, op: first.op, wave: first.wave, waveName: first.waveName, job: first.job, runs: [...mine], cwd: first.cwd });
271
+ answer = await hook.wave({ spec: first.spec, op: first.op, wave: first.wave, waveName: first.waveName, job: first.job, runs: [...mine], ...(first.risk ? { risk: structuredClone(first.risk) } : {}), cwd: first.cwd });
261
272
  const wrong = opWaveAfterPlanWaveResultProblems(answer, targets);
262
273
  if (wrong.length > 0)
263
274
  problem = `${label} answered with ${wrong.join("; ")}`;
@@ -7,6 +7,7 @@
7
7
  * `./op-waves-capability.ts` loads. See that file for the step and the holds.
8
8
  */
9
9
  import type { OpWavesSpec } from "./op-waves.js";
10
+ import type { ChangeRiskSettings } from "../change-risk.js";
10
11
  /** A capability step a wave plans and applies each run through (#4545): `{ kind, ...input }`. */
11
12
  export interface OpWaveStep {
12
13
  /** The capability's kind, such as `terraform-apply` or `pulumi-up`. */
@@ -32,6 +33,12 @@ export interface OpWaveCostHold {
32
33
  format?: OpWaveCostFormat;
33
34
  /** The currency `approveAbove` is in, for the log and the digest. Default the estimate's, else `USD`. */
34
35
  currency?: string;
36
+ /**
37
+ * Names of environment variables whose values are secret and that the plan does not mark sensitive, such as the secrets a product's store holds. A job gets each value through its environment set's `secrets` (#5348) or a variable it reads, so the spec carries the name only. The estimate runs when the variable is set: its value is replaced by `[redacted]` in the plan copy, and the variable is left out of the command's environment.
38
+ */
39
+ redactEnv?: string[];
40
+ /** Names of environment variables to leave out of the command's environment, beside the forge tokens, such as a product's own token variables. A value they hold is replaced by `[redacted]` in the plan copy too. */
41
+ dropEnv?: string[];
35
42
  }
36
43
  /** Holds a wave runs over its plans (#4545), read at base. */
37
44
  export interface OpWaveHolds {
@@ -39,6 +46,13 @@ export interface OpWaveHolds {
39
46
  policy?: boolean;
40
47
  /** Price each run and hold the wave over a monthly change. */
41
48
  cost?: OpWaveCostHold;
49
+ /**
50
+ * Score the wave's change set (#5325, `../change-risk.ts`): each run's
51
+ * policy reads the record as `input.risk`, the decision records it, and
52
+ * over `approveAbove` the wave waits whatever its gate says and takes
53
+ * `quorum`'s rules on top of its own. It only ever adds approvals.
54
+ */
55
+ risk?: Omit<ChangeRiskSettings, "questions">;
42
56
  }
43
57
  /** The digest member a cost hold adds (#4545): no run has this name. */
44
58
  export declare const OP_WAVE_COST_MEMBER = "(monthly cost)";
@@ -67,7 +67,7 @@ export function opWaveHoldsProblems(holds) {
67
67
  if (holds === undefined)
68
68
  return [];
69
69
  if (holds === null || typeof holds !== "object" || Array.isArray(holds))
70
- return ["`holds` must be { \"policy\"?: true, \"cost\"?: {...} }"];
70
+ return ["`holds` must be { \"policy\"?: true, \"cost\"?: {...}, \"risk\"?: {...} }"];
71
71
  const problems = [];
72
72
  for (const [key, value] of Object.entries(holds)) {
73
73
  if (key === "policy") {
@@ -77,14 +77,46 @@ export function opWaveHoldsProblems(holds) {
77
77
  else if (key === "cost") {
78
78
  problems.push(...costHoldProblems(value));
79
79
  }
80
+ else if (key === "risk") {
81
+ problems.push(...riskHoldProblems(value));
82
+ }
83
+ else
84
+ problems.push(`\`holds.${key}\` is not a setting; the ones there are holds.policy, holds.cost and holds.risk`);
85
+ }
86
+ return problems;
87
+ }
88
+ /**
89
+ * What is wrong with `holds.risk` (#5325). Kept here rather than read from
90
+ * `../change-risk.ts`, so the spec module stays free of run-time imports;
91
+ * `change-risk.test.ts` checks the two agree.
92
+ */
93
+ function riskHoldProblems(value) {
94
+ if (value === null || typeof value !== "object" || Array.isArray(value))
95
+ return ["`holds.risk` must be { \"approveAbove\"?: <0 to 1>, \"quorum\"?: [...] }"];
96
+ const r = value;
97
+ const problems = [];
98
+ const unit = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
99
+ for (const key of Object.keys(r)) {
100
+ if (key === "approveAbove") {
101
+ if (!unit(r.approveAbove))
102
+ problems.push("`holds.risk.approveAbove` must be a score from 0 to 1");
103
+ }
104
+ else if (key === "quorum") {
105
+ if (!Array.isArray(r.quorum) || r.quorum.length === 0 || r.quorum.some((q) => q === null || typeof q !== "object" || !Number.isInteger(q.count) || (q.count < 1))) {
106
+ problems.push("`holds.risk.quorum` must be a non-empty list of approval rules, each { \"count\", \"roles\"?, \"notAuthor\"?, \"proven\"? }");
107
+ }
108
+ }
109
+ else if (key === "questions") {
110
+ problems.push("`holds.risk.questions` is answered by the pull request's review, so it is set in `ci.risk.questions`");
111
+ }
80
112
  else
81
- problems.push(`\`holds.${key}\` is not a setting; the ones there are holds.policy and holds.cost`);
113
+ problems.push(`\`holds.risk.${key}\` is refused: a risk score only adds approvals, and its settings are approveAbove and quorum`);
82
114
  }
83
115
  return problems;
84
116
  }
85
117
  function costHoldProblems(value) {
86
118
  if (value === null || typeof value !== "object" || Array.isArray(value))
87
- return ["`holds.cost` must be { \"command\": [...], \"approveAbove\": <number>, \"format\"?, \"currency\"? }"];
119
+ return ["`holds.cost` must be { \"command\": [...], \"approveAbove\": <number>, \"format\"?, \"currency\"?, \"redactEnv\"?, \"dropEnv\"? }"];
88
120
  const c = value;
89
121
  const problems = [];
90
122
  if (!Array.isArray(c.command) || c.command.length === 0 || !c.command.every((a) => typeof a === "string" && a !== ""))
@@ -95,8 +127,14 @@ function costHoldProblems(value) {
95
127
  problems.push(`\`holds.cost.format\` must be ${OP_WAVE_COST_FORMATS.join(" or ")}`);
96
128
  if (c.currency !== undefined && (typeof c.currency !== "string" || !/^[A-Z]{3}$/.test(c.currency)))
97
129
  problems.push("`holds.cost.currency` must be a three-letter currency code, such as \"USD\"");
130
+ for (const key of ["redactEnv", "dropEnv"]) {
131
+ const names = c[key];
132
+ if (names !== undefined && (!Array.isArray(names) || !names.every((n) => typeof n === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)))) {
133
+ problems.push(`\`holds.cost.${key}\` must be a list of environment variable names, never their values`);
134
+ }
135
+ }
98
136
  for (const key of Object.keys(c))
99
- if (!["command", "approveAbove", "format", "currency"].includes(key))
137
+ if (!["command", "approveAbove", "format", "currency", "redactEnv", "dropEnv"].includes(key))
100
138
  problems.push(`\`holds.cost.${key}\` is not a setting`);
101
139
  return problems;
102
140
  }
@@ -108,7 +146,9 @@ function costHoldProblems(value) {
108
146
  export function opWaveHoldsAt(atBase, change) {
109
147
  const policy = atBase?.policy === true || change?.policy === true;
110
148
  const cost = atBase !== undefined ? atBase.cost : change?.cost;
111
- if (!policy && !cost)
149
+ // #5325: the risk at base, else the change's; it only ever adds approvals.
150
+ const risk = atBase !== undefined ? atBase.risk : change?.risk;
151
+ if (!policy && !cost && !risk)
112
152
  return undefined;
113
- return { ...(policy ? { policy: true } : {}), ...(cost ? { cost } : {}) };
153
+ return { ...(policy ? { policy: true } : {}), ...(cost ? { cost } : {}), ...(risk ? { risk } : {}) };
114
154
  }
@@ -77,6 +77,8 @@ import type { ResolvedGatePolicySource } from "../policy-source.js";
77
77
  import type { WaveMember } from "../wave-engine.js";
78
78
  import type { OpWave, OpWaveRun, OpWavesSpec } from "./op-waves.js";
79
79
  import { type LockGrain, type PlannedLock } from "../lifecycle/lock-rows.js";
80
+ import { type CostEstimate, type CostFigures } from "../cost-estimate.js";
81
+ import type { ChangeRisk } from "../change-risk.js";
80
82
  import { type OpWaveCostFormat, type OpWaveCostHold } from "./op-waves-capability-spec.js";
81
83
  export { OP_WAVE_COST_FORMATS, OP_WAVE_COST_MEMBER, opWaveHoldsAt, opWaveHoldsProblems, opWaveStepProblems } from "./op-waves-capability-spec.js";
82
84
  export type { OpWaveCostFormat, OpWaveCostHold, OpWaveHolds, OpWaveStep } from "./op-waves-capability-spec.js";
@@ -104,6 +106,8 @@ export interface OpWaveStepPlan {
104
106
  part?: ChangeSetPart;
105
107
  empty: boolean;
106
108
  destructive: boolean;
109
+ /** The engine's own destructive classes (`CapabilityPlan.destructive`), which the change risk counts (#5325). */
110
+ destructiveClasses?: string[];
107
111
  /** The run's lock grain and rows (#4552), which the apply leases on the resource grain. */
108
112
  lock?: PlannedLock;
109
113
  /** Set when the wave planned `together` (#4842): the one plan every run of it shares. */
@@ -243,6 +247,9 @@ export interface OpWaveRunVerdict {
243
247
  }
244
248
  /**
245
249
  * Run the workspace's `ci.policy` at `base` over each run's part (#4545).
250
+ * With a cost hold, each run's policy reads the wave's estimate and the
251
+ * run's own as `input.cost` (#5334), and with a risk hold the wave's
252
+ * risk record as `input.risk` (#5325).
246
253
  * Returns each run's verdict, or a line saying why no policy runs (the base
247
254
  * names none). Throws when the policy at base cannot be read while the
248
255
  * checkout names one, as the pull-request path does.
@@ -255,35 +262,36 @@ export declare function opWavePolicyVerdicts(at: {
255
262
  head: string;
256
263
  cwd: string;
257
264
  exec?: GatePolicyExec;
258
- }, parts: ReadonlyMap<string, ChangeSetPart>): Promise<{
265
+ }, parts: ReadonlyMap<string, ChangeSetPart>, cost?: CostEstimate, risk?: ChangeRisk): Promise<{
259
266
  verdicts: Map<string, OpWaveRunVerdict>;
260
267
  source?: ResolvedGatePolicySource;
261
268
  } | {
262
269
  note: string;
263
270
  }>;
264
- /** One run's estimate: the monthly change, or why there is none. */
265
- export type OpWaveRunCost = {
271
+ /** One run's estimate: the monthly change, or why there is none. The totals come with it when the estimate gives them (#5334). */
272
+ export type OpWaveRunCost = ({
266
273
  target: string;
267
- monthlyDelta: number;
268
- currency?: string;
269
- } | {
274
+ } & CostFigures) | {
270
275
  target: string;
271
276
  error: string;
272
277
  };
273
- /** The monthly change an estimate gives, in `format`. Throws when it gives none. */
274
- export declare function readCostEstimate(format: OpWaveCostFormat, stdout: string): {
275
- monthlyDelta: number;
276
- currency?: string;
277
- };
278
+ /** The figures an estimate gives, in `format` (`../cost-estimate.ts`, #5334). Throws when it gives no monthly change. */
279
+ export declare const readCostEstimate: (format: OpWaveCostFormat, stdout: string) => CostFigures;
278
280
  /** The engine's plan document a capability's artifact names (`artifact.planJson`), when it names one that exists. */
279
- export declare function planJsonOf(artifact: unknown, cwd: string): string | undefined;
280
- /** Price each run that changes something (#4545). A run with no estimate says why. */
281
+ export declare const planJsonOf: (artifact: unknown, cwd: string) => string | undefined;
282
+ /**
283
+ * Price each run that changes something (#4545), with the pull request's estimator (`../cost-estimate.ts`, #5334). A run with no estimate says why.
284
+ * A run's `env` is the one its product's run hooks gave it (#5433): `redactEnv` and `dropEnv` read their values there as well as in the job's.
285
+ */
281
286
  export declare function opWaveCosts(hold: OpWaveCostHold, runs: ReadonlyArray<{
282
287
  target: string;
283
288
  plan: string;
284
289
  artifact?: unknown;
285
290
  empty: boolean;
291
+ env?: Record<string, string>;
286
292
  }>, cwd: string, exec?: GatePolicyExec): OpWaveRunCost[];
293
+ /** A wave's estimates as the record a policy reads as `input.cost` (#5334), against the hold's `approveAbove`. */
294
+ export declare function opWaveCostEstimate(hold: OpWaveCostHold, costs: readonly OpWaveRunCost[]): CostEstimate;
287
295
  /** What a wave's estimates come to: the sum, the digest member, and the hold line when it waits. */
288
296
  export interface OpWaveCostVerdict {
289
297
  monthlyDelta: number;
@@ -69,14 +69,14 @@
69
69
  * not apply at another. A run the estimator cannot price holds the wave
70
70
  * too. The terraform lexicon's preset is `terraformCostHold` (infracost).
71
71
  */
72
- import { spawnSync } from "node:child_process";
73
- import { existsSync, mkdirSync, writeFileSync } from "node:fs";
72
+ import { mkdirSync, writeFileSync } from "node:fs";
74
73
  import { dirname, join, resolve } from "node:path";
75
74
  import { isPlanMovedError } from "../components/capability.js";
76
75
  import { composeChangeSet } from "../change-set.js";
77
76
  import { computePlanDigest } from "../lifecycle/plan-digest.js";
78
77
  import { groupDigest } from "../components/group-digest.js";
79
78
  import { resolvePlannedLock } from "../lifecycle/lock-rows.js";
79
+ import { costEstimateOf, planJsonOf as planJsonPath, policyCost, priceRuns, readCostEstimate as readEstimate } from "../cost-estimate.js";
80
80
  import { OP_WAVE_COST_MEMBER } from "./op-waves-capability-spec.js";
81
81
  export { OP_WAVE_COST_FORMATS, OP_WAVE_COST_MEMBER, opWaveHoldsAt, opWaveHoldsProblems, opWaveStepProblems } from "./op-waves-capability-spec.js";
82
82
  /** Fill `{target}`, `{op}` and `{wave}` in every string of `value`. */
@@ -184,6 +184,7 @@ export async function planOpWaveStep(at, run) {
184
184
  ...(planned.artifact !== undefined ? { artifact: planned.artifact } : {}),
185
185
  ...(planned.changeSet ? { part: planned.changeSet } : {}),
186
186
  ...effects,
187
+ ...(planned.destructive?.length ? { destructiveClasses: [...planned.destructive] } : {}),
187
188
  lock,
188
189
  };
189
190
  writeStepPlanFile(join(cwd, at.planPath), plan);
@@ -318,6 +319,7 @@ export async function planOpWaveStepGroup(at, runs) {
318
319
  ...(p.artifact !== undefined ? { artifact: p.artifact } : {}),
319
320
  ...(p.changeSet ? { part: p.changeSet } : {}),
320
321
  ...effects,
322
+ ...(p.destructive?.length ? { destructiveClasses: [...p.destructive] } : {}),
321
323
  lock,
322
324
  group,
323
325
  };
@@ -433,18 +435,21 @@ export function opWaveStepChangeSet(plans) {
433
435
  }
434
436
  /**
435
437
  * Run the workspace's `ci.policy` at `base` over each run's part (#4545).
438
+ * With a cost hold, each run's policy reads the wave's estimate and the
439
+ * run's own as `input.cost` (#5334), and with a risk hold the wave's
440
+ * risk record as `input.risk` (#5325).
436
441
  * Returns each run's verdict, or a line saying why no policy runs (the base
437
442
  * names none). Throws when the policy at base cannot be read while the
438
443
  * checkout names one, as the pull-request path does.
439
444
  */
440
- export async function opWavePolicyVerdicts(at, parts) {
445
+ export async function opWavePolicyVerdicts(at, parts, cost, risk) {
441
446
  const { prLoopPolicyAt, preparePrPolicyEngine, runPrPolicy } = await import("../components/pr-policy.js");
442
447
  const read = await preparePrPolicyEngine(prLoopPolicyAt(at.cwd, at.base));
443
448
  if (!read.settings)
444
449
  return { note: read.note ?? `holds.policy: the declaration at ${at.base.slice(0, 12)} names no ci.policy, so no policy runs` };
445
450
  const verdicts = new Map();
446
451
  for (const [target, part] of parts) {
447
- const verdict = runPrPolicy(read, { version: 1, stage: "apply", op: at.spec.name, gate: at.gate, env: at.env, pr: null, base: at.base, head: at.head, changeSet: composeChangeSet([part]) }, at.exec);
452
+ const verdict = runPrPolicy(read, { version: 1, stage: "apply", op: at.spec.name, gate: at.gate, env: at.env, pr: null, base: at.base, head: at.head, changeSet: composeChangeSet([part]), ...(cost ? { cost: policyCost(cost, target) } : {}), ...(risk ? { risk } : {}) }, at.exec);
448
453
  if (!verdict)
449
454
  continue;
450
455
  const reason = verdict.result === "error" ? verdict.error : [...verdict.denials, ...verdict.holds].map((f) => f.message).filter(Boolean).join("; ") || undefined;
@@ -452,63 +457,21 @@ export async function opWavePolicyVerdicts(at, parts) {
452
457
  }
453
458
  return { verdicts, ...(read.source ? { source: read.source } : {}) };
454
459
  }
455
- /** The monthly change an estimate gives, in `format`. Throws when it gives none. */
456
- export function readCostEstimate(format, stdout) {
457
- const doc = JSON.parse(stdout);
458
- const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)) ? Number(v) : undefined);
459
- if (format === "chant") {
460
- const delta = num(doc.monthlyDelta);
461
- if (delta === undefined)
462
- throw new Error("the estimate has no monthlyDelta");
463
- return { monthlyDelta: delta, ...(typeof doc.currency === "string" ? { currency: doc.currency } : {}) };
464
- }
465
- // infracost breakdown --format json: diffTotalMonthlyCost, else totalMonthlyCost less pastTotalMonthlyCost.
466
- const diff = num(doc.diffTotalMonthlyCost);
467
- const total = num(doc.totalMonthlyCost);
468
- const past = num(doc.pastTotalMonthlyCost);
469
- const delta = diff ?? (total !== undefined ? total - (past ?? 0) : undefined);
470
- if (delta === undefined)
471
- throw new Error("the infracost document has no diffTotalMonthlyCost or totalMonthlyCost");
472
- return { monthlyDelta: delta, ...(typeof doc.currency === "string" ? { currency: doc.currency } : {}) };
473
- }
474
- const defaultHoldExec = (argv, cwd) => {
475
- const r = spawnSync(argv[0], argv.slice(1), { cwd, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });
476
- return { status: r.error ? null : r.status, stdout: r.stdout ?? "", stderr: `${r.stderr ?? ""}${r.error ? r.error.message : ""}` };
477
- };
460
+ /** The figures an estimate gives, in `format` (`../cost-estimate.ts`, #5334). Throws when it gives no monthly change. */
461
+ export const readCostEstimate = readEstimate;
478
462
  /** The engine's plan document a capability's artifact names (`artifact.planJson`), when it names one that exists. */
479
- export function planJsonOf(artifact, cwd) {
480
- const p = artifact?.planJson;
481
- if (typeof p !== "string" || p === "")
482
- return undefined;
483
- const path = p.startsWith("/") ? p : join(cwd, p);
484
- return existsSync(path) ? path : undefined;
463
+ export const planJsonOf = planJsonPath;
464
+ /**
465
+ * Price each run that changes something (#4545), with the pull request's estimator (`../cost-estimate.ts`, #5334). A run with no estimate says why.
466
+ * A run's `env` is the one its product's run hooks gave it (#5433): `redactEnv` and `dropEnv` read their values there as well as in the job's.
467
+ */
468
+ export function opWaveCosts(hold, runs, cwd, exec) {
469
+ const priced = priceRuns(hold, runs.map((r) => ({ member: r.target, plan: r.plan, artifact: r.artifact, empty: r.empty, ...(r.env ? { env: r.env } : {}) })), cwd, exec);
470
+ return priced.map(({ member, ...rest }) => ({ target: member, ...rest }));
485
471
  }
486
- /** Price each run that changes something (#4545). A run with no estimate says why. */
487
- export function opWaveCosts(hold, runs, cwd, exec = defaultHoldExec) {
488
- const format = hold.format ?? "infracost";
489
- const out = [];
490
- for (const run of runs) {
491
- if (run.empty)
492
- continue;
493
- const planJson = planJsonOf(run.artifact, cwd);
494
- if (hold.command.some((a) => a.includes("{planJson}")) && !planJson) {
495
- out.push({ target: run.target, error: "its plan names no plan document to price" });
496
- continue;
497
- }
498
- const argv = hold.command.map((a) => a.replaceAll("{target}", run.target).replaceAll("{plan}", run.plan).replaceAll("{planJson}", planJson ?? ""));
499
- const r = exec(argv, cwd);
500
- if (r.status !== 0) {
501
- out.push({ target: run.target, error: `${argv[0]} ${r.status === null ? "did not run" : `exited ${r.status}`}: ${(r.stderr || r.stdout).trim().split("\n").slice(-2).join(" ")}` });
502
- continue;
503
- }
504
- try {
505
- out.push({ target: run.target, ...readCostEstimate(format, r.stdout) });
506
- }
507
- catch (err) {
508
- out.push({ target: run.target, error: `the estimate cannot be read: ${err instanceof Error ? err.message : String(err)}` });
509
- }
510
- }
511
- return out;
472
+ /** A wave's estimates as the record a policy reads as `input.cost` (#5334), against the hold's `approveAbove`. */
473
+ export function opWaveCostEstimate(hold, costs) {
474
+ return costEstimateOf(hold, costs.map(({ target, ...rest }) => ({ member: target, ...rest })));
512
475
  }
513
476
  /** Sum a wave's estimates against `approveAbove` (#4545). */
514
477
  export function opWaveCostVerdict(hold, costs) {
@@ -0,0 +1,41 @@
1
+ /**
2
+ * An environment's config and secret set on its stage's wave jobs (#5348).
3
+ *
4
+ * The Op waves generators (GitHub, GitLab, Forgejo) call
5
+ * {@link opWavesWithEnvironmentSets} first with the options they were given.
6
+ * With `environmentSets`, each wave takes the set of its environment: the
7
+ * spec's `labels.Env` when it names one (a stage of a pipeline, #5324,
8
+ * names its stage there), else the wave's name. The set's config, its
9
+ * record and its forge secrets join the wave's `variables`, which every job
10
+ * of the wave reads, and the read of the store secrets joins the wave's
11
+ * `prelude`, the lines of the command's own step, which run after the
12
+ * wave's trade and the product's login. A set's variable replaces a wave
13
+ * variable of the same name.
14
+ *
15
+ * Before merge (`beforeMerge`) a wave's plan job runs the pull request's
16
+ * code with the wave's variables, so a set that holds a secret is refused
17
+ * there; its config goes on as above.
18
+ *
19
+ * Without `environmentSets` the spec and the options come back as they
20
+ * were, so the files render byte for byte as before.
21
+ */
22
+ import type { OpWavesPipelineOptions } from "../lexicon.js";
23
+ import type { OpWavesSpec } from "./op-waves.js";
24
+ import { type EnvironmentSetForge, type ResolvedEnvironmentSet } from "../components/environment-sets.js";
25
+ /** The environment a wave's set is read for: the spec's `labels.Env`, else the wave's name. */
26
+ export declare function opWaveSetEnvironment(spec: Pick<OpWavesSpec, "labels">, wave: {
27
+ name: string;
28
+ }): string;
29
+ /**
30
+ * The variables a job of the set's stage sets, as the forge reads them:
31
+ * the config, the record and, unless `secrets` is false, the forge secrets.
32
+ * Throws on a name the jobs set or drop themselves.
33
+ */
34
+ export declare function environmentSetForgeVariables(set: ResolvedEnvironmentSet, forge: EnvironmentSetForge, options?: {
35
+ secrets?: boolean;
36
+ }): Record<string, string>;
37
+ /** `spec` and `options` with each wave's environment set on its jobs; both as given without `environmentSets`. */
38
+ export declare function opWavesWithEnvironmentSets(spec: OpWavesSpec, options: OpWavesPipelineOptions, forge: EnvironmentSetForge): {
39
+ spec: OpWavesSpec;
40
+ options: OpWavesPipelineOptions;
41
+ };
@@ -0,0 +1,82 @@
1
+ /**
2
+ * An environment's config and secret set on its stage's wave jobs (#5348).
3
+ *
4
+ * The Op waves generators (GitHub, GitLab, Forgejo) call
5
+ * {@link opWavesWithEnvironmentSets} first with the options they were given.
6
+ * With `environmentSets`, each wave takes the set of its environment: the
7
+ * spec's `labels.Env` when it names one (a stage of a pipeline, #5324,
8
+ * names its stage there), else the wave's name. The set's config, its
9
+ * record and its forge secrets join the wave's `variables`, which every job
10
+ * of the wave reads, and the read of the store secrets joins the wave's
11
+ * `prelude`, the lines of the command's own step, which run after the
12
+ * wave's trade and the product's login. A set's variable replaces a wave
13
+ * variable of the same name.
14
+ *
15
+ * Before merge (`beforeMerge`) a wave's plan job runs the pull request's
16
+ * code with the wave's variables, so a set that holds a secret is refused
17
+ * there; its config goes on as above.
18
+ *
19
+ * Without `environmentSets` the spec and the options come back as they
20
+ * were, so the files render byte for byte as before.
21
+ */
22
+ import { environmentSetJobInputs, resolveEnvironmentSet } from "../components/environment-sets.js";
23
+ import { FORGE_TOKEN_VARS } from "../ci-handover.js";
24
+ import { OIDC_REQUEST_VARS } from "../ci-identity.js";
25
+ /** The environment a wave's set is read for: the spec's `labels.Env`, else the wave's name. */
26
+ export function opWaveSetEnvironment(spec, wave) {
27
+ return spec.labels?.Env ?? wave.name;
28
+ }
29
+ /** The forge's spelling of a passed secret: `${{ secrets.<s> }}`, or GitLab's `$<s>` (none when the names match, since GitLab passes it as it is). */
30
+ function forgeSecret(forge, variable, secret) {
31
+ if (forge !== "gitlab")
32
+ return `\${{ secrets.${secret} }}`;
33
+ return variable === secret ? undefined : `$${secret}`;
34
+ }
35
+ /**
36
+ * The variables a job of the set's stage sets, as the forge reads them:
37
+ * the config, the record and, unless `secrets` is false, the forge secrets.
38
+ * Throws on a name the jobs set or drop themselves.
39
+ */
40
+ export function environmentSetForgeVariables(set, forge, options = {}) {
41
+ const inputs = environmentSetJobInputs(set, forge, options);
42
+ const reserved = new Set([...FORGE_TOKEN_VARS, ...OIDC_REQUEST_VARS]);
43
+ const out = { ...inputs.variables };
44
+ for (const [variable, secret] of Object.entries(inputs.secrets)) {
45
+ const spelled = forgeSecret(forge, variable, secret);
46
+ if (spelled !== undefined)
47
+ out[variable] = spelled;
48
+ }
49
+ for (const name of Object.keys(out)) {
50
+ if (reserved.has(name))
51
+ throw new Error(`the set of ${set.entry} sets ${name}, which the jobs set or drop themselves; give it another name`);
52
+ }
53
+ return out;
54
+ }
55
+ /** `spec` and `options` with each wave's environment set on its jobs; both as given without `environmentSets`. */
56
+ export function opWavesWithEnvironmentSets(spec, options, forge) {
57
+ const sets = options.environmentSets;
58
+ if (!sets)
59
+ return { spec, options };
60
+ const waveJobs = { ...(options.waveJobs ?? {}) };
61
+ const waves = spec.waves.map((wave) => {
62
+ const env = opWaveSetEnvironment(spec, wave);
63
+ let set;
64
+ try {
65
+ set = resolveEnvironmentSet(sets, env);
66
+ }
67
+ catch (err) {
68
+ throw new Error(`Op waves "${spec.name}": wave "${wave.name}" runs in ${env}, and ${err instanceof Error ? err.message : String(err)}`);
69
+ }
70
+ if (options.beforeMerge && set.secrets.length > 0) {
71
+ throw new Error(`Op waves "${spec.name}": the set of ${set.entry} holds secrets (${set.secrets.map((s) => s.name).join(", ")}), and before merge a wave's plan job runs the pull request's code with the wave's variables; run the stage's waves on a push to pass them`);
72
+ }
73
+ const inputs = environmentSetJobInputs(set, forge);
74
+ if (inputs.setup.length > 0) {
75
+ const own = waveJobs[wave.name] ?? {};
76
+ waveJobs[wave.name] = { ...own, prelude: [...inputs.setup, ...(own.prelude ?? [])] };
77
+ }
78
+ return { ...wave, variables: { ...(wave.variables ?? {}), ...environmentSetForgeVariables(set, forge) } };
79
+ });
80
+ const { environmentSets: _sets, ...rest } = options;
81
+ return { spec: { ...spec, waves }, options: { ...rest, ...(Object.keys(waveJobs).length > 0 ? { waveJobs } : {}) } };
82
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Findings for an Op waves spec's approval rules (#5349): a count plain
3
+ * `chant approve` lines can meet, and a rule that needs proof on a wave where
4
+ * nothing can prove an approver. Kept apart from `./op-waves.ts`, so the
5
+ * gate-decision bundle stays small.
6
+ */
7
+ import type { GateApprovalSource, OpWavesSpec } from "./op-waves.js";
8
+ /**
9
+ * Whether a rule that needs proof on a wave nothing can prove an approver
10
+ * for refuses the spec (#5349, #5379). True: `generateOpWavesPipeline`
11
+ * refuses the spec with the finding's lines and writes nothing.
12
+ */
13
+ export declare const UNPROVABLE_QUORUM_REFUSED = true;
14
+ /**
15
+ * The first chant whose `generateOpWavesPipeline` refuses an approval rule
16
+ * that needs proof where the signers file names nobody and no review mode
17
+ * applies (#5379), and writes nothing.
18
+ */
19
+ export declare const UNPROVABLE_QUORUM_REFUSED_FLOOR = "0.124.110";
20
+ /** What can prove an approver where the spec is built (#5349). */
21
+ export interface OpWavesProofSources {
22
+ /** The signers file the trust policy names, such as `.chant/allowed_signers`. */
23
+ signersPath: string;
24
+ /** Whether that file, or `.chant/trust.json`'s passkeys, names at least one signer. */
25
+ signersNamed: boolean;
26
+ }
27
+ /**
28
+ * Rules no approver can meet (#5349), one line each: a rule that needs a
29
+ * proven approver (`roles`, `notAuthor` or `proven`) on a wave where
30
+ * nothing can prove one. A seal proves its approver under every mode, so
31
+ * only when the signers file names nobody; and `pr-review` proves the merged
32
+ * pull request's reviewers (and a `reviewLedger`'s), so only on a wave under
33
+ * another mode. A wave that asks a decision point is decided by the point.
34
+ */
35
+ export declare function opWavesUnprovableQuorum(spec: Pick<OpWavesSpec, "waves" | "approvals" | "point">, proof: OpWavesProofSources): string[];
36
+ /** The findings for a spec (#5349): `refusals` stop the build, `warnings` are printed and the pipeline is written. */
37
+ export declare function opWavesQuorumFindings(spec: Pick<OpWavesSpec, "waves" | "approvals" | "point">, proof: OpWavesProofSources, refuseUnprovable?: boolean): {
38
+ warnings: string[];
39
+ refusals: string[];
40
+ };
41
+ /** The approval modes that count a plain `chant approve` line of the digest, sealed or not (#5349). */
42
+ export declare const PLAIN_APPROVAL_MODES: readonly GateApprovalSource[];
43
+ /**
44
+ * Warnings for a spec's approval rules (#5349), one line each: a rule whose
45
+ * `count` is above 1, without `proven`, on a wave whose `approval` mode
46
+ * takes plain `chant approve` lines. One person who can push to
47
+ * `chant/lifecycle` can write those lines in two names, so the count does
48
+ * not show two people approved. A rule with `roles` already counts only
49
+ * proven approvers and is left out. `sealed` counts sealed approvals only.
50
+ * A wave that asks a decision point is decided by the point. The spec is
51
+ * not refused: the rule is valid and works as it did.
52
+ */
53
+ export declare function opWavesQuorumWarnings(spec: Pick<OpWavesSpec, "waves" | "approvals" | "point">): string[];