@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/hcl/parse.ts

@@ -18,14 +18,20 @@
  * changed in `packages/core/package.json` for this.
  */
 
-import { readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadHcl2json, type Hcl2Json } from "@intentius/chant/terraform/parse";
 import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { SuppressionDirective } from "@intentius/chant/lint/suppressions";
+import type { TerraformDeleteMode } from "../config";
+import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
 
 /** A parsed HCL block body, as `@cdktf/hcl2json` encodes it. */
 export type BlockBody = Record<string, unknown>;
 
+/** Whether a root runs under choudoufu with a declared estate (#2103). */
+export type TerraformRootMode = "live" | "state";
+
 /** The entity every block becomes. `props` is what post-synth checks read. */
 export interface TerraformEntity extends Declarable {
   readonly lexicon: "terraform";
@@ -39,7 +45,70 @@ export interface TerraformEntity extends Declarable {
     readonly file: string;
     /** Configured root name this block belongs to. */
     readonly root: string;
+    /**
+     * The chain of `module.<name>` calls that reached this block, outermost
+     * first (chant #2112). Empty or absent on a block declared in the root
+     * module itself; `["module.cdn"]` on a block of the module `./modules/cdn`
+     * called as `cdn` from the root; `["module.cdn", "module.bucket"]` one
+     * level deeper. The same chain is in the entity key, which is
+     * `<root>/module.cdn/<address>` for the first case, so a reader can tell
+     * root scope from child scope from either.
+     *
+     * The names are the CALL names (`module.<label>`), not the directory the
+     * source points at, matching `terraform show -json`'s `child_modules[]`
+     * addresses, choudoufu's marker grammar, and tflint's `Callers:` chain.
+     */
+    readonly callers?: readonly string[];
+    /**
+     * Whether this root is live: `terraform.binary` is `"choudoufu"` and an
+     * estate is declared (a `live` block or an `estate.chdf.hcl` sidecar).
+     * Set on every entity of the root, not just the `Terraform::Live` one, so
+     * a post-synth check or `describeResources()` reads it without
+     * re-parsing (#2103). Absent when the caller supplied no `binary` (the
+     * `chant audit` content path, which has no project config to read).
+     */
+    readonly mode?: TerraformRootMode;
+    /** The declared estate name. Present only when `mode` is `"live"`. */
+    readonly estate?: string;
+    /** `terraform.roots.<name>.workspace`, recorded so TF025 can flag a non-default one on a live root. */
+    readonly workspace?: string;
+    /**
+     * `terraform.roots.<name>.delete` (#2106), recorded so TF026 can check a
+     * live root declaring `"never"` against its `policy` block's
+     * `undeclared_tagged` setting. Present regardless of mode, same as
+     * `workspace`; only a live root's TF026 reads it.
+     */
+    readonly delete?: TerraformDeleteMode;
+    /**
+     * 1-based line the block's header starts on, from a line scan over the
+     * raw source (chant #2111): hcl2json exposes no ranges to read this from
+     * instead (see `../hcl/suppressions.ts`). Undefined when the scan's block
+     * regex didn't recognize the header (unusual formatting); a suppression
+     * comment simply can't anchor to that block then.
+     */
+    readonly line?: number;
+    /**
+     * The raw text of the file this block came from, verbatim.
+     *
+     * Every other field here is post-`hcl2json`, and that parse is lossy in
+     * one way that matters: it renders a bare reference (`value = var.x`) and
+     * a quoted interpolation (`value = "${var.x}"`) as the same string,
+     * `"${var.x}"`. The second is the deprecated pre-0.12 form TF016 reports
+     * and the first is idiomatic, so a check written against `body` alone
+     * would flag every reference in the root. The source text is where the
+     * quotes still exist. Empty when a caller built the entity by hand.
+     */
+    readonly source: string;
   };
+  /**
+   * `# chant-ignore`/`chant-ignore-file`/`chant-ignore-block` directives that
+   * apply to this entity (chant #2111): the ones anchored to its own block,
+   * plus any file-level one. Read generically by
+   * `@intentius/chant/lint/suppressions`'s `entitySuppressions()`; see that
+   * module's doc comment for why this is a plain duck-typed field rather than
+   * a `PostSynthContext` addition.
+   */
+  readonly suppressions?: readonly SuppressionDirective[];
 }
 
 /** `entityType` per block kind. */
