@intentius/chant-lexicon-terraform 0.58.0 → 0.59.0

package/src/op/activities/choudoufu.test.ts

@@ -164,6 +164,18 @@ describe("choudoufuLivePlanCommand (#2103)", () => {
     );
   });
 
+  // choudoufu refuses `-estate` beside a `live` block or an `estate.chdf.hcl`
+  // sidecar, and since v0.14.0 it does not need one there (choudoufu #894, PR
+  // 915). Omitting the option is how a declared root is run.
+  test("no estate emits no -estate, for a root that names its own (choudoufu #894)", () => {
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", json: true })).toBe(
+      "choudoufu live-plan -detailed-exitcode -json",
+    );
+    expect(choudoufuLivePlanCommand({ binary: "choudoufu", json: false, noColor: true })).toBe(
+      "choudoufu live-plan -detailed-exitcode -no-color",
+    );
+  });
+
   test("-adoption-only and -no-color ride the human form (#2105)", () => {
     expect(
       choudoufuLivePlanCommand({ binary: "choudoufu", estate: "prod", json: false, adoptionOnly: true, noColor: true }),
@@ -265,10 +277,10 @@ describe("isOlderVersion / parseChoudoufuVersion (#2103)", () => {
 // ── The version check, wired into every activity via resolveRoot ───────────
 
 describe("choudoufu version check (#2103)", () => {
-  test("refuses a binary older than the floor, which the approval artifact moved to v0.13.0", async () => {
+  test("refuses a binary older than the floor, which the -json document moved to v0.14.0", async () => {
     const dir = liveProject();
-    replies.push({ match: "version", reply: { stdout: "choudoufu v0.12.0 (based on OpenTofu v1.13.0)\n", stderr: "" } });
-    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).rejects.toThrow(/older than.*v0\.13\.0/);
+    replies.push({ match: "version", reply: { stdout: "choudoufu v0.13.0 (based on OpenTofu v1.13.0)\n", stderr: "" } });
+    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).rejects.toThrow(/older than.*v0\.14\.0/);
   });
 
   test("passes at exactly the minimum version", async () => {
@@ -398,7 +410,7 @@ describe("choudoufuLivePlan (#2103)", () => {
   test("exit 0: no drift, the document is captured and written, the human plan comes from a second call", async () => {
     const dir = liveProject();
     replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: DOC, stderr: "" } });
-    replies.push({ match: "live-plan -detailed-exitcode -no-color -estate", reply: { stdout: "No changes.\n", stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "No changes.\n", stderr: "" } });
 
     const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
     expect(result.drift).toBe(false);
@@ -415,9 +427,12 @@ describe("choudoufuLivePlan (#2103)", () => {
     const written = readFileSync(join(result.dir, DEFAULT_LIVE_PLAN_DOCUMENT_FILE), "utf-8");
     expect(JSON.parse(written)).toEqual(JSON.parse(DOC));
 
+    // The root names its own estate, so neither call carries `-estate`:
+    // choudoufu refuses the flag beside a declaration, and since v0.14.0 it
+    // reads the declared name itself (choudoufu #894, PR 915).
     expect(commandsRun()).toEqual([
-      "choudoufu live-plan -detailed-exitcode -json -estate=prod-networking",
-      "choudoufu live-plan -detailed-exitcode -no-color -estate=prod-networking",
+      "choudoufu live-plan -detailed-exitcode -json",
+      "choudoufu live-plan -detailed-exitcode -no-color",
     ]);
   });
 
@@ -425,7 +440,7 @@ describe("choudoufuLivePlan (#2103)", () => {
     const dir = liveProject();
     replies.push({ match: "live-plan -detailed-exitcode -json", reply: execError(2, "", DOC) });
     replies.push({
-      match: "live-plan -detailed-exitcode -no-color -estate",
+      match: "live-plan -detailed-exitcode -no-color",
       reply: { stdout: "Plan: 2 to add, 0 to change, 1 to destroy.\n", stderr: "" },
     });
 
@@ -448,14 +463,25 @@ describe("choudoufuLivePlan (#2103)", () => {
     );
   });
 
-  test("an explicit estate overrides auto-detection", async () => {
-    const dir = liveProject();
+  test("a root declaring no estate carries the caller's as -estate", async () => {
+    const dir = liveProject({ withLiveBlock: false });
     replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: DOC, stderr: "" } });
-    replies.push({ match: "live-plan -detailed-exitcode -no-color -estate", reply: { stdout: "", stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "", stderr: "" } });
     await choudoufuLivePlan({ root: "estate", cwd: dir, estate: "other-estate" });
     expect(commandsRun()[0]).toContain("-estate=other-estate");
   });
 
+  // The declaration wins on the wire whatever the caller passes, because
+  // choudoufu refuses `-estate` beside one. The result still reports the
+  // estate the document names.
+  test("a root that declares its own estate emits no -estate, even when one is passed", async () => {
+    const dir = liveProject();
+    replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: DOC, stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "", stderr: "" } });
+    await choudoufuLivePlan({ root: "estate", cwd: dir, estate: "other-estate" });
+    expect(commandsRun().every((c) => !c.includes("-estate"))).toBe(true);
+  });
+
   test("no estate anywhere: refused, and the plan itself never runs", async () => {
     const dir = liveProject({ withLiveBlock: false });
     await expect(choudoufuLivePlan({ root: "estate", cwd: dir })).rejects.toThrow(/no estate to run against/);
@@ -494,7 +520,7 @@ describe("choudoufuLivePlan adoption ledger (#2105)", () => {
     const dir = liveProject();
     replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
     replies.push({
-      match: "live-plan -detailed-exitcode -no-color -estate",
+      match: "live-plan -detailed-exitcode -no-color",
       reply: { stdout: "Plan: 1 to add.\n", stderr: "" },
     });
 
@@ -511,7 +537,7 @@ describe("choudoufuLivePlan adoption ledger (#2105)", () => {
     const dir = liveProject();
     replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
     replies.push({
-      match: "live-plan -detailed-exitcode -no-color -estate",
+      match: "live-plan -detailed-exitcode -no-color",
       reply: { stdout: "Plan: 1 to add.\n", stderr: "" },
     });
 
@@ -531,8 +557,8 @@ describe("choudoufuLivePlan adoption ledger (#2105)", () => {
 
     const result = await choudoufuLivePlan({ root: "estate", cwd: dir, adoptionOnly: true });
     expect(commandsRun()).toEqual([
-      "choudoufu live-plan -detailed-exitcode -json -estate=prod-networking",
-      "choudoufu live-plan -detailed-exitcode -adoption-only -no-color -estate=prod-networking",
+      "choudoufu live-plan -detailed-exitcode -json",
+      "choudoufu live-plan -detailed-exitcode -adoption-only -no-color",
     ]);
     expect(result.adoptions[0].command).toBe(
       "aws ec2 create-tags --resources 'vpc-0abc' --tags 'Key=tofu-estate,Value=prod-networking'",
@@ -542,7 +568,7 @@ describe("choudoufuLivePlan adoption ledger (#2105)", () => {
   test("without adoptionOnly a candidate carries the marker values and no command", async () => {
     const dir = liveProject();
     replies.push({ match: "live-plan -detailed-exitcode -json", reply: { stdout: ADOPTABLE, stderr: "" } });
-    replies.push({ match: "live-plan -detailed-exitcode -no-color -estate", reply: { stdout: "", stderr: "" } });
+    replies.push({ match: "live-plan -detailed-exitcode -no-color", reply: { stdout: "", stderr: "" } });
 
     const result = await choudoufuLivePlan({ root: "estate", cwd: dir });
     expect(result.adoptions[0].command).toBeUndefined();
@@ -676,8 +702,14 @@ describe("choudoufuLiveCheck (#2103)", () => {
   });
 });
 
-describe("liveDocumentFrom (choudoufu #894)", () => {
-  test("skips refresh progress lines that precede the document", async () => {
+// Defensive, and no longer describing a live defect: choudoufu v0.14.0 keeps
+// `-json` stdout to the document, so the slice is the identity on every
+// supported binary. These cases pin the behaviour that makes keeping it cheap:
+// a stray writer ahead of the document costs a slice rather than a parse
+// failure, and a stdout with no document at all still reaches `JSON.parse`
+// with its real text.
+describe("liveDocumentFrom (defensive, choudoufu #894 fixed in v0.14.0)", () => {
+  test("skips any line that precedes the document, if a writer ever puts one there", async () => {
     const { liveDocumentFrom } = await import("./terraform");
     const stdout = 'aws_vpc.main: Refreshing state... [id=vpc-1]\naws_subnet.a: Refreshing state...\n{\n  "bound": []\n}\n';
     expect(JSON.parse(liveDocumentFrom(stdout))).toEqual({ bound: [] });

package/src/op/activities/terraform.ts

@@ -77,10 +77,15 @@ export const DEFAULT_LIVE_PLAN_DOCUMENT_FILE = "chant.live-plan.json";
  * ([choudoufu #878](https://github.com/INTENTIUS/choudoufu/issues/878), PR
  * 889): under a live block `plan -out=FILE` is accepted and `apply FILE`
  * re-plans the live system and refuses on a mismatch with exit status 3.
- * {@link terraformApply} depends on that refusal existing, so the floor is
- * the release that shipped it rather than the one before.
+ * v0.14.0 brought the `-json` document on a configuration that names its own
+ * estate ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894),
+ * PR 915), which is the shape every chant live root has: before it,
+ * {@link choudoufuLivePlan} could not produce the document for a real root at
+ * all. {@link terraformApply} depends on the exit-3 refusal and
+ * `describeResources()` and both document-reading Ops depend on the document,
+ * so the floor is the release that shipped the later of the two.
  */
-export const MIN_CHOUDOUFU_VERSION = "0.13.0";
+export const MIN_CHOUDOUFU_VERSION = "0.14.0";
 
 /**
  * choudoufu's own refusal summary for `-out` on the `live-plan -estate`
@@ -480,10 +485,18 @@ export function terraformApplyCommand(opts: { binary: string; planFile: string }
 }
 
 /**
- * `live-plan -detailed-exitcode -json -estate=<estate>`. `-json` is what
+ * `live-plan -detailed-exitcode [-json] [-estate=<estate>]`. `-json` is what
  * prints GitHub issue #788's document instead of the plan; the human render
  * needs a second invocation without it (see {@link choudoufuLivePlan}).
  *
+ * `estate` is omitted exactly when the configuration names its own estate.
+ * choudoufu refuses `-estate` beside a `live` block or an `estate.chdf.hcl`
+ * sidecar ("Estate named by both the live block and -estate"), and since
+ * v0.14.0 it does not need one: the run reads the declared name itself and
+ * prints the same document ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894),
+ * PR 915). The flag is still how a root that declares nothing names an
+ * estate for the run.
+ *
  * `adoptionOnly` makes that second invocation print the adoption ledger and
  * nothing else (GitHub issue #587). It is refused here alongside `json`
  * because choudoufu refuses the pair itself, and a builder that emitted a
@@ -492,7 +505,7 @@ export function terraformApplyCommand(opts: { binary: string; planFile: string }
  */
 export function choudoufuLivePlanCommand(opts: {
   binary: string;
-  estate: string;
+  estate?: string;
   json: boolean;
   adoptionOnly?: boolean;
   noColor?: boolean;
@@ -508,7 +521,7 @@ export function choudoufuLivePlanCommand(opts: {
   if (opts.json) parts.push("-json");
   if (opts.adoptionOnly) parts.push("-adoption-only");
   if (opts.noColor) parts.push("-no-color");
-  parts.push(`-estate=${quoteArg(opts.estate)}`);
+  if (opts.estate !== undefined) parts.push(`-estate=${quoteArg(opts.estate)}`);
   return parts.join(" ");
 }
 
@@ -618,7 +631,7 @@ export function isOlderVersion(version: string, min: string): boolean {
 
 /**
  * Extract the release version from `choudoufu version`'s human-readable
- * output: `"choudoufu v0.12.0 (based on OpenTofu v1.13.0)\non darwin_arm64"`.
+ * output: `"choudoufu v0.13.0 (based on OpenTofu v1.13.0)\non darwin_arm64"`.
  * `choudoufu version -json`'s `terraform_version` field is the wrong number
  * here: it names the upstream OpenTofu base this build forked from, not the
  * choudoufu release itself (`internal/command/views/version.go`), so this
@@ -961,11 +974,19 @@ function resolveEstate(args: { estate?: string }, resolved: ResolvedRoot, activi
  */
 /**
  * The JSON document within a `live-plan -json` stdout: everything from the
- * first line that is a bare `{` to the end. Stock keeps stdout to the
- * document; choudoufu's `-estate` path precedes it with refresh progress
- * lines (choudoufu #894). Returns the input unchanged when no such line
- * exists, so a clean stdout parses as before and a broken one fails in
- * `JSON.parse` with the real text in the error.
+ * first line that is a bare `{` to the end. Returns the input unchanged when
+ * no such line exists.
+ *
+ * Defensive, and kept deliberately. choudoufu v0.14.0 keeps `-json` stdout to
+ * the document on every form of live root, so on a supported binary this
+ * returns its input unchanged and the slice never fires: it was written for
+ * the `-estate` path's refresh progress lines
+ * ([choudoufu #894](https://github.com/INTENTIUS/choudoufu/issues/894), fixed
+ * in PR 915, which routes every human-prose renderer of a `-json` run through
+ * `views.View.StdoutOnStderr()`). What it buys is that a future writer put
+ * back on stdout ahead of the document costs a stale slice rather than a
+ * `JSON.parse` failure, and a stdout carrying no document at all still fails
+ * in `JSON.parse` with the real text in the error.
  */
 export function liveDocumentFrom(stdout: string): string {
   const lines = stdout.split("\n");
@@ -982,10 +1003,14 @@ export async function choudoufuLivePlan(
   const estate = resolveEstate(args, resolved, "choudoufuLivePlan");
   const env = terraformEnvironment(resolved.root);
   const documentPath = args.documentPath ?? DEFAULT_LIVE_PLAN_DOCUMENT_FILE;
+  // A root that declares its own estate is run without `-estate`: choudoufu
+  // refuses the flag beside a declaration and, since v0.14.0, settles the name
+  // from the declaration itself. See {@link choudoufuLivePlanCommand}.
+  const estateFlag: { estate?: string } = resolved.estate === undefined ? { estate } : {};
 
   let drift: boolean;
   let jsonStdout: string;
-  const planCmd = choudoufuLivePlanCommand({ binary, estate, json: true });
+  const planCmd = choudoufuLivePlanCommand({ binary, ...estateFlag, json: true });
   try {
     const { stdout, stderr } = await run(planCmd, dir, env, signal);
     report(stdout, stderr);
@@ -1005,8 +1030,8 @@ export async function choudoufuLivePlan(
     jsonStdout = failure.stdout ?? "";
   }
 
-  // On the `-estate` path choudoufu prints refresh progress to stdout ahead of
-  // the document (choudoufu #894), so parse from the first line that opens it.
+  // Belt and braces: v0.14.0 keeps `-json` stdout to the document, so this is
+  // the identity on a supported binary. See {@link liveDocumentFrom}.
   const document = liveDocumentFrom(jsonStdout);
   const json: unknown = JSON.parse(document);
   // #788's document carries no render of the human plan itself
@@ -1015,19 +1040,32 @@ export async function choudoufuLivePlan(
   // (#2105) changes which report that second read prints, never whether there
   // is one: choudoufu refuses the flag alongside `-json`, so the two reports
   // were always going to be two runs.
-  const textRun = await run(
-    choudoufuLivePlanCommand({
-      binary,
-      estate,
-      json: false,
-      noColor: true,
-      ...(args.adoptionOnly ? { adoptionOnly: true } : {}),
-    }),
-    dir,
-    env,
-    signal,
-  );
-  const text = textRun.stdout;
+  const textCmd = choudoufuLivePlanCommand({
+    binary,
+    ...estateFlag,
+    json: false,
+    noColor: true,
+    ...(args.adoptionOnly ? { adoptionOnly: true } : {}),
+  });
+  // The human render carries `-detailed-exitcode` too, so a plan with changes
+  // comes back as exit 2 on this call exactly as it does on the `-json` one.
+  // Both are success, and the drift answer is already settled above, so exit 2
+  // here yields its stdout rather than throwing; anything else is a failure
+  // with choudoufu's own output attached.
+  let text: string;
+  try {
+    text = (await run(textCmd, dir, env, signal)).stdout;
+  } catch (err) {
+    const failure = err as ExecFailure;
+    if (failure.code !== 2) {
+      const detail = (failure.stderr ?? "").trim() || (failure.stdout ?? "").trim();
+      throw new Error(
+        `${binary} live-plan (human render) failed in ${dir} (exit ${String(failure.code)})` +
+          `${detail ? `\n${detail}` : ""}`,
+      );
+    }
+    text = failure.stdout ?? "";
+  }
 
   writeFileSync(join(dir, documentPath), document);
 
@@ -1050,7 +1088,7 @@ export async function choudoufuLivePlan(
     documentPath,
     estate,
     ...countLivePlanUnowned(json),
-    ...parseChoudoufuPlanSummary(textRun.stdout),
+    ...parseChoudoufuPlanSummary(text),
   };
 }
 

package/src/op/builders.ts

@@ -84,11 +84,13 @@ export const terraformApply = (
 };
 
 /**
- * `choudoufu live-plan -detailed-exitcode -json -estate=<estate>` in the
- * named root, plus the human render. The fully typed twin of the
- * `choudoufuLivePlan` activity (#2103). `opts` is {@link ChoudoufuLivePlanArgs}
- * itself, minus the positional `root`; `estate` is optional, auto-detected
- * from the root's `live` block or `estate.chdf.hcl` sidecar when omitted.
+ * `choudoufu live-plan -detailed-exitcode -json` in the named root, plus the
+ * human render. The fully typed twin of the `choudoufuLivePlan` activity
+ * (#2103). `opts` is {@link ChoudoufuLivePlanArgs} itself, minus the
+ * positional `root`; `estate` is optional, auto-detected from the root's
+ * `live` block or `estate.chdf.hcl` sidecar when omitted, and a root that
+ * declares one is run with no `-estate` at all, which is the only form
+ * choudoufu admits there (choudoufu #894, fixed in v0.14.0).
  * Defaults to the `longInfra` profile: like `terraformPlan`, this reads the
  * live system in full (the estate-wide sweep).
  *

package/src/op/resolve-root-mode.ts

@@ -1,31 +1,45 @@
 /**
  * Best-effort, synchronous read of whether a named `terraform.roots` entry is
  * live: `terraform.binary` is `"choudoufu"` and the root's directory declares
- * an estate — a `live { }` block or an `estate.chdf.hcl` sidecar (#2103).
+ * an estate, either a `live { }` block or an `estate.chdf.hcl` sidecar (#2103).
  *
- * Two callers decide something at build time, before any activity runs, and
- * neither can afford the async work `../op/activities/terraform.ts`'s own
+ * Three callers decide something at build time, before any activity runs, and
+ * none can afford the async work `../op/activities/terraform.ts`'s own
  * `resolveRoot` does (`loadChantConfigUpward`, a full `chant.config.ts`/`.json`
  * walk):
  *
- *   - `TerraformApplyOp` (`../composites/terraform-apply-op.ts`) decides which
- *     phase shape to build — a stock plan-file pairing or a live re-plan-at-
- *     apply shape — before any step is emitted.
+ *   - `TerraformApplyOp` (`../composites/terraform-apply-op.ts`) reads the
+ *     mode to word the Gate phase's approval description, and to refuse a
+ *     root whose `policy` block sets `undeclared_untagged = "delete"`. The
+ *     mode no longer picks a phase shape: #2157 made the live and stock Apply
+ *     steps one step, so both roots build the same phases.
+ *   - `TerraformWatchOp` (`../composites/terraform-watch-op.ts`) cross-checks
+ *     its hand-set `live` flag against the root's real mode and refuses a
+ *     mismatch (#2216).
  *   - TF101 (`../lint/rules/plan-before-apply.ts`) decides whether a
  *     `terraformApply` call it is statically inspecting is exempt from the
  *     plan-file pairing it otherwise enforces.
  *
- * Both run in the build process (`chant build`/`chant lint`) rather than in
- * an activity at run time, so a synchronous read is available, but only the
- * cheap half of it: `findProjectConfig` (`@intentius/chant/project-root`) is a plain, already-
- * synchronous upward filesystem walk, but a `chant.config.ts` is project-
- * authored code, and evaluating it synchronously outside chant's own
- * config-sandbox machinery is more than either caller's best-effort question
+ * All three run in the build process (`chant build`/`chant lint`) rather than
+ * in an activity at run time, so a synchronous read is available, but only the
+ * cheap half of it: `findProjectConfig` (`@intentius/chant/project-root`) is a
+ * plain, already-synchronous upward filesystem walk, but a `chant.config.ts`
+ * is project-authored code, and evaluating it synchronously outside chant's
+ * own config-sandbox machinery is more than any caller's best-effort question
  * is worth. So this reads `chant.config.json` only; a project on a `.ts`
  * config, or with no config discoverable at all, or naming no matching root,
- * resolves to `undefined` — "unknown" reads as "stock" to both callers, which
- * is the conservative direction: TF101 keeps firing, and the composite keeps
- * building the plan-file-carrying shape.
+ * resolves to `undefined`, and "unknown" reads as "stock" to every caller.
+ *
+ * That default is conservative for the two callers that only ever add a
+ * requirement by knowing more: TF101 keeps enforcing the plan-file pairing,
+ * and the watch Op keeps accepting the flag it was given. It is the
+ * permissive direction for the apply Op's policy refusal and for the watch
+ * Op's mismatch, which is why neither refusal is left to this function alone:
+ * TF027 and TF028 (`../lint/post-synth/`) ask the same questions of the
+ * parsed HCL the build already stamped `mode` onto, whatever the config file
+ * is written in, and those checks are the guarantee (#2216). Every project in
+ * this repository is on a `chant.config.ts`, so a refusal that resolves the
+ * mode through this function alone never fires for anyone.
  */
 
 import { existsSync, readFileSync } from "node:fs";

package/src/plugin.test.ts

@@ -337,3 +337,41 @@ describe("parseTerraformRootContent", () => {
     expect([...entities.keys()]).toEqual(["app/locals", "app/locals~2"]);
   });
 });
+
+describe("detectTemplate", () => {
+  const detect = (data: unknown) => terraformPlugin.detectTemplate?.(data) ?? false;
+
+  it("recognises .tf text by its top-level block headers", () => {
+    expect(detect('terraform {\n  required_version = ">= 1.5.0"\n}')).toBe(true);
+    expect(detect('resource "null_resource" "first" {}')).toBe(true);
+    expect(detect('data "aws_ami" "ubuntu" {\n  most_recent = true\n}')).toBe(true);
+    expect(detect('provider "aws" {\n  region = "us-east-1"\n}')).toBe(true);
+    expect(detect('module "vpc" {\n  source = "./modules/vpc"\n}')).toBe(true);
+    expect(detect('variable "region" {\n  type = string\n}')).toBe(true);
+    expect(detect('output "id" {\n  value = null_resource.first.id\n}')).toBe(true);
+  });
+
+  it("recognises the .tf.json syntax by its whole key set", () => {
+    expect(detect({ resource: { null_resource: { first: {} } } })).toBe(true);
+    expect(detect({ terraform: { required_version: ">= 1.5.0" }, provider: { aws: {} } })).toBe(true);
+  });
+
+  it("refuses another lexicon's document, and anything with no block at all", () => {
+    // k8s / fountain / gcp, which share the apiVersion+kind shape.
+    expect(detect({ apiVersion: "v1", kind: "ConfigMap", data: {} })).toBe(false);
+    // CloudFormation, whose `Resources` is not one of Terraform's block names.
+    expect(detect({ AWSTemplateFormatVersion: "2010-09-09", Resources: {} })).toBe(false);
+    // Compose.
+    expect(detect({ services: { web: { image: "nginx" } } })).toBe(false);
+    expect(detect("# just a comment\n")).toBe(false);
+    expect(detect("")).toBe(false);
+    expect(detect({})).toBe(false);
+    expect(detect(null)).toBe(false);
+    expect(detect([{ resource: {} }])).toBe(false);
+    expect(detect(42)).toBe(false);
+  });
+
+  it("does not match a block header that is only mentioned mid-line", () => {
+    expect(detect('# see resource "null_resource" "first" {} in main.tf')).toBe(false);
+  });
+});

package/src/plugin.ts

@@ -1,4 +1,4 @@
-import type { LexiconPlugin } from "@intentius/chant/lexicon";
+import type { AuditEntitiesInput, LexiconPlugin } from "@intentius/chant/lexicon";
 import type { CompletionContext, HoverContext } from "@intentius/chant/lsp/types";
 import type { Declarable } from "@intentius/chant/declarable";
 import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
@@ -11,7 +11,8 @@ import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { terraformConfigSchema, type TerraformConfig } from "./config";
 import { renderTerraformRoots } from "./hcl/roots";
-import { parseTerraformRootContent, RESOURCE_TYPE } from "./hcl/parse";
+import { auditRootName, parseTerraformRootContent, RESOURCE_TYPE } from "./hcl/parse";
+import { descendModules } from "./hcl/descend";
 import { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership";
 
 const loadSkills = createSkillsLoader(import.meta.url, [
@@ -23,6 +24,43 @@ const loadSkills = createSkillsLoader(import.meta.url, [
   },
 ]);
 
+/**
+ * The only top-level names Terraform's JSON syntax admits
+ * (developer.hashicorp.com/terraform/language/syntax/json). Used as a
+ * whole-document test in `detectTemplate`: a `.tf.json` file has these keys
+ * and nothing else.
+ */
+const TF_JSON_BLOCK_TYPES = new Set([
+  "terraform",
+  "provider",
+  "variable",
+  "output",
+  "locals",
+  "module",
+  "resource",
+  "data",
+  "moved",
+  "import",
+  "check",
+  "removed",
+]);
+
+/**
+ * Whether raw text is HCL a Terraform root or module is written in. One
+ * top-level block header is enough, and every one of these headers is
+ * Terraform's own: `terraform {`, and the labelled `resource`/`data`
+ * (two labels), `provider`/`module`/`variable`/`output` (one label). `locals`
+ * is left out on purpose, since it is the one block a non-Terraform HCL
+ * dialect is also likely to carry.
+ */
+function looksLikeHcl(text: string): boolean {
+  return (
+    /^[ \t]*terraform[ \t]*\{/m.test(text) ||
+    /^[ \t]*(resource|data)[ \t]+"[^"]+"[ \t]+"[^"]+"[ \t]*\{/m.test(text) ||
+    /^[ \t]*(provider|module|variable|output)[ \t]+"[^"]+"[ \t]*\{/m.test(text)
+  );
+}
+
 /**
  * terraform lexicon plugin.
  *
@@ -166,46 +204,99 @@ export const terraformPlugin: LexiconPlugin = {
   },
 
   /**
-   * Parse-to-graph for `chant audit` (#1567, #2085). `content` is the
+   * Parse-to-graph for `chant audit` (#1567, #2085, #2217). `content` is the
    * `# file: <name>`-joined bundle discovery builds for one discovered root
-   * module (`classifyTerraform`, `packages/core/src/audit/core.ts`); the root
-   * name itself isn't threaded through this hook's single-argument contract,
-   * so a fixed placeholder ("audit-root") stands in for it. TF001 only uses
-   * the root name to group and de-duplicate diagnostics within one parse, so
-   * this is enough for the same graph-reading check that fires on `chant
-   * build` to fire here too. Never throws: malformed HCL yields an empty map.
+   * module (`classifyTerraform`, `packages/core/src/audit/discover.ts`), and
+   * `input` says where that bundle came from.
+   *
+   * The scope is named after the input's path (`auditRootName`), so two roots
+   * in one repository are two roots here as well: they no longer collide in
+   * the merged entity map the all-files pass reads, which is what used to
+   * produce a finding keyed `<root>/<address>#2` against the file
+   * `(cross-file)` that neither directory deserved.
+   *
+   * When the audit walked a local filesystem, `input.dir` is the root
+   * module's directory and the parse descends its local `module` calls
+   * exactly as `buildRoots()` does, through the same `descendModules`
+   * (`../hcl/descend.ts`): a child module's entities are keyed
+   * `<root>/module.<name>/<address>` and carry the caller chain, so TF014 and
+   * TF015 fire here with the same `Callers:` line they print on a build, and
+   * the root-only rules (TF001 to TF003) still see only the root's own
+   * blocks. `input.baseDir` is the audited directory, which bounds the
+   * descent the way the project root bounds it on a build. Discovery drops a
+   * directory another one calls as a local module, so no module is audited
+   * twice.
+   *
+   * With no `input.dir` (a fetched repository; a caller parsing a bare
+   * string) the bundle is parsed alone, and the two child-module rules have
+   * no child to report on, since nothing named one.
+   *
+   * The descent's own refusals (a registry source, a source outside the
+   * audited tree, a cycle) are warnings on a build; this hook returns
+   * entities only, so on the audit path they are dropped rather than printed.
    *
-   * Module descent (#2112) reaches this path through the same
-   * `blocksToEntities`, but finds nothing to descend into: this hook is
-   * handed one directory's joined text and no directory to read a local
-   * module's files from, and audit discovery has already classified every
-   * nested `.tf` directory as an audit input of its own (`classifyTerraform`,
-   * `packages/core/src/audit/discover.ts`). So a child module IS audited on
-   * this path, as its own root rather than as a child scope, which means the
-   * two rules that ask "is this block inside a child module?" (TF014, TF015)
-   * report on `chant build` and not in `chant audit`, and TF020 answers per
-   * directory either way. The rule pages say so.
+   * Never throws: malformed HCL yields an empty map.
    */
-  async auditEntities(content: string): Promise<Map<string, Declarable>> {
+  async auditEntities(content: string, input?: AuditEntitiesInput): Promise<Map<string, Declarable>> {
     try {
-      return await parseTerraformRootContent(content, "audit-root");
+      const root = auditRootName(input?.path);
+      const entities = await parseTerraformRootContent(content, root);
+      if (input?.dir === undefined) return entities;
+      const { entities: children } = await descendModules(entities, {
+        dir: input.dir,
+        root,
+        projectRoot: input.baseDir ?? input.dir,
+      });
+      for (const [key, entity] of children) entities.set(key, entity);
+      return entities;
     } catch {
       return new Map();
     }
   },
 
+  /**
+   * No `mcpTools()` and no `mcpResources()`, deliberately (#2220). Both were
+   * declared returning `[]` behind a TODO, which passed the two tier-2
+   * "registers <method>" checks on a member that contributed nothing. Neither
+   * of the two shapes every other lexicon uses has anything to serve here:
+   * `createDiffTool` diffs one build's serializer output against the last,
+   * and this serializer writes nothing (`src/serializer.ts` is a deliberate
+   * no-op, the `.tf` files are the artifact); `createCatalogResource` serves
+   * the generated resource registry, and this lexicon generates none
+   * (`src/codegen/generate.ts` writes `{}` on purpose). So the members are
+   * removed rather than faked, and `chant dev check-lexicon` reports two
+   * tier-2 gaps that are real.
+   */
   skills: loadSkills,
 
-  mcpTools() {
-    return []; // TODO: Implement MCP tools
-  },
-
-  mcpResources() {
-    return []; // TODO: Implement MCP resources
-  },
-
-  detectTemplate(_data: unknown) {
-    return false; // TODO: Detect if a template belongs to this lexicon
+  /**
+   * `.tf` (and Terraform's own JSON syntax, `.tf.json`) recognised by content
+   * rather than by which directory a file sits in (#2220).
+   *
+   * Two input shapes, because the two callers hand over different things.
+   * `chant import` (`packages/core/src/cli/commands/import.ts`) `JSON.parse`s
+   * the file first, so it arrives as an object; the audit's content detection
+   * (`packages/core/src/audit/discover.ts`) hands azure its raw string, and a
+   * `.tf` file is not JSON at all, so the raw string form is the one that
+   * matters for HCL. Anything else reads as false.
+   *
+   * The object form is exact rather than heuristic: Terraform's JSON syntax
+   * admits only the top-level names in {@link TF_JSON_BLOCK_TYPES}, so a
+   * document is `.tf.json` when every key is one of them and at least one is
+   * present. That refuses a Kubernetes manifest, a CloudFormation template and
+   * a Compose file without having to name any of them.
+   *
+   * Discovery still classifies Terraform by the directory bundle
+   * (`classifyTerraform`), because a root module is a directory of files that
+   * has to be parsed together and one `.tf` on its own is not an audit input.
+   * This makes the per-file question answerable for the callers that ask it
+   * one file at a time.
+   */
+  detectTemplate(data: unknown) {
+    if (typeof data === "string") return looksLikeHcl(data);
+    if (typeof data !== "object" || data === null || Array.isArray(data)) return false;
+    const keys = Object.keys(data as Record<string, unknown>);
+    return keys.length > 0 && keys.every((k) => TF_JSON_BLOCK_TYPES.has(k));
   },
 
   completionProvider(ctx: CompletionContext) {