@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
@@ -24,7 +24,7 @@
24
24
  */
25
25
  /** Every stage slot, in the order {@link assertProductWords} reports them. */
26
26
  export const CI_PRODUCT_STAGES = ["plan", "apply", "record", "check", "drift", "lock", "approval", "control"];
27
- export const CI_PRODUCT_COMMANDS = ["plan", "apply", "lock", "unlock", "agent", "action", "commit"];
27
+ export const CI_PRODUCT_COMMANDS = ["plan", "apply", "lock", "unlock", "agent", "action", "commit", "reject"];
28
28
  export const CI_PRODUCT_APPLY_MODES = ["on-merge", "release", "before-merge"];
29
29
  /** The reply slots, for checking a product's words. */
30
30
  export const CI_PRODUCT_COMMENT_REPLIES = ["plan", "apply", "lock", "unlock", "action", "agent", "fork", "member"];
@@ -34,6 +34,8 @@ export const CHANT_NOTIFY_WAVE_TEMPLATE = "wave {k} ({name}) of {spec}";
34
34
  export const CHANT_APPROVE_TEMPLATE = "chant approve {op} {gate} --plan {digest} --approver {approver} {sign}";
35
35
  /** chant's own override line. */
36
36
  export const CHANT_OVERRIDE_TEMPLATE = 'chant approve {op} {target} --rule {rule} --reason "<why>" {sign}';
37
+ /** chant's own reject line (#5354). */
38
+ export const CHANT_REJECT_TEMPLATE = "chant reject {op} {gate} --plan {digest} --reason {reason} {sign}";
37
39
  /** chant's words: what every slot defaults to. */