@@ -51,6 +120,11 @@ export const MODULE_TYPE = "Terraform::Module";
 export const VARIABLE_TYPE = "Terraform::Variable";
 export const OUTPUT_TYPE = "Terraform::Output";
 export const LOCALS_TYPE = "Terraform::Locals";
+/** A `live { estate = "..." }` block, or an `estate.chdf.hcl` sidecar's content (#2103). */
+export const LIVE_TYPE = "Terraform::Live";
+
+/** The sidecar filename choudoufu reads an estate declaration from when no in-block `live { }` is used. */
+export const LIVE_SIDECAR_FILENAME = "estate.chdf.hcl";
 
 /**
  * Build one entity. Written out rather than run through `createResource`
@@ -66,13 +140,30 @@ export function terraformEntity(
   body: BlockBody,
   file: string,
   root: string,
+  extra?: { mode?: TerraformRootMode; estate?: string; workspace?: string; delete?: TerraformDeleteMode; callers?: readonly string[] },
+  source: string = "",
+  line?: number,
+  suppressions?: readonly SuppressionDirective[],
 ): TerraformEntity {
   return {
     [DECLARABLE_MARKER]: true,
     lexicon: "terraform",
     entityType,
     kind: "resource",
-    props: { address, body, file, root },
+    props: {
+      address,
+      body,
+      file,
+      root,
+      source,
+      line,
+      ...(extra?.mode !== undefined ? { mode: extra.mode } : {}),
+      ...(extra?.estate !== undefined ? { estate: extra.estate } : {}),
+      ...(extra?.workspace !== undefined ? { workspace: extra.workspace } : {}),
+      ...(extra?.delete !== undefined ? { delete: extra.delete } : {}),
+      ...(extra?.callers !== undefined && extra.callers.length > 0 ? { callers: extra.callers } : {}),
+    },
+    suppressions,
   };
 }
 
@@ -115,6 +206,18 @@ export function listTerraformFiles(dir: string): string[] {
     .sort();
 }
 
+/**
+ * Read the `estate.chdf.hcl` sidecar beside `dir`'s `.tf` files, if present.
+ * Sibling to {@link listTerraformFiles}: the sidecar is plain HCL (a bare
+ * `estate = "..."` attribute, no wrapper block) and is never a `.tf` file, so
+ * it falls outside that glob and needs its own read.
+ */
+export function readLiveSidecarFile(dir: string): TerraformFile | undefined {
+  const path = join(dir, LIVE_SIDECAR_FILENAME);
+  if (!existsSync(path)) return undefined;
+  return { name: LIVE_SIDECAR_FILENAME, source: readFileSync(path, "utf-8") };
+}
+
 function asArray(value: unknown): unknown[] {
   return Array.isArray(value) ? value : [];
 }
