@intentius/chant-lexicon-terraform 0.124.87 → 0.124.88

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/dist/action-ops.d.ts.map +1 -1
  2. package/dist/action-ops.js +3 -1
  3. package/dist/chant-floors.d.ts +30 -0
  4. package/dist/chant-floors.d.ts.map +1 -0
  5. package/dist/chant-floors.js +29 -0
  6. package/dist/components/capability-plugin.d.ts +15 -1
  7. package/dist/components/capability-plugin.d.ts.map +1 -1
  8. package/dist/components/capability-plugin.js +13 -5
  9. package/dist/components/compose-group.d.ts +5 -1
  10. package/dist/components/compose-group.d.ts.map +1 -1
  11. package/dist/components/compose-group.js +7 -4
  12. package/dist/engine-timings.d.ts +249 -0
  13. package/dist/engine-timings.d.ts.map +1 -0
  14. package/dist/engine-timings.js +569 -0
  15. package/dist/integrity.json +2 -2
  16. package/dist/live-roots.d.ts +93 -0
  17. package/dist/live-roots.d.ts.map +1 -0
  18. package/dist/live-roots.js +206 -0
  19. package/dist/manifest.json +1 -1
  20. package/dist/migration-history.d.ts +105 -0
  21. package/dist/migration-history.d.ts.map +1 -0
  22. package/dist/migration-history.js +159 -0
  23. package/dist/module-catalog/index.d.ts +1 -0
  24. package/dist/module-catalog/index.d.ts.map +1 -1
  25. package/dist/module-catalog/index.js +3 -1
  26. package/dist/op/activities/live-detect.d.ts +15 -0
  27. package/dist/op/activities/live-detect.d.ts.map +1 -1
  28. package/dist/op/activities/live-detect.js +94 -0
  29. package/dist/op/activities/terraform.d.ts +1 -65
  30. package/dist/op/activities/terraform.d.ts.map +1 -1
  31. package/dist/op/activities/terraform.js +4 -54
  32. package/dist/op/command-hook.d.ts +88 -0
  33. package/dist/op/command-hook.d.ts.map +1 -0
  34. package/dist/op/command-hook.js +115 -0
  35. package/dist/registry/index.d.ts +1 -0
  36. package/dist/registry/index.d.ts.map +1 -1
  37. package/dist/registry/index.js +1 -0
  38. package/dist/state/exec.d.ts +23 -0
  39. package/dist/state/exec.d.ts.map +1 -1
  40. package/dist/state/exec.js +38 -0
  41. package/dist/state-ops.d.ts.map +1 -1
  42. package/dist/state-ops.js +3 -1
  43. package/dist/terragrunt/index.d.ts +3 -1
  44. package/dist/terragrunt/index.d.ts.map +1 -1
  45. package/dist/terragrunt/index.js +3 -1
  46. package/dist/terragrunt/place.d.ts +27 -0
  47. package/dist/terragrunt/place.d.ts.map +1 -0
  48. package/dist/terragrunt/place.js +52 -0
  49. package/package.json +2 -2
  50. package/src/action-ops.ts +3 -1
  51. package/src/chant-floors.ts +32 -0
  52. package/src/components/capability-plugin.ts +27 -6
  53. package/src/components/compose-group.test.ts +29 -0
  54. package/src/components/compose-group.ts +12 -5
  55. package/src/components/terraform-apply-command-hook.test.ts +43 -0
  56. package/src/engine-timings.test.ts +203 -0
  57. package/src/engine-timings.ts +718 -0
  58. package/src/live-roots.test.ts +80 -0
  59. package/src/live-roots.ts +244 -0
  60. package/src/migration-history.test.ts +83 -0
  61. package/src/migration-history.ts +199 -0
  62. package/src/module-catalog/index.ts +4 -1
  63. package/src/op/activities/live-detect.ts +87 -0
  64. package/src/op/activities/terraform.ts +12 -111
  65. package/src/op/command-hook.ts +182 -0
  66. package/src/registry/index.ts +1 -0
  67. package/src/state/engine-env.test.ts +18 -0
  68. package/src/state/exec.ts +38 -0
  69. package/src/state-ops.ts +3 -1
  70. package/src/terragrunt/index.ts +3 -1
  71. package/src/terragrunt/place.test.ts +42 -0
  72. package/src/terragrunt/place.ts +75 -0
