@intentius/chant-lexicon-terraform 0.57.0

package/dist/state-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-ownership.d.ts","sourceRoot":"","sources":["../src/state-ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,EAAE,WAI5C,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+// Code generated by chant generate. DO NOT EDIT.
+export {};

package/dist/validate-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=validate-cli.d.ts.map

package/dist/validate-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-cli.d.ts","sourceRoot":"","sources":["../src/validate-cli.ts"],"names":[],"mappings":""}

package/dist/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validate generated lexicon-terraform artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with terraform-specific configuration.
+ */
+import { type ValidateResult } from "@intentius/chant/codegen/validate";
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+/**
+ * Validate the generated lexicon-terraform artifacts.
+ */
+export declare function validate(opts?: {
+    basePath?: string;
+}): Promise<ValidateResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAKvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAQpF"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@intentius/chant-lexicon-terraform",
+  "version": "0.57.0",
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./src/*.ts"
+    },
+    "./op/activities": {
+      "development": "./src/op/activities/index.ts",
+      "types": "./dist/op/activities/index.d.ts",
+      "default": "./src/op/activities/index.ts"
+    },
+    "./lint/post-synth": {
+      "development": "./src/lint/post-synth/index.ts",
+      "types": "./dist/lint/post-synth/index.d.ts",
+      "default": "./src/lint/post-synth/index.ts"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "npx tsx src/codegen/generate-cli.ts",
+    "validate": "npx tsx src/validate-cli.ts",
+    "docs": "npx tsx src/codegen/docs-cli.ts",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
+    "bundle": "tsx src/package-cli.ts"
+  },
+  "devDependencies": {
+    "@intentius/chant": "*",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5.9.3",
+    "@cdktf/hcl2json": "^0.21.0",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6",
+    "@intentius/chant": "^0.57.0",
+    "typescript": "^5.9.3"
+  },
+  "description": "terraform lexicon for chant, existing Terraform root modules as declarable entities",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/INTENTIUS/chant#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/INTENTIUS/chant.git",
+    "directory": "lexicons/terraform"
+  },
+  "bugs": {
+    "url": "https://github.com/INTENTIUS/chant/issues"
+  },
+  "keywords": [
+    "chant",
+    "terraform",
+    "opentofu",
+    "hcl",
+    "iac"
+  ]
+}

package/src/__fixtures__/no-backend/main.tf

@@ -0,0 +1,24 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  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/__fixtures__/show-state.json

@@ -0,0 +1,68 @@
+{
+  "format_version": "1.0",
+  "terraform_version": "1.15.8",
+  "values": {
+    "root_module": {
+      "resources": [
+        {
+          "address": "null_resource.first",
+          "mode": "managed",
+          "type": "null_resource",
+          "name": "first",
+          "provider_name": "registry.terraform.io/hashicorp/null",
+          "schema_version": 0,
+          "values": {
+            "id": "1710777879587847269",
+            "triggers": {
+              "name": "first"
+            }
+          },
+          "sensitive_values": {
+            "triggers": {}
+          }
+        },
+        {
+          "address": "null_resource.second",
+          "mode": "managed",
+          "type": "null_resource",
+          "name": "second",
+          "provider_name": "registry.terraform.io/hashicorp/null",
+          "schema_version": 0,
+          "values": {
+            "id": "8141892773761384170",
+            "triggers": {
+              "name": "second"
+            }
+          },
+          "sensitive_values": {
+            "triggers": {}
+          }
+        }
+      ],
+      "child_modules": [
+        {
+          "resources": [
+            {
+              "address": "module.cdn.null_resource.edge",
+              "mode": "managed",
+              "type": "null_resource",
+              "name": "edge",
+              "provider_name": "registry.terraform.io/hashicorp/null",
+              "schema_version": 0,
+              "values": {
+                "id": "3525037590895298281",
+                "triggers": {
+                  "name": "edge"
+                }
+              },
+              "sensitive_values": {
+                "triggers": {}
+              }
+            }
+          ],
+          "address": "module.cdn"
+        }
+      ]
+    }
+  }
+}

package/src/__fixtures__/with-backend/main.tf

@@ -0,0 +1,28 @@
+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/__fixtures__/with-module/main.tf

@@ -0,0 +1,49 @@
+# The root `show-state.json` next door was recorded from: this configuration
+# was applied with terraform 1.15.8 against a local backend, and the resulting
+# `terraform show -json` saved verbatim. `null_resource.third` is declared here
+# and deliberately absent from that state, which is what an OBSERVED-ABSENT
+# entity looks like.
+
+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"
+  }
+}
+
+resource "null_resource" "third" {
+  triggers = {
+    name = "third"
+  }
+}
+
+module "cdn" {
+  source = "./modules/inner"
+}
+
+variable "region" {
+  type    = string
+  default = "us-east-1"
+}

package/src/__fixtures__/with-module/modules/inner/main.tf

@@ -0,0 +1,5 @@
+resource "null_resource" "edge" {
+  triggers = {
+    name = "edge"
+  }
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });

package/src/codegen/docs.ts

@@ -0,0 +1,50 @@
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+import type { DocsConfig } from "@intentius/chant/codegen/docs";
+
+const overview = `
+The Terraform lexicon reads an estate's existing \`.tf\` files. There is no
+generated resource surface here and nothing is emitted back over the HCL:
+Terraform's types live in provider registries, one schema per provider and
+version, and an estate that already has a root module does not need a second,
+generated copy of it.
+
+What you declare is the directory. Each entry in \`terraform.roots\` names a
+root module; \`buildRoots()\` parses it at build time and every HCL block joins
+the build as an entity keyed \`<root>/<address>\`, carrying the block body
+verbatim. Those entities are what the post-synth checks and \`chant audit\`
+read.
+
+See [Getting Started](getting-started/) for the config shape, the block-to-entity
+mapping, and what TF001 reports.
+`;
+
+/**
+ * Generate the docs site for the terraform lexicon.
+ *
+ * `basePath` is what the unified site at /chant needs so assets and internal
+ * links resolve once this site is copied under it (scripts/build-docs.test.ts
+ * asserts it). Authored pages come from `docs/pages/` by default.
+ */
+export async function generateDocs(options?: { verbose?: boolean }): Promise<void> {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+  const config: DocsConfig = {
+    name: "terraform",
+    displayName: "Terraform",
+    description: "Existing Terraform root modules as declarable chant entities",
+    distDir: join(pkgDir, "dist"),
+    outDir: join(pkgDir, "docs"),
+    basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/terraform/",
+    overview,
+    serviceFromType: (type: string) => type.split("::")[1] ?? type,
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (options?.verbose) {
+    console.error(`Generated ${result.pages.size} documentation pages`);
+  }
+}

package/src/codegen/generate-cli.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+// src/codegen/generate-cli.ts -> src/codegen -> src -> package root.
+// Two dirnames land in src/ and the first generate writes src/src/generated/ (#1614).
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result, pkgDir);

