@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,64 @@
1
+ /**
2
+ * What each stage of a folded pipeline becomes (#5324).
3
+ *
4
+ * A stage is an op-waves spec: the pipeline's shared settings, the stage's
5
+ * waves, its gate on every wave, its hooks after the pipeline's, `labels.Env`
6
+ * naming the stage so run and release records go on its environment's
7
+ * ledger. `chant run wave` runs it, and the gate is read from the folded
8
+ * pipeline at the base commit like any op-waves spec's.
9
+ *
10
+ * The merge path: a merge applies the first stage, as products do now, and
11
+ * once its last wave applied cuts a release from the applied commit (an
12
+ * after-apply hook on that wave, read at base with the others). The control
13
+ * repo dispatch (`<product>-applied`) goes after the first stage. Each later
14
+ * stage takes that release through `chant components promote --to <stage>
15
+ * --release <label>` behind its gate. A member with no components takes it
16
+ * by the stage's op waves, which the promote runs once that gate passed
17
+ * (#5427, `./stage-waves.ts`).
18
+ *
19
+ * The stage order is the promotion order: `promotionOrderOf` gives it in the
20
+ * shape `environments` in `chant.config.ts` gives it, so `components
21
+ * promote`, `release cut`, `workspace status` and `workspace train promote`
22
+ * read the same order from either.
23
+ */
24
+ import { type OpWaveHook, type OpWavesSpec } from "../op/op-waves.js";
25
+ import type { PromotionStep } from "../workspace/promotion-order.js";
26
+ import type { PipelineSpec, PipelineStage } from "./spec.js";
27
+ /** The op-waves spec name a stage runs under: `<pipeline>-<stage>`, so each stage's wave gates are its own. */
28
+ export declare function stageWavesName(spec: Pick<PipelineSpec, "name">, stage: string): string;
29
+ /** The stage named `name`, or undefined. */
30
+ export declare function pipelineStage(spec: Pick<PipelineSpec, "stages">, name: string): PipelineStage | undefined;
31
+ /** The stages in promotion order, as `promotionOrder` reads `environments`. */
32
+ export declare function promotionOrderOf(spec: Pick<PipelineSpec, "stages">): PromotionStep[];
33
+ /** The hook a merge's first stage cuts its release with. */
34
+ export declare function releaseCutHook(spec: Pick<PipelineSpec, "release">): OpWaveHook | undefined;
35
+ /**
36
+ * The hook a stage publishes its release artifacts with (#5356), run after
37
+ * the release cut on the first stage's last wave: `chant pipeline artifacts
38
+ * publish --stage <stage>`, through the cut's bin. Undefined when the stage
39
+ * publishes nothing or the merge cuts no release.
40
+ */
41
+ export declare function artifactsPublishHook(spec: Pick<PipelineSpec, "release" | "stages">, stage: string): OpWaveHook | undefined;
42
+ /**
43
+ * The op-waves spec stage `name` runs: its waves under its gate. The first
44
+ * stage also carries the release cut and the control dispatch, since it is
45
+ * the stage a merge applies. A canary wave with no soak of its own takes
46
+ * the stage's (#5327). A stage whose step's targets name environments
47
+ * records its releases under the pipeline's component (#5427). Throws on a
48
+ * stage the pipeline lacks, or a spec no job could run.
49
+ */
50
+ export declare function stageWavesSpec(spec: PipelineSpec, name: string): OpWavesSpec;
51
+ /** Why a stage refuses promotion now, and until when. */
52
+ export interface StageHeld {
53
+ stage: string;
54
+ kind: "hold" | "freeze";
55
+ /** When it lifts by itself, or null when only a change to the pipeline lifts it. */
56
+ until: string | null;
57
+ reason?: string;
58
+ /** What the person who lifts the hold reads first (#5354). */
59
+ description?: string;
60
+ }
61
+ /** The hold or freeze window on `stage` at `now`, or undefined when promotion is open. A hold wins over a window. */
62
+ export declare function stageHeldAt(stage: Pick<PipelineStage, "name" | "hold" | "freeze">, now: Date): StageHeld | undefined;
63
+ /** The line a held stage's refusal prints: what holds it, and until when. */
64
+ export declare function stageHeldLine(held: StageHeld): string;
@@ -0,0 +1,174 @@
1
+ /**
2
+ * What each stage of a folded pipeline becomes (#5324).
3
+ *
4
+ * A stage is an op-waves spec: the pipeline's shared settings, the stage's
5
+ * waves, its gate on every wave, its hooks after the pipeline's, `labels.Env`
6
+ * naming the stage so run and release records go on its environment's
7
+ * ledger. `chant run wave` runs it, and the gate is read from the folded
8
+ * pipeline at the base commit like any op-waves spec's.
9
+ *
10
+ * The merge path: a merge applies the first stage, as products do now, and
11
+ * once its last wave applied cuts a release from the applied commit (an
12
+ * after-apply hook on that wave, read at base with the others). The control
13
+ * repo dispatch (`<product>-applied`) goes after the first stage. Each later
14
+ * stage takes that release through `chant components promote --to <stage>
15
+ * --release <label>` behind its gate. A member with no components takes it
16
+ * by the stage's op waves, which the promote runs once that gate passed
17
+ * (#5427, `./stage-waves.ts`).
18
+ *
19
+ * The stage order is the promotion order: `promotionOrderOf` gives it in the
20
+ * shape `environments` in `chant.config.ts` gives it, so `components
21
+ * promote`, `release cut`, `workspace status` and `workspace train promote`
22
+ * read the same order from either.
23
+ */
24
+ import { assertOpWavesSpec } from "../op/op-waves.js";
25
+ /** The op-waves spec name a stage runs under: `<pipeline>-<stage>`, so each stage's wave gates are its own. */
26
+ export function stageWavesName(spec, stage) {
27
+ return `${spec.name}-${stage}`;
28
+ }
29
+ /** The stage named `name`, or undefined. */
30
+ export function pipelineStage(spec, name) {
31
+ return spec.stages.find((s) => s.name === name);
32
+ }
33
+ /** The stages in promotion order, as `promotionOrder` reads `environments`. */
34
+ export function promotionOrderOf(spec) {
35
+ return spec.stages.map((s) => ({ name: s.name, canary: s.canary === true }));
36
+ }
37
+ /** The hook a merge's first stage cuts its release with. */
38
+ export function releaseCutHook(spec) {
39
+ if (spec.release?.cut === false)
40
+ return undefined;
41
+ const bin = spec.release?.bin ?? ["chant"];
42
+ return { name: "release-cut", command: [...bin, "release", "cut", spec.release?.label ?? "auto", "--yes"] };
43
+ }
44
+ /**
45
+ * The hook a stage publishes its release artifacts with (#5356), run after
46
+ * the release cut on the first stage's last wave: `chant pipeline artifacts
47
+ * publish --stage <stage>`, through the cut's bin. Undefined when the stage
48
+ * publishes nothing or the merge cuts no release.
49
+ */
50
+ export function artifactsPublishHook(spec, stage) {
51
+ if (spec.release?.cut === false)
52
+ return undefined;
53
+ const declared = spec.stages.find((s) => s.name === stage)?.publish;
54
+ if (!declared || Object.keys(declared).length === 0)
55
+ return undefined;
56
+ const bin = spec.release?.bin ?? ["chant"];
57
+ return { name: "artifacts-publish", command: [...bin, "pipeline", "artifacts", "publish", "--stage", stage] };
58
+ }
59
+ function joinHooks(first, then) {
60
+ if (!first)
61
+ return then;
62
+ if (!then)
63
+ return first;
64
+ const both = (k) => {
65
+ const a = (first[k] ?? {});
66
+ const b = (then[k] ?? {});
67
+ const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])];
68
+ return keys.length === 0 ? undefined : Object.fromEntries(keys.map((m) => [m, [...(a[m] ?? []), ...(b[m] ?? [])]]));
69
+ };
70
+ const before = both("before");
71
+ const after = both("after");
72
+ const apply = then.apply ?? first.apply;
73
+ return { ...(before ? { before } : {}), ...(after ? { after } : {}), ...(apply ? { apply } : {}) };
74
+ }
75
+ /**
76
+ * The release names a stage's step records under (#5427), when the pipeline
77
+ * fixes them: a stage with a `step` whose every run target is missing from
78
+ * some other stage names an environment, not a component (a yodel project's
79
+ * `dev` and `staging`), so its records take `release.component` of the
80
+ * defaults, else the pipeline's name, and each stage's records name the same
81
+ * component. Undefined when the defaults name a component or turn the
82
+ * records off, when the stage has no step, or when a target is run by every
83
+ * stage (a root or a stack, which names its own records).
84
+ */
85
+ function stageReleaseNames(spec, stage) {
86
+ const own = spec.defaults?.release;
87
+ if (!spec.defaults?.step || own === false || own?.component !== undefined)
88
+ return undefined;
89
+ const targets = stage.waves.flatMap((w) => (w.runs ?? []).map((r) => r.target));
90
+ if (targets.length === 0 || spec.stages.length < 2)
91
+ return undefined;
92
+ const everywhere = (target) => spec.stages.every((s) => s.waves.some((w) => (w.runs ?? []).some((r) => r.target === target)));
93
+ if (targets.some(everywhere))
94
+ return undefined;
95
+ return { ...(own ?? {}), component: spec.name };
96
+ }
97
+ /**
98
+ * The op-waves spec stage `name` runs: its waves under its gate. The first
99
+ * stage also carries the release cut and the control dispatch, since it is
100
+ * the stage a merge applies. A canary wave with no soak of its own takes
101
+ * the stage's (#5327). A stage whose step's targets name environments
102
+ * records its releases under the pipeline's component (#5427). Throws on a
103
+ * stage the pipeline lacks, or a spec no job could run.
104
+ */
105
+ export function stageWavesSpec(spec, name) {
106
+ const index = spec.stages.findIndex((s) => s.name === name);
107
+ if (index < 0)
108
+ throw new Error(`the pipeline "${spec.name}" has no stage "${name}"; its stages are ${spec.stages.map((s) => s.name).join(", ")}`);
109
+ const stage = spec.stages[index];
110
+ const first = index === 0;
111
+ const defaults = spec.defaults ?? {};
112
+ const gate = stage.gate ?? {};
113
+ const waves = stage.waves.map((w, k) => {
114
+ const tolerance = w.failureTolerance ?? stage.failureTolerance;
115
+ const { failureTolerance: _own, ...rest } = w;
116
+ const wave = {
117
+ ...rest,
118
+ gate: w.gate ?? gate.policy ?? "always",
119
+ ...(w.approval ?? gate.approval ? { approval: w.approval ?? gate.approval } : {}),
120
+ ...(w.environment ?? stage.forgeEnvironment ? { environment: w.environment ?? stage.forgeEnvironment } : {}),
121
+ ...(tolerance !== undefined && tolerance !== 0 ? { failureTolerance: tolerance } : {}),
122
+ // #5327: a canary wave that declares no soak takes the stage's, so a product's waves.canary needs no key of its own.
123
+ ...(w.canary && w.soak === undefined && stage.soak !== undefined ? { soak: structuredClone(stage.soak) } : {}),
124
+ };
125
+ const cut = first && k === stage.waves.length - 1 ? releaseCutHook(spec) : undefined;
126
+ const publish = cut ? artifactsPublishHook(spec, stage.name) : undefined;
127
+ if (cut)
128
+ wave.hooks = joinHooks(wave.hooks, { after: { apply: publish ? [cut, publish] : [cut] } });
129
+ return wave;
130
+ });
131
+ const approvals = gate.quorum !== undefined ? { ...defaults.approvals, quorum: gate.quorum } : defaults.approvals;
132
+ const release = stageReleaseNames(spec, stage);
133
+ const hooks = joinHooks(defaults.hooks, stage.hooks);
134
+ const holds = gate.holds ?? defaults.holds;
135
+ const point = gate.point ?? defaults.point;
136
+ const out = {
137
+ ...defaults,
138
+ name: stageWavesName(spec, stage.name),
139
+ op: defaults.op ?? spec.name,
140
+ labels: { ...defaults.labels, Env: stage.name },
141
+ ...(approvals ? { approvals } : {}),
142
+ ...(release ? { release } : {}),
143
+ ...(hooks ? { hooks } : {}),
144
+ ...(holds ? { holds } : {}),
145
+ ...(point ? { point } : {}),
146
+ ...(first && spec.control ? { control: spec.control } : {}),
147
+ ...(stage.replanDependents ? { replanDependents: [...stage.replanDependents] } : {}),
148
+ waves,
149
+ };
150
+ assertOpWavesSpec(out);
151
+ return out;
152
+ }
153
+ /** The hold or freeze window on `stage` at `now`, or undefined when promotion is open. A hold wins over a window. */
154
+ export function stageHeldAt(stage, now) {
155
+ const hold = stage.hold;
156
+ if (hold === true)
157
+ return { stage: stage.name, kind: "hold", until: null };
158
+ if (hold !== undefined && (hold.until === undefined || Date.parse(hold.until) > now.getTime())) {
159
+ return { stage: stage.name, kind: "hold", until: hold.until ?? null, ...(hold.reason ? { reason: hold.reason } : {}), ...(hold.description ? { description: hold.description } : {}) };
160
+ }
161
+ const windows = (stage.freeze ?? []).filter((w) => Date.parse(w.from) <= now.getTime() && now.getTime() < Date.parse(w.until));
162
+ if (windows.length === 0)
163
+ return undefined;
164
+ // Overlapping windows: the one that ends last says until when.
165
+ const last = windows.reduce((a, b) => (Date.parse(b.until) > Date.parse(a.until) ? b : a));
166
+ return { stage: stage.name, kind: "freeze", until: last.until, ...(last.reason ? { reason: last.reason } : {}) };
167
+ }
168
+ /** The line a held stage's refusal prints: what holds it, and until when. */
169
+ export function stageHeldLine(held) {
170
+ const what = held.kind === "hold" ? `stage "${held.stage}" is held` : `stage "${held.stage}" is in a freeze window`;
171
+ const until = held.until ? ` until ${held.until}` : " until a change to the pipeline lifts the hold";
172
+ const read = held.description ? `. Before it goes on: ${held.description}` : "";
173
+ return `${what}${until}${held.reason ? ` (${held.reason})` : ""}, so nothing is promoted into it${read}`;
174
+ }
@@ -0,0 +1,277 @@
1
+ /**
2
+ * A rollback a stage requests when its verify or its soak fails (#5328).
3
+ *
4
+ * A stage sets `onVerifyFail: "rollback"` in `.chant/pipeline.ts` to opt in.
5
+ * The default, `"hold"`, is what every stage did before: the stage stays as
6
+ * applied, or mixed, and `workspace status` prints the rollback line for a
7
+ * person to run.
8
+ *
9
+ * Two failures count:
10
+ *
11
+ * - verify: a promote into the stage failed at a verify step, as
12
+ * `isVerifyStep` (`../components/verify-step.ts`) names one: a step in a
13
+ * phase named `Verify`, or of a wait-and-verify kind. The agent trigger of
14
+ * #5339 reads a failed verify by the same function. A failed apply is not
15
+ * one, so the stage holds as before;
16
+ * - soak: a check of the stage's soak failed while a promote out of it read
17
+ * the soak (`./soak-gate.ts`).
18
+ *
19
+ * On either, {@link requestStageRollback} writes three things on the stage's
20
+ * ledger (`./stage-ledger.ts`): a `failed` line, with each member's state
21
+ * ({@link memberStateOf}); then a `rollback-requested` line bound to the
22
+ * stage's previous release, naming the members the rollback restores and
23
+ * linking the failure; and the pending fact of gate `<stage>-rollback`
24
+ * under the pipeline's op, bound to that release's digest. It sends a
25
+ * `rollback-requested` notify event, and the command exits 3.
26
+ *
27
+ * The request applies nothing. `chant components rollback <stage>
28
+ * --requested` reads it, passes it through {@link requestedRollbackGate}
29
+ * and only then runs `components rollback --release` for the members it
30
+ * names. That gate always waits for a person: a stage gate policy of `never`
31
+ * lets a promote through, and never a requested rollback. It counts the
32
+ * stage gate's approval rules and approval mode, only approvals given since
33
+ * the request, and the run spends the approval it used. The `rolled-back`
34
+ * line links the rollback to its request and its failure.
35
+ *
36
+ * No rollback is requested, and the line `rollback-held` says why, when the
37
+ * stage ran no earlier release, when the newest earlier one is revoked or
38
+ * no longer kept, or when no member left applied ran that release.
39
+ *
40
+ * The `failed` line names no rollback, so a separate reader of failures, such
41
+ * as an agent trigger, reads it on its own; whatever that reader opens, the
42
+ * request stays on the ledger until the rollback runs.
43
+ */
44
+ import type { DriverComponentResult } from "../components/driver.js";
45
+ import type { ReleaseRecord } from "../lifecycle/release-ledger.js";
46
+ import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
47
+ import { type GateLedgerPort } from "../op/gate.js";
48
+ import { type NotifyConfig, type NotifyEvent } from "../notify.js";
49
+ import type { PipelineGateProof } from "./promote.js";
50
+ import type { PipelineOnVerifyFail, PipelineSpec, PipelineStage } from "./spec.js";
51
+ import type { StageLedgerPort, StageMemberState, StageMemberStateName, StagePauseLine, StageRelease } from "./stage-ledger.js";
52
+ /** How long a rollback request's pending fact stands. The request itself stays on the stage's ledger until the rollback runs. */
53
+ export declare const ROLLBACK_REQUEST_EXPIRY = "30d";
54
+ /** What a stage does when its verify or soak fails: its `onVerifyFail`, else `"hold"`. */
55
+ export declare function stageOnVerifyFail(stage: Pick<PipelineStage, "onVerifyFail"> | undefined): PipelineOnVerifyFail;
56
+ /** The gate a stage's requested rollback passes, under the pipeline's op. */
57
+ export declare function stageRollbackGate(stage: string): string;
58
+ /** The command that carries out a stage's requested rollback once its gate passes. */
59
+ export declare function requestedRollbackCommand(stage: string): string;
60
+ /**
61
+ * The state a run left one member in, from its result: `applied` when it
62
+ * deployed; for a failed or gated one, `left-applied` when a step's change
63
+ * stays (a `rollback-opted-out` record, an undo that failed, or a step that
64
+ * ran before a gate stopped it), `rolled-back` when each step that ran was
65
+ * undone, and `not-applied` when nothing of it ran.
66
+ */
67
+ export declare function memberStateOf(result: Pick<DriverComponentResult, "status" | "records"> | undefined): StageMemberStateName;
68
+ /** Each planned member's state after a run, in plan order. */
69
+ export declare function memberStatesOf(members: readonly string[], results: readonly Pick<DriverComponentResult, "component" | "status" | "records">[]): StageMemberState[];
70
+ /**
71
+ * The stage a held promotion's soak failure rolls back, and its members, or
72
+ * undefined when the soak held for its clock or for a check that could not
73
+ * be read (#5328). The stage is the one whose soak held (`heldBy`), which on
74
+ * a later promote can be a canary upstream rather than the stage promoted
75
+ * from or into.
76
+ */
77
+ export declare function soakFailureOf(outcome: {
78
+ passed: boolean;
79
+ decision: {
80
+ holds: readonly {
81
+ reason: string;
82
+ status?: string;
83
+ }[];
84
+ };
85
+ heldBy?: {
86
+ stage: string;
87
+ members: string[];
88
+ };
89
+ }): {
90
+ stage: string;
91
+ members: string[];
92
+ } | undefined;
93
+ /** The lines a failed run's records give, one per failed step: `<member> <phase>/<kind>: <error>`. */
94
+ export declare function failureDetail(results: readonly Pick<DriverComponentResult, "component" | "status" | "records">[]): string[];
95
+ /** What a release check says: whether the release is kept, and the revocation's reason when its commit is revoked. */
96
+ export interface ReleaseCheck {
97
+ kept: boolean;
98
+ revoked: string | null;
99
+ }
100
+ /** The stage's previous release, or why there is none to go back to. */
101
+ export type PreviousRelease = {
102
+ status: "found";
103
+ release: StageRelease;
104
+ } | {
105
+ status: "none";
106
+ } | {
107
+ status: "revoked";
108
+ release: StageRelease;
109
+ reason: string;
110
+ } | {
111
+ status: "not-kept";
112
+ release: StageRelease;
113
+ };
114
+ /**
115
+ * The release the stage ran before the one that failed: the newest release
116
+ * its ledger names outside `exclude`. Unlike `rollbackTarget`, a revoked or
117
+ * no longer kept release is not passed over for an older one; it is the
118
+ * answer, so the hold can say which release it is.
119
+ */
120
+ export declare function previousRelease(input: {
121
+ records: readonly ReleaseRecord[];
122
+ exclude: ReadonlySet<string>;
123
+ check: (releaseDigest: string) => Promise<ReleaseCheck>;
124
+ label?: (releaseDigest: string) => string | null;
125
+ }): Promise<PreviousRelease>;
126
+ /** Why no rollback is requested, as the `rollback-held` line and the promote say it. */
127
+ export declare function heldReason(stage: string, previous: Exclude<PreviousRelease, {
128
+ status: "found";
129
+ }>): string;
130
+ /**
131
+ * Which members a rollback to `to` restores: each member left `applied` or
132
+ * `left-applied` that ran release `to` in the stage. Every other member is
133
+ * listed with why it is not restored.
134
+ */
135
+ export declare function rollbackMembers(states: readonly StageMemberState[], records: readonly ReleaseRecord[], to: StageRelease): StageMemberState[];
136
+ /** The `failed` lines of a stage's ledger, oldest first: what a separate trigger reads. */
137
+ export declare function stageFailures(lines: readonly StagePauseLine[]): StagePauseLine[];
138
+ /**
139
+ * The newest rollback request no `rolled-back` line has answered, or
140
+ * undefined. With `failed`, only a request for that failed release counts.
141
+ */
142
+ export declare function standingRollbackRequest(lines: readonly StagePauseLine[], failed?: string): StagePauseLine | undefined;
143
+ /** One line in the words a person reads: each member and what the rollback does with it. */
144
+ export declare function memberLines(members: readonly StageMemberState[]): string[];
145
+ export interface StageRollbackInput {
146
+ spec: Pick<PipelineSpec, "name" | "stages">;
147
+ stage: string;
148
+ failure: "verify" | "soak";
149
+ /** The release that failed in the stage, or the promotion's digest when it named none. */
150
+ failed: StageRelease;
151
+ /** Each member's state. */
152
+ members: readonly StageMemberState[];
153
+ /** What the failure said, one line each. */
154
+ detail: readonly string[];
155
+ /** The stage's release ledger. */
156
+ records: readonly ReleaseRecord[];
157
+ /** Releases that are not earlier ones: the one that failed. */
158
+ exclude: ReadonlySet<string>;
159
+ check: (releaseDigest: string) => Promise<ReleaseCheck>;
160
+ label?: (releaseDigest: string) => string | null;
161
+ stages: StageLedgerPort;
162
+ gates: GateLedgerPort;
163
+ /** Who the lines name: the promote's actor. */
164
+ by: string;
165
+ now: Date;
166
+ gitSha?: string;
167
+ /** Where the request's notice goes. Absent: none is sent. */
168
+ notify?: {
169
+ config: NotifyConfig | undefined;
170
+ source: string;
171
+ send?: (config: NotifyConfig | undefined, event: NotifyEvent) => Promise<unknown>;
172
+ };
173
+ }
174
+ /** What {@link requestStageRollback} did. */
175
+ export type StageRollbackOutcome =
176
+ /** The stage holds, as it always did: its `onVerifyFail` is `hold`. Nothing was written. */
177
+ {
178
+ status: "hold";
179
+ }
180
+ /** A request for this failed release stands already; nothing new was written. */
181
+ | {
182
+ status: "standing";
183
+ request: StagePauseLine;
184
+ exitCode: 3;
185
+ lines: string[];
186
+ hint: string;
187
+ } | {
188
+ status: "requested";
189
+ request: StagePauseLine;
190
+ failure: StagePauseLine;
191
+ exitCode: 3;
192
+ lines: string[];
193
+ hint: string;
194
+ }
195
+ /** No rollback could be requested; the stage holds, and `reason` says why. */
196
+ | {
197
+ status: "held";
198
+ failure: StagePauseLine;
199
+ reason: string;
200
+ lines: string[];
201
+ };
202
+ /** Write a stage's failure and its rollback request. See the module comment. */
203
+ export declare function requestStageRollback(input: StageRollbackInput): Promise<StageRollbackOutcome>;
204
+ /** What {@link requestedRollbackGate} decided. */
205
+ export type RequestedRollbackGate = {
206
+ passed: true;
207
+ approval: GateResolutionRecord;
208
+ lines: string[];
209
+ } | {
210
+ passed: false;
211
+ exitCode: 3;
212
+ code: "pipeline-rollback-waiting";
213
+ message: string;
214
+ hint: string;
215
+ };
216
+ /**
217
+ * The gate a requested rollback passes before it applies: gate
218
+ * `<stage>-rollback` under the pipeline's op, bound to the release it goes
219
+ * back to, with the stage gate's approval rules and mode. It always waits
220
+ * for a person, whatever the stage's gate policy, and counts only an
221
+ * approval given since the request and not spent by an earlier rollback.
222
+ */
223
+ export declare function requestedRollbackGate(input: {
224
+ spec: Pick<PipelineSpec, "name" | "stages">;
225
+ stage: string;
226
+ request: StagePauseLine;
227
+ port: GateLedgerPort;
228
+ proof?: PipelineGateProof;
229
+ now: Date;
230
+ gitSha?: string;
231
+ }): Promise<RequestedRollbackGate>;
232
+ /** A step a stage applies, as the build check reads it: the member's component and phase, or the pipeline's `defaults.step`. */
233
+ export interface RollbackStepView {
234
+ /** Where the step sits: `component "api" step deploy/terraform-apply`, or `defaults.step`. */
235
+ where: string;
236
+ kind: string;
237
+ }
238
+ /** What the build check reads of a step's capability. */
239
+ export interface RollbackCapabilityView {
240
+ /** Whether the capability answers `releaseInputs`, so a release records the files the step applies. */
241
+ releaseInputs: boolean;
242
+ /** Its `rollbackPolicy`, else `native` when it has a `rollback` and `none-by-design` when not, as COMP003 derives it. */
243
+ rollbackPolicy: "native" | "none-by-design" | "needs-opt-out";
244
+ }
245
+ /** The step kind whose change no earlier release takes back. */
246
+ export declare const MIGRATION_STEP_KIND = "sql-migrate";
247
+ /**
248
+ * Why `chant build` refuses `onVerifyFail: "rollback"` on a stage (#5328),
249
+ * one line per step; empty when nothing refuses. A requested rollback is
250
+ * `components rollback --release`, which applies the files an earlier
251
+ * release recorded, so each step the stage applies has to be one that
252
+ * applying an earlier release restores:
253
+ *
254
+ * - a `sql-migrate` step is refused: a migration that ran stays run;
255
+ * - a step whose kind no registered capability has is refused, since
256
+ * nothing says what it does;
257
+ * - a step whose capability changes nothing (`none-by-design`) passes;
258
+ * - any other step passes only when its capability answers `releaseInputs`,
259
+ * as `terraform-apply` and `pulumi-up` do. Without it, the release records
260
+ * none of its files and the rollback has nothing of it to apply.
261
+ *
262
+ * A step's `noRollback` decides nothing here: it says the capability does not
263
+ * undo a failed apply, and the rollback is a forward apply of the earlier
264
+ * release, not an undo.
265
+ */
266
+ export declare function verifyRollbackProblems(input: {
267
+ spec: Pick<PipelineSpec, "stages">;
268
+ steps: readonly RollbackStepView[];
269
+ capability: (kind: string) => RollbackCapabilityView | undefined;
270
+ }): string[];
271
+ /** The line a requested rollback that ran writes: the members it restored, linked to its request and failure. */
272
+ export declare function rolledBackLine(input: {
273
+ request: StagePauseLine;
274
+ by: string;
275
+ approval: GateResolutionRecord;
276
+ now: Date;
277
+ }): StagePauseLine;