@intentius/chant 0.124.55 → 0.124.56

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 (370) hide show
  1. package/dist/ci-agent.d.ts.map +1 -1
  2. package/dist/ci-agent.js +1 -2
  3. package/dist/ci-audit/attribution.d.ts +111 -0
  4. package/dist/ci-audit/attribution.d.ts.map +1 -0
  5. package/dist/ci-audit/attribution.js +194 -0
  6. package/dist/ci-audit/audit-log.d.ts +144 -0
  7. package/dist/ci-audit/audit-log.d.ts.map +1 -0
  8. package/dist/ci-audit/audit-log.js +149 -0
  9. package/dist/ci-audit/index.d.ts +12 -0
  10. package/dist/ci-audit/index.d.ts.map +1 -0
  11. package/dist/ci-audit/index.js +12 -0
  12. package/dist/ci-audit/unrecorded.d.ts +74 -0
  13. package/dist/ci-audit/unrecorded.d.ts.map +1 -0
  14. package/dist/ci-audit/unrecorded.js +95 -0
  15. package/dist/ci-audit.d.ts +3 -0
  16. package/dist/ci-audit.d.ts.map +1 -0
  17. package/dist/ci-audit.js +2 -0
  18. package/dist/ci-control.d.ts.map +1 -1
  19. package/dist/ci-control.js +3 -4
  20. package/dist/ci-estate.d.ts +24 -0
  21. package/dist/ci-estate.d.ts.map +1 -1
  22. package/dist/ci-estate.js +1 -2
  23. package/dist/ci-identity.d.ts.map +1 -1
  24. package/dist/ci-identity.js +2 -3
  25. package/dist/ci-job-guard.d.ts +139 -0
  26. package/dist/ci-job-guard.d.ts.map +1 -0
  27. package/dist/ci-job-guard.js +287 -0
  28. package/dist/ci-jobs.d.ts +7 -0
  29. package/dist/ci-jobs.d.ts.map +1 -1
  30. package/dist/ci-jobs.js +7 -0
  31. package/dist/ci-product-words.d.ts +7 -1
  32. package/dist/ci-product-words.d.ts.map +1 -1
  33. package/dist/ci-product-words.js +38 -4
  34. package/dist/ci-product.d.ts +35 -0
  35. package/dist/ci-product.d.ts.map +1 -1
  36. package/dist/ci-product.js +38 -3
  37. package/dist/ci-respond-run.d.ts +73 -0
  38. package/dist/ci-respond-run.d.ts.map +1 -0
  39. package/dist/ci-respond-run.js +247 -0
  40. package/dist/ci-respond.d.ts +189 -0
  41. package/dist/ci-respond.d.ts.map +1 -0
  42. package/dist/ci-respond.js +285 -0
  43. package/dist/cli/handlers/audit-log.d.ts +12 -0
  44. package/dist/cli/handlers/audit-log.d.ts.map +1 -0
  45. package/dist/cli/handlers/audit-log.js +81 -0
  46. package/dist/cli/handlers/build.d.ts +7 -0
  47. package/dist/cli/handlers/build.d.ts.map +1 -1
  48. package/dist/cli/handlers/build.js +81 -0
  49. package/dist/cli/handlers/ci-check-job.d.ts +11 -0
  50. package/dist/cli/handlers/ci-check-job.d.ts.map +1 -0
  51. package/dist/cli/handlers/ci-check-job.js +27 -0
  52. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  53. package/dist/cli/handlers/ci-check.js +38 -9
  54. package/dist/cli/handlers/e2e-safe-run.d.ts +12 -0
  55. package/dist/cli/handlers/e2e-safe-run.d.ts.map +1 -0
  56. package/dist/cli/handlers/e2e-safe-run.js +23 -0
  57. package/dist/cli/handlers/pr.d.ts +5 -0
  58. package/dist/cli/handlers/pr.d.ts.map +1 -1
  59. package/dist/cli/handlers/pr.js +259 -4
  60. package/dist/cli/handlers/run-wave.js +89 -1
  61. package/dist/cli/main.d.ts.map +1 -1
  62. package/dist/cli/main.js +56 -2
  63. package/dist/cli/parse-args.d.ts.map +1 -1
  64. package/dist/cli/parse-args.js +107 -0
  65. package/dist/cli/registry.d.ts +38 -0
  66. package/dist/cli/registry.d.ts.map +1 -1
  67. package/dist/components/adoption.d.ts.map +1 -1
  68. package/dist/components/adoption.js +1 -2
  69. package/dist/components/capability.d.ts +37 -0
  70. package/dist/components/capability.d.ts.map +1 -1
  71. package/dist/components/capability.js +25 -0
  72. package/dist/components/check-hooks.d.ts +4 -1
  73. package/dist/components/check-hooks.d.ts.map +1 -1
  74. package/dist/components/check-steps.d.ts +74 -0
  75. package/dist/components/check-steps.d.ts.map +1 -0
  76. package/dist/components/check-steps.js +102 -0
  77. package/dist/components/ci-services.d.ts.map +1 -1
  78. package/dist/components/ci-services.js +1 -2
  79. package/dist/components/driver.d.ts +12 -0
  80. package/dist/components/driver.d.ts.map +1 -1
  81. package/dist/components/driver.js +35 -1
  82. package/dist/components/groups.d.ts.map +1 -1
  83. package/dist/components/groups.js +4 -3
  84. package/dist/components/pr-env-ledger.d.ts.map +1 -1
  85. package/dist/components/pr-env-ledger.js +1 -2
  86. package/dist/components/pr-environment.d.ts +1 -1
  87. package/dist/components/pr-environment.d.ts.map +1 -1
  88. package/dist/components/pr-environment.js +1 -1
  89. package/dist/components/pr-pipeline.d.ts +129 -3
  90. package/dist/components/pr-pipeline.d.ts.map +1 -1
  91. package/dist/components/pr-pipeline.js +153 -17
  92. package/dist/components/pr-run.d.ts +8 -0
  93. package/dist/components/pr-run.d.ts.map +1 -1
  94. package/dist/components/pr-run.js +9 -4
  95. package/dist/components/product-pipeline.d.ts +35 -2
  96. package/dist/components/product-pipeline.d.ts.map +1 -1
  97. package/dist/components/product-pipeline.js +24 -5
  98. package/dist/components/wave-plan.d.ts +8 -0
  99. package/dist/components/wave-plan.d.ts.map +1 -1
  100. package/dist/components/wave-plan.js +18 -2
  101. package/dist/e2e-harness/bucket.d.ts +21 -0
  102. package/dist/e2e-harness/bucket.d.ts.map +1 -0
  103. package/dist/e2e-harness/bucket.js +61 -0
  104. package/dist/e2e-harness/claim.d.ts +70 -0
  105. package/dist/e2e-harness/claim.d.ts.map +1 -0
  106. package/dist/e2e-harness/claim.js +98 -0
  107. package/dist/e2e-harness/driver.d.ts +64 -0
  108. package/dist/e2e-harness/driver.d.ts.map +1 -0
  109. package/dist/e2e-harness/driver.js +243 -0
  110. package/dist/e2e-harness/forgejo.d.ts +77 -0
  111. package/dist/e2e-harness/forgejo.d.ts.map +1 -0
  112. package/dist/e2e-harness/forgejo.js +205 -0
  113. package/dist/e2e-harness/git.d.ts +32 -0
  114. package/dist/e2e-harness/git.d.ts.map +1 -0
  115. package/dist/e2e-harness/git.js +67 -0
  116. package/dist/e2e-harness/index.d.ts +22 -0
  117. package/dist/e2e-harness/index.d.ts.map +1 -0
  118. package/dist/e2e-harness/index.js +48 -0
  119. package/dist/e2e-harness/jobs.d.ts +8 -0
  120. package/dist/e2e-harness/jobs.d.ts.map +1 -0
  121. package/dist/e2e-harness/jobs.js +34 -0
  122. package/dist/e2e-harness/pins.d.ts +45 -0
  123. package/dist/e2e-harness/pins.d.ts.map +1 -0
  124. package/dist/e2e-harness/pins.js +44 -0
  125. package/dist/e2e-harness/ports.d.ts +113 -0
  126. package/dist/e2e-harness/ports.d.ts.map +1 -0
  127. package/dist/e2e-harness/ports.js +4 -0
  128. package/dist/e2e-harness/reports.d.ts +45 -0
  129. package/dist/e2e-harness/reports.d.ts.map +1 -0
  130. package/dist/e2e-harness/reports.js +57 -0
  131. package/dist/e2e-harness/safe-run-cli.d.ts +17 -0
  132. package/dist/e2e-harness/safe-run-cli.d.ts.map +1 -0
  133. package/dist/e2e-harness/safe-run-cli.js +43 -0
  134. package/dist/e2e-harness/safe-run.d.ts +61 -0
  135. package/dist/e2e-harness/safe-run.d.ts.map +1 -0
  136. package/dist/e2e-harness/safe-run.js +172 -0
  137. package/dist/e2e-harness/scenario.d.ts +11 -0
  138. package/dist/e2e-harness/scenario.d.ts.map +1 -0
  139. package/dist/e2e-harness/scenario.js +89 -0
  140. package/dist/e2e-harness/schemas/demo-cycle.schema.json +282 -0
  141. package/dist/e2e-harness/schemas/demo-step.schema.json +245 -0
  142. package/dist/e2e-harness/schemas/e2e-claim-row.schema.json +33 -0
  143. package/dist/e2e-harness/schemas/e2e-claims.schema.json +18 -0
  144. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +150 -0
  145. package/dist/e2e-harness/schemas/index.d.ts +191 -0
  146. package/dist/e2e-harness/schemas/index.d.ts.map +1 -0
  147. package/dist/e2e-harness/schemas/index.js +62 -0
  148. package/dist/e2e-harness/stack.d.ts +124 -0
  149. package/dist/e2e-harness/stack.d.ts.map +1 -0
  150. package/dist/e2e-harness/stack.js +207 -0
  151. package/dist/e2e-harness/steps.d.ts +11 -0
  152. package/dist/e2e-harness/steps.d.ts.map +1 -0
  153. package/dist/e2e-harness/steps.js +22 -0
  154. package/dist/e2e-harness.d.ts +3 -0
  155. package/dist/e2e-harness.d.ts.map +1 -0
  156. package/dist/e2e-harness.js +2 -0
  157. package/dist/exit-codes.d.ts +7 -1
  158. package/dist/exit-codes.d.ts.map +1 -1
  159. package/dist/exit-codes.js +7 -1
  160. package/dist/lexicon.d.ts +46 -0
  161. package/dist/lexicon.d.ts.map +1 -1
  162. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  163. package/dist/lifecycle/gate-ledger.js +2 -3
  164. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  165. package/dist/lifecycle/gated-request.js +1 -2
  166. package/dist/lifecycle/query.d.ts.map +1 -1
  167. package/dist/lifecycle/query.js +4 -5
  168. package/dist/lifecycle/release-catalog.d.ts.map +1 -1
  169. package/dist/lifecycle/release-catalog.js +1 -1
  170. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  171. package/dist/lifecycle/release-ledger.js +1 -2
  172. package/dist/lifecycle/release-status.d.ts +20 -0
  173. package/dist/lifecycle/release-status.d.ts.map +1 -1
  174. package/dist/lifecycle/release-status.js +1 -22
  175. package/dist/lifecycle/wave-plans.d.ts +23 -7
  176. package/dist/lifecycle/wave-plans.d.ts.map +1 -1
  177. package/dist/lifecycle/wave-plans.js +9 -2
  178. package/dist/op/approval-status.d.ts +103 -0
  179. package/dist/op/approval-status.d.ts.map +1 -0
  180. package/dist/op/approval-status.js +197 -0
  181. package/dist/op/index.d.ts +1 -1
  182. package/dist/op/index.d.ts.map +1 -1
  183. package/dist/op/index.js +1 -1
  184. package/dist/op/op-waves-capability-spec.d.ts +8 -0
  185. package/dist/op/op-waves-capability-spec.d.ts.map +1 -1
  186. package/dist/op/op-waves-capability-spec.js +21 -0
  187. package/dist/op/op-waves-release.d.ts.map +1 -1
  188. package/dist/op/op-waves-release.js +1 -2
  189. package/dist/op/op-waves-run.d.ts +7 -2
  190. package/dist/op/op-waves-run.d.ts.map +1 -1
  191. package/dist/op/op-waves-run.js +96 -4
  192. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  193. package/dist/op/op-waves-stand-down.js +1 -2
  194. package/dist/op/op-waves.d.ts +35 -0
  195. package/dist/op/op-waves.d.ts.map +1 -1
  196. package/dist/op/op-waves.js +46 -6
  197. package/dist/op/runtime.d.ts +4 -0
  198. package/dist/op/runtime.d.ts.map +1 -1
  199. package/dist/op/runtime.js +2 -3
  200. package/dist/otlp.d.ts.map +1 -1
  201. package/dist/otlp.js +1 -2
  202. package/dist/parallelism.d.ts +17 -0
  203. package/dist/parallelism.d.ts.map +1 -0
  204. package/dist/parallelism.js +33 -0
  205. package/dist/policy-source.d.ts.map +1 -1
  206. package/dist/policy-source.js +1 -2
  207. package/dist/pr-forge.d.ts.map +1 -1
  208. package/dist/pr-forge.js +56 -39
  209. package/dist/pr-loop.d.ts +9 -0
  210. package/dist/pr-loop.d.ts.map +1 -1
  211. package/dist/pr-loop.js +22 -3
  212. package/dist/pr-merge.d.ts +64 -0
  213. package/dist/pr-merge.d.ts.map +1 -0
  214. package/dist/pr-merge.js +78 -0
  215. package/dist/pr-post.d.ts +70 -1
  216. package/dist/pr-post.d.ts.map +1 -1
  217. package/dist/pr-post.js +116 -5
  218. package/dist/pr-report-url.d.ts.map +1 -1
  219. package/dist/pr-report-url.js +1 -2
  220. package/dist/release-floors.d.ts +1 -1
  221. package/dist/release-floors.js +1 -1
  222. package/dist/run-event.d.ts.map +1 -1
  223. package/dist/run-event.js +1 -2
  224. package/dist/scheduled-op-cloud.d.ts +32 -0
  225. package/dist/scheduled-op-cloud.d.ts.map +1 -0
  226. package/dist/scheduled-op-cloud.js +69 -0
  227. package/dist/wave-runtime.mjs +340 -327
  228. package/dist/workspace/ci-lock-grain.d.ts +5 -0
  229. package/dist/workspace/ci-lock-grain.d.ts.map +1 -1
  230. package/dist/workspace/ci-lock-grain.js +1 -7
  231. package/dist/workspace/ci-run.d.ts.map +1 -1
  232. package/dist/workspace/ci-run.js +5 -1
  233. package/dist/workspace/pr-report.schema.json +5 -0
  234. package/package.json +1 -1
  235. package/src/ci-agent.ts +1 -2
  236. package/src/ci-audit/__fixtures__/cloudtrail-lookup-bucket.json +37 -0
  237. package/src/ci-audit/__fixtures__/cloudtrail-writes-window.json +59 -0
  238. package/src/ci-audit/attribution.ts +260 -0
  239. package/src/ci-audit/audit-log.ts +220 -0
  240. package/src/ci-audit/ci-audit.test.ts +175 -0
  241. package/src/ci-audit/index.ts +15 -0
  242. package/src/ci-audit/unrecorded.ts +140 -0
  243. package/src/ci-audit.ts +2 -0
  244. package/src/ci-control.ts +3 -4
  245. package/src/ci-estate.ts +1 -2
  246. package/src/ci-identity-database.test.ts +2 -3
  247. package/src/ci-identity-targets.test.ts +1 -3
  248. package/src/ci-identity.ts +2 -3
  249. package/src/ci-job-guard.test.ts +154 -0
  250. package/src/ci-job-guard.ts +319 -0
  251. package/src/ci-jobs.ts +8 -0
  252. package/src/ci-product-comment-targets.test.ts +45 -0
  253. package/src/ci-product-words.ts +35 -6
  254. package/src/ci-product.ts +55 -3
  255. package/src/ci-respond-run.ts +291 -0
  256. package/src/ci-respond.test.ts +264 -0
  257. package/src/ci-respond.ts +412 -0
  258. package/src/cli/handlers/audit-log.ts +74 -0
  259. package/src/cli/handlers/build-pr-loop-flags.test.ts +98 -0
  260. package/src/cli/handlers/build.ts +69 -0
  261. package/src/cli/handlers/ci-check-job.test.ts +114 -0
  262. package/src/cli/handlers/ci-check-job.ts +33 -0
  263. package/src/cli/handlers/ci-check.ts +38 -8
  264. package/src/cli/handlers/e2e-safe-run.ts +27 -0
  265. package/src/cli/handlers/pr-plan-comment-targets.test.ts +166 -0
  266. package/src/cli/handlers/pr-plan-flags.test.ts +161 -0
  267. package/src/cli/handlers/pr.ts +228 -4
  268. package/src/cli/handlers/run-wave.ts +79 -1
  269. package/src/cli/main.test.ts +1 -1
  270. package/src/cli/main.ts +56 -2
  271. package/src/cli/parse-args.ts +77 -0
  272. package/src/cli/registry.ts +38 -0
  273. package/src/components/adoption.ts +1 -2
  274. package/src/components/capability.ts +50 -0
  275. package/src/components/check-hooks.ts +4 -1
  276. package/src/components/check-steps.test.ts +70 -0
  277. package/src/components/check-steps.ts +158 -0
  278. package/src/components/ci-services.ts +1 -2
  279. package/src/components/driver.ts +35 -1
  280. package/src/components/groups.ts +4 -2
  281. package/src/components/plan-flags.test.ts +46 -0
  282. package/src/components/pr-comment-preview-targets.test.ts +34 -0
  283. package/src/components/pr-env-ledger.ts +1 -2
  284. package/src/components/pr-env-run-bundle.test.ts +0 -20
  285. package/src/components/pr-environment.ts +1 -1
  286. package/src/components/pr-pipeline-runners.test.ts +80 -0
  287. package/src/components/pr-pipeline.ts +232 -17
  288. package/src/components/pr-run.ts +17 -6
  289. package/src/components/pr-stale-job.test.ts +34 -0
  290. package/src/components/product-pipeline.ts +50 -8
  291. package/src/components/wave-plan.ts +18 -2
  292. package/src/e2e-harness/__project__/chant.config.ts +4 -0
  293. package/src/e2e-harness/__project__/src/compose.ts +33 -0
  294. package/src/e2e-harness/bucket.ts +69 -0
  295. package/src/e2e-harness/claim.test.ts +150 -0
  296. package/src/e2e-harness/claim.ts +140 -0
  297. package/src/e2e-harness/driver.test.ts +304 -0
  298. package/src/e2e-harness/driver.ts +294 -0
  299. package/src/e2e-harness/forgejo.ts +267 -0
  300. package/src/e2e-harness/git.ts +96 -0
  301. package/src/e2e-harness/index.ts +50 -0
  302. package/src/e2e-harness/jobs.ts +35 -0
  303. package/src/e2e-harness/pins.ts +52 -0
  304. package/src/e2e-harness/ports.ts +130 -0
  305. package/src/e2e-harness/reports.ts +79 -0
  306. package/src/e2e-harness/safe-run-cli.test.ts +102 -0
  307. package/src/e2e-harness/safe-run-cli.ts +54 -0
  308. package/src/e2e-harness/safe-run.ts +198 -0
  309. package/src/e2e-harness/scenario.ts +89 -0
  310. package/src/e2e-harness/schemas/README.md +62 -0
  311. package/src/e2e-harness/schemas/demo-cycle.schema.json +282 -0
  312. package/src/e2e-harness/schemas/demo-step.schema.json +245 -0
  313. package/src/e2e-harness/schemas/e2e-claim-row.schema.json +33 -0
  314. package/src/e2e-harness/schemas/e2e-claims.schema.json +18 -0
  315. package/src/e2e-harness/schemas/e2e-scenario.schema.json +150 -0
  316. package/src/e2e-harness/schemas/index.ts +220 -0
  317. package/src/e2e-harness/schemas.test.ts +145 -0
  318. package/src/e2e-harness/stack.test.ts +124 -0
  319. package/src/e2e-harness/stack.ts +306 -0
  320. package/src/e2e-harness/steps.ts +30 -0
  321. package/src/e2e-harness.ts +2 -0
  322. package/src/exit-codes.test.ts +3 -2
  323. package/src/exit-codes.ts +7 -1
  324. package/src/gate-decision-bundle.test.ts +0 -2
  325. package/src/lexicon.ts +48 -0
  326. package/src/lifecycle/control-entries-ledger.test.ts +2 -3
  327. package/src/lifecycle/gate-ledger.ts +2 -3
  328. package/src/lifecycle/gated-request.ts +1 -2
  329. package/src/lifecycle/query.ts +4 -5
  330. package/src/lifecycle/release-catalog.test.ts +3 -4
  331. package/src/lifecycle/release-catalog.ts +1 -1
  332. package/src/lifecycle/release-ledger.ts +1 -2
  333. package/src/lifecycle/release-status.test.ts +3 -4
  334. package/src/lifecycle/release-status.ts +1 -2
  335. package/src/lifecycle/wave-plans.ts +33 -5
  336. package/src/op/approval-status.test.ts +134 -0
  337. package/src/op/approval-status.ts +235 -0
  338. package/src/op/gate-review.test.ts +2 -1
  339. package/src/op/index.ts +2 -0
  340. package/src/op/op-waves-after-plan.test.ts +12 -0
  341. package/src/op/op-waves-capability-spec.ts +20 -0
  342. package/src/op/op-waves-parallelism.test.ts +89 -0
  343. package/src/op/op-waves-pull-request.test.ts +78 -1
  344. package/src/op/op-waves-release.ts +1 -2
  345. package/src/op/op-waves-run.ts +94 -4
  346. package/src/op/op-waves-stand-down.ts +1 -2
  347. package/src/op/op-waves.ts +63 -6
  348. package/src/op/runtime.ts +6 -3
  349. package/src/otlp.ts +1 -2
  350. package/src/parallelism.test.ts +38 -0
  351. package/src/parallelism.ts +33 -0
  352. package/src/policy-source.ts +1 -2
  353. package/src/pr-forge-bundle.test.ts +1 -1
  354. package/src/pr-forge.ts +54 -35
  355. package/src/pr-loop-bundle.test.ts +1 -1
  356. package/src/pr-loop-narrowed.test.ts +63 -0
  357. package/src/pr-loop.ts +30 -3
  358. package/src/pr-merge.test.ts +100 -0
  359. package/src/pr-merge.ts +105 -0
  360. package/src/pr-post-stale.test.ts +163 -0
  361. package/src/pr-post.ts +159 -5
  362. package/src/pr-report-url.ts +1 -2
  363. package/src/product-subpaths-plain-node.e2e.test.ts +1 -0
  364. package/src/release-floors.ts +1 -1
  365. package/src/run-event.ts +1 -2
  366. package/src/scheduled-op-cloud.ts +68 -0
  367. package/src/stage-hooks-bundle.test.ts +0 -2
  368. package/src/workspace/ci-lock-grain.ts +1 -2
  369. package/src/workspace/ci-run.ts +5 -1
  370. package/src/workspace/pr-report.schema.json +5 -0
