@intentius/chant-lexicon-terraform 0.124.87 → 0.124.89

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 (82) 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-runner.d.ts +86 -0
  13. package/dist/engine-runner.d.ts.map +1 -0
  14. package/dist/engine-runner.js +134 -0
  15. package/dist/engine-timings.d.ts +249 -0
  16. package/dist/engine-timings.d.ts.map +1 -0
  17. package/dist/engine-timings.js +569 -0
  18. package/dist/integrity.json +2 -2
  19. package/dist/live-roots.d.ts +143 -0
  20. package/dist/live-roots.d.ts.map +1 -0
  21. package/dist/live-roots.js +304 -0
  22. package/dist/manifest.json +1 -1
  23. package/dist/migration-history.d.ts +105 -0
  24. package/dist/migration-history.d.ts.map +1 -0
  25. package/dist/migration-history.js +159 -0
  26. package/dist/module-catalog/index.d.ts +1 -0
  27. package/dist/module-catalog/index.d.ts.map +1 -1
  28. package/dist/module-catalog/index.js +3 -1
  29. package/dist/op/activities/live-detect.d.ts +15 -0
  30. package/dist/op/activities/live-detect.d.ts.map +1 -1
  31. package/dist/op/activities/live-detect.js +94 -0
  32. package/dist/op/activities/terraform.d.ts +1 -65
  33. package/dist/op/activities/terraform.d.ts.map +1 -1
  34. package/dist/op/activities/terraform.js +4 -54
  35. package/dist/op/command-hook.d.ts +98 -0
  36. package/dist/op/command-hook.d.ts.map +1 -0
  37. package/dist/op/command-hook.js +115 -0
  38. package/dist/registry/index.d.ts +1 -0
  39. package/dist/registry/index.d.ts.map +1 -1
  40. package/dist/registry/index.js +1 -0
  41. package/dist/state/exec.d.ts +23 -0
  42. package/dist/state/exec.d.ts.map +1 -1
  43. package/dist/state/exec.js +38 -0
  44. package/dist/state-ops.d.ts.map +1 -1
  45. package/dist/state-ops.js +3 -1
  46. package/dist/terragrunt/index.d.ts +3 -1
  47. package/dist/terragrunt/index.d.ts.map +1 -1
  48. package/dist/terragrunt/index.js +3 -1
  49. package/dist/terragrunt/place.d.ts +27 -0
  50. package/dist/terragrunt/place.d.ts.map +1 -0
  51. package/dist/terragrunt/place.js +52 -0
  52. package/dist/terragrunt/run.d.ts +23 -0
  53. package/dist/terragrunt/run.d.ts.map +1 -1
  54. package/dist/terragrunt/run.js +107 -3
  55. package/package.json +2 -2
  56. package/src/action-ops.ts +3 -1
  57. package/src/chant-floors.ts +32 -0
  58. package/src/components/capability-plugin.ts +27 -6
  59. package/src/components/compose-group.test.ts +29 -0
  60. package/src/components/compose-group.ts +12 -5
  61. package/src/components/terraform-apply-command-hook.test.ts +43 -0
  62. package/src/engine-runner.test.ts +261 -0
  63. package/src/engine-runner.ts +191 -0
  64. package/src/engine-timings.test.ts +203 -0
  65. package/src/engine-timings.ts +718 -0
  66. package/src/live-record-store.test.ts +76 -0
  67. package/src/live-roots.test.ts +80 -0
  68. package/src/live-roots.ts +347 -0
  69. package/src/migration-history.test.ts +83 -0
  70. package/src/migration-history.ts +199 -0
  71. package/src/module-catalog/index.ts +4 -1
  72. package/src/op/activities/live-detect.ts +87 -0
  73. package/src/op/activities/terraform.ts +12 -111
  74. package/src/op/command-hook.ts +189 -0
  75. package/src/registry/index.ts +1 -0
  76. package/src/state/engine-env.test.ts +18 -0
  77. package/src/state/exec.ts +38 -0
  78. package/src/state-ops.ts +3 -1
  79. package/src/terragrunt/index.ts +3 -1
  80. package/src/terragrunt/place.test.ts +42 -0
  81. package/src/terragrunt/place.ts +75 -0
  82. package/src/terragrunt/run.ts +128 -4
