@intentius/sql-yodeler 0.10.0 → 0.11.0

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 (223) hide show
  1. package/README.md +4 -4
  2. package/dist/apply-steps/index.d.ts +2 -2
  3. package/dist/apply-steps/index.js +7 -7
  4. package/dist/apply-steps/index.js.map +1 -1
  5. package/dist/bin.js +8 -0
  6. package/dist/bin.js.map +1 -1
  7. package/dist/chant/apply.d.ts +0 -2
  8. package/dist/chant/apply.js +3 -4
  9. package/dist/chant/apply.js.map +1 -1
  10. package/dist/chant/build.js +3 -1
  11. package/dist/chant/build.js.map +1 -1
  12. package/dist/chant/confirm.d.ts +43 -0
  13. package/dist/chant/confirm.js +78 -0
  14. package/dist/chant/confirm.js.map +1 -0
  15. package/dist/chant/drift.d.ts +0 -2
  16. package/dist/chant/drift.js +2 -3
  17. package/dist/chant/drift.js.map +1 -1
  18. package/dist/chant/gated-request.d.ts +153 -0
  19. package/dist/chant/gated-request.js +91 -0
  20. package/dist/chant/gated-request.js.map +1 -0
  21. package/dist/chant/plan.d.ts +4 -6
  22. package/dist/chant/plan.js +8 -7
  23. package/dist/chant/plan.js.map +1 -1
  24. package/dist/chant/process.d.ts +5 -0
  25. package/dist/chant/process.js +5 -0
  26. package/dist/chant/process.js.map +1 -1
  27. package/dist/chant/stored-plan.d.ts +23 -0
  28. package/dist/chant/stored-plan.js +33 -0
  29. package/dist/chant/stored-plan.js.map +1 -0
  30. package/dist/chant-floor-version.d.ts +14 -0
  31. package/dist/chant-floor-version.js +15 -0
  32. package/dist/chant-floor-version.js.map +1 -0
  33. package/dist/chant-floor.d.ts +42 -0
  34. package/dist/chant-floor.js +82 -0
  35. package/dist/chant-floor.js.map +1 -0
  36. package/dist/check/run.js +2 -2
  37. package/dist/check/run.js.map +1 -1
  38. package/dist/ci/check-hooks.d.ts +65 -0
  39. package/dist/ci/check-hooks.js +101 -0
  40. package/dist/ci/check-hooks.js.map +1 -0
  41. package/dist/ci/login.d.ts +45 -0
  42. package/dist/ci/login.js +55 -0
  43. package/dist/ci/login.js.map +1 -1
  44. package/dist/ci/render.d.ts +127 -8
  45. package/dist/ci/render.js +254 -27
  46. package/dist/ci/render.js.map +1 -1
  47. package/dist/ci-words.d.ts +93 -0
  48. package/dist/ci-words.js +71 -0
  49. package/dist/ci-words.js.map +1 -0
  50. package/dist/cli.js +10 -1
  51. package/dist/cli.js.map +1 -1
  52. package/dist/command.js +2 -1
  53. package/dist/command.js.map +1 -1
  54. package/dist/commands/apply.d.ts +1 -1
  55. package/dist/commands/apply.js +44 -39
  56. package/dist/commands/apply.js.map +1 -1
  57. package/dist/commands/approve.d.ts +0 -2
  58. package/dist/commands/approve.js +72 -55
  59. package/dist/commands/approve.js.map +1 -1
  60. package/dist/commands/chant.d.ts +26 -0
  61. package/dist/commands/chant.js +37 -0
  62. package/dist/commands/chant.js.map +1 -0
  63. package/dist/commands/check.js +13 -10
  64. package/dist/commands/check.js.map +1 -1
  65. package/dist/commands/checkpoint.js +4 -5
  66. package/dist/commands/checkpoint.js.map +1 -1
  67. package/dist/commands/cleanup.d.ts +2 -0
  68. package/dist/commands/cleanup.js +82 -3
  69. package/dist/commands/cleanup.js.map +1 -1
  70. package/dist/commands/config.js +8 -8
  71. package/dist/commands/config.js.map +1 -1
  72. package/dist/commands/docs.js +2 -3
  73. package/dist/commands/docs.js.map +1 -1
  74. package/dist/commands/index.js +2 -0
  75. package/dist/commands/index.js.map +1 -1
  76. package/dist/commands/init.js +85 -20
  77. package/dist/commands/init.js.map +1 -1
  78. package/dist/commands/lint.js +16 -11
  79. package/dist/commands/lint.js.map +1 -1
  80. package/dist/commands/mcp.js +14 -0
  81. package/dist/commands/mcp.js.map +1 -1
  82. package/dist/commands/new.d.ts +0 -2
  83. package/dist/commands/new.js +13 -36
  84. package/dist/commands/new.js.map +1 -1
  85. package/dist/commands/override.js +14 -16
  86. package/dist/commands/override.js.map +1 -1
  87. package/dist/commands/plan.js +14 -10
  88. package/dist/commands/plan.js.map +1 -1
  89. package/dist/commands/rebase.js +10 -10
  90. package/dist/commands/rebase.js.map +1 -1
  91. package/dist/commands/repair.js +4 -4
  92. package/dist/commands/report.d.ts +0 -2
  93. package/dist/commands/report.js +4 -6
  94. package/dist/commands/report.js.map +1 -1
  95. package/dist/commands/revert.js +19 -17
  96. package/dist/commands/revert.js.map +1 -1
  97. package/dist/commands/status.d.ts +0 -4
  98. package/dist/commands/status.js +9 -11
  99. package/dist/commands/status.js.map +1 -1
  100. package/dist/commands/test.js +5 -5
  101. package/dist/commands/upgrade.d.ts +39 -0
  102. package/dist/commands/upgrade.js +197 -0
  103. package/dist/commands/upgrade.js.map +1 -0
  104. package/dist/config/define.d.ts +22 -3
  105. package/dist/config/define.js +1 -0
  106. package/dist/config/define.js.map +1 -1
  107. package/dist/config/load.js +8 -4
  108. package/dist/config/load.js.map +1 -1
  109. package/dist/credentials.d.ts +15 -20
  110. package/dist/credentials.js +7 -7
  111. package/dist/credentials.js.map +1 -1
  112. package/dist/declarative/plan.d.ts +8 -0
  113. package/dist/declarative/plan.js +35 -2
  114. package/dist/declarative/plan.js.map +1 -1
  115. package/dist/exit.d.ts +51 -15
  116. package/dist/exit.js +90 -22
  117. package/dist/exit.js.map +1 -1
  118. package/dist/history/lock.d.ts +10 -6
  119. package/dist/history/lock.js +16 -10
  120. package/dist/history/lock.js.map +1 -1
  121. package/dist/init/adopt.js +11 -11
  122. package/dist/init/adopt.js.map +1 -1
  123. package/dist/init/baseline.js +4 -4
  124. package/dist/init/baseline.js.map +1 -1
  125. package/dist/init/second.d.ts +5 -1
  126. package/dist/init/second.js +9 -6
  127. package/dist/init/second.js.map +1 -1
  128. package/dist/lint/annotations.d.ts +15 -5
  129. package/dist/lint/annotations.js +21 -5
  130. package/dist/lint/annotations.js.map +1 -1
  131. package/dist/lint/report.d.ts +0 -2
  132. package/dist/lint/report.js +2 -3
  133. package/dist/lint/report.js.map +1 -1
  134. package/dist/mcp/chant-hook.d.ts +40 -0
  135. package/dist/mcp/chant-hook.js +75 -0
  136. package/dist/mcp/chant-hook.js.map +1 -0
  137. package/dist/mcp/tools.js +1 -1
  138. package/dist/migrations/create.d.ts +1 -6
  139. package/dist/migrations/create.js +0 -3
  140. package/dist/migrations/create.js.map +1 -1
  141. package/dist/migrations/document.d.ts +1 -1
  142. package/dist/pr/model.js +2 -2
  143. package/dist/pr/model.js.map +1 -1
  144. package/dist/pr/note.d.ts +72 -0
  145. package/dist/pr/note.js +206 -0
  146. package/dist/pr/note.js.map +1 -0
  147. package/dist/pr/render.d.ts +6 -0
  148. package/dist/pr/render.js +2 -2
  149. package/dist/pr/render.js.map +1 -1
  150. package/dist/project.d.ts +11 -2
  151. package/dist/project.js +14 -3
  152. package/dist/project.js.map +1 -1
  153. package/dist/rebase/index.d.ts +0 -2
  154. package/dist/rebase/index.js +8 -9
  155. package/dist/rebase/index.js.map +1 -1
  156. package/dist/rebase/repair.d.ts +0 -2
  157. package/dist/rebase/repair.js +7 -9
  158. package/dist/rebase/repair.js.map +1 -1
  159. package/dist/replay/replay.d.ts +1 -5
  160. package/dist/replay/replay.js +4 -12
  161. package/dist/replay/replay.js.map +1 -1
  162. package/dist/replay/report.js +3 -2
  163. package/dist/replay/report.js.map +1 -1
  164. package/dist/replay/shared.js +3 -4
  165. package/dist/replay/shared.js.map +1 -1
  166. package/dist/report/audit.d.ts +65 -1
  167. package/dist/report/audit.js +73 -3
  168. package/dist/report/audit.js.map +1 -1
  169. package/dist/report/model.d.ts +15 -1
  170. package/dist/report/model.js +101 -2
  171. package/dist/report/model.js.map +1 -1
  172. package/dist/schemas.d.ts +1 -1
  173. package/dist/steps/index.d.ts +0 -5
  174. package/dist/steps/index.js +0 -10
  175. package/dist/steps/index.js.map +1 -1
  176. package/dist/steps/kinds.d.ts +2 -45
  177. package/dist/steps/kinds.js +2 -51
  178. package/dist/steps/kinds.js.map +1 -1
  179. package/dist/tenants/wave.js +5 -5
  180. package/dist/tenants/wave.js.map +1 -1
  181. package/dist/testing/report.d.ts +0 -2
  182. package/dist/testing/report.js +2 -3
  183. package/dist/testing/report.js.map +1 -1
  184. package/dist/testing/run.js +7 -10
  185. package/dist/testing/run.js.map +1 -1
  186. package/dist/versioned/approval.d.ts +0 -2
  187. package/dist/versioned/approval.js +6 -5
  188. package/dist/versioned/approval.js.map +1 -1
  189. package/dist/versioned/checks.d.ts +1 -1
  190. package/dist/versioned/checks.js +4 -5
  191. package/dist/versioned/checks.js.map +1 -1
  192. package/dist/versioned/engine.d.ts +2 -4
  193. package/dist/versioned/engine.js +11 -42
  194. package/dist/versioned/engine.js.map +1 -1
  195. package/dist/versioned/index.d.ts +1 -1
  196. package/dist/versioned/index.js +3 -4
  197. package/dist/versioned/index.js.map +1 -1
  198. package/dist/versioned/op.js +3 -2
  199. package/dist/versioned/op.js.map +1 -1
  200. package/dist/versioned/policy.d.ts +1 -1
  201. package/dist/versioned/policy.js +5 -5
  202. package/dist/versioned/policy.js.map +1 -1
  203. package/dist/versioned/revert.js +11 -11
  204. package/dist/versioned/revert.js.map +1 -1
  205. package/dist/versioned/stand-down.d.ts +15 -1
  206. package/dist/versioned/stand-down.js +29 -1
  207. package/dist/versioned/stand-down.js.map +1 -1
  208. package/dist/versioned/state.js +0 -5
  209. package/dist/versioned/state.js.map +1 -1
  210. package/dist/waves/index.d.ts +1 -1
  211. package/dist/waves/index.js +26 -12
  212. package/dist/waves/index.js.map +1 -1
  213. package/dist/waves/promotion.d.ts +1 -1
  214. package/dist/waves/promotion.js +6 -6
  215. package/dist/waves/promotion.js.map +1 -1
  216. package/package.json +8 -7
  217. package/schemas/check.schema.json +1 -1
  218. package/schemas/lint.schema.json +1 -1
  219. package/schemas/plan.schema.json +1 -1
  220. package/schemas/report.schema.json +1 -1
  221. package/dist/steps/orm-handoff.d.ts +0 -74
  222. package/dist/steps/orm-handoff.js +0 -154
  223. package/dist/steps/orm-handoff.js.map +0 -1
