@intentius/chant 0.124.87 → 0.124.88

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (342) hide show
  1. package/dist/action-pins.d.ts +1 -0
  2. package/dist/action-pins.d.ts.map +1 -1
  3. package/dist/action-pins.js +2 -0
  4. package/dist/actor.d.ts +12 -0
  5. package/dist/actor.d.ts.map +1 -0
  6. package/dist/actor.js +18 -0
  7. package/dist/bundle-check.d.ts +20 -5
  8. package/dist/bundle-check.d.ts.map +1 -1
  9. package/dist/bundle-check.js +20 -5
  10. package/dist/chant-install.d.ts +98 -0
  11. package/dist/chant-install.d.ts.map +1 -1
  12. package/dist/chant-install.js +204 -2
  13. package/dist/ci-commit.d.ts +1 -1
  14. package/dist/ci-commit.d.ts.map +1 -1
  15. package/dist/ci-commit.js +1 -2
  16. package/dist/ci-control.d.ts +1 -1
  17. package/dist/ci-control.d.ts.map +1 -1
  18. package/dist/ci-control.js +1 -1
  19. package/dist/ci-evidence-claims.d.ts +59 -0
  20. package/dist/ci-evidence-claims.d.ts.map +1 -0
  21. package/dist/ci-evidence-claims.js +87 -0
  22. package/dist/ci-evidence-from-job.d.ts +103 -0
  23. package/dist/ci-evidence-from-job.d.ts.map +1 -0
  24. package/dist/ci-evidence-from-job.js +162 -0
  25. package/dist/ci-evidence-jobs.d.ts +39 -4
  26. package/dist/ci-evidence-jobs.d.ts.map +1 -1
  27. package/dist/ci-evidence-jobs.js +38 -4
  28. package/dist/ci-handover.d.ts +12 -0
  29. package/dist/ci-handover.d.ts.map +1 -1
  30. package/dist/ci-handover.js +15 -3
  31. package/dist/ci-identity.d.ts +32 -6
  32. package/dist/ci-identity.d.ts.map +1 -1
  33. package/dist/ci-identity.js +40 -8
  34. package/dist/ci-image.d.ts +47 -9
  35. package/dist/ci-image.d.ts.map +1 -1
  36. package/dist/ci-image.js +45 -18
  37. package/dist/ci-jobs.d.ts +1 -1
  38. package/dist/ci-jobs.d.ts.map +1 -1
  39. package/dist/ci-jobs.js +7 -2
  40. package/dist/ci-login.d.ts +75 -13
  41. package/dist/ci-login.d.ts.map +1 -1
  42. package/dist/ci-login.js +89 -37
  43. package/dist/ci-product-words.d.ts +20 -1
  44. package/dist/ci-product-words.d.ts.map +1 -1
  45. package/dist/ci-product-words.js +27 -1
  46. package/dist/ci-product.d.ts +21 -2
  47. package/dist/ci-product.d.ts.map +1 -1
  48. package/dist/ci-product.js +21 -2
  49. package/dist/cli/handlers/approve-confirm.d.ts +14 -0
  50. package/dist/cli/handlers/approve-confirm.d.ts.map +1 -1
  51. package/dist/cli/handlers/approve-confirm.js +46 -0
  52. package/dist/cli/handlers/build.d.ts +1 -1
  53. package/dist/cli/handlers/build.d.ts.map +1 -1
  54. package/dist/cli/handlers/build.js +22 -1
  55. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  56. package/dist/cli/handlers/ci-check.js +21 -1
  57. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  58. package/dist/cli/handlers/ci-evidence.js +227 -18
  59. package/dist/cli/handlers/ci-forge-check.d.ts.map +1 -1
  60. package/dist/cli/handlers/ci-forge-check.js +34 -17
  61. package/dist/cli/handlers/generated-check.d.ts +3 -0
  62. package/dist/cli/handlers/generated-check.d.ts.map +1 -0
  63. package/dist/cli/handlers/generated-check.js +41 -0
  64. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  65. package/dist/cli/handlers/lifecycle.js +3 -0
  66. package/dist/cli/handlers/local-chant.d.ts +13 -0
  67. package/dist/cli/handlers/local-chant.d.ts.map +1 -1
  68. package/dist/cli/handlers/local-chant.js +42 -1
  69. package/dist/cli/handlers/pr.d.ts.map +1 -1
  70. package/dist/cli/handlers/pr.js +42 -5
  71. package/dist/cli/handlers/run-wave.js +8 -0
  72. package/dist/cli/main.d.ts.map +1 -1
  73. package/dist/cli/main.js +38 -4
  74. package/dist/cli/parse-args.d.ts.map +1 -1
  75. package/dist/cli/parse-args.js +66 -0
  76. package/dist/cli/registry.d.ts +24 -0
  77. package/dist/cli/registry.d.ts.map +1 -1
  78. package/dist/components/check-hooks.d.ts +10 -0
  79. package/dist/components/check-hooks.d.ts.map +1 -1
  80. package/dist/components/check-hooks.js +18 -0
  81. package/dist/components/pr-checks.d.ts +105 -0
  82. package/dist/components/pr-checks.d.ts.map +1 -0
  83. package/dist/components/pr-checks.js +119 -0
  84. package/dist/components/pr-pipeline.d.ts +34 -0
  85. package/dist/components/pr-pipeline.d.ts.map +1 -1
  86. package/dist/components/pr-pipeline.js +14 -1
  87. package/dist/components/product-pipeline.d.ts +16 -1
  88. package/dist/components/product-pipeline.d.ts.map +1 -1
  89. package/dist/components/product-pipeline.js +17 -2
  90. package/dist/components/product-plan.d.ts +257 -4
  91. package/dist/components/product-plan.d.ts.map +1 -1
  92. package/dist/components/product-plan.js +241 -11
  93. package/dist/config.d.ts +10 -6
  94. package/dist/config.d.ts.map +1 -1
  95. package/dist/config.js +11 -6
  96. package/dist/control/consumers.d.ts +6 -0
  97. package/dist/control/consumers.d.ts.map +1 -1
  98. package/dist/control/consumers.js +6 -0
  99. package/dist/dead-guards.d.ts.map +1 -1
  100. package/dist/dead-guards.js +9 -6
  101. package/dist/discovery/files.d.ts +1 -1
  102. package/dist/discovery/files.js +1 -1
  103. package/dist/drift-issue.d.ts +20 -3
  104. package/dist/drift-issue.d.ts.map +1 -1
  105. package/dist/drift-issue.js +16 -0
  106. package/dist/drift-record.d.ts +45 -5
  107. package/dist/drift-record.d.ts.map +1 -1
  108. package/dist/drift-record.js +27 -6
  109. package/dist/floor-table.d.ts +6 -6
  110. package/dist/floor-table.d.ts.map +1 -1
  111. package/dist/floor-table.data.d.ts.map +1 -1
  112. package/dist/floor-table.data.js +58 -21
  113. package/dist/floor-table.js +10 -7
  114. package/dist/forge-check/contract.d.ts +8 -0
  115. package/dist/forge-check/contract.d.ts.map +1 -1
  116. package/dist/forge-check/contract.js +4 -1
  117. package/dist/forge-check/index.d.ts +2 -0
  118. package/dist/forge-check/index.d.ts.map +1 -1
  119. package/dist/forge-check/index.js +2 -0
  120. package/dist/forge-flags.d.ts +10 -0
  121. package/dist/forge-flags.d.ts.map +1 -1
  122. package/dist/forge-flags.js +31 -0
  123. package/dist/forge-remote.d.ts +47 -0
  124. package/dist/forge-remote.d.ts.map +1 -0
  125. package/dist/forge-remote.js +69 -0
  126. package/dist/generated-check.d.ts +74 -0
  127. package/dist/generated-check.d.ts.map +1 -0
  128. package/dist/generated-check.js +216 -0
  129. package/dist/lexicon.d.ts +16 -0
  130. package/dist/lexicon.d.ts.map +1 -1
  131. package/dist/lifecycle/publish-npm.d.ts +15 -0
  132. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  133. package/dist/lifecycle/publish-npm.js +49 -3
  134. package/dist/lifecycle/release-images.d.ts +22 -1
  135. package/dist/lifecycle/release-images.d.ts.map +1 -1
  136. package/dist/lifecycle/release-images.js +27 -3
  137. package/dist/lifecycle/release-ledger.d.ts +4 -3
  138. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  139. package/dist/lifecycle/release-ledger.js +3 -2
  140. package/dist/local-chant.d.ts +57 -3
  141. package/dist/local-chant.d.ts.map +1 -1
  142. package/dist/local-chant.js +122 -13
  143. package/dist/op/op-waves-evidence-jobs.d.ts +92 -0
  144. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -0
  145. package/dist/op/op-waves-evidence-jobs.js +112 -0
  146. package/dist/op/op-waves-evidence.d.ts +12 -1
  147. package/dist/op/op-waves-evidence.d.ts.map +1 -1
  148. package/dist/op/op-waves-evidence.js +23 -2
  149. package/dist/op/op-waves-run.d.ts +12 -1
  150. package/dist/op/op-waves-run.d.ts.map +1 -1
  151. package/dist/op/op-waves-run.js +54 -3
  152. package/dist/op/op-waves.d.ts +8 -0
  153. package/dist/op/op-waves.d.ts.map +1 -1
  154. package/dist/op/op-waves.js +10 -0
  155. package/dist/op/schedule-overdue.d.ts +39 -2
  156. package/dist/op/schedule-overdue.d.ts.map +1 -1
  157. package/dist/op/schedule-overdue.js +89 -7
  158. package/dist/pr-forge-reads.d.ts +21 -1
  159. package/dist/pr-forge-reads.d.ts.map +1 -1
  160. package/dist/pr-forge-reads.js +19 -1
  161. package/dist/pr-forge.d.ts +7 -1
  162. package/dist/pr-forge.d.ts.map +1 -1
  163. package/dist/pr-forge.js +7 -2
  164. package/dist/pr-plan-note.d.ts +24 -0
  165. package/dist/pr-plan-note.d.ts.map +1 -1
  166. package/dist/pr-plan-note.js +11 -1
  167. package/dist/pr-plan-record.d.ts +47 -0
  168. package/dist/pr-plan-record.d.ts.map +1 -0
  169. package/dist/pr-plan-record.js +89 -0
  170. package/dist/pr-post.d.ts +40 -0
  171. package/dist/pr-post.d.ts.map +1 -1
  172. package/dist/pr-post.js +79 -6
  173. package/dist/pr-requires.d.ts +8 -0
  174. package/dist/pr-requires.d.ts.map +1 -1
  175. package/dist/pr-requires.js +3 -1
  176. package/dist/ref-gate-init.d.ts +76 -0
  177. package/dist/ref-gate-init.d.ts.map +1 -0
  178. package/dist/ref-gate-init.js +144 -0
  179. package/dist/ref-gate-rules.d.ts +19 -0
  180. package/dist/ref-gate-rules.d.ts.map +1 -0
  181. package/dist/ref-gate-rules.js +17 -0
  182. package/dist/release-floors.d.ts +64 -16
  183. package/dist/release-floors.d.ts.map +1 -1
  184. package/dist/release-floors.js +65 -17
  185. package/dist/state-migration.d.ts +24 -1
  186. package/dist/state-migration.d.ts.map +1 -1
  187. package/dist/state-migration.js +39 -3
  188. package/dist/state-unlock.d.ts +32 -1
  189. package/dist/state-unlock.d.ts.map +1 -1
  190. package/dist/state-unlock.js +31 -0
  191. package/dist/wave-runtime.mjs +292 -285
  192. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  193. package/dist/workspace/ci-green-cli.js +13 -7
  194. package/dist/workspace/drift-cli.d.ts +1 -1
  195. package/dist/workspace/drift-cli.d.ts.map +1 -1
  196. package/dist/workspace/drift-cli.js +5 -12
  197. package/dist/workspace/forge-work.d.ts +3 -2
  198. package/dist/workspace/forge-work.d.ts.map +1 -1
  199. package/dist/workspace/forge-work.js +7 -17
  200. package/dist/workspace/lexicon-outputs.js +2 -2
  201. package/dist/workspace/release-workflow.d.ts +26 -3
  202. package/dist/workspace/release-workflow.d.ts.map +1 -1
  203. package/dist/workspace/release-workflow.js +48 -6
  204. package/dist/workspace/trust/check-evidence-report.d.ts +18 -0
  205. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  206. package/dist/workspace/trust/check-evidence-report.js +13 -0
  207. package/dist/workspace/trust/check-evidence.d.ts +13 -1
  208. package/dist/workspace/trust/check-evidence.d.ts.map +1 -1
  209. package/dist/workspace/trust/check-evidence.js +8 -3
  210. package/dist/workspace/trust/evidence.d.ts +5 -0
  211. package/dist/workspace/trust/evidence.d.ts.map +1 -1
  212. package/dist/workspace/trust/evidence.js +5 -0
  213. package/dist/workspace/trust/open-evidence.d.ts +67 -0
  214. package/dist/workspace/trust/open-evidence.d.ts.map +1 -0
  215. package/dist/workspace/trust/open-evidence.js +92 -0
  216. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  217. package/dist/workspace/trust/ref-gate-cli.js +65 -3
  218. package/dist/workspace/trust/ref-gate.d.ts +61 -2
  219. package/dist/workspace/trust/ref-gate.d.ts.map +1 -1
  220. package/dist/workspace/trust/ref-gate.js +72 -7
  221. package/package.json +1 -1
  222. package/src/action-pins.ts +2 -0
  223. package/src/actor.test.ts +12 -0
  224. package/src/actor.ts +19 -0
  225. package/src/bundle-check.test.ts +22 -0
  226. package/src/bundle-check.ts +33 -5
  227. package/src/chant-install.test.ts +109 -1
  228. package/src/chant-install.ts +243 -2
  229. package/src/ci-commit.test.ts +51 -5
  230. package/src/ci-commit.ts +1 -2
  231. package/src/ci-control.ts +1 -0
  232. package/src/ci-evidence-claims.ts +102 -0
  233. package/src/ci-evidence-from-job.test.ts +147 -0
  234. package/src/ci-evidence-from-job.ts +195 -0
  235. package/src/ci-evidence-jobs.ts +41 -4
  236. package/src/ci-handover.ts +16 -3
  237. package/src/ci-identity.test.ts +3 -3
  238. package/src/ci-identity.ts +51 -11
  239. package/src/ci-image.test.ts +60 -10
  240. package/src/ci-image.ts +78 -19
  241. package/src/ci-jobs.ts +7 -2
  242. package/src/ci-login.test.ts +131 -3
  243. package/src/ci-login.token-drop.test.ts +204 -0
  244. package/src/ci-login.ts +137 -39
  245. package/src/ci-product-words.ts +30 -0
  246. package/src/ci-product.ts +26 -1
  247. package/src/cli/commands/__fixtures__/source-dir-root/migrations/0001-init/backfill.ts +3 -0
  248. package/src/cli/handlers/approve-confirm.test.ts +35 -0
  249. package/src/cli/handlers/approve-confirm.ts +44 -0
  250. package/src/cli/handlers/build-source-dir.test.ts +4 -0
  251. package/src/cli/handlers/build.ts +20 -2
  252. package/src/cli/handlers/ci-check.ts +19 -1
  253. package/src/cli/handlers/ci-evidence-open.test.ts +164 -0
  254. package/src/cli/handlers/ci-evidence.ts +210 -16
  255. package/src/cli/handlers/ci-forge-check.ts +22 -9
  256. package/src/cli/handlers/generated-check.ts +39 -0
  257. package/src/cli/handlers/lifecycle.test.ts +20 -0
  258. package/src/cli/handlers/lifecycle.ts +4 -0
  259. package/src/cli/handlers/local-chant.ts +39 -1
  260. package/src/cli/handlers/pr.ts +43 -5
  261. package/src/cli/handlers/run-wave.ts +7 -0
  262. package/src/cli/main.ts +38 -4
  263. package/src/cli/parse-args.ts +46 -0
  264. package/src/cli/registry.ts +24 -0
  265. package/src/components/check-hooks.ts +22 -0
  266. package/src/components/check-report-summary.test.ts +78 -0
  267. package/src/components/pr-checks.ts +159 -0
  268. package/src/components/pr-pipeline.ts +41 -1
  269. package/src/components/product-pipeline.ts +25 -3
  270. package/src/components/product-plan.test.ts +102 -1
  271. package/src/components/product-plan.ts +416 -15
  272. package/src/config.ts +13 -8
  273. package/src/control/consumers.ts +7 -0
  274. package/src/dead-guards.test.ts +27 -5
  275. package/src/dead-guards.ts +9 -6
  276. package/src/discovery/files.ts +1 -1
  277. package/src/drift-issue.test.ts +29 -1
  278. package/src/drift-issue.ts +28 -3
  279. package/src/drift-record.test.ts +25 -0
  280. package/src/drift-record.ts +55 -6
  281. package/src/floor-table.data.ts +58 -21
  282. package/src/floor-table.ts +12 -9
  283. package/src/forge-check/contract.ts +11 -1
  284. package/src/forge-check/forge-check.test.ts +8 -0
  285. package/src/forge-check/index.ts +2 -0
  286. package/src/forge-flags.test.ts +25 -1
  287. package/src/forge-flags.ts +34 -0
  288. package/src/forge-remote.test.ts +37 -0
  289. package/src/forge-remote.ts +79 -0
  290. package/src/generated-check.e2e.test.ts +98 -0
  291. package/src/generated-check.test.ts +104 -0
  292. package/src/generated-check.ts +269 -0
  293. package/src/lexicon.ts +17 -0
  294. package/src/lifecycle/publish-npm.ts +56 -3
  295. package/src/lifecycle/release-catalog.test.ts +2 -2
  296. package/src/lifecycle/release-images-dockerfile.test.ts +20 -0
  297. package/src/lifecycle/release-images.test.ts +44 -0
  298. package/src/lifecycle/release-images.ts +39 -3
  299. package/src/lifecycle/release-ledger.ts +4 -3
  300. package/src/local-chant.e2e.test.ts +81 -6
  301. package/src/local-chant.test.ts +22 -3
  302. package/src/local-chant.ts +130 -13
  303. package/src/op/op-waves-evidence-jobs.ts +134 -0
  304. package/src/op/op-waves-evidence.test.ts +36 -3
  305. package/src/op/op-waves-evidence.ts +23 -3
  306. package/src/op/op-waves-run.ts +57 -2
  307. package/src/op/op-waves.ts +11 -0
  308. package/src/op/schedule-overdue.test.ts +83 -1
  309. package/src/op/schedule-overdue.ts +107 -9
  310. package/src/pr-forge-reads-compare.test.ts +2 -1
  311. package/src/pr-forge-reads.ts +37 -1
  312. package/src/pr-forge.ts +14 -3
  313. package/src/pr-plan-note.ts +32 -3
  314. package/src/pr-plan-record.test.ts +75 -0
  315. package/src/pr-plan-record.ts +101 -0
  316. package/src/pr-post-plan-note.test.ts +60 -0
  317. package/src/pr-post.test.ts +30 -0
  318. package/src/pr-post.ts +110 -6
  319. package/src/pr-requires.test.ts +20 -0
  320. package/src/pr-requires.ts +10 -1
  321. package/src/ref-gate-init.ts +189 -0
  322. package/src/ref-gate-rules.ts +26 -0
  323. package/src/release-floors.ts +86 -17
  324. package/src/state-migration-record.test.ts +90 -0
  325. package/src/state-migration.test.ts +1 -1
  326. package/src/state-migration.ts +52 -3
  327. package/src/state-unlock.test.ts +33 -1
  328. package/src/state-unlock.ts +49 -1
  329. package/src/workspace/ci-green-cli.ts +12 -6
  330. package/src/workspace/drift-cli.ts +6 -18
  331. package/src/workspace/forge-work.ts +7 -14
  332. package/src/workspace/lexicon-outputs.ts +2 -2
  333. package/src/workspace/release-workflow.test.ts +70 -0
  334. package/src/workspace/release-workflow.ts +56 -8
  335. package/src/workspace/trust/check-evidence-report.ts +24 -0
  336. package/src/workspace/trust/check-evidence.ts +17 -5
  337. package/src/workspace/trust/evidence.ts +5 -0
  338. package/src/workspace/trust/open-evidence.ts +129 -0
  339. package/src/workspace/trust/ref-gate-cli.ts +59 -3
  340. package/src/workspace/trust/ref-gate-pieces.test.ts +175 -0
  341. package/src/workspace/trust/ref-gate.e2e.test.ts +17 -0
  342. package/src/workspace/trust/ref-gate.ts +87 -6
