@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
@@ -23,6 +23,24 @@
23
23
  * with none, no approval proves anything, so a rule naming roles or
24
24
  * `notAuthor` is never met.
25
25
  *
26
+ * With `proven` (#5349), only a proven approver counts toward the rule's
27
+ * `count` at all. Without it a `count` counts every human approver of the
28
+ * plan, proven or not, so under a mode that takes plain `chant approve`
29
+ * lines (`ledger`, `pr-review`, `pull-request`) one person who can push to
30
+ * `chant/lifecycle` can write two lines in two names and meet `count: 2`.
31
+ * Off by default.
32
+ *
33
+ * Rules combine with `all` and `any` (#5354): a group `{ all: [...] }` is
34
+ * met when every rule in it is, and `{ any: [...] }` when one is, so a gate
35
+ * can take "two approvers, or one with the `release-manager` role". The list
36
+ * a gate takes is an `all`. Groups nest up to {@link QUORUM_MAX_DEPTH} deep,
37
+ * and every rule and group may carry a `name`, which the progress lines, the
38
+ * plan note and the pending fact on the ledger show. A group whose rules a
39
+ * gate's targets leave out is dropped, never met by nobody: an `any` is met
40
+ * only by a rule that counts real approvers, so it opens no way past the
41
+ * gate's approval. Only a caller that passes `combine: true` to
42
+ * {@link quorumProblems} reads groups and names.
43
+ *
26
44
  * `notAuthor` reads who was involved in the change (#4333): the pull
27
45
  * request's author, each login a `Requested-by:` trailer on its commits
28
46
  * names, and the accounts an agent acts as. With `excludeInvolved`, an
@@ -36,6 +54,8 @@ import { type GateSigners } from "../lifecycle/gate-seal.js";
36
54
  import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
37
55
  /** One approval rule. */
38
56
  export interface GateQuorumRule {
57
+ /** The rule's name (#5354), shown in its progress line, the plan note and the pending fact. */
58
+ name?: string;
39
59
  /** Globs over the gate's targets (an Op wave's run targets, an Op gate's environment). Absent, the rule covers every target. */
40
60
  targets?: string[];
41
61
  /** Distinct human approvers the rule needs. At least 1. */
@@ -44,9 +64,37 @@ export interface GateQuorumRule {
44
64
  roles?: string[];
45
65
  /** When true, at least one counted approver is proven and is not the change's author. */
46
66
  notAuthor?: boolean;
67
+ /**
68
+ * When true (#5349), only a proven approver counts toward `count`: a seal
69
+ * that verifies against the signers at base, or a review the judge proves.
70
+ * Default false: every human approver of the plan counts.
71
+ */
72
+ proven?: boolean;
73
+ }
74
+ /** A group met when every rule in it is met (#5354). */
75
+ export interface GateQuorumAll {
76
+ name?: string;
77
+ all: GateQuorumNode[];
47
78
  }
48
- /** A gate's quorum: one rule (the form before #4290), or a list of them. */
49
- export type GateQuorumSpec = GateQuorumRule | readonly GateQuorumRule[];
79
+ /** A group met when one rule in it is met (#5354). */
80
+ export interface GateQuorumAny {
81
+ name?: string;
82
+ any: GateQuorumNode[];
83
+ }
84
+ /** A rule, or a group of rules (#5354). */
85
+ export type GateQuorumNode = GateQuorumRule | GateQuorumAll | GateQuorumAny;
86
+ /** A gate's quorum: one rule (the form before #4290), or a list of rules and groups, all of which must be met. */
87
+ export type GateQuorumSpec = GateQuorumRule | readonly GateQuorumNode[];
88
+ /** How deep `all` and `any` groups nest (#5354): a group in a group in a group, and no further. */
89
+ export declare const QUORUM_MAX_DEPTH = 3;
90
+ /** Whether `node` is an `all` group. */
91
+ export declare const isQuorumAll: (node: GateQuorumNode) => node is GateQuorumAll;
92
+ /** Whether `node` is an `any` group. */
93
+ export declare const isQuorumAny: (node: GateQuorumNode) => node is GateQuorumAny;
94
+ /** Whether `node` is a group, `all` or `any`. */
95
+ export declare const isQuorumGroup: (node: GateQuorumNode) => node is GateQuorumAll | GateQuorumAny;
96
+ /** The rules and groups a quorum lists, at the top. Absent, none. */
97
+ export declare function quorumNodes(quorum: GateQuorumSpec | undefined): GateQuorumNode[];
50
98
  /** What a judge says about one approval. */
51
99
  export interface QuorumJudgement {
52
100
  /** The approval proves who `resolvedBy` is: a verified seal, or the forge's review. */
@@ -72,13 +120,30 @@ export interface GateQuorumRuleProgress {
72
120
  count: number;
73
121
  roles?: string[];
74
122
  notAuthor?: boolean;
123
+ proven?: boolean;
75
124
  /** The approvers it counts, oldest first. */
76
125
  approvers: string[];
77
126
  met: boolean;
78
127
  /** Why the author could not be told apart, when `notAuthor` is set and nobody knows the author. */
79
128
  authorUnknown?: boolean;
129
+ /** The rule's name (#5354). */
130
+ name?: string;
131
+ }
132
+ /** How far a group of rules is met (#5354). */
133
+ export interface GateQuorumGroupProgress {
134
+ kind: "all" | "any";
135
+ name?: string;
136
+ met: boolean;
137
+ children: Array<GateQuorumRuleProgress | GateQuorumGroupProgress>;
80
138
  }
81
- /** The rules of a quorum, as a list. Absent, none. */
139
+ /** Whether a progress entry is a group's. */
140
+ export declare const isGroupProgress: (p: GateQuorumRuleProgress | GateQuorumGroupProgress) => p is GateQuorumGroupProgress;
141
+ /**
142
+ * The rules of a quorum, as a flat list: every rule, inside groups too
143
+ * (#5354). For a quorum with no groups, the list it is. Read it to ask what
144
+ * any rule needs (proof, a count); judge whether the quorum is met with
145
+ * {@link quorumTreeProgress}, which reads the groups.
146
+ */
82
147
  export declare function quorumRules(quorum: GateQuorumSpec | undefined): GateQuorumRule[];
83
148
  /**
84
149
  * Whether `target` matches `glob`: `*` within a `/` segment, `**` across
@@ -87,17 +152,35 @@ export declare function quorumRules(quorum: GateQuorumSpec | undefined): GateQuo
87
152
  * one thing in both.
88
153
  */
89
154
  export declare function targetGlobMatch(glob: string, target: string): boolean;
90
- /** The rules a gate whose targets are `targets` takes: those with no `targets`, and those a glob of matches one. */
91
- export declare function quorumRulesFor(rules: readonly GateQuorumRule[], targets: readonly string[]): GateQuorumRule[];
155
+ /**
156
+ * The rules a gate whose targets are `targets` takes: those with no
157
+ * `targets`, and those a glob of matches one. A group keeps the rules in it
158
+ * the gate takes, and is dropped when it keeps none (#5354), so an `any`
159
+ * is never met by a rule left out.
160
+ */
161
+ export declare function quorumRulesFor<T extends GateQuorumNode>(rules: readonly T[], targets: readonly string[]): T[];
92
162
  /** The most approvers any rule needs, 1 with none. */
93
163
  export declare function quorumNeed(rules: readonly GateQuorumRule[]): number;
164
+ /** Every rule with where it is written (#5354): `approvals.quorum[1].any[0]`, under `where`. */
165
+ export declare function quorumRuleSites(quorum: GateQuorumSpec | undefined, where: string): Array<{
166
+ rule: GateQuorumRule;
167
+ at: string;
168
+ }>;
169
+ /** A rule or group's name (#5354): lowercase letters, digits, `-` and `_`. */
170
+ export declare const QUORUM_NAME: RegExp;
94
171
  /**
95
172
  * Everything wrong with a quorum, one line each. `where` names it
96
173
  * (`approval.quorum`). With `notAuthor: false`, a rule naming `notAuthor` is
97
- * refused, since that caller has no author to judge by.
174
+ * refused, since that caller has no author to judge by. Without `proven:
175
+ * true`, a rule naming `proven` is refused (#5349): an Op waves spec's
176
+ * `approvals.quorum` reads it. Without `combine: true`, a group (`all`,
177
+ * `any`) and a `name` are refused (#5354): an Op waves spec's
178
+ * `approvals.quorum` and a pipeline stage's gate read them.
98
179
  */
99
180
  export declare function quorumProblems(value: unknown, where: string, opts: {
100
181
  notAuthor: boolean;
182
+ proven?: boolean;
183
+ combine?: boolean;
101
184
  }): string[];
102
185
  /** Whether two principals name the same person, compared trimmed and lower-cased. */
103
186
  export declare const samePrincipal: (a: string, b: string) => boolean;
@@ -111,14 +194,37 @@ export interface QuorumApprover {
111
194
  }
112
195
  /** How far `rule` is met by `approvers`: each counted once, by name, oldest first. */
113
196
  export declare function quorumRuleProgress(rule: GateQuorumRule, approvers: readonly QuorumApprover[]): GateQuorumRuleProgress;
197
+ /** Whether `approver` counts toward `rule` on their own, before the count (#5354): not left out, proven when the rule needs it, holding a role it names. */
198
+ export declare function ruleAdmits(rule: GateQuorumRule, judged: QuorumJudgement): boolean;
199
+ /** What {@link quorumTreeProgress} found. */
200
+ export interface GateQuorumTreeProgress {
201
+ /** Every rule (#5354), groups' included, in the order written. */
202
+ rules: GateQuorumRuleProgress[];
203
+ /** The top-level rules and groups, with each group's. Absent when the quorum has no group. */
204
+ groups?: Array<GateQuorumRuleProgress | GateQuorumGroupProgress>;
205
+ /** Every top-level rule and group is met. False with none. */
206
+ met: boolean;
207
+ }
208
+ /**
209
+ * How far a list of rules and groups is met by `approvers` (#5354): each
210
+ * rule as {@link quorumRuleProgress} counts it, an `all` group when every
211
+ * rule in it is met, an `any` group when one is, and the list when every
212
+ * entry is. A list with no entry is not met; a caller with no rules asks for
213
+ * one human approval itself.
214
+ */
215
+ export declare function quorumTreeProgress(nodes: readonly GateQuorumNode[], approvers: readonly QuorumApprover[]): GateQuorumTreeProgress;
216
+ /** A group's line (#5354): `any fast-path: met by release-manager`, or what it waits on. */
217
+ export declare function quorumGroupLine(g: GateQuorumGroupProgress): string;
218
+ /** Every group's line, outermost first (#5354). */
219
+ export declare function quorumGroupLines(groups: ReadonlyArray<GateQuorumRuleProgress | GateQuorumGroupProgress> | undefined): string[];
114
220
  /**
115
221
  * Where a rule stands, in one line: `prod-*: 1 of 2 approvals (github:alice),
116
- * needs 1 more from platform`.
222
+ * needs 1 more from platform`. A named rule (#5354) leads with its name.
117
223
  */
118
224
  export declare function quorumRuleLine(p: GateQuorumRuleProgress): string;
119
225
  /** The rules that are not met, one line each joined by `; `. */
120
226
  export declare function quorumWaiting(progress: readonly GateQuorumRuleProgress[]): string;
121
- /** Whether a rule needs a proven approver: it names roles, or `notAuthor`. */
227
+ /** Whether a rule needs a proven approver: it names roles, `notAuthor` or `proven`. */
122
228
  export declare const ruleNeedsProof: (rule: GateQuorumRule) => boolean;
123
229
  /** Someone involved in a change (#4333), and why: `github:bob asked for abc1234`. */
124
230
  export interface QuorumInvolvement {
@@ -23,6 +23,24 @@
23
23
  * with none, no approval proves anything, so a rule naming roles or
24
24
  * `notAuthor` is never met.
25
25
  *
26
+ * With `proven` (#5349), only a proven approver counts toward the rule's
27
+ * `count` at all. Without it a `count` counts every human approver of the
28
+ * plan, proven or not, so under a mode that takes plain `chant approve`
29
+ * lines (`ledger`, `pr-review`, `pull-request`) one person who can push to
30
+ * `chant/lifecycle` can write two lines in two names and meet `count: 2`.
31
+ * Off by default.
32
+ *
33
+ * Rules combine with `all` and `any` (#5354): a group `{ all: [...] }` is
34
+ * met when every rule in it is, and `{ any: [...] }` when one is, so a gate
35
+ * can take "two approvers, or one with the `release-manager` role". The list
36
+ * a gate takes is an `all`. Groups nest up to {@link QUORUM_MAX_DEPTH} deep,
37
+ * and every rule and group may carry a `name`, which the progress lines, the
38
+ * plan note and the pending fact on the ledger show. A group whose rules a
39
+ * gate's targets leave out is dropped, never met by nobody: an `any` is met
40
+ * only by a rule that counts real approvers, so it opens no way past the
41
+ * gate's approval. Only a caller that passes `combine: true` to
42
+ * {@link quorumProblems} reads groups and names.
43
+ *
26
44
  * `notAuthor` reads who was involved in the change (#4333): the pull
27
45
  * request's author, each login a `Requested-by:` trailer on its commits
28
46
  * names, and the accounts an agent acts as. With `excludeInvolved`, an
@@ -33,14 +51,43 @@
33
51
  * caller from the trust policy it read at base ({@link trustQuorumJudge}).
34
52
  */
35
53
  import { gateSealRefusal } from "../lifecycle/gate-seal.js";
36
- /** The judge with nothing to judge by: no approval proves anyone, and nobody's author is known. */
37
- export const UNPROVEN_JUDGE = () => ({ proven: false, roles: [] });
38
- /** The rules of a quorum, as a list. Absent, none. */
39
- export function quorumRules(quorum) {
54
+ /** How deep `all` and `any` groups nest (#5354): a group in a group in a group, and no further. */
55
+ export const QUORUM_MAX_DEPTH = 3;
56
+ /** Whether `node` is an `all` group. */
57
+ export const isQuorumAll = (node) => Array.isArray(node.all);
58
+ /** Whether `node` is an `any` group. */
59
+ export const isQuorumAny = (node) => Array.isArray(node.any);
60
+ /** Whether `node` is a group, `all` or `any`. */
61
+ export const isQuorumGroup = (node) => isQuorumAll(node) || isQuorumAny(node);
62
+ /** The rules and groups a quorum lists, at the top. Absent, none. */
63
+ export function quorumNodes(quorum) {
40
64
  if (quorum === undefined)
41
65
  return [];
42
66
  return Array.isArray(quorum) ? [...quorum] : [quorum];
43
67
  }
68
+ /** The judge with nothing to judge by: no approval proves anyone, and nobody's author is known. */
69
+ export const UNPROVEN_JUDGE = () => ({ proven: false, roles: [] });
70
+ /** Whether a progress entry is a group's. */
71
+ export const isGroupProgress = (p) => "children" in p;
72
+ /**
73
+ * The rules of a quorum, as a flat list: every rule, inside groups too
74
+ * (#5354). For a quorum with no groups, the list it is. Read it to ask what
75
+ * any rule needs (proof, a count); judge whether the quorum is met with
76
+ * {@link quorumTreeProgress}, which reads the groups.
77
+ */
78
+ export function quorumRules(quorum) {
79
+ const out = [];
80
+ const walk = (n) => {
81
+ if (isQuorumAll(n))
82
+ n.all.forEach(walk);
83
+ else if (isQuorumAny(n))
84
+ n.any.forEach(walk);
85
+ else
86
+ out.push(n);
87
+ };
88
+ quorumNodes(quorum).forEach(walk);
89
+ return out;
90
+ }
44
91
  /**
45
92
  * Whether `target` matches `glob`: `*` within a `/` segment, `**` across
46
93
  * segments (and `a/**\/b` across none), `?` one character. The same reading
@@ -71,31 +118,94 @@ export function targetGlobMatch(glob, target) {
71
118
  }
72
119
  return new RegExp(`^${re}$`).test(target.replace(/\\/g, "/").replace(/\/+$/, ""));
73
120
  }
74
- /** The rules a gate whose targets are `targets` takes: those with no `targets`, and those a glob of matches one. */
121
+ /**
122
+ * The rules a gate whose targets are `targets` takes: those with no
123
+ * `targets`, and those a glob of matches one. A group keeps the rules in it
124
+ * the gate takes, and is dropped when it keeps none (#5354), so an `any`
125
+ * is never met by a rule left out.
126
+ */
75
127
  export function quorumRulesFor(rules, targets) {
76
- return rules.filter((r) => r.targets === undefined || r.targets.some((g) => targets.some((t) => targetGlobMatch(g, t))));
128
+ const prune = (n) => {
129
+ if (isQuorumGroup(n)) {
130
+ const kids = (isQuorumAll(n) ? n.all : n.any).map(prune).filter((k) => k !== undefined);
131
+ if (kids.length === 0)
132
+ return undefined;
133
+ return isQuorumAll(n) ? { ...(n.name !== undefined ? { name: n.name } : {}), all: kids } : { ...(n.name !== undefined ? { name: n.name } : {}), any: kids };
134
+ }
135
+ return n.targets === undefined || n.targets.some((g) => targets.some((t) => targetGlobMatch(g, t))) ? n : undefined;
136
+ };
137
+ return rules.map(prune).filter((n) => n !== undefined);
77
138
  }
78
139
  /** The most approvers any rule needs, 1 with none. */
79
140
  export function quorumNeed(rules) {
80
141
  return rules.reduce((n, r) => Math.max(n, r.count), 1);
81
142
  }
143
+ /** Every rule with where it is written (#5354): `approvals.quorum[1].any[0]`, under `where`. */
144
+ export function quorumRuleSites(quorum, where) {
145
+ const out = [];
146
+ const walk = (n, at) => {
147
+ if (isQuorumAll(n))
148
+ n.all.forEach((k, i) => walk(k, `${at}.all[${i}]`));
149
+ else if (isQuorumAny(n))
150
+ n.any.forEach((k, i) => walk(k, `${at}.any[${i}]`));
151
+ else
152
+ out.push({ rule: n, at });
153
+ };
154
+ quorumNodes(quorum).forEach((n, i) => walk(n, Array.isArray(quorum) ? `${where}[${i}]` : where));
155
+ return out;
156
+ }
157
+ /** A rule or group's name (#5354): lowercase letters, digits, `-` and `_`. */
158
+ export const QUORUM_NAME = /^[a-z0-9][a-z0-9_-]*$/;
82
159
  /**
83
160
  * Everything wrong with a quorum, one line each. `where` names it
84
161
  * (`approval.quorum`). With `notAuthor: false`, a rule naming `notAuthor` is
85
- * refused, since that caller has no author to judge by.
162
+ * refused, since that caller has no author to judge by. Without `proven:
163
+ * true`, a rule naming `proven` is refused (#5349): an Op waves spec's
164
+ * `approvals.quorum` reads it. Without `combine: true`, a group (`all`,
165
+ * `any`) and a `name` are refused (#5354): an Op waves spec's
166
+ * `approvals.quorum` and a pipeline stage's gate read them.
86
167
  */
87
168
  export function quorumProblems(value, where, opts) {
88
169
  const list = Array.isArray(value) ? value : [value];
89
170
  const problems = [];
90
171
  if (Array.isArray(value) && value.length === 0)
91
172
  problems.push(`\`${where}\` must name at least one rule`);
92
- list.forEach((rule, i) => {
93
- const at = Array.isArray(value) ? `${where}[${i}]` : where;
173
+ const names = new Set();
174
+ const nameProblem = (q, at) => {
175
+ if (q.name === undefined)
176
+ return;
177
+ if (!opts.combine)
178
+ return;
179
+ if (typeof q.name !== "string" || !QUORUM_NAME.test(q.name))
180
+ problems.push(`\`${at}.name\` must be lowercase letters, digits, - and _`);
181
+ else if (names.has(q.name))
182
+ problems.push(`\`${at}.name\` is ${JSON.stringify(q.name)}, which another rule of the gate already names`);
183
+ else
184
+ names.add(q.name);
185
+ };
186
+ const node = (rule, at, depth) => {
94
187
  if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
95
188
  problems.push(`\`${at}\` must be an object`);
96
189
  return;
97
190
  }
98
191
  const q = rule;
192
+ if (opts.combine && ("all" in q || "any" in q)) {
193
+ nameProblem(q, at);
194
+ if ("all" in q && "any" in q)
195
+ problems.push(`\`${at}\` names both all and any; a group is one of them`);
196
+ const kind = "all" in q ? "all" : "any";
197
+ const kids = q[kind];
198
+ if (depth >= QUORUM_MAX_DEPTH)
199
+ problems.push(`\`${at}\` nests groups deeper than ${QUORUM_MAX_DEPTH}; all and any nest up to ${QUORUM_MAX_DEPTH} groups deep`);
200
+ else if (!Array.isArray(kids) || kids.length === 0)
201
+ problems.push(`\`${at}.${kind}\` must list at least one rule`);
202
+ else
203
+ kids.forEach((k, i) => node(k, `${at}.${kind}[${i}]`, depth + 1));
204
+ for (const key of Object.keys(q))
205
+ if (key !== "name" && key !== "all" && key !== "any")
206
+ problems.push(`\`${at}.${key}\` is not read on a group; a group takes name and one of all or any`);
207
+ return;
208
+ }
99
209
  if (typeof q.count !== "number" || !Number.isInteger(q.count) || q.count < 1)
100
210
  problems.push(`\`${at}.count\` must be an integer of at least 1`);
101
211
  if (q.roles !== undefined && (!Array.isArray(q.roles) || q.roles.length === 0 || q.roles.some((r) => typeof r !== "string" || r === ""))) {
@@ -109,11 +219,20 @@ export function quorumProblems(value, where, opts) {
109
219
  if (q.notAuthor === true && !opts.notAuthor) {
110
220
  problems.push(`\`${at}.notAuthor\` is not read here: an Op gate has no author to judge by. An Op waves spec's \`approvals.quorum\` reads it from the merged pull request`);
111
221
  }
112
- const known = new Set(["targets", "count", "roles", "notAuthor"]);
222
+ if (q.proven !== undefined && typeof q.proven !== "boolean")
223
+ problems.push(`\`${at}.proven\` must be true or false`);
224
+ if (q.proven !== undefined && opts.proven !== true) {
225
+ problems.push(`\`${at}.proven\` is not read here. An Op waves spec's \`approvals.quorum\` reads it`);
226
+ }
227
+ nameProblem(q, at);
228
+ const known = new Set(["targets", "count", "roles", "notAuthor", ...(opts.proven ? ["proven"] : []), ...(opts.combine ? ["name"] : [])]);
229
+ const fields = [...known];
230
+ const words = `${fields.slice(0, -1).join(", ")} or ${fields[fields.length - 1]}`;
113
231
  for (const key of Object.keys(q))
114
- if (!known.has(key))
115
- problems.push(`\`${at}.${key}\` is not a quorum field; use targets, count, roles or notAuthor`);
116
- });
232
+ if (!known.has(key) && key !== "proven")
233
+ problems.push(`\`${at}.${key}\` is not a quorum field; use ${words}${opts.combine ? ", or a group of all or any" : ""}`);
234
+ };
235
+ list.forEach((rule, i) => node(rule, Array.isArray(value) ? `${where}[${i}]` : where, 0));
117
236
  return problems;
118
237
  }
119
238
  const norm = (s) => s.normalize("NFKC").trim().toLowerCase();
@@ -131,9 +250,7 @@ export function quorumRuleProgress(rule, approvers) {
131
250
  const seen = new Set();
132
251
  const counted = [];
133
252
  for (const a of [...approvers].sort((x, y) => Date.parse(x.at) - Date.parse(y.at))) {
134
- if (seen.has(norm(a.who)) || a.judged.excluded !== undefined)
135
- continue;
136
- if (rule.roles?.length && !(a.judged.proven && a.judged.roles.some((r) => rule.roles.includes(r))))
253
+ if (seen.has(norm(a.who)) || !ruleAdmits(rule, a.judged))
137
254
  continue;
138
255
  seen.add(norm(a.who));
139
256
  counted.push(a);
@@ -141,28 +258,88 @@ export function quorumRuleProgress(rule, approvers) {
141
258
  const notAuthor = !rule.notAuthor || counted.some((a) => a.judged.proven && a.judged.author === false);
142
259
  const authorUnknown = rule.notAuthor === true && !notAuthor && counted.some((a) => a.judged.proven && a.judged.author === undefined);
143
260
  return {
261
+ ...(rule.name !== undefined ? { name: rule.name } : {}),
144
262
  ...(rule.targets ? { targets: [...rule.targets] } : {}),
145
263
  count: rule.count,
146
264
  ...(rule.roles?.length ? { roles: [...rule.roles] } : {}),
147
265
  ...(rule.notAuthor ? { notAuthor: true } : {}),
266
+ ...(rule.proven ? { proven: true } : {}),
148
267
  approvers: counted.map((a) => a.who),
149
268
  met: counted.length >= rule.count && notAuthor,
150
269
  ...(authorUnknown ? { authorUnknown: true } : {}),
151
270
  };
152
271
  }
272
+ /** Whether `approver` counts toward `rule` on their own, before the count (#5354): not left out, proven when the rule needs it, holding a role it names. */
273
+ export function ruleAdmits(rule, judged) {
274
+ if (judged.excluded !== undefined)
275
+ return false;
276
+ if (rule.proven && !judged.proven)
277
+ return false;
278
+ if (rule.roles?.length && !(judged.proven && judged.roles.some((r) => rule.roles.includes(r))))
279
+ return false;
280
+ return true;
281
+ }
282
+ /**
283
+ * How far a list of rules and groups is met by `approvers` (#5354): each
284
+ * rule as {@link quorumRuleProgress} counts it, an `all` group when every
285
+ * rule in it is met, an `any` group when one is, and the list when every
286
+ * entry is. A list with no entry is not met; a caller with no rules asks for
287
+ * one human approval itself.
288
+ */
289
+ export function quorumTreeProgress(nodes, approvers) {
290
+ const rules = [];
291
+ let grouped = false;
292
+ const walk = (n) => {
293
+ if (isQuorumGroup(n)) {
294
+ grouped = true;
295
+ const kind = isQuorumAll(n) ? "all" : "any";
296
+ const children = (isQuorumAll(n) ? n.all : n.any).map(walk);
297
+ const met = children.length > 0 && (kind === "all" ? children.every((c) => c.met) : children.some((c) => c.met));
298
+ return { kind, ...(n.name !== undefined ? { name: n.name } : {}), met, children };
299
+ }
300
+ const p = quorumRuleProgress(n, approvers);
301
+ rules.push(p);
302
+ return p;
303
+ };
304
+ const top = nodes.map(walk);
305
+ return { rules, ...(grouped ? { groups: top } : {}), met: top.length > 0 && top.every((p) => p.met) };
306
+ }
307
+ /** A group's line (#5354): `any fast-path: met by release-manager`, or what it waits on. */
308
+ export function quorumGroupLine(g) {
309
+ const label = (c, i) => c.name ?? `${isGroupProgress(c) ? c.kind : "rule"} ${i + 1}`;
310
+ const head = `${g.kind}${g.name !== undefined ? ` ${g.name}` : ""}`;
311
+ const met = g.children.map((c, i) => [c, i]).filter(([c]) => c.met).map(([c, i]) => label(c, i));
312
+ if (g.met)
313
+ return `${head}: met by ${met.join(", ")}`;
314
+ const open = g.children.map((c, i) => [c, i]).filter(([c]) => !c.met).map(([c, i]) => label(c, i));
315
+ return g.kind === "any" ? `${head}: waits for one of ${open.join(", ")}` : `${head}: waits for ${open.join(", ")}`;
316
+ }
317
+ /** Every group's line, outermost first (#5354). */
318
+ export function quorumGroupLines(groups) {
319
+ const out = [];
320
+ const walk = (p) => {
321
+ if (!isGroupProgress(p))
322
+ return;
323
+ out.push(quorumGroupLine(p));
324
+ p.children.forEach(walk);
325
+ };
326
+ (groups ?? []).forEach(walk);
327
+ return out;
328
+ }
153
329
  /**
154
330
  * Where a rule stands, in one line: `prod-*: 1 of 2 approvals (github:alice),
155
- * needs 1 more from platform`.
331
+ * needs 1 more from platform`. A named rule (#5354) leads with its name.
156
332
  */
157
333
  export function quorumRuleLine(p) {
158
- const scope = p.targets ? p.targets.join(", ") : "every target";
334
+ const where = p.targets ? p.targets.join(", ") : "every target";
335
+ const scope = p.name !== undefined ? `${p.name} (${where})` : where;
159
336
  const have = `${p.approvers.length} of ${p.count} approval${p.count === 1 ? "" : "s"}${p.approvers.length ? ` (${p.approvers.join(", ")})` : ""}`;
160
337
  if (p.met)
161
338
  return `${scope}: ${have}, met`;
162
339
  const more = p.count - p.approvers.length;
163
340
  const needs = [];
164
341
  if (more > 0)
165
- needs.push(`${more} more${p.roles?.length ? ` from ${p.roles.join(" or ")}` : ""}`);
342
+ needs.push(`${more} more${p.proven && !p.roles?.length ? " proven" : ""}${p.roles?.length ? ` from ${p.roles.join(" or ")}` : ""}`);
166
343
  if (p.notAuthor)
167
344
  needs.push(more > 0 ? "one of them not the author" : "an approver who is not the author");
168
345
  const unknown = p.authorUnknown ? " (the change's author is not known, so no approver can show they are someone else)" : "";
@@ -172,8 +349,8 @@ export function quorumRuleLine(p) {
172
349
  export function quorumWaiting(progress) {
173
350
  return progress.filter((p) => !p.met).map(quorumRuleLine).join("; ");
174
351
  }
175
- /** Whether a rule needs a proven approver: it names roles, or `notAuthor`. */
176
- export const ruleNeedsProof = (rule) => (rule.roles?.length ?? 0) > 0 || rule.notAuthor === true;
352
+ /** Whether a rule needs a proven approver: it names roles, `notAuthor` or `proven`. */
353
+ export const ruleNeedsProof = (rule) => (rule.roles?.length ?? 0) > 0 || rule.notAuthor === true || rule.proven === true;
177
354
  /** A login as a forge allows it, and a GitHub App's `[bot]` suffix. */
178
355
  const LOGIN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[bot\])?$/;
179
356
  /**
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Which rejections stop a gate (#5354).
3
+ *
4
+ * `chant reject <op> <gate>` records a rejection of the digest a gate waits
5
+ * on (`../lifecycle/gate-rejection.ts`). At a stage's gate that digest is a
6
+ * release's, so a rejection turns that release down at that stage. A
7
+ * rejection that counts stops the gate before any approval is read: more
8
+ * approvals never clear it. Only a new release, with a new digest, goes
9
+ * through again.
10
+ *
11
+ * A rejection counts by the proof rules an approval of the same gate counts
12
+ * by:
13
+ *
14
+ * - it is a person's, as only a person's approval counts toward a quorum;
15
+ * - a gate whose `approval` mode is `sealed` counts only a rejection whose
16
+ * seal verifies against the signers at base, as it counts only sealed
17
+ * approvals. `ledger`, `pr-review` and `pull-request` take a plain
18
+ * `chant approve` line, so they take a plain `chant reject` line too;
19
+ * - a gate the workspace's `identity.gates` names counts only a rejection
20
+ * that rule admits (signed, from its class);
21
+ * - a gate with approval rules counts a rejection only from someone one of
22
+ * its rules would count as an approver: a rule with `proven` or `roles`
23
+ * counts only a proven approver, one holding a role it names.
24
+ *
25
+ * A rejection that does not count is listed with why, so the run says so.
26
+ * Pure: no git, no clock.
27
+ */
28
+ import { type GateRejectionRecord } from "../lifecycle/gate-rejection.js";
29
+ import type { GateSigners } from "../lifecycle/gate-seal.js";
30
+ import { type GateQuorumSpec } from "./gate-quorum.js";
31
+ import type { GateApprovalSource } from "./op-waves.js";
32
+ /**
33
+ * The first chant with `chant reject` (#5354): a rejection of the digest a
34
+ * gate waits on, which stops a release at a pipeline stage's gate by the
35
+ * proof rules the gate's approvals count by, and with approval rules that
36
+ * combine in `all` and `any` groups, nested up to three deep, each rule and
37
+ * group with a `name` the progress lines, the plan note and the ledger
38
+ * show, a stage hold's `description`, and a `reject` comment command a
39
+ * comment job records under the author's forge identity (`../ci-comment-reject.ts`).
40
+ */
41
+ export declare const GATE_REJECTION_FLOOR = "0.124.110";
42
+ /** What a gate's rejections are judged by. */
43
+ export interface GateRejectionInput {
44
+ gate: string;
45
+ /** The digest the gate waits on: a release's at a stage's gate. */
46
+ planDigest: string;
47
+ /** The gate's environment: a stage's name. A rejection that names another environment is for another gate. */
48
+ environment?: string;
49
+ /** The release the gate binds. A rejection that names another release is for another release. */
50
+ releaseDigest?: string;
51
+ /** The gate's approval mode. Default `ledger`. */
52
+ mode?: GateApprovalSource;
53
+ /** The rules the gate takes, after its targets are applied. */
54
+ quorum?: GateQuorumSpec;
55
+ /** The signers and passkeys at base, which prove who signed a rejection. */
56
+ signers: GateSigners;
57
+ /** `.chant/trust.json`'s role grants at base. */
58
+ roles: Readonly<Record<string, readonly string[]>>;
59
+ /** The workspace's `identity.gates` rule for the gate, when one applies. */
60
+ identity?: ((r: GateRejectionRecord) => string | null) | null;
61
+ }
62
+ /** What {@link gateRejections} found. */
63
+ export interface GateRejections {
64
+ /** The rejections that stop the gate, oldest first. */
65
+ standing: GateRejectionRecord[];
66
+ /** Rejections of this digest that do not count, with why, oldest first. */
67
+ ignored: {
68
+ rejection: GateRejectionRecord;
69
+ why: string;
70
+ }[];
71
+ }
72
+ /** Whether `r` rejects this gate's digest: its gate, digest, environment and release. */
73
+ export declare function rejectsDigest(r: GateRejectionRecord, input: Pick<GateRejectionInput, "gate" | "planDigest" | "environment" | "releaseDigest">): boolean;
74
+ /** Why `r` does not count at the gate, or null when it does. */
75
+ export declare function rejectionRefusal(r: GateRejectionRecord, input: GateRejectionInput): string | null;
76
+ /** The rejections of the gate's digest, split into those that stop it and those that do not count. */
77
+ export declare function gateRejections(records: readonly GateRejectionRecord[], input: GateRejectionInput): GateRejections;
78
+ /** The line a stopped gate prints for one rejection: who, when and why. */
79
+ export declare function rejectionLine(r: GateRejectionRecord): string;