@intentius/chant-lexicon-terraform 0.58.0 → 0.60.0

package/src/lint/audit.test.ts

@@ -1,12 +1,15 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { copyFileSync, mkdtempSync, rmSync } from "node:fs";
+import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { describe, expect, test } from "vitest";
-import { auditFiles, type ChecksProvider, type EntitiesProvider } from "@intentius/chant/audit/core";
+import { auditFiles, CROSS_FILE, type AuditFinding, type ChecksProvider, type EntitiesProvider } from "@intentius/chant/audit/core";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
 import { collectCandidates, discoverByDetection, type DetectPlugin } from "@intentius/chant/audit/discover";
 import { auditTerraformState } from "@intentius/chant/audit/terraform-state";
 import { terraformPlugin } from "../plugin";
+import { AUDIT_ROOT_NAME } from "../hcl/parse";
+import { renderTerraformRoots } from "../hcl/roots";
 import { postSynthChecks } from "./post-synth";
 
 /**
@@ -39,10 +42,24 @@ describe("chant audit against a discovered terraform root module", () => {
     expect(tf001[0]!.lexicon).toBe("terraform");
   });
 
-  test("reports nothing for the with-backend root", async () => {
+  // #2218: `backend "local"` is the local backend named rather than fallen
+  // back into, so it is the same finding as no backend at all. The audit path
+  // gets its own case because it parses joined file content rather than a
+  // directory, and the label has to survive that parse too.
+  test('reports TF001 for a root whose only backend is `backend "local"`', async () => {
     const inputs = discoverByDetection(join(fixtures, "with-backend"), [terraformDetectPlugin]);
     expect(inputs).toHaveLength(1);
 
+    const findings = await auditFiles(inputs, { checksProvider, entitiesProvider });
+    const tf001 = findings.filter((f) => f.checkId === "TF001");
+    expect(tf001).toHaveLength(1);
+    expect(tf001[0]!.message).toContain('the backend it declares is `backend "local"`');
+  });
+
+  test("reports nothing for the remote-backend root", async () => {
+    const inputs = discoverByDetection(join(fixtures, "remote-backend"), [terraformDetectPlugin]);
+    expect(inputs).toHaveLength(1);
+
     const findings = await auditFiles(inputs, { checksProvider, entitiesProvider });
     expect(findings.filter((f) => f.checkId === "TF001")).toHaveLength(0);
   });
@@ -82,3 +99,154 @@ describe("TF023: Terraform state committed to the repository", () => {
     expect(terraformPlugin.auditCatalog?.()).not.toHaveProperty("TF023");
   });
 });
+
+/**
+ * #2217: `chant audit` used to hand the plugin one directory's joined text and
+ * no directory, so the parse stopped at the root module's own files and every
+ * discovered directory parsed under the same fixed scope name. A root and its
+ * `modules/*` then merged into one entity map, which produced a finding keyed
+ * `<scope>/<address>#2` against the file `(cross-file)` and left the two rules
+ * about child modules (TF014, TF015) with no child to see. These run the real
+ * discovery and the real audit over the tree fixtures those rules were written
+ * for.
+ */
+describe("chant audit descends a root module's local modules (#2217)", () => {
+  const treeFixtures = join(dirname(fileURLToPath(import.meta.url)), "post-synth", "fixtures");
+
+  async function audit(dir: string): Promise<AuditFinding[]> {
+    return auditFiles(discoverByDetection(dir, [terraformDetectPlugin]), { checksProvider, entitiesProvider });
+  }
+
+  test("a directory the root calls as a module is not audited as a root of its own", () => {
+    const inputs = discoverByDetection(join(treeFixtures, "TF014", "positive"), [terraformDetectPlugin]);
+    expect(inputs.map((i) => i.path)).toEqual(["."]);
+    expect(inputs[0]!.dir).toBe(join(treeFixtures, "TF014", "positive"));
+  });
+
+  test("TF014 fires on the positive fixture, named by its call chain", async () => {
+    const findings = await audit(join(treeFixtures, "TF014", "positive"));
+    const tf014 = findings.filter((f) => f.checkId === "TF014");
+    expect(tf014).toHaveLength(1);
+    expect(tf014[0]!.entity).toBe("audit-root/module.cdn/provider.aws");
+    expect(tf014[0]!.message).toContain("Callers: audit-root -> module.cdn (main.tf:13).");
+    expect(tf014[0]!.file).toBe(".");
+  });
+
+  test("nothing is attributed to a synthetic cross-file entity any more", async () => {
+    const findings = await audit(join(treeFixtures, "TF014", "positive"));
+    expect(findings.map((f) => f.file)).not.toContain(CROSS_FILE);
+    expect(findings.filter((f) => /#\d+$/.test(f.entity ?? ""))).toEqual([]);
+    // The root's own provider block is still the root's: TF002 reports it
+    // against the root scope, not against a merge of the two directories.
+    const tf002 = findings.filter((f) => f.checkId === "TF002");
+    expect(tf002.map((f) => f.entity)).toEqual(["audit-root/provider.aws"]);
+  });
+
+  test("TF014 says nothing about the negative fixture's alias-only block", async () => {
+    const findings = await audit(join(treeFixtures, "TF014", "negative"));
+    expect(findings.filter((f) => f.checkId === "TF014")).toEqual([]);
+    expect(findings.map((f) => f.file)).not.toContain(CROSS_FILE);
+  });
+
+  test("TF015 fires on a child module that declares a backend", async () => {
+    const findings = await audit(join(treeFixtures, "TF015", "positive"));
+    expect(findings.map((f) => `${f.checkId} ${f.entity}`)).toEqual(["TF015 audit-root/module.cdn/terraform"]);
+    expect(findings[0]!.message).toContain("Callers: audit-root -> module.cdn");
+  });
+
+  test("TF015 leaves a child's required_version and required_providers alone", async () => {
+    expect(await audit(join(treeFixtures, "TF015", "negative"))).toEqual([]);
+  });
+
+  test("TF001 stays root-only: the child module without a backend is not reported", async () => {
+    const findings = await audit(join(treeFixtures, "TF014", "positive"));
+    expect(findings.filter((f) => f.checkId === "TF001")).toEqual([]);
+  });
+
+  test("two roots in one repository are two scopes, each named after its directory", async () => {
+    const repo = mkdtempSync(join(tmpdir(), "chant-2217-"));
+    for (const env of ["prod", "dev"]) {
+      mkdirSync(join(repo, "envs", env), { recursive: true });
+      writeFileSync(join(repo, "envs", env, "main.tf"), 'terraform {\n  required_version = ">= 1.5.0"\n}\n');
+    }
+    const findings = await audit(repo);
+    rmSync(repo, { recursive: true, force: true });
+
+    const tf001 = findings.filter((f) => f.checkId === "TF001");
+    expect(tf001.map((f) => f.missing?.scope).sort()).toEqual(["envs.dev", "envs.prod"]);
+    expect(tf001.map((f) => f.file).sort()).toEqual(["envs/dev", "envs/prod"]);
+    expect(findings.map((f) => f.file)).not.toContain(CROSS_FILE);
+  });
+});
+
+/**
+ * The regression net for #2217: for every fixture root in the family, the
+ * verdict `chant audit` reaches through real discovery is the verdict
+ * `chant build` reaches through `renderTerraformRoots`. The two paths parse
+ * the same directories with the same checks, so any rule whose behaviour
+ * depends on scope (every module-descent rule, and every root-only rule that
+ * must NOT follow one) is pinned on both paths at once.
+ *
+ * The build side renders with no `binary`, so a `live` fixture (TF024 to
+ * TF026) is stock on both sides: the audit path does not detect live mode
+ * (#2103), and this asserts the two agree, not that either sees an estate.
+ */
+describe("every fixture root gets the same verdict from chant audit as from chant build (#2217)", () => {
+  const fixtureRoot = join(dirname(fileURLToPath(import.meta.url)), "post-synth", "fixtures");
+
+  function verdictOf(findings: Array<{ checkId: string; entity?: string }>): string[] {
+    return findings.map((f) => `${f.checkId} ${f.entity ?? ""}`).sort();
+  }
+
+  async function buildVerdict(dir: string): Promise<string[]> {
+    const { entities, warnings } = await renderTerraformRoots({
+      projectRoot: dir,
+      roots: { [AUDIT_ROOT_NAME]: { dir } },
+    });
+    const ctx = {
+      outputs: new Map(),
+      entities,
+      buildResult: { outputs: new Map(), entities, warnings, errors: [], sourceFileCount: entities.size },
+    } as unknown as PostSynthContext;
+    return verdictOf((terraformPlugin.postSynthChecks?.() ?? []).flatMap((check) => check.check(ctx)));
+  }
+
+  async function auditVerdict(dir: string): Promise<string[]> {
+    const inputs = discoverByDetection(dir, [terraformDetectPlugin]);
+    return verdictOf(await auditFiles(inputs, { checksProvider, entitiesProvider }));
+  }
+
+  /** Every fixture case: a `<id>/<case>/` tree as it stands, and a `<id>/<case>.tf` copied into a directory of its own. */
+  function cases(): Array<{ name: string; materialize: (into: string) => string }> {
+    const out: Array<{ name: string; materialize: (into: string) => string }> = [];
+    for (const id of readdirSync(fixtureRoot).filter((e) => statSync(join(fixtureRoot, e)).isDirectory()).sort()) {
+      for (const entry of readdirSync(join(fixtureRoot, id)).sort()) {
+        const full = join(fixtureRoot, id, entry);
+        if (statSync(full).isDirectory()) {
+          out.push({ name: `${id}/${entry}`, materialize: () => full });
+        } else if (entry.endsWith(".tf")) {
+          out.push({
+            name: `${id}/${entry}`,
+            materialize: (into) => {
+              copyFileSync(full, join(into, entry));
+              return into;
+            },
+          });
+        }
+      }
+    }
+    return out;
+  }
+
+  for (const { name, materialize } of cases()) {
+    test(name, async () => {
+      const scratch = mkdtempSync(join(tmpdir(), "chant-2217-fx-"));
+      const dir = materialize(scratch);
+      try {
+        expect(await auditVerdict(dir)).toEqual(await buildVerdict(dir));
+      } finally {
+        rmSync(scratch, { recursive: true, force: true });
+      }
+    });
+  }
+});

package/src/lint/post-synth/fixtures/TF001/negative-cloud.tf

@@ -0,0 +1,28 @@
+# Terraform Cloud / HCP holds the state, so there is no terraform.tfstate on
+# the machine that runs the plan. `cloud {}` counts as remote for TF001.
+terraform {
+  required_version = ">= 1.5.0"
+
+  cloud {
+    organization = "acme"
+
+    workspaces {
+      name = "app"
+    }
+  }
+
+  required_providers {
+    null = {
+      source  = "hashicorp/null"
+      version = "~> 3.2"
+    }
+  }
+}
+
+provider "null" {}
+
+resource "null_resource" "first" {
+  triggers = {
+    name = "first"
+  }
+}

package/src/lint/post-synth/fixtures/TF001/negative.tf

@@ -1,8 +1,10 @@
 terraform {
   required_version = ">= 1.5.0"
 
-  backend "local" {
-    path = "terraform.tfstate"
+  backend "s3" {
+    bucket = "tfstate"
+    key    = "app/terraform.tfstate"
+    region = "us-east-1"
   }
 
   required_providers {

package/src/lint/post-synth/fixtures/TF001/positive-local.tf

@@ -0,0 +1,31 @@
+# `backend "local"` is the local backend asked for by name: the same
+# terraform.tfstate in the working directory a root with no backend block
+# falls back to. TF001 reports it for that reason (#2218).
+terraform {
+  required_version = ">= 1.5.0"
+
+  backend "local" {
+    path = "terraform.tfstate"
+  }
+
+  required_providers {
+    null = {
+      source  = "hashicorp/null"
+      version = "~> 3.2"
+    }
+  }
+}
+
+provider "null" {}
+
+resource "null_resource" "first" {
+  triggers = {
+    name = "first"
+  }
+}
+
+resource "null_resource" "second" {
+  triggers = {
+    name = "second"
+  }
+}

package/src/lint/post-synth/fixtures/TF014/negative/main.tf

@@ -1,8 +1,8 @@
 terraform {
   required_version = ">= 1.5.0"
 
-  backend "local" {
-    path = "terraform.tfstate"
+  backend "s3" {
+    bucket = "tfstate"
   }
 }
 

package/src/lint/post-synth/fixtures/TF014/positive/main.tf

@@ -1,8 +1,8 @@
 terraform {
   required_version = ">= 1.5.0"
 
-  backend "local" {
-    path = "terraform.tfstate"
+  backend "s3" {
+    bucket = "tfstate"
   }
 }
 

package/src/lint/post-synth/fixtures/TF020/scoped/main.tf

@@ -5,8 +5,8 @@
 terraform {
   required_version = ">= 1.5.0"
 
-  backend "local" {
-    path = "terraform.tfstate"
+  backend "s3" {
+    bucket = "tfstate"
   }
 }
 

package/src/lint/post-synth/fixtures/TF027/live-default/main.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/fixtures/TF027/live-untagged-delete/main.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+
+    policy {
+      undeclared_untagged = "delete"
+    }
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/fixtures/TF027/live-untagged-delete-scoped/main.tf

@@ -0,0 +1,17 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+
+    scope {
+      region = "us-east-1"
+    }
+
+    policy {
+      undeclared_untagged = "delete"
+    }
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/fixtures/TF027/live-untagged-report/main.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+
+    policy {
+      undeclared_untagged = "report"
+    }
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/fixtures/TF028/live/main.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/fixtures/TF028/stock/main.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  backend "s3" {
+    bucket = "tfstate"
+    key    = "fixture"
+  }
+}
+
+resource "null_resource" "first" {}

package/src/lint/post-synth/index.ts

@@ -25,6 +25,8 @@ import { tf022 } from "./tf022";
 import { tf024 } from "./tf024";
 import { tf025 } from "./tf025";
 import { tf026 } from "./tf026";
+import { tf027 } from "./tf027";
+import { tf028 } from "./tf028";
 
 export const postSynthChecks: PostSynthCheck[] = [
   tf001,
@@ -52,4 +54,6 @@ export const postSynthChecks: PostSynthCheck[] = [
   tf024,
   tf025,
   tf026,
+  tf027,
+  tf028,
 ];

package/src/lint/post-synth/live-refusals-config-format.test.ts

@@ -0,0 +1,143 @@
+/**
+ * The two live-root refusals against both config file formats (#2216).
+ *
+ * `TerraformApplyOp` and `TerraformWatchOp` each resolve a root's mode
+ * synchronously when they are built, and `resolveRootModeSync` reads a
+ * `chant.config.json` and nothing else: a `chant.config.ts` is project-
+ * authored code it will not evaluate. Every project in this repository is on
+ * a `chant.config.ts`, so a refusal that lives only in a composite has never
+ * fired for anyone. TF027 and TF028 read the mode the build stamps onto the
+ * parsed HCL instead, which is the same either way, and these tests
+ * materialise one project in each format to prove it.
+ *
+ * The build path here is the plugin's own `buildRoots` hook (what `chant
+ * build` calls to turn `terraform.roots` into entities) followed by the
+ * checks the plugin contributes, so the entities under test are the ones a
+ * real build produces rather than a hand-assembled map.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { terraformPlugin } from "../../plugin";
+import { TerraformApplyOp } from "../../composites/terraform-apply-op";
+import { TerraformWatchOp } from "../../composites/terraform-watch-op";
+
+const UNTAGGED_DELETE_ROOT = `terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "prod-estate"
+
+    policy {
+      undeclared_untagged = "delete"
+    }
+  }
+}
+
+resource "null_resource" "first" {}
+`;
+
+const LIVE_ROOT = `terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "prod-estate"
+  }
+}
+
+resource "null_resource" "first" {}
+`;
+
+const CONFIG = {
+  lexicons: ["terraform"],
+  terraform: { binary: "choudoufu", roots: { estate: { dir: "./estate" } } },
+};
+
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+/** A project whose one root is `mainTf`, its config written in `format`. */
+function project(format: "ts" | "json", mainTf: string): string {
+  const dir = mkdtempSync(join(tmpdir(), `chant-tf-2216-${format}-`));
+  dirs.push(dir);
+  mkdirSync(join(dir, "estate"), { recursive: true });
+  writeFileSync(join(dir, "estate", "main.tf"), mainTf);
+  writeFileSync(
+    join(dir, `chant.config.${format}`),
+    format === "json"
+      ? JSON.stringify(CONFIG, null, 2)
+      : `import type { ChantConfig } from "@intentius/chant/config";\n\nexport default ${JSON.stringify(CONFIG, null, 2)} satisfies ChantConfig;\n`,
+  );
+  return dir;
+}
+
+/** `chant build`'s own path: the plugin's `buildRoots`, then the checks it contributes. */
+async function checkProject(dir: string, ops: Map<string, Declarable> = new Map()): Promise<PostSynthDiagnostic[]> {
+  const { entities } = await terraformPlugin.buildRoots!({ projectRoot: dir, config: CONFIG, entities: new Map() });
+  for (const [name, op] of ops) entities.set(name, op);
+  const ctx = { outputs: new Map(), entities } as unknown as PostSynthContext;
+  return (terraformPlugin.postSynthChecks?.() ?? []).flatMap((check) => check.check(ctx));
+}
+
+describe('TF027 fires on undeclared_untagged = "delete" whatever the config format (#2216)', () => {
+  for (const format of ["ts", "json"] as const) {
+    test(`chant.config.${format}: the build reports the root and the setting`, async () => {
+      const diags = await checkProject(project(format, UNTAGGED_DELETE_ROOT));
+      const tf027 = diags.filter((d) => d.checkId === "TF027");
+      expect(tf027).toHaveLength(1);
+      expect(tf027[0].severity).toBe("error");
+      expect(tf027[0].message).toContain('Root module "estate"');
+      expect(tf027[0].message).toContain('undeclared_untagged = "delete"');
+    });
+  }
+
+  test("the same project with no such policy setting is clean", async () => {
+    const diags = await checkProject(project("ts", LIVE_ROOT));
+    expect(diags.filter((d) => d.checkId === "TF027")).toEqual([]);
+  });
+
+  test("the composite's own refusal fires only on the format it can read, which is why the check exists", () => {
+    const json = project("json", UNTAGGED_DELETE_ROOT);
+    expect(() => TerraformApplyOp({ name: "estate-apply", root: "estate", cwd: json })).toThrow(
+      /undeclared_untagged = "delete"/,
+    );
+
+    const ts = project("ts", UNTAGGED_DELETE_ROOT);
+    expect(() => TerraformApplyOp({ name: "estate-apply", root: "estate", cwd: ts })).not.toThrow();
+  });
+});
+
+describe("TF028 reports a stock-mode watch Op on a live root whatever the config format (#2216)", () => {
+  test("chant.config.ts: the composite builds, and the build reports the Op", async () => {
+    const dir = project("ts", LIVE_ROOT);
+    const { op } = TerraformWatchOp({ name: "estate-watch", root: "estate", cwd: dir });
+    const diags = await checkProject(dir, new Map([["estate-watch", op as unknown as Declarable]]));
+    const tf028 = diags.filter((d) => d.checkId === "TF028");
+    expect(tf028).toHaveLength(1);
+    expect(tf028[0].message).toContain('Op "estate-watch"');
+    expect(tf028[0].message).toContain('root module "estate"');
+  });
+
+  test("chant.config.json: the composite refuses before there is an Op to check", () => {
+    const dir = project("json", LIVE_ROOT);
+    expect(() => TerraformWatchOp({ name: "estate-watch", root: "estate", cwd: dir })).toThrow(
+      /runs choudoufu with a declared estate/,
+    );
+  });
+
+  test("live: true on the same root is clean in both formats", async () => {
+    for (const format of ["ts", "json"] as const) {
+      const dir = project(format, LIVE_ROOT);
+      const { op } = TerraformWatchOp({ name: "estate-watch", root: "estate", live: true, cwd: dir });
+      const diags = await checkProject(dir, new Map([["estate-watch", op as unknown as Declarable]]));
+      expect(diags.filter((d) => d.checkId === "TF028")).toEqual([]);
+    }
+  });
+});

package/src/lint/post-synth/module-rules.test.ts

@@ -72,7 +72,7 @@ describe("TF001 still fires only on roots (#2112)", () => {
 
   it("still reports a root that has none, descent or no descent", async () => {
     const ctx = await loadTreeFixture("TF020", "scoped", "app");
-    expect(tf001.check(ctx)).toEqual([]); // this root has a local backend block
+    expect(tf001.check(ctx)).toEqual([]); // this root has a remote backend block
 
     const bare = await loadFixture("TF001", "positive", "app");
     expect(tf001.check(bare)).toHaveLength(1);

package/src/lint/post-synth/post-synth.test.ts

@@ -1,16 +1,16 @@
 import { describe, expect, test } from "vitest";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
-import { tf001 } from "./tf001";
+import { backendTypes, hasRemoteBackend, tf001 } from "./tf001";
 import { loadFixture } from "./fixtures/load";
 import { TERRAFORM_TYPE, terraformEntity } from "../../hcl/parse";
 
 /**
  * The local context builder for the edge cases below that are about the
  * *collection* (several roots or several blocks sharing one root), not about
- * one root's parsed shape, which is what real HCL fixtures represent. The two
- * headline cases (a backendless root, a root with a backend) go through
- * `fixtures/TF001/` and `loadFixture` instead; see that module's doc comment
- * for why.
+ * one root's parsed shape, which is what real HCL fixtures represent. The four
+ * headline cases (a backendless root, a `backend "local"` root, a remote
+ * backend, a `cloud` block) go through `fixtures/TF001/` and `loadFixture`
+ * instead; see that module's doc comment for why.
  */
 function makeCtx(entities: Record<string, ReturnType<typeof terraformEntity>>): PostSynthContext {
   return {
@@ -32,14 +32,33 @@ describe("TF001: root module declares no remote backend", () => {
     expect(diags[0].entity).toBe("TF001/terraform");
     expect(diags[0].lexicon).toBe("terraform");
     expect(diags[0].message).toContain("TF001");
+    expect(diags[0].message).toContain("there is no backend block at all");
     expect(diags[0].missing).toEqual({ kind: "backend", scope: "TF001" });
   });
 
-  test("passes a root with a backend block", async () => {
+  // #2218: the check reads the backend block's type label, so the local
+  // backend is the same finding whether it is fallen back into or asked for
+  // by name, and the message says which one it found.
+  test('flags a root whose backend is `backend "local"`', async () => {
+    const diags = tf001.check(await loadFixture("TF001", "positive-local"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("TF001");
+    expect(diags[0].entity).toBe("TF001/terraform");
+    expect(diags[0].message).toContain('the backend it declares is `backend "local"`');
+    expect(diags[0].message).not.toContain("no backend block");
+    expect(diags[0].missing).toEqual({ kind: "backend", scope: "TF001" });
+  });
+
+  test("passes a root with a remote backend block", async () => {
     const diags = tf001.check(await loadFixture("TF001", "negative"));
     expect(diags).toHaveLength(0);
   });
 
+  test("passes a root whose cloud block is the whole state configuration", async () => {
+    const diags = tf001.check(await loadFixture("TF001", "negative-cloud"));
+    expect(diags).toHaveLength(0);
+  });
+
   test("passes a root using Terraform Cloud's cloud block", () => {
     const diags = tf001.check(
       makeCtx({
@@ -91,4 +110,43 @@ describe("TF001: root module declares no remote backend", () => {
     const diags = tf001.check(makeCtx({ "app/terraform": terraformBlock("app", { backend: {} }) }));
     expect(diags).toHaveLength(1);
   });
+
+  test('flags a hand-built body carrying `backend "local"`', () => {
+    const diags = tf001.check(
+      makeCtx({
+        "app/terraform": terraformBlock("app", { backend: { local: [{ path: "terraform.tfstate" }] } }),
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('the backend it declares is `backend "local"`');
+  });
+});
+
+/**
+ * The label read itself (#2218). hcl2json nests a labelled block one level
+ * deeper than an unlabelled one, and the type only survives the parse as a
+ * key of that inner object, so the shape is worth pinning down apart from the
+ * check that reads it.
+ */
+describe("backendTypes / hasRemoteBackend", () => {
+  test("reads the type label out of the nested object hcl2json builds", () => {
+    expect(backendTypes({ backend: { local: [{ path: "terraform.tfstate" }] } })).toEqual(["local"]);
+    expect(backendTypes({ backend: { s3: [{ bucket: "tfstate" }] } })).toEqual(["s3"]);
+  });
+
+  test("has no labels to read when there is no backend block, or a malformed one", () => {
+    expect(backendTypes({})).toEqual([]);
+    expect(backendTypes({ backend: [{ bucket: "tfstate" }] })).toEqual([]);
+    expect(backendTypes({ backend: "s3" })).toEqual([]);
+  });
+
+  test("counts every backend but `local` as remote, and counts `cloud`", () => {
+    expect(hasRemoteBackend({ backend: { local: [{}] } })).toBe(false);
+    expect(hasRemoteBackend({})).toBe(false);
+    expect(hasRemoteBackend({ backend: { s3: [{}] } })).toBe(true);
+    expect(hasRemoteBackend({ backend: { gcs: [{}] } })).toBe(true);
+    expect(hasRemoteBackend({ backend: { azurerm: [{}] } })).toBe(true);
+    expect(hasRemoteBackend({ backend: { http: [{}] } })).toBe(true);
+    expect(hasRemoteBackend({ cloud: [{ organization: "acme" }] })).toBe(true);
+  });
 });