package/dist/ci/render.js CHANGED
@@ -47,7 +47,10 @@
47
47
  * second apply: it waits for the first's lock (YODEL_LOCK_WAIT), and an
48
48
  * apply whose commit is no longer main's tip stands down
49
49
  * (YODEL_STAND_DOWN), since the newer commit's waves apply the same
50
- * environments.
50
+ * environments. With a chant that has the lock grain and stand-down
51
+ * (#293), chant does both: its lease on the environment exits 5 for the
52
+ * apply that finds it held, and `standDown` in the spec exits 6 for one
53
+ * a newer commit supersedes; the jobs carry neither variable.
51
54
  * - watch-<env>: the environment's WatchOp on its own schedule, rendered by
52
55
  * chant's generateOpsPipeline, with the reader's credentials. After the
53
56
  * Op, `yodel drift <env> --issue` compares the server with the schema the
@@ -71,24 +74,30 @@
71
74
  * image ghcr.io/intentius/sql-yodeler pinned by its digest, every job runs
72
75
  * in that image instead, which carries node, yodel, chant and the lexicons
73
76
  * on PATH, and no job runs `npm ci` ({@link Toolchain}).
77
+ *
78
+ * With a chant that has `@intentius/chant/ci-product` (chant#4550), yodel ci
79
+ * renders through chant's product pipeline with yodel's words (#289,
80
+ * ../ci-words.ts): {@link productWaves}.
74
81
  */
75
82
  import { existsSync } from "node:fs";
76
83
  import { join, resolve } from "node:path";
77
84
  import { pathToFileURL } from "node:url";
78
85
  import { APPROVAL_MODES, WAVE_GATES, waveGateHint } from "../config/define.js";
79
86
  import { stepHooks } from "../apply-steps/index.js";
80
- import { audience, CLOUD_OF, jobLogins, loginSteps } from "./login.js";
87
+ import { audience, chantTrade, CLOUD_OF, jobLogins, loginSteps, tradeIdTokens, tradesThroughChant, useChantTrade } from "./login.js";
81
88
  import { RECORD_PLANS_ENV } from "../approval-mode/index.js";
82
89
  import { cloudToken, credentialsOf, roleVariables } from "../credentials.js";
83
90
  import { loadYodelConfig } from "../config/load.js";
84
91
  import { testFiles } from "../testing/files.js";
85
92
  import { CODE_QUALITY_FILE } from "../lint/annotations.js";
93
+ import { chantCheckHooks, checkPresets, declarationFile, declarationWithHooks } from "./check-hooks.js";
86
94
  import { emitYAMLEntry, parseYAMLDocument } from "@intentius/chant/yaml";
87
95
  import { Concurrency, Job as ActionsJob, Permissions, Service as ActionsService, Step, Workflow as ActionsWorkflow, } from "@intentius/chant-lexicon-github";
88
96
  import { githubSerializer } from "@intentius/chant-lexicon-github/serializer";
89
97
  import { forgejoSerializer } from "@intentius/chant-lexicon-forgejo/serializer";
90
98
  import { Artifacts as GitLabArtifacts, Image, Job as GitLabJob, Pipeline as GitLabPipeline, Rule, Service as GitLabService, Workflow as GitLabWorkflow, WorkflowRule, } from "@intentius/chant-lexicon-gitlab";
91
99
  import { gitlabSerializer } from "@intentius/chant-lexicon-gitlab/serializer";
100
+ import { chantProduct, YODEL_WORDS } from "../ci-words.js";
92
101
  export const FORGES = ["github", "gitlab", "forgejo"];
93
102
  /** The image every job runs in, where the forge runs jobs in a container. It needs git, so not -slim. */
94
103
  export const IMAGE = "node:22-bookworm";
@@ -103,6 +112,22 @@ const CHECKOUT = "actions/checkout@v7";
103
112
  const SETUP_NODE = "actions/setup-node@v7";
104
113
  /** DEV for dev: the prefix of an environment's variables. */
105
114
  export const prefixOf = (env) => env.toUpperCase().replace(/[^A-Z0-9]/g, "_");
115
+ /** The line the lint job runs chant's check moment with (#294): the hooks are read at the pull request's base. */
116
+ export const checkHooksLine = (forge) => `yodel chant ci check --base ${forge === "gitlab" ? "$CI_MERGE_REQUEST_DIFF_BASE_SHA" : "${{ github.event.pull_request.base.sha }}"}`;
117
+ /** yodel's checks and the project's tools as check-hook presets for `forge` (#294). */
118
+ export function checkHooksOf(envs_) {
119
+ const forge = "github";
120
+ return checkPresets({
121
+ dialect: envs_.dialect,
122
+ // --format forge: one list of hooks for every forge, each job printing its own forge's format.
123
+ commands: { ci: CI_CHECK, types: TYPES_CHECK, lint: `${LINT} --format forge --output ${CODE_QUALITY_FILE}`, replay: REPLAY, test: TEST, check: checkCommand(forge).replace(/--format \S+( --output \S+)?$/, `--format forge --output ${CODE_QUALITY_FILE}`) },
124
+ typedColumns: envs_.typedColumns === true,
125
+ replay: envs_.replay,
126
+ tests: envs_.tests === true,
127
+ check: envs_.check === true,
128
+ tools: envs_.tools ?? [],
129
+ });
130
+ }
106
131
  /** Whether the apply pipeline is rendered: unless yodel.config.ts `ci.apply` is false. */
107
132
  const rendersApply = (envs) => envs.apply !== false;
108
133
  /** DEV_CLICKHOUSE for dev on ClickHouse: what an environment's variables start with. */
@@ -137,7 +162,12 @@ const cloudsOf = (envs, held) => [
137
162
  ...new Set(held.map(([env, role]) => envs.credentials?.[env]?.[role].cloud).filter((c) => c !== undefined)),
138
163
  ];
139
164
  /** A GitLab job's `id_tokens` for `clouds`, each for its login's audience when the job logs in (#132): GCP's is the workload identity provider's own. */
140
- const idTokens = (clouds, logins = []) => Object.fromEntries(clouds.map((c) => {
165
+ const idTokens = (clouds, logins = []) => ({
166
+ ...ownIdTokens(clouds.filter((c) => !(tradesThroughChant() && logins.some((l) => l.cloud === CLOUD_OF[c]))), logins),
167
+ // Through chant's trade (#296), the logins' tokens come in chant's variables.
168
+ ...(tradeIdTokens(logins) ?? {}),
169
+ });
170
+ const ownIdTokens = (clouds, logins) => Object.fromEntries(clouds.map((c) => {
141
171
  const login = logins.find((l) => l.cloud === CLOUD_OF[c]);
142
172
  return [ID_TOKENS[c].variable, { aud: login ? audience(login) : ID_TOKENS[c].aud }];
143
173
  }));
@@ -269,7 +299,7 @@ export const WEBHOOK_VARIABLES = ["YODEL_WEBHOOK_URL", "YODEL_WEBHOOK_KEY"];
269
299
  export const REPORT_DIR = "yodel-report";
270
300
  /**
271
301
  * `yodel report <env>` as JSON and as the HTML run view, into REPORT_DIR.
272
- * It runs whatever the job's outcome, and a gap it reports (exit 4) does not
302
+ * It runs whatever the job's outcome, and a gap it reports (exit 1) does not
273
303
  * fail the job: the report is for reading. `yodel` is the project's, named
274
304
  * by path, since GitLab's after_script does not keep before_script's PATH;
275
305
  * in the yodel image, the image's, which is on PATH.
@@ -370,7 +400,9 @@ function checkJob(forge, dialect, tc) {
370
400
  ],
371
401
  });
372
402
  }
373
- function lintJob(forge, dialect, replay, tc, tests = false, typedColumns = false, check = false) {
403
+ function lintJob(forge, dialect, replay, tc, tests = false, typedColumns = false, check = false, hooks = false) {
404
+ if (hooks)
405
+ return checkHooksJob(forge, dialect, replay, tc);
374
406
  // With the replay check, the job runs in IMAGE on every forge and reaches
375
407
  // its replay server by the service's name on the job's own network. On
376
408
  // GitHub's VM the service would be on localhost through a published port,
@@ -399,6 +431,25 @@ function lintJob(forge, dialect, replay, tc, tests = false, typedColumns = false
399
431
  ],
400
432
  });
401
433
  }
434
+ /**
435
+ * The lint job on chant's check moment (#294): the replay server when the
436
+ * project has one, then `yodel chant ci check`, which runs the hooks the
437
+ * declaration at the pull request's base names. The job runs in IMAGE with
438
+ * the replay server, as {@link lintJob} does.
439
+ */
440
+ function checkHooksJob(forge, dialect, replay, tc) {
441
+ const container = replay || inContainer(forge, tc);
442
+ const steps = [...setupSteps(container, tc), new Step({ name: "Check hooks at the base (chant ci check)", run: checkHooksLine(forge) })];
443
+ if (!replay)
444
+ return new ActionsJob({ ...runner(container, tc), steps });
445
+ const { svc, services, env } = replayService(dialect);
446
+ return new ActionsJob({
447
+ ...runner(container, tc),
448
+ services,
449
+ env,
450
+ steps: [...setupSteps(container, tc), new Step({ name: `Wait for the replay server (${svc.name})`, run: waitFor(svc.name, svc.port) }), new Step({ name: "Check hooks at the base (chant ci check)", run: checkHooksLine(forge) })],
451
+ });
452
+ }
402
453
  /** The pull request workflow of a project that only runs yodel check (#1). */
403
454
  function checkOnlyActions(forge, envs_) {
404
455
  const jobs = { check: checkJob(forge, envs_.dialect, toolchainOf(envs_)) };
@@ -425,7 +476,7 @@ export function actionsReview(forge, envs_) {
425
476
  const tc = toolchainOf(envs_);
426
477
  if (envs_.checkOnly)
427
478
  return checkOnlyActions(forge, envs_);
428
- const jobs = { lint: lintJob(forge, dialect, replay, tc, envs_.tests === true, envs_.typedColumns === true, envs_.check === true) };
479
+ const jobs = { lint: lintJob(forge, dialect, replay, tc, envs_.tests === true, envs_.typedColumns === true, envs_.check === true, envs_.checkHooks === true) };
429
480
  for (const env of envs) {
430
481
  const read = [env, ...requiredOf(waves, env)];
431
482
  jobs[`plan-${env}`] = new ActionsJob({
@@ -530,11 +581,11 @@ export function gitlabPipeline(envs_) {
530
581
  rules: mr(),
531
582
  ...(replay
532
583
  ? {
533
- script: [CI_CHECK, ...types, lintCommand("gitlab"), waitFor(svc.name, svc.port), REPLAY, ...(envs_.tests === true ? [TEST] : []), ...check],
584
+ script: envs_.checkHooks === true ? [waitFor(svc.name, svc.port), checkHooksLine("gitlab")] : [CI_CHECK, ...types, lintCommand("gitlab"), waitFor(svc.name, svc.port), REPLAY, ...(envs_.tests === true ? [TEST] : []), ...check],
534
585
  services: [new GitLabService({ name: svc.image, alias: svc.name, variables: svc.env })],
535
586
  variables: { [`${variablePrefix(REPLAY_PROFILE, dialect)}_URL`]: svc.url(svc.name), ...svc.jobEnv },
536
587
  }
537
- : { script: [CI_CHECK, ...types, lintCommand("gitlab")] }),
588
+ : { script: envs_.checkHooks === true ? [checkHooksLine("gitlab")] : [CI_CHECK, ...types, lintCommand("gitlab")] }),
538
589
  // The code quality report, kept when lint fails too: that is when it has something to show.
539
590
  artifacts: new GitLabArtifacts({ when: "always", reports: { codequality: CODE_QUALITY_FILE } }),
540
591
  }));
@@ -633,16 +684,38 @@ export const APPLY_PIPELINE = "yodel-apply";
633
684
  /**
634
685
  * The waves spec. What the file holds is the same for every forge; each
635
686
  * forge's jobs get their own variables on top (`variables`).
687
+ *
688
+ * With `step` (#291), a chant whose sql lexicon has the `sql-migrate`
689
+ * capability (chant#4569): the spec names the capability, and chant plans
690
+ * and applies each run through it, which calls the same engine entry points
691
+ * (`yodel apply <env> --wave-plan` and `--wave-apply`) by a fixed argv. The
692
+ * spec then has no `plan` or `apply` callback. Without it, the callbacks.
693
+ *
694
+ * The steps around apply (#64) under `step`: chant refuses `hooks.apply.runBy:
695
+ * "apply"` with a capability step, and it would run apply-stage hooks
696
+ * around the step itself, outside the engine's lock, while `--wave-apply`
697
+ * with no CHANT_HOOKS runs the steps at base under its lock as well. So the
698
+ * spec keeps only the `before.plan` SQL checks, which chant runs when it
699
+ * plans the wave (one that fails with `onFailure: "approve"` holds the wave
700
+ * for a person), and `--wave-apply` runs every step under its lock, read at
701
+ * the base commit, as it does run by hand. A step runs once, under the
702
+ * lock, as #107 asks.
636
703
  */
637
- export function wavesSpec(waves, variables, resume) {
704
+ export function wavesSpec(waves, variables, resume, options = {}) {
638
705
  const first = waves[0];
639
706
  if (!first)
640
707
  throw new Error("no waves to render");
641
708
  return {
642
709
  name: APPLY_PIPELINE,
643
710
  op: `migrate-${first.env}`,
644
- plan: ["yodel", "apply", "{target}", "--wave-plan", "{plan}", "--spec", WAVES_SPEC],
645
- apply: ["yodel", "apply", "{target}", "--wave-apply", "{plan}", "--spec", WAVES_SPEC],
711
+ ...(options.step
712
+ ? { step: { kind: SQL_MIGRATE, environment: "{target}", spec: WAVES_SPEC } }
713
+ : {
714
+ plan: ["yodel", "apply", "{target}", "--wave-plan", "{plan}", "--spec", WAVES_SPEC],
715
+ apply: ["yodel", "apply", "{target}", "--wave-apply", "{plan}", "--spec", WAVES_SPEC],
716
+ }),
717
+ // chant's stand-down (#293): the job applies nothing and exits 6 when a newer commit on main will apply the same environments.
718
+ ...(options.step && options.chantLocks ? { standDown: true } : {}),
646
719
  branches: [MAIN],
647
720
  waves: waves.map((w) => ({
648
721
  name: w.env,
@@ -652,29 +725,86 @@ export function wavesSpec(waves, variables, resume) {
652
725
  ...(w.approval !== undefined && w.approval !== "ledger" ? { approval: w.approval } : {}),
653
726
  ...(variables ? { environment: { name: w.env }, variables: variables(w.env) } : {}),
654
727
  // The steps around apply (#64) as chant's stage hooks, which the apply runs under its lock (#206).
655
- ...hooksOf(w.steps),
728
+ ...hooksOf(w.steps, options.step === true),
656
729
  })),
657
730
  ...(resume ? { resume } : {}),
658
731
  };
659
732
  }
660
- /** A wave's stage hooks from its steps, when it has any. */
661
- function hooksOf(steps) {
733
+ /**
734
+ * Whether the installed chant locks and stands down the waves itself (#293):
735
+ * `@intentius/chant/op` exports `OP_WAVE_STAND_DOWN_FLOOR` and
736
+ * `newerCommitOnBranch` (chant#4581), and the sql lexicon gives SQL members
737
+ * their lock grain, the environment (`sqlDefaultLockGrain`, chant#4571, on
738
+ * chant#4552's grain). Then the apply jobs carry no lock settings of their
739
+ * own: chant's lease on the target keeps two applies of one environment
740
+ * apart and exits 5 (`held`) for the one that finds it taken, the engine's
741
+ * own lock still guards the history under it, and a superseded apply exits
742
+ * 6 (`superseded`). Lazy imports, with the specifiers in variables, so a
743
+ * published chant keeps YODEL_LOCK_WAIT and YODEL_STAND_DOWN.
744
+ */
745
+ export async function chantLocksWaves() {
746
+ const op = "@intentius/chant/op";
747
+ const grain = "@intentius/chant-lexicon-sql/lock-grain";
748
+ try {
749
+ const m = (await import(op));
750
+ const g = (await import(grain));
751
+ return typeof m.OP_WAVE_STAND_DOWN_FLOOR === "string" && typeof m.newerCommitOnBranch === "function" && typeof g.sqlDefaultLockGrain === "function";
752
+ }
753
+ catch {
754
+ return false;
755
+ }
756
+ }
757
+ /** The sql lexicon's capability for a versioned environment (chant#4569). */
758
+ export const SQL_MIGRATE = "sql-migrate";
759
+ /**
760
+ * Whether the installed sql lexicon plans and applies through chant (#291):
761
+ * it exports `sqlCapabilityPlugin` (chant#4569), and the chant that ships
762
+ * with it runs an op wave's `step`. A lazy import, with the specifier in a
763
+ * variable, so a published lexicon without it keeps the callbacks.
764
+ */
765
+ export async function hasSqlCapability() {
766
+ const specifier = "@intentius/chant-lexicon-sql/capability-plugin";
767
+ try {
768
+ const m = (await import(specifier));
769
+ return m.sqlCapabilityPlugin !== undefined && m.sqlCapabilityPlugin !== null;
770
+ }
771
+ catch {
772
+ return false;
773
+ }
774
+ }
775
+ /** A wave's stage hooks from its steps, when it has any; under a capability `step`, the `before.plan` checks only ({@link wavesSpec}). */
776
+ function hooksOf(steps, step = false) {
662
777
  const hooks = stepHooks(steps);
663
- return hooks ? { hooks } : {};
778
+ if (!hooks)
779
+ return {};
780
+ if (!step)
781
+ return { hooks };
782
+ const plan = hooks.before?.plan;
783
+ return plan && plan.length > 0 ? { hooks: { before: { plan } } } : {};
664
784
  }
665
- /** The waves spec file and the apply pipeline on each forge. */
666
- export async function applyPipelines(dir, envs) {
785
+ /**
786
+ * The waves spec file and the apply pipeline on each forge. With `product`
787
+ * (chant's product pipeline, #289), the spec comes from chant's
788
+ * productPipelineJobs under yodel's words, and each job runs `yodel chant`
789
+ * where chant's own runs `chant` ({@link productWaves}).
790
+ */
791
+ export async function applyPipelines(dir, envs, product) {
667
792
  const { dialect, waves } = envs;
668
793
  const tc = toolchainOf(envs);
669
794
  const { generateOpWavesPipeline } = (await import("@intentius/chant/op"));
670
- const out = [{ path: WAVES_SPEC, content: `${JSON.stringify(wavesSpec(waves), null, 2)}\n` }];
795
+ const named = (forge, spec) => (product ? productWaves(product, forge, spec) : { spec, jobs: [] });
796
+ // Through chant's product pipeline, the sql capability plans and applies (#291) when the installed lexicon has it.
797
+ const capable = product !== undefined && (await hasSqlCapability());
798
+ // chant's lock grain and stand-down (#293), under the capability, when chant has them.
799
+ const step = { step: capable, chantLocks: capable && (await chantLocksWaves()) };
800
+ const out = [{ path: WAVES_SPEC, content: `${JSON.stringify(named("github", wavesSpec(waves, undefined, undefined, step)).spec, null, 2)}\n` }];
671
801
  // A GitLab job already has the project's variables, a writer's only under its environment.
672
802
  const variables = (forge) => (env) => {
673
803
  const wave = waves.find((w) => w.env === env);
674
804
  const required = wave?.requires;
675
805
  return {
676
806
  YODEL_CREDENTIALS: `writer:${env}`,
677
- ...APPLY_LOCK,
807
+ ...(step.chantLocks ? {} : APPLY_LOCK),
678
808
  ...(forge === "gitlab"
679
809
  ? {}
680
810
  : {
@@ -721,7 +851,8 @@ export async function applyPipelines(dir, envs) {
721
851
  "# holds no writer's credentials: it plans with each environment's reader.",
722
852
  ];
723
853
  for (const forge of FORGES) {
724
- const result = await generateOpWavesPipeline(wavesSpec(waves, variables(forge), envs.resume), forge, {
854
+ const { spec, jobs } = named(forge, wavesSpec(waves, variables(forge), envs.resume, step));
855
+ const result = await generateOpWavesPipeline(spec, forge, {
725
856
  specFile: WAVES_SPEC,
726
857
  image: tc.image,
727
858
  beforeScript: [...installLines(tc, forge), FETCH_APPROVALS],
@@ -734,12 +865,12 @@ export async function applyPipelines(dir, envs) {
734
865
  const yaml = file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`;
735
866
  // The resume workflow (GitHub, Forgejo) has no wave job to report on.
736
867
  if (forge !== "gitlab" && file.name === `${APPLY_PIPELINE}-resume.yml`)
737
- out.push({ path: at, content: withHeader(resumeHeader(forge), yaml) });
868
+ out.push({ path: at, content: withHeader(resumeHeader(forge), withBin(product, yaml)) });
738
869
  // The pull request workflow that records the plans a review approves (#48).
739
870
  else if (forge !== "gitlab" && file.name === `${APPLY_PIPELINE}-plans.yml`)
740
- out.push({ path: at, content: withHeader(plansHeader, withPlansReaders(forge, yaml, waves, dialect, envs)) });
871
+ out.push({ path: at, content: withHeader(plansHeader, withBin(product, withPlansReaders(forge, yaml, waves, dialect, envs))) });
741
872
  else
742
- out.push({ path: at, content: withHeader([...header, ...identityHeader(forge, waveClouds)], withWaveReports(forge, yaml, waves, tc, envs)) });
873
+ out.push({ path: at, content: withHeader([...header, ...identityHeader(forge, waveClouds)], withWaveLines(forge, withBin(product, withWaveReports(forge, yaml, waves, tc, envs)), jobs)) });
743
874
  }
744
875
  }
745
876
  return out;
@@ -910,6 +1041,55 @@ export async function withTenants(dir, waves) {
910
1041
  }
911
1042
  return out;
912
1043
  }
1044
+ // ── chant's product pipeline (#289) ─────────────────────────────────────────
1045
+ //
1046
+ // With a chant that has @intentius/chant/ci-product (chant#4550), the apply
1047
+ // waves come from chant's productPipelineJobs with yodel's words: the spec
1048
+ // under yodel's op and gate names (`yodel-apply`, `yodel-apply-wave-<k>`,
1049
+ // the names on the ledger since the waves began, so approvals already
1050
+ // recorded keep counting), and each job running `yodel chant` where chant's
1051
+ // own runs `chant`, so the job writes yodel's statuses and approve lines.
1052
+ // The forge lexicons serialize the jobs as before, and yodel adds its
1053
+ // reports, logins and readers to them as before. A chant without the entry
1054
+ // leaves every file as yodel rendered it before, so main stays green on its
1055
+ // published chant.
1056
+ //
1057
+ // Still yodel's own until chant can run them: the plan jobs (`yodel plan
1058
+ // <env> --comment` with the write probe) wait for the sql lexicon's
1059
+ // capability (chant#4569) and the note through chant's renderer (#290); the
1060
+ // lint job for the check hook (#294); the watch for chant#4582
1061
+ // ({@link watchPipelines}).
1062
+ /** The spec under yodel's words, and the wave jobs chant's product pipeline names for `forge`. */
1063
+ export function productWaves(product, forge, spec) {
1064
+ const out = product.productPipelineJobs(forge, spec.waves[0]?.name ?? MAIN, { words: YODEL_WORDS, waves: spec, wavesSpecFile: WAVES_SPEC });
1065
+ if (!out.waves)
1066
+ throw new Error(`${forge}: chant's product pipeline gave no apply waves`);
1067
+ if (out.waves.specFile !== WAVES_SPEC)
1068
+ throw new Error(`${forge}: chant's product pipeline reads the waves from ${out.waves.specFile}, not ${WAVES_SPEC}`);
1069
+ const named = out.waves.spec;
1070
+ if (named.name !== APPLY_PIPELINE)
1071
+ throw new Error(`${forge}: chant's product pipeline names the waves ${named.name}, and the ledger has them as ${APPLY_PIPELINE}`);
1072
+ return { spec: named, jobs: out.waves.jobs };
1073
+ }
1074
+ /** A `chant` command line in a rendered file: a step's `run:` or a GitLab script line, never a comment. */
1075
+ const CHANT_LINE = /^(\s*(?:- )?(?:run: )?)(chant [a-z].*)$/gm;
1076
+ /** `yaml` with yodel's bin in each chant command line (#289), through chant's own productCommand; unchanged without `product`. */
1077
+ export function withBin(product, yaml) {
1078
+ if (!product)
1079
+ return yaml;
1080
+ const words = product.assertProductWords(YODEL_WORDS);
1081
+ return yaml.replace(CHANT_LINE, (_m, lead, line) => `${lead}${product.productCommand(words, line)}`);
1082
+ }
1083
+ /** Refuses an apply file whose wave jobs do not run the line chant's product pipeline gives each of them. */
1084
+ function withWaveLines(forge, yaml, jobs) {
1085
+ for (const job of jobs) {
1086
+ const line = job.command.join(" ");
1087
+ if (!new RegExp(`^\\s*(?:- )?(?:run: )?${line.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`, "m").test(yaml)) {
1088
+ throw new Error(`${forge}: wave job ${job.jobName} does not run ${line}, the line chant's product pipeline gives it`);
1089
+ }
1090
+ }
1091
+ return yaml;
1092
+ }
913
1093
  /**
914
1094
  * The watch's spec for one environment: the Op, and on GitHub and Forgejo the
915
1095
  * reader's secrets. A GitLab job already has the project's variables (a
@@ -982,7 +1162,19 @@ function withWatchIdTokens(yaml, envs) {
982
1162
  }
983
1163
  return emit(doc);
984
1164
  }
985
- export async function watchPipelines(dir, envs_) {
1165
+ /**
1166
+ * The drift watches. With `product` (#289) each job runs `yodel chant run
1167
+ * watch-<env>` where chant's runs `chant run watch-<env>`, so the Op's
1168
+ * statuses and notices say yodel.
1169
+ *
1170
+ * The job stays chant's generateOpsPipeline and its last line stays `yodel
1171
+ * drift <env> --issue`, which plans the build for ClickHouse grant drift
1172
+ * (../chant/drift.ts `withClickHouseGrants`), since `chant lifecycle diff
1173
+ * --live` leaves ClickHouse::Grant out. Once chant#4582 puts grants in the
1174
+ * sql lexicon's live diff, the watch moves onto chant's drift job with
1175
+ * `stages.drift` and the workaround goes.
1176
+ */
1177
+ export async function watchPipelines(dir, envs_, product) {
986
1178
  const { dialect, names: envs } = envs_;
987
1179
  const tc = toolchainOf(envs_);
988
1180
  const { generateOpsPipeline } = (await import("@intentius/chant/op"));
@@ -1001,7 +1193,7 @@ export async function watchPipelines(dir, envs_) {
1001
1193
  const yaml = file.yaml.endsWith("\n") ? file.yaml : `${file.yaml}\n`;
1002
1194
  // A GitHub or Forgejo file is one environment's watch: its name is watch-<env>.yml.
1003
1195
  const env = file.name.replace(/^watch-|\.yml$/g, "");
1004
- out.push({ path: at, content: `${HEADER.join("\n")}\n${forge === "gitlab" ? withWatchIdTokens(yaml, envs_) : withWatchLogin(forge, yaml, env, envs_)}` });
1196
+ out.push({ path: at, content: `${HEADER.join("\n")}\n${withBin(product, forge === "gitlab" ? withWatchIdTokens(yaml, envs_) : withWatchLogin(forge, yaml, env, envs_))}` });
1005
1197
  }
1006
1198
  };
1007
1199
  // `chant run` exits 0 when a watch finds drift; the last line, yodel drift, fails the job then.
@@ -1075,6 +1267,7 @@ export async function environments(dir) {
1075
1267
  ...(ci?.login ? { login: ci.login } : {}),
1076
1268
  ...(ci?.apply === false ? { apply: false } : {}),
1077
1269
  ...(check ? { check: true } : {}),
1270
+ ...(ci?.tools && ci.tools.length > 0 ? { tools: ci.tools } : {}),
1078
1271
  };
1079
1272
  }
1080
1273
  /** The roles of each environment whose profile is made with credentials(). */
@@ -1131,6 +1324,26 @@ function ownJobs(own, yodels, what) {
1131
1324
  export function review(envs) {
1132
1325
  return [actionsReview("github", envs), actionsReview("forgejo", envs), gitlabPipeline(envs)];
1133
1326
  }
1327
+ /**
1328
+ * The workspace declaration with yodel's check presets in `ci.hooks.check`
1329
+ * (#294), or undefined when the installed chant has no check moment or the
1330
+ * project has no declaration. The hooks are one list for every forge: the
1331
+ * lint and check presets print with `--format forge`, so a GitHub or
1332
+ * Forgejo job annotates the files and a GitLab job writes the code quality
1333
+ * report its artifact keeps.
1334
+ */
1335
+ export async function checkHooksDeclaration(dir, envs_, declaration) {
1336
+ const chant = await chantCheckHooks();
1337
+ const file = declarationFile(dir);
1338
+ if (!chant)
1339
+ return undefined;
1340
+ if (file)
1341
+ return { path: file, content: declarationWithHooks(chant, dir, file, checkHooksOf(envs_)) };
1342
+ // A declaration `yodel upgrade` adds, rendered before it is written (#298).
1343
+ if (declaration)
1344
+ return { path: declaration.path, content: declarationWithHooks(chant, dir, declaration.path, checkHooksOf(envs_), declaration.content) };
1345
+ return undefined;
1346
+ }
1134
1347
  /** The forge a rendered file is for; undefined for the waves spec, which every forge's apply reads. */
1135
1348
  export function forgeOf(path) {
1136
1349
  if (path.startsWith(".github/"))
@@ -1141,13 +1354,27 @@ export function forgeOf(path) {
1141
1354
  return "gitlab";
1142
1355
  return undefined;
1143
1356
  }
1144
- export async function render(dir) {
1357
+ /**
1358
+ * Every file `yodel ci` writes. Through chant's product pipeline when the
1359
+ * installed chant has it (#289), unless `options.product` is false, which
1360
+ * renders with yodel's own generator as a chant before chant#4550 does.
1361
+ * `options.declaration` is a workspace declaration to render the check
1362
+ * hooks into when the project has none on disk: the one `yodel upgrade`
1363
+ * adds (#298).
1364
+ */
1365
+ export async function render(dir, options = {}) {
1145
1366
  const envs = await environments(dir);
1146
1367
  const forges = envs.forges ?? FORGES;
1147
1368
  if (envs.checkOnly)
1148
1369
  return review(envs).filter((f) => forges.includes(forgeOf(f.path)));
1370
+ const product = options.product === false ? undefined : await chantProduct();
1371
+ // The cloud login through chant's ci-identity (#296), with the product pipeline, when chant and the sql lexicon have it.
1372
+ useChantTrade(product ? await chantTrade() : undefined);
1373
+ // The check on chant's check moment (#294), with the product pipeline, when chant has the moment and the project a declaration.
1374
+ const hooks = product ? await checkHooksDeclaration(dir, envs, options.declaration) : undefined;
1375
+ const reviewed = hooks ? { ...envs, checkHooks: true } : envs;
1149
1376
  // ci.apply: false (#175): no waves spec and no apply pipeline on any forge.
1150
- const files = [...review(envs), ...(rendersApply(envs) ? await applyPipelines(dir, envs) : []), ...(await watchPipelines(dir, envs))];
1377
+ const files = [...review(reviewed), ...(hooks ? [hooks] : []), ...(rendersApply(envs) ? await applyPipelines(dir, envs, product) : []), ...(await watchPipelines(dir, envs, product))];
1151
1378
  return files.filter((f) => {
1152
1379
  const forge = forgeOf(f.path);
1153
1380
  return forge === undefined || forges.includes(forge);