@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/hcl/value.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from "vitest";
+import { attr } from "./value";
+import type { BlockBody } from "./parse";
+
+describe("attr(): the value envelope over a parsed block body (chant #2113)", () => {
+  test("absent: the key is not present at all", () => {
+    const body: BlockBody = {};
+    expect(attr(body, "bucket")).toEqual({ kind: "absent", raw: undefined });
+  });
+
+  test("absent: null is treated the same as a missing key", () => {
+    const body: BlockBody = { bucket: null };
+    expect(attr(body, "bucket")).toEqual({ kind: "absent", raw: null });
+  });
+
+  test("literal: a plain string with no interpolation", () => {
+    const body: BlockBody = { bucket: "my-bucket" };
+    expect(attr(body, "bucket")).toEqual({ kind: "literal", value: "my-bucket", raw: "my-bucket" });
+  });
+
+  test("literal: a number", () => {
+    const body: BlockBody = { count: 3 };
+    expect(attr(body, "count")).toEqual({ kind: "literal", value: 3, raw: 3 });
+  });
+
+  test("literal: a boolean", () => {
+    const body: BlockBody = { enabled: false };
+    expect(attr(body, "enabled")).toEqual({ kind: "literal", value: false, raw: false });
+  });
+
+  test("literal: an array (also how hcl2json encodes a nested block under the same key)", () => {
+    const body: BlockBody = { backend: [{ s3: [{ bucket: "tfstate" }] }] };
+    const a = attr(body, "backend");
+    expect(a.kind).toBe("literal");
+    expect(a.value).toEqual([{ s3: [{ bucket: "tfstate" }] }]);
+    expect(a.raw).toBe(a.value);
+  });
+
+  test("literal: an object", () => {
+    const body: BlockBody = { tags: { team: "infra" } };
+    expect(attr(body, "tags")).toEqual({ kind: "literal", value: { team: "infra" }, raw: { team: "infra" } });
+  });
+
+  test("reference: the whole string is one interpolation", () => {
+    const body: BlockBody = { bucket: "${aws_s3_bucket.foo.id}" };
+    expect(attr(body, "bucket")).toEqual({ kind: "reference", refs: ["aws_s3_bucket.foo.id"], raw: "${aws_s3_bucket.foo.id}" });
+  });
+
+  test("reference: a bare variable reference", () => {
+    const body: BlockBody = { region: "${var.region}" };
+    expect(attr(body, "region")).toEqual({ kind: "reference", refs: ["var.region"], raw: "${var.region}" });
+  });
+
+  test("reference: a function call still counts as one whole-string reference", () => {
+    const body: BlockBody = { name: "${lower(var.name)}" };
+    expect(attr(body, "name")).toEqual({ kind: "reference", refs: ["lower(var.name)"], raw: "${lower(var.name)}" });
+  });
+
+  test("template: interpolation mixed with literal text", () => {
+    const body: BlockBody = { name: "prefix-${var.env}-suffix" };
+    expect(attr(body, "name")).toEqual({ kind: "template", refs: ["var.env"], raw: "prefix-${var.env}-suffix" });
+  });
+
+  test("template: two interpolations in one string, both captured in source order", () => {
+    const body: BlockBody = { name: "${var.a}-${var.b}" };
+    expect(attr(body, "name")).toEqual({ kind: "template", refs: ["var.a", "var.b"], raw: "${var.a}-${var.b}" });
+  });
+
+  test("literal: a string that merely contains a bare $ with no interpolation", () => {
+    const body: BlockBody = { price: "$5" };
+    expect(attr(body, "price")).toEqual({ kind: "literal", value: "$5", raw: "$5" });
+  });
+});

package/src/hcl/value.ts

