@intentius/chant-lexicon-terraform 0.124.51 → 0.124.54

package/dist/hcl/files.js

@@ -0,0 +1,221 @@
+/**
+ * Which files of a directory are a root's configuration, and how a JSON-syntax
+ * one reads (chant#4457). Every lister in the lexicon asks here, so the parser,
+ * change detection, the backend readers, the report and the rollout pin all
+ * see the same file set for one root.
+ *
+ * The set follows the root's binary. Terraform reads `.tf` and `.tf.json`.
+ * OpenTofu (and choudoufu, which is OpenTofu) also reads `.tofu` and
+ * `.tofu.json`, and when `x.tofu` and `x.tf` both exist it reads `x.tofu`
+ * only (likewise `x.tofu.json` over `x.tf.json`). A binary that is not given
+ * is `terraform`, the config's default.
+ *
+ * `parse.ts` re-exports all of this; the module is separate so the readers
+ * that never parse HCL (`state/backend.ts`, `changed-roots.ts`) do not load
+ * the parser's dependencies.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** The configuration file suffixes Terraform reads. */
+export const TERRAFORM_SUFFIXES = [".tf", ".tf.json"];
+/** The ones OpenTofu reads as well. */
+export const TOFU_SUFFIXES = [".tofu", ".tofu.json"];
+/** Whether a root run by `binary` reads `.tofu` files: `tofu` and `choudoufu` do (by name or path), `terraform` and an unset binary do not. */
+export function readsTofuFiles(binary) {
+    const base = (binary ?? "terraform").split(/[\\/]/).pop() ?? "";
+    return base.startsWith("tofu") || base.startsWith("choudoufu");
+}
+/** Whether `name` is a configuration file in Terraform's JSON syntax (`.tf.json`, `.tofu.json`). */
+export function isJsonConfigFile(name) {
+    return name.endsWith(".tf.json") || name.endsWith(".tofu.json");
+}
+/** Whether `name` is a `.tofu` or `.tofu.json` file. */
+export function isTofuConfigFile(name) {
+    return TOFU_SUFFIXES.some((s) => name.endsWith(s));
+}
+/** Whether `name` is a configuration file a root run by `binary` reads, before the `.tofu`-over-`.tf` rule. */
+export function isConfigFileFor(name, binary) {
+    if (TERRAFORM_SUFFIXES.some((s) => name.endsWith(s)))
+        return true;
+    return readsTofuFiles(binary) && isTofuConfigFile(name);
+}
+/**
+ * The configuration files among `names` a root run by `binary` reads, in
+ * filename order. For a tofu or choudoufu root, `x.tf` is dropped when
+ * `x.tofu` is present and `x.tf.json` when `x.tofu.json` is, which is
+ * OpenTofu's own rule. Names may carry a directory; the rule compares names
+ * in the same directory.
+ */
+export function selectConfigFiles(names, binary) {
+    const kept = [...names].filter((n) => isConfigFileFor(n, binary));
+    const present = new Set(kept);
+    return kept
+        .filter((n) => {
+        if (n.endsWith(".tf"))
+            return !present.has(`${n.slice(0, -".tf".length)}.tofu`);
+        if (n.endsWith(".tf.json"))
+            return !present.has(`${n.slice(0, -".tf.json".length)}.tofu.json`);
+        return true;
+    })
+        .sort();
+}
+/**
+ * The configuration files directly under `dir` a root run by `binary` reads,
+ * by name, in filename order. Non-recursive, matching Terraform's module
+ * scoping; directories named like a file are left out. Throws when `dir`
+ * cannot be read.
+ */
+export function listConfigFiles(dir, binary) {
+    const files = readdirSync(dir).filter((n) => {
+        if (!isConfigFileFor(n, binary))
+            return false;
+        try {
+            return statSync(join(dir, n)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+    return selectConfigFiles(files, binary);
+}
+/** {@link listConfigFiles}, empty when `dir` cannot be read. */
+export function listConfigFilesSafe(dir, binary) {
+    try {
+        return listConfigFiles(dir, binary);
+    }
+    catch {
+        return [];
+    }
+}
+const LIFECYCLE = { labels: 0, exprs: ["ignore_changes", "replace_triggered_by"] };
+const RESOURCE_NESTED = {
+    lifecycle: LIFECYCLE,
+    provisioner: { labels: 1, nested: { connection: { labels: 0 } } },
+    connection: { labels: 0 },
+};
+const REFERS = ["provider", "depends_on"];
+const TOP_LEVEL = {
+    terraform: {
+        labels: 0,
+        nested: {
+            backend: { labels: 1 },
+            cloud: { labels: 0, nested: { workspaces: { labels: 0 } } },
+            required_providers: { labels: 0 },
+            provider_meta: { labels: 1 },
+            live: { labels: 0 },
+        },
+    },
+    locals: { labels: 0 },
+    provider: { labels: 1 },
+    module: { labels: 1, exprs: ["depends_on", "providers"] },
+    variable: { labels: 1, nested: { validation: { labels: 0 } }, exprs: ["type"] },
+    output: { labels: 1, nested: { precondition: { labels: 0 } }, exprs: ["depends_on"] },
+    resource: { labels: 2, nested: RESOURCE_NESTED, exprs: REFERS },
+    data: { labels: 2, nested: { lifecycle: LIFECYCLE }, exprs: REFERS },
+    moved: { labels: 0, exprs: ["from", "to"] },
+    import: { labels: 0, exprs: ["to", "provider"] },
+    removed: { labels: 0, nested: { lifecycle: LIFECYCLE, provisioner: RESOURCE_NESTED.provisioner }, exprs: ["from"] },
+    check: { labels: 1, nested: { data: { labels: 2 }, assert: { labels: 0 } } },
+};
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A bare expression string as hcl2json writes the expression: `aws.west` becomes `${aws.west}`; a template is kept. */
+function asExpression(v) {
+    if (typeof v === "string")
+        return v.includes("${") ? v : `\${${v}}`;
+    if (Array.isArray(v))
+        return v.map(asExpression);
+    if (isObject(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, asExpression(x)]));
+    return v;
+}
+/** A JSON body with its `"//"` comment keys dropped (Terraform ignores them), its known nested blocks wrapped and its expression attributes written as hcl2json writes them. */
+function normaliseBody(body, shape) {
+    const out = {};
+    if (!isObject(body))
+        return out;
+    for (const [k, v] of Object.entries(body)) {
+        if (k === "//")
+            continue;
+        const inner = shape.nested?.[k];
+        out[k] = inner ? wrapBlock(v, inner) : shape.exprs?.includes(k) ? asExpression(v) : v;
+    }
+    return out;
+}
+/**
+ * A block in JSON syntax as hcl2json gives the same block in HCL: one object
+ * level per label, then an array of bodies. JSON syntax writes a single body
+ * as an object or several as an array, and allows an array of objects at a
+ * label level to be merged, so both are read.
+ */
+function wrapBlock(value, shape, labels = shape.labels) {
+    if (labels === 0)
+        return (Array.isArray(value) ? value : [value]).filter(isObject).map((b) => normaliseBody(b, shape));
+    const out = {};
+    for (const part of Array.isArray(value) ? value : [value]) {
+        if (!isObject(part))
+            continue;
+        for (const [label, inner] of Object.entries(part)) {
+            if (label === "//")
+                continue;
+            const wrapped = wrapBlock(inner, shape, labels - 1);
+            const had = out[label];
+            if (Array.isArray(had) && Array.isArray(wrapped))
+                out[label] = [...had, ...wrapped];
+            else if (isObject(had) && isObject(wrapped))
+                out[label] = mergeLabelled(had, wrapped);
+            else
+                out[label] = wrapped;
+        }
+    }
+    return out;
+}
+function mergeLabelled(a, b) {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b)) {
+        const had = out[k];
+        if (Array.isArray(had) && Array.isArray(v))
+            out[k] = [...had, ...v];
+        else if (isObject(had) && isObject(v))
+            out[k] = mergeLabelled(had, v);
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * A `.tf.json` or `.tofu.json` document in the tree shape hcl2json gives an
+ * HCL file, so `blocksToEntities` reads both the same way. Top-level keys it
+ * does not know are kept as written. Throws on malformed JSON, as hcl2json
+ * throws on malformed HCL.
+ */
+export function jsonConfigTree(source) {
+    const doc = JSON.parse(source);
+    if (!isObject(doc))
+        throw new Error("a JSON configuration file must hold an object");
+    const out = {};
+    for (const [k, v] of Object.entries(doc)) {
+        if (k === "//")
+            continue;
+        const shape = TOP_LEVEL[k];
+        out[k] = shape ? wrapBlock(v, shape) : v;
+    }
+    return out;
+}
+/**
+ * The bodies of the `live` blocks nested in the `terraform` blocks of a
+ * `.tf.json` or `.tofu.json` document, in the order written (chant#4504).
+ * The fast live readers (`report.ts`'s `estateOfDir`, `op/activities/live-detect.ts`)
+ * read HCL by text and a JSON file through this. Malformed JSON reads as no
+ * `live` block, as those readers treat any file they cannot read.
+ */
+export function jsonLiveBlocks(source) {
+    let tree;
+    try {
+        tree = jsonConfigTree(source);
+    }
+    catch {
+        return [];
+    }
+    const terraform = Array.isArray(tree.terraform) ? tree.terraform : [];
+    return terraform.flatMap((t) => (isObject(t) && Array.isArray(t.live) ? t.live.filter(isObject) : []));
+}

package/dist/hcl/instances.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Instance nodes the declared graph can count from variables, and instance
+ * nodes under expanded module calls (chant #4486).
+ *
+ * `./parse.ts` gives a block its `instanceKeys` when its `count` or
+ * `for_each` is a literal (#4454). This pass runs once a root and its child
+ * modules are parsed and adds two cases that need the whole root:
+ *
+ * - An expansion that reads a variable, `count = var.n`, gets its keys when
+ *   the variable's value is known from the files a plan would read: the
+ *   `variable` block's `default`, then `terraform.tfvars`,
+ *   `terraform.tfvars.json`, `*.auto.tfvars(.json)` in filename order, then
+ *   `terraform.roots.<name>.varFiles`, later over earlier. In a child module
+ *   the value is the call's argument, when it is a literal or a `var.x`
+ *   known in the caller, else the child variable's default when the call
+ *   passes nothing. `TF_CLI_ARGS` is not read, so the declared graph does not
+ *   change with the environment the build runs in.
+ * - A block under a module call that is itself expanded gets one instance
+ *   per module instance (times its own instances), with the module key on
+ *   the call's segment: `estate/module.app[0]/aws_eip.pool[1]`. The entity
+ *   lists those as `instances` (full ids), which core's `withInstanceNodes`
+ *   reads in place of `instanceKeys` (`@intentius/chant/instance-nodes`
+ *   holds the id rule). A module call with a countable expansion gets
+ *   instance nodes of its own, `estate/module.app[0]`.
+ *
+ * The forms read are `var.n`, `length(var.x)`, `var.m` (a map, or a set
+ * variable) for `for_each`, and `toset(var.l)`; since #4489 the same with
+ * `local.<x>` in place of `var.<x>`, where the local's value is a literal or
+ * one of the `var` forms in its scope, and `var.on ? 1 : 0` (any two whole
+ * numbers, and `local.on` too) over a known bool. Anything else, or any
+ * value that is unknown, leaves the block as one node, which is what it
+ * was, and the entity gets an `instanceRollup` saying why (#4489, the codes
+ * in `@intentius/chant/instance-nodes`). `each.value` and `merge()` stay
+ * rolled up by ruling. A block under an expanded call whose own expansion
+ * or whose call's expansion cannot be counted gets no instances at all,
+ * since a partial list would name ids the plan never prints.
+ */
+import { type Declarable } from "@intentius/chant/declarable";
+import type { InstanceRollup } from "@intentius/chant/instance-nodes";
+import { type Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { type BlockBody } from "./parse.js";
+/** A variable's known value, and whether it is declared as a set. */
+interface VarValue {
+    value: unknown;
+    set: boolean;
+}
+/** Variable name to known value, for one module scope. A name that is absent is unknown. */
+type ScopeVars = Map<string, VarValue>;
+/** A scope's known `var` and `local` values (#4489). */
+interface Scope {
+    vars: ScopeVars;
+    locals: ScopeVars;
+}
+export interface ResolveInstancesOptions {
+    /** The root's directory, where its tfvars files sit. */
+    dir: string;
+    /** `terraform.roots.<name>.varFiles`, relative to `dir`. */
+    varFiles?: readonly string[];
+    hcl2json?: Hcl2Json;
+}
+/**
+ * A block's expansion in a scope: its instance keys as Terraform prints them,
+ * `null` when the block is not expanded, or why the keys are not known.
+ */
+export declare function expansionIn(body: BlockBody, scope: Scope): {
+    keys: string[];
+} | {
+    rollup: InstanceRollup;
+} | null;
+/**
+ * The instance keys a block's `count` or `for_each` gives in `vars`, as
+ * Terraform prints them. `null` when the block is not expanded, undefined
+ * when it is and the keys are not known.
+ */
+export declare function instanceKeysIn(body: BlockBody, vars: ScopeVars, locals?: ScopeVars): string[] | null | undefined;
+/**
+ * Add instance nodes the declared graph can count to one root's entities, in
+ * place (#4486). Entities of other roots in the map are left alone.
+ */
+export declare function resolveInstanceNodes(entities: Map<string, Declarable>, root: string, opts: ResolveInstancesOptions): Promise<void>;
+export {};
+//# sourceMappingURL=instances.d.ts.map

package/dist/hcl/instances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../src/hcl/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAsB,MAAM,iCAAiC,CAAC;AAC1F,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EASL,KAAK,SAAS,EAEf,MAAM,SAAS,CAAC;AAiBjB,qEAAqE;AACrE,UAAU,QAAQ;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CACd;AAED,4FAA4F;AAC5F,KAAK,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEvC,wDAAwD;AACxD,UAAU,KAAK;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;CACnB;AAWD,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAqED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,GAAG,IAAI,CAwBjH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,SAAqB,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,CAG3H;AAoDD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAyJf"}