@@ -0,0 +1,80 @@
1
+ /**
2
+ * chant#4910: live roots and estates read from a root's files, the setup
3
+ * `choudoufu live-check -json` resolves (through a fake exec), and the bucket
4
+ * check's target for a resolved store. Nothing runs choudoufu or reaches a
5
+ * bucket.
6
+ */
7
+ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
8
+ import { tmpdir } from "node:os";
9
+ import { join } from "node:path";
10
+ import { afterEach, describe, expect, test } from "vitest";
11
+ import { bucketLines, bucketTarget, checkStoreBucket, estateOf, forgetLiveSetups, liveRoots, parseLiveSetup, readLiveSetup, resolvedEstate, setupLine } from "./live-roots";
12
+ import type { BinaryExec } from "./state/exec";
13
+
14
+ afterEach(() => forgetLiveSetups());
15
+
16
+ function repo(files: Record<string, string>): string {
17
+ const dir = mkdtempSync(join(tmpdir(), "chant-live-roots-"));
18
+ for (const [path, text] of Object.entries(files)) {
19
+ mkdirSync(join(dir, path, ".."), { recursive: true });
20
+ writeFileSync(join(dir, path), text);
21
+ }
22
+ return dir;
23
+ }
24
+
25
+ describe("liveRoots and estateOf (chant#4910)", () => {
26
+ const dir = repo({
27
+ "envs/plain/main.tf": 'terraform {\n backend "s3" {}\n}\n',
28
+ "envs/block/main.tf": 'terraform {\n live {\n estate = "prod"\n }\n}\n\ndata "terraform_estate_outputs" "net" {\n estate = "network"\n}\n',
29
+ "envs/unnamed/main.tf": "terraform {\n live {}\n}\n",
30
+ "envs/sidecar/main.tf": "",
31
+ "envs/sidecar/estate.chdf.hcl": 'estate = "side"\n',
32
+ "envs/json/main.tf.json": JSON.stringify({ terraform: [{ live: [{ estate: "js" }] }], data: { terraform_estate_outputs: { up: { estate: "upstream" } } } }),
33
+ "envs/commented/main.tf": '# terraform {\n# live {}\n# }\ndata "terraform_estate_outputs" "x" {\n # estate = "ignored"\n estate = "kept"\n}\n',
34
+ });
35
+
36
+ test("a live block, named or not, an estate sidecar, and a JSON live block make a live root; a commented one does not", () => {
37
+ expect(liveRoots(dir, ["envs/plain", "envs/block", "envs/unnamed", "envs/sidecar", "envs/json", "envs/commented"])).toEqual(["envs/block", "envs/unnamed", "envs/sidecar", "envs/json"]);
38
+ });
39
+
40
+ test("a root's estate and the estates whose outputs it reads", () => {
41
+ expect(estateOf(join(dir, "envs/block"))).toEqual({ estate: "prod", reads: ["network"] });
42
+ expect(estateOf(join(dir, "envs/sidecar"))).toEqual({ estate: "side", reads: [] });
43
+ expect(estateOf(join(dir, "envs/json"))).toEqual({ estate: "js", reads: ["upstream"] });
44
+ expect(estateOf(join(dir, "envs/commented"))).toEqual({ reads: ["kept"] });
45
+ expect(estateOf(join(dir, "envs/unnamed"))).toEqual({ reads: [] });
46
+ });
47
+ });
48
+
49
+ const LIVE_CHECK = JSON.stringify({ estate: "prod", estate_source: "backend_key", record_store: { kind: "s3", bucket: "acme-records", prefix: "tofu-records/prod/", source: "backend", declared_at: "main.tf:2" } });
50
+
51
+ describe("the setup choudoufu resolves (chant#4910)", () => {
52
+ test("live-check's estate and store are read once per directory, and win over the files' estate", async () => {
53
+ const dir = repo({ "r/main.tf": 'terraform {\n live {\n estate = "written"\n }\n}\n' });
54
+ const calls: string[][] = [];
55
+ const exec: BinaryExec = async (bin, args) => (calls.push([bin, ...args]), { code: 1, stdout: LIVE_CHECK, out: LIVE_CHECK });
56
+ expect(resolvedEstate(join(dir, "r"))).toBe("written");
57
+ const setup = await readLiveSetup(join(dir, "r"), { exec });
58
+ await readLiveSetup(join(dir, "r"), { exec });
59
+ expect(calls).toHaveLength(1);
60
+ expect(calls[0]!.slice(0, 3)).toEqual(["choudoufu", "live-check", "-json"]);
61
+ expect(setup).toEqual({ estate: "prod", estateSource: "backend_key", store: { kind: "s3", bucket: "acme-records", prefix: "tofu-records/prod/", source: "backend", declaredAt: "main.tf:2" } });
62
+ expect(resolvedEstate(join(dir, "r"))).toBe("prod");
63
+ expect(setupLine("r", setup!)).toBe('r: records in s3 bucket "acme-records" under tofu-records/prod/ (derived from its backend block at main.tf:2); estate "prod" (from the backend key)');
64
+ });
65
+
66
+ test("a release that prints no estate_source gives no setup", () => {
67
+ expect(parseLiveSetup(JSON.stringify({ estate: "prod" }))).toBeUndefined();
68
+ expect(parseLiveSetup("not json")).toBeUndefined();
69
+ });
70
+
71
+ test("the bucket check's target, or why there is none", async () => {
72
+ const s3 = parseLiveSetup(LIVE_CHECK)!.store!;
73
+ expect(bucketTarget(s3, { region: "eu-west-1" }, {})).toEqual({ target: { store: "s3", bucket: "acme-records", region: "eu-west-1" } });
74
+ expect(bucketTarget(s3, {}, {})).toEqual({ skip: "no region: set region in the backend block or AWS_REGION" });
75
+ expect(bucketTarget({ ...s3, kind: "azurerm", bucket: "acct/records" }, {}, {})).toMatchObject({ skip: expect.stringContaining("resource group") });
76
+ const checked = await checkStoreBucket(s3, { region: "eu-west-1" }, {}, async (t) => ({ store: t.store, bucket: "acme-records", correct: true, settings: [{ setting: "versioning", verdict: "ok", found: "Enabled" }] }) as never);
77
+ expect(bucketLines("r", checked)).toEqual(["r: bucket acme-records has every setting choudoufu needs (versioning)"]);
78
+ expect(await checkStoreBucket({ ...s3, kind: "local" })).toEqual({ skipped: "the local store has no bucket" });
79
+ });
80
+ });
@@ -0,0 +1,244 @@
1
+ /**
2
+ * Which roots are choudoufu live roots, their estates, and the setup
3
+ * choudoufu resolves for each (chant#4910).
4
+ *
5
+ * - {@link liveRoots}: the roots that keep their resources under choudoufu's
6
+ * live markers, a `live` block in a `terraform` block or an
7
+ * `estate.chdf.hcl` sidecar.
8
+ * - {@link estateOf}: a root's estate as its files name it, and the estates
9
+ * whose recorded outputs it reads through `data "terraform_estate_outputs"`.
10
+ * - {@link readLiveSetup}: the record store and estate choudoufu resolves
11
+ * for a root, from `choudoufu live-check -json` (its `estate`,
12
+ * `estate_source` and `record_store` fields), remembered for the process,
13
+ * and {@link resolvedEstate}, which prefers it to the files' own name. A
14
+ * choudoufu release that prints no `estate_source` gives no setup, and the
15
+ * readers fall back to the files.
16
+ * - {@link setupLine}, {@link storePhrase}, {@link bucketTarget},
17
+ * {@link checkStoreBucket} and {@link bucketLines}: the setup as a log line,
18
+ * and core's bucket check (`@intentius/chant/bucket-check`, chant#4558) on
19
+ * the resolved store.
20
+ *
21
+ * Text reads, as `./op/activities/live-detect.ts` does them: no HCL parser
22
+ * is loaded. Lifted from terragucci's `detect.ts` (`liveRoots`, `estateOf`)
23
+ * and `live-setup.ts`, so terragucci deletes its copies.
24
+ */
25
+ import { join, resolve } from "node:path";
26
+ import { checkBucket, type BucketReport, type BucketTarget } from "@intentius/chant/bucket-check";
27
+ import { declaresLive, detectLiveEstate, estateOutputReads } from "./op/activities/live-detect";
28
+ import { runBinary, type BinaryExec } from "./state/exec";
29
+
30
+ export { declaresLive, detectLiveEstate, estateOutputReads } from "./op/activities/live-detect";
31
+
32
+ /** The roots of `roots` (paths under `repo`) that keep their resources under choudoufu's live markers, in the order given. */
33
+ export function liveRoots(repo: string, roots: readonly string[], binary = "choudoufu"): string[] {
34
+ return roots.filter((r) => declaresLive(join(repo, r), binary));
35
+ }
36
+
37
+ /** A root's estate, as its sidecar or `live` block names it, and the estates whose recorded outputs it reads. */
38
+ export function estateOf(dir: string, binary = "choudoufu"): { estate?: string; reads: string[] } {
39
+ const estate = detectLiveEstate(dir, binary);
40
+ return { ...(estate ? { estate } : {}), reads: estateOutputReads(dir, binary).map((r) => r.estate) };
41
+ }
42
+
43
+ /** Where choudoufu's estate name came from: the live block, the configuration's tags, the backend key, or the root's path. */
44
+ export type EstateSource = "explicit" | "tags" | "backend_key" | "root_path" | "none";
45
+
46
+ /** The record store choudoufu resolved, as `live-check -json` prints it. */
47
+ export interface LiveStore {
48
+ /** `local`, `s3`, `gcs`, `azurerm` or `kubernetes`. */
49
+ kind: string;
50
+ /** The s3 or gcs bucket, `<account>/<container>` for azurerm, the namespace for kubernetes, the directory for local. */
51
+ bucket: string;
52
+ /** Where this estate's records go, with one trailing slash. */
53
+ prefix: string;
54
+ /** `record_store` (written by the author), `backend` (derived from the backend block) or `implied` (the local store). */
55
+ source: string;
56
+ /** `file:line` of the block that decided it. */
57
+ declaredAt?: string;
58
+ /** Why a backend that was there was not used. */
59
+ note?: string;
60
+ }
61
+
62
+ /** What choudoufu resolves for one root. */
63
+ export interface LiveSetup {
64
+ estate?: string;
65
+ estateSource: string;
66
+ store?: LiveStore;
67
+ }
68
+
69
+ const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
70
+
71
+ /** The setup in a `live-check -json` document, or undefined when the document is not JSON or comes from a choudoufu that does not print `estate_source`. */
72
+ export function parseLiveSetup(stdout: string): LiveSetup | undefined {
73
+ let doc: Record<string, unknown>;
74
+ try {
75
+ doc = JSON.parse(stdout) as Record<string, unknown>;
76
+ } catch {
77
+ return undefined;
78
+ }
79
+ if (!doc || typeof doc !== "object" || typeof doc.estate_source !== "string") return undefined;
80
+ const rs = doc.record_store && typeof doc.record_store === "object" ? (doc.record_store as Record<string, unknown>) : undefined;
81
+ const kind = str(rs?.kind);
82
+ const store: LiveStore | undefined =
83
+ rs && kind
84
+ ? {
85
+ kind,
86
+ bucket: str(rs.bucket) ?? "",
87
+ prefix: str(rs.prefix) ?? "",
88
+ source: str(rs.source) ?? "",
89
+ ...(str(rs.declared_at) ? { declaredAt: str(rs.declared_at) } : {}),
90
+ ...(str(rs.note) ? { note: str(rs.note) } : {}),
91
+ }
92
+ : undefined;
93
+ const estate = str(doc.estate);
94
+ return { ...(estate ? { estate } : {}), estateSource: doc.estate_source, ...(store ? { store } : {}) };
95
+ }
96
+
97
+ const known = new Map<string, LiveSetup>();
98
+
99
+ /** Keep what choudoufu resolved for a root's directory, for the readers below. */
100
+ export function rememberLiveSetup(dir: string, setup: LiveSetup): void {
101
+ known.set(resolve(dir), setup);
102
+ }
103
+
104
+ /** What choudoufu resolved for a root's directory in this process, if it was read. */
105
+ export function knownLiveSetup(dir: string): LiveSetup | undefined {
106
+ return known.get(resolve(dir));
107
+ }
108
+
109
+ /** For tests: forget every setup read so far. */
110
+ export function forgetLiveSetups(): void {
111
+ known.clear();
112
+ }
113
+
114
+ /**
115
+ * `choudoufu live-check -json <dir>` for one root, run in the directory, and
116
+ * the setup it prints, remembered for the process. Undefined when the binary
117
+ * prints none (an older release, a root it cannot read, or no binary at
118
+ * all); the caller then reads the files. A root that live-check blocks still
119
+ * prints its setup, so the exit code is not read.
120
+ */
121
+ export async function readLiveSetup(dir: string, options: { binary?: string; exec?: BinaryExec; env?: NodeJS.ProcessEnv } = {}): Promise<LiveSetup | undefined> {
122
+ const at = resolve(dir);
123
+ const had = known.get(at);
124
+ if (had) return had;
125
+ const exec = options.exec ?? runBinary;
126
+ let stdout: string;
127
+ try {
128
+ stdout = (await exec(options.binary ?? "choudoufu", ["live-check", "-json", at], at, options.env ?? process.env)).stdout;
129
+ } catch {
130
+ return undefined;
131
+ }
132
+ const setup = parseLiveSetup(stdout);
133
+ if (setup) known.set(at, setup);
134
+ return setup;
135
+ }
136
+
137
+ /** A live root's estate: choudoufu's resolved name when it was read, else the name its files write. */
138
+ export function resolvedEstate(dir: string, binary = "choudoufu"): string | undefined {
139
+ return knownLiveSetup(dir)?.estate ?? estateOf(dir, binary).estate;
140
+ }
141
+
142
+ const STORE_FROM: Record<string, string> = {
143
+ record_store: "from its record_store block",
144
+ backend: "derived from its backend block",
145
+ implied: "the local store, since no backend block gives one",
146
+ };
147
+
148
+ const ESTATE_FROM: Record<EstateSource, string> = {
149
+ explicit: "named by its live block",
150
+ tags: "from its tofu-estate tags",
151
+ backend_key: "from the backend key",
152
+ root_path: "from the root's path",
153
+ none: "none resolves",
154
+ };
155
+
156
+ /** The store as one phrase: `s3 bucket "acme" under tofu-records/prod/`. */
157
+ export function storePhrase(s: LiveStore): string {
158
+ if (s.kind === "local") return `the local directory ${s.bucket || ".tofu-records"} under ${s.prefix}`;
159
+ if (s.kind === "azurerm") return `azurerm container ${s.bucket} under ${s.prefix}`;
160
+ if (s.kind === "kubernetes") return `kubernetes namespace ${s.bucket} under ${s.prefix}`;
161
+ return `${s.kind} bucket "${s.bucket}" under ${s.prefix}`;
162
+ }
163
+
164
+ /** A root's setup on one line: where its records go, where that came from, and its estate. */
165
+ export function setupLine(root: string, setup: LiveSetup): string {
166
+ const s = setup.store;
167
+ const where = s ? `records in ${storePhrase(s)} (${STORE_FROM[s.source] ?? s.source}${s.declaredAt ? ` at ${s.declaredAt}` : ""})` : "no record store resolved";
168
+ const estate = setup.estate ? `estate "${setup.estate}" (${ESTATE_FROM[setup.estateSource as EstateSource] ?? setup.estateSource})` : "no estate resolves";
169
+ return `${root}: ${where}; ${estate}${s?.note ? `; ${s.note}` : ""}`;
170
+ }
171
+
172
+ /** The setup's store is the local directory, which is empty on every CI run. */
173
+ export const onLocalStore = (setup: LiveSetup): boolean => setup.store?.kind === "local";
174
+
175
+ /**
176
+ * The bucket core's check reads for a resolved store, or why there is none.
177
+ * `backend` is the root's backend block's string attributes, for the s3
178
+ * region and the azurerm subscription and resource group. s3 takes the
179
+ * region from there or the job, and an emulator's endpoint and keys from the
180
+ * job; gcs an emulator from `STORAGE_EMULATOR_HOST`; azurerm needs the
181
+ * subscription and resource group, from the backend block or
182
+ * `ARM_SUBSCRIPTION_ID`.
183
+ */
184
+ export function bucketTarget(s: LiveStore, backend: Record<string, string> = {}, env: NodeJS.ProcessEnv = process.env): { target: BucketTarget } | { skip: string } {
185
+ if (s.kind === "s3") {
186
+ const region = backend.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
187
+ if (!region) return { skip: "no region: set region in the backend block or AWS_REGION" };
188
+ const endpoint = env.AWS_ENDPOINT_URL_S3 ?? env.AWS_ENDPOINT_URL;
189
+ const keys =
190
+ env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY
191
+ ? { accessKeyId: env.AWS_ACCESS_KEY_ID, secretAccessKey: env.AWS_SECRET_ACCESS_KEY, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) }
192
+ : undefined;
193
+ if (endpoint && !keys) return { skip: "AWS_ENDPOINT_URL is set with no AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY" };
194
+ return { target: { store: "s3", bucket: s.bucket, region, ...(endpoint ? { endpoint, credentials: keys } : {}) } as BucketTarget };
195
+ }
196
+ if (s.kind === "gcs") {
197
+ const emulator = env.STORAGE_EMULATOR_HOST;
198
+ return { target: { store: "gcs", bucket: s.bucket, ...(emulator ? { endpoint: /^https?:\/\//.test(emulator) ? emulator : `http://${emulator}`, token: null } : {}) } as BucketTarget };
199
+ }
200
+ if (s.kind === "azurerm") {
201
+ const [account, container] = s.bucket.split("/");
202
+ const subscriptionId = backend.subscription_id ?? env.ARM_SUBSCRIPTION_ID;
203
+ const resourceGroup = backend.resource_group_name;
204
+ if (!account || !container) return { skip: "the store names no storage account and container" };
205
+ if (!subscriptionId || !resourceGroup) return { skip: "the bucket check needs the subscription and resource group: set resource_group_name in the backend block, and subscription_id there or ARM_SUBSCRIPTION_ID" };
206
+ return { target: { store: "azblob", subscriptionId, resourceGroup, account, container } as BucketTarget };
207
+ }
208
+ return { skip: `a ${s.kind} store has no bucket to check` };
209
+ }
210
+
211
+ /** What the bucket check said about one root's store. */
212
+ export type BucketOutcome = { checked: BucketReport } | { skipped: string };
213
+
214
+ /**
215
+ * Core's bucket check on a root's resolved store: the settings choudoufu
216
+ * refuses to open the bucket without. It reads only. A store with no bucket,
217
+ * or a check that cannot run, is skipped with the reason; nothing here throws.
218
+ * `check` is injectable for tests.
219
+ */
220
+ export async function checkStoreBucket(
221
+ s: LiveStore,
222
+ backend: Record<string, string> = {},
223
+ env: NodeJS.ProcessEnv = process.env,
224
+ check: (target: BucketTarget, options: { namespaces: string[] }) => Promise<BucketReport> = checkBucket,
225
+ ): Promise<BucketOutcome> {
226
+ if (s.kind === "local") return { skipped: "the local store has no bucket" };
227
+ const t = bucketTarget(s, backend, env);
228
+ if ("skip" in t) return { skipped: t.skip };
229
+ try {
230
+ return { checked: await check(t.target, { namespaces: s.prefix ? [s.prefix] : [] }) };
231
+ } catch (e) {
232
+ return { skipped: `the bucket could not be checked: ${(e as Error).message}` };
233
+ }
234
+ }
235
+
236
+ /** The bucket check's outcome as lines: one for a correct bucket, else one per setting that did not pass, with its fix. */
237
+ export function bucketLines(root: string, outcome: BucketOutcome): string[] {
238
+ if ("skipped" in outcome) return [`${root}: bucket not checked: ${outcome.skipped}`];
239
+ const r = outcome.checked;
240
+ if (r.correct) return [`${root}: bucket ${r.bucket} has every setting choudoufu needs (${r.settings.map((f) => f.setting).join(", ")})`];
241
+ return r.settings
242
+ .filter((f) => f.verdict !== "ok")
243
+ .map((f) => `${root}: bucket ${r.bucket}: ${f.setting} ${f.verdict === "unreadable" ? "could not be read" : "fails"}: ${f.found}${f.unwaivable ? " (no allow_insecure reaches this one)" : ""}${f.fix ? `; fix: ${f.fix}` : ""}`);
244
+ }
@@ -0,0 +1,83 @@
1
+ /**
2
+ * chant#4910: a migration's history read back from the finished lines core's
3
+ * `runStateMigration` writes, and the revert of one that applied. Plain text;
4
+ * nothing reads git.
5
+ */
6
+ import { describe, expect, test } from "vitest";
7
+ import { doneMigrations, finishedMigrationLines, migrationHistory, revertMigration } from "./migration-history";
8
+ import { MigrationError } from "./state-migration";
9
+
10
+ const finished = (gate: string, detail: Record<string, string>, timestamp = "2026-11-08T10:00:00Z") =>
11
+ JSON.stringify({ version: 1, kind: "finished", op: "tf-migrate", gate, planDigest: `sha256:${gate}`, timestamp, detail });
12
+
13
+ const moved = finished("move-queues", {
14
+ result: "applied",
15
+ approved_by: "bo",
16
+ file_digest: "sha256:file",
17
+ change: "moves",
18
+ migration_change: "moves",
19
+ roots: "envs/a,envs/b",
20
+ "envs/a.location": "s3://acme/a.tfstate",
21
+ "envs/a.before": "a1",
22
+ "envs/a.after": "a2",
23
+ "envs/a.before_digest": "sha256:a1",
24
+ "envs/a.after_digest": "sha256:a2",
25
+ "envs/b.location": "s3://acme/b.tfstate",
26
+ "envs/b.after": "b1",
27
+ "envs/b.after_digest": "sha256:b1",
28
+ });
29
+
30
+ describe("finishedMigrationLines (chant#4910)", () => {
31
+ test("each finished line as a history line; a run refused under the locks, or one with no result, has none", () => {
32
+ const text = [moved, finished("refused-one", { result: "refused", roots: "x" }), finished("threw", {}), "not json", ""].join("\n");
33
+ const lines = finishedMigrationLines(text, "tf-migrate");
34
+ expect(lines).toHaveLength(1);
35
+ expect(lines[0]).toEqual({
36
+ version: 1,
37
+ kind: "migration",
38
+ op: "tf-migrate",
39
+ gate: "move-queues",
40
+ timestamp: "2026-11-08T10:00:00Z",
41
+ planDigest: "sha256:move-queues",
42
+ file_digest: "sha256:file",
43
+ result: "applied",
44
+ approvedBy: "bo",
45
+ change: "moves",
46
+ roots: [
47
+ { root: "envs/a", location: "s3://acme/a.tfstate", before: "a1", after: "a2", before_digest: "sha256:a1", after_digest: "sha256:a2" },
48
+ { root: "envs/b", location: "s3://acme/b.tfstate", before: null, after: "b1", before_digest: null, after_digest: "sha256:b1" },
49
+ ],
50
+ source: "finished",
51
+ });
52
+ });
53
+
54
+ test("the history reads the product's earlier lines first, and the newest line of a migration wins", () => {
55
+ const earlier = JSON.stringify({ version: 1, kind: "migration", op: "tf-migrate", gate: "move-queues", timestamp: "2026-10-01T00:00:00Z", result: "failed", roots: [] });
56
+ const files: Record<string, string> = { "_gates/tf-migrate/done.jsonl": `${earlier}\n`, "_gates/tf-migrate/applied.jsonl": `${moved}\n` };
57
+ const history = migrationHistory((p) => files[p] ?? "", { op: "tf-migrate", earlier: "_gates/tf-migrate/done.jsonl" });
58
+ expect(history.trim().split("\n")).toHaveLength(2);
59
+ expect(doneMigrations(history).get("move-queues")).toEqual({ status: "applied", file_digest: "sha256:file", timestamp: "2026-11-08T10:00:00Z" });
60
+ });
61
+ });
62
+
63
+ describe("revertMigration (chant#4910)", () => {
64
+ const history = finishedMigrationLines(moved, "tf-migrate").map((l) => JSON.stringify(l)).join("\n");
65
+
66
+ test("each root back to the version recorded before the write, from the one recorded after", () => {
67
+ const r = revertMigration("move-queues", history, { header: ["Written by the product."] });
68
+ expect(r.name).toBe("move-queues-revert");
69
+ expect(r.restores).toEqual([
70
+ { root: "envs/a", location: "s3://acme/a.tfstate", version_id: "a1", from_version_id: "a2" },
71
+ { root: "envs/b", location: "s3://acme/b.tfstate", version_id: null, from_version_id: "b1" },
72
+ ]);
73
+ expect(r.text.split("\n").slice(0, 4)).toEqual(["# Written by the product.", "revert: move-queues", "restores:", " - root: envs/a"]);
74
+ });
75
+
76
+ test("a migration never applied, a backend move, and a root with no version are refused with why", () => {
77
+ expect(() => revertMigration("other", history, { where: "in its history" })).toThrow(new MigrationError("chant/lifecycle records no applied migration other, in its history"));
78
+ const backends = finishedMigrationLines(finished("to-gcs", { result: "applied", migration_change: "backends", roots: "r" }), "tf-migrate").map((l) => JSON.stringify(l)).join("\n");
79
+ expect(() => revertMigration("to-gcs", backends)).toThrow(/backend move the other way/);
80
+ const pg = finishedMigrationLines(finished("pg", { result: "applied", migration_change: "moves", roots: "r", "r.location": "pg://db", "r.after_digest": "sha256:x" }), "tf-migrate").map((l) => JSON.stringify(l)).join("\n");
81
+ expect(() => revertMigration("pg", pg)).toThrow(/keeps no versions/);
82
+ });
83
+ });
@@ -0,0 +1,199 @@
1
+ /**
2
+ * A state migration's history, read back from the lines chant wrote
3
+ * (chant#4910): each `finished` line of the migration's gated requests
4
+ * (`_gates/<op>/applied.jsonl` on `chant/lifecycle`, written by core's
5
+ * `runStateMigration` with `migrationFacts`), as one history line per run,
6
+ * and the revert of a migration that applied, each root back to the version
7
+ * the migration recorded before it wrote.
8
+ *
9
+ * The history line is the form terragucci's `done.jsonl` has always held,
10
+ * so a product that kept such a file before chant ran its gate reads the two
11
+ * together ({@link migrationHistory}). Besides core's facts, a finished
12
+ * line's detail may carry the product's `file_digest`, its change
13
+ * (`migration_change`, else `change`) and the migration a revert put back
14
+ * (`revert`); they are read when there.
15
+ *
16
+ * Lifted from terragucci's `finishedMigrationLines`, `migrationHistory` and
17
+ * `revertMigration` (migrate.ts), so terragucci deletes its copies and keeps
18
+ * its file's words.
19
+ */
20
+ import { MigrationError, type Restore } from "./state-migration";
21
+
22
+ /** One root of a history line: where its state is, and its version and digest before and after. */
23
+ export interface MigrationHistoryRoot {
24
+ root: string;
25
+ location: string | null;
26
+ before: string | null;
27
+ after: string | null;
28
+ before_digest: string | null;
29
+ after_digest: string | null;
30
+ /** A backend move's source, and the version read there. */
31
+ source?: string | null;
32
+ source_version?: string | null;
33
+ }
34
+
35
+ /** One run of a migration, as its history holds it. */
36
+ export interface MigrationHistoryLine {
37
+ version: 1;
38
+ kind: "migration";
39
+ op: string;
40
+ /** The migration's name. */
41
+ gate: string;
42
+ timestamp: string;
43
+ planDigest?: string;
44
+ file_digest?: string;
45
+ /** `applied` or `failed`. A run refused under the locks wrote nothing and has no line. */
46
+ result: string;
47
+ approvedBy?: string;
48
+ /** The migration's change: `moves`, `backends`, `revert`, `retag`, `adopt`, as the product's detail names it. */
49
+ change: string | null;
50
+ /** The migration a revert put back. */
51
+ revert?: string;
52
+ roots: MigrationHistoryRoot[];
53
+ error?: string;
54
+ /** `finished`: read from a gated request's finished line. */
55
+ source?: string;
56
+ }
57
+
58
+ /**
59
+ * The finished lines of a migration op's `applied.jsonl` as history lines,
60
+ * oldest first. A line without a `result` is skipped (the migration threw
61
+ * before it ended), and so is a run refused under the lock, which wrote
62
+ * nothing.
63
+ */
64
+ export function finishedMigrationLines(appliedText: string, op: string): MigrationHistoryLine[] {
65
+ const out: MigrationHistoryLine[] = [];
66
+ for (const l of appliedText.split("\n").map((x) => x.trim()).filter(Boolean)) {
67
+ let r: Record<string, unknown>;
68
+ try {
69
+ r = JSON.parse(l) as Record<string, unknown>;
70
+ } catch {
71
+ continue;
72
+ }
73
+ if (r.version !== 1 || r.kind !== "finished" || typeof r.gate !== "string" || typeof r.timestamp !== "string") continue;
74
+ const d = r.detail && typeof r.detail === "object" ? (r.detail as Record<string, unknown>) : {};
75
+ if (typeof d.result !== "string" || d.result === "refused") continue;
76
+ const str = (k: string): string | null => (typeof d[k] === "string" ? (d[k] as string) : null);
77
+ const roots = (str("roots") ?? "")
78
+ .split(",")
79
+ .filter(Boolean)
80
+ .map((root): MigrationHistoryRoot => ({
81
+ root,
82
+ location: str(`${root}.location`),
83
+ before: str(`${root}.before`),
84
+ after: str(`${root}.after`),
85
+ before_digest: str(`${root}.before_digest`),
86
+ after_digest: str(`${root}.after_digest`),
87
+ ...(str(`${root}.source`) ? { source: str(`${root}.source`), source_version: str(`${root}.source_version`) } : {}),
88
+ }));
89
+ out.push({
90
+ version: 1,
91
+ kind: "migration",
92
+ op,
93
+ gate: r.gate,
94
+ timestamp: r.timestamp,
95
+ ...(typeof r.planDigest === "string" ? { planDigest: r.planDigest } : {}),
96
+ ...(str("file_digest") ? { file_digest: str("file_digest")! } : {}),
97
+ result: d.result,
98
+ ...(str("approved_by") ? { approvedBy: str("approved_by")! } : {}),
99
+ change: str("migration_change") ?? str("change"),
100
+ ...(str("revert") ? { revert: str("revert")! } : {}),
101
+ roots,
102
+ ...(str("error") ? { error: str("error")! } : {}),
103
+ source: "finished",
104
+ });
105
+ }
106
+ return out;
107
+ }
108
+
109
+ /** Where a migration op's history is kept on `chant/lifecycle`: chant's `applied.jsonl`, and the product's own earlier file, if it kept one. */
110
+ export interface MigrationHistoryFiles {
111
+ op: string;
112
+ /** The product's file of history lines written before chant ran the gate, such as `_gates/tf-migrate/done.jsonl`. */
113
+ earlier?: string;
114
+ }
115
+
116
+ /**
117
+ * A migration op's history as history-line text, one JSON line each: the
118
+ * product's earlier lines first, then each finished line of chant's gated
119
+ * requests. The newest line of a migration wins. `show` reads a path on
120
+ * `chant/lifecycle` as the caller wants it read (the remote ref as last
121
+ * fetched, say), answering "" for a path that is not there.
122
+ */
123
+ export function migrationHistory(show: (path: string) => string, files: MigrationHistoryFiles): string {
124
+ const earlier = files.earlier ? show(files.earlier).split("\n").map((l) => l.trim()).filter(Boolean) : [];
125
+ const finished = finishedMigrationLines(show(`_gates/${files.op}/applied.jsonl`), files.op).map((l) => JSON.stringify(l));
126
+ return [...earlier, ...finished].join("\n") + "\n";
127
+ }
128
+
129
+ /** The newest line of each migration that ran its writes, by name. */
130
+ export function doneMigrations(history: string): Map<string, { status: string; file_digest?: string; timestamp: string }> {
131
+ const out = new Map<string, { status: string; file_digest?: string; timestamp: string }>();
132
+ for (const line of history.split("\n").map((l) => l.trim()).filter(Boolean)) {
133
+ try {
134
+ const r = JSON.parse(line) as Record<string, unknown>;
135
+ if (r.kind !== "migration" || typeof r.gate !== "string" || typeof r.timestamp !== "string") continue;
136
+ out.set(r.gate, { status: String(r.result), ...(typeof r.file_digest === "string" ? { file_digest: r.file_digest } : {}), timestamp: r.timestamp });
137
+ } catch {
138
+ continue;
139
+ }
140
+ }
141
+ return out;
142
+ }
143
+
144
+ /** The name a revert of `name` takes. */
145
+ export const revertName = (name: string): string => `${name}-revert`;
146
+
147
+ /** A revert of a migration that applied: its name, each root's restore, and the migration file that asks for it. */
148
+ export interface MigrationRevert {
149
+ name: string;
150
+ restores: Restore[];
151
+ /** The file, `revert:` and `restores:`, under the caller's comment lines. */
152
+ text: string;
153
+ }
154
+
155
+ /**
156
+ * The revert of a migration that applied, from its newest applied line in
157
+ * `history`: each root back to the version the migration recorded before it
158
+ * wrote, from the version it recorded after (the write is refused when a
159
+ * state moved past it). A backend move, a revert, an estate retag or an
160
+ * estate adoption is not put back this way, and a root whose bucket kept no
161
+ * version cannot be put back: each throws {@link MigrationError} naming why.
162
+ * `where` names the history in the refusal; `header` are the file's comment
163
+ * lines, without their `# `.
164
+ */
165
+ export function revertMigration(name: string, history: string, options: { where?: string; header?: readonly string[] } = {}): MigrationRevert {
166
+ let line: Record<string, unknown> | undefined;
167
+ for (const l of history.split("\n").map((x) => x.trim()).filter(Boolean)) {
168
+ try {
169
+ const r = JSON.parse(l) as Record<string, unknown>;
170
+ if (r.kind === "migration" && r.gate === name && r.result === "applied") line = r;
171
+ } catch {
172
+ continue;
173
+ }
174
+ }
175
+ if (!line) throw new MigrationError(`chant/lifecycle records no applied migration ${name}${options.where ? `, ${options.where}` : ""}`);
176
+ if (line.change === "backends") throw new MigrationError(`${name} moved states to new backends; put it back with a backend move the other way, which reads each state where it is now`);
177
+ if (line.change === "revert") throw new MigrationError(`${name} is a revert; apply the migration it put back again with a new migration file`);
178
+ if (line.change === "retag") throw new MigrationError(`${name} retagged resources between estates; put it back with a moves migration the other way`);
179
+ if (line.change === "adopt") throw new MigrationError(`${name} adopted a state into an estate and left the state where it was; to go back, put the backend block back in place of the live block`);
180
+ const roots = Array.isArray(line.roots) ? (line.roots as Record<string, unknown>[]) : [];
181
+ const problems: string[] = [];
182
+ const restores: Restore[] = roots.map((r) => {
183
+ const root = String(r.root);
184
+ if (typeof r.location !== "string" || !/^(s3|gs|az):\/\//.test(r.location)) problems.push(`${root}: its backend keeps no versions, so there is no earlier state to put back`);
185
+ if (r.before === null && r.before_digest !== null) problems.push(`${root}: its bucket kept no version before ${name} wrote, so there is no earlier state to put back`);
186
+ if (typeof r.after !== "string") problems.push(`${root}: ${name} recorded no version after its write, so a later change could not be told apart`);
187
+ return { root, location: String(r.location), version_id: typeof r.before === "string" ? r.before : null, from_version_id: typeof r.after === "string" ? r.after : null };
188
+ });
189
+ if (problems.length > 0) throw new MigrationError(`${name} cannot be put back:\n ${problems.join("\n ")}`);
190
+ const q = (v: string | null): string => (v === null ? "null" : JSON.stringify(v));
191
+ const text = [
192
+ ...(options.header ?? [`Puts back the states migration ${name} wrote, to the versions it recorded before it wrote them.`]).map((h) => `# ${h}`),
193
+ `revert: ${name}`,
194
+ "restores:",
195
+ ...restores.flatMap((r) => [` - root: ${r.root}`, ` location: ${r.location}`, ` version_id: ${q(r.version_id)}`, ` from_version_id: ${q(r.from_version_id)}`]),
196
+ "",
197
+ ].join("\n");
198
+ return { name: revertName(name), restores, text };
199
+ }
@@ -14,11 +14,14 @@
14
14
  * it counts static rows only.
15
15
  *
16
16
  * This subpath, `@intentius/chant-lexicon-terraform/module-catalog`, imports
17
- * nothing but its own data, so a consumer can load it on its own.
17
+ * nothing but its own data and the lexicon's floors file (#4916), so a
18
+ * consumer can load it on its own.
18
19
  */
19
20
  import { SOURCE_COMMIT, SOURCE_PATH, STATIC_MEASUREMENT, STATIC_ROWS } from "./static-tier";
20
21
  import type { StaticRow } from "./types";
21
22
 
23
+ export { MODULE_CATALOG_FLOOR } from "../chant-floors";
24
+
22
25
  export type { StaticRefusal, StaticRow, StaticMeasurement, StaticSource } from "./types";
23
26
 
24
27
  /** Where the vendored rows came from. */