@@ -125,29 +228,85 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
+/** Every `live { ... }` block nested inside every `terraform { ... }` block of `tree`. */
+function liveBlocksIn(tree: Record<string, unknown>): BlockBody[] {
+  const out: BlockBody[] = [];
+  for (const tfBody of asArray(tree["terraform"])) {
+    const body = asRecord(tfBody);
+    for (const liveBody of asArray(body["live"])) out.push(asRecord(liveBody));
+  }
+  return out;
+}
+
+/**
+ * Options threading the config-level facts a root's mode depends on into the
+ * parse, so `blocksToEntities` can stamp `mode`/`estate`/`workspace` onto
+ * every entity without a second pass over the project config (#2103).
+ */
+export interface TerraformRootModeOptions {
+  /** `terraform.binary`. A root is live only when this is `"choudoufu"` and an estate is declared. */
+  binary?: string;
+  /** `terraform.roots.<name>.workspace`, recorded verbatim regardless of mode. */
+  workspace?: string;
+  /** `terraform.roots.<name>.delete`, recorded verbatim regardless of mode (#2106). */
+  delete?: TerraformDeleteMode;
+}
+
 /**
  * Parse a set of files into entities keyed `<root>/<address>`. Two blocks that
  * genuinely share an address (two `locals` blocks, or the same address in two
  * files of one root) are numbered `~2`, `~3` rather than overwriting.
+ *
+ * Recognises both ways an estate is declared: a `live { }` block nested in a
+ * `terraform { }` block of any file here, and, when `sidecar` is given, the
+ * `estate.chdf.hcl` sidecar's bare `estate = "..."` attribute. Either becomes
+ * a {@link LIVE_TYPE} entity, and the root is live (`mode: "live"`) exactly
+ * when `modeOptions.binary` is `"choudoufu"` and one of the two named an
+ * estate; that verdict, and the estate name when live, is then stamped onto
+ * every entity this call returns, sidecar and in-block declaration alike so
+ * a post-synth check or `describeResources()` reads it without re-parsing.
+ * When both forms are present the sidecar wins, matching choudoufu's own
+ * "the sidecar is the leading one" (choudoufu refuses the combination
+ * outright; this lexicon does not police that here, see TF024/TF025 for
+ * what it does police on a live root).
+ *
+ * `callers` is the module-call chain these files were reached through
+ * (chant #2112), empty for a root module. When it is non-empty the keys
+ * become `<root>/module.<name>/<address>` (one segment per caller) and every
+ * entity carries the chain on `props.callers`. `./descend.ts` is what fills
+ * it in; nothing else should pass it.
  */
 export async function blocksToEntities(
   files: readonly TerraformFile[],
   root: string,
   hcl2json?: Hcl2Json,
+  modeOptions?: TerraformRootModeOptions,
+  sidecar?: TerraformFile,
+  callers: readonly string[] = [],
 ): Promise<Map<string, Declarable>> {
   const parser = hcl2json ?? (await loadHcl2json());
   const entities = new Map<string, Declarable>();
+  const prefix = callers.length > 0 ? `${root}/${callers.join("/")}` : root;
 
-  const add = (entityType: string, address: string, body: unknown, file: string): void => {
+  const add = (entityType: string, address: string, body: unknown, file: TerraformFile, scan: FileScan): void => {
+    const { line, suppressions } = directivesFor(scan, address);
     const entity = terraformEntity(
       entityType,
       address,
       (typeof body === "object" && body !== null ? body : {}) as BlockBody,
-      file,
+      file.name,
       root,
+      {
+        ...(modeOptions?.workspace !== undefined ? { workspace: modeOptions.workspace } : {}),
+        ...(modeOptions?.delete !== undefined ? { delete: modeOptions.delete } : {}),
+        ...(callers.length > 0 ? { callers } : {}),
+      },
+      file.source,
+      line,
+      suppressions,
     );
-    let key = `${root}/${address}`;
-    for (let n = 2; entities.has(key); n++) key = `${root}/${address}~${n}`;
+    let key = `${prefix}/${address}`;
+    for (let n = 2; entities.has(key); n++) key = `${prefix}/${address}~${n}`;
     entities.set(key, entity);
   };
 
@@ -156,9 +315,10 @@ export async function blocksToEntities(
     tree: Record<string, unknown>,
     section: string,
     entityType: string,
-    file: string,
+    file: TerraformFile,
+    scan: FileScan,
   ): void => {
-    for (const body of asArray(tree[section])) add(entityType, section, body, file);
+    for (const body of asArray(tree[section])) add(entityType, section, body, file, scan);
   };
 
   /** `provider`, `module`, `variable`, `output`: one label, so `Record<name, body[]>`. */
@@ -167,10 +327,11 @@ export async function blocksToEntities(
     section: string,
     entityType: string,
     address: (name: string) => string,
-    file: string,
+    file: TerraformFile,
+    scan: FileScan,
   ): void => {
     for (const [name, bodies] of Object.entries(asRecord(tree[section]))) {
-      for (const body of asArray(bodies)) add(entityType, address(name), body, file);
+      for (const body of asArray(bodies)) add(entityType, address(name), body, file, scan);
     }
   };
 
@@ -180,56 +341,117 @@ export async function blocksToEntities(
     section: string,
     entityType: string,
     address: (type: string, name: string) => string,
-    file: string,
+    file: TerraformFile,
+    scan: FileScan,
   ): void => {
     for (const [type, named] of Object.entries(asRecord(tree[section]))) {
       for (const [name, bodies] of Object.entries(asRecord(named))) {
-        for (const body of asArray(bodies)) add(entityType, address(type, name), body, file);
+        for (const body of asArray(bodies)) add(entityType, address(type, name), body, file, scan);
       }
     }
   };
 
   for (const file of files) {
     const tree = (await parser.parse(file.name, file.source)) as Record<string, unknown>;
-    unlabelled(tree, "terraform", TERRAFORM_TYPE, file.name);
-    unlabelled(tree, "locals", LOCALS_TYPE, file.name);
-    oneLabel(tree, "provider", PROVIDER_TYPE, (n) => `provider.${n}`, file.name);
-    oneLabel(tree, "module", MODULE_TYPE, (n) => `module.${n}`, file.name);
-    oneLabel(tree, "variable", VARIABLE_TYPE, (n) => `var.${n}`, file.name);
-    oneLabel(tree, "output", OUTPUT_TYPE, (n) => `output.${n}`, file.name);
-    twoLabels(tree, "resource", RESOURCE_TYPE, (t, n) => `${t}.${n}`, file.name);
-    twoLabels(tree, "data", DATA_TYPE, (t, n) => `data.${t}.${n}`, file.name);
+    const scan = scanSuppressions(file.name, file.source);
+    unlabelled(tree, "terraform", TERRAFORM_TYPE, file, scan);
+    for (const liveBody of liveBlocksIn(tree)) add(LIVE_TYPE, "live", liveBody, file, scan);
+    unlabelled(tree, "locals", LOCALS_TYPE, file, scan);
+    oneLabel(tree, "provider", PROVIDER_TYPE, (n) => `provider.${n}`, file, scan);
+    oneLabel(tree, "module", MODULE_TYPE, (n) => `module.${n}`, file, scan);
+    oneLabel(tree, "variable", VARIABLE_TYPE, (n) => `var.${n}`, file, scan);
+    oneLabel(tree, "output", OUTPUT_TYPE, (n) => `output.${n}`, file, scan);
+    twoLabels(tree, "resource", RESOURCE_TYPE, (t, n) => `${t}.${n}`, file, scan);
+    twoLabels(tree, "data", DATA_TYPE, (t, n) => `data.${t}.${n}`, file, scan);
+  }
+
+  if (sidecar) {
+    const tree = (await parser.parse(sidecar.name, sidecar.source)) as Record<string, unknown>;
+    if (typeof tree["estate"] === "string") add(LIVE_TYPE, "live", tree, sidecar, scanSuppressions(sidecar.name, sidecar.source));
+  }
+
+  // Which of the (at most two) Live entities names the estate, preferring the
+  // sidecar over an in-block declaration when both are present.
+  let estate: string | undefined;
+  for (const entity of entities.values()) {
+    if (entity.entityType !== LIVE_TYPE) continue;
+    const props = (entity as TerraformEntity).props;
+    const name = typeof props.body["estate"] === "string" ? (props.body["estate"] as string) : undefined;
+    if (name === undefined) continue;
+    if (estate === undefined || props.file === LIVE_SIDECAR_FILENAME) estate = name;
+  }
+
+  const mode: TerraformRootMode = modeOptions?.binary === "choudoufu" && estate !== undefined ? "live" : "state";
+  for (const [key, entity] of entities) {
+    const te = entity as TerraformEntity;
+    const stamped: TerraformEntity = {
+      ...te,
+      props: { ...te.props, mode, ...(mode === "live" ? { estate } : {}) },
+    };
+    entities.set(key, stamped);
   }
 
   return entities;
 }
 
 /**
- * Parse a root module directory. Reads every `.tf` directly under `dir`.
- * Throws whatever the parser throws for malformed HCL; `buildRoots()` is where
- * that becomes a warning.
+ * Parse a root module directory. Reads every `.tf` directly under `dir`, plus
+ * the `estate.chdf.hcl` sidecar beside them when present. Throws whatever the
+ * parser throws for malformed HCL; `buildRoots()` is where that becomes a
+ * warning.
  */
 export async function parseTerraformRootDir(
   dir: string,
   root: string,
   hcl2json?: Hcl2Json,
+  modeOptions?: TerraformRootModeOptions,
+  callers: readonly string[] = [],
 ): Promise<Map<string, Declarable>> {
   const files = listTerraformFiles(dir).map((name) => ({
     name,
     source: readFileSync(join(dir, name), "utf-8"),
   }));
-  return blocksToEntities(files, root, hcl2json);
+  // A child module gets no sidecar read: `estate.chdf.hcl` declares the
+  // estate a ROOT runs against, and choudoufu reads it from the root's own
+  // directory only. See `./descend.ts`.
+  const sidecar = callers.length === 0 ? readLiveSidecarFile(dir) : undefined;
+  return blocksToEntities(files, root, hcl2json, modeOptions, sidecar, callers);
 }
 
 /**
  * Parse the joined-file string form `chant audit` produces for a discovered
- * root module (`AuditInput.content`). Unwired for now: #2085's
- * `auditEntities()` is what calls it.
+ * root module (`AuditInput.content`). `auditEntities()` is what calls it; that
+ * hook's single-argument contract carries no project config, so `modeOptions`
+ * is left undefined there and every entity gets `mode: "state"`; the audit
+ * path does not detect live mode (#2103). `modeOptions` exists here mainly for
+ * tests exercising the mode-stamping behaviour directly against inline HCL,
+ * the same way `parseTerraformRootDir`'s callers exercise it against files.
  */
 export async function parseTerraformRootContent(
   content: string,
   root: string,
   hcl2json?: Hcl2Json,
+  modeOptions?: TerraformRootModeOptions,
 ): Promise<Map<string, Declarable>> {
-  return blocksToEntities(splitBundleContent(content), root, hcl2json);
+  return blocksToEntities(splitBundleContent(content), root, hcl2json, modeOptions);
+}
+
+/**
+ * The module scope an entity key names: the part before the address.
+ *
+ * `"app/aws_s3_bucket.assets"` is scope `"app"` (the root module);
+ * `"app/module.cdn/aws_s3_bucket.assets"` is scope `"app/module.cdn"`. Keys
+ * are built here (see {@link blocksToEntities}), so the split lives here too:
+ * the reference index (`./references.ts`) and the module-scoped checks read
+ * scopes through it rather than re-deriving the key shape.
+ */
+export function scopeOfKey(key: string): string {
+  const slash = key.lastIndexOf("/");
+  return slash === -1 ? "" : key.slice(0, slash);
+}
+
+/** The `module.<name>` chain in an entity key, outermost first. Empty for a root-module block. */
+export function callersOfKey(key: string): string[] {
+  const parts = key.split("/");
+  return parts.length <= 2 ? [] : parts.slice(1, -1);
 }

package/src/hcl/references.test.ts

@@ -0,0 +1,116 @@
+/**
+ * The reference index (chant #2112), against
+ * `src/__fixtures__/references/main.tf`, which carries every form the index
+ * collects exactly once.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { blocksToEntities } from "./parse";
+import {
+  buildReferenceIndex,
+  collectReferences,
+  isReferenced,
+  providerReference,
+  referencesInBody,
+  referencesTo,
+  type ReferenceIndex,
+} from "./references";
+
+const FIXTURE = join(dirname(fileURLToPath(import.meta.url)), "..", "__fixtures__", "references", "main.tf");
+
+let entities: Map<string, Declarable>;
+let index: ReferenceIndex;
+
+beforeAll(async () => {
+  entities = await blocksToEntities([{ name: "main.tf", source: readFileSync(FIXTURE, "utf-8") }], "app");
+  index = buildReferenceIndex(entities);
+});
+
+describe("collectReferences", () => {
+  it("reads each reference form out of one expression string", () => {
+    expect(collectReferences("${var.region}").sort()).toEqual(["var.region"]);
+    expect(collectReferences("${local.tags}").sort()).toEqual(["local.tags"]);
+    expect(collectReferences("${data.aws_ami.ubuntu.id}").sort()).toEqual(["data.aws_ami.ubuntu"]);
+    expect(collectReferences("${module.cdn.url}").sort()).toEqual(["module.cdn"]);
+  });
+
+  it("does not read a data source as a bare type reference", () => {
+    expect(collectReferences("${data.aws_ami.ubuntu.id}")).not.toContain("var.aws_ami");
+  });
+
+  it("reads several references out of one interpolated string", () => {
+    expect(collectReferences("assets-${var.region}-${local.suffix}").sort()).toEqual([
+      "local.suffix",
+      "var.region",
+    ]);
+  });
+
+  it("finds nothing in a string that names nothing", () => {
+    expect(collectReferences("a plain value")).toEqual([]);
+  });
+});
+
+describe("providerReference", () => {
+  it("reads the provider meta-argument's own form", () => {
+    expect(providerReference("${aws.replica}")).toBe("provider.aws.replica");
+    expect(providerReference("aws.replica")).toBe("provider.aws.replica");
+  });
+
+  it("is not fooled by an expression that merely contains a dot", () => {
+    expect(providerReference("${var.region}.example.com")).toBeUndefined();
+    expect(providerReference(42)).toBeUndefined();
+  });
+});
+
+describe("referencesInBody", () => {
+  it("reads a provider reference from the meta-argument and from a providers map", () => {
+    expect(referencesInBody({ provider: "${aws.replica}" })).toContain("provider.aws.replica");
+    expect(referencesInBody({ providers: { aws: "${aws.replica}" } })).toContain("provider.aws.replica");
+  });
+
+  it("descends through nested blocks", () => {
+    expect(referencesInBody({ tags: { Name: "${var.name}" } })).toContain("var.name");
+  });
+});
+
+describe("buildReferenceIndex over the fixture", () => {
+  it("collects every reference form in the root scope", () => {
+    const refs = [...(index.scopes.get("app") ?? new Map()).keys()].sort();
+    expect(refs).toEqual([
+      "data.aws_ami.ubuntu",
+      "local.bucket_name",
+      "local.tags",
+      "module.cdn",
+      "provider.aws.replica",
+      "var.region",
+      "var.subnets",
+    ]);
+  });
+
+  it("records which block each reference came from", () => {
+    expect([...referencesTo(index, "app", "module.cdn")]).toEqual(["app/output.cdn_url"]);
+    expect([...referencesTo(index, "app", "data.aws_ami.ubuntu")]).toEqual(["app/aws_instance.web"]);
+  });
+
+  it("counts a reference from the declaration's own body only when asked to", () => {
+    // `local.bucket_name` is built from `var.region` inside the same `locals`
+    // block, and read again by `aws_s3_bucket.replica`.
+    expect([...referencesTo(index, "app", "var.region")]).toEqual(["app/locals"]);
+    expect(isReferenced(index, "app", "var.region")).toBe(true);
+    expect(isReferenced(index, "app", "var.region", "app/locals")).toBe(false);
+  });
+
+  it("knows nothing about a token nobody names", () => {
+    expect(isReferenced(index, "app", "var.absent")).toBe(false);
+    expect(referencesTo(index, "app", "var.absent").size).toBe(0);
+  });
+
+  it("keeps scopes apart", () => {
+    expect(index.scopes.has("app")).toBe(true);
+    expect(isReferenced(index, "app/module.cdn", "var.region")).toBe(false);
+  });
+});