package/src/codegen/generate.ts

@@ -0,0 +1,68 @@
+/**
+ * Generation for the terraform lexicon: there is nothing to generate.
+ *
+ * Every other lexicon fetches one upstream schema and emits typed resource
+ * classes from it. Terraform has no such thing. Its resource surface lives in
+ * provider registries, one schema per provider and per version, and this
+ * lexicon does not model it: an estate's `.tf` files are read as they are
+ * (see `../hcl/parse.ts`) and the blocks become entities with their bodies
+ * carried verbatim. So `core`'s `generatePipeline` is not called at all, and
+ * this returns the empty result the packaging pipeline needs to assemble a
+ * bundle.
+ *
+ * The registry is still written, empty, because `validate` reads it and
+ * `writeBundleSpec` derives `dist/meta.json` from it. An empty registry is the
+ * honest statement that this lexicon exports no generated resource classes.
+ */
+
+import { writeGeneratedArtifacts } from "@intentius/chant/codegen/generate";
+import type { GenerateResult } from "@intentius/chant/codegen/generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+/** Filename of the generated registry, read back by `../validate.ts`. */
+export const LEXICON_JSON_FILENAME = "lexicon-terraform.json";
+
+const EMPTY_INDEX_TS = `// Code generated by chant generate. DO NOT EDIT.
+// The terraform lexicon models no upstream schema, so there are no resource
+// classes to export. See src/codegen/generate.ts.
+export {};
+`;
+
+const EMPTY_TYPES_DTS = `// Code generated by chant generate. DO NOT EDIT.
+export {};
+`;
+
+export async function generate(options?: { verbose?: boolean; force?: boolean }): Promise<GenerateResult> {
+  const result: GenerateResult = {
+    lexiconJSON: `${JSON.stringify({}, null, 2)}\n`,
+    typesDTS: EMPTY_TYPES_DTS,
+    indexTS: EMPTY_INDEX_TS,
+    resources: 0,
+    properties: 0,
+    enums: 0,
+    warnings: [],
+  };
+
+  if (options?.verbose) {
+    console.error("terraform generates no types: the .tf files an estate already has are the input");
+  }
+
+  return result;
+}
+
+/**
+ * Write generated files to the package directory.
+ */
+export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
+  // This file lives in src/codegen/, so the package root is three levels up.
+  const dir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  writeGeneratedArtifacts({
+    baseDir: dir,
+    files: {
+      [LEXICON_JSON_FILENAME]: result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+    },
+  });
+}

