@intentius/chant 0.124.109 → 0.124.110

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (338) hide show
  1. package/dist/__golden__/wave-loop/fan-out-applied.json +12 -6
  2. package/dist/__golden__/wave-loop/fan-out-apply-fails.json +8 -4
  3. package/dist/__golden__/wave-loop/fan-out-gated.json +4 -2
  4. package/dist/__golden__/wave-loop/fan-out-no-members.json +16 -8
  5. package/dist/__golden__/wave-loop/fan-out-plan-fails.json +8 -4
  6. package/dist/__golden__/wave-loop/fan-out-same-root.json +4 -2
  7. package/dist/agent-facts.d.ts +130 -0
  8. package/dist/agent-facts.js +196 -0
  9. package/dist/change-risk.d.ts +216 -0
  10. package/dist/change-risk.js +304 -0
  11. package/dist/change-set.d.ts +8 -0
  12. package/dist/ci-agent-alert.d.ts +139 -0
  13. package/dist/ci-agent-alert.js +342 -0
  14. package/dist/ci-agent-triggers.d.ts +152 -0
  15. package/dist/ci-agent-triggers.js +232 -0
  16. package/dist/ci-agent-verify-failed.d.ts +149 -0
  17. package/dist/ci-agent-verify-failed.js +191 -0
  18. package/dist/ci-agent.d.ts +136 -8
  19. package/dist/ci-agent.js +353 -26
  20. package/dist/ci-comment-commands.d.ts +8 -0
  21. package/dist/ci-comment-commands.js +17 -1
  22. package/dist/ci-comment-reject.d.ts +70 -0
  23. package/dist/ci-comment-reject.js +135 -0
  24. package/dist/ci-comment-replies.d.ts +3 -1
  25. package/dist/ci-comment-replies.js +6 -0
  26. package/dist/ci-estate/delivery.d.ts +25 -3
  27. package/dist/ci-estate/delivery.js +28 -9
  28. package/dist/ci-estate/page.d.ts +7 -3
  29. package/dist/ci-estate/page.js +19 -4
  30. package/dist/ci-estate/rows.d.ts +14 -2
  31. package/dist/ci-estate/rows.js +9 -1
  32. package/dist/ci-estate.d.ts +5 -2
  33. package/dist/ci-estate.js +3 -2
  34. package/dist/ci-handover.d.ts +2 -7
  35. package/dist/ci-handover.js +3 -20
  36. package/dist/ci-jobs.d.ts +6 -0
  37. package/dist/ci-jobs.js +17 -0
  38. package/dist/ci-note-commands.d.ts +2 -0
  39. package/dist/ci-note-commands.js +12 -1
  40. package/dist/ci-product-words.d.ts +151 -1
  41. package/dist/ci-product-words.js +1390 -3
  42. package/dist/ci-product.d.ts +100 -4
  43. package/dist/ci-product.js +99 -3
  44. package/dist/ci-respond-run.d.ts +9 -0
  45. package/dist/ci-respond-run.js +35 -4
  46. package/dist/ci-respond-summary-env.d.ts +56 -0
  47. package/dist/ci-respond-summary-env.js +81 -0
  48. package/dist/ci-respond-summary.d.ts +103 -0
  49. package/dist/ci-respond-summary.js +243 -0
  50. package/dist/ci-respond.d.ts +4 -2
  51. package/dist/ci-respond.js +4 -2
  52. package/dist/cli/command-group.js +1 -1
  53. package/dist/cli/commands/lint.js +21 -3
  54. package/dist/cli/handlers/agent.js +49 -4
  55. package/dist/cli/handlers/approve.js +3 -1
  56. package/dist/cli/handlers/build.d.ts +97 -1
  57. package/dist/cli/handlers/build.js +251 -3
  58. package/dist/cli/handlers/fan-out.js +55 -0
  59. package/dist/cli/handlers/graph.d.ts +14 -0
  60. package/dist/cli/handlers/graph.js +58 -3
  61. package/dist/cli/handlers/lifecycle-health.d.ts +7 -0
  62. package/dist/cli/handlers/lifecycle-health.js +47 -9
  63. package/dist/cli/handlers/lifecycle.js +4 -1
  64. package/dist/cli/handlers/notify-relay.d.ts +2 -2
  65. package/dist/cli/handlers/notify-relay.js +67 -7
  66. package/dist/cli/handlers/pipeline-agent.d.ts +30 -0
  67. package/dist/cli/handlers/pipeline-agent.js +255 -0
  68. package/dist/cli/handlers/pipeline-artifacts.d.ts +39 -0
  69. package/dist/cli/handlers/pipeline-artifacts.js +203 -0
  70. package/dist/cli/handlers/pipeline.d.ts +16 -0
  71. package/dist/cli/handlers/pipeline.js +112 -0
  72. package/dist/cli/handlers/pr-comment.js +4 -0
  73. package/dist/cli/handlers/pr-notes.js +4 -1
  74. package/dist/cli/handlers/pr.d.ts +20 -0
  75. package/dist/cli/handlers/pr.js +114 -11
  76. package/dist/cli/handlers/promote.js +792 -47
  77. package/dist/cli/handlers/reject.d.ts +84 -0
  78. package/dist/cli/handlers/reject.js +216 -0
  79. package/dist/cli/handlers/replan.d.ts +54 -0
  80. package/dist/cli/handlers/replan.js +177 -0
  81. package/dist/cli/handlers/run-generate.d.ts +5 -0
  82. package/dist/cli/handlers/run-generate.js +31 -4
  83. package/dist/cli/handlers/run-wave.js +15 -2
  84. package/dist/cli/handlers/run.js +4 -2
  85. package/dist/cli/handlers/stage.d.ts +35 -0
  86. package/dist/cli/handlers/stage.js +90 -0
  87. package/dist/cli/lsp/server.js +4 -0
  88. package/dist/cli/main.js +88 -8
  89. package/dist/cli/parse-args.js +35 -2
  90. package/dist/cli/registry.d.ts +12 -0
  91. package/dist/components/auto-release.d.ts +2 -0
  92. package/dist/components/auto-release.js +1 -0
  93. package/dist/components/capability.d.ts +40 -0
  94. package/dist/components/cli-support.d.ts +21 -1
  95. package/dist/components/cli-support.js +28 -6
  96. package/dist/components/component.d.ts +23 -4
  97. package/dist/components/component.schema.json +28 -0
  98. package/dist/components/declared-reads.d.ts +44 -4
  99. package/dist/components/declared-reads.js +80 -3
  100. package/dist/components/discover.d.ts +8 -0
  101. package/dist/components/discover.js +1 -1
  102. package/dist/components/driver.d.ts +13 -0
  103. package/dist/components/driver.js +23 -2
  104. package/dist/components/environment-sets.d.ts +229 -0
  105. package/dist/components/environment-sets.js +338 -0
  106. package/dist/components/fan-out-canary.d.ts +47 -0
  107. package/dist/components/fan-out-canary.js +58 -0
  108. package/dist/components/fan-out-run.d.ts +17 -0
  109. package/dist/components/fan-out-run.js +14 -1
  110. package/dist/components/fan-out-support.d.ts +7 -0
  111. package/dist/components/fan-out-support.js +1 -1
  112. package/dist/components/groups.d.ts +8 -1
  113. package/dist/components/groups.js +19 -1
  114. package/dist/components/index.d.ts +5 -2
  115. package/dist/components/index.js +4 -1
  116. package/dist/components/pr-cost.d.ts +28 -0
  117. package/dist/components/pr-cost.js +53 -0
  118. package/dist/components/pr-pipeline.d.ts +33 -0
  119. package/dist/components/pr-pipeline.js +32 -5
  120. package/dist/components/pr-policy.d.ts +33 -2
  121. package/dist/components/pr-policy.js +5 -2
  122. package/dist/components/pr-risk.d.ts +42 -0
  123. package/dist/components/pr-risk.js +74 -0
  124. package/dist/components/product-pipeline.d.ts +43 -0
  125. package/dist/components/product-pipeline.js +67 -1
  126. package/dist/components/promote.d.ts +6 -0
  127. package/dist/components/promote.js +13 -0
  128. package/dist/components/release-compile.js +3 -1
  129. package/dist/components/release-gate.d.ts +6 -1
  130. package/dist/components/release-gate.js +10 -2
  131. package/dist/components/step-environments.d.ts +236 -0
  132. package/dist/components/step-environments.js +392 -0
  133. package/dist/components/upstream-replan.d.ts +201 -0
  134. package/dist/components/upstream-replan.js +249 -0
  135. package/dist/components/verify-step.d.ts +30 -0
  136. package/dist/components/verify-step.js +27 -0
  137. package/dist/components/wave-plan.js +6 -2
  138. package/dist/config-environments.d.ts +4 -2
  139. package/dist/control/dispatch.d.ts +15 -0
  140. package/dist/control/dispatch.js +28 -4
  141. package/dist/cost-estimate.d.ts +188 -0
  142. package/dist/cost-estimate.js +363 -0
  143. package/dist/drift-record.d.ts +36 -0
  144. package/dist/drift-record.js +44 -0
  145. package/dist/engine-facts.d.ts +105 -0
  146. package/dist/engine-facts.js +111 -0
  147. package/dist/exit-codes.d.ts +4 -3
  148. package/dist/exit-codes.js +4 -3
  149. package/dist/flag-params.d.ts +2 -2
  150. package/dist/flag-params.js +9 -4
  151. package/dist/floor-table.data.js +53 -0
  152. package/dist/forge-token-vars.d.ts +12 -0
  153. package/dist/forge-token-vars.js +25 -0
  154. package/dist/gate-decision.d.ts +3 -1
  155. package/dist/gate-decision.js +3 -1
  156. package/dist/gated-waves.d.ts +2 -0
  157. package/dist/gated-waves.js +1 -0
  158. package/dist/graph-ir.d.ts +30 -0
  159. package/dist/graph-ir.js +33 -1
  160. package/dist/graph-refs.d.ts +26 -0
  161. package/dist/graph-refs.js +34 -3
  162. package/dist/graph-schema/graph.schema.json +136 -0
  163. package/dist/health.d.ts +65 -0
  164. package/dist/health.js +62 -0
  165. package/dist/lexicon.d.ts +188 -1
  166. package/dist/lifecycle/disruption.d.ts +14 -1
  167. package/dist/lifecycle/disruption.js +5 -1
  168. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  169. package/dist/lifecycle/gate-change-set.js +2 -1
  170. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  171. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  172. package/dist/lifecycle/gate-rejection.js +93 -0
  173. package/dist/lifecycle/gate-seal.d.ts +3 -3
  174. package/dist/lifecycle/gate-seal.js +5 -5
  175. package/dist/lifecycle/observe.d.ts +17 -0
  176. package/dist/lifecycle/observe.js +10 -1
  177. package/dist/lifecycle/release-cut.js +4 -0
  178. package/dist/lifecycle/release-ledger.d.ts +8 -0
  179. package/dist/lifecycle/release-risk.d.ts +137 -0
  180. package/dist/lifecycle/release-risk.js +214 -0
  181. package/dist/lifecycle/release-store.d.ts +9 -0
  182. package/dist/lifecycle/release-store.js +4 -0
  183. package/dist/lifecycle/stage-log.d.ts +85 -0
  184. package/dist/lifecycle/stage-log.js +141 -0
  185. package/dist/lint/canary-checks.d.ts +31 -0
  186. package/dist/lint/canary-checks.js +45 -0
  187. package/dist/lint/rule.d.ts +1 -0
  188. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  190. package/dist/lint/rules/index.d.ts +1 -0
  191. package/dist/lint/rules/index.js +3 -0
  192. package/dist/notify-relay-repo.d.ts +54 -0
  193. package/dist/notify-relay-repo.js +84 -0
  194. package/dist/notify-relay.d.ts +53 -3
  195. package/dist/notify-relay.js +96 -3
  196. package/dist/notify.d.ts +57 -1
  197. package/dist/notify.js +7 -1
  198. package/dist/notify.schema.json +61 -3
  199. package/dist/observation.d.ts +34 -0
  200. package/dist/observation.js +14 -1
  201. package/dist/op/activities/review-agent.d.ts +39 -2
  202. package/dist/op/activities/review-agent.js +88 -5
  203. package/dist/op/agent-permit.d.ts +88 -0
  204. package/dist/op/agent-permit.js +97 -0
  205. package/dist/op/gate-approval-base.d.ts +8 -0
  206. package/dist/op/gate-approval-base.js +9 -0
  207. package/dist/op/gate-approval.d.ts +30 -1
  208. package/dist/op/gate-approval.js +23 -2
  209. package/dist/op/gate-quorum.d.ts +114 -8
  210. package/dist/op/gate-quorum.js +198 -21
  211. package/dist/op/gate-reject.d.ts +79 -0
  212. package/dist/op/gate-reject.js +96 -0
  213. package/dist/op/gate-summary.js +1 -1
  214. package/dist/op/gate.d.ts +28 -3
  215. package/dist/op/gate.js +55 -13
  216. package/dist/op/generate-pipeline.d.ts +15 -1
  217. package/dist/op/generate-pipeline.js +32 -5
  218. package/dist/op/index.d.ts +11 -6
  219. package/dist/op/index.js +10 -5
  220. package/dist/op/local-executor.d.ts +2 -0
  221. package/dist/op/local-executor.js +23 -4
  222. package/dist/op/op-waves-after-plan.d.ts +23 -0
  223. package/dist/op/op-waves-after-plan.js +12 -1
  224. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  225. package/dist/op/op-waves-capability-spec.js +46 -6
  226. package/dist/op/op-waves-capability.d.ts +21 -13
  227. package/dist/op/op-waves-capability.js +22 -59
  228. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  229. package/dist/op/op-waves-environment-sets.js +82 -0
  230. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  231. package/dist/op/op-waves-quorum-warnings.js +90 -0
  232. package/dist/op/op-waves-release-port.d.ts +7 -0
  233. package/dist/op/op-waves-release-port.js +15 -3
  234. package/dist/op/op-waves-release.d.ts +15 -0
  235. package/dist/op/op-waves-release.js +15 -0
  236. package/dist/op/op-waves-run.d.ts +37 -3
  237. package/dist/op/op-waves-run.js +141 -18
  238. package/dist/op/op-waves-soak.d.ts +57 -0
  239. package/dist/op/op-waves-soak.js +111 -0
  240. package/dist/op/op-waves-split.d.ts +4 -0
  241. package/dist/op/op-waves-split.js +4 -0
  242. package/dist/op/op-waves.d.ts +67 -4
  243. package/dist/op/op-waves.js +71 -3
  244. package/dist/pipeline/agent-ajv.d.ts +4 -0
  245. package/dist/pipeline/agent-ajv.js +14 -0
  246. package/dist/pipeline/agent-steps.d.ts +329 -0
  247. package/dist/pipeline/agent-steps.js +602 -0
  248. package/dist/pipeline/artifacts.d.ts +264 -0
  249. package/dist/pipeline/artifacts.js +425 -0
  250. package/dist/pipeline/diff.d.ts +45 -0
  251. package/dist/pipeline/diff.js +177 -0
  252. package/dist/pipeline/fold.d.ts +43 -0
  253. package/dist/pipeline/fold.js +140 -0
  254. package/dist/pipeline/generate.d.ts +52 -0
  255. package/dist/pipeline/generate.js +120 -0
  256. package/dist/pipeline/product.d.ts +225 -0
  257. package/dist/pipeline/product.js +257 -0
  258. package/dist/pipeline/promote.d.ts +404 -0
  259. package/dist/pipeline/promote.js +694 -0
  260. package/dist/pipeline/read.d.ts +37 -0
  261. package/dist/pipeline/read.js +58 -0
  262. package/dist/pipeline/rendered.d.ts +25 -0
  263. package/dist/pipeline/rendered.js +53 -0
  264. package/dist/pipeline/soak-checks.d.ts +80 -0
  265. package/dist/pipeline/soak-checks.js +254 -0
  266. package/dist/pipeline/soak-gate.d.ts +97 -0
  267. package/dist/pipeline/soak-gate.js +176 -0
  268. package/dist/pipeline/soak-sources.d.ts +17 -0
  269. package/dist/pipeline/soak-sources.js +42 -0
  270. package/dist/pipeline/soak.d.ts +260 -0
  271. package/dist/pipeline/soak.js +378 -0
  272. package/dist/pipeline/spec.d.ts +724 -0
  273. package/dist/pipeline/spec.js +567 -0
  274. package/dist/pipeline/stage-ledger.d.ts +187 -0
  275. package/dist/pipeline/stage-ledger.js +185 -0
  276. package/dist/pipeline/stage-waves.d.ts +114 -0
  277. package/dist/pipeline/stage-waves.js +161 -0
  278. package/dist/pipeline/stages.d.ts +64 -0
  279. package/dist/pipeline/stages.js +174 -0
  280. package/dist/pipeline/verify-rollback.d.ts +277 -0
  281. package/dist/pipeline/verify-rollback.js +393 -0
  282. package/dist/pipeline.d.ts +142 -0
  283. package/dist/pipeline.js +143 -0
  284. package/dist/pr-loop.d.ts +22 -0
  285. package/dist/pr-loop.js +8 -0
  286. package/dist/pr-plan-note.d.ts +15 -1
  287. package/dist/pr-plan-note.js +8 -0
  288. package/dist/pr-post.d.ts +31 -0
  289. package/dist/pr-post.js +89 -0
  290. package/dist/release-floors.d.ts +1 -1
  291. package/dist/release-floors.js +1 -1
  292. package/dist/report-store/audit.schema.json +50 -0
  293. package/dist/report-store/dora.schema.json +331 -0
  294. package/dist/report-store/estate.schema.json +96 -0
  295. package/dist/report-store/run.schema.json +14 -0
  296. package/dist/report-store.d.ts +151 -0
  297. package/dist/report-store.js +344 -0
  298. package/dist/run-event.d.ts +7 -2
  299. package/dist/wave-runtime.mjs +458 -404
  300. package/dist/workspace/catalog-edges.js +3 -3
  301. package/dist/workspace/change-set.schema.json +4 -0
  302. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  303. package/dist/workspace/ci-cloud-identity.js +30 -0
  304. package/dist/workspace/ci-run.js +17 -2
  305. package/dist/workspace/ci-secrets.d.ts +3 -1
  306. package/dist/workspace/ci-secrets.js +7 -1
  307. package/dist/workspace/compose-graph.d.ts +1 -1
  308. package/dist/workspace/compose-graph.js +3 -1
  309. package/dist/workspace/declaration.d.ts +27 -0
  310. package/dist/workspace/declaration.js +35 -0
  311. package/dist/workspace/declaration.schema.json +56 -0
  312. package/dist/workspace/graph-cli.js +26 -0
  313. package/dist/workspace/graph.schema.json +5 -1
  314. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  315. package/dist/workspace/identity-gate-rule.js +2 -2
  316. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  317. package/dist/workspace/identity-reject-rule.js +24 -0
  318. package/dist/workspace/identity.d.ts +3 -0
  319. package/dist/workspace/identity.js +2 -1
  320. package/dist/workspace/nested-graph.js +2 -0
  321. package/dist/workspace/pr-report.schema.json +65 -0
  322. package/dist/workspace/promotion-order.d.ts +19 -4
  323. package/dist/workspace/promotion-order.js +26 -4
  324. package/dist/workspace/release-train.d.ts +14 -0
  325. package/dist/workspace/release-train.js +32 -0
  326. package/dist/workspace/run-event.schema.json +2 -2
  327. package/dist/workspace/stack-read-edges.d.ts +19 -0
  328. package/dist/workspace/stack-read-edges.js +54 -0
  329. package/dist/workspace/status-gates.d.ts +51 -1
  330. package/dist/workspace/status-gates.js +60 -0
  331. package/dist/workspace/status-stages.d.ts +223 -0
  332. package/dist/workspace/status-stages.js +279 -0
  333. package/dist/workspace/status.d.ts +45 -1
  334. package/dist/workspace/status.js +109 -5
  335. package/dist/workspace/status.schema.json +283 -2
  336. package/dist/workspace/trust/seal.d.ts +7 -0
  337. package/dist/workspace/trust/seal.js +9 -0
  338. package/package.json +5 -1