@@ -0,0 +1,79 @@
1
+ /**
2
+ * chant's pull request reports as the harness reads them (chant#4587). A
3
+ * scenario's outcomes come from these and from the run ledger, never from a
4
+ * runner's status or its logs. The jobs write them under `--report-url`, at
5
+ * `<pr>/<commit>/pr-plan.json` and `pr-apply.json` (reportKey).
6
+ */
7
+ import { reportKey } from "../pr-report-url";
8
+ import type { Bucket, Clock } from "./ports";
9
+
10
+ export type ReportStage = "plan" | "apply";
11
+
12
+ /** pr-report/v1, the fields the harness reads. */
13
+ export interface PrReportView {
14
+ stage: ReportStage;
15
+ pr: number | null;
16
+ head: string;
17
+ op: string;
18
+ gate: string;
19
+ digest: string;
20
+ status: string;
21
+ refusal?: string;
22
+ message?: string;
23
+ approval?: { status?: string };
24
+ selection: { waves: string[][] };
25
+ members: Array<{ member: string; component: string; status: string; error?: string }>;
26
+ }
27
+
28
+ /** The report file of a stage. */
29
+ export const reportFile = (stage: ReportStage): string => `pr-${stage}.json`;
30
+
31
+ /**
32
+ * The bucket key of a report: `prefix` is the report URL's path below the
33
+ * bucket (`s3://<bucket>/<prefix>`), as the bucket names keys.
34
+ */
35
+ export function reportObjectKey(prefix: string, pr: number | null, commit: string, stage: ReportStage): string {
36
+ return `${prefix.replace(/\/+$/, "")}/${reportKey(pr, commit)}/${reportFile(stage)}`;
37
+ }
38
+
39
+ /** The path of an s3:// report URL below its bucket, and the bucket. */
40
+ export function splitReportUrl(url: string): { bucket: string; prefix: string } {
41
+ const m = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
42
+ if (!m) throw new Error(`${url} is not an s3:// report URL`);
43
+ return { bucket: m[1]!, prefix: m[2]!.replace(/\/+$/, "") };
44
+ }
45
+
46
+ /** A report, or null while there is none. */
47
+ export async function readReport(bucket: Bucket, key: string): Promise<PrReportView | null> {
48
+ const text = await bucket.get(key);
49
+ return text === null ? null : (JSON.parse(text) as PrReportView);
50
+ }
51
+
52
+ /** Wait for a report until `deadline` (clock ms). Resolves with it, or null past the deadline. */
53
+ export async function waitForReport(bucket: Bucket, key: string, clock: Clock, deadline: number, pollMs = 2000): Promise<PrReportView | null> {
54
+ for (;;) {
55
+ const r = await readReport(bucket, key);
56
+ if (r) return r;
57
+ if (clock.now() >= deadline) return null;
58
+ await clock.sleep(pollMs);
59
+ }
60
+ }
61
+
62
+ /** Each component's status in a report: failed if a member failed, else the members' one status, else them joined with +. */
63
+ export function componentStatuses(report: Pick<PrReportView, "members">): Map<string, string> {
64
+ const byComponent = new Map<string, string[]>();
65
+ for (const m of report.members) {
66
+ const name = m.component || m.member;
67
+ byComponent.set(name, [...(byComponent.get(name) ?? []), m.status]);
68
+ }
69
+ const out = new Map<string, string>();
70
+ for (const [name, statuses] of byComponent) {
71
+ const one = statuses.includes("failed")
72
+ ? "failed"
73
+ : statuses.every((s) => s === statuses[0])
74
+ ? statuses[0]!
75
+ : statuses.join("+");
76
+ out.set(name, one);
77
+ }
78
+ return out;
79
+ }
@@ -0,0 +1,102 @@
1
+ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
2
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import { join } from "node:path";
5
+ import { EXIT_REAL_CLOUD, EXIT_REFUSED, runSafeRunCommand } from "./safe-run-cli";
6
+ import { parseArgs } from "../cli/parse-args";
7
+
8
+ const node = (script: string): string[] => [process.execPath, "-e", script];
9
+
10
+ describe("chant e2e safe-run", () => {
11
+ let scratch: string;
12
+ let out: string[];
13
+ let err: string[];
14
+ beforeEach(() => {
15
+ scratch = mkdtempSync(join(tmpdir(), "safe-run-cli-test-"));
16
+ out = [];
17
+ err = [];
18
+ vi.spyOn(console, "log").mockImplementation((...a) => void out.push(a.join(" ")));
19
+ vi.spyOn(console, "error").mockImplementation((...a) => void err.push(a.join(" ")));
20
+ });
21
+ afterEach(() => vi.restoreAllMocks());
22
+
23
+ const base = { PATH: process.env.PATH, HOME: "/nonexistent" };
24
+
25
+ test("runs the command with the scrubbed environment and prints CLEAN", async () => {
26
+ const dump = join(scratch, "env.json");
27
+ const code = await runSafeRunCommand({
28
+ command: node(`require("fs").writeFileSync(${JSON.stringify(dump)}, JSON.stringify(process.env))`),
29
+ scratch,
30
+ echo: false,
31
+ base: { ...base, GOOGLE_APPLICATION_CREDENTIALS: "/real/key.json", AWS_PROFILE: "prod", GOOGLE_CLOUD_PROJECT: "p", CLOUDSDK_CONFIG: "/home/me/.config/gcloud", PULUMI_ACCESS_TOKEN: "pul-x" },
32
+ });
33
+ expect(code).toBe(0);
34
+ expect(out).toEqual(["CLEAN"]);
35
+ const env = JSON.parse(readFileSync(dump, "utf8")) as Record<string, string>;
36
+ expect(env.GOOGLE_APPLICATION_CREDENTIALS).toBeUndefined();
37
+ expect(env.AWS_PROFILE).toBeUndefined();
38
+ expect(env.GOOGLE_CLOUD_PROJECT).toBeUndefined();
39
+ expect(env.PULUMI_ACCESS_TOKEN).toBeUndefined();
40
+ expect(env.CLOUDSDK_CONFIG).not.toBe("/home/me/.config/gcloud");
41
+ expect(existsSync(env.CLOUDSDK_CONFIG)).toBe(true);
42
+ expect(env.PULUMI_BACKEND_URL).toMatch(/^file:\/\//);
43
+ expect(env.PULUMI_SKIP_UPDATE_CHECK).toBe("true");
44
+ });
45
+
46
+ test("keeps a local PULUMI_BACKEND_URL and refuses a remote one", async () => {
47
+ const dump = join(scratch, "backend.txt");
48
+ const script = `require("fs").writeFileSync(${JSON.stringify(dump)}, process.env.PULUMI_BACKEND_URL)`;
49
+ expect(await runSafeRunCommand({ command: node(script), scratch, echo: false, base: { ...base, PULUMI_BACKEND_URL: "file:///tmp/mine" } })).toBe(0);
50
+ expect(readFileSync(dump, "utf8")).toBe("file:///tmp/mine");
51
+ expect(await runSafeRunCommand({ command: node(script), scratch, echo: false, base: { ...base, PULUMI_BACKEND_URL: "https://api.pulumi.com" } })).toBe(EXIT_REFUSED);
52
+ expect(err.join("\n")).toContain("not a local backend");
53
+ });
54
+
55
+ test("passes the command's own exit code through after a CLEAN scan", async () => {
56
+ expect(await runSafeRunCommand({ command: node("process.exit(7)"), scratch, echo: false, base })).toBe(7);
57
+ expect(out).toEqual(["CLEAN"]);
58
+ });
59
+
60
+ test("rejects output where a real cloud refused a credential, and exits non-zero even when the command exits 0", async () => {
61
+ const code = await runSafeRunCommand({
62
+ command: node(`console.log("An error occurred (UnrecognizedClientException) when calling the ListBuckets operation")`),
63
+ scratch,
64
+ echo: false,
65
+ base,
66
+ });
67
+ expect(code).toBe(EXIT_REAL_CLOUD);
68
+ expect(out).not.toContain("CLEAN");
69
+ expect(err.join("\n")).toContain("UnrecognizedClientException");
70
+ });
71
+
72
+ test("rejects a 401 from a cloud host in a --scan directory, and a missing --scan directory", async () => {
73
+ const dir = join(scratch, "logs");
74
+ mkdirSync(dir);
75
+ writeFileSync(join(dir, "a.log"), "GET https://storage.googleapis.com/b 401 Unauthorized\n");
76
+ expect(await runSafeRunCommand({ command: node("0"), scratch, scan: [dir], echo: false, base })).toBe(EXIT_REAL_CLOUD);
77
+ expect(err.join("\n")).toContain("a.log:1:");
78
+ err.length = 0;
79
+ expect(await runSafeRunCommand({ command: node("0"), scratch, scan: [join(scratch, "nope")], echo: false, base })).toBe(EXIT_REAL_CLOUD);
80
+ expect(err.join("\n")).toContain("could not be checked");
81
+ });
82
+
83
+ test("a clean --scan directory passes", async () => {
84
+ const dir = join(scratch, "clean");
85
+ mkdirSync(dir);
86
+ writeFileSync(join(dir, "a.log"), "all good\n");
87
+ expect(await runSafeRunCommand({ command: node("0"), scratch, scan: [dir], echo: false, base })).toBe(0);
88
+ });
89
+
90
+ test("a command that cannot start is a refusal, not a pass", async () => {
91
+ expect(await runSafeRunCommand({ command: ["/nonexistent/fake-cmd"], scratch, echo: false, base })).toBe(EXIT_REFUSED);
92
+ });
93
+
94
+ test("parseArgs keeps the command after -- and collects each --scan", () => {
95
+ const a = parseArgs(["e2e", "safe-run", "--scan", "a", "--scan", "b", "--", "bash", "-c", "echo hi", "--flag"]);
96
+ expect(a.command).toBe("e2e");
97
+ expect(a.path).toBe("safe-run");
98
+ expect(a.scanDirs).toEqual(["a", "b"]);
99
+ expect(a.positionals?.slice(1)).toEqual(["bash", "-c", "echo hi", "--flag"]);
100
+ expect(() => parseArgs(["e2e", "safe-run", "--scan"])).toThrow(/--scan needs a directory/);
101
+ });
102
+ });
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The body of `chant e2e safe-run` (chant#4587, C1): run one command through
3
+ * {@link SafeRun}, so a bash driver gets the same environment and the same
4
+ * scan the TypeScript harness uses.
5
+ */
6
+ import { mkdtempSync } from "node:fs";
7
+ import { tmpdir } from "node:os";
8
+ import { join, resolve } from "node:path";
9
+ import { SafeRun } from "./safe-run";
10
+
11
+ /** Exit code when the scan finds a real cloud answering: nothing may be recorded. */
12
+ export const EXIT_REAL_CLOUD = 3;
13
+ /** Exit code for a usage error or an environment the wrapper refuses. */
14
+ export const EXIT_REFUSED = 2;
15
+
16
+ export interface SafeRunCommandInput {
17
+ command: string[];
18
+ /** Directories scanned after the run, beside the command's output. */
19
+ scan?: string[];
20
+ /** Where the log and the empty config dirs go; a fresh temp dir by default. */
21
+ scratch?: string;
22
+ /** The environment the wrapper scrubs; process.env by default. */
23
+ base?: Record<string, string | undefined>;
24
+ /** Pass the command's output through to this process's stdout and stderr (default true). */
25
+ echo?: boolean;
26
+ }
27
+
28
+ export async function runSafeRunCommand(i: SafeRunCommandInput): Promise<number> {
29
+ const scratch = i.scratch ?? mkdtempSync(join(tmpdir(), "chant-e2e-safe-run-"));
30
+ let safe: SafeRun;
31
+ try {
32
+ safe = new SafeRun({ scratch, scan: (i.scan ?? []).map((d) => resolve(d)), echo: i.echo ?? true }, i.base);
33
+ } catch (err) {
34
+ console.error(`e2e-safe-run: refused: ${err instanceof Error ? err.message : String(err)}`);
35
+ return EXIT_REFUSED;
36
+ }
37
+ let code: number;
38
+ try {
39
+ code = await safe.run(i.command);
40
+ } catch (err) {
41
+ console.error(`e2e-safe-run: could not run ${i.command[0]}: ${err instanceof Error ? err.message : String(err)}`);
42
+ return EXIT_REFUSED;
43
+ }
44
+ const verdict = safe.scan();
45
+ if (verdict.verdict === "CLEAN") {
46
+ console.log("CLEAN");
47
+ console.error(`e2e-safe-run: log ${safe.logFile}`);
48
+ return code;
49
+ }
50
+ console.error("REAL-CLOUD CALL: the output shows a public cloud rejecting a credential, so a call left this machine. This run is not recorded.");
51
+ for (const h of verdict.hits) console.error(` ${h}`);
52
+ console.error(`e2e-safe-run: log ${safe.logFile}`);
53
+ return EXIT_REAL_CLOUD;
54
+ }
@@ -0,0 +1,198 @@
1
+ /**
2
+ * The harness's one no-real-cloud wrapper (chant#4587), with plunge's rule
3
+ * (scripts/plunge-safe-run.sh, scripts/plunge-races/record.sh:8-11): every
4
+ * process a scenario starts runs with no real cloud credential in reach, its
5
+ * output is logged, and a run whose log shows a real cloud answering is
6
+ * never recorded. A row is written only after a CLEAN scan.
7
+ *
8
+ * What a command runs with: every AWS_*, AZURE_*, ARM_*, GOOGLE_*, CLOUDSDK_*
9
+ * and GCE_* variable unset (GOOGLE_APPLICATION_CREDENTIALS among them), then
10
+ * floci's test credentials, empty AWS config files, an empty CLOUDSDK_CONFIG
11
+ * and AZURE_CONFIG_DIR, a closed loopback GCE metadata host, no
12
+ * PULUMI_ACCESS_TOKEN, and a file:// Pulumi backend in the scratch
13
+ * directory (a backend already set is kept only when it is local).
14
+ *
15
+ * The scan looks for what a real cloud answers to a fake or missing
16
+ * credential, which no emulator says: UnrecognizedClientException,
17
+ * InvalidClientTokenId, invalid_grant, AADSTS, CREDENTIALS_MISSING, and a 401
18
+ * on a line naming googleapis.com, amazonaws.com, azure.com or windows.net.
19
+ */
20
+ import { spawn } from "node:child_process";
21
+ import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
22
+ import { join } from "node:path";
23
+ import type { OpRunRecordInput } from "../op/runtime";
24
+ import type { RunOrigin } from "../lifecycle/release-ledger";
25
+ import { claimRunRecordInput } from "./claim";
26
+ import type { ClaimRun } from "./driver";
27
+ import type { OutOfBand } from "./ports";
28
+ import type { ClaimRow } from "./schemas/index";
29
+
30
+ /** The prefixes of every variable a cloud SDK reads credentials or config from. */
31
+ export const CLOUD_ENV_PREFIXES = ["AWS_", "AZURE_", "ARM_", "GOOGLE_", "CLOUDSDK_", "GCE_"] as const;
32
+
33
+ const MARKERS = /UnrecognizedClientException|InvalidClientTokenId|invalid_grant|AADSTS[0-9]*|CREDENTIALS_MISSING/;
34
+ const CLOUD_HOSTS = /googleapis\.com|amazonaws\.com|azure\.com|windows\.net/;
35
+ const FOUR_OH_ONE = /(^|[^0-9])401([^0-9]|$)/;
36
+
37
+ /** A backend URL a run may keep: local files, or a bucket store on a loopback emulator. */
38
+ export function backendIsLocal(url: string, env: Record<string, string | undefined> = {}): boolean {
39
+ if (url.startsWith("file://") || url.startsWith("plunge+file://")) return true;
40
+ if (url.startsWith("plunge+s3://") || url.startsWith("plunge+azblob://")) {
41
+ return /[?&](endpoint=https?(:\/\/|%3A%2F%2F)(localhost|127\.0\.0\.1)([:/%]|$|&)|metadata_host=(localhost|127\.0\.0\.1)(:|%3A))/.test(url);
42
+ }
43
+ if (url.startsWith("plunge+gs://")) return /^(localhost|127\.0\.0\.1):[0-9]+$/.test(env.STORAGE_EMULATOR_HOST ?? "");
44
+ return false;
45
+ }
46
+
47
+ export interface SafeEnvOptions {
48
+ /** The scratch directory for the empty config locations and the state. */
49
+ scratch: string;
50
+ /** Variables set after the scrub: an emulator endpoint, BREAK=1. GOOGLE_APPLICATION_CREDENTIALS is refused. */
51
+ extra?: Record<string, string>;
52
+ }
53
+
54
+ /** The environment a scenario's processes run with, from `base` (default process.env). */
55
+ export function safeRunEnv(o: SafeEnvOptions, base: Record<string, string | undefined> = process.env): Record<string, string> {
56
+ for (const k of Object.keys(o.extra ?? {})) {
57
+ if (k === "GOOGLE_APPLICATION_CREDENTIALS") throw new Error("GOOGLE_APPLICATION_CREDENTIALS is refused: no credentials file may be in reach of a run");
58
+ }
59
+ const backend = base.PULUMI_BACKEND_URL;
60
+ if (backend && !backendIsLocal(backend, base)) {
61
+ throw new Error(`PULUMI_BACKEND_URL=${backend} is not a local backend (file://, plunge+file://, or a plunge store on a loopback emulator)`);
62
+ }
63
+ mkdirSync(o.scratch, { recursive: true });
64
+ const dir = mkdtempSync(join(o.scratch, "env-"));
65
+ for (const d of ["gcloud", "azure", "state"]) mkdirSync(join(dir, d), { recursive: true });
66
+ writeFileSync(join(dir, "aws-config"), "");
67
+ writeFileSync(join(dir, "aws-credentials"), "");
68
+
69
+ const env: Record<string, string> = {};
70
+ for (const [k, v] of Object.entries(base)) {
71
+ if (v === undefined || k === "PULUMI_ACCESS_TOKEN") continue;
72
+ if (CLOUD_ENV_PREFIXES.some((p) => k.startsWith(p))) continue;
73
+ env[k] = v;
74
+ }
75
+ Object.assign(env, {
76
+ AWS_ACCESS_KEY_ID: "test",
77
+ AWS_SECRET_ACCESS_KEY: "test",
78
+ AWS_REGION: "us-east-1",
79
+ AWS_EC2_METADATA_DISABLED: "true",
80
+ AWS_CONFIG_FILE: join(dir, "aws-config"),
81
+ AWS_SHARED_CREDENTIALS_FILE: join(dir, "aws-credentials"),
82
+ CLOUDSDK_CONFIG: join(dir, "gcloud"),
83
+ AZURE_CONFIG_DIR: join(dir, "azure"),
84
+ GCE_METADATA_HOST: "127.0.0.1:9",
85
+ PULUMI_SKIP_UPDATE_CHECK: "true",
86
+ PULUMI_SKIP_CONFIRMATIONS: "true",
87
+ PULUMI_BACKEND_URL: backend ?? `file://${join(dir, "state")}`,
88
+ });
89
+ Object.assign(env, o.extra ?? {});
90
+ return env;
91
+ }
92
+
93
+ /** The lines of `text` a real cloud wrote, as `<where>:<line>:<text>`. */
94
+ export function realCloudHits(text: string, where = "log"): string[] {
95
+ const out: string[] = [];
96
+ text.split("\n").forEach((line, i) => {
97
+ if (MARKERS.test(line) || (FOUR_OH_ONE.test(line) && CLOUD_HOSTS.test(line))) out.push(`${where}:${i + 1}:${line}`);
98
+ });
99
+ return out;
100
+ }
101
+
102
+ export type SafeVerdict = { verdict: "CLEAN" } | { verdict: "REAL-CLOUD"; hits: string[] };
103
+
104
+ function filesUnder(dir: string): string[] {
105
+ const out: string[] = [];
106
+ for (const name of readdirSync(dir)) {
107
+ const p = join(dir, name);
108
+ if (statSync(p).isDirectory()) out.push(...filesUnder(p));
109
+ else out.push(p);
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /**
115
+ * One scenario's wrapper: the scrubbed environment, the log every process's
116
+ * output goes to, and the scan at the end. A directory named in `scan` that
117
+ * does not exist when the scan runs is a hit, since it could not be checked.
118
+ */
119
+ export class SafeRun {
120
+ readonly env: Record<string, string>;
121
+ readonly logFile: string;
122
+
123
+ constructor(private readonly o: SafeEnvOptions & { logFile?: string; scan?: string[]; echo?: boolean }, base: Record<string, string | undefined> = process.env) {
124
+ this.env = safeRunEnv(o, base);
125
+ this.logFile = o.logFile ?? join(o.scratch, "safe-run.log");
126
+ appendFileSync(this.logFile, `e2e-safe-run: ${new Date().toISOString()} PULUMI_BACKEND_URL=${this.env.PULUMI_BACKEND_URL} CLOUDSDK_CONFIG=${this.env.CLOUDSDK_CONFIG}\n`);
127
+ }
128
+
129
+ log(line: string): void {
130
+ appendFileSync(this.logFile, line.endsWith("\n") ? line : `${line}\n`);
131
+ }
132
+
133
+ /** Run a command with the scrubbed environment, its output teed to the log. Resolves with its exit code. */
134
+ run(command: string[], extra: Record<string, string> = {}): Promise<number> {
135
+ const [file, ...args] = command;
136
+ if (!file) return Promise.reject(new Error("no command to run"));
137
+ this.log(`e2e-safe-run: command: ${command.map((a) => JSON.stringify(a)).join(" ")}`);
138
+ return new Promise((resolve, reject) => {
139
+ const child = spawn(file, args, { env: { ...this.env, ...extra }, stdio: ["ignore", "pipe", "pipe"] });
140
+ child.stdout.on("data", (b: Buffer) => {
141
+ appendFileSync(this.logFile, b);
142
+ if (this.o.echo) process.stdout.write(b);
143
+ });
144
+ child.stderr.on("data", (b: Buffer) => {
145
+ appendFileSync(this.logFile, b);
146
+ if (this.o.echo) process.stderr.write(b);
147
+ });
148
+ child.on("error", reject);
149
+ child.on("close", (code) => resolve(code ?? 1));
150
+ });
151
+ }
152
+
153
+ /** Out-of-band steps, run through this wrapper. */
154
+ outOfBand(): OutOfBand {
155
+ return { run: (command) => this.run(command) };
156
+ }
157
+
158
+ /** The scan of the log and every `scan` directory. Writes the verdict line to the log. */
159
+ scan(extraDirs: string[] = []): SafeVerdict {
160
+ const hits = realCloudHits(readFileSync(this.logFile, "utf8"), this.logFile);
161
+ for (const d of [...(this.o.scan ?? []), ...extraDirs]) {
162
+ if (!existsSync(d)) {
163
+ hits.push(`${d}: the scan directory does not exist after the run, so it could not be checked`);
164
+ continue;
165
+ }
166
+ for (const f of filesUnder(d)) if (f !== this.logFile) hits.push(...realCloudHits(readFileSync(f, "utf8"), f));
167
+ }
168
+ if (hits.length > 0) {
169
+ this.log(`e2e-safe-run: REAL-CLOUD CALL: the output shows a public cloud rejecting a credential, so a call left this machine. This run is not recorded.\n${hits.map((h) => ` ${h}`).join("\n")}`);
170
+ return { verdict: "REAL-CLOUD", hits };
171
+ }
172
+ this.log("e2e-safe-run: CLEAN");
173
+ return { verdict: "CLEAN" };
174
+ }
175
+ }
176
+
177
+ export interface RecordClaimInput {
178
+ row: ClaimRow;
179
+ run: ClaimRun;
180
+ /** The scan of the run. Anything but CLEAN is refused and nothing is written. */
181
+ verdict: SafeVerdict;
182
+ /** Append the run record to the ledger (appendRunRecord, then push chant/lifecycle). */
183
+ append(input: OpRunRecordInput): Promise<void>;
184
+ env?: string;
185
+ gitSha?: string;
186
+ runOrigin?: RunOrigin;
187
+ }
188
+
189
+ /** Record a claim run on the ledger, only after a CLEAN scan. */
190
+ export async function recordClaimRow(i: RecordClaimInput): Promise<OpRunRecordInput> {
191
+ if (i.verdict.verdict !== "CLEAN") {
192
+ throw new Error(`refusing to record ${i.row.scenario}/${i.row.claim}: the no-real-cloud scan found ${i.verdict.hits.length} real-cloud line(s)`);
193
+ }
194
+ if (i.row.safeRun !== "CLEAN") throw new Error(`refusing to record ${i.row.scenario}/${i.row.claim}: its row does not say CLEAN`);
195
+ const input = claimRunRecordInput({ row: i.row, run: i.run, env: i.env, gitSha: i.gitSha, runOrigin: i.runOrigin });
196
+ await i.append(input);
197
+ return input;
198
+ }
@@ -0,0 +1,89 @@
1
+ /**
2
+ * A scenario file (e2e-scenario/v1, chant#4587) and its lint. A scenario is
3
+ * a repo tree, an ordered list of pull request steps, and the outcomes each
4
+ * step must show. The lint refuses one that cannot record a row: no claim
5
+ * id, no BREAK arm, nothing to check, or a step that names a pull request or
6
+ * a merge no earlier step made.
7
+ */
8
+ import { readFileSync } from "node:fs";
9
+ import { validateScenario, type Scenario, type ScenarioStep } from "./schemas/index";
10
+
11
+ export interface ScenarioFinding {
12
+ /** Where, as a JSON pointer into the file. */
13
+ at: string;
14
+ message: string;
15
+ }
16
+
17
+ /** Every reason `data` is not a scenario the driver can run and record. Empty when it is one. */
18
+ export function lintScenario(data: unknown): ScenarioFinding[] {
19
+ const out: ScenarioFinding[] = [];
20
+ const doc = (data ?? {}) as Partial<Scenario> & Record<string, unknown>;
21
+ // The two refusals the protocol rests on, said plainly before the schema's wording.
22
+ if (typeof doc.claim !== "string" || doc.claim.trim() === "") out.push({ at: "/claim", message: "the scenario has no claim id, so its run would record a row for nothing" });
23
+ if (doc.break === undefined || doc.break === null) out.push({ at: "/break", message: "the scenario has no BREAK arm, so nothing shows its outcomes can fail" });
24
+ else if ((doc.break as { env?: Record<string, string> }).env?.BREAK !== "1") out.push({ at: "/break/env/BREAK", message: 'the BREAK arm must set BREAK to "1"' });
25
+
26
+ const v = validateScenario(data);
27
+ if (!v.ok) {
28
+ for (const e of v.errors) {
29
+ const [at, ...rest] = e.split(" ");
30
+ if ((at === "/" && /claim|break/.test(e)) || at!.startsWith("/break")) continue;
31
+ out.push({ at: at!, message: rest.join(" ") });
32
+ }
33
+ return out;
34
+ }
35
+ const s = v.value;
36
+
37
+ const seen = new Map<string, ScenarioStep>();
38
+ let expectations = 0;
39
+ s.steps.forEach((step, i) => {
40
+ const at = `/steps/${i}`;
41
+ if (seen.has(step.id)) out.push({ at: `${at}/id`, message: `step id ${step.id} is used twice` });
42
+ const opened = (id: string) => {
43
+ const o = seen.get(id);
44
+ return o !== undefined && (o.do === "open" || o.do === "open-concurrent");
45
+ };
46
+ switch (step.do) {
47
+ case "open-concurrent": {
48
+ const prev = s.steps[i - 1];
49
+ if (!prev || (prev.do !== "open" && prev.do !== "open-concurrent")) {
50
+ out.push({ at: `${at}/do`, message: "open-concurrent opens beside the step before it, which must be an open" });
51
+ }
52
+ break;
53
+ }
54
+ case "plan":
55
+ case "approve":
56
+ case "merge":
57
+ if (!opened(step.pull)) out.push({ at: `${at}/pull`, message: `${step.do} names ${step.pull}, which is not an earlier open step` });
58
+ break;
59
+ case "apply": {
60
+ const m = seen.get(step.merge);
61
+ if (!m || m.do !== "merge") out.push({ at: `${at}/merge`, message: `apply names ${step.merge}, which is not an earlier merge step` });
62
+ break;
63
+ }
64
+ default:
65
+ break;
66
+ }
67
+ for (const [j, e] of (step.expect ?? []).entries()) {
68
+ expectations++;
69
+ if ("report" in e && step.do !== "plan" && step.do !== "apply") {
70
+ out.push({ at: `${at}/expect/${j}`, message: `a report outcome belongs on a plan or apply step, not ${step.do}` });
71
+ }
72
+ if ("comment" in e && !("pull" in step) && step.do !== "open" && step.do !== "open-concurrent") {
73
+ out.push({ at: `${at}/expect/${j}`, message: "a comment outcome belongs on a step with a pull request" });
74
+ }
75
+ if ("exit" in e && step.do !== "out-of-band") out.push({ at: `${at}/expect/${j}`, message: "an exit outcome belongs on an out-of-band step" });
76
+ }
77
+ seen.set(step.id, step);
78
+ });
79
+ if (expectations === 0) out.push({ at: "/steps", message: "no step expects anything, so the plain run would pass and the BREAK run could never be caught" });
80
+ return out;
81
+ }
82
+
83
+ /** Read and lint a scenario file. Throws with every finding when it is not one. */
84
+ export function loadScenario(path: string): Scenario {
85
+ const data = JSON.parse(readFileSync(path, "utf8")) as unknown;
86
+ const findings = lintScenario(data);
87
+ if (findings.length > 0) throw new Error(`${path} is not a scenario the harness runs:\n${findings.map((f) => ` ${f.at}: ${f.message}`).join("\n")}`);
88
+ return data as Scenario;
89
+ }
@@ -0,0 +1,62 @@
1
+ # e2e harness schemas
2
+
3
+ JSON Schemas (draft 2020-12) of the e2e harness (chant#4587). `index.ts` exports their types and validators. The two demo schemas came from `examples/fan-out-estate/demo/schemas/`, where the fan-out demo's driver (#4091) and its readers (behold) use them; their design is INTENTIUS/chant#4085, section 3.
4
+
5
+ | Schema | Written to | When |
6
+ |---|---|---|
7
+ | `demo-step.schema.json` (`demo-step/v1`) | a demo's `step.json`, such as `s3://chant-demo/fan-out-estate/step.json` | at every step of a cycle |
8
+ | `demo-cycle.schema.json` (`demo-cycle/v1`) | `cycles/latest.json` and `cycles/<cycle>.json`, newest five | at reset, full cycles only |
9
+ | `e2e-scenario.schema.json` (`e2e-scenario/v1`) | a product's scenario files | by hand; `lintScenario` checks them |
10
+ | `e2e-claim-row.schema.json` (`e2e-claim-row/v1`) | the `claim` outcome of an `e2e-claim` run record on the ledger (#4551) | once per claim run, after a CLEAN scan |
11
+ | `e2e-claims.schema.json` (`e2e-claims/v1`) | the file a product's page reads | rendered from the ledger by `renderClaims` |
12
+
13
+ ## demo-step/v1
14
+
15
+ | Field | Required | Meaning |
16
+ |---|---|---|
17
+ | `$schema` | yes | The schema's `$id`. |
18
+ | `contract` | yes | `1`. |
19
+ | `demo` | yes | `fan-out-estate`. |
20
+ | `cycle` | yes | Cycle number. |
21
+ | `step` | yes | One of pull-request, planned, waiting, approved, merged, applying, failed, resumed, applied, reset, stalled. |
22
+ | `repo` | no | Forge repository, `chant-demo/fan-out-estate`. |
23
+ | `scenario`, `name`, `title`, `label` | no | Scenario id, display name, story title, one line narrating the step. |
24
+ | `highlight` | no | `{title, body}` or null: a call-out a viewer may show as a modal at the step that earns one. Cycle step items carry it too. |
25
+ | `chapter` | no | `{n, of, headline, short}` or null. Null only on the base and on a stall before the first step. |
26
+ | `started_at`, `at` | no | When the cycle started and when this step was written. |
27
+ | `next` | no | `{action, from, at}`: the driver's next action after the hold. |
28
+ | `pull`, `commit` | no | Pull request number and the commit the step concerns. |
29
+ | `reports` | no | `{url, plan?, apply?}`. `plan` and `apply` are `reportKey(pr, commit)` keys (`<pr>/<commit>`) below `url`. |
30
+ | `about` | no | `{changes, watch, shows}` cards. |
31
+
32
+ ## demo-cycle/v1
33
+
34
+ | Field | Required | Meaning |
35
+ |---|---|---|
36
+ | `$schema`, `contract`, `demo`, `cycle` | yes | As above. |
37
+ | `steps` | yes | The step records as written, each with `at`. `step` and `at` are required in each. |
38
+ | `repo`, `started`, `ended` | no | Repository and the cycle's start and end. |
39
+ | `reports` | no | `[{stage, pr, commit, key}]`, stage `plan` or `apply`, `key` from `reportKey(pr, commit)`. |
40
+
41
+ ## e2e-scenario/v1
42
+
43
+ | Field | Required | Meaning |
44
+ |---|---|---|
45
+ | `$schema`, `contract` | yes | The schema's `$id`, and `1`. |
46
+ | `id`, `product`, `claim` | yes | The scenario id, the product that drives it, and the claim id its row records. |
47
+ | `tree` | yes | `{base, overlays?}`: the repo the forge serves and the overlays steps copy over it, relative to the file. |
48
+ | `reportUrl` | yes | The pipeline's `--report-url`, `s3://<bucket>/<prefix>`. |
49
+ | `env` | no | The chant environment the ledger records runs under. Default `local`. |
50
+ | `limits` | no | Seconds per kind of step, over the defaults in `steps.ts`. |
51
+ | `steps` | yes | In order. `do` is open, open-concurrent, plan, approve, merge, apply, out-of-band or kill-job; each may carry `expect`. |
52
+ | `break` | yes | The BREAK arm: `env` with `BREAK: "1"`, and an optional `overlay` copied over every pull request of the break run. |
53
+
54
+ An outcome in `expect` has one key: `report` (`status`, `components`, `only`) on a plan or apply step, `ledger` (`op`, `status`, `count`), `comment`, `issue` (`title`, `open`), or `exit` on an out-of-band step.
55
+
56
+ ## e2e-claim-row/v1 and e2e-claims/v1
57
+
58
+ A row carries `product`, `productCommit` (40 hex), `scenario`, `claim`, `engine` (`binary`, `version`), `floci` (`sha256:` digest), `date` (`YYYY-MM-DD`), `plain` (`pass` or `fail`), `break` (`caught`, `missed` or `stalled`) and `safeRun`, which is always `CLEAN`. `chant` and `runUrl` are optional. e2e-claims/v1 is `{product, rows}`, the newest row per scenario and claim.
59
+
60
+ ## Versioning
61
+
62
+ Each contract is versioned like the workspace read contract. Within `contract: 1` a field is only ever added, and a new field is optional. Readers ignore fields they do not know, and a reader treats a step it does not know as one it cannot classify. The `step` enum of demo-step lists what a writer may write in this version; a new step is added to it within contract 1, so a reader never rejects a record for its step. A rename or removal is `contract: 2` with a new `$id` path (`v2`).