@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,42 @@
1
+ /**
2
+ * The change risk on the pull-request path (#5325): `ci.risk` in the
3
+ * workspace declaration, read at the base the job measures the change from,
4
+ * scored by `chant components pr-plan` and `pr-apply` over the change set the
5
+ * gate binds. The record is `../change-risk.ts`'s: the report and the note
6
+ * carry it as `risk`, the stored change set keeps it, and the policy reads
7
+ * it as `input.risk`.
8
+ *
9
+ * Reading it at base means a change cannot raise its own `approveAbove`,
10
+ * drop a question, or drop the score that would ask for an approval. Like
11
+ * the cost estimate, a base that cannot be read while the checkout names
12
+ * `ci.risk` stops the job.
13
+ */
14
+ import { type ChangeRisk, type ChangeRiskSettings } from "../change-risk.js";
15
+ import type { ChangeSetDocument } from "../change-set.js";
16
+ import type { GraphIdReader } from "../lifecycle/gate-change-set.js";
17
+ import type { PrMigrationFile } from "../pr-migrations.js";
18
+ import type { PolicyReview } from "./pr-policy.js";
19
+ /** `ci.risk` as read at base. */
20
+ export interface PrLoopRisk {
21
+ /** Absent when the declaration at base sets none. */
22
+ settings?: Omit<ChangeRiskSettings, "quorum">;
23
+ base: string;
24
+ /** A line for the log when no risk is scored because the base has no declaration. */
25
+ note?: string;
26
+ }
27
+ /** The risk settings a pull-request job in `cwd` scores under, from the declaration at `base`. Throws when the base cannot be read and the checkout names one. */
28
+ export declare function prLoopRiskAt(cwd: string, base: string): PrLoopRisk;
29
+ /** The graph nodes that depend on what `doc` changes, from the graph `readGraph` reads in `cwd`, or why none were read. */
30
+ export declare function prRiskDependents(doc: ChangeSetDocument, cwd: string, readGraph: GraphIdReader): Promise<{
31
+ dependents: string[];
32
+ } | {
33
+ error: string;
34
+ }>;
35
+ /** Score a planned change set under `ci.risk` at base. Undefined when the base sets none. */
36
+ export declare function scorePrSet(read: PrLoopRisk, facts: {
37
+ doc: ChangeSetDocument;
38
+ env: string;
39
+ review?: PolicyReview;
40
+ migrations?: readonly PrMigrationFile[];
41
+ dependents?: readonly string[];
42
+ }): ChangeRisk | undefined;
@@ -0,0 +1,74 @@
1
+ /**
2
+ * The change risk on the pull-request path (#5325): `ci.risk` in the
3
+ * workspace declaration, read at the base the job measures the change from,
4
+ * scored by `chant components pr-plan` and `pr-apply` over the change set the
5
+ * gate binds. The record is `../change-risk.ts`'s: the report and the note
6
+ * carry it as `risk`, the stored change set keeps it, and the policy reads
7
+ * it as `input.risk`.
8
+ *
9
+ * Reading it at base means a change cannot raise its own `approveAbove`,
10
+ * drop a question, or drop the score that would ask for an approval. Like
11
+ * the cost estimate, a base that cannot be read while the checkout names
12
+ * `ci.risk` stops the job.
13
+ */
14
+ import { readDeclaration, WorkspaceReadError } from "../workspace/declaration.js";
15
+ import { locateWorkspace } from "../workspace/which-chant.js";
16
+ import { graphDependents, scoreChangeRisk } from "../change-risk.js";
17
+ import { mapChangeSetToGraph } from "../change-set-graph.js";
18
+ function checkoutNamesRisk(cwd) {
19
+ try {
20
+ return readDeclaration(locateWorkspace(cwd).tree).ci?.risk !== undefined;
21
+ }
22
+ catch {
23
+ return false;
24
+ }
25
+ }
26
+ /** The risk settings a pull-request job in `cwd` scores under, from the declaration at `base`. Throws when the base cannot be read and the checkout names one. */
27
+ export function prLoopRiskAt(cwd, base) {
28
+ try {
29
+ const settings = readDeclaration(locateWorkspace(cwd, base).tree).ci?.risk;
30
+ return settings ? { base, settings } : { base };
31
+ }
32
+ catch (err) {
33
+ const missing = err instanceof WorkspaceReadError && (err.code === "declaration-missing" || err.code === "not-a-git-repository");
34
+ const why = err instanceof Error ? err.message : String(err);
35
+ if (checkoutNamesRisk(cwd)) {
36
+ if (missing)
37
+ return { base, note: `ci.risk: the base ${base.slice(0, 12)} has no workspace declaration, so the risk this change declares is scored once it merges` };
38
+ throw new Error(`ci.risk is read from the workspace declaration at ${base.slice(0, 12)}, and it could not be read (${why}), so the plan cannot be scored`);
39
+ }
40
+ return { base };
41
+ }
42
+ }
43
+ /** The graph nodes that depend on what `doc` changes, from the graph `readGraph` reads in `cwd`, or why none were read. */
44
+ export async function prRiskDependents(doc, cwd, readGraph) {
45
+ try {
46
+ const read = await readGraph(cwd);
47
+ if ("error" in read)
48
+ return { error: read.error };
49
+ const mapped = mapChangeSetToGraph(doc, { member: null, at: null, ids: read.ids });
50
+ return { dependents: graphDependents(mapped, read.edges ?? []) };
51
+ }
52
+ catch (err) {
53
+ return { error: err instanceof Error ? err.message : String(err) };
54
+ }
55
+ }
56
+ /** Score a planned change set under `ci.risk` at base. Undefined when the base sets none. */
57
+ export function scorePrSet(read, facts) {
58
+ if (!read.settings)
59
+ return undefined;
60
+ const review = facts.review
61
+ ? {
62
+ risk: facts.review.risk,
63
+ ...(facts.review.answers ? { answers: facts.review.answers } : {}),
64
+ ...(facts.review.found ? {} : { unknownBecause: facts.review.reason ?? "no review was found" }),
65
+ }
66
+ : undefined;
67
+ return scoreChangeRisk({
68
+ changeSet: facts.doc,
69
+ environments: [facts.env],
70
+ ...(facts.migrations?.length ? { migrations: facts.migrations } : {}),
71
+ ...(facts.dependents ? { dependents: facts.dependents } : {}),
72
+ ...(review ? { review } : {}),
73
+ }, read.settings);
74
+ }
@@ -435,6 +435,49 @@ export declare function productCommitSpec(wordsIn: CiProductWordsInput | CiProdu
435
435
  export declare function productCheckCommit(wordsIn: CiProductWordsInput | CiProductWords, op: string, options: Omit<OpCommitSpec, "on" | "comment">): OpCommitSpec;
436
436
  /** The agent's Op spec for `/<product> agent <ask>` (#4616). The settings are checked here, so a product finds a bad one when it generates. */
437
437
  export declare function productAgentSpec(wordsIn: CiProductWordsInput | CiProductWords, comment: string, options?: ProductAgentOptions): ScheduledOpSpec;
438
+ /**
439
+ * The alert agent's Op spec (#5329): a workflow of its own that the relay
440
+ * starts after it records an alert, and that runs on its schedule
441
+ * (`AGENT_ALERT_SCHEDULE` unless `schedule` names another cron). The agent
442
+ * answers each member's new alerts with a pull request from
443
+ * `<product>/agent/<name>-<member>`. Off until a product asks for it.
444
+ */
445
+ export declare function productAlertAgent(wordsIn: CiProductWordsInput | CiProductWords, options?: ProductAgentOptions & {
446
+ schedule?: string;
447
+ }): ScheduledOpSpec;
448
+ /**
449
+ * The failed-apply agent's Op spec (#5357): a workflow of its own that runs
450
+ * on its schedule (`AGENT_ALERT_SCHEDULE` unless `schedule` names another
451
+ * cron) and when started by hand, and answers the failed applies the apply
452
+ * jobs recorded (`CHANT_AGENT_FACTS=apply-failed` on those jobs, with the
453
+ * relay key) with a pull request from `<product>/agent/<name>-<member>`.
454
+ * The triage comment stays. Off until a product asks for it.
455
+ */
456
+ export declare function productApplyFailedAgent(wordsIn: CiProductWordsInput | CiProductWords, options?: ProductAgentOptions & {
457
+ schedule?: string;
458
+ }): ScheduledOpSpec;
459
+ /**
460
+ * The failed-verify agent's Op spec (#5339): a workflow of its own that
461
+ * runs on its schedule (`AGENT_ALERT_SCHEDULE` unless `schedule` names
462
+ * another cron) and when started by hand, and answers the failed verify
463
+ * steps and failing soak checks the promote and wave jobs recorded
464
+ * (`agentFacts` with `verify-failed` among its triggers, which puts
465
+ * `CHANT_AGENT_FACTS=verify-failed` and the relay key on those jobs) with a
466
+ * pull request from `<product>/agent/<name>-<member>`. A rollback the stage
467
+ * requested stands. Off until a product asks for it.
468
+ */
469
+ export declare function productVerifyFailedAgent(wordsIn: CiProductWordsInput | CiProductWords, options?: ProductAgentOptions & {
470
+ schedule?: string;
471
+ }): ScheduledOpSpec;
472
+ /**
473
+ * A scheduled agent's Op spec (#5357): a workflow of its own on `schedule`,
474
+ * a cron, which does `task` on each run and answers with a pull request
475
+ * from `<product>/agent/<name>`. Off until a product asks for it.
476
+ */
477
+ export declare function productScheduleAgent(wordsIn: CiProductWordsInput | CiProductWords, options: ProductAgentOptions & {
478
+ schedule: string;
479
+ task: string;
480
+ }): ScheduledOpSpec;
438
481
  /**
439
482
  * The `agent` of a scheduled drift Op (#4616): after the Op's run exits with
440
483
  * chant's `drift` code, the agent changes the code to say what is live and
@@ -25,7 +25,7 @@ import { opWaveBinArgv, opWaveJobs, opWavesControlTarget } from "../op/op-waves.
25
25
  import { controlNoteCheckout } from "../control/dispatch.js";
26
26
  import { assertProductWords, CHANT_WORDS, CI_PRODUCT_COMMANDS, commentLine, productStatusContext, } from "../ci-product-words.js";
27
27
  import { checkJobOptions, PR_LOOP_REPORT_DIR, prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prNoteCommandsJob, prStaleJob, withProductBin } from "./pr-pipeline.js";
28
- import { resolveAgentSpec } from "../ci-agent.js";
28
+ import { AGENT_ALERT_SCHEDULE, resolveAgentSpec } from "../ci-agent.js";
29
29
  import { resolveCommitSpec } from "../ci-commit.js";
30
30
  import { planEvidenceOf, productPlanContext, productPlanJobs, productPlanReachLock } from "./product-plan.js";
31
31
  import { gitlabOpenEvidenceDir } from "../ci-evidence-jobs.js";
@@ -75,6 +75,70 @@ export function productAgentSpec(wordsIn, comment, options = {}) {
75
75
  resolveAgentSpec(name, agent, words.product);
76
76
  return { name, trigger: { kind: "pull_request" }, agent, ...(runner !== undefined ? { runner } : {}) };
77
77
  }
78
+ /**
79
+ * The alert agent's Op spec (#5329): a workflow of its own that the relay
80
+ * starts after it records an alert, and that runs on its schedule
81
+ * (`AGENT_ALERT_SCHEDULE` unless `schedule` names another cron). The agent
82
+ * answers each member's new alerts with a pull request from
83
+ * `<product>/agent/<name>-<member>`. Off until a product asks for it.
84
+ */
85
+ export function productAlertAgent(wordsIn, options = {}) {
86
+ const words = assertProductWords(wordsIn);
87
+ const { name: given, runner, schedule, ...settings } = options;
88
+ const name = given ?? `${words.product}-alert-agent`;
89
+ const agent = { on: "alert", ...settings };
90
+ resolveAgentSpec(name, agent, words.product);
91
+ return { name, trigger: { kind: "cron", schedule: schedule ?? AGENT_ALERT_SCHEDULE }, agent, ...(runner !== undefined ? { runner } : {}) };
92
+ }
93
+ /**
94
+ * The failed-apply agent's Op spec (#5357): a workflow of its own that runs
95
+ * on its schedule (`AGENT_ALERT_SCHEDULE` unless `schedule` names another
96
+ * cron) and when started by hand, and answers the failed applies the apply
97
+ * jobs recorded (`CHANT_AGENT_FACTS=apply-failed` on those jobs, with the
98
+ * relay key) with a pull request from `<product>/agent/<name>-<member>`.
99
+ * The triage comment stays. Off until a product asks for it.
100
+ */
101
+ export function productApplyFailedAgent(wordsIn, options = {}) {
102
+ const words = assertProductWords(wordsIn);
103
+ const { name: given, runner, schedule, task: _task, ...settings } = options;
104
+ const name = given ?? `${words.product}-apply-failed-agent`;
105
+ const agent = { on: "apply-failed", ...settings };
106
+ resolveAgentSpec(name, agent, words.product);
107
+ return { name, trigger: { kind: "cron", schedule: schedule ?? AGENT_ALERT_SCHEDULE }, agent, ...(runner !== undefined ? { runner } : {}) };
108
+ }
109
+ /**
110
+ * The failed-verify agent's Op spec (#5339): a workflow of its own that
111
+ * runs on its schedule (`AGENT_ALERT_SCHEDULE` unless `schedule` names
112
+ * another cron) and when started by hand, and answers the failed verify
113
+ * steps and failing soak checks the promote and wave jobs recorded
114
+ * (`agentFacts` with `verify-failed` among its triggers, which puts
115
+ * `CHANT_AGENT_FACTS=verify-failed` and the relay key on those jobs) with a
116
+ * pull request from `<product>/agent/<name>-<member>`. A rollback the stage
117
+ * requested stands. Off until a product asks for it.
118
+ */
119
+ export function productVerifyFailedAgent(wordsIn, options = {}) {
120
+ const words = assertProductWords(wordsIn);
121
+ const { name: given, runner, schedule, task: _task, ...settings } = options;
122
+ const name = given ?? `${words.product}-verify-failed-agent`;
123
+ const agent = { on: "verify-failed", ...settings };
124
+ resolveAgentSpec(name, agent, words.product);
125
+ return { name, trigger: { kind: "cron", schedule: schedule ?? AGENT_ALERT_SCHEDULE }, agent, ...(runner !== undefined ? { runner } : {}) };
126
+ }
127
+ /**
128
+ * A scheduled agent's Op spec (#5357): a workflow of its own on `schedule`,
129
+ * a cron, which does `task` on each run and answers with a pull request
130
+ * from `<product>/agent/<name>`. Off until a product asks for it.
131
+ */
132
+ export function productScheduleAgent(wordsIn, options) {
133
+ const words = assertProductWords(wordsIn);
134
+ const { name: given, runner, schedule, relayKeyEnv: _relay, ...settings } = options;
135
+ const name = given ?? `${words.product}-schedule-agent`;
136
+ const agent = { on: "schedule", ...settings };
137
+ resolveAgentSpec(name, agent, words.product);
138
+ if (typeof schedule !== "string" || schedule.trim().split(/\s+/).length !== 5)
139
+ throw new Error(`the scheduled agent ${name} needs schedule, a five-field cron`);
140
+ return { name, trigger: { kind: "cron", schedule }, agent, ...(runner !== undefined ? { runner } : {}) };
141
+ }
78
142
  /**
79
143
  * The `agent` of a scheduled drift Op (#4616): after the Op's run exits with
80
144
  * chant's `drift` code, the agent changes the code to say what is live and
@@ -272,6 +336,8 @@ export function productPipelineJobs(forge, env, options) {
272
336
  ...(spec.parallelism === undefined && options.parallelism !== undefined && spec.step !== undefined ? { parallelism: options.parallelism } : {}),
273
337
  }, words),
274
338
  ...(Object.keys(wavesRespond).length > 0 ? { respond: { ...(spec.respond ?? {}), ...wavesRespond } } : {}),
339
+ // #5335: the summary's settings go with the responses to the wave jobs.
340
+ ...(options.waveSummary ? { waveSummary: { ...(spec.waveSummary ?? {}), ...options.waveSummary } } : {}),
275
341
  }
276
342
  : undefined;
277
343
  const specFile = named ? (wavesSpecFile ?? productWavesSpecFile(named.name)) : undefined;
@@ -156,6 +156,8 @@ export declare function planReleaseRollback(input: {
156
156
  label: string | null;
157
157
  /** Components a run left failed or gated in `env` (../lifecycle/mixed-environment.ts). */
158
158
  unsettled?: ReadonlySet<string>;
159
+ /** Restore only these components of the release (#5328): the members a stage's rollback request names. */
160
+ only?: ReadonlySet<string>;
159
161
  }): PromotionPlan | {
160
162
  error: string;
161
163
  };