@@ -0,0 +1,216 @@
1
+ /**
2
+ * A scored change risk (#5325): a number from 0 to 1, a level, and each
3
+ * reason behind it with its weight, computed from facts chant already holds
4
+ * about a change set.
5
+ *
6
+ * The facts are the change set's deletes and replacements, the disruption
7
+ * class of each change (`./lifecycle/disruption.ts`, the terraform and
8
+ * pulumi classifiers), the sql lexicon's destructive migration classes, how
9
+ * many members and environments the change reaches, what depends on the
10
+ * changed nodes in the graph, the review agent's level, the level each
11
+ * agent step of a stage answers (#5358), and the review's answers to the
12
+ * questions a team writes. Each reason gives a value from 0
13
+ * to 1, and the score is the chance that at least one of them bites:
14
+ *
15
+ * score = 1 - (1 - w1 * v1) * (1 - w2 * v2) * ...
16
+ *
17
+ * so a reason only ever raises the score, and the same facts always give the
18
+ * same score. The weights are pinned in {@link CHANGE_RISK_WEIGHTS}, and a
19
+ * unit test pins them.
20
+ *
21
+ * The record only adds approvals. With `approveAbove`, a score over it, or
22
+ * an answer over its question's own threshold, makes the change `over`: the
23
+ * pull request's plan then needs an approval of its own digest, a wave
24
+ * waits whatever its gate says, and a stage gate takes the extra approval
25
+ * rules its `quorum` names. A low score passes no gate and lets nothing apply
26
+ * unapproved; there is no setting that does either.
27
+ *
28
+ * Imports types only, so the pull-request loop's bundle carries it.
29
+ */
30
+ import type { ChangeSetDocument } from "./change-set.js";
31
+ import type { GateQuorumRule } from "./op/gate-quorum.js";
32
+ import type { PrMigrationFile } from "./pr-migrations.js";
33
+ /** The record's shape version. */
34
+ export declare const CHANGE_RISK_VERSION = 1;
35
+ /** The review agent's levels, and `unknown` when there is none. */
36
+ export type ChangeRiskReviewLevel = "low" | "medium" | "high" | "unknown";
37
+ /** A score's level. */
38
+ export type ChangeRiskLevel = "low" | "medium" | "high";
39
+ /** Where each level starts: `medium` at 0.3, `high` at 0.6. */
40
+ export declare const CHANGE_RISK_LEVEL_FROM: Readonly<Record<Exclude<ChangeRiskLevel, "low">, number>>;
41
+ /**
42
+ * The weight of each reason chant computes, from 0 to 1. A question's weight
43
+ * is the one its config gives. Pinned: a change here changes every score,
44
+ * and `change-risk.test.ts` fails until it is changed there too.
45
+ */
46
+ export declare const CHANGE_RISK_WEIGHTS: {
47
+ /** Resources the change set deletes. */
48
+ readonly destroys: 0.7;
49
+ /** Resources it replaces. */
50
+ readonly replacements: 0.5;
51
+ /** Replacements that remove the old resource first, so a window has nothing there. */
52
+ readonly "disruption.destroy": 0.6;
53
+ /** Updates whose workload rolls. */
54
+ readonly "disruption.rolling": 0.2;
55
+ /** Updates and replacements no lexicon could classify. */
56
+ readonly "disruption.unknown": 0.3;
57
+ /** Destructive sql migration classes. */
58
+ readonly "sql.destructive": 0.7;
59
+ /** Members changed beyond the first. */
60
+ readonly members: 0.2;
61
+ /** Environments reached beyond the first. */
62
+ readonly environments: 0.3;
63
+ /** Graph nodes that depend on a changed node and are not changed themselves. */
64
+ readonly dependents: 0.3;
65
+ /** The review agent's level. */
66
+ readonly review: 0.5;
67
+ /** An agent step's level (#5358): its answer's `risk`, one reason per step. */
68
+ readonly agent: 0.5;
69
+ };
70
+ /** A reason chant computes. */
71
+ export type ChangeRiskFactReason = keyof typeof CHANGE_RISK_WEIGHTS;
72
+ /**
73
+ * How a count becomes a value: `1 - 2^(-n / half)`, so `half` items give 0.5
74
+ * and more approach 1. Members and environments count those beyond the first.
75
+ */
76
+ export declare const CHANGE_RISK_HALF: Readonly<Record<Exclude<ChangeRiskFactReason, "review" | "agent">, number>>;
77
+ /** The review's level as a value. `unknown` counts as `medium`: no review is not a low one. */
78
+ export declare const CHANGE_RISK_REVIEW_VALUES: Readonly<Record<ChangeRiskReviewLevel, number>>;
79
+ /** A question a team writes for the review agent, answered from 0 (no concern) to 1. */
80
+ export interface ChangeRiskQuestion {
81
+ /** The answer's key: lowercase letters, digits, `-` and `_`. */
82
+ id: string;
83
+ /** The question the review agent answers. */
84
+ text: string;
85
+ /** Its weight in the score, from 0 to 1. */
86
+ weight: number;
87
+ /** An answer above this makes the change `over` whatever the score. An `unknown` answer is above every threshold. */
88
+ approveAbove?: number;
89
+ }
90
+ /**
91
+ * The risk settings: `ci.risk` in the workspace declaration (read at base),
92
+ * a wave's or a stage gate's `holds.risk`, and an Op gate's `approval.risk`.
93
+ * Every field is optional; with none set the record is computed and shown,
94
+ * and asks for nothing.
95
+ */
96
+ export interface ChangeRiskSettings {
97
+ /** A score above this makes the change `over`, from 0 to 1. Absent: the score informs only. */
98
+ approveAbove?: number;
99
+ /**
100
+ * Approval rules the gate takes on top of its own when the change is over:
101
+ * `{ count: 2 }` raises the quorum, `{ count: 1, roles: ["sre"] }` requires
102
+ * a role. Read by stage gates (a wave's `holds.risk`) and an Op gate's
103
+ * `approval.risk`. Absent: an over change waits for one approval of its own.
104
+ */
105
+ quorum?: GateQuorumRule[];
106
+ /** Questions the review agent answers on the pull request. Read from `ci.risk` only. */
107
+ questions?: ChangeRiskQuestion[];
108
+ }
109
+ /** The facts a score is made from. Each is optional; a fact that is absent adds nothing. */
110
+ export interface ChangeRiskFacts {
111
+ /** The change set the gate binds. */
112
+ changeSet: Pick<ChangeSetDocument, "members" | "entries">;
113
+ /** Destructive migration classes an engine named (`CapabilityPlan.destructive` of the sql lexicon). */
114
+ destructive?: readonly string[];
115
+ /** New migration files the pull request adds, as the plan note classifies them. Their destructive changes count by rule. */
116
+ migrations?: readonly PrMigrationFile[];
117
+ /** The environments the change reaches. */
118
+ environments?: readonly string[];
119
+ /** Graph nodes that depend on a changed node. */
120
+ dependents?: readonly string[];
121
+ /** The review agent's level and answers, when a review was looked for. */
122
+ review?: {
123
+ risk: ChangeRiskReviewLevel;
124
+ answers?: Readonly<Record<string, number | "unknown">>;
125
+ unknownBecause?: string;
126
+ };
127
+ /**
128
+ * Each agent step's level (#5358), by step name: the `risk` its answer
129
+ * names (`../pipeline/agent-steps.ts`, `agentStepRiskLevels`). Each is one
130
+ * reason `agent.<step>`, weighed as the review's level is. A step whose
131
+ * answer names no level adds nothing.
132
+ */
133
+ agent?: Readonly<Record<string, ChangeRiskReviewLevel>>;
134
+ }
135
+ /** One reason, as the record keeps it. */
136
+ export interface ChangeRiskReason {
137
+ /** A {@link ChangeRiskFactReason}, or `question.<id>`. */
138
+ id: string;
139
+ weight: number;
140
+ /** How many things the reason counted. Absent on the review and on a question. */
141
+ count?: number;
142
+ /** The reason's value, from 0 to 1. */
143
+ value: number;
144
+ /** `weight * value`: how much it raises the score on its own. */
145
+ contribution: number;
146
+ /** What it counted, in a few words. */
147
+ detail: string;
148
+ /** On a question: the review's answer, or `unknown`. */
149
+ answer?: number | "unknown";
150
+ /** On a question: its own threshold. */
151
+ approveAbove?: number;
152
+ }
153
+ /** The risk record (#5325): stored with the change set, shown in the plan note, read by Rego as `input.risk`. */
154
+ export interface ChangeRisk {
155
+ version: typeof CHANGE_RISK_VERSION;
156
+ /** From 0 to 1, to four places. */
157
+ score: number;
158
+ level: ChangeRiskLevel;
159
+ /** Every reason chant computed, the ones that counted nothing included, in a fixed order, then the questions. */
160
+ reasons: ChangeRiskReason[];
161
+ /** The score threshold, or null when none is set. */
162
+ approveAbove: number | null;
163
+ /** The score is over `approveAbove`, or an answer is over its question's threshold. */
164
+ over: boolean;
165
+ /** Each threshold crossed, one line each. Empty when not over. */
166
+ overBy: string[];
167
+ }
168
+ /** The level of a score. */
169
+ export declare function changeRiskLevel(score: number): ChangeRiskLevel;
170
+ /** The destructive classes a set of migration files names, by rule, sorted. */
171
+ export declare function destructiveMigrationClasses(migrations: readonly PrMigrationFile[] | undefined): string[];
172
+ /** The nodes that depend on a changed node of `doc` through `edges` (`from` reads `to`), not changed themselves, sorted. */
173
+ export declare function graphDependents(doc: Pick<ChangeSetDocument, "entries">, edges: ReadonlyArray<{
174
+ from: string;
175
+ to: string;
176
+ }>): string[];
177
+ /**
178
+ * The risk of a change set: each reason with its weight, the score and the
179
+ * level, and whether a threshold in `settings` is crossed. Pure: the same
180
+ * facts and settings give the same record.
181
+ */
182
+ /**
183
+ * The reasons agent steps' levels give (#5358), `agent.<step>` in step-name
184
+ * order, each weighed as the review's level is. Empty when there are none.
185
+ * A promote folds them into the release's score at a stage gate.
186
+ */
187
+ export declare function agentStepRiskReasons(levels: ChangeRiskFacts["agent"]): ChangeRiskReason[];
188
+ export declare function scoreChangeRisk(facts: ChangeRiskFacts, settings?: ChangeRiskSettings): ChangeRisk;
189
+ /** The approval rules an over change adds to its gate: the settings' `quorum`, or none. */
190
+ export declare function changeRiskQuorum(risk: Pick<ChangeRisk, "over">, settings: Pick<ChangeRiskSettings, "quorum"> | undefined): GateQuorumRule[];
191
+ /**
192
+ * The record as a Cedar gate policy reads it, `context.changeRisk`: Cedar has
193
+ * no decimals, so the score is `percent`, a whole number from 0 to 100.
194
+ */
195
+ export interface ChangeRiskContext {
196
+ percent: number;
197
+ level: ChangeRiskLevel;
198
+ over: boolean;
199
+ /** The ids of the reasons that counted something. */
200
+ reasons: string[];
201
+ }
202
+ /** The `approval.context` key the record lands under on an Op gate that declares `approval.risk`. An authored context may not use it. */
203
+ export declare const CHANGE_RISK_CONTEXT_KEY = "changeRisk";
204
+ /** The record as Cedar context. */
205
+ export declare function changeRiskContext(risk: ChangeRisk): ChangeRiskContext;
206
+ /**
207
+ * What is wrong with a risk settings value, one line each. `quorum` and
208
+ * `questions` are refused where the caller says they are not read, so a
209
+ * setting no chant reads is never accepted.
210
+ */
211
+ export declare function changeRiskProblems(where: string, value: unknown, takes: {
212
+ quorum: boolean;
213
+ questions: boolean;
214
+ }, quorumCheck?: (rules: unknown, at: string) => string[]): string[];
215
+ /** The plan note's lines for a risk record: the score and level, the reasons that counted, and what it asks for. */
216
+ export declare function changeRiskLines(risk: ChangeRisk): string[];
@@ -0,0 +1,304 @@
1
+ /**
2
+ * A scored change risk (#5325): a number from 0 to 1, a level, and each
3
+ * reason behind it with its weight, computed from facts chant already holds
4
+ * about a change set.
5
+ *
6
+ * The facts are the change set's deletes and replacements, the disruption
7
+ * class of each change (`./lifecycle/disruption.ts`, the terraform and
8
+ * pulumi classifiers), the sql lexicon's destructive migration classes, how
9
+ * many members and environments the change reaches, what depends on the
10
+ * changed nodes in the graph, the review agent's level, the level each
11
+ * agent step of a stage answers (#5358), and the review's answers to the
12
+ * questions a team writes. Each reason gives a value from 0
13
+ * to 1, and the score is the chance that at least one of them bites:
14
+ *
15
+ * score = 1 - (1 - w1 * v1) * (1 - w2 * v2) * ...
16
+ *
17
+ * so a reason only ever raises the score, and the same facts always give the
18
+ * same score. The weights are pinned in {@link CHANGE_RISK_WEIGHTS}, and a
19
+ * unit test pins them.
20
+ *
21
+ * The record only adds approvals. With `approveAbove`, a score over it, or
22
+ * an answer over its question's own threshold, makes the change `over`: the
23
+ * pull request's plan then needs an approval of its own digest, a wave
24
+ * waits whatever its gate says, and a stage gate takes the extra approval
25
+ * rules its `quorum` names. A low score passes no gate and lets nothing apply
26
+ * unapproved; there is no setting that does either.
27
+ *
28
+ * Imports types only, so the pull-request loop's bundle carries it.
29
+ */
30
+ /** The record's shape version. */
31
+ export const CHANGE_RISK_VERSION = 1;
32
+ /** Where each level starts: `medium` at 0.3, `high` at 0.6. */
33
+ export const CHANGE_RISK_LEVEL_FROM = { medium: 0.3, high: 0.6 };
34
+ /**
35
+ * The weight of each reason chant computes, from 0 to 1. A question's weight
36
+ * is the one its config gives. Pinned: a change here changes every score,
37
+ * and `change-risk.test.ts` fails until it is changed there too.
38
+ */
39
+ export const CHANGE_RISK_WEIGHTS = {
40
+ /** Resources the change set deletes. */
41
+ destroys: 0.7,
42
+ /** Resources it replaces. */
43
+ replacements: 0.5,
44
+ /** Replacements that remove the old resource first, so a window has nothing there. */
45
+ "disruption.destroy": 0.6,
46
+ /** Updates whose workload rolls. */
47
+ "disruption.rolling": 0.2,
48
+ /** Updates and replacements no lexicon could classify. */
49
+ "disruption.unknown": 0.3,
50
+ /** Destructive sql migration classes. */
51
+ "sql.destructive": 0.7,
52
+ /** Members changed beyond the first. */
53
+ members: 0.2,
54
+ /** Environments reached beyond the first. */
55
+ environments: 0.3,
56
+ /** Graph nodes that depend on a changed node and are not changed themselves. */
57
+ dependents: 0.3,
58
+ /** The review agent's level. */
59
+ review: 0.5,
60
+ /** An agent step's level (#5358): its answer's `risk`, one reason per step. */
61
+ agent: 0.5,
62
+ };
63
+ /**
64
+ * How a count becomes a value: `1 - 2^(-n / half)`, so `half` items give 0.5
65
+ * and more approach 1. Members and environments count those beyond the first.
66
+ */
67
+ export const CHANGE_RISK_HALF = {
68
+ destroys: 1,
69
+ replacements: 1,
70
+ "disruption.destroy": 1,
71
+ "disruption.rolling": 2,
72
+ "disruption.unknown": 2,
73
+ "sql.destructive": 1,
74
+ members: 2,
75
+ environments: 1,
76
+ dependents: 4,
77
+ };
78
+ /** The review's level as a value. `unknown` counts as `medium`: no review is not a low one. */
79
+ export const CHANGE_RISK_REVIEW_VALUES = { low: 0, medium: 0.5, high: 1, unknown: 0.5 };
80
+ const round = (n) => Math.round(n * 10000) / 10000;
81
+ const saturate = (n, half) => (n <= 0 ? 0 : round(1 - Math.pow(2, -n / half)));
82
+ const CHANGES = new Set(["create", "update", "replace", "delete"]);
83
+ const QUESTION_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
84
+ const isMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
85
+ const unit = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
86
+ /** The level of a score. */
87
+ export function changeRiskLevel(score) {
88
+ if (score >= CHANGE_RISK_LEVEL_FROM.high)
89
+ return "high";
90
+ if (score >= CHANGE_RISK_LEVEL_FROM.medium)
91
+ return "medium";
92
+ return "low";
93
+ }
94
+ /** The destructive classes a set of migration files names, by rule, sorted. */
95
+ export function destructiveMigrationClasses(migrations) {
96
+ const out = new Set();
97
+ for (const f of migrations ?? [])
98
+ for (const s of f.statements ?? [])
99
+ for (const c of s.changes ?? [])
100
+ if (c.destructive)
101
+ out.add(c.rule);
102
+ return [...out].sort();
103
+ }
104
+ /** The nodes that depend on a changed node of `doc` through `edges` (`from` reads `to`), not changed themselves, sorted. */
105
+ export function graphDependents(doc, edges) {
106
+ const changed = new Set();
107
+ for (const e of doc.entries) {
108
+ if (!CHANGES.has(e.action))
109
+ continue;
110
+ if (typeof e.node === "string")
111
+ changed.add(e.node);
112
+ if (typeof e.instanceOf === "string")
113
+ changed.add(e.instanceOf);
114
+ }
115
+ const out = new Set();
116
+ for (const edge of edges)
117
+ if (changed.has(edge.to) && !changed.has(edge.from))
118
+ out.add(edge.from);
119
+ return [...out].sort();
120
+ }
121
+ /**
122
+ * The risk of a change set: each reason with its weight, the score and the
123
+ * level, and whether a threshold in `settings` is crossed. Pure: the same
124
+ * facts and settings give the same record.
125
+ */
126
+ /**
127
+ * The reasons agent steps' levels give (#5358), `agent.<step>` in step-name
128
+ * order, each weighed as the review's level is. Empty when there are none.
129
+ * A promote folds them into the release's score at a stage gate.
130
+ */
131
+ export function agentStepRiskReasons(levels) {
132
+ const weight = CHANGE_RISK_WEIGHTS.agent;
133
+ return Object.keys(levels ?? {})
134
+ .sort()
135
+ .map((step) => {
136
+ const level = levels[step];
137
+ const value = CHANGE_RISK_REVIEW_VALUES[level] ?? CHANGE_RISK_REVIEW_VALUES.unknown;
138
+ return { id: `agent.${step}`, weight, value, contribution: round(weight * value), detail: `agent step ${step} answered ${level}` };
139
+ });
140
+ }
141
+ export function scoreChangeRisk(facts, settings = {}) {
142
+ const entries = facts.changeSet.entries ?? [];
143
+ const count = (pred) => entries.filter(pred).length;
144
+ const destroys = count((e) => e.action === "delete");
145
+ const replacements = count((e) => e.action === "replace");
146
+ const deleteFirst = count((e) => e.action === "replace" && e.disruption === "destroy");
147
+ const rolling = count((e) => e.action === "update" && e.disruption === "rolling");
148
+ const unclassified = count((e) => (e.action === "update" || e.action === "replace") && e.disruption === "unknown");
149
+ const classes = new Set([...(facts.destructive ?? []), ...destructiveMigrationClasses(facts.migrations)]);
150
+ const members = new Set(entries.filter((e) => CHANGES.has(e.action)).map((e) => e.member));
151
+ for (const m of facts.changeSet.members ?? [])
152
+ if ((m.outputs?.length ?? 0) > 0)
153
+ members.add(m.member);
154
+ const environments = new Set(facts.environments ?? []);
155
+ const dependents = new Set(facts.dependents ?? []);
156
+ const counted = (id, n, detail, over = n) => {
157
+ const weight = CHANGE_RISK_WEIGHTS[id];
158
+ const value = saturate(over, CHANGE_RISK_HALF[id]);
159
+ return { id, weight, count: n, value, contribution: round(weight * value), detail };
160
+ };
161
+ const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
162
+ const reasons = [
163
+ counted("destroys", destroys, `${plural(destroys, "delete")}`),
164
+ counted("replacements", replacements, `${plural(replacements, "replacement")}`),
165
+ counted("disruption.destroy", deleteFirst, `${plural(deleteFirst, "replacement")} that delete the old resource first`),
166
+ counted("disruption.rolling", rolling, `${plural(rolling, "update")} that roll a workload`),
167
+ counted("disruption.unknown", unclassified, `${plural(unclassified, "change")} no lexicon could classify`),
168
+ counted("sql.destructive", classes.size, classes.size > 0 ? `destructive migration classes: ${[...classes].sort().join(", ")}` : "no destructive migration class"),
169
+ counted("members", members.size, `${plural(members.size, "member")} changed`, Math.max(0, members.size - 1)),
170
+ counted("environments", environments.size, `${plural(environments.size, "environment")} reached`, Math.max(0, environments.size - 1)),
171
+ counted("dependents", dependents.size, `${plural(dependents.size, "graph node")} depending on a changed one`),
172
+ ];
173
+ if (facts.review) {
174
+ const weight = CHANGE_RISK_WEIGHTS.review;
175
+ const value = CHANGE_RISK_REVIEW_VALUES[facts.review.risk] ?? CHANGE_RISK_REVIEW_VALUES.unknown;
176
+ reasons.push({ id: "review", weight, value, contribution: round(weight * value), detail: `the review's level is ${facts.review.risk}` });
177
+ }
178
+ reasons.push(...agentStepRiskReasons(facts.agent));
179
+ const overBy = [];
180
+ for (const q of settings.questions ?? []) {
181
+ const given = facts.review?.answers?.[q.id];
182
+ const answer = unit(given) ? given : "unknown";
183
+ const value = answer === "unknown" ? 1 : answer;
184
+ const why = answer === "unknown" ? (facts.review?.unknownBecause ? `, ${facts.review.unknownBecause}` : facts.review ? ", the review gave no answer" : ", no review was found") : "";
185
+ reasons.push({
186
+ id: `question.${q.id}`,
187
+ weight: q.weight,
188
+ value,
189
+ contribution: round(q.weight * value),
190
+ detail: `${q.text} (answer ${answer}${why})`,
191
+ answer,
192
+ ...(q.approveAbove !== undefined ? { approveAbove: q.approveAbove } : {}),
193
+ });
194
+ if (q.approveAbove !== undefined && (answer === "unknown" || answer > q.approveAbove)) {
195
+ overBy.push(answer === "unknown" ? `question ${q.id} has no answer, which counts above its threshold of ${q.approveAbove}` : `question ${q.id} was answered ${answer}, above its threshold of ${q.approveAbove}`);
196
+ }
197
+ }
198
+ const score = round(1 - reasons.reduce((p, r) => p * (1 - Math.min(1, Math.max(0, r.contribution))), 1));
199
+ const approveAbove = settings.approveAbove ?? null;
200
+ if (approveAbove !== null && score > approveAbove)
201
+ overBy.unshift(`the score ${score} is above ${approveAbove}`);
202
+ return { version: CHANGE_RISK_VERSION, score, level: changeRiskLevel(score), reasons, approveAbove, over: overBy.length > 0, overBy };
203
+ }
204
+ /** The approval rules an over change adds to its gate: the settings' `quorum`, or none. */
205
+ export function changeRiskQuorum(risk, settings) {
206
+ return risk.over && settings?.quorum ? settings.quorum.map((r) => ({ ...r })) : [];
207
+ }
208
+ /** The `approval.context` key the record lands under on an Op gate that declares `approval.risk`. An authored context may not use it. */
209
+ export const CHANGE_RISK_CONTEXT_KEY = "changeRisk";
210
+ /** The record as Cedar context. */
211
+ export function changeRiskContext(risk) {
212
+ return {
213
+ percent: Math.round(risk.score * 100),
214
+ level: risk.level,
215
+ over: risk.over,
216
+ reasons: risk.reasons.filter((r) => r.contribution > 0).map((r) => r.id).sort(),
217
+ };
218
+ }
219
+ /** Keys a score must never read as: each would let a low score stand in for an approval. */
220
+ const REFUSED_KEYS = ["allow_unattended", "allowUnattended", "approveBelow", "approve_below", "passBelow", "skipBelow", "unattended"];
221
+ /**
222
+ * What is wrong with a risk settings value, one line each. `quorum` and
223
+ * `questions` are refused where the caller says they are not read, so a
224
+ * setting no chant reads is never accepted.
225
+ */
226
+ export function changeRiskProblems(where, value, takes, quorumCheck) {
227
+ if (!isMap(value))
228
+ return [`\`${where}\` must be { "approveAbove"?: <0 to 1>${takes.quorum ? ', "quorum"?: [...]' : ""}${takes.questions ? ', "questions"?: [...]' : ""} }`];
229
+ const problems = [];
230
+ for (const key of Object.keys(value)) {
231
+ if (REFUSED_KEYS.includes(key))
232
+ problems.push(`\`${where}.${key}\` is refused: a risk score only adds approvals, and nothing lets a plan apply with nobody approving it`);
233
+ else if (key === "approveAbove") {
234
+ if (!unit(value.approveAbove))
235
+ problems.push(`\`${where}.approveAbove\` must be a score from 0 to 1`);
236
+ }
237
+ else if (key === "quorum" && takes.quorum) {
238
+ if (!Array.isArray(value.quorum) || value.quorum.length === 0)
239
+ problems.push(`\`${where}.quorum\` must be a non-empty list of approval rules`);
240
+ else if (quorumCheck)
241
+ problems.push(...quorumCheck(value.quorum, `${where}.quorum`));
242
+ }
243
+ else if (key === "questions" && takes.questions) {
244
+ problems.push(...questionProblems(`${where}.questions`, value.questions));
245
+ }
246
+ else if ((key === "quorum" && !takes.quorum) || (key === "questions" && !takes.questions)) {
247
+ problems.push(key === "quorum"
248
+ ? `\`${where}.quorum\` is read by a stage gate's \`holds.risk\` and an Op gate's \`approval.risk\`; here an over change waits for an approval of its own digest`
249
+ : `\`${where}.questions\` is answered by the pull request's review, so it is set in \`ci.risk.questions\``);
250
+ }
251
+ else
252
+ problems.push(`\`${where}.${key}\` is not a setting; the ones there are approveAbove${takes.quorum ? ", quorum" : ""}${takes.questions ? ", questions" : ""}`);
253
+ }
254
+ return problems;
255
+ }
256
+ function questionProblems(where, value) {
257
+ if (!Array.isArray(value))
258
+ return [`\`${where}\` must be a list of { "id", "text", "weight", "approveAbove"? }`];
259
+ const problems = [];
260
+ const seen = new Set();
261
+ value.forEach((q, i) => {
262
+ const at = `${where}[${i}]`;
263
+ if (!isMap(q)) {
264
+ problems.push(`\`${at}\` must be { "id", "text", "weight", "approveAbove"? }`);
265
+ return;
266
+ }
267
+ if (typeof q.id !== "string" || !QUESTION_ID.test(q.id))
268
+ problems.push(`\`${at}.id\` must be lowercase letters, digits, "-" and "_"`);
269
+ else if (seen.has(q.id))
270
+ problems.push(`\`${at}.id\` "${q.id}" is named twice`);
271
+ else
272
+ seen.add(q.id);
273
+ if (typeof q.text !== "string" || q.text.trim() === "")
274
+ problems.push(`\`${at}.text\` must be the question, as text`);
275
+ if (!unit(q.weight))
276
+ problems.push(`\`${at}.weight\` must be from 0 to 1`);
277
+ if (q.approveAbove !== undefined && !unit(q.approveAbove))
278
+ problems.push(`\`${at}.approveAbove\` must be from 0 to 1`);
279
+ for (const key of Object.keys(q)) {
280
+ if (REFUSED_KEYS.includes(key))
281
+ problems.push(`\`${at}.${key}\` is refused: an answer only adds approvals`);
282
+ else if (!["id", "text", "weight", "approveAbove"].includes(key))
283
+ problems.push(`\`${at}.${key}\` is not a setting`);
284
+ }
285
+ });
286
+ return problems;
287
+ }
288
+ /** One line of plain text, so nothing in a record breaks the note's layout. */
289
+ const plain = (s) => String(s).split(/\s+/).join(" ").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("|", "\\|").trim();
290
+ /** The plan note's lines for a risk record: the score and level, the reasons that counted, and what it asks for. */
291
+ export function changeRiskLines(risk) {
292
+ const out = ["", `**Risk:** ${risk.score.toFixed(2)} (${risk.level}).`];
293
+ const counted = (Array.isArray(risk.reasons) ? risk.reasons : []).filter((r) => r.contribution > 0 || r.id.startsWith("question."));
294
+ if (counted.length > 0) {
295
+ out.push("", "| Reason | Weight | Value | Adds |", "|---|---:|---:|---:|");
296
+ for (const r of counted)
297
+ out.push(`| \`${plain(r.id)}\`: ${plain(r.detail)} | ${r.weight} | ${r.value} | ${r.contribution} |`);
298
+ }
299
+ if (risk.over)
300
+ out.push("", `${(risk.overBy ?? []).map(plain).join("; ")}, so this plan needs an approval of its own digest.`);
301
+ else if (risk.approveAbove !== null)
302
+ out.push("", `The score is within ${risk.approveAbove}. A score within it asks for nothing more, and approves nothing.`);
303
+ return out;
304
+ }
@@ -43,6 +43,7 @@
43
43
  */
44
44
  import type { ChangeSet as LifecycleChangeSet } from "./lifecycle/change-set.js";
45
45
  import type { ChangeSet as ReconcileChangeSet } from "./reconcile.js";
46
+ import type { ChangeRisk } from "./change-risk.js";
46
47
  /** The schema a change-set document names in `$schema`. */
47
48
  export declare const CHANGE_SET_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json";
48
49
  /** The read-contract version the document follows. */
@@ -281,6 +282,13 @@ export interface ChangeSetDocument {
281
282
  releaseDigest?: string;
282
283
  /** The environment this change set was planned for (#4045), set with `releaseDigest`. Part of the digest when present. */
283
284
  environment?: string;
285
+ /**
286
+ * The change risk scored when the gate bound it (#5325,
287
+ * `./change-risk.ts`): the score, its level and each reason with its
288
+ * weight. Set on a stored change set when `ci.risk` was set at base.
289
+ * Like `graph`, never part of the digest.
290
+ */
291
+ risk?: ChangeRisk;
284
292
  }
285
293
  /** Where a document's node ids come from. */
286
294
  export interface ChangeSetGraph {