@@ -13,6 +13,12 @@
13
13
  * `policy:<wave>` when `ci.policy` ran over the plans and denied nothing.
14
14
  * They are attached under `refs/notes/chant/evidence` and pushed, where #4867's ref gate
15
15
  * and a later wave read them.
16
+ * - A generated pipeline (#4926) runs the wave's policy as a step of its own
17
+ * (`--policy-only`; on GitLab a `<wave job>-policy` job) and signs
18
+ * `policy:<wave>` in an evidence job after the wave job, from the forge's
19
+ * record of that step; a wave that trades cloud credentials and signs
20
+ * keyless signs `plan:<wave>` there too. `CHANT_WAVE_EVIDENCE` tells the
21
+ * command step which of the two it still signs itself.
16
22
  *
17
23
  * See ../workspace/trust/check-evidence.ts.
18
24
  */
@@ -20,6 +26,7 @@
20
26
  import { execFileSync } from "node:child_process";
21
27
  import type { OpRunPolicyRow } from "./runtime";
22
28
  export { opWavesEvidenceProblems, type OpWavesEvidence } from "./op-waves-evidence-spec";
29
+ import { WAVE_EVIDENCE_ENV, writeCheckClaimFile } from "../ci-evidence-claims";
23
30
  import { CHECK_EVIDENCE_KEY_ENV, missingCheckEvidence, recordChecks, RUNNER_IDENTITY_ENV, runnerEvidenceSigner, signChecks } from "../workspace/trust/check-evidence";
24
31
 
25
32
  function top(cwd: string): string {
@@ -32,20 +39,33 @@ export async function opWaveEvidenceRefusal(cwd: string, head: string, base: str
32
39
  return missingCheckEvidence(top(cwd), head, base, requires);
33
40
  }
34
41
 
42
+ export { WAVE_EVIDENCE_ENV };
43
+
35
44
  /**
36
45
  * Sign the wave's plan and policy checks when the job has a runner identity.
37
46
  * Never fails the wave: a key or identity the policy at base does not list, or a
38
- * notes push that does not land, is a line in the log.
47
+ * notes push that does not land, is a line in the log. With
48
+ * `CHANT_WAVE_EVIDENCE` (#4926) it signs only what that leaves to the step,
49
+ * and writes the plan's claim file in `checksDir`.
39
50
  */
40
- export async function signOpWaveChecks(input: { cwd: string; head: string; base: string; wave: string; planDigest?: string; policyRows: ReadonlyMap<string, OpRunPolicyRow>; log: (line: string) => void; env?: NodeJS.ProcessEnv; push?: boolean; fetch?: typeof fetch }): Promise<string[]> {
51
+ export async function signOpWaveChecks(input: { cwd: string; head: string; base: string; wave: string; planDigest?: string; policyRows: ReadonlyMap<string, OpRunPolicyRow>; log: (line: string) => void; env?: NodeJS.ProcessEnv; push?: boolean; fetch?: typeof fetch; checksDir?: string }): Promise<string[]> {
41
52
  const env = input.env ?? process.env;
53
+ const mode = env[WAVE_EVIDENCE_ENV];
54
+ if (mode && input.checksDir) {
55
+ try {
56
+ writeCheckClaimFile(input.checksDir, { check: `plan:${input.wave}`, passed: true, ...(input.planDigest ? { claim: input.planDigest } : {}) });
57
+ } catch (err) {
58
+ input.log(`wave ${input.wave}: the plan's claim file was not written: ${err instanceof Error ? err.message : String(err)}`);
59
+ }
60
+ }
61
+ if (mode === "job") return [];
42
62
  if (!env[CHECK_EVIDENCE_KEY_ENV] && !env[RUNNER_IDENTITY_ENV]) return [];
43
63
  try {
44
64
  const repo = top(input.cwd);
45
65
  const signer = (await runnerEvidenceSigner(repo, input.base, { env, ...(input.fetch ? { fetch: input.fetch } : {}) }))!;
46
66
  const rows = [...input.policyRows.values()];
47
67
  const checks: Array<{ check: string; claim?: string }> = [{ check: `plan:${input.wave}`, ...(input.planDigest ? { claim: input.planDigest } : {}) }];
48
- if (rows.length > 0 && rows.every((r) => r.result !== "denied")) checks.push({ check: `policy:${input.wave}`, claim: JSON.stringify(rows) });
68
+ if (mode !== "plan" && rows.length > 0 && rows.every((r) => r.result !== "denied")) checks.push({ check: `policy:${input.wave}`, claim: JSON.stringify(rows) });
49
69
  const signed = await signChecks(repo, input.head, checks, signer);
50
70
  const pushed = await recordChecks(repo, signed, { push: input.push !== false });
51
71
  if (input.push !== false && !pushed.pushed && pushed.pushWarning) input.log(`wave ${input.wave}: ${pushed.pushWarning}`);
@@ -91,6 +91,7 @@ import { ciRunIdFromEnv } from "./gate-run-locator";
91
91
  import { appendRunRecord, DEFAULT_RUN_ENV } from "../lifecycle/run-ledger";
92
92
  import { LifecyclePushLostError, pushLifecycleRebasing } from "../lifecycle/git";
93
93
  import { opWaveEvidenceRefusal, signOpWaveChecks } from "./op-waves-evidence";
94
+ import { writeCheckClaimFile } from "../ci-evidence-claims";
94
95
  import { opWavesEvidenceProblems, type OpWavesEvidence } from "./op-waves-evidence-spec";
95
96
  import { resolveCiJob } from "../lifecycle/release-ledger";
96
97
  import type { OpRunPolicyRow, OpRunRecordInput, OpRunStepRecord, OpRunWave, OpRunWavePlan, OpRunWaveTarget } from "./runtime";
@@ -143,6 +144,7 @@ import {
143
144
  opWaveGateName,
144
145
  opWaveHooksAt,
145
146
  opWaveHookRuns,
147
+ opWaveChecksDir,
146
148
  opWaveOutcomeDir,
147
149
  opWavePointAt,
148
150
  opWavePointProblems,
@@ -785,6 +787,15 @@ export interface RunOpWaveOptions {
785
787
  wave: number;
786
788
  /** Plan and decide only (a wide wave's deciding job). */
787
789
  decide?: boolean;
790
+ /**
791
+ * Plan the wave and run its policy hold, and nothing after it (#4926): the
792
+ * wave job's policy step, whose result the forge reports and the wave's
793
+ * evidence job signs `policy:<wave>` from. Exits 0 only when `ci.policy`
794
+ * ran over the wave's plans and denied nothing, 7 when it denied a run, 1
795
+ * when it did not run. Writes the check's claim file under
796
+ * {@link opWaveChecksDir} and no outcome file or run record.
797
+ */
798
+ policyOnly?: boolean;
788
799
  /** Apply this 1-based share of a decided wave, or with `group`, of that job group. */
789
800
  share?: number;
790
801
  /**
@@ -969,6 +980,8 @@ export interface RunOpWaveResult {
969
980
  targets?: Record<string, OpRunWaveTarget>;
970
981
  /** Each planned run with policy rows or an after-plan hook's files (#4614), as the run record's `wave.plans`. */
971
982
  plans?: Record<string, OpRunWavePlan>;
983
+ /** With `policyOnly` (#4926): the `ci.policy` rows the wave's policy hold gave, in run order. Empty when no policy ran. */
984
+ policyRows?: OpRunPolicyRow[];
972
985
  }
973
986
 
974
987
  /** What one wave job works with. */
@@ -2045,6 +2058,8 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
2045
2058
  if (afterPlanWrong.length > 0) throw new Error(`Op waves "${options.spec.name}": ${afterPlanWrong.join("; ")}`);
2046
2059
  const runHooksWrong = opWaveRunHooksProblems(options.runHooks);
2047
2060
  if (runHooksWrong.length > 0) throw new Error(`Op waves "${options.spec.name}": ${runHooksWrong.join("; ")}`);
2061
+ // #4926: the policy step applies nothing, so it keeps no run record and no outcome file.
2062
+ if (options.policyOnly) return runOpWavePolicyOnly(options);
2048
2063
  // #4551: one run record per job, on every way the job ends.
2049
2064
  const started = new Date().toISOString();
2050
2065
  // #4555: the job's run events and its trace, when a reader or an exporter wants them.
@@ -2324,6 +2339,41 @@ async function runOpWaveJob(options: RunOpWaveOptions): Promise<RunOpWaveResult>
2324
2339
  return result;
2325
2340
  }
2326
2341
 
2342
+ /**
2343
+ * The wave job's policy step (#4926): plan the wave, run its policy hold,
2344
+ * and write `policy:<wave>`'s claim file, passed only when `ci.policy` ran
2345
+ * over the plans and denied nothing. The exit says the same, so the forge's
2346
+ * record of the step (GitLab: of the `<wave>-policy` job) carries it where
2347
+ * the change's code in the later steps cannot rewrite it. A share or job
2348
+ * group's job has no policy of its own; its deciding job's stands.
2349
+ */
2350
+ async function runOpWavePolicyOnly(options: RunOpWaveOptions): Promise<RunOpWaveResult> {
2351
+ const { spec } = options;
2352
+ if (options.share !== undefined || options.group !== undefined) throw new Error("--policy-only runs a wave's policy in its own or its deciding job; a share or job group's job has none of its own");
2353
+ const log = options.log ?? ((line: string) => console.error(line));
2354
+ const cwd = options.cwd ?? process.cwd();
2355
+ const outcomeDir = options.outcomeDir ?? opWaveOutcomeDir(spec);
2356
+ const dir = isAbsolute(outcomeDir) ? outcomeDir : join(cwd, outcomeDir);
2357
+ const wave = spec.waves[options.wave - 1] ?? spec.waves[spec.waves.length - 1]!;
2358
+ const check = `policy:${wave.name}`;
2359
+ const end = (exitCode: number, rows: OpRunPolicyRow[], line?: string): RunOpWaveResult => {
2360
+ if (line) log(line);
2361
+ const passed = exitCode === 0;
2362
+ writeCheckClaimFile(join(cwd, opWaveChecksDir(spec)), { check, passed, ...(passed ? { claim: JSON.stringify(rows) } : {}) });
2363
+ return { exitCode, applied: [], failed: [], moved: [], hooks: [], policyRows: rows };
2364
+ };
2365
+ const before = opWaveBefore(options, dir);
2366
+ if (before.stop) return end(CHANT_EXIT.failed, [], `${before.stop.line}; wave ${options.wave}'s policy did not run`);
2367
+ const step = await planOpWave(options, { k: options.wave, pass: 0 }, before.blocked);
2368
+ const got = "end" in step ? step.end : undefined;
2369
+ const rows = got?.policyRows ?? [];
2370
+ if (!got || got.exitCode !== 0 || got.policyRows === undefined) return end(got && got.exitCode !== 0 ? got.exitCode : CHANT_EXIT.failed, rows, `wave ${options.wave} (${wave.name}): its policy did not run to the end, so ${check} did not pass`);
2371
+ if (rows.length === 0) return end(CHANT_EXIT.failed, rows, `wave ${options.wave} (${wave.name}): no ci.policy ran over its plans (holds.policy is off, or the hold at base could not be read), so ${check} did not pass`);
2372
+ const denied = rows.filter((r) => r.result === "denied");
2373
+ if (denied.length > 0) return end(CHANT_EXIT.denied, rows, `wave ${options.wave} (${wave.name}): ci.policy denied ${denied.length} of its ${rows.length} plans, so ${check} did not pass`);
2374
+ return end(CHANT_EXIT.done, rows, `wave ${options.wave} (${wave.name}): ci.policy ran over its ${rows.length} plans and denied none`);
2375
+ }
2376
+
2327
2377
  /** The wave engine's loop over this module's steps, from `options.wave` on, with the runs in `skip` left out of that wave. */
2328
2378
  async function runOpWaveLoop(options: RunOpWaveOptions, log: (line: string) => void, applied: string[], skip: ReadonlyMap<string, string>): Promise<RunOpWaveResult> {
2329
2379
  const { spec } = options;
@@ -2658,6 +2708,8 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2658
2708
  }
2659
2709
  const before = await runBeforePlanHooks(ctx, rules.hooks, wave.runs);
2660
2710
  if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
2711
+ // #4926: the policy step records no decision; the wave's own step does.
2712
+ if (before.waitingOn && options.policyOnly) return { end: failed(ctx, `wave ${k} (${wave.name}): a hook before the plan waits on ${before.waitingOn}, so its policy did not run`) };
2661
2713
  if (before.waitingOn) return { end: await decided(ctx, decision, recordPath, before.waitingOn) };
2662
2714
  if (spec.step) ctx.steps = new Map();
2663
2715
  const { members, pending: planPending, overriders: planOverriders, overridersSource: planOverridersSource, extras: planExtras, waves: found, changeSet, parts } = await planWaveRuns(ctx, wave.runs, wave.discover === true);
@@ -2676,8 +2728,11 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2676
2728
  // #4613: the decision names the shared policy commit its runs were judged by.
2677
2729
  if (held.policySource) decision.ciPolicySource = held.policySource;
2678
2730
  }
2679
- // #4870: with a runner key, the wave's plan and policy checks are signed over its commit.
2680
- await signOpWaveChecks({ cwd, head: options.head ?? "HEAD", base, wave: wave.name, planDigest: opWaveSetDigest(spec, members), policyRows, log });
2731
+ // #4926: the policy step ends here, with the rows its result stands for.
2732
+ if (options.policyOnly) return { end: { ...result, policyRows: [...policyRows.values()] } };
2733
+ // #4870: with a runner key, the wave's plan and policy checks are signed over its commit;
2734
+ // #4926: with an evidence job after it, the plan's claim file is left for that job.
2735
+ await signOpWaveChecks({ cwd, head: options.head ?? "HEAD", base, wave: wave.name, planDigest: opWaveSetDigest(spec, members), policyRows, log, checksDir: join(cwd, opWaveChecksDir(spec)) });
2681
2736
  // #4614: the after-plan hooks in the job's process, before the set digest and the gate.
2682
2737
  const inProcess = await runAfterPlan(ctx, members, parts, policyRows);
2683
2738
  if (inProcess.failed) return { end: failed(ctx, `${inProcess.failed}, so nothing in wave ${k} was approved or applied`) };
@@ -921,6 +921,17 @@ export function opWaveOutcomeDir(spec: Pick<OpWavesSpec, "name">): string {
921
921
  return `.chant/op-waves/${spec.name}/outcomes`;
922
922
  }
923
923
 
924
+ /**
925
+ * Where a wave job's steps leave the claim files of the checks they ran
926
+ * (#4926), for the wave's evidence job: `plan-<wave>.json` from the wave's
927
+ * command, `policy-<wave>.json` from its policy step. Beside the outcome
928
+ * directory; a later job that downloads every artifact into that directory
929
+ * skips them, since they are not named as outcome files.
930
+ */
931
+ export function opWaveChecksDir(spec: Pick<OpWavesSpec, "name">): string {
932
+ return `.chant/op-waves/${spec.name}/checks`;
933
+ }
934
+
924
935
  /** The outcome file of wave `wave`'s job, or of one group or share of it (#4322). */
925
936
  export function opWaveOutcomePath(spec: Pick<OpWavesSpec, "name">, wave: number, part: { group?: string; share?: number } = {}): string {
926
937
  return `${opWaveOutcomeDir(spec)}/${waveOutcomeFileName(wave, part)}`;
@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
9
9
  import { join } from "node:path";
10
10
  import { afterEach, describe, expect, test } from "vitest";
11
11
  import { cronFiresUtc } from "./cron";
12
- import { checkOverdueOps, opPipelineFile, overdueVerdict, scheduledWatches } from "./schedule-overdue";
12
+ import { checkOverdueOps, opPipelineFile, overdueOpsAt, overdueVerdict, PLAN_WATCHES_ENV, plannedWatchesFromEnv, scheduledWatches, scheduledWatchProblem } from "./schedule-overdue";
13
13
  import { forgejoForge, githubForge, gitlabForge, type ForgeFetch, type PrForge } from "../pr-forge";
14
14
  import { renderPrNote, type PrReport } from "../pr-loop";
15
15
  import type { OpConfig } from "./types";
@@ -329,3 +329,85 @@ describe("the plan note", () => {
329
329
  expect(renderPrNote(report)).toContain("Warning: Op `drift` is overdue: test.");
330
330
  });
331
331
  });
332
+
333
+ // #4888: a product's prefix and label, and its own watches beside the discovered Ops.
334
+ describe("a product's words and watches", () => {
335
+ /** A temporary repository, left for the OS to clear. */
336
+ function repo(files: Record<string, string>): string {
337
+ const dir = mkdtempSync(join(tmpdir(), "chant-overdue-words-"));
338
+ const date = "2026-10-01T00:00:00Z";
339
+ const git = (...args: string[]) => execFileSync("git", ["-C", dir, ...args], { env: { ...process.env, GIT_COMMITTER_DATE: date, GIT_AUTHOR_DATE: date }, stdio: "pipe" });
340
+ git("init", "-q");
341
+ for (const [path, body] of Object.entries(files)) {
342
+ mkdirSync(join(dir, path, ".."), { recursive: true });
343
+ writeFileSync(join(dir, path), body);
344
+ }
345
+ git("add", ".");
346
+ git("-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "add");
347
+ return dir;
348
+ }
349
+
350
+ const forge = (scheduledRuns: PrForge["scheduledRuns"]): PrForge => ({ kind: "github", host: "example", scheduledRuns }) as PrForge;
351
+ const now = new Date("2026-10-22T00:00:00Z");
352
+
353
+ test("logPrefix goes before every log line and label before each verdict's message", async () => {
354
+ const root = repo({ ".github/workflows/drift.yml": "on: schedule", ".github/workflows/other.yml": "on: schedule" });
355
+ const lines: string[] = [];
356
+ const found = await checkOverdueOps({
357
+ watches: [
358
+ { op: "drift", cron: "0 6 * * *" },
359
+ { op: "other", cron: "0 6 * * *" },
360
+ ],
361
+ forge: forge(async (q) => {
362
+ if (q.op === "other") throw new Error("403\nmore");
363
+ return {};
364
+ }),
365
+ repoRoot: root,
366
+ now,
367
+ log: (l) => lines.push(l),
368
+ logPrefix: "yodel plan: ",
369
+ label: "Warning: ",
370
+ });
371
+ expect(found).toHaveLength(1);
372
+ expect(found[0]!.message).toMatch(/^Warning: Op `drift` is overdue: /);
373
+ expect(lines).toHaveLength(2);
374
+ expect(lines[0]).toMatch(/^yodel plan: Op `drift` is overdue: /);
375
+ expect(lines[1]).toBe("yodel plan: schedule check: github did not say when Op other last ran, so it is not checked: 403");
376
+ });
377
+
378
+ test("without words the lines and messages are chant's as before", async () => {
379
+ const root = repo({ ".github/workflows/drift.yml": "on: schedule" });
380
+ const lines: string[] = [];
381
+ const found = await checkOverdueOps({ watches: [{ op: "drift", cron: "0 6 * * *" }], forge: forge(async () => ({})), repoRoot: root, now, log: (l) => lines.push(l) });
382
+ expect(found[0]!.message).toMatch(/^Op `drift` is overdue: /);
383
+ expect(lines).toEqual([found[0]!.message]);
384
+ });
385
+
386
+ test("overdueOpsAt checks a product's watches where no Op is discovered", async () => {
387
+ const root = repo({ ".github/workflows/terragucci-drift.yml": "on: schedule" });
388
+ const asked: string[] = [];
389
+ const found = await overdueOpsAt({
390
+ forge: forge(async (q) => {
391
+ asked.push(`${q.op} ${q.workflow}`);
392
+ return {};
393
+ }),
394
+ cwd: root,
395
+ now,
396
+ log: () => {},
397
+ watches: [{ op: "tf-drift", cron: "0 6 * * *", files: [".github/workflows/terragucci-drift.yml", ".github/workflows/terragucci.yml"] }],
398
+ });
399
+ expect(asked).toEqual(["tf-drift terragucci-drift.yml"]);
400
+ expect(found.map((o) => o.op)).toEqual(["tf-drift"]);
401
+ });
402
+
403
+ test("the watches the pipeline names, each checked; one that is not a watch is said and left out", () => {
404
+ const lines: string[] = [];
405
+ const good = { op: "tf-drift", cron: "0 6 * * *", files: [".gitlab/terragucci-drift.yml"], schedule: { variable: "TERRAGUCCI_SCHEDULE", not: ["comments", "resume"] } };
406
+ const env = { [PLAN_WATCHES_ENV]: JSON.stringify([good, { op: "x", cron: "nope" }, { op: "y", cron: "0 6 * * *", files: ["../etc/passwd"] }]) };
407
+ expect(plannedWatchesFromEnv(env, (l) => lines.push(l))).toEqual([good]);
408
+ expect(lines).toEqual([`${PLAN_WATCHES_ENV}: watch x's cron "nope" is not five fields, so it is not checked`, `${PLAN_WATCHES_ENV}: watch y's files are not paths from the repository root, so it is not checked`]);
409
+ expect(plannedWatchesFromEnv({})).toEqual([]);
410
+ expect(plannedWatchesFromEnv({ [PLAN_WATCHES_ENV]: "{" }, (l) => lines.push(l))).toEqual([]);
411
+ expect(scheduledWatchProblem({ op: "a", cron: "0 6 * * *", schedule: { variable: "V", value: 'x" || true' } })).toContain("schedule value");
412
+ });
413
+ });
@@ -273,9 +273,10 @@ export async function checkOverdueOps(input: {
273
273
  member?: string;
274
274
  now: Date;
275
275
  log: (line: string) => void;
276
- }): Promise<OverdueOp[]> {
276
+ } & OverdueWords): Promise<OverdueOp[]> {
277
277
  const { forge } = input;
278
278
  if (!forge.scheduledRuns) return [];
279
+ const log = (line: string): void => input.log(`${input.logPrefix ?? ""}${line}`);
279
280
  const out: OverdueOp[] = [];
280
281
  for (const watch of input.watches) {
281
282
  const file = opPipelineFile(input.repoRoot, forge.kind, watch, input.member);
@@ -284,18 +285,91 @@ export async function checkOverdueOps(input: {
284
285
  try {
285
286
  runs = await forge.scheduledRuns({ op: watch.op, workflow: file.split("/").pop()!, ...(watch.schedule ? { schedule: watch.schedule } : {}) });
286
287
  } catch (err) {
287
- input.log(`schedule check: ${forge.kind} did not say when Op ${watch.op} last ran, so it is not checked: ${(err instanceof Error ? err.message : String(err)).split("\n")[0]}`);
288
+ log(`schedule check: ${forge.kind} did not say when Op ${watch.op} last ran, so it is not checked: ${(err instanceof Error ? err.message : String(err)).split("\n")[0]}`);
288
289
  continue;
289
290
  }
290
291
  const found = overdueVerdict(watch, forge.kind, runs, runs.last ? undefined : fileAdded(input.repoRoot, file), input.now);
291
292
  if (found) {
292
- input.log(found.message);
293
- out.push(found);
293
+ log(found.message);
294
+ out.push(input.label ? { ...found, message: `${input.label}${found.message}` } : found);
294
295
  }
295
296
  }
296
297
  return out;
297
298
  }
298
299
 
300
+ /**
301
+ * A product's words for the overdue check (#4888), so it passes them in
302
+ * place of wrapping `log` and each verdict's message itself.
303
+ */
304
+ export interface OverdueWords {
305
+ /** Put before every line the check writes to `log`, such as `yodel plan: `. */
306
+ logPrefix?: string;
307
+ /** Put before each verdict's `message`, the line the note shows, such as `Warning: `. The log line keeps chant's words. */
308
+ label?: string;
309
+ }
310
+
311
+ /**
312
+ * The variable the generated plan-note job names a product's own scheduled
313
+ * watches in (#4888): a JSON array of {@link ScheduledWatch}, from the
314
+ * pipeline (`productPlan.watches`), never from the plan job's report.
315
+ * `pr-post` checks them with the job's token beside the Ops it discovers.
316
+ */
317
+ export const PLAN_WATCHES_ENV = "CHANT_PLAN_WATCHES";
318
+
319
+ const OP_NAME = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
320
+ const REL_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9_.\/-]+$/;
321
+ const VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
322
+
323
+ /**
324
+ * Why `watch` is not a scheduled watch a pipeline may name (#4888), or
325
+ * undefined when it is: an Op name, a cron of five fields, `files` as
326
+ * relative paths with no `..`, and a GitLab selector of a variable name and
327
+ * plain values. None of them holds a `$`, so GitLab, which expands
328
+ * variables in a job's variables, passes the JSON as written.
329
+ */
330
+ export function scheduledWatchProblem(watch: unknown): string | undefined {
331
+ if (!isRecord(watch)) return "a watch is an object with op and cron";
332
+ if (typeof watch.op !== "string" || !OP_NAME.test(watch.op)) return `the watch's op ${JSON.stringify(watch.op)} is not an Op name`;
333
+ if (typeof watch.cron !== "string" || !/^[0-9A-Za-z*\/,? -]+$/.test(watch.cron) || watch.cron.trim().split(/\s+/).length !== 5) return `watch ${watch.op}'s cron ${JSON.stringify(watch.cron)} is not five fields`;
334
+ if (watch.files !== undefined && (!Array.isArray(watch.files) || watch.files.some((f) => typeof f !== "string" || !REL_PATH.test(f)))) return `watch ${watch.op}'s files are not paths from the repository root`;
335
+ if (watch.schedule !== undefined) {
336
+ const s = watch.schedule;
337
+ const plain = (v: unknown): boolean => typeof v === "string" && /^[A-Za-z0-9_.:\/-]+$/.test(v);
338
+ if (!isRecord(s) || typeof s.variable !== "string" || !VAR_NAME.test(s.variable)) return `watch ${watch.op}'s schedule names no variable`;
339
+ if (s.value !== undefined && !plain(s.value)) return `watch ${watch.op}'s schedule value is not a plain word`;
340
+ if (s.not !== undefined && (!Array.isArray(s.not) || !s.not.every(plain))) return `watch ${watch.op}'s schedule not is not a list of plain words`;
341
+ }
342
+ return undefined;
343
+ }
344
+
345
+ /**
346
+ * The watches {@link PLAN_WATCHES_ENV} names (#4888), each checked with
347
+ * {@link scheduledWatchProblem}; one that is not a watch is a line in `log`
348
+ * and left out. None when the variable is unset or not a JSON array.
349
+ */
350
+ export function plannedWatchesFromEnv(env: Record<string, string | undefined> = process.env, log: (line: string) => void = () => undefined): ScheduledWatch[] {
351
+ const raw = env[PLAN_WATCHES_ENV];
352
+ if (!raw?.trim()) return [];
353
+ let doc: unknown;
354
+ try {
355
+ doc = JSON.parse(raw);
356
+ } catch {
357
+ log(`${PLAN_WATCHES_ENV} is not JSON, so no product watch is checked`);
358
+ return [];
359
+ }
360
+ if (!Array.isArray(doc)) {
361
+ log(`${PLAN_WATCHES_ENV} is not a JSON array, so no product watch is checked`);
362
+ return [];
363
+ }
364
+ const out: ScheduledWatch[] = [];
365
+ for (const w of doc) {
366
+ const problem = scheduledWatchProblem(w);
367
+ if (problem) log(`${PLAN_WATCHES_ENV}: ${problem}, so it is not checked`);
368
+ else out.push(w as ScheduledWatch);
369
+ }
370
+ return out;
371
+ }
372
+
299
373
  /**
300
374
  * The overdue check over the Ops declared at `cwd` (#4289), as the plan note
301
375
  * reports it: the Ops `discoverOps` finds there, and the repository root
@@ -305,14 +379,36 @@ export async function checkOverdueOps(input: {
305
379
  * when a job ran, nothing is checked. A failure is a line in `log` and no
306
380
  * verdict, and the plan goes on.
307
381
  */
308
- export async function overdueOpsAt(input: { forge: PrForge | undefined; cwd: string; member?: string; now?: Date; log: (line: string) => void }): Promise<OverdueOp[]> {
382
+ export async function overdueOpsAt(
383
+ input: {
384
+ forge: PrForge | undefined;
385
+ cwd: string;
386
+ member?: string;
387
+ now?: Date;
388
+ log: (line: string) => void;
389
+ /**
390
+ * A product's own scheduled watches (#4888), checked beside the
391
+ * discovered Ops; one of the same name takes the discovered Op's place.
392
+ * They are checked even when discovery fails.
393
+ */
394
+ watches?: readonly ScheduledWatch[];
395
+ } & OverdueWords,
396
+ ): Promise<OverdueOp[]> {
309
397
  const { forge } = input;
310
398
  if (!forge?.scheduledRuns) return [];
399
+ const own = input.watches ?? [];
400
+ let discovered: ScheduledWatch[] = [];
311
401
  try {
312
402
  const { discoverOps } = await import("./discover");
313
- const discovered = await discoverOps({ cwd: input.cwd });
314
- const watches = scheduledWatches([...discovered.ops.values()].map((d) => d.config));
315
- if (watches.length === 0) return [];
403
+ const found = await discoverOps({ cwd: input.cwd });
404
+ discovered = scheduledWatches([...found.ops.values()].map((d) => d.config));
405
+ } catch (err) {
406
+ input.log(`${input.logPrefix ?? ""}could not check the scheduled Ops, so none is reported overdue: ${err instanceof Error ? err.message : String(err)}`);
407
+ if (own.length === 0) return [];
408
+ }
409
+ const watches = [...discovered.filter((d) => !own.some((w) => w.op === d.op)), ...own];
410
+ if (watches.length === 0) return [];
411
+ try {
316
412
  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: input.cwd, encoding: "utf-8" });
317
413
  if (top.status !== 0) return [];
318
414
  return await checkOverdueOps({
@@ -322,9 +418,11 @@ export async function overdueOpsAt(input: { forge: PrForge | undefined; cwd: str
322
418
  ...(input.member ? { member: input.member } : {}),
323
419
  now: input.now ?? new Date(),
324
420
  log: input.log,
421
+ ...(input.logPrefix ? { logPrefix: input.logPrefix } : {}),
422
+ ...(input.label ? { label: input.label } : {}),
325
423
  });
326
424
  } catch (err) {
327
- input.log(`could not check the scheduled Ops, so none is reported overdue: ${err instanceof Error ? err.message : String(err)}`);
425
+ input.log(`${input.logPrefix ?? ""}could not check the scheduled Ops, so none is reported overdue: ${err instanceof Error ? err.message : String(err)}`);
328
426
  return [];
329
427
  }
330
428
  }
@@ -115,7 +115,8 @@ describe("a job by id, and the jobs' URLs", () => {
115
115
  test("gitlab: a job with its pipeline, ref, tag and URL; a pipeline's jobs with their URLs", async () => {
116
116
  routes[`GET ${P}/jobs/5`] = { id: 5, name: "review", status: "success", ref: "main", tag: false, web_url: "https://gitlab.com/acme/infra/-/jobs/5", pipeline: { id: 10, sha: SHA } };
117
117
  routes[`GET ${P}/jobs/6`] = { id: 6, name: "plan", status: "failed", ref: "v1", tag: true, pipeline: { id: 11 } };
118
- expect(await gl().job(5)).toEqual({ id: 5, name: "review", status: "success", done: true, run: 10, ref: "main", tag: false, url: "https://gitlab.com/acme/infra/-/jobs/5" });
118
+ // #4926: the pipeline's commit is the job's.
119
+ expect(await gl().job(5)).toEqual({ id: 5, name: "review", status: "success", done: true, run: 10, ref: "main", tag: false, url: "https://gitlab.com/acme/infra/-/jobs/5", headSha: SHA });
119
120
  expect(await gl().job(6)).toEqual({ id: 6, name: "plan", status: "failed", done: true, run: 11, ref: "v1", tag: true });
120
121
  expect(await gl().job(7)).toBeUndefined();
121
122
  routes[`GET ${P}/pipelines/10/jobs`] = [{ id: 4, name: "plan", status: "success", ref: "refs/merge-requests/3/head", tag: false, web_url: "https://gitlab.com/acme/infra/-/jobs/4", pipeline: { id: 10 } }];
@@ -8,7 +8,9 @@
8
8
  * (GitLab's pipelines), a run, its jobs, and the artifacts it kept, by name in
9
9
  * a run or across the repository, as a product's review agent reads them
10
10
  * (#4846); the files a head changes since its merge base, a job by id, and
11
- * a file of a GitLab job's artifacts (#4862).
11
+ * a file of a GitLab job's artifacts (#4862); and the commit each job ran
12
+ * on with, on GitHub and Forgejo, its steps' conclusions, which a wave's
13
+ * evidence job signs from (#4926).
12
14
  *
13
15
  * They take the same options as the clients in `./pr-forge.ts` and live in
14
16
  * their own module, imported only by the products that call them, so the
@@ -160,6 +162,25 @@ export interface RunJob {
160
162
  tag?: boolean;
161
163
  /** The job's page on the forge. */
162
164
  url?: string;
165
+ /** The commit it ran on (#4926): GitHub's and Forgejo's `head_sha`, GitLab's `commit.id` or `pipeline.sha`. */
166
+ headSha?: string;
167
+ /**
168
+ * Its steps as the runner reported them (#4926): GitHub's and Forgejo's
169
+ * `steps[]`, by name, in order. GitLab reports no steps, so it has none,
170
+ * and a check there reads the job's own status.
171
+ */
172
+ steps?: RunJobStep[];
173
+ }
174
+
175
+ /** One step of a {@link RunJob} (#4926). */
176
+ export interface RunJobStep {
177
+ name: string;
178
+ /** 1-based, as the forge numbers it. */
179
+ number?: number;
180
+ /** `queued`, `in_progress`, `completed` (Forgejo: also `success`, `failure`, ...). */
181
+ status: string;
182
+ /** `success`, `failure`, `skipped`, `cancelled`, once it finished. */
183
+ conclusion?: string;
163
184
  }
164
185
 
165
186
  /** A file a comparison changes, with the path it had before a rename when the forge names it (#4862). */
@@ -642,6 +663,9 @@ function jobOf(j: unknown): RunJob | undefined {
642
663
  const run = num(j.run_id) ?? (isObject(j.pipeline) ? num(j.pipeline.id) : undefined);
643
664
  const ref = str(j.head_branch) ?? str(j.ref);
644
665
  const url = str(j.html_url) ?? str(j.web_url);
666
+ // #4926: the commit, and on GitHub and Forgejo the steps, which `chant ci evidence sign --from-job` reads.
667
+ const headSha = str(j.head_sha) ?? (isObject(j.commit) ? str(j.commit.id) : undefined) ?? (isObject(j.pipeline) ? str(j.pipeline.sha) : undefined);
668
+ const steps = Array.isArray(j.steps) ? j.steps.map(stepOf).filter(defined) : undefined;
645
669
  return {
646
670
  id,
647
671
  name,
@@ -652,9 +676,21 @@ function jobOf(j: unknown): RunJob | undefined {
652
676
  ...(ref ? { ref } : {}),
653
677
  ...(typeof j.tag === "boolean" ? { tag: j.tag } : {}),
654
678
  ...(url ? { url } : {}),
679
+ ...(headSha ? { headSha } : {}),
680
+ ...(steps ? { steps } : {}),
655
681
  };
656
682
  }
657
683
 
684
+ /** A job's step as GitHub or Forgejo answers it (#4926). */
685
+ function stepOf(s: unknown): RunJobStep | undefined {
686
+ if (!isObject(s)) return undefined;
687
+ const name = str(s.name);
688
+ if (!name) return undefined;
689
+ const number = num(s.number);
690
+ const conclusion = str(s.conclusion);
691
+ return { name, ...(number !== undefined ? { number } : {}), status: str(s.status) ?? "", ...(conclusion ? { conclusion } : {}) };
692
+ }
693
+
658
694
  /** GitLab's access levels, by the number its API answers. */
659
695
  const GITLAB_ROLES: Record<number, string> = { 5: "minimal", 10: "guest", 15: "planner", 20: "reporter", 30: "developer", 40: "maintainer", 50: "owner" };
660
696
 
package/src/pr-forge.ts CHANGED
@@ -505,8 +505,12 @@ export interface PrForge {
505
505
  * Every status and check reported on `head` passed, and at least one did.
506
506
  * Statuses named in `ignore` are left out, such as the apply's own.
507
507
  * Pending while one still runs or none has reported.
508
+ *
509
+ * Commit statuses named in `require` (#4913) must have reported as well,
510
+ * such as the ref gate's (`@intentius/chant/ref-gate-rules`), which a job
511
+ * posts later than the others: one not posted yet counts as still running.
508
512
  */
509
- prChecksPassed?(pr: number, head: string, ignore?: readonly string[]): Promise<PrRequireResult>;
513
+ prChecksPassed?(pr: number, head: string, ignore?: readonly string[], require?: readonly string[]): Promise<PrRequireResult>;
510
514
  /**
511
515
  * GitLab (#4328): each open merge request into `branch` whose newest
512
516
  * pipeline at its head commit, in this project, ran a job named `job`,
@@ -1117,16 +1121,18 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
1117
1121
  if (!tip || !base) return refuse(`the forge did not say where ${into} is or where ${short(head)} left it`);
1118
1122
  return base === tip ? pass(`${short(head)} contains ${into} at ${short(tip)}`) : refuse(`${short(head)} does not contain ${into} at ${short(tip)}`);
1119
1123
  },
1120
- async prChecksPassed(_pr, head, ignore = []) {
1124
+ async prChecksPassed(_pr, head, ignore = [], need = []) {
1121
1125
  const skip = ignoredStatus(ignore);
1122
1126
  const failing: string[] = [];
1123
1127
  const waiting: string[] = [];
1128
+ const seen = new Set<string>();
1124
1129
  let count = 0;
1125
1130
  // The combined status holds each context's newest status.
1126
1131
  const combined = await api.call("GET", `${repo}/commits/${head}/status`);
1127
1132
  for (const st of isObject(combined) && Array.isArray(combined.statuses) ? combined.statuses : []) {
1128
1133
  const context = isObject(st) ? str(st.context) : undefined;
1129
1134
  if (!context) continue;
1135
+ seen.add(context);
1130
1136
  const state = str(st.state) ?? str(st.status) ?? "";
1131
1137
  // A status left out still shows the checks reported, unless it is what held them back.
1132
1138
  if (skip(context)) {
@@ -1147,6 +1153,8 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
1147
1153
  else if (!["success", "neutral", "skipped"].includes(String(run.conclusion))) failing.push(name);
1148
1154
  }
1149
1155
  }
1156
+ // #4913: a required status not posted yet is waited for.
1157
+ waiting.push(...need.filter((n) => !seen.has(n)));
1150
1158
  return checksVerdict(`pull request ${_pr}`, head, failing, waiting, count);
1151
1159
  },
1152
1160
  async pullRequestOpen(pr) {
@@ -1564,7 +1572,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
1564
1572
  if (behind === undefined) return refuse(`GitLab did not say how far ${short(head)} is behind ${into}`);
1565
1573
  return behind === 0 ? pass(`${short(head)} contains ${into}`) : refuse(`${short(head)} is ${behind} commit${behind === 1 ? "" : "s"} behind ${into}`);
1566
1574
  },
1567
- async prChecksPassed(mr, head, ignore = []) {
1575
+ async prChecksPassed(mr, head, ignore = [], need = []) {
1568
1576
  const skip = ignoredStatus(ignore);
1569
1577
  // Each name's newest status; a job allowed to fail holds nothing back.
1570
1578
  const newest = new Map<string, Record<string, unknown>>();
@@ -1588,6 +1596,7 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
1588
1596
  if ((state === "failed" || state === "canceled") && st.allow_failure !== true) failing.push(name);
1589
1597
  else if (GITLAB_RUNNING.has(state)) waiting.push(name);
1590
1598
  }
1599
+ waiting.push(...need.filter((n) => !newest.has(n)));
1591
1600
  return checksVerdict(`merge request !${mr}`, head, failing, waiting, count);
1592
1601
  },
1593
1602
  async pullRequestOpen(mr) {
@@ -1866,6 +1875,8 @@ export interface ForgeTarget {
1866
1875
  repo: string;
1867
1876
  /** Lower-cased. */
1868
1877
  host: string;
1878
+ /** The web origin, `https://host` or `http://host:port` (#4888). Set by `forgeTargetWith` in `@intentius/chant/forge-flags`. */
1879
+ origin?: string;
1869
1880
  token: string;
1870
1881
  /** The variable the token came from, for messages. Never the token itself. */
1871
1882
  tokenSource: string;
@@ -60,11 +60,33 @@ export interface PrPlanNoteHandoff {
60
60
  state: "success" | "failure" | "pending";
61
61
  description: string;
62
62
  note: PrPlanNote;
63
+ /**
64
+ * The product's own hidden line's body (#4931), such as terragucci's
65
+ * `roots=a,b`: `pr-post` writes `<!-- <productMarker> <marker> -->` on the
66
+ * note's second line, under chant's marker, when the pipeline's note words
67
+ * name a `productMarker`. Letters, digits and `_.,/@+=:-`, words split by
68
+ * one space, at most {@link PRODUCT_MARKER_LIMIT} characters.
69
+ */
70
+ marker?: string;
71
+ }
72
+
73
+ /** The most characters a hand-off's {@link PrPlanNoteHandoff.marker} holds (#4931). */
74
+ export const PRODUCT_MARKER_LIMIT = 4096;
75
+
76
+ /** What a hand-off's marker may hold (#4931): no `-->`, no `<` or `>`, nothing that ends the comment or starts another. */
77
+ export const PRODUCT_MARKER_BODY = /^[A-Za-z0-9_.,\/@+=:-]+( [A-Za-z0-9_.,\/@+=:-]+)*$/;
78
+
79
+ /** What a note words' {@link PrPlanNoteWords.productMarker} may be (#4931): a name such as `terragucci:plan`. */
80
+ export const PRODUCT_MARKER_NAME = /^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)*$/;
81
+
82
+ /** The product's hidden line (#4931): `<!-- <name> <body> -->`, or `<!-- <name> -->` with an empty body. */
83
+ export function productMarkerLine(name: string, body: string): string {
84
+ return body ? `<!-- ${name} ${body} -->` : `<!-- ${name} -->`;
63
85
  }
64
86
 
65
87
  /** The hand-off for `note` (#4799), as a product's plan verb writes it to {@link PR_PLAN_NOTE_FILE}. */
66
- export function planNoteHandoff(note: PrPlanNote, at: { pr: number; env: string; member?: string; state: PrPlanNoteHandoff["state"]; description: string }): PrPlanNoteHandoff {
67
- return { kind: "plan-note-handoff", contract: PR_PLAN_NOTE_CONTRACT, pr: at.pr, head: note.head, env: at.env, ...(at.member !== undefined ? { member: at.member } : {}), state: at.state, description: at.description, note };
88
+ export function planNoteHandoff(note: PrPlanNote, at: { pr: number; env: string; member?: string; state: PrPlanNoteHandoff["state"]; description: string; marker?: string }): PrPlanNoteHandoff {
89
+ return { kind: "plan-note-handoff", contract: PR_PLAN_NOTE_CONTRACT, pr: at.pr, head: note.head, env: at.env, ...(at.member !== undefined ? { member: at.member } : {}), state: at.state, description: at.description, note, ...(at.marker !== undefined ? { marker: at.marker } : {}) };
68
90
  }
69
91
 
70
92
  /** One change line of a group, as chant's plan summary groups them. */
@@ -229,9 +251,16 @@ export interface PrPlanNoteWords {
229
251
  planFile?: string;
230
252
  /** The op an override is recorded under. */
231
253
  overrideOp?: string;
254
+ /**
255
+ * The name of the product's own hidden line (#4931), such as
256
+ * `terragucci:plan`: a hand-off's `marker` is kept as `<!-- <name>
257
+ * <marker> -->` on the note's second line, where the product finds its
258
+ * note by it. Absent: a hand-off's marker is dropped.
259
+ */
260
+ productMarker?: string;
232
261
  }
233
262
 
234
- const NOTE_WORDS: Required<Omit<PrPlanNoteWords, "marker">> = {
263
+ const NOTE_WORDS: Required<Omit<PrPlanNoteWords, "marker" | "productMarker">> = {
235
264
  footer: "",
236
265
  page: "report.html",
237
266
  artifact: "chant-pr",