@intentius/chant 0.124.96 → 0.124.98

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 (237) hide show
  1. package/dist/audit/core.d.ts +29 -0
  2. package/dist/audit/core.d.ts.map +1 -1
  3. package/dist/audit/core.js +48 -11
  4. package/dist/audit/identity.d.ts +27 -0
  5. package/dist/audit/identity.d.ts.map +1 -0
  6. package/dist/audit/identity.js +36 -0
  7. package/dist/audit/report-html.d.ts +3 -1
  8. package/dist/audit/report-html.d.ts.map +1 -1
  9. package/dist/audit/report-html.js +1 -1
  10. package/dist/audit/report-model.d.ts +16 -0
  11. package/dist/audit/report-model.d.ts.map +1 -1
  12. package/dist/audit/report-model.js +5 -1
  13. package/dist/change-set-graph.d.ts +3 -1
  14. package/dist/change-set-graph.d.ts.map +1 -1
  15. package/dist/change-set-graph.js +7 -1
  16. package/dist/change-set.d.ts +5 -2
  17. package/dist/change-set.d.ts.map +1 -1
  18. package/dist/change-set.js +6 -3
  19. package/dist/ci-agent.d.ts +17 -0
  20. package/dist/ci-agent.d.ts.map +1 -1
  21. package/dist/ci-agent.js +32 -0
  22. package/dist/ci-comment-allow.d.ts +88 -0
  23. package/dist/ci-comment-allow.d.ts.map +1 -0
  24. package/dist/ci-comment-allow.js +178 -0
  25. package/dist/ci-comment-commands.d.ts +12 -0
  26. package/dist/ci-comment-commands.d.ts.map +1 -1
  27. package/dist/ci-comment-commands.js +22 -0
  28. package/dist/ci-control.d.ts +6 -1
  29. package/dist/ci-control.d.ts.map +1 -1
  30. package/dist/ci-control.js +6 -1
  31. package/dist/ci-product.d.ts +3 -0
  32. package/dist/ci-product.d.ts.map +1 -1
  33. package/dist/ci-product.js +3 -0
  34. package/dist/cli/commands/audit.d.ts +3 -1
  35. package/dist/cli/commands/audit.d.ts.map +1 -1
  36. package/dist/cli/commands/audit.js +23 -6
  37. package/dist/cli/commands/import.d.ts +8 -1
  38. package/dist/cli/commands/import.d.ts.map +1 -1
  39. package/dist/cli/commands/import.js +31 -6
  40. package/dist/cli/handlers/agent.d.ts.map +1 -1
  41. package/dist/cli/handlers/agent.js +12 -2
  42. package/dist/cli/handlers/pr-comment.d.ts +6 -0
  43. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  44. package/dist/cli/handlers/pr-comment.js +12 -0
  45. package/dist/cli/handlers/promote.d.ts.map +1 -1
  46. package/dist/cli/handlers/promote.js +53 -6
  47. package/dist/cli/main.d.ts.map +1 -1
  48. package/dist/cli/main.js +29 -6
  49. package/dist/cli/parse-args.d.ts.map +1 -1
  50. package/dist/cli/parse-args.js +23 -0
  51. package/dist/cli/registry.d.ts +8 -0
  52. package/dist/cli/registry.d.ts.map +1 -1
  53. package/dist/cloud-lister/mask.d.ts +30 -1
  54. package/dist/cloud-lister/mask.d.ts.map +1 -1
  55. package/dist/cloud-lister/mask.js +66 -3
  56. package/dist/components/driver.d.ts +8 -1
  57. package/dist/components/driver.d.ts.map +1 -1
  58. package/dist/components/driver.js +1 -0
  59. package/dist/components/product-pipeline.d.ts +23 -1
  60. package/dist/components/product-pipeline.d.ts.map +1 -1
  61. package/dist/components/product-pipeline.js +40 -7
  62. package/dist/components/product-plan.d.ts +20 -0
  63. package/dist/components/product-plan.d.ts.map +1 -1
  64. package/dist/components/product-plan.js +11 -1
  65. package/dist/control/applied.d.ts +8 -1
  66. package/dist/control/applied.d.ts.map +1 -1
  67. package/dist/control/applied.js +18 -2
  68. package/dist/control/dispatch.d.ts +52 -0
  69. package/dist/control/dispatch.d.ts.map +1 -1
  70. package/dist/control/dispatch.js +140 -4
  71. package/dist/control/train.d.ts +198 -0
  72. package/dist/control/train.d.ts.map +1 -0
  73. package/dist/control/train.js +294 -0
  74. package/dist/deep-observation.js +2 -2
  75. package/dist/floor-table.data.d.ts.map +1 -1
  76. package/dist/floor-table.data.js +7 -1
  77. package/dist/graph-detail.d.ts +9 -0
  78. package/dist/graph-detail.d.ts.map +1 -1
  79. package/dist/graph-detail.js +38 -13
  80. package/dist/graph-refs.d.ts +233 -3
  81. package/dist/graph-refs.d.ts.map +1 -1
  82. package/dist/graph-refs.js +106 -15
  83. package/dist/lint/post-synth.d.ts +22 -0
  84. package/dist/lint/post-synth.d.ts.map +1 -1
  85. package/dist/lint/rules/declarable-naming-convention.d.ts +12 -0
  86. package/dist/lint/rules/declarable-naming-convention.d.ts.map +1 -1
  87. package/dist/lint/rules/declarable-naming-convention.js +38 -8
  88. package/dist/lint/rules/imported-source.d.ts +20 -0
  89. package/dist/lint/rules/imported-source.d.ts.map +1 -0
  90. package/dist/lint/rules/imported-source.js +27 -0
  91. package/dist/lint/rules/no-unused-declarable.d.ts.map +1 -1
  92. package/dist/lint/rules/no-unused-declarable.js +3 -0
  93. package/dist/op/gate.d.ts +2 -0
  94. package/dist/op/gate.d.ts.map +1 -1
  95. package/dist/op/gate.js +8 -1
  96. package/dist/pr-forge-reads.d.ts +17 -0
  97. package/dist/pr-forge-reads.d.ts.map +1 -1
  98. package/dist/pr-forge-reads.js +55 -0
  99. package/dist/reconcile.d.ts +9 -0
  100. package/dist/reconcile.d.ts.map +1 -1
  101. package/dist/release-floors.d.ts +9 -1
  102. package/dist/release-floors.d.ts.map +1 -1
  103. package/dist/release-floors.js +10 -2
  104. package/dist/repo-path.d.ts +29 -0
  105. package/dist/repo-path.d.ts.map +1 -0
  106. package/dist/repo-path.js +81 -0
  107. package/dist/sensitive-key.d.ts +23 -0
  108. package/dist/sensitive-key.d.ts.map +1 -1
  109. package/dist/sensitive-key.js +37 -0
  110. package/dist/terraform/hcl2json.d.ts +7 -0
  111. package/dist/terraform/hcl2json.d.ts.map +1 -1
  112. package/dist/terraform/hcl2json.js +7 -0
  113. package/dist/wave-runtime.mjs +352 -345
  114. package/dist/workspace/catalog-edges.d.ts +147 -0
  115. package/dist/workspace/catalog-edges.d.ts.map +1 -0
  116. package/dist/workspace/catalog-edges.js +461 -0
  117. package/dist/workspace/compose-graph.d.ts +73 -3
  118. package/dist/workspace/compose-graph.d.ts.map +1 -1
  119. package/dist/workspace/declaration.d.ts +2 -0
  120. package/dist/workspace/declaration.d.ts.map +1 -1
  121. package/dist/workspace/declaration.js +1 -0
  122. package/dist/workspace/declaration.schema.json +6 -0
  123. package/dist/workspace/discover.d.ts +134 -0
  124. package/dist/workspace/discover.d.ts.map +1 -0
  125. package/dist/workspace/discover.js +372 -0
  126. package/dist/workspace/graph-cli.d.ts +20 -0
  127. package/dist/workspace/graph-cli.d.ts.map +1 -1
  128. package/dist/workspace/graph-cli.js +178 -20
  129. package/dist/workspace/graph.schema.json +195 -2
  130. package/dist/workspace/release-train.d.ts +214 -3
  131. package/dist/workspace/release-train.d.ts.map +1 -1
  132. package/dist/workspace/release-train.js +552 -16
  133. package/dist/workspace/repo-ref.d.ts +14 -0
  134. package/dist/workspace/repo-ref.d.ts.map +1 -1
  135. package/dist/workspace/repo-ref.js +26 -1
  136. package/dist/workspace/workspace-gates.d.ts +24 -0
  137. package/dist/workspace/workspace-gates.d.ts.map +1 -1
  138. package/dist/workspace/workspace-gates.js +29 -5
  139. package/dist/workspace/workspace-ledger.d.ts +31 -5
  140. package/dist/workspace/workspace-ledger.d.ts.map +1 -1
  141. package/dist/workspace/workspace-ledger.js +2 -1
  142. package/dist/workspace/workspace-run.d.ts +14 -0
  143. package/dist/workspace/workspace-run.d.ts.map +1 -1
  144. package/dist/workspace/workspace-run.js +2 -2
  145. package/dist/yaml.d.ts.map +1 -1
  146. package/dist/yaml.js +33 -8
  147. package/package.json +1 -1
  148. package/src/audit/core.test.ts +64 -1
  149. package/src/audit/core.ts +75 -10
  150. package/src/audit/identity.test.ts +31 -0
  151. package/src/audit/identity.ts +43 -0
  152. package/src/audit/report-html.ts +4 -2
  153. package/src/audit/report-model.ts +21 -1
  154. package/src/change-set-graph.test.ts +33 -1
  155. package/src/change-set-graph.ts +7 -1
  156. package/src/change-set.ts +6 -3
  157. package/src/ci-agent.test.ts +32 -0
  158. package/src/ci-agent.ts +42 -0
  159. package/src/ci-comment-allow.test.ts +380 -0
  160. package/src/ci-comment-allow.ts +184 -0
  161. package/src/ci-comment-commands.ts +25 -0
  162. package/src/ci-control.ts +42 -0
  163. package/src/ci-product.ts +3 -0
  164. package/src/cli/commands/audit-parser-notice.test.ts +74 -0
  165. package/src/cli/commands/audit.test.ts +12 -0
  166. package/src/cli/commands/audit.ts +25 -7
  167. package/src/cli/commands/import-layout.test.ts +2 -1
  168. package/src/cli/commands/import.ts +29 -6
  169. package/src/cli/handlers/agent.ts +13 -2
  170. package/src/cli/handlers/pr-before-merge.test.ts +18 -0
  171. package/src/cli/handlers/pr-comment.ts +12 -0
  172. package/src/cli/handlers/promote.test.ts +68 -0
  173. package/src/cli/handlers/promote.ts +52 -6
  174. package/src/cli/main.test.ts +5 -0
  175. package/src/cli/main.ts +29 -6
  176. package/src/cli/parse-args.ts +18 -0
  177. package/src/cli/registry.ts +8 -0
  178. package/src/cloud-lister/kubernetes.k3d.e2e.test.ts +104 -0
  179. package/src/cloud-lister/mask-references.test.ts +132 -0
  180. package/src/cloud-lister/mask.ts +68 -3
  181. package/src/components/driver.ts +9 -1
  182. package/src/components/product-pipeline.ts +57 -7
  183. package/src/components/product-plan.ts +27 -2
  184. package/src/control/applied.ts +33 -3
  185. package/src/control/dispatch.ts +156 -5
  186. package/src/control/train.test.ts +215 -0
  187. package/src/control/train.ts +413 -0
  188. package/src/deep-observation.ts +2 -2
  189. package/src/floor-table.data.ts +7 -1
  190. package/src/graph-detail.ts +37 -12
  191. package/src/graph-refs.test.ts +45 -1
  192. package/src/graph-refs.ts +321 -14
  193. package/src/lint/post-synth.ts +20 -0
  194. package/src/lint/rules/declarable-naming-convention.test.ts +35 -1
  195. package/src/lint/rules/declarable-naming-convention.ts +35 -8
  196. package/src/lint/rules/imported-source.test.ts +22 -0
  197. package/src/lint/rules/imported-source.ts +31 -0
  198. package/src/lint/rules/no-unused-declarable.test.ts +16 -0
  199. package/src/lint/rules/no-unused-declarable.ts +7 -0
  200. package/src/op/gate.ts +10 -2
  201. package/src/pr-forge-reads.ts +62 -0
  202. package/src/reconcile.ts +9 -0
  203. package/src/release-floors.ts +14 -2
  204. package/src/repo-path.test.ts +72 -0
  205. package/src/repo-path.ts +103 -0
  206. package/src/sensitive-key.ts +38 -0
  207. package/src/terraform/hcl2json.ts +8 -0
  208. package/src/workspace/application-set.e2e.test.ts +405 -0
  209. package/src/workspace/catalog-edges.ts +507 -0
  210. package/src/workspace/ci-green-workflow.test.ts +2 -2
  211. package/src/workspace/cluster-join.e2e.test.ts +150 -0
  212. package/src/workspace/compose-graph.ts +74 -5
  213. package/src/workspace/declaration.schema.json +6 -0
  214. package/src/workspace/declaration.ts +3 -0
  215. package/src/workspace/discover.e2e.test.ts +122 -0
  216. package/src/workspace/discover.test.ts +225 -0
  217. package/src/workspace/discover.ts +406 -0
  218. package/src/workspace/drift-reader.test.ts +3 -3
  219. package/src/workspace/external-secret-catalog.e2e.test.ts +98 -0
  220. package/src/workspace/external-secret-catalog.test.ts +142 -0
  221. package/src/workspace/graph-cli.ts +207 -21
  222. package/src/workspace/graph-contract.test.ts +92 -0
  223. package/src/workspace/graph.schema.json +195 -2
  224. package/src/workspace/helm-references.e2e.test.ts +135 -0
  225. package/src/workspace/identity-annotation-catalog.e2e.test.ts +91 -0
  226. package/src/workspace/identity-annotation-catalog.test.ts +139 -0
  227. package/src/workspace/release-train-repos.test.ts +304 -0
  228. package/src/workspace/release-train.test.ts +296 -0
  229. package/src/workspace/release-train.ts +631 -16
  230. package/src/workspace/repo-ref.ts +26 -1
  231. package/src/workspace/runs-on.test.ts +45 -0
  232. package/src/workspace/workspace-gates.ts +48 -5
  233. package/src/workspace/workspace-ledger.ts +28 -5
  234. package/src/workspace/workspace-run.test.ts +1 -1
  235. package/src/workspace/workspace-run.ts +2 -2
  236. package/src/yaml.test.ts +96 -8
  237. package/src/yaml.ts +36 -8
