@intentius/chant-lexicon-terraform 0.57.0 → 0.59.0

package/src/plugin.test.ts

@@ -9,6 +9,7 @@ import { terraformPlugin } from "./plugin";
 import { terraformConfigSchema } from "./config";
 import {
   DATA_TYPE,
+  LIVE_TYPE,
   PROVIDER_TYPE,
   RESOURCE_TYPE,
   TERRAFORM_TYPE,
@@ -57,6 +58,12 @@ describe("terraform plugin", () => {
     expect(terraformPlugin.postSynthChecks?.().length).toBeGreaterThan(0);
   });
 
+  it("registers the estate-wide reads a live root makes possible (#2104)", () => {
+    expect(terraformPlugin.ambientKinds?.()).toEqual(["Terraform::Resource"]);
+    expect(typeof terraformPlugin.observeAmbient).toBe("function");
+    expect(typeof terraformPlugin.teardownOwned).toBe("function");
+  });
+
   it("registers the LSP providers and docs", () => {
     expect(typeof terraformPlugin.completionProvider).toBe("function");
     expect(typeof terraformPlugin.hoverProvider).toBe("function");
@@ -227,6 +234,67 @@ describe("buildRoots", () => {
   });
 });
 
+describe("buildRoots: choudoufu live mode (#2103)", () => {
+  it("marks every entity live and carries the estate, under binary: choudoufu", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { binary: "choudoufu", roots: { estate: { dir: "./live" } } },
+    });
+
+    expect(warnings ?? []).toEqual([]);
+    expect([...entities.keys()].sort()).toEqual([
+      "estate/live",
+      "estate/null_resource.first",
+      "estate/null_resource.second",
+      "estate/provider.null",
+      "estate/terraform",
+    ]);
+
+    const live = entities.get("estate/live")!;
+    expect(live.entityType).toBe(LIVE_TYPE);
+    for (const key of entities.keys()) {
+      const props = propsOf(entities.get(key));
+      expect(props.mode).toBe("live");
+      expect(props.estate).toBe("fixture-estate");
+    }
+  });
+
+  it("reads the estate from the estate.chdf.hcl sidecar the same way", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { binary: "choudoufu", roots: { estate: { dir: "./live-sidecar" } } },
+    });
+
+    expect(warnings ?? []).toEqual([]);
+    const live = entities.get("estate/live")!;
+    expect(live.entityType).toBe(LIVE_TYPE);
+    expect(propsOf(live).file).toBe("estate.chdf.hcl");
+    expect(propsOf(entities.get("estate/terraform")).estate).toBe("fixture-estate");
+  });
+
+  it("stays state mode and warns when the estate is declared but the binary is not choudoufu", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { roots: { estate: { dir: "./live" } } },
+    });
+
+    for (const key of entities.keys()) {
+      const props = propsOf(entities.get(key));
+      expect(props.mode).toBe("state");
+      expect(props.estate).toBeUndefined();
+    }
+    expect(warnings).toHaveLength(1);
+    expect(warnings![0]).toContain("terraform.roots.estate");
+    expect(warnings![0]).toContain("inert");
+  });
+
+  it("stays state mode with no live declaration at all, regardless of binary", async () => {
+    const { entities, warnings } = await buildRoots(fixtures, {
+      terraform: { binary: "choudoufu", roots: { app: { dir: "./with-backend" } } },
+    });
+
+    expect(warnings ?? []).toEqual([]);
+    expect(propsOf(entities.get("app/terraform")).mode).toBe("state");
+  });
+});
+
 describe("auditEntities (#2085, parse-to-graph for chant audit)", () => {
   it("parses a joined `# file:` bundle into entities", async () => {
     const hook = terraformPlugin.auditEntities;
@@ -269,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,16 +1,18 @@
-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";
 import { terraformSerializer } from "./serializer";
 import { rules } from "./lint/rules";
 import { postSynthChecks } from "./lint/post-synth";
+import { withCallersChain } from "./lint/post-synth/scope";
 import { terraformAuditCatalog } from "./lint/audit-catalog";
 import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { terraformConfigSchema, type TerraformConfig } from "./config";
 import { renderTerraformRoots } from "./hcl/roots";
-import { parseTerraformRootContent } 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, [
@@ -22,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.
  *
@@ -70,11 +109,19 @@ export const terraformPlugin: LexiconPlugin = {
   // ── Optional extensions ────────────────────────────────────
 
   /**
-   * Terraform's ownership channel is the state file, not a tag or a label
-   * (#2087). Every address `terraform show -json` returns is `owned`;
-   * everything else is `unknown`. Declaring the channel is what makes that a
-   * claim the conformance suite checks rather than a silent degradation.
-   * See `./describe-resources.ts` and `docs/pages/observation.mdx`.
+   * The ownership channel is per mode, and the channel declared here names
+   * the stock one, because a project's roots are stock unless it opts into
+   * choudoufu.
+   *
+   * On a stock root the channel is the state file, not a tag or a label
+   * (#2087): every address `terraform show -json` returns is `owned` and
+   * everything else is `unknown`. On a live root (#2104) it is choudoufu's
+   * two marker tags, `./live-ownership.ts`'s `TERRAFORM_LIVE_MARKER_KEYS`,
+   * and the verdicts come from `live-plan -json`'s own sections. Both
+   * readings resolve a real verdict on this path, which is what declaring
+   * `describeResources` here claims and what the conformance suite checks,
+   * for both modes. See `./describe-resources.ts` and
+   * `docs/pages/observation.mdx`.
    */
   ownershipChannel: {
     keys: TERRAFORM_STATE_OWNERSHIP_KEYS,
@@ -86,6 +133,26 @@ export const terraformPlugin: LexiconPlugin = {
     return describeResources(options);
   },
 
+  /**
+   * The kinds a live root can enumerate beyond its declaration (#1278,
+   * #2104). Empty on a project with no live root, because `live-ls` is the
+   * only estate-wide read this lexicon has and a stock root has none: a state
+   * file knows what it created and nothing else.
+   */
+  ambientKinds() {
+    return [RESOURCE_TYPE];
+  },
+
+  async observeAmbient(options) {
+    const { observeAmbient } = await import("./describe-resources");
+    return observeAmbient(options);
+  },
+
+  async teardownOwned(options) {
+    const { teardownOwned } = await import("./describe-resources");
+    return teardownOwned(options);
+  },
+
   /**
    * Each entry in `terraform.roots` is a root module directory that parses at
    * build time into one entity per HCL block. The render lives in
@@ -93,17 +160,28 @@ export const terraformPlugin: LexiconPlugin = {
    * project root, which is what relative `dir` paths resolve against.
    */
   async buildRoots(ctx): Promise<{ entities: Map<string, Declarable>; warnings: string[] }> {
-    const roots = (ctx.config as { terraform?: TerraformConfig }).terraform?.roots ?? {};
+    const namespace = (ctx.config as { terraform?: TerraformConfig }).terraform;
+    const roots = namespace?.roots ?? {};
     if (Object.keys(roots).length === 0) return { entities: new Map(), warnings: [] };
-    return renderTerraformRoots({ projectRoot: ctx.projectRoot, roots });
+    return renderTerraformRoots({
+      projectRoot: ctx.projectRoot,
+      roots,
+      binary: namespace?.binary,
+      callModuleType: namespace?.callModuleType,
+    });
   },
 
   lintRules() {
     return rules;
   },
 
+  /**
+   * The generated barrel of checks, each wrapped so a finding inside a
+   * descended child module names the call chain that reached it (#2112). See
+   * `./lint/post-synth/scope.ts`.
+   */
   postSynthChecks() {
-    return postSynthChecks;
+    return withCallersChain(postSynthChecks);
   },
 
   auditCatalog() {
@@ -111,35 +189,114 @@ export const terraformPlugin: LexiconPlugin = {
   },
 
   /**
-   * Parse-to-graph for `chant audit` (#1567, #2085). `content` is the
+   * `recommended`/`all` (chant #2113), the tflint-ruleset-terraform shape:
+   * `recommended` is every `merge-worthy` TF rule (a correctness/security
+   * finding worth reporting by default), `all` adds the `report-only` ones
+   * (hygiene the family grows into as #2109/#2110/#2112 land). Derived from
+   * `terraformAuditCatalog` rather than a hand-kept id list, so a rule that
+   * lands in a later, parallel issue is picked up automatically the moment
+   * its catalog entry ships, with no second list to fall out of sync.
+   */
+  lintPresets() {
+    const ids = Object.keys(terraformAuditCatalog);
+    const recommended = ids.filter((id) => terraformAuditCatalog[id].tier === "merge-worthy");
+    return { recommended, all: ids };
+  },
+
+  /**
+   * 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.
+   *
+   * 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) {

package/src/skills/chant-terraform.md

@@ -65,7 +65,7 @@ export const { op } = TerraformApplyOp({
 });
 ```
 
-`gate: "never"` is what makes the Op runnable under the local executor (`chant run`); any other mode emits a Gate phase, and a gate is durable-runtime work the local executor refuses. The Gate phase always shows the saved plan first and reports its `destroys` count as a `Destroys` search attribute, because `GateStep` carries no condition to branch on at build time — the approver sees what's at stake before approving, rather than the Op deciding for them.
+`gate: "never"` drops the Gate phase, so `chant run` walks straight from Plan to Apply; any other mode emits a Gate phase, and a run that reaches an unapproved gate records a pending fact on the gate ledger, ends `gated` and exits 3 until someone runs `chant approve <op> <gate>`. The Gate phase always shows the saved plan first and reports its `destroys` count as a `Destroys` run outcome, because `GateStep` carries no condition to branch on at build time — the approver sees what's at stake before approving, rather than the Op deciding for them.
 
 Terraform has no automatic rollback, so `compensate: true` with no command throws at build time, naming the Op, rather than warning once an apply has already half-run:
 

package/src/validate.ts

@@ -11,7 +11,16 @@ import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/
 
 export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
 
-// TODO: Add names of required entities for your lexicon
+/**
+ * Empty, and correct empty (#2220). `requiredNames` names generated resource
+ * classes that must survive a regenerate, and this lexicon generates none:
+ * `codegen/generate.ts` writes `lexicon-terraform.json` as `{}` on purpose,
+ * because Terraform's resource surface lives in provider registries rather
+ * than in one upstream schema, and an estate's `.tf` files are read as they
+ * are. There is no name to require, so the list stays empty and the
+ * remaining checks (the artifacts exist, the registry parses, the surface
+ * snapshot) are what validate actually proves here.
+ */
 const REQUIRED_NAMES: string[] = [];
 
 /**