@@ -0,0 +1,106 @@
+/**
+ * A value envelope over a parsed block body (chant #2113).
+ *
+ * Every TF post-synth check reads `BlockBody` (`./parse.ts`), raw
+ * `@cdktf/hcl2json` output, and re-derives, by hand, whether an attribute is
+ * a plain literal, a reference/expression, or absent. tflint's OPA ruleset
+ * hands a policy `{value, unknown, sensitive, ephemeral, range}` per
+ * attribute so a check reads that uniformly instead of re-deriving it
+ * (`tflint-ruleset-opa`'s `docs/functions.md`, cited in the #2107 survey).
+ * `attr()` is the equivalent for chant's static string-based body.
+ *
+ * The shape here is narrower than tflint's for one structural reason.
+ * hcl2json converts HCL to plain JSON with no evaluation and no position
+ * data. There is no live Terraform graph behind this parse, so there is no
+ * `unknown` (this runs over source, not a plan), and no `sensitive`/
+ * `ephemeral` flag (those live on a `variable` block's own attributes, not on
+ * every attribute that happens to reference one; a check that cares reads
+ * the referenced variable's declaration itself). `range` is the one field
+ * tflint's envelope carries that this cannot. hcl2json's own output is bare
+ * values, JSON-round-tripped from HCL, with no line/column/byte-range
+ * attached anywhere in the tree, so there is nothing for `attr()` to read a
+ * position from. (#2111 adds a `props.line` to the *entity*, from a separate
+ * text-based mechanism this file does not touch and is not a substitute for
+ * per-attribute ranges. See that issue for how it gets a line at all.)
+ */
+
+import type { BlockBody } from "./parse";
+
+/** What kind of value an attribute holds, once template interpolation is accounted for. */
+export type AttrKind = "literal" | "reference" | "template" | "absent";
+
+/**
+ * The value envelope `attr()` returns for one attribute of a block body.
+ *
+ * `raw` is always the untouched `body[name]` (or `undefined` when absent),
+ * so a caller that needs the original hcl2json value for a case this
+ * envelope doesn't model can still reach it without a second lookup.
+ */
+export interface AttrValue {
+  kind: AttrKind;
+  /**
+   * The attribute's value when `kind` is `"literal"`: a string, number,
+   * boolean, array or object, verbatim from hcl2json. Absent for every other
+   * kind (a reference/template's "value" is not known statically).
+   */
+  value?: unknown;
+  /**
+   * The expression(s) found inside `${...}` for `"reference"` and
+   * `"template"`: one entry for `"reference"` (the whole interpolation),
+   * one per `${...}` span in source order for `"template"`. Absent for
+   * `"literal"`/`"absent"`.
+   */
+  refs?: string[];
+  /** The untouched `body[name]`, regardless of `kind`. `undefined` when absent. */
+  raw: unknown;
+}
+
+/**
+ * Every `${...}` span within a string, in source order. One level of nested
+ * `{...}` is tolerated (an object constructor or a map-typed function argument
+ * inside the interpolation), which is as far as a regex can go without
+ * becoming a brace-counting parser. `attr()` below decides `"reference"` vs
+ * `"template"` from how many spans this finds and whether the one span (if
+ * there is exactly one) consumes the whole string, not from a second,
+ * separately-anchored pattern, so the two checks can't disagree about what
+ * counts as an interpolation.
+ */
+const INTERPOLATION_SPANS = /\$\{([^{}]*(?:\{[^{}]*\}[^{}]*)*)\}/g;
+
+/**
+ * Read one attribute of a parsed block body as a value envelope.
+ *
+ * - `"absent"`: `name` is not a key of `body` at all (or is `undefined`/`null`).
+ * - `"reference"`: the value is a string that is nothing but one
+ *   `${...}` interpolation (`"${aws_s3_bucket.foo.id}"`, `"${var.x}"`,
+ *   `"${lower(var.x)}"`; a function call counts, since the whole value is
+ *   still one expression, not a literal). `refs` carries that one expression.
+ * - `"template"`: the value is a string with `${...}` interpolation mixed
+ *   with literal text (`"prefix-${var.x}-suffix"`, or two interpolations in
+ *   one string). `refs` carries every span found, in source order.
+ * - `"literal"`: anything else. A plain string with no interpolation, a
+ *   number, a boolean, an array, or an object (which is how hcl2json encodes
+ *   a nested block under the same key a caller might ask `attr()` about, so
+ *   a nested block reads as `kind: "literal"` with `value` holding its body
+ *   or bodies array). See `hasBlock()` in `../lint/post-synth/tf001.ts`,
+ *   which is exactly that case.
+ *
+ * A malformed `${` with no matching `}` is not specially detected; it falls
+ * through to `"literal"` (no complete span found), matching hcl2json's own
+ * behavior of passing such text through as a plain string.
+ */
+export function attr(body: BlockBody, name: string): AttrValue {
+  const raw = body[name];
+  if (raw === undefined || raw === null) return { kind: "absent", raw };
+
+  if (typeof raw === "string") {
+    const spans = [...raw.matchAll(INTERPOLATION_SPANS)];
+    if (spans.length === 0) return { kind: "literal", value: raw, raw };
+
+    const refs = spans.map((m) => m[1].trim());
+    const isWholeString = spans.length === 1 && spans[0].index === 0 && spans[0][0].length === raw.length;
+    return isWholeString ? { kind: "reference", refs, raw } : { kind: "template", refs, raw };
+  }
+
+  return { kind: "literal", value: raw, raw };
+}