@@ -0,0 +1,198 @@
1
+ /**
2
+ * A release train across repositories (#5119): the control repo dispatches
3
+ * into each member repository in turn, and each member answers with its
4
+ * existing `<product>-applied` dispatch.
5
+ *
6
+ * - The control repo's promote (`chant workspace train promote`, in
7
+ * ../workspace/release-train.ts) sends one `<product>-train` dispatch to a
8
+ * member repository, carrying the member, the environment, the train, the
9
+ * run of its promote, the release digest and the release's commit. It
10
+ * holds one dispatch-only token per member repository
11
+ * ({@link trainTokenEnv}) and no cloud credentials.
12
+ * - The member's `<product>-train` job checks out the release's commit and
13
+ * runs `chant run --components all --env <env> --release <digest>` under
14
+ * its own identity, so its deploy records name the release. It then tells
15
+ * the control repo how the run ended, with the train's fields, through
16
+ * the dispatch step of ./dispatch.ts.
17
+ * - The control repo records that answer in `_control/applied.jsonl` and
18
+ * continues the train (`--continue`): the next member after `applied` or
19
+ * `unchanged`, else the train stops there.
20
+ *
21
+ * The jobs are written for GitHub and Forgejo, whose workflows share one
22
+ * shape; a GitLab member repository takes no train dispatch yet. This file
23
+ * builds the requests and the jobs; the forge lexicons serialize the jobs.
24
+ * Like ./dispatch.ts it imports types and the words alone, so a product
25
+ * bundle can carry it.
26
+ */
27
+ import type { ForgeFetch, ForgeKind } from "../pr-forge.js";
28
+ import { type CiProductWords, type CiProductWordsInput } from "../ci-product-words.js";
29
+ import { trainTokenEnv, trainTokenEnvOf, type ControlTarget } from "./dispatch.js";
30
+ export { trainTokenEnv, trainTokenEnvOf };
31
+ /** The first chant with release trains across repositories (#5119). `trainControlJobSpec` present means the rest is too. */
32
+ export declare const CONTROL_TRAIN_FLOOR = "0.124.98";
33
+ /** The variables the member's train job reads the dispatch from. */
34
+ export declare const TRAIN_ENV_VAR = "CHANT_TRAIN_ENV";
35
+ export declare const TRAIN_ID_VAR = "CHANT_TRAIN_ID";
36
+ export declare const TRAIN_RUN_VAR = "CHANT_TRAIN_RUN";
37
+ export declare const TRAIN_RELEASE_VAR = "CHANT_TRAIN_RELEASE";
38
+ export declare const TRAIN_COMMIT_VAR = "CHANT_TRAIN_COMMIT";
39
+ /** The variable a control repo's job names its product in, so the dispatch's event and file names are the product's: `<product>-train`. */
40
+ export declare const TRAIN_PRODUCT_VAR = "CHANT_TRAIN_PRODUCT";
41
+ /** The product a control repo's job names in {@link TRAIN_PRODUCT_VAR}, or chant's when it names none or one that is not a name. */
42
+ export declare function trainProductOf(env?: Record<string, string | undefined>): CiProductWordsInput;
43
+ /** The forges a train dispatches into and its jobs are written for. */
44
+ export type TrainForge = Exclude<ForgeKind, "gitlab">;
45
+ /** The event type of the dispatch a member repository takes: `<product>-train`. */
46
+ export declare function trainDispatchEvent(wordsIn?: CiProductWordsInput | CiProductWords): string;
47
+ /** The train workflow's file name, the same in the member repository and the control repo: `<product>-train.yml`. */
48
+ export declare function trainPipelineFileName(wordsIn?: CiProductWordsInput | CiProductWords): string;
49
+ /** Where the train workflow goes on each forge. */
50
+ export declare function trainPipelinePath(forge: TrainForge, wordsIn?: CiProductWordsInput | CiProductWords): string;
51
+ /** What one dispatch into a member repository carries. */
52
+ export interface TrainDispatch {
53
+ member: string;
54
+ env: string;
55
+ train: string;
56
+ run: string;
57
+ releaseDigest: string;
58
+ /** The release's commit, which the member checks out and runs. */
59
+ commit: string;
60
+ }
61
+ /** The problems with a dispatch, or [] when it can be sent. */
62
+ export declare function trainDispatchProblems(d: TrainDispatch): string[];
63
+ /** A member repository a train dispatches into. */
64
+ export interface TrainMemberTarget {
65
+ /** The repository's URL as the declaration names it, credentials removed. */
66
+ repo: string;
67
+ host: string;
68
+ path: string;
69
+ forge: TrainForge;
70
+ apiBase: string;
71
+ /** The branch a Forgejo dispatch runs on. */
72
+ ref: string;
73
+ }
74
+ /**
75
+ * The forge repository a `repo` member's URL names: `https://<host>/<path>`,
76
+ * `ssh://[user@]<host>/<path>` or `<user>@<host>:<path>`, with or without
77
+ * `.git`. A local path names no forge and is refused, as is a host that
78
+ * does not say which forge it is unless `forge` does, and a GitLab one.
79
+ */
80
+ export declare function trainMemberTarget(url: string, opts?: {
81
+ forge?: ForgeKind;
82
+ apiBase?: string;
83
+ ref?: string;
84
+ }): TrainMemberTarget;
85
+ /** One dispatch request into a member repository, without its token. */
86
+ export interface TrainDispatchRequest {
87
+ url: string;
88
+ method: "POST";
89
+ headers: Record<string, string>;
90
+ body: {
91
+ json: Record<string, unknown>;
92
+ };
93
+ token: {
94
+ in: "header";
95
+ name: string;
96
+ scheme: string;
97
+ };
98
+ }
99
+ /**
100
+ * The request that starts a member's train job: GitHub's `repository_dispatch`
101
+ * of `<product>-train`, or a Forgejo workflow dispatch of `<product>-train.yml`.
102
+ */
103
+ export declare function trainDispatchRequest(target: TrainMemberTarget, d: TrainDispatch, wordsIn?: CiProductWordsInput | CiProductWords): TrainDispatchRequest;
104
+ /** What {@link dispatchTrainMember} takes. */
105
+ export interface DispatchTrainOptions {
106
+ /** The dispatch token. Default: {@link trainTokenEnv} of the member in `env`. */
107
+ token?: string;
108
+ env?: Record<string, string | undefined>;
109
+ fetch?: ForgeFetch;
110
+ words?: CiProductWordsInput | CiProductWords;
111
+ }
112
+ /**
113
+ * Sends one dispatch into a member repository. A missing token or a status
114
+ * other than 2xx throws {@link ControlDispatchError}, the token cut out of
115
+ * the forge's answer.
116
+ */
117
+ export declare function dispatchTrainMember(target: TrainMemberTarget, d: TrainDispatch, opts?: DispatchTrainOptions): Promise<{
118
+ status: number;
119
+ }>;
120
+ /** What {@link trainMemberJobSpec} takes besides the control target. */
121
+ export interface TrainMemberJobOptions {
122
+ words?: CiProductWordsInput | CiProductWords;
123
+ /** The command the job runs chant with. Default `npx --no-install chant`. */
124
+ command?: string;
125
+ /** The directory the run starts in, relative to the repository root: the workspace root the `repo` member names. Default the root. */
126
+ dir?: string;
127
+ /** The install line run before chant. Default `npm ci`. */
128
+ install?: string;
129
+ }
130
+ type Inputs = Record<string, {
131
+ description: string;
132
+ required: boolean;
133
+ type: "string";
134
+ }>;
135
+ /** The member's train job, for a GitHub-shaped forge: what a forge lexicon serializes. */
136
+ export interface TrainMemberJobSpec {
137
+ forge: TrainForge;
138
+ path: string;
139
+ header: string[];
140
+ /** GitHub: the `repository_dispatch` event type. */
141
+ event: string;
142
+ /** The manual dispatch's inputs. */
143
+ inputs: Inputs;
144
+ /** The run step: its environment (the dispatch's fields) and script. */
145
+ run: {
146
+ name: string;
147
+ env: Record<string, string>;
148
+ script: string;
149
+ workingDirectory: string | null;
150
+ };
151
+ /** The answer step, run whatever the run step did. It alone holds the control repo's token. */
152
+ answer: {
153
+ name: string;
154
+ env: Record<string, string>;
155
+ script: string;
156
+ };
157
+ /** The expression the checkout takes the release's commit from. */
158
+ commit: string;
159
+ /** One train job at a time in the repository, none cancelled. */
160
+ group: string;
161
+ notes: string[];
162
+ }
163
+ /**
164
+ * The job a member repository adds to take a train's dispatch (#5119). It
165
+ * checks out the release's commit, runs `chant run --components all --env
166
+ * <env> --release <digest>` under the repository's own identity, which
167
+ * records each deploy with the release's digest, and answers the control
168
+ * repo with `<product>-applied`: the outcome (`applied`, `waiting` at the
169
+ * member's own gate, or `failed`) and the train's fields. A product adds
170
+ * its own cloud login before the run step; the answer step holds the
171
+ * control repo's dispatch token and nothing else.
172
+ */
173
+ export declare function trainMemberJobSpec(forge: TrainForge, control: ControlTarget, opts?: TrainMemberJobOptions): TrainMemberJobSpec;
174
+ /** The control repo's train job, for a GitHub-shaped forge. */
175
+ export interface TrainControlJobSpec {
176
+ forge: TrainForge;
177
+ path: string;
178
+ header: string[];
179
+ inputs: Inputs;
180
+ /** The step's environment: the inputs, and one dispatch token per member repository. No cloud credential. */
181
+ env: Record<string, string>;
182
+ script: string;
183
+ group: string;
184
+ notes: string[];
185
+ }
186
+ /**
187
+ * The control repo's job that starts a train's promote (#5119): `chant
188
+ * workspace train promote <env> [<train>]`, which dispatches the first
189
+ * member repository, then a push of what it recorded on `chant/lifecycle`.
190
+ * Each later member is dispatched by the control repo's dependents job
191
+ * when the one before it answers. The job holds one dispatch token per
192
+ * member repository and nothing else: no cloud login, no `id-token`.
193
+ */
194
+ export declare function trainControlJobSpec(forge: TrainForge, members: readonly string[], opts?: {
195
+ words?: CiProductWordsInput | CiProductWords;
196
+ command?: string;
197
+ }): TrainControlJobSpec;
198
+ //# sourceMappingURL=train.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"train.d.ts","sourceRoot":"","sources":["../../src/control/train.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,294 @@
1
+ /**
2
+ * A release train across repositories (#5119): the control repo dispatches
3
+ * into each member repository in turn, and each member answers with its
4
+ * existing `<product>-applied` dispatch.
5
+ *
6
+ * - The control repo's promote (`chant workspace train promote`, in
7
+ * ../workspace/release-train.ts) sends one `<product>-train` dispatch to a
8
+ * member repository, carrying the member, the environment, the train, the
9
+ * run of its promote, the release digest and the release's commit. It
10
+ * holds one dispatch-only token per member repository
11
+ * ({@link trainTokenEnv}) and no cloud credentials.
12
+ * - The member's `<product>-train` job checks out the release's commit and
13
+ * runs `chant run --components all --env <env> --release <digest>` under
14
+ * its own identity, so its deploy records name the release. It then tells
15
+ * the control repo how the run ended, with the train's fields, through
16
+ * the dispatch step of ./dispatch.ts.
17
+ * - The control repo records that answer in `_control/applied.jsonl` and
18
+ * continues the train (`--continue`): the next member after `applied` or
19
+ * `unchanged`, else the train stops there.
20
+ *
21
+ * The jobs are written for GitHub and Forgejo, whose workflows share one
22
+ * shape; a GitLab member repository takes no train dispatch yet. This file
23
+ * builds the requests and the jobs; the forge lexicons serialize the jobs.
24
+ * Like ./dispatch.ts it imports types and the words alone, so a product
25
+ * bundle can carry it.
26
+ */
27
+ import { resolveProductWords } from "../ci-product-words.js";
28
+ import { NEXT_RELEASE } from "../release-floors.js";
29
+ import { CONTROL_CHANT_COMMAND, CONTROL_ENV_VAR, CONTROL_NAME, CONTROL_OUTCOME_VAR, CONTROL_REF, CONTROL_REF_DEFAULT, CONTROL_RELEASE_DIGEST, CONTROL_RELEASE_VAR, CONTROL_RUN_ID, CONTROL_RUN_VAR, CONTROL_SHA_VAR, CONTROL_TOKEN_ENV, CONTROL_TRAIN_ID, CONTROL_TRAIN_VAR, ControlConfigError, ControlDispatchError, controlDispatchScript, forgeApiBase, forgeFromHost, shellPatterns, trainTokenEnv, trainTokenEnvOf, } from "./dispatch.js";
30
+ export { trainTokenEnv, trainTokenEnvOf };
31
+ /** The first chant with release trains across repositories (#5119). `trainControlJobSpec` present means the rest is too. */
32
+ export const CONTROL_TRAIN_FLOOR = NEXT_RELEASE;
33
+ /** The variables the member's train job reads the dispatch from. */
34
+ export const TRAIN_ENV_VAR = "CHANT_TRAIN_ENV";
35
+ export const TRAIN_ID_VAR = "CHANT_TRAIN_ID";
36
+ export const TRAIN_RUN_VAR = "CHANT_TRAIN_RUN";
37
+ export const TRAIN_RELEASE_VAR = "CHANT_TRAIN_RELEASE";
38
+ export const TRAIN_COMMIT_VAR = "CHANT_TRAIN_COMMIT";
39
+ /** The variable a control repo's job names its product in, so the dispatch's event and file names are the product's: `<product>-train`. */
40
+ export const TRAIN_PRODUCT_VAR = "CHANT_TRAIN_PRODUCT";
41
+ /** The product a control repo's job names in {@link TRAIN_PRODUCT_VAR}, or chant's when it names none or one that is not a name. */
42
+ export function trainProductOf(env = process.env) {
43
+ const p = env[TRAIN_PRODUCT_VAR];
44
+ return p && /^[a-z][a-z0-9-]{0,63}$/.test(p) ? { product: p } : {};
45
+ }
46
+ /** The exit code `chant run` ends with when a run waits at a gate (`CHANT_EXIT.waiting`). */
47
+ const WAITING_EXIT = 3;
48
+ const SHA = /^[0-9a-f]{7,64}$/;
49
+ /** The event type of the dispatch a member repository takes: `<product>-train`. */
50
+ export function trainDispatchEvent(wordsIn = {}) {
51
+ return `${resolveProductWords(wordsIn).product}-train`;
52
+ }
53
+ /** The train workflow's file name, the same in the member repository and the control repo: `<product>-train.yml`. */
54
+ export function trainPipelineFileName(wordsIn = {}) {
55
+ return `${resolveProductWords(wordsIn).product}-train.yml`;
56
+ }
57
+ /** Where the train workflow goes on each forge. */
58
+ export function trainPipelinePath(forge, wordsIn = {}) {
59
+ return `${forge === "github" ? ".github" : ".forgejo"}/workflows/${trainPipelineFileName(wordsIn)}`;
60
+ }
61
+ /** The problems with a dispatch, or [] when it can be sent. */
62
+ export function trainDispatchProblems(d) {
63
+ const out = [];
64
+ if (!CONTROL_NAME.test(d.member))
65
+ out.push(`member "${d.member}" is not a member's name`);
66
+ if (!CONTROL_NAME.test(d.env))
67
+ out.push(`env "${d.env}" is not an environment's name`);
68
+ if (!CONTROL_TRAIN_ID.test(d.train))
69
+ out.push(`train "${d.train}" is not a release train's id`);
70
+ if (!CONTROL_RUN_ID.test(d.run))
71
+ out.push(`run "${d.run}" is not a workspace run's id`);
72
+ if (!CONTROL_RELEASE_DIGEST.test(d.releaseDigest))
73
+ out.push(`release "${d.releaseDigest}" is not a release digest`);
74
+ if (!SHA.test(d.commit))
75
+ out.push(`commit "${d.commit}" is not a commit sha`);
76
+ return out;
77
+ }
78
+ /**
79
+ * The forge repository a `repo` member's URL names: `https://<host>/<path>`,
80
+ * `ssh://[user@]<host>/<path>` or `<user>@<host>:<path>`, with or without
81
+ * `.git`. A local path names no forge and is refused, as is a host that
82
+ * does not say which forge it is unless `forge` does, and a GitLab one.
83
+ */
84
+ export function trainMemberTarget(url, opts = {}) {
85
+ let host;
86
+ let path;
87
+ const scp = /^[^@/\s]+@([^:/\s]+):(?!\/\/)(.+)$/.exec(url);
88
+ if (scp) {
89
+ host = scp[1];
90
+ path = scp[2];
91
+ }
92
+ else {
93
+ let u = null;
94
+ try {
95
+ u = new URL(url);
96
+ }
97
+ catch {
98
+ u = null;
99
+ }
100
+ if (!u || !["https:", "http:", "ssh:"].includes(u.protocol) || u.hostname === "")
101
+ throw new ControlConfigError(`${url} names no forge repository, so the train cannot dispatch into it`);
102
+ host = u.protocol === "ssh:" ? u.hostname : u.host;
103
+ path = u.pathname.replace(/^\/+/, "");
104
+ }
105
+ path = path.replace(/\.git$/, "").replace(/\/+$/, "");
106
+ if (path.split("/").length < 2 || path.split("/").some((p) => p === ""))
107
+ throw new ControlConfigError(`${url} names no <owner>/<name> repository`);
108
+ const forge = opts.forge ?? forgeFromHost(host);
109
+ if (!forge)
110
+ throw new ControlConfigError(`${url}: its host does not say which forge it is`);
111
+ // The member's train job is written for GitHub and Forgejo; a GitLab member would never answer.
112
+ if (forge === "gitlab")
113
+ throw new ControlConfigError(`${url} is on GitLab, and a train dispatches into GitHub and Forgejo repositories only`);
114
+ const ref = opts.ref ?? CONTROL_REF_DEFAULT;
115
+ if (!CONTROL_REF.test(ref))
116
+ throw new ControlConfigError(`"${ref}" is not a branch name`);
117
+ return { repo: url.replace(/\/\/[^@/]*@/, "//"), host, path, forge, apiBase: (opts.apiBase ?? forgeApiBase(forge, host)).replace(/\/+$/, ""), ref };
118
+ }
119
+ /**
120
+ * The request that starts a member's train job: GitHub's `repository_dispatch`
121
+ * of `<product>-train`, or a Forgejo workflow dispatch of `<product>-train.yml`.
122
+ */
123
+ export function trainDispatchRequest(target, d, wordsIn = {}) {
124
+ const problems = trainDispatchProblems(d);
125
+ if (problems.length > 0)
126
+ throw new ControlConfigError(`the train's dispatch to ${target.repo}: ${problems.join(", ")}`, problems);
127
+ const fields = { member: d.member, env: d.env, train: d.train, run: d.run, release: d.releaseDigest, commit: d.commit };
128
+ if (target.forge === "github") {
129
+ return {
130
+ url: `${target.apiBase}/repos/${target.path}/dispatches`,
131
+ method: "POST",
132
+ headers: { Accept: "application/vnd.github+json", "Content-Type": "application/json" },
133
+ body: { json: { event_type: trainDispatchEvent(wordsIn), client_payload: fields } },
134
+ token: { in: "header", name: "Authorization", scheme: "Bearer" },
135
+ };
136
+ }
137
+ return {
138
+ url: `${target.apiBase}/repos/${target.path}/actions/workflows/${trainPipelineFileName(wordsIn)}/dispatches`,
139
+ method: "POST",
140
+ headers: { Accept: "application/json", "Content-Type": "application/json" },
141
+ body: { json: { ref: target.ref, inputs: fields } },
142
+ token: { in: "header", name: "Authorization", scheme: "token" },
143
+ };
144
+ }
145
+ /**
146
+ * Sends one dispatch into a member repository. A missing token or a status
147
+ * other than 2xx throws {@link ControlDispatchError}, the token cut out of
148
+ * the forge's answer.
149
+ */
150
+ export async function dispatchTrainMember(target, d, opts = {}) {
151
+ const tokenVar = trainTokenEnv(d.member);
152
+ const token = opts.token ?? (opts.env ?? process.env)[tokenVar];
153
+ if (!token)
154
+ throw new ControlDispatchError(`${tokenVar} is not set, so ${target.repo} was not dispatched; give the control repo a secret of that name holding a token that may dispatch there and do nothing else`, undefined);
155
+ const req = trainDispatchRequest(target, d, opts.words);
156
+ const headers = { ...req.headers, [req.token.name]: `${req.token.scheme} ${token}` };
157
+ const fetchImpl = opts.fetch ?? globalThis.fetch;
158
+ let res;
159
+ try {
160
+ res = await fetchImpl(req.url, { method: req.method, headers, body: JSON.stringify(req.body.json) });
161
+ }
162
+ catch (e) {
163
+ throw new ControlDispatchError(`the dispatch to ${target.repo} could not be sent: ${String(e.message ?? e).split(token).join("***")}`, undefined);
164
+ }
165
+ if (res.status < 200 || res.status > 299) {
166
+ const answer = (await res.text().catch(() => "")).slice(0, 400).split(token).join("***");
167
+ throw new ControlDispatchError(`${target.repo} refused the dispatch (HTTP ${res.status}): ${answer}`, res.status);
168
+ }
169
+ return { status: res.status };
170
+ }
171
+ /** The run step's script: check the dispatch, run the release, and hand the outcome to the answer step. */
172
+ function trainRunScript(command, install, label) {
173
+ return [
174
+ "set -u",
175
+ `env="\${${TRAIN_ENV_VAR}:-}"`,
176
+ `release="\${${TRAIN_RELEASE_VAR}:-}"`,
177
+ `commit="\${${TRAIN_COMMIT_VAR}:-}"`,
178
+ `train="\${${TRAIN_ID_VAR}:-}"`,
179
+ `run="\${${TRAIN_RUN_VAR}:-}"`,
180
+ // The dispatch is data: only names, ids, a digest and a sha go any further.
181
+ ...shellPatterns({ name: CONTROL_NAME, release: CONTROL_RELEASE_DIGEST, sha: SHA, train: CONTROL_TRAIN_ID, run: CONTROL_RUN_ID }),
182
+ `[[ $env =~ $name_re && $release =~ $release_re && $commit =~ $sha_re && $train =~ $train_re && $run =~ $run_re ]] || { echo "${label}: the train's dispatch is not usable (env=\\"$env\\", release=\\"$release\\", commit=\\"$commit\\")" >&2; exit 2; }`,
183
+ // The checkout is the release's commit; chant run --release refuses any other.
184
+ `[ "$(git rev-parse HEAD)" = "$commit" ] || { echo "${label}: the checkout is not at the release's commit \${commit:0:12}" >&2; exit 2; }`,
185
+ install,
186
+ "code=0",
187
+ `${command} run --components all --env "$env" --release "$release" || code=$?`,
188
+ `case "$code" in 0) outcome=applied ;; ${WAITING_EXIT}) outcome=waiting ;; *) outcome=failed ;; esac`,
189
+ `echo "${label}: the release \${release:0:24} ran in $env: $outcome (exit $code)"`,
190
+ // The answer step reads these; it runs whatever this step did.
191
+ ...[`${CONTROL_OUTCOME_VAR}=$outcome`, `${CONTROL_SHA_VAR}=$commit`, `${CONTROL_TRAIN_VAR}=$train`, `${CONTROL_RUN_VAR}=$run`, `${CONTROL_ENV_VAR}=$env`, `${CONTROL_RELEASE_VAR}=$release`].map((kv) => `echo "${kv}" >> "$GITHUB_ENV"`),
192
+ `exit "$code"`,
193
+ ].join("\n");
194
+ }
195
+ /**
196
+ * The job a member repository adds to take a train's dispatch (#5119). It
197
+ * checks out the release's commit, runs `chant run --components all --env
198
+ * <env> --release <digest>` under the repository's own identity, which
199
+ * records each deploy with the release's digest, and answers the control
200
+ * repo with `<product>-applied`: the outcome (`applied`, `waiting` at the
201
+ * member's own gate, or `failed`) and the train's fields. A product adds
202
+ * its own cloud login before the run step; the answer step holds the
203
+ * control repo's dispatch token and nothing else.
204
+ */
205
+ export function trainMemberJobSpec(forge, control, opts = {}) {
206
+ const words = resolveProductWords(opts.words ?? {});
207
+ const label = words.product;
208
+ if (opts.dir !== undefined && !/^[A-Za-z0-9._/-]+$/.test(opts.dir))
209
+ throw new ControlConfigError(`"${opts.dir}" is not a directory a job can start in`);
210
+ const field = (key) => `\${{ github.event.client_payload.${key} || inputs.${key} }}`;
211
+ return {
212
+ forge,
213
+ path: trainPipelinePath(forge, words),
214
+ header: [
215
+ `# The control repo ${control.repo} dispatches here to promote one release of a`,
216
+ "# release train: the job runs that release at its commit and tells the control",
217
+ "# repo how the run ended.",
218
+ ],
219
+ event: trainDispatchEvent(words),
220
+ inputs: {
221
+ env: { description: "The environment to run the release in", required: true, type: "string" },
222
+ release: { description: "The release digest", required: true, type: "string" },
223
+ commit: { description: "The release's commit", required: true, type: "string" },
224
+ train: { description: "The release train", required: true, type: "string" },
225
+ run: { description: "The control repo's run of the train's promote", required: true, type: "string" },
226
+ },
227
+ run: {
228
+ name: "Run the release the train names",
229
+ env: { [TRAIN_ENV_VAR]: field("env"), [TRAIN_RELEASE_VAR]: field("release"), [TRAIN_COMMIT_VAR]: field("commit"), [TRAIN_ID_VAR]: field("train"), [TRAIN_RUN_VAR]: field("run") },
230
+ script: trainRunScript(opts.command ?? CONTROL_CHANT_COMMAND, opts.install ?? "npm ci", label),
231
+ workingDirectory: opts.dir && opts.dir !== "." ? opts.dir : null,
232
+ },
233
+ answer: {
234
+ name: `Tell the control repo ${control.repo} how the run ended`,
235
+ env: { [CONTROL_TOKEN_ENV]: `\${{ secrets.${control.tokenSecret} }}` },
236
+ script: controlDispatchScript(control, { words, outcome: true, train: true }),
237
+ },
238
+ commit: field("commit"),
239
+ group: `${label}-train`,
240
+ notes: [
241
+ `give the control repo a ${trainTokenEnv(control.member)} secret: a token that may ${forge === "github" ? "send a repository_dispatch to" : "dispatch workflows in"} this repo and do nothing else`,
242
+ "the run step deploys under this repo's own identity: add the cloud login it needs before it",
243
+ `the answer goes back with ${control.tokenSecret}, the dispatch token the control repo's other dispatches use`,
244
+ ],
245
+ };
246
+ }
247
+ /**
248
+ * The control repo's job that starts a train's promote (#5119): `chant
249
+ * workspace train promote <env> [<train>]`, which dispatches the first
250
+ * member repository, then a push of what it recorded on `chant/lifecycle`.
251
+ * Each later member is dispatched by the control repo's dependents job
252
+ * when the one before it answers. The job holds one dispatch token per
253
+ * member repository and nothing else: no cloud login, no `id-token`.
254
+ */
255
+ export function trainControlJobSpec(forge, members, opts = {}) {
256
+ const words = resolveProductWords(opts.words ?? {});
257
+ const label = words.product;
258
+ const chant = opts.command ?? CONTROL_CHANT_COMMAND;
259
+ if (members.length === 0)
260
+ throw new ControlConfigError("a train's control job needs the repo members it dispatches into");
261
+ const script = [
262
+ "set -eu",
263
+ `env="\${${TRAIN_ENV_VAR}:-}"`,
264
+ `train="\${${TRAIN_ID_VAR}:-}"`,
265
+ ...shellPatterns({ name: CONTROL_NAME, train: CONTROL_TRAIN_ID, release: CONTROL_RELEASE_DIGEST }),
266
+ `[[ $env =~ $name_re ]] || { echo "${label}: no usable environment (\\"$env\\")" >&2; exit 2; }`,
267
+ `[ -z "$train" ] || [[ $train =~ $train_re || $train =~ $release_re ]] || { echo "${label}: no usable train (\\"$train\\")" >&2; exit 2; }`,
268
+ "npm ci",
269
+ `code=0; ${chant} workspace train promote "$env" \${train:+"$train"} --json || code=$?`,
270
+ `git push -q origin refs/heads/chant/lifecycle:refs/heads/chant/lifecycle || echo "${label}: the train's records were not pushed to chant/lifecycle" >&2`,
271
+ `exit "$code"`,
272
+ ].join("\n");
273
+ return {
274
+ forge,
275
+ path: trainPipelinePath(forge, words),
276
+ header: [
277
+ "# Promote a release train: dispatch its first member repository. Each later",
278
+ `# member is dispatched when the one before it answers (${label}-dependents.yml).`,
279
+ "# This repo holds a dispatch token per member repository and no cloud credentials.",
280
+ ],
281
+ inputs: {
282
+ env: { description: "The environment to promote the train to", required: true, type: "string" },
283
+ train: { description: "The train, by id or digest; the newest for the environment when empty", required: false, type: "string" },
284
+ },
285
+ env: { [TRAIN_ENV_VAR]: "${{ inputs.env }}", [TRAIN_ID_VAR]: "${{ inputs.train }}", [TRAIN_PRODUCT_VAR]: label, ...trainTokenEnvOf(members) },
286
+ script,
287
+ group: `${label}-train`,
288
+ notes: [
289
+ ...members.map((m) => `add a ${trainTokenEnv(m)} secret holding a token that may dispatch into ${m}'s repository and do nothing else`),
290
+ "the job pushes chant/lifecycle with its own token (contents: write)",
291
+ `the dependents workflow (${label}-dependents.yml) takes the members' answers and needs the same secrets`,
292
+ ],
293
+ };
294
+ }
@@ -43,7 +43,7 @@
43
43
  * when nobody declared the property.