package/src/codegen/package.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { terraformPlugin } from "../plugin";
+
+/**
+ * This package's `src/` directory. `packagePipeline` scans it for the rule
+ * files that go into `dist/rules/`, so it must be `src/` and not `src/codegen/`
+ * (which is where `dirname(import.meta.url)` alone lands, and where
+ * `lint/rules` does not exist). `lexicons/aws/src/codegen/package.ts` resolves
+ * it the same way.
+ */
+const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** The published version, so the manifest cannot drift from package.json. */
+function packageVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8")) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/**
+ * Package the terraform lexicon for distribution.
+ */
+export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
+  const version = packageVersion();
+
+  const { spec, stats } = await packagePipeline(
+    {
+      generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+      buildManifest: () => ({
+        name: "terraform",
+        version,
+        chantVersion: ">=0.1.0",
+        namespace: "Terraform",
+      }),
+      srcDir,
+      collectSkills: () => collectSkills(terraformPlugin.skills?.() ?? []),
+      version,
+    },
+    options,
+  );
+
+  return { spec, stats };
+}

package/src/composites/terraform-apply-op.acceptance.test.ts

@@ -0,0 +1,138 @@
+/**
+ * The acceptance test is terraform, not a fixture (#2086).
+ *
+ * Everything else in this lexicon's Op suite proves the shape of what chant
+ * emits. This proves the shape runs: build a `TerraformApplyOp` with
+ * `gate: "never"` (the local executor refuses any Op containing a gate), hand
+ * it to `runOpLocally` with the activities the registry resolves by
+ * convention, and let a real `terraform` — or `tofu` — init, plan and apply
+ * the #2083 `with-backend` fixture root into a temp directory. Two
+ * `null_resource`s in the resulting state is the pass.
+ *
+ * The backend is `local`, so no credentials and no remote state are involved.
+ * The `hashicorp/null` provider still has to be downloaded from the registry,
+ * so the suite needs network as well as a binary. Both are gated, with the
+ * reason visible in the runner:
+ *
+ *   - no `terraform` and no `tofu` on PATH,
+ *   - `CHANT_OFFLINE` set, or `registry.terraform.io` not resolvable.
+ *
+ * Gating copied from `lexicons/k3s/src/serializer.acceptance.test.ts`, which
+ * skips the same way when Docker is absent.
+ */
+
+import { execSync } from "node:child_process";
+import { lookup } from "node:dns/promises";
+import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { loadActivities, loadProfiles, runOpLocally, type OpConfig } from "@intentius/chant/op";
+import { TerraformApplyOp } from "./terraform-apply-op";
+import { terraformShow } from "../op/activities/terraform";
+
+function onPath(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The registry has to answer for the provider download; a DNS answer is enough of a probe. */
+async function registryResolvable(): Promise<boolean> {
+  try {
+    await Promise.race([
+      lookup("registry.terraform.io"),
+      new Promise((_r, reject) => setTimeout(() => reject(new Error("dns timeout")), 3000)),
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const binary: "terraform" | "tofu" | undefined = onPath("terraform")
+  ? "terraform"
+  : onPath("tofu")
+    ? "tofu"
+    : undefined;
+const offline = Boolean(process.env.CHANT_OFFLINE);
+const online = !offline && binary !== undefined && (await registryResolvable());
+
+const skipReason = !binary
+  ? "no terraform or tofu binary on PATH"
+  : !online
+    ? offline
+      ? "CHANT_OFFLINE is set and the provider download needs the registry"
+      : "registry.terraform.io is unreachable and the provider download needs it"
+    : "";
+
+const FIXTURE = join(import.meta.dirname, "..", "__fixtures__", "with-backend");
+const workspaces: string[] = [];
+
+afterAll(() => {
+  for (const dir of workspaces) rmSync(dir, { recursive: true, force: true });
+});
+
+describe.skipIf(skipReason !== "")(
+  `TerraformApplyOp applies a real root${skipReason ? ` (skipped: ${skipReason})` : ""}`,
+  () => {
+    it(
+      "inits, plans and applies the with-backend fixture, leaving two null_resources in state",
+      { timeout: 300_000 },
+      async () => {
+        const project = mkdtempSync(join(tmpdir(), "chant-tf-accept-"));
+        workspaces.push(project);
+        cpSync(FIXTURE, join(project, "root"), { recursive: true });
+        writeFileSync(
+          join(project, "chant.config.json"),
+          JSON.stringify(
+            { lexicons: ["terraform"], terraform: { binary, roots: { acceptance: { dir: "./root" } } } },
+            null,
+            2,
+          ),
+        );
+
+        const { op } = TerraformApplyOp({
+          name: "terraform-acceptance",
+          root: "acceptance",
+          gate: "never",
+          cwd: project,
+        });
+
+        const activities = await loadActivities(["terraform"]);
+        expect([...activities.keys()]).toEqual(
+          expect.arrayContaining(["terraformInit", "terraformPlan", "terraformApply", "terraformShow"]),
+        );
+
+        const result = await runOpLocally(
+          (op as unknown as { props: OpConfig }).props,
+          activities,
+          await loadProfiles(),
+        );
+
+        expect(result.ok).toBe(true);
+        expect(result.records.map((r) => `${r.phase}:${r.status}`)).toEqual([
+          "Init:ok",
+          "Plan:ok",
+          "Apply:ok",
+        ]);
+
+        // The plan proposed two creates, and said so through the outcome the
+        // Plan step surfaces as the `Changed` search attribute.
+        const plan = result.records.find((r) => r.phase === "Plan")!;
+        expect(plan.outcome).toEqual({ name: "Changed", value: true });
+
+        // What terraform actually left behind.
+        const state = await terraformShow({ root: "acceptance", cwd: project });
+        const addresses = (
+          (state.json as { values?: { root_module?: { resources?: Array<{ address?: string }> } } }).values
+            ?.root_module?.resources ?? []
+        ).map((r) => r.address);
+        expect(addresses.sort()).toEqual(["null_resource.first", "null_resource.second"]);
+      },
+    );
+  },
+);