package/src/index.ts

@@ -21,9 +21,12 @@ export {
   blocksToEntities,
   parseTerraformRootContent,
   parseTerraformRootDir,
+  readLiveSidecarFile,
   splitBundleContent,
   terraformEntity,
   DATA_TYPE,
+  LIVE_SIDECAR_FILENAME,
+  LIVE_TYPE,
   LOCALS_TYPE,
   MODULE_TYPE,
   OUTPUT_TYPE,
@@ -34,6 +37,8 @@ export {
   type BlockBody,
   type TerraformEntity,
   type TerraformFile,
+  type TerraformRootMode,
+  type TerraformRootModeOptions,
 } from "./hcl/parse";
 
 export { renderTerraformRoots, type TerraformRootsResult } from "./hcl/roots";
@@ -41,7 +46,27 @@ export { renderTerraformRoots, type TerraformRootsResult } from "./hcl/roots";
 // Typed Op step builders (#2086). Same names as the activities they wrap, and
 // like k3s's they are opt-in from the lexicon root — the activities themselves
 // are reached by the registry through `./op/activities`, never from here.
-export { terraformInit, terraformPlan, terraformApply, terraformShow } from "./op/builders";
+export {
+  terraformInit,
+  terraformPlan,
+  terraformApply,
+  terraformShow,
+  choudoufuLivePlan,
+  choudoufuLiveLs,
+  choudoufuLiveCheck,
+  choudoufuAdopt,
+} from "./op/builders";
+
+// The adoption ledger over `live-plan -json`'s document (#2105). Pure, and
+// exported because the ledger's shape is what a project reading an Op's own
+// result is reading.
+export {
+  parseAdoptionCommands,
+  readAdoptionLedger,
+  renderAdoptionLedger,
+  type AdoptionCandidate,
+  type AdoptionLedger,
+} from "./op/adoption";
 
 // The Init/Plan/Gate/Apply composite (#2086).
 export { TerraformApplyOp } from "./composites/terraform-apply-op";
@@ -59,6 +84,11 @@ export type {
   TerraformFindingMode,
 } from "./composites/terraform-watch-op";
 
+// The Check/Ledger/Gate/Adopt composite (#2105): reconcile for a choudoufu
+// estate, and #2089's answer for this backend.
+export { TerraformAdoptOp } from "./composites/terraform-adopt-op";
+export type { TerraformAdoptOpConfig, TerraformAdoptOpResources } from "./composites/terraform-adopt-op";
+
 // Live observation over `terraform show -json` (#2087). The plugin reaches
 // `describeResources` through a dynamic import; the ownership keys are here
 // because `ownershipChannel` declares them eagerly.

package/src/lint/audit-catalog.ts

@@ -4,13 +4,25 @@
  * Every post-synth check needs an entry or it contributes nothing to
  * `chant audit`, silently, and `packages/core/src/audit/catalog.test.ts` fails.
  *
- * TF001 reads the chant model (`ctx.entities`), never emitted output, so
- * `yamlBased` is false. Prior-art lineage lives in ./audit-lineage.ts.
+ * TF001, TF024, TF025 and TF026 all read the chant model (`ctx.entities`),
+ * never emitted output, so `yamlBased` is false for all four. Prior-art
+ * lineage lives in ./audit-lineage.ts.
  */
-import type { RuleMeta } from "@intentius/chant/audit/catalog";
+import type { Authority, RuleMeta } from "@intentius/chant/audit/catalog";
 import { applyLineage } from "@intentius/chant/audit/catalog";
 import { terraformAuditLineage } from "./audit-lineage";
 
+const HASHICORP_STYLE_VARIABLES: Authority = {
+  name: "HashiCorp Terraform style guide — Variables",
+  url: "https://developer.hashicorp.com/terraform/language/style#variables",
+};
+
+// The vendor guides behind TF014, TF015 and TF021 are credited as lineage in
+// ./audit-lineage.ts, not as `authority` here. `authority` is reserved for
+// security rules that fail a merge (packages/core/src/audit/catalog.test.ts
+// holds both halves of that invariant), and these three are correctness and
+// best-practice rules (#2112).
+
 export const terraformAuditCatalog: Record<string, RuleMeta> = {
   TF001: {
     id: "TF001",
@@ -23,6 +35,255 @@ export const terraformAuditCatalog: Record<string, RuleMeta> = {
       "module's terraform block, then `terraform init -migrate-state`.",
     yamlBased: false,
   },
+  TF024: {
+    id: "TF024",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Live root declares a backend or cloud block, which choudoufu refuses",
+    remediation:
+      "Remove the `backend`/`cloud` block from the live root's terraform block; a live root's prior " +
+      "state is a projection rebuilt from the live system every run, so there is no state to store.",
+    yamlBased: false,
+  },
+  TF025: {
+    id: "TF025",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Live root references a non-default terraform.workspace, which choudoufu refuses",
+    remediation:
+      "Remove `workspace` from the root's terraform.roots config, and remove any `terraform.workspace` " +
+      'reference from its HCL; choudoufu refuses any workspace but "default" on a live root.',
+    yamlBased: false,
+  },
+  TF026: {
+    id: "TF026",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: 'Live root declares delete: "never" but its policy leaves undeclared_tagged at "delete"',
+    remediation:
+      'Add undeclared_tagged = "keep" (or "untag" or "report") to the live root\'s policy block, or ' +
+      'change terraform.roots.<name>.delete to "owned-only" or "gated" if an owned orphan should be ' +
+      "deleted after all.",
+    yamlBased: false,
+  },
+  TF002: {
+    id: "TF002",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Provider implied by the root has no required_providers entry",
+    remediation:
+      "Add the provider to the terraform block's `required_providers`, with both `source` and " +
+      "`version` set, so a future provider release can't silently change behavior.",
+    yamlBased: false,
+  },
+  TF003: {
+    id: "TF003",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Root module's terraform block has no required_version",
+    remediation: 'Set `required_version = ">= <lowest supported version>"` in the terraform block.',
+    yamlBased: false,
+  },
+  TF004: {
+    id: "TF004",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Registry-sourced module block has no version",
+    remediation: "Add a `version` constraint to the module block (e.g. `~> 5.0`).",
+    yamlBased: false,
+  },
+  TF005: {
+    id: "TF005",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Git/hg module source is unpinned, or pinned to a mutable ref",
+    remediation: "Pin the module's `?ref=` to a tag or a full commit SHA.",
+    yamlBased: false,
+  },
+  TF006: {
+    id: "TF006",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "security",
+    title: "Default value on a sensitive variable",
+    remediation:
+      "Delete the `default` and require the caller to supply the value at apply time, through a tfvars " +
+      "file kept out of version control, a `TF_VAR_` entry in the environment, or a workspace input.",
+    yamlBased: false,
+  },
+  TF007: {
+    id: "TF007",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "security",
+    title: "Plaintext secret in a variable default or a locals value",
+    remediation:
+      "Remove the literal, mark the variable `sensitive = true`, and read the value from a secret " +
+      "manager data source or an input at apply time, then rotate the credential, which is already " +
+      "in version control history.",
+    yamlBased: false,
+  },
+  TF008: {
+    id: "TF008",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "security",
+    title: "Provider block configures a hardcoded credential",
+    remediation:
+      "Delete the credential from the provider block and let the provider read it from the " +
+      "environment, a shared credentials file, or an OIDC role assumption. Rotate the credential.",
+    yamlBased: false,
+  },
+  TF009: {
+    id: "TF009",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "security",
+    title: "Credential-named variable is not marked sensitive",
+    remediation:
+      "Add `sensitive = true` to the variable so its value is not printed in plan and apply output. " +
+      "The value is still stored in plaintext in state, so keep the state remote and encrypted.",
+    authority: [HASHICORP_STYLE_VARIABLES],
+    yamlBased: false,
+  },
+  TF010: {
+    id: "TF010",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Variable declares no type constraint",
+    remediation: "Add a `type` to the variable (`string`, `number`, `bool`, `list(string)`, `object({...})`).",
+    yamlBased: false,
+  },
+  TF011: {
+    id: "TF011",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Undocumented variable",
+    remediation: "Add a `description` saying what the value is for and what a valid one looks like.",
+    yamlBased: false,
+  },
+  TF012: {
+    id: "TF012",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Undocumented output",
+    remediation: "Write a `description` for the output, covering what the value is and what a caller can rely on it for.",
+    yamlBased: false,
+  },
+  TF013: {
+    id: "TF013",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "lifecycle ignore_changes is set to all",
+    remediation:
+      "Replace `ignore_changes = all` with the list of attributes that genuinely change outside " +
+      "Terraform, so every other attribute is still reconciled.",
+    yamlBased: false,
+  },
+  TF014: {
+    id: "TF014",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Child module configures a provider block",
+    remediation:
+      "Move the provider configuration to the root module and pass it into the module with " +
+      "`providers = { ... }`, leaving at most an `alias`-only block in the module.",
+    yamlBased: false,
+  },
+  TF015: {
+    id: "TF015",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "correctness",
+    title: "Child module declares a backend or cloud block",
+    remediation:
+      "Delete the `backend`/`cloud` block from the child module. State belongs to the root module " +
+      "that calls it, one state for the whole tree.",
+    yamlBased: false,
+  },
+  TF020: {
+    id: "TF020",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Declaration is never referenced in its module scope",
+    remediation:
+      "Delete the variable, local, data source or aliased provider, or reference it where it was " +
+      "meant to be used.",
+    yamlBased: false,
+  },
+  TF021: {
+    id: "TF021",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "count builds instance identities from count.index where for_each is safer",
+    remediation:
+      "Switch to `for_each` over a map or set so each instance is addressed by a stable key, then " +
+      "`terraform state mv` the existing indexed instances onto their new keys.",
+    yamlBased: false,
+  },
+  TF016: {
+    id: "TF016",
+    tier: "report-only",
+    fixKind: "deterministic",
+    category: "best-practice",
+    title: "Attribute value is a quoted interpolation of a single expression",
+    remediation: 'Drop the quotes and the `${}`: write `x = var.y`, not `x = "${var.y}"`.',
+    yamlBased: false,
+  },
+  TF017: {
+    id: "TF017",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Module block uses depends_on",
+    remediation:
+      "Remove `depends_on` from the module call and pass an attribute of the dependency into a module " +
+      "input, so Terraform derives the narrower edge itself.",
+    yamlBased: false,
+  },
+  TF018: {
+    id: "TF018",
+    tier: "report-only",
+    fixKind: "guidance",
+    category: "best-practice",
+    title: "Output value is a whole resource or data source",
+    remediation: "Return the attribute the caller needs (`.id`, `.arn`, `.endpoint`) instead of the whole block.",
+    yamlBased: false,
+  },
+  TF019: {
+    id: "TF019",
+    tier: "report-only",
+    fixKind: "deterministic",
+    category: "best-practice",
+    title: "Meta-argument explicitly set to its default of false",
+    remediation: "Deleting the line is the whole fix. `sensitive`, `ephemeral`, `prevent_destroy` and `create_before_destroy` are false unless set.",
+    yamlBased: false,
+  },
+  TF022: {
+    id: "TF022",
+    tier: "merge-worthy",
+    fixKind: "guidance",
+    category: "security",
+    title: "Credential-named resource attribute holds a plaintext literal",
+    remediation:
+      "Replace the constant with a lookup, either an input the caller supplies or a data source " +
+      "pointed at whatever vault owns the credential, and rotate what was committed.",
+    yamlBased: false,
+  },
 };
 
 // Prior art credits, if any, live beside the rules in ./audit-lineage.ts (see