@@ -0,0 +1,76 @@
1
+ /**
2
+ * A live root's record store resolved through chant (chant#4954):
3
+ * choudoufu's resolved store when `live-check -json` was read, else the
4
+ * `record_store` block the files write, and the backend block's strings for
5
+ * an s3 store's region and the bucket check.
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 { forgetLiveSetups, liveBlockText, liveRecordStore, rememberLiveSetup, rootBackendAttrs, writtenRecordStore } from "./live-roots";
12
+
13
+ afterEach(() => forgetLiveSetups());
14
+
15
+ /** A root directory holding `files`. */
16
+ function root(files: Record<string, string>): string {
17
+ const dir = mkdtempSync(join(tmpdir(), "chant-record-store-"));
18
+ for (const [name, text] of Object.entries(files)) {
19
+ mkdirSync(join(dir, name, ".."), { recursive: true });
20
+ writeFileSync(join(dir, name), text);
21
+ }
22
+ return dir;
23
+ }
24
+
25
+ const S3_BACKEND = 'terraform {\n backend "s3" {\n bucket = "state"\n region = "eu-west-1"\n encrypt = true\n }\n}\n';
26
+
27
+ describe("the store a root's files write", () => {
28
+ test("an s3 record_store block, its key_prefix, bucket and region", () => {
29
+ const dir = root({
30
+ "main.tf": 'terraform {\n live {\n estate = "prod"\n # record_store "local" {}\n record_store "s3" {\n bucket = "records"\n region = "us-east-2"\n key_prefix = "custom/prod"\n }\n }\n}\n',
31
+ });
32
+ expect(writtenRecordStore(dir, "prod")).toEqual({ kind: "s3", bucket: "records", prefix: "custom/prod/", region: "us-east-2" });
33
+ });
34
+
35
+ test("no record_store block is the local store beside the root, under tofu-records/<estate>/", () => {
36
+ const dir = root({ "estate.chdf.hcl": 'estate = "dev"\n' });
37
+ expect(writtenRecordStore(dir, "dev")).toEqual({ kind: "local", dir: join(dir, ".tofu-records"), prefix: "tofu-records/dev/" });
38
+ expect(liveBlockText(dir)).toContain('estate = "dev"');
39
+ });
40
+
41
+ test("an s3 store with no bucket, and a kind it does not read, are unread", () => {
42
+ expect(writtenRecordStore(root({ "main.tf": 'terraform {\n live {\n record_store "s3" {\n }\n }\n}\n' }), "e")).toEqual({ kind: "unread", name: "s3" });
43
+ expect(writtenRecordStore(root({ "main.tf": 'terraform {\n live {\n record_store "kubernetes" {\n namespace = "x"\n }\n }\n}\n' }), "e")).toEqual({ kind: "unread", name: "kubernetes" });
44
+ });
45
+
46
+ test("a root with no live block has no store", () => {
47
+ const dir = root({ "main.tf": S3_BACKEND });
48
+ expect(writtenRecordStore(dir, "e")).toBeUndefined();
49
+ expect(liveRecordStore(dir, "e")).toBeUndefined();
50
+ });
51
+ });
52
+
53
+ describe("the store choudoufu resolved", () => {
54
+ test("wins over the files, an s3 store taking its region from the backend block", () => {
55
+ const dir = root({ "main.tf": 'terraform {\n live {\n estate = "prod"\n }\n}\n', "backend.tf": S3_BACKEND });
56
+ rememberLiveSetup(dir, { estate: "prod", estateSource: "explicit", store: { kind: "s3", bucket: "state", prefix: "tofu-records/prod/", source: "backend" } });
57
+ expect(liveRecordStore(dir, "prod")).toEqual({ kind: "s3", bucket: "state", prefix: "tofu-records/prod/", region: "eu-west-1" });
58
+ });
59
+
60
+ test("a resolved local store is a directory under the root, and another kind is unread", () => {
61
+ const dir = root({ "main.tf": 'terraform {\n live {\n }\n}\n' });
62
+ rememberLiveSetup(dir, { estateSource: "root_path", store: { kind: "local", bucket: "", prefix: "tofu-records/x/", source: "implied" } });
63
+ expect(liveRecordStore(dir, "x")).toEqual({ kind: "local", dir: join(dir, ".tofu-records"), prefix: "tofu-records/x/" });
64
+ forgetLiveSetups();
65
+ rememberLiveSetup(dir, { estateSource: "root_path", store: { kind: "gcs", bucket: "b", prefix: "p/", source: "backend" } });
66
+ expect(liveRecordStore(dir, "x")).toEqual({ kind: "unread", name: "gcs" });
67
+ });
68
+ });
69
+
70
+ describe("the backend block's strings", () => {
71
+ test("are its plain string attributes, and none for a cloud block or no backend", () => {
72
+ expect(rootBackendAttrs(root({ "main.tf": S3_BACKEND }))).toEqual({ bucket: "state", region: "eu-west-1" });
73
+ expect(rootBackendAttrs(root({ "main.tf": 'terraform {\n cloud {\n organization = "o"\n }\n}\n' }))).toEqual({});
74
+ expect(rootBackendAttrs(root({ "main.tf": 'resource "x" "y" {}\n' }))).toEqual({});
75
+ });
76
+ });
@@ -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,347 @@
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
+ * - {@link liveRecordStore}: where a live root's records are, choudoufu's
21
+ * resolved store over the one its files write ({@link writtenRecordStore}),
22
+ * and {@link rootBackendAttrs}, the backend block's strings the bucket
23
+ * check and an s3 store's region read (chant#4954).
24
+ *
25
+ * Text reads, as `./op/activities/live-detect.ts` does them: no HCL parser
26
+ * is loaded. Lifted from terragucci's `detect.ts` (`liveRoots`, `estateOf`)
27
+ * and `live-setup.ts`, and `cdf-records.ts` (`recordStoreOf`), so
28
+ * terragucci deletes its copies.
29
+ */
30
+ import { existsSync, readFileSync } from "node:fs";
31
+ import { join, resolve } from "node:path";
32
+ import { checkBucket, type BucketReport, type BucketTarget } from "@intentius/chant/bucket-check";
33
+ import { blankComments, blockBody, hclAttr, rootTexts } from "./compose/hcl";
34
+ import { declaresLive, detectLiveEstate, estateOutputReads } from "./op/activities/live-detect";
35
+ import { declaredBackend } from "./state/backend";
36
+ import { runBinary, type BinaryExec } from "./state/exec";
37
+
38
+ export { declaresLive, detectLiveEstate, estateOutputReads } from "./op/activities/live-detect";
39
+
40
+ /** The roots of `roots` (paths under `repo`) that keep their resources under choudoufu's live markers, in the order given. */
41
+ export function liveRoots(repo: string, roots: readonly string[], binary = "choudoufu"): string[] {
42
+ return roots.filter((r) => declaresLive(join(repo, r), binary));
43
+ }
44
+
45
+ /** A root's estate, as its sidecar or `live` block names it, and the estates whose recorded outputs it reads. */
46
+ export function estateOf(dir: string, binary = "choudoufu"): { estate?: string; reads: string[] } {
47
+ const estate = detectLiveEstate(dir, binary);
48
+ return { ...(estate ? { estate } : {}), reads: estateOutputReads(dir, binary).map((r) => r.estate) };
49
+ }
50
+
51
+ /** Where choudoufu's estate name came from: the live block, the configuration's tags, the backend key, or the root's path. */
52
+ export type EstateSource = "explicit" | "tags" | "backend_key" | "root_path" | "none";
53
+
54
+ /** The record store choudoufu resolved, as `live-check -json` prints it. */
55
+ export interface LiveStore {
56
+ /** `local`, `s3`, `gcs`, `azurerm` or `kubernetes`. */
57
+ kind: string;
58
+ /** The s3 or gcs bucket, `<account>/<container>` for azurerm, the namespace for kubernetes, the directory for local. */
59
+ bucket: string;
60
+ /** Where this estate's records go, with one trailing slash. */
61
+ prefix: string;
62
+ /** `record_store` (written by the author), `backend` (derived from the backend block) or `implied` (the local store). */
63
+ source: string;
64
+ /** `file:line` of the block that decided it. */
65
+ declaredAt?: string;
66
+ /** Why a backend that was there was not used. */
67
+ note?: string;
68
+ }
69
+
70
+ /** What choudoufu resolves for one root. */
71
+ export interface LiveSetup {
72
+ estate?: string;
73
+ estateSource: string;
74
+ store?: LiveStore;
75
+ }
76
+
77
+ const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
78
+
79
+ /** 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`. */
80
+ export function parseLiveSetup(stdout: string): LiveSetup | undefined {
81
+ let doc: Record<string, unknown>;
82
+ try {
83
+ doc = JSON.parse(stdout) as Record<string, unknown>;
84
+ } catch {
85
+ return undefined;
86
+ }
87
+ if (!doc || typeof doc !== "object" || typeof doc.estate_source !== "string") return undefined;
88
+ const rs = doc.record_store && typeof doc.record_store === "object" ? (doc.record_store as Record<string, unknown>) : undefined;
89
+ const kind = str(rs?.kind);
90
+ const store: LiveStore | undefined =
91
+ rs && kind
92
+ ? {
93
+ kind,
94
+ bucket: str(rs.bucket) ?? "",
95
+ prefix: str(rs.prefix) ?? "",
96
+ source: str(rs.source) ?? "",
97
+ ...(str(rs.declared_at) ? { declaredAt: str(rs.declared_at) } : {}),
98
+ ...(str(rs.note) ? { note: str(rs.note) } : {}),
99
+ }
100
+ : undefined;
101
+ const estate = str(doc.estate);
102
+ return { ...(estate ? { estate } : {}), estateSource: doc.estate_source, ...(store ? { store } : {}) };
103
+ }
104
+
105
+ const known = new Map<string, LiveSetup>();
106
+
107
+ /** Keep what choudoufu resolved for a root's directory, for the readers below. */
108
+ export function rememberLiveSetup(dir: string, setup: LiveSetup): void {
109
+ known.set(resolve(dir), setup);
110
+ }
111
+
112
+ /** What choudoufu resolved for a root's directory in this process, if it was read. */
113
+ export function knownLiveSetup(dir: string): LiveSetup | undefined {
114
+ return known.get(resolve(dir));
115
+ }
116
+
117
+ /** For tests: forget every setup read so far. */
118
+ export function forgetLiveSetups(): void {
119
+ known.clear();
120
+ }
121
+
122
+ /**
123
+ * `choudoufu live-check -json <dir>` for one root, run in the directory, and
124
+ * the setup it prints, remembered for the process. Undefined when the binary
125
+ * prints none (an older release, a root it cannot read, or no binary at
126
+ * all); the caller then reads the files. A root that live-check blocks still
127
+ * prints its setup, so the exit code is not read.
128
+ */
129
+ export async function readLiveSetup(dir: string, options: { binary?: string; exec?: BinaryExec; env?: NodeJS.ProcessEnv } = {}): Promise<LiveSetup | undefined> {
130
+ const at = resolve(dir);
131
+ const had = known.get(at);
132
+ if (had) return had;
133
+ const exec = options.exec ?? runBinary;
134
+ let stdout: string;
135
+ try {
136
+ stdout = (await exec(options.binary ?? "choudoufu", ["live-check", "-json", at], at, options.env ?? process.env)).stdout;
137
+ } catch {
138
+ return undefined;
139
+ }
140
+ const setup = parseLiveSetup(stdout);
141
+ if (setup) known.set(at, setup);
142
+ return setup;
143
+ }
144
+
145
+ /** A live root's estate: choudoufu's resolved name when it was read, else the name its files write. */
146
+ export function resolvedEstate(dir: string, binary = "choudoufu"): string | undefined {
147
+ return knownLiveSetup(dir)?.estate ?? estateOf(dir, binary).estate;
148
+ }
149
+
150
+ /**
151
+ * Where a live root's records are, for a product that lists them
152
+ * (chant#4954): an S3 bucket, a directory, or a store it does not read
153
+ * (`name` is its kind). `prefix` has one trailing slash.
154
+ */
155
+ export type RecordStore =
156
+ | { kind: "s3"; bucket: string; prefix: string; region?: string }
157
+ | { kind: "local"; dir: string; prefix: string }
158
+ | { kind: "unread"; name: string };
159
+
160
+ /** A key namespace with exactly one trailing slash, as choudoufu's NamespacePrefix makes it. */
161
+ const namespace = (prefix: string): string => `${prefix.replace(/\/+$/, "")}/`;
162
+
163
+ /**
164
+ * The text of a root's `live` block, comments blanked: its `estate.chdf.hcl`
165
+ * sidecar whole, else the `live` block in a `terraform` block of its HCL
166
+ * files. Undefined when it has neither.
167
+ */
168
+ export function liveBlockText(dir: string, binary = "choudoufu"): string | undefined {
169
+ const sidecar = join(dir, "estate.chdf.hcl");
170
+ if (existsSync(sidecar)) return blankComments(readFileSync(sidecar, "utf-8"));
171
+ for (const { text, json } of rootTexts(dir, binary)) {
172
+ if (json) continue;
173
+ for (const t of text.matchAll(/^\s*terraform\s*\{/gm)) {
174
+ const body = blockBody(text, t.index!);
175
+ const live = body.match(/\blive\s*\{/);
176
+ if (live) return blockBody(body, live.index!);
177
+ }
178
+ }
179
+ return undefined;
180
+ }
181
+
182
+ /**
183
+ * The record store a live root's files write for `estate` (chant#4954): the
184
+ * `record_store "<kind>"` block in its `live` block or sidecar, its
185
+ * `key_prefix` (default `tofu-records/<estate>/`), an s3 store's `bucket` and
186
+ * `region`, a local store's `path` (default `.tofu-records`, beside the
187
+ * root). No `record_store` block is the local store. Undefined when the root
188
+ * has no live block. Lifted from terragucci's `recordStoreOf`
189
+ * (cdf-records.ts).
190
+ */
191
+ export function writtenRecordStore(dir: string, estate: string, binary = "choudoufu"): RecordStore | undefined {
192
+ const live = liveBlockText(dir, binary);
193
+ if (live === undefined) return undefined;
194
+ const m = /\brecord_store\s+"([^"]+)"\s*\{/.exec(live);
195
+ const attr = m ? hclAttr(blockBody(live, m.index)) : () => undefined;
196
+ const str = (name: string): string | undefined => {
197
+ const v = attr(name);
198
+ return typeof v === "string" ? v : undefined;
199
+ };
200
+ const prefix = namespace(str("key_prefix") ?? `tofu-records/${estate}`);
201
+ const kind = m?.[1] ?? "local";
202
+ if (kind === "s3") {
203
+ const bucket = str("bucket");
204
+ if (!bucket) return { kind: "unread", name: "s3" };
205
+ const region = str("region");
206
+ return { kind: "s3", bucket, prefix, ...(region ? { region } : {}) };
207
+ }
208
+ if (kind === "local") return { kind: "local", dir: join(dir, str("path") ?? ".tofu-records"), prefix };
209
+ return { kind: "unread", name: kind };
210
+ }
211
+
212
+ /**
213
+ * The string attributes of a root's backend block as its code writes them
214
+ * (chant#4954), for the bucket check's s3 region and azurerm subscription
215
+ * and resource group. Empty for a `cloud` block or no backend. Read with
216
+ * {@link declaredBackend}, without the job's `-backend-config` flags.
217
+ */
218
+ export function rootBackendAttrs(dir: string, binary = "choudoufu"): Record<string, string> {
219
+ const b = declaredBackend(dir, { binary, env: {} });
220
+ if (!b || b.type === "cloud") return {};
221
+ return Object.fromEntries(Object.entries(b.config).filter((e): e is [string, string] => typeof e[1] === "string"));
222
+ }
223
+
224
+ /**
225
+ * A live root's record store (chant#4954): choudoufu's resolved store when
226
+ * {@link readLiveSetup} read it for the root, else the one its files write
227
+ * ({@link writtenRecordStore}). An s3 store's region, which `live-check
228
+ * -json` does not print, comes from the `record_store` block, else the
229
+ * backend block. Undefined when the root has no live block. Lifted from
230
+ * terragucci's `resolvedRecordStore` (live-setup.ts).
231
+ */
232
+ export function liveRecordStore(dir: string, estate: string, binary = "choudoufu"): RecordStore | undefined {
233
+ if (liveBlockText(dir, binary) === undefined) return undefined;
234
+ const s = knownLiveSetup(dir)?.store;
235
+ if (!s) return writtenRecordStore(dir, estate, binary);
236
+ if (s.kind === "local") return { kind: "local", dir: resolve(dir, s.bucket || ".tofu-records"), prefix: s.prefix };
237
+ if (s.kind === "s3" && s.bucket) {
238
+ const written = writtenRecordStore(dir, estate, binary);
239
+ const region = (written?.kind === "s3" ? written.region : undefined) ?? rootBackendAttrs(dir, binary).region;
240
+ return { kind: "s3", bucket: s.bucket, prefix: s.prefix, ...(region ? { region } : {}) };
241
+ }
242
+ return { kind: "unread", name: s.kind };
243
+ }
244
+
245
+ const STORE_FROM: Record<string, string> = {
246
+ record_store: "from its record_store block",
247
+ backend: "derived from its backend block",
248
+ implied: "the local store, since no backend block gives one",
249
+ };
250
+
251
+ const ESTATE_FROM: Record<EstateSource, string> = {
252
+ explicit: "named by its live block",
253
+ tags: "from its tofu-estate tags",
254
+ backend_key: "from the backend key",
255
+ root_path: "from the root's path",
256
+ none: "none resolves",
257
+ };
258
+
259
+ /** The store as one phrase: `s3 bucket "acme" under tofu-records/prod/`. */
260
+ export function storePhrase(s: LiveStore): string {
261
+ if (s.kind === "local") return `the local directory ${s.bucket || ".tofu-records"} under ${s.prefix}`;
262
+ if (s.kind === "azurerm") return `azurerm container ${s.bucket} under ${s.prefix}`;
263
+ if (s.kind === "kubernetes") return `kubernetes namespace ${s.bucket} under ${s.prefix}`;
264
+ return `${s.kind} bucket "${s.bucket}" under ${s.prefix}`;
265
+ }
266
+
267
+ /** A root's setup on one line: where its records go, where that came from, and its estate. */
268
+ export function setupLine(root: string, setup: LiveSetup): string {
269
+ const s = setup.store;
270
+ const where = s ? `records in ${storePhrase(s)} (${STORE_FROM[s.source] ?? s.source}${s.declaredAt ? ` at ${s.declaredAt}` : ""})` : "no record store resolved";
271
+ const estate = setup.estate ? `estate "${setup.estate}" (${ESTATE_FROM[setup.estateSource as EstateSource] ?? setup.estateSource})` : "no estate resolves";
272
+ return `${root}: ${where}; ${estate}${s?.note ? `; ${s.note}` : ""}`;
273
+ }
274
+
275
+ /** The setup's store is the local directory, which is empty on every CI run. */
276
+ export const onLocalStore = (setup: LiveSetup): boolean => setup.store?.kind === "local";
277
+
278
+ /**
279
+ * The bucket core's check reads for a resolved store, or why there is none.
280
+ * `backend` is the root's backend block's string attributes, for the s3
281
+ * region and the azurerm subscription and resource group. s3 takes the
282
+ * region from there or the job, and an emulator's endpoint and keys from the
283
+ * job; gcs an emulator from `STORAGE_EMULATOR_HOST`; azurerm needs the
284
+ * subscription and resource group, from the backend block or
285
+ * `ARM_SUBSCRIPTION_ID`.
286
+ */
287
+ export function bucketTarget(s: LiveStore, backend: Record<string, string> = {}, env: NodeJS.ProcessEnv = process.env): { target: BucketTarget } | { skip: string } {
288
+ if (s.kind === "s3") {
289
+ const region = backend.region ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
290
+ if (!region) return { skip: "no region: set region in the backend block or AWS_REGION" };
291
+ const endpoint = env.AWS_ENDPOINT_URL_S3 ?? env.AWS_ENDPOINT_URL;
292
+ const keys =
293
+ env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY
294
+ ? { accessKeyId: env.AWS_ACCESS_KEY_ID, secretAccessKey: env.AWS_SECRET_ACCESS_KEY, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) }
295
+ : undefined;
296
+ if (endpoint && !keys) return { skip: "AWS_ENDPOINT_URL is set with no AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY" };
297
+ return { target: { store: "s3", bucket: s.bucket, region, ...(endpoint ? { endpoint, credentials: keys } : {}) } as BucketTarget };
298
+ }
299
+ if (s.kind === "gcs") {
300
+ const emulator = env.STORAGE_EMULATOR_HOST;
301
+ return { target: { store: "gcs", bucket: s.bucket, ...(emulator ? { endpoint: /^https?:\/\//.test(emulator) ? emulator : `http://${emulator}`, token: null } : {}) } as BucketTarget };
302
+ }
303
+ if (s.kind === "azurerm") {
304
+ const [account, container] = s.bucket.split("/");
305
+ const subscriptionId = backend.subscription_id ?? env.ARM_SUBSCRIPTION_ID;
306
+ const resourceGroup = backend.resource_group_name;
307
+ if (!account || !container) return { skip: "the store names no storage account and container" };
308
+ 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" };
309
+ return { target: { store: "azblob", subscriptionId, resourceGroup, account, container } as BucketTarget };
310
+ }
311
+ return { skip: `a ${s.kind} store has no bucket to check` };
312
+ }
313
+
314
+ /** What the bucket check said about one root's store. */
315
+ export type BucketOutcome = { checked: BucketReport } | { skipped: string };
316
+
317
+ /**
318
+ * Core's bucket check on a root's resolved store: the settings choudoufu
319
+ * refuses to open the bucket without. It reads only. A store with no bucket,
320
+ * or a check that cannot run, is skipped with the reason; nothing here throws.
321
+ * `check` is injectable for tests.
322
+ */
323
+ export async function checkStoreBucket(
324
+ s: LiveStore,
325
+ backend: Record<string, string> = {},
326
+ env: NodeJS.ProcessEnv = process.env,
327
+ check: (target: BucketTarget, options: { namespaces: string[] }) => Promise<BucketReport> = checkBucket,
328
+ ): Promise<BucketOutcome> {
329
+ if (s.kind === "local") return { skipped: "the local store has no bucket" };
330
+ const t = bucketTarget(s, backend, env);
331
+ if ("skip" in t) return { skipped: t.skip };
332
+ try {
333
+ return { checked: await check(t.target, { namespaces: s.prefix ? [s.prefix] : [] }) };
334
+ } catch (e) {
335
+ return { skipped: `the bucket could not be checked: ${(e as Error).message}` };
336
+ }
337
+ }
338
+
339
+ /** The bucket check's outcome as lines: one for a correct bucket, else one per setting that did not pass, with its fix. */
340
+ export function bucketLines(root: string, outcome: BucketOutcome): string[] {
341
+ if ("skipped" in outcome) return [`${root}: bucket not checked: ${outcome.skipped}`];
342
+ const r = outcome.checked;
343
+ if (r.correct) return [`${root}: bucket ${r.bucket} has every setting choudoufu needs (${r.settings.map((f) => f.setting).join(", ")})`];
344
+ return r.settings
345
+ .filter((f) => f.verdict !== "ok")
346
+ .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}` : ""}`);
347
+ }
@@ -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
+ });