@intentius/chant 0.124.109 → 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 (338) 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/replan.d.ts +54 -0
  80. package/dist/cli/handlers/replan.js +177 -0
  81. package/dist/cli/handlers/run-generate.d.ts +5 -0
  82. package/dist/cli/handlers/run-generate.js +31 -4
  83. package/dist/cli/handlers/run-wave.js +15 -2
  84. package/dist/cli/handlers/run.js +4 -2
  85. package/dist/cli/handlers/stage.d.ts +35 -0
  86. package/dist/cli/handlers/stage.js +90 -0
  87. package/dist/cli/lsp/server.js +4 -0
  88. package/dist/cli/main.js +88 -8
  89. package/dist/cli/parse-args.js +35 -2
  90. package/dist/cli/registry.d.ts +12 -0
  91. package/dist/components/auto-release.d.ts +2 -0
  92. package/dist/components/auto-release.js +1 -0
  93. package/dist/components/capability.d.ts +40 -0
  94. package/dist/components/cli-support.d.ts +21 -1
  95. package/dist/components/cli-support.js +28 -6
  96. package/dist/components/component.d.ts +23 -4
  97. package/dist/components/component.schema.json +28 -0
  98. package/dist/components/declared-reads.d.ts +44 -4
  99. package/dist/components/declared-reads.js +80 -3
  100. package/dist/components/discover.d.ts +8 -0
  101. package/dist/components/discover.js +1 -1
  102. package/dist/components/driver.d.ts +13 -0
  103. package/dist/components/driver.js +23 -2
  104. package/dist/components/environment-sets.d.ts +229 -0
  105. package/dist/components/environment-sets.js +338 -0
  106. package/dist/components/fan-out-canary.d.ts +47 -0
  107. package/dist/components/fan-out-canary.js +58 -0
  108. package/dist/components/fan-out-run.d.ts +17 -0
  109. package/dist/components/fan-out-run.js +14 -1
  110. package/dist/components/fan-out-support.d.ts +7 -0
  111. package/dist/components/fan-out-support.js +1 -1
  112. package/dist/components/groups.d.ts +8 -1
  113. package/dist/components/groups.js +19 -1
  114. package/dist/components/index.d.ts +5 -2
  115. package/dist/components/index.js +4 -1
  116. package/dist/components/pr-cost.d.ts +28 -0
  117. package/dist/components/pr-cost.js +53 -0
  118. package/dist/components/pr-pipeline.d.ts +33 -0
  119. package/dist/components/pr-pipeline.js +32 -5
  120. package/dist/components/pr-policy.d.ts +33 -2
  121. package/dist/components/pr-policy.js +5 -2
  122. package/dist/components/pr-risk.d.ts +42 -0
  123. package/dist/components/pr-risk.js +74 -0
  124. package/dist/components/product-pipeline.d.ts +43 -0
  125. package/dist/components/product-pipeline.js +67 -1
  126. package/dist/components/promote.d.ts +6 -0
  127. package/dist/components/promote.js +13 -0
  128. package/dist/components/release-compile.js +3 -1
  129. package/dist/components/release-gate.d.ts +6 -1
  130. package/dist/components/release-gate.js +10 -2
  131. package/dist/components/step-environments.d.ts +236 -0
  132. package/dist/components/step-environments.js +392 -0
  133. package/dist/components/upstream-replan.d.ts +201 -0
  134. package/dist/components/upstream-replan.js +249 -0
  135. package/dist/components/verify-step.d.ts +30 -0
  136. package/dist/components/verify-step.js +27 -0
  137. package/dist/components/wave-plan.js +6 -2
  138. package/dist/config-environments.d.ts +4 -2
  139. package/dist/control/dispatch.d.ts +15 -0
  140. package/dist/control/dispatch.js +28 -4
  141. package/dist/cost-estimate.d.ts +188 -0
  142. package/dist/cost-estimate.js +363 -0
  143. package/dist/drift-record.d.ts +36 -0
  144. package/dist/drift-record.js +44 -0
  145. package/dist/engine-facts.d.ts +105 -0
  146. package/dist/engine-facts.js +111 -0
  147. package/dist/exit-codes.d.ts +4 -3
  148. package/dist/exit-codes.js +4 -3
  149. package/dist/flag-params.d.ts +2 -2
  150. package/dist/flag-params.js +9 -4
  151. package/dist/floor-table.data.js +53 -0
  152. package/dist/forge-token-vars.d.ts +12 -0
  153. package/dist/forge-token-vars.js +25 -0
  154. package/dist/gate-decision.d.ts +3 -1
  155. package/dist/gate-decision.js +3 -1
  156. package/dist/gated-waves.d.ts +2 -0
  157. package/dist/gated-waves.js +1 -0
  158. package/dist/graph-ir.d.ts +30 -0
  159. package/dist/graph-ir.js +33 -1
  160. package/dist/graph-refs.d.ts +26 -0
  161. package/dist/graph-refs.js +34 -3
  162. package/dist/graph-schema/graph.schema.json +136 -0
  163. package/dist/health.d.ts +65 -0
  164. package/dist/health.js +62 -0
  165. package/dist/lexicon.d.ts +188 -1
  166. package/dist/lifecycle/disruption.d.ts +14 -1
  167. package/dist/lifecycle/disruption.js +5 -1
  168. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  169. package/dist/lifecycle/gate-change-set.js +2 -1
  170. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  171. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  172. package/dist/lifecycle/gate-rejection.js +93 -0
  173. package/dist/lifecycle/gate-seal.d.ts +3 -3
  174. package/dist/lifecycle/gate-seal.js +5 -5
  175. package/dist/lifecycle/observe.d.ts +17 -0
  176. package/dist/lifecycle/observe.js +10 -1
  177. package/dist/lifecycle/release-cut.js +4 -0
  178. package/dist/lifecycle/release-ledger.d.ts +8 -0
  179. package/dist/lifecycle/release-risk.d.ts +137 -0
  180. package/dist/lifecycle/release-risk.js +214 -0
  181. package/dist/lifecycle/release-store.d.ts +9 -0
  182. package/dist/lifecycle/release-store.js +4 -0
  183. package/dist/lifecycle/stage-log.d.ts +85 -0
  184. package/dist/lifecycle/stage-log.js +141 -0
  185. package/dist/lint/canary-checks.d.ts +31 -0
  186. package/dist/lint/canary-checks.js +45 -0
  187. package/dist/lint/rule.d.ts +1 -0
  188. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  190. package/dist/lint/rules/index.d.ts +1 -0
  191. package/dist/lint/rules/index.js +3 -0
  192. package/dist/notify-relay-repo.d.ts +54 -0
  193. package/dist/notify-relay-repo.js +84 -0
  194. package/dist/notify-relay.d.ts +53 -3
  195. package/dist/notify-relay.js +96 -3
  196. package/dist/notify.d.ts +57 -1
  197. package/dist/notify.js +7 -1
  198. package/dist/notify.schema.json +61 -3
  199. package/dist/observation.d.ts +34 -0
  200. package/dist/observation.js +14 -1
  201. package/dist/op/activities/review-agent.d.ts +39 -2
  202. package/dist/op/activities/review-agent.js +88 -5
  203. package/dist/op/agent-permit.d.ts +88 -0
  204. package/dist/op/agent-permit.js +97 -0
  205. package/dist/op/gate-approval-base.d.ts +8 -0
  206. package/dist/op/gate-approval-base.js +9 -0
  207. package/dist/op/gate-approval.d.ts +30 -1
  208. package/dist/op/gate-approval.js +23 -2
  209. package/dist/op/gate-quorum.d.ts +114 -8
  210. package/dist/op/gate-quorum.js +198 -21
  211. package/dist/op/gate-reject.d.ts +79 -0
  212. package/dist/op/gate-reject.js +96 -0
  213. package/dist/op/gate-summary.js +1 -1
  214. package/dist/op/gate.d.ts +28 -3
  215. package/dist/op/gate.js +55 -13
  216. package/dist/op/generate-pipeline.d.ts +15 -1
  217. package/dist/op/generate-pipeline.js +32 -5
  218. package/dist/op/index.d.ts +11 -6
  219. package/dist/op/index.js +10 -5
  220. package/dist/op/local-executor.d.ts +2 -0
  221. package/dist/op/local-executor.js +23 -4
  222. package/dist/op/op-waves-after-plan.d.ts +23 -0
  223. package/dist/op/op-waves-after-plan.js +12 -1
  224. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  225. package/dist/op/op-waves-capability-spec.js +46 -6
  226. package/dist/op/op-waves-capability.d.ts +21 -13
  227. package/dist/op/op-waves-capability.js +22 -59
  228. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  229. package/dist/op/op-waves-environment-sets.js +82 -0
  230. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  231. package/dist/op/op-waves-quorum-warnings.js +90 -0
  232. package/dist/op/op-waves-release-port.d.ts +7 -0
  233. package/dist/op/op-waves-release-port.js +15 -3
  234. package/dist/op/op-waves-release.d.ts +15 -0
  235. package/dist/op/op-waves-release.js +15 -0
  236. package/dist/op/op-waves-run.d.ts +37 -3
  237. package/dist/op/op-waves-run.js +141 -18
  238. package/dist/op/op-waves-soak.d.ts +57 -0
  239. package/dist/op/op-waves-soak.js +111 -0
  240. package/dist/op/op-waves-split.d.ts +4 -0
  241. package/dist/op/op-waves-split.js +4 -0
  242. package/dist/op/op-waves.d.ts +67 -4
  243. package/dist/op/op-waves.js +71 -3
  244. package/dist/pipeline/agent-ajv.d.ts +4 -0
  245. package/dist/pipeline/agent-ajv.js +14 -0
  246. package/dist/pipeline/agent-steps.d.ts +329 -0
  247. package/dist/pipeline/agent-steps.js +602 -0
  248. package/dist/pipeline/artifacts.d.ts +264 -0
  249. package/dist/pipeline/artifacts.js +425 -0
  250. package/dist/pipeline/diff.d.ts +45 -0
  251. package/dist/pipeline/diff.js +177 -0
  252. package/dist/pipeline/fold.d.ts +43 -0
  253. package/dist/pipeline/fold.js +140 -0
  254. package/dist/pipeline/generate.d.ts +52 -0
  255. package/dist/pipeline/generate.js +120 -0
  256. package/dist/pipeline/product.d.ts +225 -0
  257. package/dist/pipeline/product.js +257 -0
  258. package/dist/pipeline/promote.d.ts +404 -0
  259. package/dist/pipeline/promote.js +694 -0
  260. package/dist/pipeline/read.d.ts +37 -0
  261. package/dist/pipeline/read.js +58 -0
  262. package/dist/pipeline/rendered.d.ts +25 -0
  263. package/dist/pipeline/rendered.js +53 -0
  264. package/dist/pipeline/soak-checks.d.ts +80 -0
  265. package/dist/pipeline/soak-checks.js +254 -0
  266. package/dist/pipeline/soak-gate.d.ts +97 -0
  267. package/dist/pipeline/soak-gate.js +176 -0
  268. package/dist/pipeline/soak-sources.d.ts +17 -0
  269. package/dist/pipeline/soak-sources.js +42 -0
  270. package/dist/pipeline/soak.d.ts +260 -0
  271. package/dist/pipeline/soak.js +378 -0
  272. package/dist/pipeline/spec.d.ts +724 -0
  273. package/dist/pipeline/spec.js +567 -0
  274. package/dist/pipeline/stage-ledger.d.ts +187 -0
  275. package/dist/pipeline/stage-ledger.js +185 -0
  276. package/dist/pipeline/stage-waves.d.ts +114 -0
  277. package/dist/pipeline/stage-waves.js +161 -0
  278. package/dist/pipeline/stages.d.ts +64 -0
  279. package/dist/pipeline/stages.js +174 -0
  280. package/dist/pipeline/verify-rollback.d.ts +277 -0
  281. package/dist/pipeline/verify-rollback.js +393 -0
  282. package/dist/pipeline.d.ts +142 -0
  283. package/dist/pipeline.js +143 -0
  284. package/dist/pr-loop.d.ts +22 -0
  285. package/dist/pr-loop.js +8 -0
  286. package/dist/pr-plan-note.d.ts +15 -1
  287. package/dist/pr-plan-note.js +8 -0
  288. package/dist/pr-post.d.ts +31 -0
  289. package/dist/pr-post.js +89 -0
  290. package/dist/release-floors.d.ts +1 -1
  291. package/dist/release-floors.js +1 -1
  292. package/dist/report-store/audit.schema.json +50 -0
  293. package/dist/report-store/dora.schema.json +331 -0
  294. package/dist/report-store/estate.schema.json +96 -0
  295. package/dist/report-store/run.schema.json +14 -0
  296. package/dist/report-store.d.ts +151 -0
  297. package/dist/report-store.js +344 -0
  298. package/dist/run-event.d.ts +7 -2
  299. package/dist/wave-runtime.mjs +458 -404
  300. package/dist/workspace/catalog-edges.js +3 -3
  301. package/dist/workspace/change-set.schema.json +4 -0
  302. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  303. package/dist/workspace/ci-cloud-identity.js +30 -0
  304. package/dist/workspace/ci-run.js +17 -2
  305. package/dist/workspace/ci-secrets.d.ts +3 -1
  306. package/dist/workspace/ci-secrets.js +7 -1
  307. package/dist/workspace/compose-graph.d.ts +1 -1
  308. package/dist/workspace/compose-graph.js +3 -1
  309. package/dist/workspace/declaration.d.ts +27 -0
  310. package/dist/workspace/declaration.js +35 -0
  311. package/dist/workspace/declaration.schema.json +56 -0
  312. package/dist/workspace/graph-cli.js +26 -0
  313. package/dist/workspace/graph.schema.json +5 -1
  314. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  315. package/dist/workspace/identity-gate-rule.js +2 -2
  316. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  317. package/dist/workspace/identity-reject-rule.js +24 -0
  318. package/dist/workspace/identity.d.ts +3 -0
  319. package/dist/workspace/identity.js +2 -1
  320. package/dist/workspace/nested-graph.js +2 -0
  321. package/dist/workspace/pr-report.schema.json +65 -0
  322. package/dist/workspace/promotion-order.d.ts +19 -4
  323. package/dist/workspace/promotion-order.js +26 -4
  324. package/dist/workspace/release-train.d.ts +14 -0
  325. package/dist/workspace/release-train.js +32 -0
  326. package/dist/workspace/run-event.schema.json +2 -2
  327. package/dist/workspace/stack-read-edges.d.ts +19 -0
  328. package/dist/workspace/stack-read-edges.js +54 -0
  329. package/dist/workspace/status-gates.d.ts +51 -1
  330. package/dist/workspace/status-gates.js +60 -0
  331. package/dist/workspace/status-stages.d.ts +223 -0
  332. package/dist/workspace/status-stages.js +279 -0
  333. package/dist/workspace/status.d.ts +45 -1
  334. package/dist/workspace/status.js +109 -5
  335. package/dist/workspace/status.schema.json +283 -2
  336. package/dist/workspace/trust/seal.d.ts +7 -0
  337. package/dist/workspace/trust/seal.js +9 -0
  338. package/package.json +5 -1