44
44
  */
45
45
  import { isHeldElsewhere, isNormalizedHeldElsewhere, normalizeHeldElsewhere } from "./held-elsewhere.js";
46
- import { isSensitiveKey } from "./sensitive-key.js";
46
+ import { isReferenceField, isSensitiveKey } from "./sensitive-key.js";
47
47
  /** True when `value` is the versioned {@link DeepObservationResult} envelope. */
48
48
  export function isDeepObservationResult(value) {
49
49
  return (typeof value === "object" &&
@@ -232,7 +232,7 @@ export function normalizeDeepProperties(tree, options) {
232
232
  // very identity that makes it a marker rather than authored data.
233
233
  if (isHeldElsewhere(value))
234
234
  return normalizeHeldElsewhere(value);
235
- if (isSensitiveKey(key))
235
+ if (isSensitiveKey(key) && !isReferenceField(key, value))
236
236
  return MASKED;
237
237
  // The lexicon's structural mask — same collapse, path-shaped rather than
238
238
  // key-named (a k8s Secret's `data.*` no matter what the key is called).
@@ -1 +1 @@
1
- {"version":3,"file":"floor-table.data.d.ts","sourceRoot":"","sources":["../src/floor-table.data.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EA2QzC,CAAC"}
1
+ {"version":3,"file":"floor-table.data.d.ts","sourceRoot":"","sources":["../src/floor-table.data.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAiRzC,CAAC"}
@@ -82,6 +82,7 @@ export const FLOOR_ROWS = [
82
82
  { name: "NORMALIZED_INPUTS_FLOOR", version: "0.124.68", gates: "The first chant that reads `inputs.normalize` and writes `normalizedInputs` on a skip record (#4718).", issue: "#4718", file: "components/unchanged-inputs.ts", modules: ["@intentius/chant/components/unchanged-inputs"] },
83
83
  { name: "CONTROL_CONSUMERS_FLOOR", version: "0.124.55", gates: "The first chant with the consumers join, joinControlConsumers and readControlConsumers on `@intentius/chant/ci-control` (#4600).", issue: "#4600", file: "control/consumers.ts", modules: ["@intentius/chant/ci-control", "@intentius/chant/control/consumers"] },
84
84
  { name: "CONTROL_DEPENDENTS_FLOOR", version: "0.124.47", gates: "The first chant with `chant workspace run --dependents-of`, which the control repo's package.json pins.", file: "control/dispatch.ts", modules: ["@intentius/chant/ci-control", "@intentius/chant/control/dispatch"] },
85
+ { name: "CONTROL_TRAIN_FLOOR", version: NEXT_RELEASE, gates: "The first chant with release trains across repositories (#5119).", issue: "#5119", file: "control/train.ts", modules: ["@intentius/chant/ci-control", "@intentius/chant/control/train"] },
85
86
  { name: "E2E_HARNESS_FLOOR", version: "0.124.56", gates: "The first chant with the e2e harness.", file: "e2e-harness/index.ts", modules: ["@intentius/chant/e2e-harness", "@intentius/chant/e2e-harness/index"] },
86
87
  { name: "E2E_HARNESS_PULL_STEPS_FLOOR", version: "0.124.58", gates: "The first chant whose harness follows a pull request a product opened (chant#4650): the await-pull and comment steps, the pull and gated outcomes, and the forge reads under them.", issue: "#4650", file: "e2e-harness/index.ts", modules: ["@intentius/chant/e2e-harness", "@intentius/chant/e2e-harness/index"] },
87
88
  { name: "ENGINE_FACTS_FLOOR", version: "0.124.54", gates: "The first chant whose graph carries `nodes[].facts` and `edges[].grain` (#4527, #4529, #4528): a live read through an engine (the terraform lexicon's read of `choudoufu live-graph -json -from-plan`, which writes `ResourceMetadata.facts` and the observation's `edges`), and a plunge member's checked-in `engine-graph.json` in the pulumi lexicon's member read.", issue: "#4527", file: "engine-facts.ts", modules: ["@intentius/chant", "@intentius/chant/engine-facts", "@intentius/chant/index"] },
@@ -241,9 +242,13 @@ export const FLOOR_ROWS = [
241
242
  { name: "OP_WAVES_REMAINDER_PARITY_FLOOR", version: "0.124.94", gates: "The first chant whose `approvals.remainder` resumes the waves terragucci's own records resume (#5056): the terraform step gives a live choudoufu root's plan (`live-plan-set`) its `resourceDigests`, so its applied line names the changes, and the cover leaves out the cost member `(monthly cost)`, whose digest follows from the plans, on both sides.", issue: "#5056", file: "release-floors.ts", modules: ["@intentius/chant/ci-product", "@intentius/chant/op/op-waves-remainder", "@intentius/chant/release-floors"] },
242
243
  { name: "OP_WAVES_CONTROL_BEFORE_MERGE_FLOOR", version: "0.124.95", gates: "The first chant whose Op waves generators, in a product's workflow (`runIf`) with `beforeMerge` and a spec `control`, run the control job on the default branch's push, outside the product's `runIf` and after its `firstWaveNeeds` jobs, and tell the control repo the waves applied at the pushed commit without adding up outcomes, on GitHub, Forgejo and GitLab (#5060).", issue: "#5060", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
243
244
  { name: "WAVES_BEFORE_MERGE_LOCKS_FLOOR", version: "0.124.95", gates: "The first chant whose waves before merge lock and unlock on a comment by the product plan's reach line (#5061): with `wavesBeforeMerge` and `productPlan.reach`, and no `locks: \"plan\"`, the comment job (GitHub, Forgejo) and the note poll (GitLab, `chantNoteRuns`) answer `/<product> lock` on an open pull request by taking the locks of what the reach line prints at stage `apply` in `_locks/<reach.gate>.json` without applying (`decideLocksBeforeMerge`), refused with the holder named, and `/<product> unlock` by releasing the pull request's locks; and the product plan takes `reach` without `locks: \"plan\"` under `wavesBeforeMerge`, writing no reach lock job.", issue: "#5061", file: "release-floors.ts", modules: ["@intentius/chant/ci-product", "@intentius/chant/release-floors"] },
244
- { name: "KIND_DRIFT_READER_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose kinds file takes `drift: { reader, config }` beside `graph` and whose `chant workspace drift --member` reads a member of such a kind with that module, `(input: { dir, config, member, observedAt, read?, resource?, stack? }) => DriftReaderOutput` from `@intentius/chant/workspace/drift-reader`, checked against `drift-reader.schema.json` (#5068).", issue: "#5068", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
245
+ { name: "KIND_DRIFT_READER_FLOOR", version: "0.124.96", gates: "The first chant whose kinds file takes `drift: { reader, config }` beside `graph` and whose `chant workspace drift --member` reads a member of such a kind with that module, `(input: { dir, config, member, observedAt, read?, resource?, stack? }) => DriftReaderOutput` from `@intentius/chant/workspace/drift-reader`, checked against `drift-reader.schema.json` (#5068).", issue: "#5068", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
246
+ { name: "WORKSPACE_GRAPH_CATALOG_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `chant workspace graph` runs each lexicon's reference catalog over the composed declared graph, across members, on full attributes at every `--detail` (#5097): derived edges in `edges` with `origin: \"derived\"`, `rule` and `relation`, references to no node in `dangling` with their `rule` and `targetKind`, references to several nodes in `ambiguous` with every candidate, and `catalog` naming the lexicons and members read, each rule named, and per node the arguments not read because not literal; a catalog path takes a quoted key, `metadata.annotations[\"iam.gke.io/gcp-service-account\"]`; and a catalog takes `scopes` and `declaredNode`.", issue: "#5097", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
247
+ { name: "WORKSPACE_GRAPH_CLUSTER_JOIN_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose reference catalogs join an Argo CD cluster Secret to the cluster resource (#5101): an Application's `spec.destination.name` and `spec.destination.server` to the Secret whose `name` and `server` match, and the Secret's `name` (base64 `data` decoded) to a `google_container_cluster`, `aws_eks_cluster` or `azurerm_kubernetes_cluster` of that literal name, with a reference no rule of its id matched listed once in `dangling`; a member of kind `argo-app` or `manifests` reads a cluster Secret cut down to its `name` and `server`; and a workspace member entry takes `runsOn`, `<member>/<address>`, with `chant workspace graph --discover --runs-on <member>=<member>/<address>`, which draws a declared edge from each of the member's cluster Secrets to that node.", issue: "#5101", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
248
+ { name: "WORKSPACE_GRAPH_APPLICATION_SET_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `chant workspace graph` expands an Argo CD ApplicationSet's `list` and `clusters` generators (#5102): one node per generated Application, with `generatedBy` naming the ApplicationSet, the rule, the generator, the parameters and the cluster Secret it was made for, a derived edge from the ApplicationSet to it under `k8s:K8s::Argo::ApplicationSet:spec.generators` and from it to the cluster Secret a clusters generator selected under `k8s:K8s::Argo::ApplicationSet:generators[].clusters`, and `expansion` on the ApplicationSet with the count and what was not expanded; and whose catalogs read an Application's `spec.source.path`, `spec.sources[].path` and `helm.valueFiles`, listing a path the workspace's own repository does not have in `dangling`, with `through` and `cluster` on a generated one.", issue: "#5102", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
245
249
  { name: "GITLAB_WAVE_EVIDENCE_RETRY_FLOOR", version: "0.124.89", gates: "The first chant whose `chant run resume` (`resumeGateRun`) on GitLab retries a wave job's `<wave job>-evidence` with the wave job when the evidence job already ran, and whose `ci evidence sign --from-job` waits for a job it reads to finish, so a resumed wave's evidence job signs from the new try (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs", "@intentius/chant/release-floors"] },
246
250
  { name: "TERRAFORM_COMMAND_TRACE_FLOOR", version: "0.124.91", gates: "The first chant whose terraform lexicon's engine runs carry what a product's own command tracing read: `runBinary` and the engine runner's `exec` and `execSync` answer stderr apart (`Ran.stderr`) and a spawn failure's message (`Ran.error`), a hook's `after` gets a binary that could not be started as a null code with `error`, `commandTrace` ends that span with the message, and `composeCommandHooks` runs a product's own hook and `commandTrace` as one `onCommand` (#5007).", issue: "#5007", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
251
+ { name: "COMMENT_ALLOW_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose product pipeline limits comment commands to logins and teams on GitHub and Forgejo (INTENTIUS/terragucci#1461): `commentAllow: { allow, tokenSecret? }` in `productPipelineJobs`, where `allow` maps `plan`, `apply`, `lock`, `unlock`, `agent` and `default` to logins and `team:<org>/<team>` entries.", issue: "#1461", file: "release-floors.ts", modules: ["@intentius/chant/ci-product", "@intentius/chant/release-floors"] },
247
252
  { name: "RUN_EVENT_FLOOR", version: "0.124.28", gates: "The first chant that writes contract version 1 of the run-event stream.", file: "run-event.ts", modules: ["@intentius/chant", "@intentius/chant/index", "@intentius/chant/run-event"] },
248
253
  { name: "RUN_EVENT_FAILURE_FLOOR", version: "0.124.30", gates: "The first chant that writes `failure` on `run-settle` (#4094).", issue: "#4094", file: "run-event.ts", modules: ["@intentius/chant", "@intentius/chant/index", "@intentius/chant/run-event"] },
249
254
  { name: "RUN_EVENT_COMPONENT_SKIP_FLOOR", version: "0.124.29", gates: "The first chant that writes `blocked`, `already-applied` and `blockedBy` on `component-settle` (#4007).", issue: "#4007", file: "run-event.ts", modules: ["@intentius/chant", "@intentius/chant/index", "@intentius/chant/run-event"] },
@@ -267,6 +272,7 @@ export const FLOOR_ROWS = [
267
272
  { name: "READ_CONTRACT_FLOOR", version: "0.81.0", gates: "The first chant release that writes contract version 1.", file: "workspace/reason-codes.ts", modules: ["@intentius/chant/workspace/reason-codes"] },
268
273
  { name: "RELEASE_CANDIDATES_CLOSES_FLOOR", version: "0.124.63", gates: "The first chant whose candidates carry `changes[].closes` and `groups[].issue` (#4649).", issue: "#4649", file: "workspace/release-candidates.ts", modules: ["@intentius/chant/workspace/release-candidates"] },
269
274
  { name: "RELEASE_CANDIDATES_LANE_FLOOR", version: "0.124.64", gates: "The first chant whose candidates document carries `lane` and reads a lane's tags (#4692).", issue: "#4692", file: "workspace/release-candidates.ts", modules: ["@intentius/chant/workspace/release-candidates"] },
275
+ { name: "TRAIN_PROMOTE_FLOOR", version: NEXT_RELEASE, gates: "The first chant that writes ReleaseTrainRecord.trainDigest and has `chant workspace train promote` (#4037).", issue: "#4037", file: "workspace/release-train.ts", modules: ["@intentius/chant/workspace/release-train"] },
270
276
  { name: "MODULE_CONSUMERS_FLOOR", version: "0.124.55", gates: "The first chant whose terraform lexicon has `moduleConsumers`, the scan of every registry module call a root makes, with `readRegistryCatalog` and `deprecatedPins` beside it on `./registry` (#4599).", issue: "#4599", file: "lexicons/terraform/src/chant-floors.ts", modules: ["@intentius/chant-lexicon-terraform/chant-floors", "@intentius/chant-lexicon-terraform/registry", "@intentius/chant-lexicon-terraform/registry/index"] },
271
277
  { name: "USED_SOURCES_FLOOR", version: "0.124.55", gates: "The first chant whose terraform lexicon has `usedSources`, every module source and provider address a root uses, with `moduleSourceForms`, `providerAddressForms` and `lockedProviders` on `./registry` (#3924).", issue: "#3924", file: "lexicons/terraform/src/chant-floors.ts", modules: ["@intentius/chant-lexicon-terraform/chant-floors", "@intentius/chant-lexicon-terraform/registry", "@intentius/chant-lexicon-terraform/registry/index"] },
272
278
  { name: "MODULE_CATALOG_FLOOR", version: "0.124.55", gates: "The first chant whose terraform lexicon has `./module-catalog`, the known-module catalog TF047 reads (#4560).", issue: "#4560", file: "lexicons/terraform/src/chant-floors.ts", modules: ["@intentius/chant-lexicon-terraform/chant-floors", "@intentius/chant-lexicon-terraform/module-catalog", "@intentius/chant-lexicon-terraform/module-catalog/index"] },
@@ -35,6 +35,15 @@ export declare const DETAIL: {
35
35
  };
36
36
  /** Apply a detail tier to the base (declarable-level) IR. */
37
37
  export declare function applyDetail(ir: GraphIR, level: DetailLevel): GraphIR;
38
+ /** A node's attrs as a tier prints them: all of them at T3, the resource view at T2, overlay paint below. */
39
+ export declare function nodeAttrsAt(attrs: Record<string, unknown>, level: DetailLevel): Record<string, unknown>;
40
+ /**
41
+ * The node each node of the base IR is drawn as at a detail tier (#5097): at
42
+ * T0 its lexicon's stack node, at T1 the composite instance it belongs to,
43
+ * and itself at T2 and T3. A reader that derives edges from the base IR maps
44
+ * them through this to put them on the tier's nodes.
45
+ */
46
+ export declare function detailIdMap(ir: GraphIR, level: DetailLevel): Map<string, string>;
38
47
  /**
39
48
  * chant #1489 — the message to print when `--detail 3` changed nothing.
40
49
  *
@@ -1 +1 @@
1
- {"version":3,"file":"graph-detail.d.ts","sourceRoot":"","sources":["../src/graph-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC,eAAO,MAAM,MAAM;aACjB,MAAM,EAAE,CAAC;aACT,UAAU,EAAE,CAAC;aACb,WAAW,EAAE,CAAC;aACd,UAAU,EAAE,CAAC;CACL,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAYpE;AAgQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAYtF"}
1
+ {"version":3,"file":"graph-detail.d.ts","sourceRoot":"","sources":["../src/graph-detail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,YAAY,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC,eAAO,MAAM,MAAM;aACjB,MAAM,EAAE,CAAC;aACT,UAAU,EAAE,CAAC;aACb,WAAW,EAAE,CAAC;aACd,UAAU,EAAE,CAAC;CACL,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAYpE;AAqED,6GAA6G;AAC7G,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGvG;AA0ED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAIhF;AA4HD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAYtF"}