38
40
  export const CHANT_WORDS = Object.freeze({
39
41
  product: "chant",
@@ -44,6 +46,7 @@ export const CHANT_WORDS = Object.freeze({
44
46
  aliases: [],
45
47
  approve: CHANT_APPROVE_TEMPLATE,
46
48
  override: CHANT_OVERRIDE_TEMPLATE,
49
+ reject: CHANT_REJECT_TEMPLATE,
47
50
  gateName: "{gate}-wave-{k}",
48
51
  prGate: "pr-apply",
49
52
  approval: "pull-request",
@@ -65,6 +68,7 @@ export function resolveProductWords(input = {}) {
65
68
  // A product's own lines default to chant's grammar under its own name.
66
69
  approve: input.approve ?? (own ? `${product} approve {op} {gate} --plan {digest} {sign}` : CHANT_APPROVE_TEMPLATE),
67
70
  override: input.override ?? (own ? `${product} override {target} --rule {rule} --reason {reason} {sign}` : CHANT_OVERRIDE_TEMPLATE),
71
+ reject: input.reject ?? (own ? `${product} reject {op} {gate} --plan {digest} --reason {reason} {sign}` : CHANT_REJECT_TEMPLATE),
68
72
  ...(input.op !== undefined ? { op: input.op } : {}),
69
73
  gateName: input.gateName ?? CHANT_WORDS.gateName,
70
74
  prGate: input.prGate ?? CHANT_WORDS.prGate,
@@ -153,7 +157,7 @@ export function productWordsProblems(words, options = {}) {
153
157
  if (slot !== "member" || (m[1] !== "member" && m[1] !== "members"))
154
158
  problems.push(`replies.${slot} names {${m[1]}}, which chant does not fill`);
155
159
  }
156
- for (const [where, template] of [["approve", words.approve], ["override", words.override]]) {
160
+ for (const [where, template] of [["approve", words.approve], ["override", words.override], ["reject", words.reject ?? CHANT_REJECT_TEMPLATE]]) {
157
161
  for (const m of template.matchAll(/\{([^}]*)\}/g))
158
162
  if (!PLACEHOLDERS.has(m[1]))
159
163
  problems.push(`${where} names {${m[1]}}, which chant does not fill`);
@@ -280,6 +284,18 @@ export function overrideLine(words, input) {
280
284
  sign: input.sign ? "--sign" : "",
281
285
  });
282
286
  }
287
+ /** The command a reviewer runs to reject a release at a gate (#5354): the product's reject template filled. */
288
+ export function rejectLine(words, input) {
289
+ return fill(words.reject ?? CHANT_REJECT_TEMPLATE, {
290
+ op: input.op,
291
+ gate: input.gate,
292
+ digest: input.digest,
293
+ reason: input.reason ?? "<why>",
294
+ approver: "<you>",
295
+ sign: input.sign === false ? "" : "--sign",
296
+ target: input.target ?? "",
297
+ });
298
+ }
283
299
  /** The typed word for one of chant's commands: the first `commands` entry that maps onto it. */
284
300
  export function commandWord(words, command) {
285
301
  return Object.entries(words.commands).find(([, c]) => c === command)?.[0];
@@ -406,7 +422,12 @@ export function parseProductComment(words, body, env = {}, commitArgs = {}, opti
406
422
  if (command === undefined) {
407
423
  return {
408
424
  kind: "refused",
409
- reason: NEVER.has(typed) ? `a comment never runs \`${typed}\`: ${words.product} re-plans, and runs what an approval covers, on request and nothing more` : `the commands are ${known}`,
425
+ reason: typed === "reject"
426
+ ? // #5354: words that map no comment command onto reject leave rejections to the reject line.
427
+ `${words.product}'s comments take no reject command: run \`${rejectLine(words, { op: words.op ?? "<op>", gate: "<gate>", digest: "<digest>" })}\``
428
+ : NEVER.has(typed)
429
+ ? `a comment never runs \`${typed}\`: ${words.product} re-plans, and runs what an approval covers, on request and nothing more`
430
+ : `the commands are ${known}`,
410
431
  };
411
432
  }
412
433
  const line = `\`${prefix} ${typed}\``;
@@ -451,6 +472,27 @@ export function parseProductComment(words, body, env = {}, commitArgs = {}, opti
451
472
  return { kind: "refused", reason: "an action is an action address or name, with no spaces or shell characters" };
452
473
  return { kind: "action", member, address };
453
474
  }
475
+ case "reject": {
476
+ // #5354: the reason is the rest of the line; `--stage <stage>` first names the stage when several wait.
477
+ let rest = text.slice(`${prefix} ${typed}`.length).trim();
478
+ let stage;
479
+ const flag = /^--stage[ \t]+(\S+)[ \t]*/.exec(rest);
480
+ if (flag) {
481
+ if (!NAME.test(flag[1]))
482
+ return { kind: "refused", reason: "a stage is a name of lowercase letters, digits, - and _" };
483
+ stage = flag[1];
484
+ rest = rest.slice(flag[0].length).trim();
485
+ }
486
+ else if (rest.startsWith("-"))
487
+ return { kind: "refused", reason: `${line} takes \`--stage <stage>\` and a reason, and no other flag` };
488
+ if (rest === "")
489
+ return { kind: "refused", reason: `${line} needs a reason after it, on the same line: \`${prefix} ${typed} [--stage <stage>] <reason>\`` };
490
+ if (rest.length > PRODUCT_COMMENT_ASK_MAX)
491
+ return { kind: "refused", reason: `a reason is at most ${PRODUCT_COMMENT_ASK_MAX} characters` };
492
+ if (/[\u0000-\u001f\u007f\u2028\u2029]/.test(rest))
493
+ return { kind: "refused", reason: "a reason is plain text on one line" };
494
+ return { kind: "reject", ...(stage !== undefined ? { stage } : {}), reason: rest };
495
+ }
454
496
  case "apply": {
455
497
  if (parts.length === 2)
456
498
  return { kind: "apply" };
@@ -536,3 +578,1348 @@ export function productActionFromEnv(words, env) {
536
578
  return { ...parsed, from: "dispatch" };
537
579
  return parsed?.kind === "refused" ? parsed : { kind: "refused", reason: `a dispatched action names a ${words.noun[0]} and an action` };
538
580
  }
581
+ const SECRET_NAME = "^[A-Za-z_][A-Za-z0-9_]*$";
582
+ const DURATION = "^\\d+[mhd]$";
583
+ const STORAGE_URL = "^(s3|gs|az|file)://\\S+$";
584
+ const CRON = "^\\S+(\\s+\\S+){4}$";
585
+ /** The CI products this vocabulary was settled across. */
586
+ export const CI_PRODUCTS = ["terragucci", "plywood", "sql-yodeler"];
587
+ /** The vocabulary, in page order. */
588
+ export const PRODUCT_CONFIG_WORDS = /* @__PURE__ */ Object.freeze([
589
+ // Environments
590
+ {
591
+ key: "environments.<name>",
592
+ concept: "an environment's settings, keyed by the environment's name",
593
+ section: "environments",
594
+ value: "a map per environment",
595
+ chant: "the names in `environments` of the member's `chant.config.ts`",
596
+ products: ["terragucci", "sql-yodeler"],
597
+ },
598
+ {
599
+ key: "forge_environments.<glob>",
600
+ concept: "the forge deployment environment the jobs of the members a glob matches run in",
601
+ section: "environments",
602
+ value: "a name, or `{ name, url }`",
603
+ chant: "a wave's `environment` in the op-waves spec",
604
+ also: ["environments.<name>.forge_environment"],
605
+ products: [],
606
+ aliases: [{ product: "plywood", key: "environments", shape: "forge-environments" }],
607
+ },
608
+ {
609
+ key: "gate",
610
+ concept: "when a wave waits for an approval",
611
+ section: "approval",
612
+ values: ["always", "on-destructive", "never"],
613
+ chant: "a wave's `gate` (`OpWaveGatePolicy`)",
614
+ also: ["environments.<name>.gate", "stacks.<name>.gate", "waves[].gate"],
615
+ products: ["terragucci", "plywood", "sql-yodeler"],
616
+ aliases: [{ product: "terragucci", value: ["on-destroy", "on-destructive"] }],
617
+ },
618
+ // Stage and release
619
+ {
620
+ key: "promotion",
621
+ concept: "the order a release moves through the environments, first to last",
622
+ section: "stage",
623
+ value: "a list of environment names",
624
+ chant: "`environments` in the member's `chant.config.ts`, in order, which `promotionOrder` reads and `chant components promote` follows; with a pipeline, the order of its stages",
625
+ products: [],
626
+ },
627
+ // #5324: the pipeline's stage keys, written into `.chant/pipeline.ts` by `pipelineFromConfig`.
628
+ {
629
+ key: "environments.<name>.hold",
630
+ concept: "a manual hold: no release is promoted into the stage",
631
+ section: "stage",
632
+ value: "`true`, or a map with `reason` and `until`, an ISO 8601 time",
633
+ chant: "a stage's `hold` in `.chant/pipeline.ts`",
634
+ products: [],
635
+ },
636
+ {
637
+ key: "environments.<name>.freeze",
638
+ concept: "the freeze windows in which no release is promoted into the stage",
639
+ section: "stage",
640
+ value: "a list of maps with `from`, `until` (ISO 8601 times) and `reason`",
641
+ chant: "a stage's `freeze` in `.chant/pipeline.ts`",
642
+ products: [],
643
+ },
644
+ // #5355: a stage's urgent rule and its pause after a rollback.
645
+ {
646
+ key: "environments.<name>.urgent.role",
647
+ concept: "the role whose one proven approval passes the stage's gate on an urgent promote",
648
+ section: "stage",
649
+ value: "a role name from `.chant/trust.json`",
650
+ chant: "a stage gate's `urgent.role` in `.chant/pipeline.ts`, which `chant components promote --urgent` passes",
651
+ products: [],
652
+ },
653
+ {
654
+ key: "environments.<name>.pause_after_rollback",
655
+ concept: "a rollback of the stage pauses it until it is resumed",
656
+ section: "stage",
657
+ value: "true or false",
658
+ chant: "a stage's `pauseAfterRollback` in `.chant/pipeline.ts`",
659
+ products: [],
660
+ },
661
+ // #5421: the commands a stage runs around its waves.
662
+ {
663
+ key: "environments.<name>.hooks.<when>",
664
+ concept: "the commands a stage runs around its waves at one moment: before anything reads live state, before or after the plan, after the gate decides, before or after the apply",
665
+ section: "stage",
666
+ value: "a list of hooks, each a map with `command` (a list of arguments), `name`, `on_failure` (`fail` or `approve`), `per_run` and `targets`; `<when>` is `before-observe`, `before-plan`, `after-plan`, `after-gate`, `before-apply` or `after-apply`",
667
+ chant: "a stage's `hooks` in `.chant/pipeline.ts`: `before.observe`, `before.plan`, `after.plan`, `after.gate`, `before.apply` and `after.apply`, run after the pipeline's own hooks",
668
+ products: [],
669
+ },
670
+ // #5328: what a stage does when its verify or soak fails.
671
+ {
672
+ key: "environments.<name>.on_verify_fail",
673
+ concept: "a stage's answer to a failed verify after a promote or a failed check of its soak: hold as applied, or request the rollback to its previous release, which waits for an approval",
674
+ section: "stage",
675
+ values: ["hold", "rollback"],
676
+ chant: "a stage's `onVerifyFail` in `.chant/pipeline.ts`; `hold` when unset",
677
+ products: [],
678
+ },
679
+ {
680
+ key: "environments.<name>.failure_tolerance",
681
+ concept: "the failed runs a wave of many targets lets through before the stage stops",
682
+ section: "stage",
683
+ pattern: "^(100|[1-9]?[0-9])%$",
684
+ value: "a whole number of runs, or a share of the wave's runs such as `10%`",
685
+ chant: "a stage's `failureTolerance` in `.chant/pipeline.ts`, a wave's `failureTolerance`",
686
+ products: [],
687
+ },
688
+ // #5353: stages that follow several stages, and stages that take one release at a time.
689
+ {
690
+ key: "environments.<name>.after",
691
+ concept: "the stages a release applies in before the stage opens for it",
692
+ section: "stage",
693
+ value: "a list of environment names; the stage before it in `promotion` when unset",
694
+ chant: "a stage's `after` in `.chant/pipeline.ts`",
695
+ products: [],
696
+ },
697
+ {
698
+ key: "environments.<name>.queue",
699
+ concept: "how a stage takes releases: one at a time, a newer release waiting replacing an older one",
700
+ section: "stage",
701
+ values: ["replace"],
702
+ chant: "a stage's `queue` in `.chant/pipeline.ts`",
703
+ products: [],
704
+ },
705
+ {
706
+ key: "environments.<name>.approval_rules",
707
+ concept: "the approval rules of one stage, in place of `approval_rules`",
708
+ section: "stage",
709
+ value: "the rules `approval_rules` takes",
710
+ chant: "a stage gate's `quorum` in `.chant/pipeline.ts`",
711
+ products: [],
712
+ },
713
+ {
714
+ key: "release.cut",
715
+ concept: "a merge cuts a release once the first stage applied",
716
+ section: "stage",
717
+ value: "`true` or `false`; `true` when the product writes a pipeline",
718
+ chant: "`release.cut` in `.chant/pipeline.ts`",
719
+ products: [],
720
+ },
721
+ {
722
+ key: "release.label",
723
+ concept: "the label the merge's release is cut with",
724
+ section: "stage",
725
+ value: "a label, or `auto` for the next version",
726
+ chant: "`release.label` in `.chant/pipeline.ts`, `chant release cut <label>`",
727
+ products: [],
728
+ },
729
+ {
730
+ key: "environments.<name>.targets.<member>",
731
+ concept: "the target a member applies in one environment: a stack, a root, or the step's inputs there",
732
+ section: "stage",
733
+ value: "a target name or path, or a map of the step's inputs",
734
+ chant: "the member's step's `environments.<name>` entry, which core merges over the step's input for the run's environment",
735
+ products: [],
736
+ },
737
+ {
738
+ key: "environments.<name>.config.<variable>",
739
+ concept: "a plain value the stage's jobs get as a variable in one environment",
740
+ section: "stage",
741
+ value: "a string",
742
+ chant: "`EnvironmentSets.environments.<name>.config`, which `resolveEnvironmentSet` resolves for the stage's environment",
743
+ also: ["config_sets.<set>.config.<variable>"],
744
+ products: [],
745
+ },
746
+ {
747
+ key: "environments.<name>.secrets.<variable>",
748
+ concept: "a secret the stage's jobs get as a variable in one environment, named by where it is kept",
749
+ section: "stage",
750
+ pattern: SECRET_NAME,
751
+ value: "a forge secret's name, or a map with one of `forge_secret`, `aws_secrets_manager`, `gcp_secret_manager`, `azure_key_vault`",
752
+ chant: "`EnvironmentSets.environments.<name>.secrets`",
753
+ also: ["config_sets.<set>.secrets.<variable>"],
754
+ products: [],
755
+ },
756
+ {
757
+ key: "environments.<name>.secrets.<variable>.forge_secret",
758
+ concept: "the forge secret a set's secret is kept in",
759
+ section: "stage",
760
+ pattern: SECRET_NAME,
761
+ chant: "`forgeSecret` of an `EnvironmentSecretRef`",
762
+ also: ["config_sets.<set>.secrets.<variable>.forge_secret"],
763
+ products: [],
764
+ },
765
+ {
766
+ key: "environments.<name>.imports",
767
+ concept: "the shared sets an environment's set takes first, in order",
768
+ section: "stage",
769
+ value: "a list of `config_sets` names",
770
+ chant: "`EnvironmentSet.imports`",
771
+ also: ["config_sets.<set>.imports"],
772
+ products: [],
773
+ },
774
+ {
775
+ key: "config_sets.<set>",
776
+ concept: "a shared set of config and secrets that environments import",
777
+ section: "stage",
778
+ value: "a map of `config`, `secrets` and `imports`",
779
+ chant: "`EnvironmentSets.configSets`",
780
+ products: [],
781
+ },
782
+ // #5345: plan a member's dependents again when an output they read changes after its apply.
783
+ {
784
+ key: "replan_dependents",
785
+ concept: "the members whose dependents are planned again when an output they read changes after an apply; the plan waits at its gate",
786
+ section: "stage",
787
+ value: "a list of member names or globs",
788
+ chant: "`replanDependents` in `.chant/pipeline.ts` (a stage's, else `defaults`), which `chant components replan` reads",
789
+ also: ["environments.<name>.replan_dependents"],
790
+ products: [],
791
+ },
792
+ // #5356: release artifacts, values a stage publishes for the release it applied, read by later stages and other repos.
793
+ {
794
+ key: "environments.<name>.publish.<artifact>",
795
+ concept: "a release artifact the stage publishes once it applied, kept with the release digest",
796
+ section: "stage",
797
+ value: "a map with `member` and `output` (a member's output), or with `secret` (where a secret is kept, as `environments.<name>.secrets.<variable>` takes it)",
798
+ chant: "a stage's `publish` in `.chant/pipeline.ts`, recorded on `<stage>/artifacts.jsonl`",
799
+ products: [],
800
+ },
801
+ {
802
+ key: "environments.<name>.publish.<artifact>.secret.forge_secret",
803
+ concept: "the forge secret a secret artifact names; the artifact holds the name, never the secret",
804
+ section: "stage",
805
+ pattern: SECRET_NAME,
806
+ chant: "`forgeSecret` of the `EnvironmentSecretRef` in a stage's `publish`",
807
+ products: [],
808
+ },
809
+ {
810
+ key: "environments.<name>.reads.<variable>",
811
+ concept: "an artifact of an earlier stage that the stage's deploy gets in a variable, from the release it takes",
812
+ section: "stage",
813
+ value: "a map with `stage` (an earlier stage) and `artifact` (a name that stage publishes)",
814
+ chant: "a stage's `reads` in `.chant/pipeline.ts`",
815
+ products: [],
816
+ },
817
+ {
818
+ key: "environments.<name>.agent_steps.<step>",
819
+ concept: "an agent step of the stage: a model's reading of the release it takes, with an answer of a declared shape, which approves nothing and applies nothing",
820
+ section: "stage",
821
+ value: "a map with `prompt`, `schema` and `reads`",
822
+ chant: "a stage's `agentSteps` in `.chant/pipeline.ts` (#5358)",
823
+ products: [],
824
+ },
825
+ {
826
+ key: "environments.<name>.agent_steps.<step>.prompt",
827
+ concept: "what the agent step's model is asked",
828
+ section: "stage",
829
+ value: "text, at most 4000 characters",
830
+ chant: "`prompt` of a stage's agent step",
831
+ products: [],
832
+ },
833
+ {
834
+ key: "environments.<name>.agent_steps.<step>.reads.<input>",
835
+ concept: "what the agent step reads, by the name its prompt shows it under: an artifact an earlier stage published for the same release, or the answer of a step before it",
836
+ section: "stage",
837
+ value: "a map with `stage` and `artifact`, or with `step`",
838
+ chant: "`reads` of a stage's agent step",
839
+ products: [],
840
+ },
841
+ {
842
+ key: "environments.<name>.agent_steps.<step>.schema",
843
+ concept: "the JSON Schema the agent step's answer must match; an answer that does not fails the step and holds the stage",
844
+ section: "stage",
845
+ value: "a JSON Schema (2020-12) object",
846
+ chant: "`schema` of a stage's agent step",
847
+ products: [],
848
+ },
849
+ {
850
+ key: "environments.<name>.agent_steps.<step>.command",
851
+ concept: "the model command the agent step runs, prompt on stdin and answer on stdout",
852
+ section: "stage",
853
+ value: "a command line",
854
+ chant: "`command` of a stage's agent step",
855
+ products: [],
856
+ },
857
+ {
858
+ key: "environments.<name>.agent_steps.<step>.key_secret",
859
+ concept: "the secret holding the agent step's model key",
860
+ section: "stage",
861
+ pattern: SECRET_NAME,
862
+ chant: "`keyEnv` of a stage's agent step",
863
+ products: [],
864
+ },
865
+ {
866
+ key: "environments.<name>.agent_steps.<step>.timeout",
867
+ concept: "the minutes the agent step's model command may run",
868
+ section: "stage",
869
+ value: "a whole number from 1 to 360",
870
+ chant: "`timeout` of a stage's agent step",
871
+ products: [],
872
+ },
873
+ {
874
+ key: "environments.<name>.agent_steps.<step>.max_runs",
875
+ concept: "the most runs of the agent step per day",
876
+ section: "stage",
877
+ value: "a whole number",
878
+ chant: "`maxRuns` of a stage's agent step",
879
+ products: [],
880
+ },
881
+ {
882
+ key: "environments.<name>.agent_steps.<step>.max_cost_usd",
883
+ concept: "the most US dollars the agent step's runs may cost per day",
884
+ section: "stage",
885
+ value: "a number above 0",
886
+ chant: "`maxCostUsd` of a stage's agent step",
887
+ products: [],
888
+ },
889
+ {
890
+ key: "control.release",
891
+ concept: "the `<product>-applied` dispatch carries the release digest the applied commit was cut into, so a downstream run reads that release's artifacts",
892
+ section: "stage",
893
+ value: "`true` or `false`",
894
+ chant: "`release` of `ControlSettingsInput`, sent as `CHANT_CONTROL_RELEASE`",
895
+ products: [],
896
+ },
897
+ // #5334: the cost estimate, in the plan note, as the policy's input.cost, and as a hold.
898
+ {
899
+ key: "cost.command",
900
+ concept: "the estimator run over each member's plan document, which prints its monthly cost",
901
+ section: "stage",
902
+ value: "a command naming `{planJson}`, as argv or a command line",
903
+ chant: "`ci.cost.command` and `holds.cost.command`; the presets are `terraformCostHold` and `pulumiCostHold`",
904
+ products: ["terragucci"],
905
+ },
906
+ {
907
+ key: "cost.format",
908
+ concept: "what the estimator prints",
909
+ section: "stage",
910
+ values: ["infracost", "chant"],
911
+ chant: "`ci.cost.format` and `holds.cost.format`",
912
+ products: [],
913
+ },
914
+ {
915
+ key: "cost.currency",
916
+ concept: "the currency the amounts are in",
917
+ section: "stage",
918
+ pattern: "^[A-Z]{3}$",
919
+ value: "a three-letter currency code such as `USD`",
920
+ chant: "`ci.cost.currency` and `holds.cost.currency`",
921
+ products: [],
922
+ },
923
+ {
924
+ key: "cost.approve_above",
925
+ concept: "the monthly change above which a plan needs an approval of its own",
926
+ section: "stage",
927
+ value: "a monthly amount of 0 or more",
928
+ chant: "`ci.cost.approveAbove` and `holds.cost.approveAbove`",
929
+ products: ["terragucci"],
930
+ },
931
+ {
932
+ key: "agent.wave-refused.command",
933
+ concept: "the model command that summarizes a refused wave, prompt on stdin and summary on stdout",
934
+ section: "stage",
935
+ value: "a command line",
936
+ chant: "`WaveSummarySpec.command` (`CHANT_WAVE_SUMMARY_COMMAND`)",
937
+ products: [],
938
+ },
939
+ {
940
+ key: "agent.wave-refused.key_secret",
941
+ concept: "the secret holding the summarizing model's key",
942
+ section: "stage",
943
+ pattern: SECRET_NAME,
944
+ chant: "`WaveSummarySpec.keyEnv` (`CHANT_WAVE_SUMMARY_KEY_ENV`)",
945
+ products: [],
946
+ },
947
+ {
948
+ key: "agent.wave-refused.timeout",
949
+ concept: "the minutes the summary command may run",
950
+ section: "stage",
951
+ value: "a whole number",
952
+ chant: "`WaveSummarySpec.timeout` (`CHANT_WAVE_SUMMARY_TIMEOUT`)",
953
+ products: [],
954
+ },
955
+ {
956
+ key: "agent.wave-refused.max_runs",
957
+ concept: "the most refused-wave summaries per day",
958
+ section: "stage",
959
+ value: "a whole number",
960
+ chant: "`WaveSummarySpec.maxRuns` (`CHANT_WAVE_SUMMARY_MAX_RUNS`)",
961
+ products: [],
962
+ },
963
+ {
964
+ key: "agent.wave-refused.max_cost_usd",
965
+ concept: "the most US dollars the refused-wave summaries may cost per day",
966
+ section: "stage",
967
+ value: "a number above 0",
968
+ chant: "`WaveSummarySpec.maxCostUsd` (`CHANT_WAVE_SUMMARY_MAX_COST_USD`)",
969
+ products: [],
970
+ },
971
+ {
972
+ key: "approval_rules.<rule>.proven",
973
+ concept: "a rule's count met only by approvers a seal or a review proves",
974
+ section: "stage",
975
+ value: "true or false",
976
+ chant: "`proven` of a quorum rule (`GateQuorumRule`, #5349)",
977
+ also: ["approval_rules[].proven"],
978
+ products: [],
979
+ },
980
+ // #5325: the scored change risk, in the plan note, as the policy's input.risk, and as a hold.
981
+ {
982
+ key: "risk.approve_above",
983
+ concept: "the risk score above which a plan needs an approval of its own",
984
+ section: "stage",
985
+ value: "a score from 0 to 1",
986
+ chant: "`ci.risk.approveAbove` and `holds.risk.approveAbove`",
987
+ also: ["environments.<name>.risk.approve_above"],
988
+ products: [],
989
+ },
990
+ {
991
+ key: "risk.questions",
992
+ concept: "the questions the review agent answers from 0 to 1, each a reason in the risk score",
993
+ section: "stage",
994
+ value: "a list of maps with `id`, `text`, `weight` (0 to 1) and `approve_above` (0 to 1)",
995
+ chant: "`ci.risk.questions`",
996
+ products: [],
997
+ },
998
+ {
999
+ key: "environments.<name>.risk.approval_rules",
1000
+ concept: "the approval rules a stage's gate takes on top of its own when the risk is over its score",
1001
+ section: "stage",
1002
+ value: "the rules `approval_rules` takes",
1003
+ chant: "a stage gate's `holds.risk.quorum` in `.chant/pipeline.ts`",
1004
+ products: [],
1005
+ },
1006
+ {
1007
+ key: "approval_rules.<rule>.name",
1008
+ concept: "a rule's or a group's name, shown in its progress line, the plan note and the pending fact on the ledger",
1009
+ section: "stage",
1010
+ pattern: "^[a-z0-9][a-z0-9_-]*$",
1011
+ value: "lowercase letters, digits, `-` and `_`",
1012
+ chant: "`name` of a quorum rule or group (`GateQuorumNode`, #5354)",
1013
+ also: ["approval_rules[].name"],
1014
+ products: [],
1015
+ },
1016
+ {
1017
+ key: "approval_rules.<rule>.all",
1018
+ concept: "a group of rules met when every rule in it is met; groups nest up to three deep",
1019
+ section: "stage",
1020
+ value: "a list or a map of rules and groups",
1021
+ chant: "`{ all: [...] }` in a quorum (`GateQuorumAll`, #5354)",
1022
+ also: ["approval_rules[].all"],
1023
+ products: [],
1024
+ },
1025
+ {
1026
+ key: "approval_rules.<rule>.any",
1027
+ concept: "a group of rules met when one rule in it is met; groups nest up to three deep",
1028
+ section: "stage",
1029
+ value: "a list or a map of rules and groups",
1030
+ chant: "`{ any: [...] }` in a quorum (`GateQuorumAny`, #5354)",
1031
+ also: ["approval_rules[].any"],
1032
+ products: [],
1033
+ },
1034
+ {
1035
+ key: "environments.<name>.hold.description",
1036
+ concept: "what the person who lifts a stage's hold reads first, shown in the plan note, the promote it refuses and `workspace status`",
1037
+ section: "stage",
1038
+ value: "one line of text",
1039
+ chant: "`description` of a stage's `hold` (#5354)",
1040
+ products: [],
1041
+ },
1042
+ // #5327: the canary stage, written into `.chant/pipeline.ts` by `pipelineFromConfig`.
1043
+ {
1044
+ key: "environments.<name>.canary",
1045
+ concept: "the canary stage, whose soak holds every stage after it",
1046
+ section: "stage",
1047
+ value: "`true` or `false`",
1048
+ chant: "a stage's `canary` in `.chant/pipeline.ts`, which takes a `soak` with at least one check",
1049
+ products: [],
1050
+ },
1051
+ // #5326: soak checks that hold the next stage, written into `.chant/pipeline.ts` by `pipelineFromConfig`.
1052
+ {
1053
+ key: "environments.<name>.soak.duration",
1054
+ concept: "how long a stage's soak checks must keep passing after its last apply before a release is promoted into the next stage",
1055
+ section: "stage",
1056
+ pattern: "^(0|\\d+[mhd])$",
1057
+ value: "a duration, or `0` to wait for the checks alone",
1058
+ chant: "a stage's `soak.duration` in `.chant/pipeline.ts`",
1059
+ products: [],
1060
+ },
1061
+ {
1062
+ key: "environments.<name>.soak.checks[].kind",
1063
+ concept: "what one soak check reads",
1064
+ section: "stage",
1065
+ values: ["http", "prometheus", "cloudwatch-alarm", "command", "health", "drift", "apply", "policy"],
1066
+ chant: "a soak check's `kind` (`SoakCheck`), with that kind's settings beside it",
1067
+ products: [],
1068
+ },
1069
+ {
1070
+ key: "environments.<name>.soak.checks[].on_fail",
1071
+ concept: "what a failing soak check does: start the soak over once it passes again, or hold with the elapsed time kept",
1072
+ section: "stage",
1073
+ values: ["restart", "hold"],
1074
+ chant: "a soak check's `onFail`; `restart` when unset",
1075
+ products: [],
1076
+ },
1077
+ {
1078
+ key: "environments.<name>.soak.overrides[].members",
1079
+ concept: "the members an override's duration and checks apply to, in place of the soak's",
1080
+ section: "stage",
1081
+ value: "a list of member names or globs",
1082
+ chant: "a soak override's `members` (`SoakOverride`), with its `duration` and `checks`",
1083
+ products: [],
1084
+ },
1085
+ {
1086
+ key: "recheck.schedule",
1087
+ concept: "how often a promotion a soak holds is tried again",
1088
+ section: "stage",
1089
+ pattern: CRON,
1090
+ value: "a five-field cron line",
1091
+ chant: "`recheck.schedule` in `.chant/pipeline.ts`, which renders a `recheck-<stage>` job per stage running `components promote --pending`",
1092
+ products: [],
1093
+ },
1094
+ // Apply
1095
+ {
1096
+ key: "apply.when",
1097
+ concept: "when a change applies",
1098
+ section: "apply",
1099
+ values: ["merge", "pull-request"],
1100
+ chant: "`ci.workflow`",
1101
+ products: ["terragucci", "plywood"],
1102
+ },
1103
+ {
1104
+ key: "apply.merge",
1105
+ concept: "who merges a pull request that applied before merge",
1106
+ section: "apply",
1107
+ values: ["manual", "auto"],
1108
+ chant: "`chant build --pr-loop --merge`",
1109
+ products: ["terragucci", "plywood"],
1110
+ },
1111
+ {
1112
+ key: "apply.merge_token_env",
1113
+ concept: "the variable holding the token that merges",
1114
+ section: "apply",
1115
+ pattern: SECRET_NAME,
1116
+ chant: "`--merge-token-env`",
1117
+ products: ["terragucci", "plywood"],
1118
+ },
1119
+ {
1120
+ key: "apply.merge_method",
1121
+ concept: "how the merge is made",
1122
+ section: "apply",
1123
+ values: ["merge", "squash", "rebase"],
1124
+ chant: "`--merge-method`",
1125
+ products: ["plywood"],
1126
+ },
1127
+ {
1128
+ key: "apply.requires",
1129
+ concept: "the checks that pass before an apply",
1130
+ section: "apply",
1131
+ value: "a list of check names",
1132
+ chant: "the pull request pipeline's required checks",
1133
+ products: ["terragucci", "plywood"],
1134
+ },
1135
+ {
1136
+ key: "branches.<branch>",
1137
+ concept: "the members a branch applies, by glob",
1138
+ section: "apply",
1139
+ value: "a list of globs",
1140
+ chant: "`ci.branches`",
1141
+ products: ["plywood"],
1142
+ aliases: [{ product: "terragucci", key: "apply.branches" }],
1143
+ },
1144
+ {
1145
+ key: "labels.<label>",
1146
+ concept: "the members a labelled pull request plans, by glob",
1147
+ section: "apply",
1148
+ value: "a list of globs",
1149
+ chant: "`ci.labels`",
1150
+ products: ["plywood"],
1151
+ },
1152
+ {
1153
+ key: "locks.when",
1154
+ concept: "when a pull request takes its locks, in the product's stage words",
1155
+ section: "apply",
1156
+ values: ["plan", "apply", "preview", "up"],
1157
+ chant: "`ci.locks`",
1158
+ products: ["plywood"],
1159
+ aliases: [{ product: "terragucci", key: "locks", shape: "string" }],
1160
+ },
1161
+ {
1162
+ key: "locks.grain",
1163
+ concept: "what one lock covers",
1164
+ section: "apply",
1165
+ values: ["resource", "stack"],
1166
+ chant: "`ci.lockGrain`",
1167
+ products: ["plywood"],
1168
+ },
1169
+ {
1170
+ key: "waves.canary",
1171
+ concept: "the members that apply first, in a wave of their own",
1172
+ section: "apply",
1173
+ value: "a list of member names or globs",
1174
+ chant: "the first wave of the op-waves spec, marked `canary` (#5327): its soak, the environment's soak unless the wave has its own, holds every wave after it",
1175
+ products: ["terragucci", "plywood"],
1176
+ },
1177
+ {
1178
+ key: "waves.after.<name>",
1179
+ concept: "the members one member applies after",
1180
+ section: "apply",
1181
+ value: "a list of member names",
1182
+ chant: "the wave order of the op-waves spec",
1183
+ products: ["terragucci", "plywood"],
1184
+ },
1185
+ {
1186
+ key: "parallelism",
1187
+ concept: "how many members one job applies at once",
1188
+ section: "jobs",
1189
+ value: "a whole number",
1190
+ chant: "the wave job's parallelism",
1191
+ also: ["environments.<name>.parallelism"],
1192
+ products: ["terragucci", "plywood"],
1193
+ },
1194
+ // Approval
1195
+ {
1196
+ key: "approval",
1197
+ concept: "which approvals of a plan count",
1198
+ section: "approval",
1199
+ values: ["ledger", "pr-review", "sealed", "pull-request", "prow-labels"],
1200
+ chant: "a wave's `approval` (`GateApprovalSource`)",
1201
+ also: ["approval.mode", "waves[].approval", "environments.<name>.approval"],
1202
+ products: ["terragucci", "plywood", "sql-yodeler"],
1203
+ },
1204
+ {
1205
+ key: "approval_rules.<rule>.count",
1206
+ concept: "how many distinct people approve",
1207
+ section: "approval",
1208
+ value: "a whole number, at least 1",
1209
+ chant: "`count` of a quorum rule (`GateQuorumRule`)",
1210
+ also: ["approval_rules[].count"],
1211
+ products: ["terragucci"],
1212
+ aliases: [{ product: "plywood", key: "approval_rules.<name>.quorum" }],
1213
+ },
1214
+ {
1215
+ key: "approval_rules.<rule>.roles",
1216
+ concept: "the roles a counted approver holds",
1217
+ section: "approval",
1218
+ value: "a list of role names",
1219
+ chant: "`roles` of a quorum rule",
1220
+ also: ["approval_rules[].roles"],
1221
+ products: ["terragucci", "plywood"],
1222
+ aliases: [{ product: "plywood", key: "approval_rules.<name>.role", shape: "string" }],
1223
+ },
1224
+ {
1225
+ key: "approval_rules.<rule>.not_author",
1226
+ concept: "a counted approver who is not the change's author",
1227
+ section: "approval",
1228
+ value: "true or false",
1229
+ chant: "`notAuthor` of a quorum rule",
1230
+ also: ["approval_rules[].not_author"],
1231
+ products: ["terragucci"],
1232
+ },
1233
+ {
1234
+ key: "policy.engine",
1235
+ concept: "the policy engine",
1236
+ section: "approval",
1237
+ values: ["conftest", "opa"],
1238
+ chant: "`ci.policy`",
1239
+ products: ["terragucci", "plywood"],
1240
+ },
1241
+ {
1242
+ key: "policy.path",
1243
+ concept: "the directory of policy rules in the repository",
1244
+ section: "approval",
1245
+ value: "a path relative to the repository root",
1246
+ chant: "`ci.policy.path`",
1247
+ products: ["terragucci"],
1248
+ aliases: [{ product: "plywood", key: "policy.rego" }],
1249
+ },
1250
+ {
1251
+ key: "policy.namespace",
1252
+ concept: "the policy package the rules sit in",
1253
+ section: "approval",
1254
+ value: "a package name",
1255
+ chant: "`ci.policy`",
1256
+ products: ["terragucci", "plywood"],
1257
+ },
1258
+ {
1259
+ key: "policy.source",
1260
+ concept: "a shared rule set from another repository",
1261
+ section: "approval",
1262
+ value: "a git source at a ref",
1263
+ chant: "`ci.policy.source`",
1264
+ products: ["terragucci", "plywood"],
1265
+ },
1266
+ {
1267
+ key: "evidence.identity",
1268
+ concept: "the keyless identity that signs checks",
1269
+ section: "approval",
1270
+ values: ["oidc"],
1271
+ chant: "`PipelineEvidence.identity`",
1272
+ products: ["terragucci", "plywood", "sql-yodeler"],
1273
+ },
1274
+ {
1275
+ key: "evidence.runner_key_secret",
1276
+ concept: "the secret holding the runner key that signs checks",
1277
+ section: "approval",
1278
+ pattern: SECRET_NAME,
1279
+ chant: "`PipelineEvidence.runnerKeySecret`",
1280
+ products: ["terragucci", "plywood", "sql-yodeler"],
1281
+ },
1282
+ // Respond
1283
+ {
1284
+ key: "respond.wave-refused",
1285
+ concept: "what follows a wave that applied nothing because its plan moved",
1286
+ section: "respond",
1287
+ values: ["diff", "summary", "off"],
1288
+ chant: "`CiResponses[\"wave-refused\"]`",
1289
+ products: ["terragucci"],
1290
+ aliases: [{ product: "plywood", key: "respond.wave_refused" }],
1291
+ },
1292
+ {
1293
+ key: "respond.apply-failed",
1294
+ concept: "what follows a failed apply",
1295
+ section: "respond",
1296
+ values: ["triage", "off"],
1297
+ chant: "`CiResponses[\"apply-failed\"]`",
1298
+ products: ["terragucci"],
1299
+ aliases: [{ product: "plywood", key: "respond.apply_failed" }],
1300
+ },
1301
+ {
1302
+ key: "respond.description",
1303
+ concept: "the pull request description check",
1304
+ section: "respond",
1305
+ values: ["check", "off"],
1306
+ chant: "`CiResponses.description`",
1307
+ products: ["terragucci", "plywood"],
1308
+ },
1309
+ {
1310
+ key: "respond.drift",
1311
+ concept: "what follows a drift the scheduled check finds",
1312
+ section: "respond",
1313
+ values: ["issue", "pull-request", "attribute", "up", "off"],
1314
+ chant: "the scheduled drift Op's response",
1315
+ products: ["terragucci", "plywood"],
1316
+ aliases: [{ product: "plywood", value: ["none", "off"] }],
1317
+ },
1318
+ {
1319
+ key: "drift.schedule",
1320
+ concept: "when the scheduled drift check runs",
1321
+ section: "respond",
1322
+ pattern: CRON,
1323
+ value: "a five-field cron line",
1324
+ chant: "the scheduled drift Op's cron",
1325
+ products: ["plywood"],
1326
+ aliases: [{ product: "terragucci", key: "drift", shape: "string" }],
1327
+ },
1328
+ {
1329
+ key: "decide.backend",
1330
+ concept: "the service that answers a gate's questions",
1331
+ section: "respond",
1332
+ value: "a backend name",
1333
+ chant: "`--decide-backend`",
1334
+ products: ["terragucci", "plywood"],
1335
+ },
1336
+ // Reports
1337
+ {
1338
+ key: "reports.bucket",
1339
+ concept: "where the jobs keep their reports and run index",
1340
+ section: "reports",
1341
+ pattern: STORAGE_URL,
1342
+ value: "an `s3://`, `gs://`, `az://` or `file://` URL",
1343
+ chant: "`ci.reportUrl`",
1344
+ products: ["terragucci"],
1345
+ aliases: [{ product: "plywood", key: "reports.url", shape: "storage-url" }],
1346
+ },
1347
+ {
1348
+ key: "reports.url",
1349
+ concept: "the browser address the reports are read at",
1350
+ section: "reports",
1351
+ pattern: "^https?://\\S+$",
1352
+ value: "an `https://` URL",
1353
+ chant: "the report links in the plan note",
1354
+ products: ["terragucci"],
1355
+ },
1356
+ {
1357
+ key: "telemetry.endpoint",
1358
+ concept: "the OTLP/HTTP base URL traces go to",
1359
+ section: "reports",
1360
+ value: "a URL",
1361
+ chant: "`OTEL_EXPORTER_OTLP_ENDPOINT`",
1362
+ products: ["plywood"],
1363
+ },
1364
+ {
1365
+ key: "telemetry.headers_secret",
1366
+ concept: "the secret holding the OTLP headers",
1367
+ section: "reports",
1368
+ pattern: SECRET_NAME,
1369
+ chant: "`OTEL_EXPORTER_OTLP_HEADERS`",
1370
+ products: ["terragucci"],
1371
+ aliases: [{ product: "plywood", key: "telemetry.headers_env" }],
1372
+ },
1373
+ {
1374
+ key: "telemetry.trace_url",
1375
+ concept: "a link to one trace, with `{trace_id}`",
1376
+ section: "reports",
1377
+ value: "a URL holding `{trace_id}`",
1378
+ chant: "the trace link in the plan note",
1379
+ products: ["terragucci"],
1380
+ },
1381
+ // Identity
1382
+ {
1383
+ key: "identity",
1384
+ concept: "the cloud identities the jobs log in as",
1385
+ section: "identity",
1386
+ value: "a map per cloud, with a role per stage word and per environment",
1387
+ chant: "`ci.identity` and the `ci-login` trade",
1388
+ products: ["plywood"],
1389
+ aliases: [
1390
+ { product: "terragucci", key: "oidc" },
1391
+ { product: "sql-yodeler", key: "ci.login" },
1392
+ ],
1393
+ },
1394
+ {
1395
+ key: "ephemeral",
1396
+ concept: "a copy of the members per open pull request",
1397
+ section: "identity",
1398
+ value: "a map",
1399
+ chant: "`ci.prEnvironment`",
1400
+ products: ["terragucci"],
1401
+ aliases: [{ product: "plywood", key: "review_stacks" }],
1402
+ },
1403
+ {
1404
+ key: "ephemeral.ttl",
1405
+ concept: "how long a pull request's copy lives after its last update",
1406
+ section: "identity",
1407
+ pattern: DURATION,
1408
+ value: "a duration such as `48h`",
1409
+ chant: "`ci.prEnvironment.ttl`",
1410
+ products: ["terragucci"],
1411
+ aliases: [{ product: "plywood", key: "review_stacks.ttl" }],
1412
+ },
1413
+ {
1414
+ key: "forge",
1415
+ concept: "the forge the repository is on",
1416
+ section: "identity",
1417
+ values: ["github", "gitlab", "forgejo"],
1418
+ chant: "`ci.forge`",
1419
+ products: ["terragucci"],
1420
+ aliases: [{ product: "plywood", key: "forge.kind" }],
1421
+ },
1422
+ {
1423
+ key: "forge_url",
1424
+ concept: "the forge's address, for a forge not on https or the default port",
1425
+ section: "identity",
1426
+ value: "a URL",
1427
+ chant: "the forge client's base URL",
1428
+ products: [],
1429
+ aliases: [
1430
+ { product: "terragucci", key: "url" },
1431
+ { product: "plywood", key: "forge.url" },
1432
+ ],
1433
+ },
1434
+ {
1435
+ key: "forges",
1436
+ concept: "the forges the pipelines are rendered for",
1437
+ section: "identity",
1438
+ values: ["github", "gitlab", "forgejo"],
1439
+ chant: "the generators `chant ci` runs",
1440
+ products: ["sql-yodeler"],
1441
+ },
1442
+ // Secrets
1443
+ {
1444
+ key: "token_env",
1445
+ concept: "the variable holding the forge token",
1446
+ section: "secrets",
1447
+ pattern: SECRET_NAME,
1448
+ chant: "the forge client's token",
1449
+ also: ["control.token_env", "agent.token_env"],
1450
+ products: ["terragucci", "plywood"],
1451
+ },
1452
+ {
1453
+ key: "pass.secrets",
1454
+ concept: "the CI secrets the jobs read as variables",
1455
+ section: "secrets",
1456
+ value: "a list of secret names",
1457
+ chant: "the jobs' `env`",
1458
+ products: ["terragucci"],
1459
+ aliases: [{ product: "plywood", key: "pass", shape: "list-or-map" }],
1460
+ },
1461
+ {
1462
+ key: "pass.vars",
1463
+ concept: "the CI variables the jobs read",
1464
+ section: "secrets",
1465
+ value: "a list of variable names",
1466
+ chant: "the jobs' `env`",
1467
+ products: ["terragucci"],
1468
+ },
1469
+ {
1470
+ key: "env.<name>",
1471
+ concept: "plain variables every job sets",
1472
+ section: "secrets",
1473
+ value: "a map of name to value",
1474
+ chant: "the jobs' `env`",
1475
+ products: ["terragucci", "plywood"],
1476
+ },
1477
+ // Notify
1478
+ {
1479
+ key: "notify.slack",
1480
+ concept: "the secret holding a Slack incoming webhook's URL",
1481
+ section: "notify",
1482
+ pattern: SECRET_NAME,
1483
+ chant: "`NotifyConfig.slack`",
1484
+ products: ["terragucci", "sql-yodeler"],
1485
+ aliases: [{ product: "plywood", key: "notify.slack.webhook" }],
1486
+ },
1487
+ {
1488
+ key: "notify.teams",
1489
+ concept: "the secret holding a Microsoft Teams incoming webhook's URL",
1490
+ section: "notify",
1491
+ pattern: SECRET_NAME,
1492
+ chant: "`NotifyConfig.teams`",
1493
+ products: ["terragucci", "sql-yodeler"],
1494
+ aliases: [{ product: "plywood", key: "notify.teams.webhook" }],
1495
+ },
1496
+ {
1497
+ key: "notify.webhook",
1498
+ concept: "the secret holding a generic webhook's URL",
1499
+ section: "notify",
1500
+ pattern: SECRET_NAME,
1501
+ chant: "`NotifyConfig.webhook`",
1502
+ products: ["terragucci", "sql-yodeler"],
1503
+ aliases: [{ product: "plywood", key: "notify.webhook.url" }],
1504
+ },
1505
+ {
1506
+ key: "notify.webhook_key",
1507
+ concept: "the secret holding the key a generic webhook's events are signed with",
1508
+ section: "notify",
1509
+ pattern: SECRET_NAME,
1510
+ chant: "`NotifyConfig.key`",
1511
+ products: ["terragucci"],
1512
+ aliases: [
1513
+ { product: "plywood", key: "notify.webhook.key" },
1514
+ { product: "sql-yodeler", key: "notify.key" },
1515
+ ],
1516
+ },
1517
+ {
1518
+ key: "notify.events",
1519
+ concept: "the events sent",
1520
+ section: "notify",
1521
+ values: ["waiting", "refused", "failed", "drift"],
1522
+ chant: "`NotifyConfig.events`",
1523
+ products: ["sql-yodeler"],
1524
+ aliases: [{ product: "plywood", key: "notify.on" }],
1525
+ },
1526
+ {
1527
+ key: "notify.relay_key",
1528
+ concept: "the secret holding the key the relay checks Approve and Decline with",
1529
+ section: "notify",
1530
+ pattern: SECRET_NAME,
1531
+ chant: "`NotifyConfig.relay`",
1532
+ products: ["terragucci"],
1533
+ aliases: [
1534
+ { product: "plywood", key: "notify.relay" },
1535
+ { product: "sql-yodeler", key: "notify.relay" },
1536
+ ],
1537
+ },
1538
+ {
1539
+ key: "notify.relay_name",
1540
+ concept: "the relay's name as people mention it in Teams",
1541
+ section: "notify",
1542
+ value: "a name",
1543
+ chant: "`NotifyConfig.relayName`",
1544
+ products: ["sql-yodeler"],
1545
+ aliases: [{ product: "terragucci", key: "notify.relay" }],
1546
+ },
1547
+ // Agents
1548
+ {
1549
+ key: "review.key_secret",
1550
+ concept: "the secret holding the reviewing model's key",
1551
+ section: "agents",
1552
+ pattern: SECRET_NAME,
1553
+ chant: "the review agent step's key variable",
1554
+ products: ["terragucci"],
1555
+ aliases: [{ product: "plywood", key: "review.key_env" }],
1556
+ },
1557
+ {
1558
+ key: "review.command",
1559
+ concept: "the model command, prompt on stdin and answer on stdout",
1560
+ section: "agents",
1561
+ value: "a command line",
1562
+ chant: "the review agent step's command",
1563
+ products: ["terragucci", "plywood"],
1564
+ },
1565
+ {
1566
+ key: "review.timeout",
1567
+ concept: "the minutes the review command may run",
1568
+ section: "agents",
1569
+ value: "a whole number",
1570
+ chant: "the review agent step's timeout",
1571
+ products: ["terragucci", "plywood"],
1572
+ },
1573
+ {
1574
+ key: "agent.key_secret",
1575
+ concept: "the secret holding the agent model's key",
1576
+ section: "agents",
1577
+ pattern: SECRET_NAME,
1578
+ chant: "the agent job's key variable",
1579
+ also: ["agent.comment.key_secret", "agent.drift.key_secret", "agent.alert.key_secret", "agent.apply-failed.key_secret", "agent.schedule.key_secret", "agent.verify-failed.key_secret"],
1580
+ products: ["terragucci"],
1581
+ aliases: [{ product: "plywood", key: "agent.key_env" }],
1582
+ },
1583
+ {
1584
+ key: "agent.comment",
1585
+ concept: "an agent that answers a comment command",
1586
+ section: "agents",
1587
+ value: "true, or a map",
1588
+ chant: "the comment agent's jobs",
1589
+ products: ["terragucci", "plywood"],
1590
+ },
1591
+ {
1592
+ key: "agent.drift",
1593
+ concept: "an agent that opens a pull request for a drifted member",
1594
+ section: "agents",
1595
+ value: "true, or a map",
1596
+ chant: "the drift Op's agent",
1597
+ products: ["terragucci", "plywood"],
1598
+ },
1599
+ {
1600
+ key: "agent.alert",
1601
+ concept: "an agent that opens a pull request for a production alert the relay recorded",
1602
+ section: "agents",
1603
+ value: "true, or a map",
1604
+ chant: "`productAlertAgent`, the alert agent's workflow",
1605
+ products: [],
1606
+ },
1607
+ {
1608
+ key: "agent.apply-failed",
1609
+ concept: "an agent that opens a pull request for a failed apply, beside the triage comment",
1610
+ section: "agents",
1611
+ value: "true, or a map",
1612
+ chant: "`productApplyFailedAgent`, the failed-apply agent's workflow, and `CHANT_AGENT_FACTS=apply-failed` on the apply jobs",
1613
+ products: [],
1614
+ },
1615
+ {
1616
+ key: "agent.verify-failed",
1617
+ concept: "an agent that opens a pull request when a stage's verify or soak fails after an apply",
1618
+ section: "agents",
1619
+ value: "true, or a map",
1620
+ chant: "`productVerifyFailedAgent`, the failed-verify agent's workflow, and `agentFacts` with `verify-failed` among its triggers on the pipeline's jobs",
1621
+ products: [],
1622
+ },
1623
+ {
1624
+ key: "agent.schedule",
1625
+ concept: "an agent that does a recurring task on a cron and opens a pull request",
1626
+ section: "agents",
1627
+ value: "a map with `cron` and `task`",
1628
+ chant: "`productScheduleAgent`, the scheduled agent's workflow",
1629
+ products: [],
1630
+ },
1631
+ {
1632
+ key: "agent.schedule.cron",
1633
+ concept: "when the scheduled agent runs",
1634
+ section: "agents",
1635
+ value: "a five-field cron",
1636
+ chant: "the scheduled agent's `schedule`",
1637
+ products: [],
1638
+ },
1639
+ {
1640
+ key: "agent.schedule.task",
1641
+ concept: "what the scheduled agent does on each run",
1642
+ section: "agents",
1643
+ value: "text, at most 4000 characters",
1644
+ chant: "the scheduled agent's `task`",
1645
+ products: [],
1646
+ },
1647
+ {
1648
+ key: "agent.alert.window",
1649
+ concept: "the minutes in which one member's alerts, failed applies, failed verifies or scheduled runs join one agent run",
1650
+ section: "agents",
1651
+ value: "a whole number from 1 to 1440, 15 by default",
1652
+ chant: "the agent's `window`",
1653
+ also: ["agent.apply-failed.window", "agent.schedule.window", "agent.verify-failed.window"],
1654
+ products: [],
1655
+ },
1656
+ {
1657
+ key: "agent.alert.relay_key_secret",
1658
+ concept: "the secret holding the relay key the alert, failed-apply and failed-verify facts are signed and checked with",
1659
+ section: "agents",
1660
+ pattern: SECRET_NAME,
1661
+ chant: "the agent's `relayKeyEnv`, and the pipeline jobs' `agentFacts.relayKeyEnv`",
1662
+ also: ["agent.apply-failed.relay_key_secret", "agent.verify-failed.relay_key_secret"],
1663
+ products: [],
1664
+ },
1665
+ {
1666
+ key: "control.repo",
1667
+ concept: "the control repository told after each apply on merge",
1668
+ section: "agents",
1669
+ value: "host/owner/name or a URL",
1670
+ chant: "the `<product>-applied` dispatch",
1671
+ products: ["terragucci", "plywood"],
1672
+ },
1673
+ {
1674
+ key: "runner",
1675
+ concept: "the runner every job runs on, or one per stage word",
1676
+ section: "jobs",
1677
+ value: "a label, a list of labels, a runner group, or a map of `default` and the stage words",
1678
+ chant: "a wave's `runner`",
1679
+ also: ["environments.<name>.runner"],
1680
+ products: ["terragucci"],
1681
+ aliases: [{ product: "plywood", key: "runners" }],
1682
+ },
1683
+ {
1684
+ key: "image",
1685
+ concept: "the image every job runs in",
1686
+ section: "jobs",
1687
+ value: "an image reference, or a map with `name`",
1688
+ chant: "the jobs' container",
1689
+ products: ["terragucci", "plywood", "sql-yodeler"],
1690
+ },
1691
+ ]);
1692
+ /** The words for a release through the environments: the subcommands and flags a product's bin passes to `chant components`. */
1693
+ export const PRODUCT_RELEASE_WORDS = /* @__PURE__ */ Object.freeze({
1694
+ /** `<product> promote --to <env> [--release <label>]`: `chant components promote`. */
1695
+ promote: "promote",
1696
+ /** `<product> reject <op> <gate> --plan <digest> --reason <text>`: `chant reject` (#5354), the release turned down at a stage's gate. */
1697
+ reject: "reject",
1698
+ /** Why a release is rejected, on one line (#5354), and why a pause, a resume or an urgent promote was made (#5355). */
1699
+ reason: "--reason",
1700
+ /** `<product> rollback <env> --release <label>`: `chant components rollback`, the environment positional. */
1701
+ rollback: "rollback",
1702
+ /** `<product> redeploy <env>`: `chant components redeploy`. */
1703
+ redeploy: "redeploy",
1704
+ /** The environment a promote deploys to. */
1705
+ to: "--to",
1706
+ /** The environment a promote reads from; default the step before `--to` in `promotion`. */
1707
+ from: "--from",
1708
+ /** A release's label or digest. */
1709
+ release: "--release",
1710
+ /** Lets a promote skip an environment of `promotion`. */
1711
+ allowSkip: "--allow-skip",
1712
+ /** Prints the plan and changes nothing. */
1713
+ dryRun: "--dry-run",
1714
+ /** `<product> pause <env> --reason <text>`: `chant stage pause` (#5355). */
1715
+ pause: "pause",
1716
+ /** `<product> resume <env> --reason <text>`: `chant stage resume` (#5355). */
1717
+ resume: "resume",
1718
+ /** Lets a promote pass the stage's gate on its urgent rule (#5355). */
1719
+ urgent: "--urgent",
1720
+ });
1721
+ /** Release command spellings a product accepts beside {@link PRODUCT_RELEASE_WORDS}: `rollback --env <env>` for the positional. */
1722
+ export const PRODUCT_RELEASE_ALIASES = /* @__PURE__ */ Object.freeze([
1723
+ { product: "plywood", command: "rollback", alias: "--env <env>", word: "<env> (the positional, with --release)" },
1724
+ ]);
1725
+ /**
1726
+ * The kinds of an audit line, in the words a person reads: the event that
1727
+ * happened, each with the spellings a product wrote for it. The gate ledger's
1728
+ * entries (`GATE_AUDIT_KINDS`) are the first eight; `refused` and `recorded`
1729
+ * hold a product's own records. The report store's audit line
1730
+ * (`@intentius/chant/report-store`, #5336) takes its `kind` from here.
1731
+ */
1732
+ export const PRODUCT_AUDIT_KINDS = /* @__PURE__ */ Object.freeze({
1733
+ /** A plan reached its gate and waits for an approval. */
1734
+ "approval-requested": [],
1735
+ /** An approval of a plan's digest; terragucci writes `approval`. */
1736
+ approved: ["approval"],
1737
+ /** An approval or an override a commit removed from the ledger; terragucci writes `approval-revoked` and `override-revoked`. */
1738
+ revoked: ["approval-revoked", "override-revoked"],
1739
+ /** A policy denial that waits for an override. */
1740
+ "override-requested": [],
1741
+ /** An override of a denial; terragucci and sql-yodeler write `override`. */
1742
+ "override-recorded": ["override"],
1743
+ /** An override an apply cited. */
1744
+ "override-spent": [],
1745
+ /** A wave's apply, whichever way it ended (`result` says); terragucci writes `apply`. */
1746
+ applied: ["apply"],
1747
+ /** An apply the gate or a check refused. */
1748
+ refused: [],
1749
+ /** A hook's outcome at a wave. */
1750
+ hook: [],
1751
+ /** Any other event a product records from its own records, named in the line's `product_kind`. */
1752
+ recorded: [],
1753
+ });
1754
+ /** One segment in the product's case: `not_author` → `notAuthor` under camelCase. */
1755
+ function spell(segment, kase) {
1756
+ if (kase === "snake" || segment.startsWith("<"))
1757
+ return segment;
1758
+ return segment.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
1759
+ }
1760
+ function segments(key, kase) {
1761
+ const out = [];
1762
+ for (const raw of key.split(".")) {
1763
+ if (raw.endsWith("[]")) {
1764
+ out.push(spell(raw.slice(0, -2), kase), "[]");
1765
+ }
1766
+ else {
1767
+ out.push(spell(raw, kase));
1768
+ }
1769
+ }
1770
+ return out;
1771
+ }
1772
+ function isMap(v) {
1773
+ return typeof v === "object" && v !== null && !Array.isArray(v);
1774
+ }
1775
+ /** Every concrete path a key pattern reaches in `doc`, with its value. */
1776
+ function resolve(doc, parts, at = []) {
1777
+ if (parts.length === 0)
1778
+ return [{ path: at.join("."), value: doc }];
1779
+ const [head, ...rest] = parts;
1780
+ if (head === "[]") {
1781
+ if (!Array.isArray(doc))
1782
+ return [];
1783
+ return doc.flatMap((item, i) => resolve(item, rest, [...at.slice(0, -1), `${at[at.length - 1] ?? ""}[${i}]`]));
1784
+ }
1785
+ if (!isMap(doc))
1786
+ return [];
1787
+ if (head.startsWith("<"))
1788
+ return Object.entries(doc).flatMap(([k, v]) => resolve(v, rest, [...at, k]));
1789
+ if (!Object.prototype.hasOwnProperty.call(doc, head))
1790
+ return [];
1791
+ return resolve(doc[head], rest, [...at, head]);
1792
+ }
1793
+ function hasShape(value, shape) {
1794
+ switch (shape) {
1795
+ case undefined:
1796
+ return value !== undefined;
1797
+ case "string":
1798
+ return typeof value === "string";
1799
+ case "map":
1800
+ return isMap(value);
1801
+ case "list-or-map":
1802
+ return Array.isArray(value) || isMap(value);
1803
+ case "storage-url":
1804
+ return typeof value === "string" && new RegExp(STORAGE_URL).test(value);
1805
+ case "forge-environments":
1806
+ return isMap(value) && Object.values(value).every((v) => typeof v === "string" || (isMap(v) && typeof v.name === "string"));
1807
+ }
1808
+ }
1809
+ function spelled(key, kase) {
1810
+ return segments(key, kase)
1811
+ .join(".")
1812
+ .replace(/\.\[\]/g, "[]");
1813
+ }
1814
+ /**
1815
+ * Checks a product's config against the vocabulary: each alias the product
1816
+ * accepts is a warning naming the vocabulary key, an alias set beside its key
1817
+ * is an error, and a value outside a key's words or pattern is an error.
1818
+ * Keys the vocabulary does not hold are the product's own and are not read.
1819
+ * `promotion` is checked as a list of distinct environment names, each one a
1820
+ * key of `environments` when the config has that map.
1821
+ */
1822
+ export function productConfigProblems(config, options) {
1823
+ const kase = options.case ?? "snake";
1824
+ const out = [];
1825
+ if (!isMap(config))
1826
+ return out;
1827
+ const roots = [{ prefix: "", doc: config }];
1828
+ for (const scope of options.scopes ?? []) {
1829
+ const doc = config[scope];
1830
+ if (isMap(doc))
1831
+ roots.push({ prefix: `${scope}.`, doc });
1832
+ }
1833
+ for (const { prefix, doc } of roots) {
1834
+ const at = (p) => `${prefix}${p}`;
1835
+ // The paths an alias of this product reads, so the key it shares a
1836
+ // spelling with (plywood's storage `reports.url`) does not judge them.
1837
+ const aliased = new Set();
1838
+ for (const word of PRODUCT_CONFIG_WORDS) {
1839
+ const shown = spelled(word.key, kase);
1840
+ for (const alias of word.aliases ?? []) {
1841
+ if (alias.product !== options.product || alias.key === undefined)
1842
+ continue;
1843
+ // An alias names its full path. Inside a scope it is read when that
1844
+ // path starts at the scope; the top-level pass already reports it as a
1845
+ // warning, so here it only finds the key set beside it.
1846
+ const parts = segments(alias.key, kase);
1847
+ if (prefix !== "" && parts[0] !== prefix.slice(0, -1))
1848
+ continue;
1849
+ for (const hit of resolve(doc, prefix === "" ? parts : parts.slice(1))) {
1850
+ if (!hasShape(hit.value, alias.shape))
1851
+ continue;
1852
+ // The key sits inside the alias (plywood's `pass.secrets` inside
1853
+ // `pass`): the value is written in the key's spelling, not the alias's.
1854
+ if (!alias.key.includes("<") && resolve(doc, segments(word.key, kase)).some((h) => h.path.startsWith(`${hit.path}.`)))
1855
+ continue;
1856
+ aliased.add(hit.path);
1857
+ if (prefix === "")
1858
+ out.push({ level: "warning", path: at(hit.path), key: word.key, message: `is accepted as ${shown}, the vocabulary's key` });
1859
+ // The key set beside its alias, where the alias does not sit inside
1860
+ // it (plywood's `notify.slack.webhook` sits inside `notify.slack`).
1861
+ if (!alias.key.includes("<") && resolve(doc, segments(word.key, kase)).some((h) => !hit.path.startsWith(`${h.path}.`))) {
1862
+ out.push({ level: "error", path: at(hit.path), key: word.key, message: `and ${at(shown)} are both set; set ${at(shown)} alone` });
1863
+ }
1864
+ }
1865
+ }
1866
+ }
1867
+ for (const word of PRODUCT_CONFIG_WORDS) {
1868
+ const shown = spelled(word.key, kase);
1869
+ const valueAliases = new Map((word.aliases ?? []).flatMap((a) => (a.product === options.product && a.value ? [a.value] : [])));
1870
+ for (const key of [word.key, ...(word.also ?? [])]) {
1871
+ for (const hit of resolve(doc, segments(key, kase))) {
1872
+ if (aliased.has(hit.path))
1873
+ continue;
1874
+ const items = Array.isArray(hit.value) && word.values ? hit.value : [hit.value];
1875
+ for (const item of items) {
1876
+ if (typeof item !== "string")
1877
+ continue;
1878
+ const accepted = valueAliases.get(item);
1879
+ if (accepted !== undefined) {
1880
+ out.push({ level: "warning", path: at(hit.path), key: word.key, message: `${item} is accepted as ${accepted}, the vocabulary's word` });
1881
+ }
1882
+ else if (word.values && !word.values.includes(item)) {
1883
+ out.push({ level: "error", path: at(hit.path), key: word.key, message: `is ${item}; ${shown} takes ${word.values.join(", ")}` });
1884
+ }
1885
+ else if (word.pattern && !word.values && !new RegExp(word.pattern).test(item)) {
1886
+ out.push({ level: "error", path: at(hit.path), key: word.key, message: `is ${item}; ${shown} is ${word.value ?? (word.pattern === SECRET_NAME ? "a secret or variable name" : `a value matching ${word.pattern}`)}` });
1887
+ }
1888
+ }
1889
+ }
1890
+ }
1891
+ }
1892
+ out.push(...promotionProblems(doc, prefix));
1893
+ }
1894
+ return out;
1895
+ }
1896
+ function promotionProblems(doc, prefix) {
1897
+ if (!isMap(doc) || doc.promotion === undefined)
1898
+ return [];
1899
+ const path = `${prefix}promotion`;
1900
+ const problem = (message) => ({ level: "error", path, key: "promotion", message });
1901
+ const order = doc.promotion;
1902
+ if (!Array.isArray(order) || order.length === 0 || !order.every((n) => typeof n === "string" && n.trim() !== "")) {
1903
+ return [problem("is a list of environment names, first to last")];
1904
+ }
1905
+ const out = [];
1906
+ const seen = new Set();
1907
+ for (const name of order) {
1908
+ if (/[*?[\]{}]/.test(name))
1909
+ out.push(problem(`names ${name}, a pattern; each step is one environment`));
1910
+ if (seen.has(name))
1911
+ out.push(problem(`names ${name} twice; an environment is one step`));
1912
+ seen.add(name);
1913
+ }
1914
+ const envs = doc.environments;
1915
+ if (isMap(envs) && !hasShape(envs, "forge-environments")) {
1916
+ for (const name of seen)
1917
+ if (!(name in envs))
1918
+ out.push(problem(`names ${name}, which environments does not declare`));
1919
+ }
1920
+ return out;
1921
+ }
1922
+ /** The vocabulary's word for `key` (snake_case notation), or undefined. */
1923
+ export function productConfigWord(key) {
1924
+ return PRODUCT_CONFIG_WORDS.find((w) => w.key === key);
1925
+ }