@@ -0,0 +1,378 @@
1
+ /**
2
+ * Soak (#5326): checks that must keep passing for a while after a stage or
3
+ * a wave applied, before the next stage's gate or the next wave opens.
4
+ *
5
+ * No process waits. A promote into the next stage, or the next wave's job,
6
+ * reads the soak when it runs: when the clock started (the last apply the
7
+ * ledger recorded), how long the soak is, and what each check says now. A
8
+ * soak that is not over records its pending fact and exits 3 with the time
9
+ * left; a later run, by hand or from the pipeline's scheduled re-run, reads
10
+ * the clock and the checks again.
11
+ *
12
+ * The decision here is pure: {@link decideSoak} takes the soak, the members
13
+ * that applied and when, the time, a person's early end, the state the last
14
+ * run left, and a reader for the checks. `./soak-checks.ts` holds the
15
+ * readers chant ships, and `./soak-gate.ts` the part a promote and a wave
16
+ * job run, which reads and writes the gate ledger.
17
+ *
18
+ * A soak only holds. It adds a wait in front of a gate and never stands in
19
+ * for an approval: once it passes, or a person ends it, the next stage's own
20
+ * gate still decides.
21
+ *
22
+ * The rules, in the order they apply:
23
+ *
24
+ * 1. No soak: nothing is held.
25
+ * 2. A person ended the soak through its gate: nothing is held, whatever
26
+ * else is true.
27
+ * 3. An apply with no usable time: held, since no clock can be counted.
28
+ * 4. Each `restart` check is read on every run. One that fails holds; once
29
+ * it passes again the clock starts over at that run.
30
+ * 5. Before the clock is up, held for the time left. A `hold` check is not
31
+ * read yet: its failure would keep the elapsed time and hold all the same.
32
+ * 6. Once the clock is up, each `hold` check is read. One that fails holds
33
+ * until it passes or a person ends the soak; the elapsed time is kept.
34
+ * 7. Otherwise the soak passed.
35
+ *
36
+ * `unknown` never counts as passing: a check that cannot be read holds.
37
+ */
38
+ import { createHash } from "node:crypto";
39
+ /** The check kinds, in the order the per-member ones report. */
40
+ export const SOAK_CHECK_KINDS = ["drift", "apply", "policy", "http", "prometheus", "cloudwatch-alarm", "command", "health"];
41
+ /** The kinds read once per member that applied, over that member's targets. The rest are read once per soak. */
42
+ export const SOAK_MEMBER_KINDS = ["drift", "apply", "policy"];
43
+ const DURATION = /^(0|\d+[mhd])$/;
44
+ const UNIT_MS = { m: 60000, h: 3600000, d: 86400000 };
45
+ /** A soak duration in milliseconds, or undefined when it is not `<n>m`, `<n>h`, `<n>d` or `0`. */
46
+ export function soakDurationMs(value) {
47
+ if (!DURATION.test(value))
48
+ return undefined;
49
+ if (value === "0")
50
+ return 0;
51
+ return Number(value.slice(0, -1)) * UNIT_MS[value.slice(-1)];
52
+ }
53
+ /**
54
+ * Whether `glob` names `name`: `*` matches within one `/` segment, `**`
55
+ * across them (and `a/**\/b` also matches `a/b`), `?` one character other
56
+ * than `/`. A glob with no wildcard matches only the same name.
57
+ */
58
+ export function soakGlobMatch(glob, name) {
59
+ if (!/[*?]/.test(glob))
60
+ return glob === name;
61
+ let re = "";
62
+ for (let i = 0; i < glob.length; i++) {
63
+ const c = glob[i];
64
+ if (c === "*" && glob[i + 1] === "*") {
65
+ if (glob[i + 2] === "/") {
66
+ re += "(?:.*/)?";
67
+ i += 2;
68
+ }
69
+ else {
70
+ re += ".*";
71
+ i += 1;
72
+ }
73
+ }
74
+ else if (c === "*")
75
+ re += "[^/]*";
76
+ else if (c === "?")
77
+ re += "[^/]";
78
+ else
79
+ re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
80
+ }
81
+ return new RegExp(`^${re}$`).test(name);
82
+ }
83
+ /** The rule for a member known by `names` (its name, and any other spelling of it): the first override whose glob names one of them, else the soak's own. */
84
+ export function soakRuleFor(soak, names) {
85
+ const hit = (soak.overrides ?? []).find((o) => o.members.some((g) => names.some((n) => soakGlobMatch(g, n))));
86
+ const duration = hit?.duration ?? soak.duration;
87
+ return { duration, durationMs: soakDurationMs(duration) ?? 0, checks: [...(hit?.checks ?? soak.checks ?? [])] };
88
+ }
89
+ /** What a failure of `check` does. */
90
+ export function soakOnFail(check) {
91
+ return check.onFail ?? "restart";
92
+ }
93
+ /** The check's name: its own, else its kind and a short digest of its settings, so the same check keeps its name from run to run. */
94
+ export function soakCheckName(check) {
95
+ if (check.name)
96
+ return check.name;
97
+ const { name: _n, onFail: _o, kind, ...settings } = check;
98
+ if (Object.keys(settings).length === 0)
99
+ return kind;
100
+ const text = JSON.stringify(settings, Object.keys(settings).sort());
101
+ return `${kind}-${createHash("sha256").update(text).digest("hex").slice(0, 8)}`;
102
+ }
103
+ // ---------------------------------------------------------------------------
104
+ // Checking a declaration
105
+ const isMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
106
+ const COMMON_KEYS = ["kind", "name", "onFail"];
107
+ const CHECK_KEYS = {
108
+ http: ["url", "status", "body", "timeoutSeconds"],
109
+ prometheus: ["url", "query", "max", "min", "timeoutSeconds"],
110
+ "cloudwatch-alarm": ["alarm", "region"],
111
+ command: ["command", "timeoutSeconds"],
112
+ health: ["covers"],
113
+ drift: [],
114
+ apply: [],
115
+ policy: [],
116
+ };
117
+ function checkProblems(check, at) {
118
+ if (!isMap(check) || typeof check.kind !== "string" || !SOAK_CHECK_KINDS.includes(check.kind)) {
119
+ return [`${at} must be a check: { "kind": ${SOAK_CHECK_KINDS.join(", ")}, ... }`];
120
+ }
121
+ const kind = check.kind;
122
+ const keys = [...COMMON_KEYS, ...CHECK_KEYS[kind]];
123
+ const out = Object.keys(check).filter((k) => !keys.includes(k)).map((k) => `${at} has an unknown key "${k}"; a ${kind} check takes ${keys.join(", ")}`);
124
+ if (check.name !== undefined && (typeof check.name !== "string" || check.name.trim() === ""))
125
+ out.push(`${at}.name must be text`);
126
+ if (check.onFail !== undefined && check.onFail !== "restart" && check.onFail !== "hold")
127
+ out.push(`${at}.onFail is restart or hold`);
128
+ const text = (k) => typeof check[k] === "string" && check[k].trim() !== "";
129
+ const seconds = check.timeoutSeconds;
130
+ if (seconds !== undefined && !(typeof seconds === "number" && Number.isInteger(seconds) && seconds > 0))
131
+ out.push(`${at}.timeoutSeconds must be a whole number above 0`);
132
+ switch (kind) {
133
+ case "http": {
134
+ if (!text("url") || !/^https?:\/\//.test(check.url))
135
+ out.push(`${at}.url must be an http or https URL`);
136
+ const s = check.status;
137
+ const okStatus = (n) => typeof n === "number" && Number.isInteger(n) && n >= 100 && n <= 599;
138
+ if (s !== undefined && !(okStatus(s) || (Array.isArray(s) && s.length > 0 && s.every(okStatus))))
139
+ out.push(`${at}.status must be an HTTP status or a list of them`);
140
+ if (check.body !== undefined) {
141
+ if (typeof check.body !== "string")
142
+ out.push(`${at}.body must be a regular expression`);
143
+ else {
144
+ try {
145
+ new RegExp(check.body);
146
+ }
147
+ catch {
148
+ out.push(`${at}.body is not a regular expression`);
149
+ }
150
+ }
151
+ }
152
+ break;
153
+ }
154
+ case "prometheus":
155
+ if (!text("url") || !/^https?:\/\//.test(check.url))
156
+ out.push(`${at}.url must be the server's http or https URL`);
157
+ if (!text("query"))
158
+ out.push(`${at}.query must be a PromQL query`);
159
+ for (const k of ["max", "min"])
160
+ if (check[k] !== undefined && typeof check[k] !== "number")
161
+ out.push(`${at}.${k} must be a number`);
162
+ if (check.max === undefined && check.min === undefined)
163
+ out.push(`${at} sets max, min, or both: the threshold the query's samples are held to`);
164
+ break;
165
+ case "cloudwatch-alarm":
166
+ if (!text("alarm"))
167
+ out.push(`${at}.alarm must name a CloudWatch alarm`);
168
+ if (check.region !== undefined && !text("region"))
169
+ out.push(`${at}.region must name a region`);
170
+ break;
171
+ case "command":
172
+ if (!Array.isArray(check.command) || check.command.length === 0 || check.command.some((w) => typeof w !== "string" || w === ""))
173
+ out.push(`${at}.command must be a list of words, such as ["./smoke.sh", "prod"]`);
174
+ break;
175
+ case "health":
176
+ if (check.covers !== undefined && !(Array.isArray(check.covers) && check.covers.length > 0 && check.covers.every((g) => typeof g === "string" && g.trim() !== "")))
177
+ out.push(`${at}.covers must list resource names, types or globs`);
178
+ break;
179
+ }
180
+ return out;
181
+ }
182
+ function checksProblems(checks, at) {
183
+ if (checks === undefined)
184
+ return [];
185
+ if (!Array.isArray(checks))
186
+ return [`${at} must be a list of checks`];
187
+ const out = checks.flatMap((c, i) => checkProblems(c, `${at}[${i}]`));
188
+ const names = new Map();
189
+ checks.forEach((c, i) => {
190
+ if (out.length > 0 || !isMap(c))
191
+ return;
192
+ const name = soakCheckName(c);
193
+ if (names.has(name))
194
+ out.push(`${at}[${i}] has the same name as ${at}[${names.get(name)}] ("${name}"); give one a name`);
195
+ else
196
+ names.set(name, i);
197
+ });
198
+ return out;
199
+ }
200
+ /** Everything wrong with a soak, one line each; empty when it reads. */
201
+ export function soakProblems(soak, where) {
202
+ if (soak === undefined)
203
+ return [];
204
+ if (!isMap(soak))
205
+ return [`${where}.soak must be { "duration", "checks"?, "overrides"? }`];
206
+ const at = `${where}.soak`;
207
+ const out = Object.keys(soak).filter((k) => !["duration", "checks", "overrides"].includes(k)).map((k) => `${at} has an unknown key "${k}"; it takes duration, checks, overrides`);
208
+ if (typeof soak.duration !== "string" || soakDurationMs(soak.duration) === undefined)
209
+ out.push(`${at}.duration must be a duration in minutes, hours or days, such as 24h, or 0`);
210
+ out.push(...checksProblems(soak.checks, `${at}.checks`));
211
+ if (soak.overrides !== undefined) {
212
+ if (!Array.isArray(soak.overrides))
213
+ out.push(`${at}.overrides must be a list of { "members", "duration"?, "checks"? }`);
214
+ else
215
+ soak.overrides.forEach((o, i) => {
216
+ const oat = `${at}.overrides[${i}]`;
217
+ if (!isMap(o)) {
218
+ out.push(`${oat} must be { "members", "duration"?, "checks"? }`);
219
+ return;
220
+ }
221
+ out.push(...Object.keys(o).filter((k) => !["members", "duration", "checks"].includes(k)).map((k) => `${oat} has an unknown key "${k}"; it takes members, duration, checks`));
222
+ if (!Array.isArray(o.members) || o.members.length === 0 || o.members.some((g) => typeof g !== "string" || g.trim() === ""))
223
+ out.push(`${oat}.members must list member names or globs`);
224
+ if (o.duration !== undefined && (typeof o.duration !== "string" || soakDurationMs(o.duration) === undefined))
225
+ out.push(`${oat}.duration must be a duration in minutes, hours or days, such as 24h, or 0`);
226
+ out.push(...checksProblems(o.checks, `${oat}.checks`));
227
+ });
228
+ }
229
+ return out;
230
+ }
231
+ const iso = (ms) => new Date(ms).toISOString();
232
+ /** Decide a soak at `input.now`. See the module comment for the order. */
233
+ export async function decideSoak(input) {
234
+ const { soak, subjects, now } = input;
235
+ if (!soak)
236
+ return { outcome: "release", via: "no-soak", rules: [], clockStart: null, due: null, holds: [], state: {} };
237
+ const rules = subjects.map((s) => ({ member: s.member, rule: soakRuleFor(soak, [s.member, ...(s.names ?? [])]) }));
238
+ if (input.ended)
239
+ return { outcome: "release", via: "ended", rules, clockStart: null, due: null, holds: [], endedBy: { ...input.ended }, state: {} };
240
+ const unknown = subjects.filter((s) => s.appliedAt === undefined || Number.isNaN(Date.parse(s.appliedAt)));
241
+ if (unknown.length > 0 || subjects.length === 0) {
242
+ return { outcome: "hold", rules, clockStart: null, due: null, holds: [{ reason: "clock-unknown", members: unknown.map((s) => s.member) }], state: { ...input.state } };
243
+ }
244
+ const applied = Math.max(...subjects.map((s) => Date.parse(s.appliedAt)));
245
+ const prior = input.state ?? {};
246
+ const restarted = prior.restartedAt !== undefined && !Number.isNaN(Date.parse(prior.restartedAt)) ? Date.parse(prior.restartedAt) : undefined;
247
+ let start = restarted !== undefined && restarted > applied ? restarted : applied;
248
+ const items = [];
249
+ const shared = new Map();
250
+ for (const [i, s] of subjects.entries()) {
251
+ const rule = rules[i].rule;
252
+ const own = rule.checks.filter((c) => SOAK_MEMBER_KINDS.includes(c.kind)).sort((a, b) => SOAK_CHECK_KINDS.indexOf(a.kind) - SOAK_CHECK_KINDS.indexOf(b.kind));
253
+ for (const c of own)
254
+ items.push({ check: c, name: soakCheckName(c), subject: s, durationMs: rule.durationMs });
255
+ for (const c of rule.checks.filter((c) => !SOAK_MEMBER_KINDS.includes(c.kind))) {
256
+ const name = soakCheckName(c);
257
+ const had = shared.get(name);
258
+ if (had)
259
+ had.durationMs = Math.max(had.durationMs, rule.durationMs);
260
+ else
261
+ shared.set(name, { check: c, name, durationMs: rule.durationMs });
262
+ }
263
+ }
264
+ items.push(...shared.values());
265
+ const read = async (item) => {
266
+ try {
267
+ return await input.read(item.check, {
268
+ environment: input.environment,
269
+ ...(item.subject ? { member: item.subject.member } : {}),
270
+ targets: item.subject ? [...item.subject.targets] : subjects.flatMap((s) => s.targets),
271
+ since: iso(start),
272
+ now,
273
+ });
274
+ }
275
+ catch (err) {
276
+ return { status: "unknown", detail: `the check could not be read: ${err instanceof Error ? err.message : String(err)}` };
277
+ }
278
+ };
279
+ const holdOf = (item, r) => ({
280
+ reason: "check",
281
+ check: item.name,
282
+ kind: item.check.kind,
283
+ onFail: soakOnFail(item.check),
284
+ status: r.status === "passed" ? "failed" : r.status,
285
+ ...(item.subject ? { member: item.subject.member } : {}),
286
+ ...(item.subject ? { targets: r.targets ?? [...item.subject.targets] } : {}),
287
+ detail: r.detail,
288
+ });
289
+ // 4. Restart checks, on every run.
290
+ const failing = new Set();
291
+ const restartHolds = [];
292
+ let passedAgain = false;
293
+ for (const item of items.filter((x) => soakOnFail(x.check) === "restart")) {
294
+ const r = await read(item);
295
+ const key = item.subject ? `${item.name}@${item.subject.member}` : item.name;
296
+ if (r.status === "passed") {
297
+ if ((prior.failing ?? []).includes(key))
298
+ passedAgain = true;
299
+ continue;
300
+ }
301
+ failing.add(key);
302
+ restartHolds.push(holdOf(item, r));
303
+ }
304
+ const state = { ...(prior.restartedAt ? { restartedAt: prior.restartedAt } : {}) };
305
+ if (restartHolds.length === 0 && passedAgain) {
306
+ // Every restart check passes again: the clock starts over now.
307
+ start = Math.max(start, now.getTime());
308
+ state.restartedAt = iso(start);
309
+ }
310
+ const longest = Math.max(0, ...rules.map((r) => r.rule.durationMs));
311
+ const due = start + longest;
312
+ const times = { clockStart: iso(start), due: iso(due) };
313
+ const holds = [];
314
+ if (now.getTime() < due)
315
+ holds.push({ reason: "time", due: iso(due), leftMs: due - now.getTime() });
316
+ holds.push(...restartHolds);
317
+ // 6. Hold checks, once the clock is up for their member.
318
+ for (const item of items.filter((x) => soakOnFail(x.check) === "hold")) {
319
+ if (now.getTime() < start + item.durationMs)
320
+ continue;
321
+ const r = await read(item);
322
+ if (r.status === "passed")
323
+ continue;
324
+ failing.add(item.subject ? `${item.name}@${item.subject.member}` : item.name);
325
+ holds.push(holdOf(item, r));
326
+ }
327
+ if (failing.size > 0)
328
+ state.failing = [...failing].sort();
329
+ return holds.length === 0
330
+ ? { outcome: "release", via: "soaked", rules, ...times, holds: [], state }
331
+ : { outcome: "hold", rules, ...times, holds, state };
332
+ }
333
+ // ---------------------------------------------------------------------------
334
+ // Words
335
+ /** A span of milliseconds as a person reads it: `2h 5m`, `3d 4h`, `40s`. */
336
+ export function soakSpan(ms) {
337
+ const s = Math.max(0, Math.ceil(ms / 1000));
338
+ const d = Math.floor(s / 86400);
339
+ const h = Math.floor((s % 86400) / 3600);
340
+ const m = Math.floor((s % 3600) / 60);
341
+ if (d > 0)
342
+ return h > 0 ? `${d}d ${h}h` : `${d}d`;
343
+ if (h > 0)
344
+ return m > 0 ? `${h}h ${m}m` : `${h}h`;
345
+ if (m > 0)
346
+ return `${m}m`;
347
+ return `${s}s`;
348
+ }
349
+ /** One line per hold: what the next stage or wave waits for. */
350
+ export function soakHoldLines(decision) {
351
+ return decision.holds.map((h) => {
352
+ if (h.reason === "time")
353
+ return `${soakSpan(h.leftMs)} left, until ${h.due}`;
354
+ if (h.reason === "clock-unknown")
355
+ return `the ledger gives no apply time for ${h.members.length > 0 ? h.members.join(", ") : "anything that applied"}, so the soak's clock cannot be counted`;
356
+ const where = h.member ? ` on ${h.member}${h.targets && h.targets.length > 0 ? ` (${h.targets.join(", ")})` : ""}` : "";
357
+ const then = h.onFail === "restart" ? "the soak starts over once it passes" : "held until it passes, with the elapsed time kept";
358
+ return `check ${h.check}${where} ${h.status === "unknown" ? "could not be read" : "failed"}: ${h.detail}; ${then}`;
359
+ });
360
+ }
361
+ /**
362
+ * How many checks a soak reads, its own and its overrides' (#5327). A
363
+ * canary with none holds nothing but a timer, so a pipeline refuses it and
364
+ * existing config warns.
365
+ */
366
+ export function soakCheckCount(soak) {
367
+ if (!soak)
368
+ return 0;
369
+ const count = (checks) => (Array.isArray(checks) ? checks.length : 0);
370
+ const overrides = Array.isArray(soak.overrides) ? soak.overrides : [];
371
+ return count(soak.checks) + overrides.reduce((n, o) => n + (typeof o === "object" && o !== null ? count(o.checks) : 0), 0);
372
+ }
373
+ /** How a soak reads in the plan note and the docs: its duration and its checks. */
374
+ export function soakSummary(soak) {
375
+ const checks = (soak.checks ?? []).map((c) => `${soakCheckName(c)} (${soakOnFail(c)})`);
376
+ const overrides = soak.overrides?.length ? `; ${soak.overrides.length} override${soak.overrides.length === 1 ? "" : "s"} by member` : "";
377
+ return `${soak.duration === "0" ? "no wait" : soak.duration}${checks.length > 0 ? `, while ${checks.join(", ")} pass${checks.length === 1 ? "es" : ""}` : ""}${overrides}`;
378
+ }