@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/lint/post-synth/tf009.js

@@ -0,0 +1,49 @@
+/**
+ * TF009: a credential-named variable is not marked `sensitive`.
+ *
+ * No tool in #2107's survey checks this. The authority is HashiCorp's own style
+ * guide, whose variables section says plainly: "For sensitive variables, such
+ * as passwords and private keys, set the sensitive parameter to true."
+ *
+ * Without the flag the value is echoed in `terraform plan` and
+ * `terraform apply` output, which means it lands in CI logs, in the pull
+ * request comment a plan bot posts, and in every terminal scrollback. The flag
+ * does not keep the value out of state (nothing does), which is why the
+ * remediation says both things.
+ *
+ * Only the name is read. A variable with no default and no value in the
+ * repository is still flagged, because the finding is about where the value
+ * goes at run time, not about what is committed. That is TF007's question.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { VARIABLE_TYPE } from "../../hcl/parse.js";
+import { isSecretName } from "../secret-shape.js";
+import { blockName, blocksOfType } from "./blocks.js";
+export const tf009 = {
+    id: "TF009",
+    description: "Credential-named variable is not marked sensitive",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfType(ctx, VARIABLE_TYPE)) {
+            const name = blockName(block.address);
+            if (!isSecretName(name))
+                continue;
+            if (block.body.sensitive === true)
+                continue;
+            diagnostics.push({
+                checkId: "TF009",
+                severity: "error",
+                message: `Variable "${name}" is named like a credential but is not marked \`sensitive = true\`, so ` +
+                    "Terraform prints its value in plan and apply output, and from there into CI logs and plan " +
+                    "comments. Add `sensitive = true`, and remember the value is still stored in plaintext in " +
+                    "state either way.",
+                entity: block.key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf010.js

@@ -0,0 +1,40 @@
+/**
+ * TF010: a `variable` declares no `type`.
+ *
+ * Without a type constraint Terraform accepts whatever it is given and infers
+ * the type from the value, so a variable meant to be a list arrives as a
+ * string from a `TF_VAR_` environment variable, or a number arrives as `"3"`
+ * from a tfvars file, and the failure surfaces deep inside a resource
+ * argument rather than at the module boundary where it was introduced.
+ *
+ * A blank `type` counts as absent, matching KICS, which fails a `type` that
+ * trims to empty.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { VARIABLE_TYPE } from "../../hcl/parse.js";
+import { blockName, blocksOfType, isBlank } from "./blocks.js";
+export const tf010 = {
+    id: "TF010",
+    description: "Variable declares no type constraint",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfType(ctx, VARIABLE_TYPE)) {
+            if (!isBlank(block.body.type))
+                continue;
+            diagnostics.push({
+                checkId: "TF010",
+                severity: "info",
+                message: `Variable "${blockName(block.address)}" declares no \`type\`, so Terraform accepts any ` +
+                    "value and infers the type from whatever it is given. Add a type constraint " +
+                    "(`string`, `number`, `bool`, `list(string)`, an `object({...})`) so a wrong value is " +
+                    "rejected at the module boundary.",
+                entity: block.key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf011.js

@@ -0,0 +1,38 @@
+/**
+ * TF011: a `variable` declares no `description`.
+ *
+ * A module's variables are its API. The description is what `terraform-docs`
+ * renders into the README, what the HCP Terraform and Terraform Cloud variable
+ * UI shows next to the input box, and what a caller reads before deciding what
+ * to pass. Without it the only documentation is the variable's name.
+ *
+ * Report-only: this is documentation hygiene, filed the way KICS files it (as
+ * INFO) and the way tflint files it (in the `all` preset, not `recommended`).
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { VARIABLE_TYPE } from "../../hcl/parse.js";
+import { blockName, blocksOfType, isBlank } from "./blocks.js";
+export const tf011 = {
+    id: "TF011",
+    description: "Variable declares no description",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfType(ctx, VARIABLE_TYPE)) {
+            if (!isBlank(block.body.description))
+                continue;
+            diagnostics.push({
+                checkId: "TF011",
+                severity: "info",
+                message: `Variable "${blockName(block.address)}" declares no \`description\`, so the module's ` +
+                    "generated documentation and the variable prompt have nothing to show but the name. Add a " +
+                    "description saying what the value is for and what a valid one looks like.",
+                entity: block.key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf012.js

@@ -0,0 +1,36 @@
+/**
+ * TF012: an `output` declares no `description`.
+ *
+ * The other half of a module's API. An output is what a caller wires into the
+ * next module, and the description is the only place to say what the value
+ * actually is (an id or an ARN, a full URL or a bare hostname) and whether it
+ * is stable enough to depend on.
+ *
+ * Report-only, for the same reason TF011 is.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { OUTPUT_TYPE } from "../../hcl/parse.js";
+import { blockName, blocksOfType, isBlank } from "./blocks.js";
+export const tf012 = {
+    id: "TF012",
+    description: "Output declares no description",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfType(ctx, OUTPUT_TYPE)) {
+            if (!isBlank(block.body.description))
+                continue;
+            diagnostics.push({
+                checkId: "TF012",
+                severity: "info",
+                message: `Output "${blockName(block.address)}" declares no \`description\`. Outputs are a module's ` +
+                    "public interface, so say what the value is and what a caller can rely on it for.",
+                entity: block.key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf013.js

@@ -0,0 +1,53 @@
+/**
+ * TF013: `lifecycle { ignore_changes = all }`.
+ *
+ * `all` tells Terraform to ignore drift on every attribute of the resource
+ * after it is created. Nothing about that resource is ever reconciled again:
+ * a manual console edit, a deleted security-group rule, a downgraded instance
+ * class, all of it plans clean forever. It is also silent, because a plan that
+ * finds nothing looks exactly like a plan that was told to look at nothing.
+ *
+ * That is the observe half of chant's lifecycle switched off, so this is
+ * merge-worthy rather than hygiene. A list of specific attributes is fine and
+ * is not reported: ignoring `tags` an external tool writes is a real need, and
+ * naming them is what makes the intent auditable.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { DATA_TYPE, RESOURCE_TYPE } from "../../hcl/parse.js";
+import { blocksOfTypes, nestedBodies } from "./blocks.js";
+/**
+ * `ignore_changes = all` parses to the string `"${all}"`: hcl2json renders the
+ * bare keyword as an expression template. A list of attributes parses to an
+ * array, so an array is only a match if `all` is the whole of it.
+ */
+function ignoresEverything(value) {
+    if (value === "${all}")
+        return true;
+    return Array.isArray(value) && value.length === 1 && value[0] === "${all}";
+}
+export const tf013 = {
+    id: "TF013",
+    description: "lifecycle ignore_changes is set to all",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfTypes(ctx, [RESOURCE_TYPE, DATA_TYPE])) {
+            for (const lifecycle of nestedBodies(block.body, "lifecycle")) {
+                if (!ignoresEverything(lifecycle.ignore_changes))
+                    continue;
+                diagnostics.push({
+                    checkId: "TF013",
+                    severity: "warning",
+                    message: `"${block.address}" sets \`ignore_changes = all\`, so Terraform stops reconciling every ` +
+                        "attribute of the resource after it is created. Drift becomes invisible: a manual change " +
+                        "in the console plans clean forever. List the specific attributes to ignore instead.",
+                    entity: block.key,
+                    lexicon: "terraform",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf014.js

@@ -0,0 +1,61 @@
+/**
+ * TF014: a `provider` block inside a child module that configures anything.
+ *
+ * Scope: child modules only. A `provider` block in the ROOT module is where
+ * providers are supposed to be configured, and TF008 is what checks its
+ * contents.
+ *
+ * A child module that configures its own provider takes the decision away
+ * from its caller: the caller can no longer point the module at a different
+ * region, account or endpoint, and two calls of the module in one root cannot
+ * differ. Worse, Terraform cannot remove a module whose provider is declared
+ * inside it, because destroying the resources needs a provider configuration
+ * that the removal itself deletes. That is the "Provider configuration not
+ * present" failure that leaves a root unable to plan.
+ *
+ * The one legal form is a provider block that declares only `alias`, which
+ * names a slot the caller fills through `providers = { aws.replica =
+ * aws.west }`. That is a declaration, not a configuration, so a block whose
+ * body has nothing but `alias` is not reported. Everything else is: a
+ * `region`, a `profile`, an `assume_role` block, and `version` too, which has
+ * been deprecated in favour of `required_providers` since Terraform 0.13.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { PROVIDER_TYPE } from "../../hcl/parse.js";
+import { isChildScoped } from "./scope.js";
+/** Everything in a provider body that is not the `alias` slot declaration. */
+function configuredKeys(body) {
+    return Object.keys(body).filter((key) => key !== "alias");
+}
+export const tf014 = {
+    id: "TF014",
+    description: "Child module configures a provider block",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [key, entity] of ctx.entities) {
+            if (entity.entityType !== PROVIDER_TYPE || !isResourceDeclarable(entity))
+                continue;
+            if (!isChildScoped(entity))
+                continue;
+            const props = entity.props;
+            const body = (typeof props.body === "object" && props.body !== null ? props.body : {});
+            const configured = configuredKeys(body);
+            if (configured.length === 0)
+                continue;
+            const address = typeof props.address === "string" ? props.address : key;
+            diagnostics.push({
+                checkId: "TF014",
+                severity: "warning",
+                message: `Child module block "${address}" configures a provider (${configured.sort().join(", ")}). ` +
+                    "A module that configures its own provider cannot be pointed at another region or account by " +
+                    "its caller, cannot be called twice with different settings, and cannot be removed, since " +
+                    "destroying its resources needs the provider configuration the removal deletes. Configure the " +
+                    "provider in the root module and pass it in with `providers = { ... }`, leaving at most an " +
+                    "`alias`-only block here.",
+                entity: key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf015.js

@@ -0,0 +1,62 @@
+/**
+ * TF015: a `backend` or `cloud` block inside a child module.
+ *
+ * Scope: child modules only. This is TF001's mirror image. TF001 wants a root
+ * module to declare a REMOTE backend, because a root without one keeps its
+ * state on local disk. A child module must declare neither: state belongs to
+ * the root,
+ * one state per root however many modules it calls, and Terraform says so
+ * directly, "A backend block can only appear in the root module" and the
+ * same for `cloud`. Depending on the version, the block is ignored with a
+ * warning or the root refuses to initialize, and either way the block is a
+ * claim about where state lives that the module does not get to make.
+ *
+ * The usual cause is a directory that used to be a root module and became a
+ * child when someone factored it out, with its `terraform` block carried
+ * along. The rest of that block is fine to keep: `required_version` and
+ * `required_providers` are meaningful in a child module and are not reported
+ * here.
+ *
+ * Label-blind on purpose (#2218). TF001 had to start reading the backend
+ * block's type label, since `local` is the state placement it warns about
+ * rather than a cure for it. Nothing of the sort applies here: what a child
+ * module may not do is name a backend at all, `local` included, and
+ * Terraform's own refusal ("A backend block can only appear in the root
+ * module") does not read the label either. `hasBlock` is the right test, and
+ * the `positive` fixture's child declares `backend "local"` for that reason.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { TERRAFORM_TYPE } from "../../hcl/parse.js";
+import { hasBlock } from "./tf001.js";
+import { isChildScoped } from "./scope.js";
+export const tf015 = {
+    id: "TF015",
+    description: "Child module declares a backend or cloud block",
+    check(ctx) {
+        const diagnostics = [];
+        for (const [key, entity] of ctx.entities) {
+            if (entity.entityType !== TERRAFORM_TYPE || !isResourceDeclarable(entity))
+                continue;
+            if (!isChildScoped(entity))
+                continue;
+            const props = entity.props;
+            const body = (typeof props.body === "object" && props.body !== null ? props.body : {});
+            const backend = hasBlock(body, "backend");
+            const cloud = hasBlock(body, "cloud");
+            if (!backend && !cloud)
+                continue;
+            const blockKind = backend ? "backend" : "cloud";
+            diagnostics.push({
+                checkId: "TF015",
+                severity: "warning",
+                message: `A child module's terraform block declares a ${blockKind} block. Only a root module may: ` +
+                    "state belongs to the root, one state file for every module it calls, so this block is either " +
+                    `ignored with a warning or refused at init. Delete the ${blockKind} block and leave the state ` +
+                    "configuration to the root module that calls this one.",
+                entity: key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf016.js

@@ -0,0 +1,66 @@
+/**
+ * TF016: an attribute whose whole value is one quoted interpolation,
+ * `x = "${var.y}"`, the pre-0.12 style Terraform deprecated in 2019.
+ *
+ * The quotes buy nothing and cost readability: the expression is already an
+ * expression, and wrapping it in a template makes every value in the file look
+ * like a string whether it is one or not, which hides the actual type of an
+ * argument that takes a list or a bool.
+ *
+ * This is the one rule in the family that reads the block's SOURCE rather than
+ * its parsed body, and it has to. `@cdktn/hcl2json` renders both `x = var.y`
+ * and `x = "${var.y}"` as the string `"${var.y}"`, so a check over the parse
+ * cannot tell the deprecated form from the idiomatic one and would report every
+ * reference in the root. The quotes only survive in the text, so the text is
+ * what is scanned, one pass per file, through the same
+ * `interpolationOnlyLine` the deterministic fix uses, so the finding and the
+ * patch can never disagree.
+ *
+ * Out of reach, and deliberately not guessed at: tflint also reports the
+ * deprecated interpolation inside an object KEY (`"${var.k}" = "value"`).
+ * That is a different line shape and its fix is not a simple unquote, so this
+ * rule leaves it alone rather than emit a diff it cannot justify.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { interpolationOnlyLine } from "@intentius/chant/audit/proof";
+export const tf016 = {
+    id: "TF016",
+    description: "Attribute value is a quoted interpolation of a single expression",
+    check(ctx) {
+        const diagnostics = [];
+        /** `<root>/<file>` to that file's source, so a file is scanned once however many blocks it holds. */
+        const sources = new Map();
+        for (const entity of ctx.entities.values()) {
+            if (entity.lexicon !== "terraform")
+                continue;
+            if (!isResourceDeclarable(entity))
+                continue;
+            const props = entity.props;
+            if (typeof props.source !== "string" || props.source === "")
+                continue;
+            sources.set(`${props.root ?? ""}/${props.file ?? ""}`, props.source);
+        }
+        for (const [key, source] of sources) {
+            const lines = source.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                const parsed = interpolationOnlyLine(lines[i]);
+                if (!parsed)
+                    continue;
+                diagnostics.push({
+                    checkId: "TF016",
+                    severity: "info",
+                    message: `${key}:${i + 1}: \`${parsed.name}\` wraps a single expression in a template ` +
+                        `("\${${parsed.expr}}"). Terraform deprecated that spelling in 0.12. Write ` +
+                        `\`${parsed.name} = ${parsed.expr}\` instead, so the argument keeps its own type.`,
+                    entity: `${key}:${i + 1}`,
+                    lexicon: "terraform",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf017.js

@@ -0,0 +1,39 @@
+/**
+ * TF017: a `module` block carries `depends_on`.
+ *
+ * `depends_on` on a module applies to every resource inside it, including the
+ * ones that had no reason to wait, so the whole module serializes behind the
+ * named dependency and a plan that could have run in parallel does not. It
+ * also makes the dependency invisible from inside the module, where the
+ * resource that actually needed the ordering lives.
+ *
+ * Passing an attribute of the dependency into a module input creates the same
+ * edge implicitly, only narrower and self-documenting.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { MODULE_TYPE } from "../../hcl/parse.js";
+import { blocksOfType } from "./blocks.js";
+export const tf017 = {
+    id: "TF017",
+    description: "Module block uses depends_on",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfType(ctx, MODULE_TYPE)) {
+            if (!("depends_on" in block.body))
+                continue;
+            diagnostics.push({
+                checkId: "TF017",
+                severity: "info",
+                message: `"${block.address}" uses \`depends_on\`, which orders every resource in the module behind ` +
+                    "the dependency, not just the one that needs it. Pass an attribute of the dependency into " +
+                    "a module input instead, so Terraform derives the edge itself.",
+                entity: block.key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf018.js

@@ -0,0 +1,63 @@
+/**
+ * TF018: an `output` returns a whole resource or data source.
+ *
+ * `value = aws_instance.web` exports every attribute the provider schema
+ * happens to have, which is a much larger promise than the module meant to
+ * make. Consumers reach into whatever they find, the module can no longer
+ * change any of it, and a provider upgrade that adds or renames an attribute
+ * moves the module's public interface without anyone editing it. Sensitive
+ * attributes ride along too.
+ *
+ * A bare `module.x` reference is not reported: a module's outputs are already
+ * a curated surface, which is the property this rule is asking for.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { OUTPUT_TYPE } from "../../hcl/parse.js";
+import { blockName, blocksOfType } from "./blocks.js";
+/** Reference prefixes that are not a managed resource type. */
+const NOT_A_RESOURCE = new Set(["var", "local", "module", "each", "count", "self", "path", "terraform"]);
+/**
+ * Is this value a reference to a whole resource (`type.name`) or a whole data
+ * source (`data.type.name`), with no attribute selected? Anything with a third
+ * segment, an index, or a function call around it has already narrowed the
+ * value down, which is the fix.
+ */
+function wholeBlockReference(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const m = /^\$\{([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)+)\}$/.exec(value);
+    if (!m)
+        return undefined;
+    const parts = m[1].split(".");
+    if (parts[0] === "data")
+        return parts.length === 3 ? m[1] : undefined;
+    if (NOT_A_RESOURCE.has(parts[0]))
+        return undefined;
+    return parts.length === 2 ? m[1] : undefined;
+}
+export const tf018 = {
+    id: "TF018",
+    description: "Output value is a whole resource or data source",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfType(ctx, OUTPUT_TYPE)) {
+            const reference = wholeBlockReference(block.body.value);
+            if (!reference)
+                continue;
+            diagnostics.push({
+                checkId: "TF018",
+                severity: "info",
+                message: `Output "${blockName(block.address)}" returns the whole of \`${reference}\`, so every ` +
+                    "attribute the provider schema has becomes part of this module's public interface, " +
+                    "including the ones a provider upgrade adds later. Return the attribute the caller needs " +
+                    `(\`${reference}.id\`, \`${reference}.arn\`) instead.`,
+                entity: block.key,
+                lexicon: "terraform",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/tf019.js

@@ -0,0 +1,60 @@
+/**
+ * TF019: a meta-argument is explicitly set to its own default, `false`.
+ *
+ * `sensitive` and `ephemeral` on a `variable` or an `output`, `prevent_destroy`
+ * and `create_before_destroy` inside a `lifecycle` block. All four default to
+ * false, so writing it changes nothing and reads as though someone considered
+ * the setting and turned it off, which is exactly the impression a reviewer
+ * should not get from a variable called `password`.
+ *
+ * The first TF rule with a mechanical fix: the remediation is the deletion of
+ * the line, so this ships `fixKind: "deterministic"` and `chant audit` renders
+ * the diff in its quick-wins section. `packages/core/src/audit/proof.ts` owns
+ * the patch, as it does for every other deterministic rule.
+ *
+ * Only a literal `false` counts. `prevent_destroy = var.protect` is a real
+ * decision expressed as a variable, and hcl2json leaves it a `"${var.protect}"`
+ * string rather than a boolean, so it never reaches the comparison.
+ *
+ * Scope: root and child modules alike (#2112). The condition is a property
+ * of the block itself, so a descended module's block is read exactly as a
+ * root's is.
+ */
+import { DATA_TYPE, OUTPUT_TYPE, RESOURCE_TYPE, VARIABLE_TYPE } from "../../hcl/parse.js";
+import { blocksOfTypes, nestedBodies } from "./blocks.js";
+/** Meta-arguments that default to false on a `variable` or an `output`. */
+const BLOCK_ARGS = ["sensitive", "ephemeral"];
+/** Meta-arguments that default to false inside a `lifecycle` block. */
+const LIFECYCLE_ARGS = ["prevent_destroy", "create_before_destroy"];
+function redundant(block, arg, where) {
+    return {
+        checkId: "TF019",
+        severity: "info",
+        message: `"${block.address}" sets \`${arg} = false\`${where}, which is already the default. Declaring a ` +
+            "default reads as a deliberate decision to turn the behaviour off. Delete the line.",
+        entity: `${block.key}.${arg}`,
+        lexicon: "terraform",
+    };
+}
+export const tf019 = {
+    id: "TF019",
+    description: "Meta-argument explicitly set to its default of false",
+    check(ctx) {
+        const diagnostics = [];
+        for (const block of blocksOfTypes(ctx, [VARIABLE_TYPE, OUTPUT_TYPE])) {
+            for (const arg of BLOCK_ARGS) {
+                if (block.body[arg] === false)
+                    diagnostics.push(redundant(block, arg, ""));
+            }
+        }
+        for (const block of blocksOfTypes(ctx, [RESOURCE_TYPE, DATA_TYPE])) {
+            for (const lifecycle of nestedBodies(block.body, "lifecycle")) {
+                for (const arg of LIFECYCLE_ARGS) {
+                    if (lifecycle[arg] === false)
+                        diagnostics.push(redundant(block, arg, " in its `lifecycle` block"));
+                }
+            }
+        }
+        return diagnostics;
+    },
+};