@@ -293,6 +295,8 @@ export declare function gateApprover(result: DriverComponentResult | undefined):
293
295
  * recorded. Undefined for a component that passed no gate.
294
296
  */
295
297
  export declare function gateAdmission(result: DriverComponentResult | undefined): ReleaseAdmission | undefined;
298
+ /** The gates a component skipped in this run because they apply in other environments (#5401), sorted and distinct; undefined when none. */
299
+ export declare function gatesSkipped(result: DriverComponentResult | undefined): string[] | undefined;
296
300
  /** What a promote, rollback or redeploy knows about its own run, for the records it writes. */
297
301
  export interface DeployRunInfo {
298
302
  runId: string;
@@ -302,6 +306,8 @@ export interface DeployRunInfo {
302
306
  approver?: string;
303
307
  /** The gate resolution that admitted the deploy (#4020), from {@link gateAdmission}. */
304
308
  admission?: ReleaseAdmission;
309
+ /** The gates the run skipped because they apply in other environments (#5401), from {@link gatesSkipped}. */
310
+ gatesSkipped?: string[];
305
311
  }
306
312
  /**
307
313
  * The release record a successful promotion appends to the target ledger.
@@ -239,6 +239,10 @@ export function planReleaseRollback(input) {
239
239
  inRelease.add(t.component);
240
240
  for (const a of release.artifactDigests)
241
241
  inRelease.add(a.component);
242
+ if (input.only)
243
+ for (const c of [...inRelease])
244
+ if (!input.only.has(c))
245
+ inRelease.delete(c);
242
246
  const items = [];
243
247
  const notPromoted = [];
244
248
  const neverRan = [];
@@ -627,6 +631,14 @@ export function gateAdmission(result) {
627
631
  }
628
632
  return admission;
629
633
  }
634
+ /** The gates a component skipped in this run because they apply in other environments (#5401), sorted and distinct; undefined when none. */
635
+ export function gatesSkipped(result) {
636
+ const names = new Set();
637
+ for (const record of result?.records ?? [])
638
+ if (record.gateSkipped)
639
+ names.add(record.kind.replace(/^gate:/, ""));
640
+ return names.size > 0 ? [...names].sort() : undefined;
641
+ }
630
642
  /** The fields a promote, a rollback and a redeploy record share: the artifact is the earlier release's own. */
631
643
  function sharedRecord(item, env, run) {
632
644
  const { source } = item;
@@ -641,6 +653,7 @@ function sharedRecord(item, env, run) {
641
653
  actor: run.actor,
642
654
  ...(run.approver ? { approver: run.approver } : {}),
643
655
  ...(run.admission ? { admission: run.admission } : {}),
656
+ ...(run.gatesSkipped ? { gatesSkipped: run.gatesSkipped } : {}),
644
657
  ...(source.manifestDigest ? { manifestDigest: source.manifestDigest } : {}),
645
658
  ...(source.inputDigest ? { inputDigest: source.inputDigest } : {}),
646
659
  // #4274: a release's templates digest stays one when it is deployed again.
@@ -55,6 +55,7 @@ import { memoryGateLedgerPort } from "../op/gate.js";
55
55
  import { RELEASE_DIGESTS_ENV } from "../lifecycle/release-images.js";
56
56
  /** The deploy step fields whose literal file paths are a component's templates. */
57
57
  export { TEMPLATE_FIELDS } from "./deploy-inputs.js";
58
+ import { componentForEnvironment } from "./step-environments.js";
58
59
  import { DEPLOY_INPUT_FIELDS, directoryFiles, ignoredByGit, TEMPLATE_FIELDS, walkFiles } from "./deploy-inputs.js";
59
60
  /** The prefix a step may write before an archive-relative template path. */
60
61
  const ARCHIVE_PREFIX = "archive:";
@@ -248,7 +249,8 @@ async function loadComponents(inputs, env) {
248
249
  config,
249
250
  params: resolved.provenance.map(({ name, value, source }) => ({ name, value, source })),
250
251
  declared: all.length,
251
- components: enabled.map((c) => ({ component: applyConfigDefaults(c, config), file: fileOf.get(c.name) })),
252
+ // #5360: each step's inputs for this environment, so its target's files are the ones recorded.
253
+ components: enabled.map((c) => ({ component: componentForEnvironment(applyConfigDefaults(c, config), env).component, file: fileOf.get(c.name) })),
252
254
  };
253
255
  }
254
256
  /**
@@ -72,7 +72,12 @@ import type { StoredChangeSetRead } from "../lifecycle/change-set-store.js";
72
72
  export { RELEASE_GATE_OP };
73
73
  /** The address and type a `chant` member's one entry has. */
74
74
  export declare const RELEASE_COMPONENT_ENTRY_TYPE = "chant:component";
75
- /** The name of every gate the compositions declare, nested phases included, sorted and distinct. */
75
+ /**
76
+ * The name of every gate the compositions declare, nested phases included,
77
+ * sorted and distinct. A promote hands it components resolved for its
78
+ * environment (`componentForEnvironment`, ./step-environments.ts), so a gate
79
+ * whose `environments` names others is already out of its phase (#5401).
80
+ */
76
81
  export declare function gateNamesOf(components: readonly DriverComponent[]): string[];
77
82
  /** What an environment runs of one component now: its latest deploy record, and the release that record names when it can be read. */
78
83
  export interface CurrentDeploy {
@@ -60,6 +60,7 @@
60
60
  * recorded since (#4035): its record names what ran before that run.
61
61
  */
62
62
  import { groupsByComponent, planComponentGroup } from "./groups.js";
63
+ import { stepInputForEnvironment } from "./step-environments.js";
63
64
  import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences } from "./driver.js";
64
65
  import { componentPlanDigest } from "./gate-plan.js";
65
66
  import { gateName, RELEASE_GATE_OP } from "../op/gate-name.js";
@@ -75,7 +76,12 @@ function isGate(step) {
75
76
  function isPhase(step) {
76
77
  return typeof step.phase === "string" && Array.isArray(step.steps);
77
78
  }
78
- /** The name of every gate the compositions declare, nested phases included, sorted and distinct. */
79
+ /**
80
+ * The name of every gate the compositions declare, nested phases included,
81
+ * sorted and distinct. A promote hands it components resolved for its
82
+ * environment (`componentForEnvironment`, ./step-environments.ts), so a gate
83
+ * whose `environments` names others is already out of its phase (#5401).
84
+ */
79
85
  export function gateNamesOf(components) {
80
86
  const names = new Set();
81
87
  const walk = (steps) => {
@@ -323,7 +329,9 @@ export async function planReleaseSet(input) {
323
329
  const unknown = unknownOf(component, new Set());
324
330
  let exposes;
325
331
  for (const step of plannable) {
326
- const { kind, ...rest } = step;
332
+ const { kind, ...declared } = step;
333
+ // #5360: the step's inputs for this environment.
334
+ const rest = stepInputForEnvironment(declared, env, { component: name, phase: "deploy", kind });
327
335
  const result = await registry.resolve(kind).plan(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs));
328
336
  if (result.outputs)
329
337
  exposes = { known: { ...(exposes?.known ?? {}), ...result.outputs.known }, unknown: [...new Set([...(exposes?.unknown ?? []), ...result.outputs.unknown])].sort() };
@@ -0,0 +1,236 @@
1
+ /**
2
+ * A step's inputs per environment (#5360): one component carries a release's
3
+ * commit to each environment's own target.
4
+ *
5
+ * A step may carry `environments`, keyed by environment name, each entry a
6
+ * map of the step's inputs for that environment:
7
+ *
8
+ * {
9
+ * kind: "pulumi-up",
10
+ * dir: "infra/shop",
11
+ * environments: {
12
+ * dev: { stack: "acme/shop/dev" },
13
+ * staging: { stack: "acme/shop/staging" },
14
+ * prod: { stack: "acme/shop/prod" },
15
+ * },
16
+ * }
17
+ *
18
+ * Core resolves it for the run's environment before the capability sees the
19
+ * input: the entry's keys replace the step's keys of the same name, one level
20
+ * deep, and `environments` itself is removed. So `pulumi-up` takes its stack
21
+ * this way, `terraform-apply` its `root` and `vars`, and any other engine
22
+ * step whatever input picks its target. A step with no `environments` is
23
+ * passed on as it is.
24
+ *
25
+ * The map is plain data in the composition, so it is the same in every
26
+ * environment: `chant components promote --to staging` deploys the
27
+ * component it loaded with the staging entry, and records it under staging;
28
+ * `rollback` and `redeploy` pick the entry of the environment they act on.
29
+ *
30
+ * An environment the map does not name is refused before anything runs,
31
+ * naming the environments it does name. A pull request's environment
32
+ * `pr-<n>` takes the entry of its template environment, the one `pr-env up`
33
+ * sets in `CHANT_ENV_TEMPLATE` (`ci.prEnvironment.template`); a template
34
+ * that names a stack, `<project>/<stack>`, picks the entry its last segment
35
+ * names. The step's own review-stack handling then runs on that entry, as
36
+ * it does on a fixed stack.
37
+ *
38
+ * The callers resolve early, where the environment is known and before a
39
+ * plan, a release pin or a run reads the steps: `chant run --components`
40
+ * (./cli-support.ts), promote, rollback and redeploy
41
+ * (../cli/handlers/promote.ts), a release cut's compile
42
+ * (./release-compile.ts), and the fan-out a pull request's plan and `chant
43
+ * components fan-out` derive (./fan-out-support.ts), whose declared reads
44
+ * (./declared-reads.ts) a capability such as `pulumi-up` answers from the
45
+ * resolved stack. A group's members reach `planGroup`, `groupReads` and
46
+ * `groupFallback` resolved (./groups.ts), so terraform's composition reads
47
+ * each member's resolved root. The driver refuses a component still carrying a
48
+ * map that does not name its environment before its first wave
49
+ * (`runInterpretDriver`), and each place that hands a capability its input
50
+ * resolves the step again, which is a no-op on a resolved one.
51
+ *
52
+ * An environment's config and secret set (./environment-sets.ts, #5348)
53
+ * picks its entry with {@link environmentEntryName}, the same lookup.
54
+ *
55
+ * ## Gate steps (#5401)
56
+ *
57
+ * A gate step takes `environments` too, naming the environments it applies
58
+ * in: a list of names, or a map whose entries may set the gate's `gate`,
59
+ * `description` and `timeout` there.
60
+ *
61
+ * { kind: "gate", gate: "release", environments: ["staging", "prod"] }
62
+ *
63
+ * The same resolution reads it, with the same lookup (a pull request's
64
+ * environment takes its template's entry). In an environment the gate
65
+ * names, the gate stays, its entry merged over it and `environments`
66
+ * removed. In any other, the gate is taken out of its phase and listed on
67
+ * the phase's `skippedGates`, so every reader past this point (the release
68
+ * gate's plan and binding, the gate names a promote prints, the driver)
69
+ * sees only the gates that apply, and the driver records each skip
70
+ * (`gateSkipped` on its step record, a `step-settle` with
71
+ * `skip: "environment"`). A gate step with no `environments` applies in
72
+ * every environment, as before. `chant build` refuses a gate that names an
73
+ * environment the member does not declare ({@link unknownGateEnvironments}).
74
+ *
75
+ * This module imports only the release floors at run time.
76
+ */
77
+ /** The step key that holds its inputs per environment. */
78
+ export declare const STEP_ENVIRONMENTS_KEY = "environments";
79
+ /**
80
+ * The first chant that resolves a component step's `environments` for the
81
+ * run's environment before its capability sees the input (#5360), for
82
+ * `pulumi-up`'s stack, `terraform-apply`'s root and vars and every other
83
+ * engine step, in `run --components`, promote, rollback, redeploy, a
84
+ * release cut, and a pull request's plan, its declared reads and its groups.
85
+ */
86
+ export declare const STEP_ENVIRONMENTS_FLOOR = "0.124.110";
87
+ /**
88
+ * The first chant that applies a gate step only in the environments its
89
+ * `environments` names (#5401): in any other the gate is skipped and the
90
+ * skip recorded on the run's step records, its run events, the release
91
+ * records and `chant workspace status`, and a promote's plan lists it; a
92
+ * gate naming an environment the member does not declare fails `chant
93
+ * build`.
94
+ */
95
+ export declare const GATE_ENVIRONMENTS_FLOOR = "0.124.110";
96
+ /** The keys a gate step's `environments` entry may set (#5401). */
97
+ export declare const GATE_ENVIRONMENT_KEYS: readonly string[];
98
+ /** A gate step that does not apply in the run's environment, as its phase lists it (#5401). */
99
+ export interface SkippedGate {
100
+ /** The gate's name, as the step names it. */
101
+ gate: string;
102
+ /** The environments the gate applies in, in the order it names them. */
103
+ environments: string[];
104
+ }
105
+ /** A skipped gate with the component and phase it sits in. */
106
+ export interface SkippedGateAt extends SkippedGate {
107
+ component: string;
108
+ phase: string;
109
+ }
110
+ /** A step's inputs per environment: environment name to the inputs that replace the step's own. */
111
+ export type StepEnvironments = Record<string, Record<string, unknown>>;
112
+ /** Where the environment and the pull request template come from. */
113
+ export interface StepEnvironmentOptions {
114
+ /** A pull request environment's template. Default: `CHANT_ENV_TEMPLATE` from `processEnv`. */
115
+ template?: string;
116
+ /** Read for the template when none is given. Default: `process.env`. */
117
+ processEnv?: Record<string, string | undefined>;
118
+ }
119
+ /** One step that cannot run in the environment, and why. */
120
+ export interface StepEnvironmentRefusal {
121
+ component: string;
122
+ phase: string;
123
+ kind: string;
124
+ env: string;
125
+ /** The environments the step names, in the order it names them. Empty when the map is malformed. */
126
+ named: string[];
127
+ message: string;
128
+ }
129
+ /** Thrown when a step's `environments` does not name the run's environment. */
130
+ export declare class StepEnvironmentRefusedError extends Error {
131
+ readonly refusals: readonly StepEnvironmentRefusal[];
132
+ constructor(refusals: readonly StepEnvironmentRefusal[]);
133
+ }
134
+ /** Whether `step` carries inputs per environment. */
135
+ export declare function hasStepEnvironments(step: Record<string, unknown>): boolean;
136
+ /** The environments a step names, in the order it names them; empty for a step with none. */
137
+ export declare function stepEnvironmentNames(step: Record<string, unknown>): string[];
138
+ /**
139
+ * The name of the entry `env` takes in a map keyed by environment name:
140
+ * itself, or for a pull request environment `pr-<n>` its template's (the
141
+ * template's name, or the last segment of a template that names a stack).
142
+ * Undefined when the map names neither. A step's `environments` and an
143
+ * environment's config and secret set (./environment-sets.ts, #5348) pick
144
+ * their entry with it, so both read the run's environment the same way.
145
+ */
146
+ export declare function environmentEntryName(map: Record<string, unknown>, env: string, options?: StepEnvironmentOptions): string | undefined;
147
+ /**
148
+ * `step` with its `environments` resolved for `env`, or the reason it
149
+ * cannot run there. A step with no `environments` comes back as it is.
150
+ */
151
+ export declare function stepForEnvironment<T extends Record<string, unknown>>(step: T, env: string, options?: StepEnvironmentOptions): {
152
+ step: T;
153
+ } | {
154
+ error: string;
155
+ named: string[];
156
+ };
157
+ /** The environments a gate step names, in the order it names them; empty for a gate with none or a malformed one. */
158
+ export declare function gateEnvironmentNames(step: Record<string, unknown>): string[];
159
+ /**
160
+ * A gate step resolved for `env` (#5401): the gate with its entry merged and
161
+ * `environments` removed when it applies there, the skip when it does not,
162
+ * or why its `environments` cannot be read. A gate with no `environments`
163
+ * comes back as it is.
164
+ */
165
+ export declare function gateForEnvironment<T extends Record<string, unknown>>(step: T, env: string, options?: StepEnvironmentOptions): {
166
+ step: T;
167
+ } | {
168
+ skipped: SkippedGate;
169
+ } | {
170
+ error: string;
171
+ named: string[];
172
+ };
173
+ /**
174
+ * A step's input with its `environments` resolved for `env`. Throws a
175
+ * {@link StepEnvironmentRefusedError} when the step does not name it. For
176
+ * the places that hand a capability its input; a resolved step comes back
177
+ * as it is.
178
+ */
179
+ export declare function stepInputForEnvironment<T extends Record<string, unknown>>(input: T, env: string, at: {
180
+ component: string;
181
+ phase: string;
182
+ kind: string;
183
+ }, options?: StepEnvironmentOptions): T;
184
+ interface PhaseShape {
185
+ phase: string;
186
+ steps: unknown[];
187
+ onFailure?: PhaseShape[];
188
+ /** The gates taken out of this phase for the run's environment (#5401). */
189
+ skippedGates?: SkippedGate[];
190
+ }
191
+ interface ComponentShape {
192
+ name: string;
193
+ deploy: PhaseShape[];
194
+ verify?: PhaseShape[];
195
+ rollback?: PhaseShape[];
196
+ }
197
+ /**
198
+ * `component` with every step's `environments` resolved for `env`, through
199
+ * `deploy`, `verify`, `rollback`, nested phases and `onFailure`, and the
200
+ * steps that cannot run there. A step that cannot is left as it is, so a
201
+ * caller that does not run the component can still read it. A gate step
202
+ * that does not apply in `env` is taken out of its phase and listed on the
203
+ * phase's `skippedGates` and in `skippedGates` here (#5401). A component
204
+ * with no such step comes back as the same object.
205
+ */
206
+ export declare function componentForEnvironment<C extends ComponentShape>(component: C, env: string, options?: StepEnvironmentOptions): {
207
+ component: C;
208
+ refusals: StepEnvironmentRefusal[];
209
+ skippedGates: SkippedGateAt[];
210
+ };
211
+ /** The gate steps a component skips, read off its resolved phases' `skippedGates`, nested phases and `onFailure` included (#5401). */
212
+ export declare function skippedGatesOf(component: ComponentShape): SkippedGateAt[];
213
+ /** One gate that names an environment the member does not declare (#5401). */
214
+ export interface UnknownGateEnvironment {
215
+ component: string;
216
+ phase: string;
217
+ gate: string;
218
+ /** The names it gives that are not declared. */
219
+ unknown: string[];
220
+ message: string;
221
+ }
222
+ /**
223
+ * Every gate step whose `environments` names an environment outside
224
+ * `declared`, or cannot be read, for `chant build` to refuse (#5401). A gate
225
+ * that names a misspelt environment would otherwise be skipped in the one it
226
+ * was meant for. `declared` holds the member's `environments`, its
227
+ * pipeline's stages and each component's own `environments`.
228
+ */
229
+ export declare function unknownGateEnvironments(components: readonly ComponentShape[], declared: ReadonlySet<string>): UnknownGateEnvironment[];
230
+ /**
231
+ * Every component resolved for `env`. Throws a
232
+ * {@link StepEnvironmentRefusedError} naming each step that cannot run
233
+ * there, with the environments it names, before anything runs.
234
+ */
235
+ export declare function componentsForEnvironment<C extends ComponentShape>(components: readonly C[], env: string, options?: StepEnvironmentOptions): C[];
236
+ export {};