@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/dist/rules/tf026.ts

@@ -0,0 +1,80 @@
+/**
+ * TF026: a live root declares `delete: "never"` but its `policy` block still
+ * deletes an orphaned marked resource.
+ *
+ * chant's cross-lexicon delete-mode vocabulary (`terraform.roots.<name>.delete`,
+ * `../../config.ts`'s `TerraformDeleteMode`) maps onto choudoufu's `policy`
+ * block: `undeclared_tagged` governs what happens to a resource this estate
+ * marked that the configuration no longer declares, and defaults to
+ * `"delete"` when the `policy` block omits it, or the root declares no
+ * `policy` block at all. `delete: "never"` promises that `TerraformApplyOp`
+ * never proposes deleting a resource it owns, so a root making that promise
+ * has to have actually turned the quadrant's default off — `"keep"`,
+ * `"untag"` or `"report"` all satisfy it; anything else (the unset default,
+ * or an explicit `"delete"`) does not.
+ *
+ * One diagnostic per root, fired from the root's `Terraform::Live` entity —
+ * the same entity TF024 and TF025 fire from.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { LIVE_TYPE, type BlockBody } from "../../hcl/parse";
+
+/** Verbs that satisfy `delete: "never"` for the `undeclared_tagged` quadrant. */
+const SATISFIES_NEVER = new Set(["keep", "untag", "report"]);
+
+/** The `policy { }` block nested in a `live { }` block's body, hcl2json's own "one block, wrapped in an array" shape. */
+function policyBlockOf(liveBody: BlockBody): BlockBody | undefined {
+  const policy = liveBody["policy"];
+  return Array.isArray(policy) && policy.length > 0 && typeof policy[0] === "object" && policy[0] !== null
+    ? (policy[0] as BlockBody)
+    : undefined;
+}
+
+export const tf026: PostSynthCheck = {
+  id: "TF026",
+  description: "Live root declares delete: \"never\" but its policy leaves undeclared_tagged at \"delete\"",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const flagged = new Set<string>();
+
+    for (const [name, entity] of ctx.entities) {
+      if (entity.entityType !== LIVE_TYPE) continue;
+      if (!isResourceDeclarable(entity)) continue;
+      const props = entity.props as { root?: unknown; body?: unknown; mode?: unknown; delete?: unknown };
+      if (props.mode !== "live") continue;
+      if (props.delete !== "never") continue;
+      const root = typeof props.root === "string" ? props.root : "";
+      if (flagged.has(root)) continue;
+
+      const body = (typeof props.body === "object" && props.body !== null ? props.body : {}) as BlockBody;
+      const policy = policyBlockOf(body);
+      const undeclaredTagged = policy && typeof policy["undeclared_tagged"] === "string" ? (policy["undeclared_tagged"] as string) : undefined;
+      if (undeclaredTagged !== undefined && SATISFIES_NEVER.has(undeclaredTagged)) continue;
+
+      flagged.add(root);
+      const found =
+        undeclaredTagged === undefined
+          ? "leaves undeclared_tagged unset, which defaults to \"delete\""
+          : `sets undeclared_tagged = "${undeclaredTagged}"`;
+      diagnostics.push({
+        checkId: "TF026",
+        severity: "error",
+        message:
+          `Root module "${root}" declares delete: "never" (terraform.roots.${root}.delete), but its ` +
+          `policy block ${found}. Add undeclared_tagged = "keep" (or "untag" or "report") to the live ` +
+          "block's policy block, or change this root's delete mode.",
+        entity: name,
+        lexicon: "terraform",
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-terraform",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "type": "module",
   "files": [
     "src/",
@@ -22,6 +22,11 @@
       "types": "./dist/op/activities/index.d.ts",
       "default": "./src/op/activities/index.ts"
     },
+    "./op/activity-contracts": {
+      "development": "./src/op/activity-contracts.ts",
+      "types": "./dist/op/activity-contracts.d.ts",
+      "default": "./src/op/activity-contracts.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -51,7 +56,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.57.0",
+    "@intentius/chant": "^0.58.0",
     "typescript": "^5.9.3"
   },
   "description": "terraform lexicon for chant, existing Terraform root modules as declarable entities",

package/src/__fixtures__/live/main.tf

@@ -0,0 +1,28 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  live {
+    estate = "fixture-estate"
+  }
+
+  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__/live-adopt/estate.chdf.hcl

@@ -0,0 +1,6 @@
+# The body of this file is the live block's content, with no wrapper block
+# (choudoufu's live/MARKERS.md and site/content/docs/use/setup.md). The sidecar
+# form rather than the in-block one, because choudoufu's own migration guide
+# calls it the leading form: stock tooling never reads this file, so adopting
+# live markers adds one file and changes zero existing lines.
+estate = "chant-adopt-fixture"

package/src/__fixtures__/live-adopt/main.tf

@@ -0,0 +1,21 @@
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}
+
+provider "aws" {}
+
+# A VPC the acceptance test creates out of band, with no ownership marker on
+# it, before this root ever plans. choudoufu's content matcher offers a VPC on
+# `cidr_block` (`matchTable` in choudoufu's internal/live/foreign/classify.go),
+# so an unmarked live VPC at this exact cidr is what makes this root's plan
+# report one adoptable match rather than proposing a second VPC beside it.
+resource "aws_vpc" "adoptable" {
+  cidr_block = "10.77.0.0/16"
+}

package/src/__fixtures__/live-estate/README.md

@@ -0,0 +1,58 @@
+# The live-root fixture, and the two documents recorded from it
+
+This directory is one choudoufu live root: `.tf` files derived from
+choudoufu's own `live/e2e/estate-block/`, plus an `estate.chdf.hcl` sidecar
+naming the estate `stateless-e2e-block`. Under `terraform.binary:
+"choudoufu"` chant reads it as `mode: "live"` (#2103), which is what makes
+`describeResources()` branch onto `live-plan` instead of `terraform show`.
+
+`../live-plan.json` and `../live-ls.json` were recorded from this exact
+configuration, running choudoufu built from source at
+https://github.com/INTENTIUS/choudoufu (`go build ./cmd/choudoufu`,
+OpenTofu 1.13.0-dev) against that repository's own pinned floci emulator
+(`live/smoke/README.md`'s `just smoke` stack image, `live/floci-image`):
+
+```
+choudoufu init
+choudoufu apply -auto-approve                 # with storage.tf still present
+aws logs create-log-group --log-group-name /stateless-e2e-block/adoptable
+aws logs create-log-group --log-group-name /stateless-e2e-block/held-elsewhere
+aws logs tag-log-group    --log-group-name /stateless-e2e-block/held-elsewhere \
+  --tags tofu-estate=other-estate,tofu-address=aws_cloudwatch_log_group.elsewhere
+rm storage.tf                                 # the applied bucket becomes an owned orphan
+choudoufu live-plan -detailed-exitcode -json -estate=stateless-e2e-block
+choudoufu live-ls -estate=stateless-e2e-block -json -consistent .
+```
+
+Every row `describe-resources.ts` maps is in those two documents because the
+run produced it, not because a fixture author typed it:
+
+| Case | Where it came from |
+|---|---|
+| bound by marker | `aws_vpc.main`, `aws_subnet.app`, `aws_security_group.main`, and the two `aws_eip.pool` count instances with their slots |
+| bound by derivation | `aws_cloudwatch_log_group.app`, whose identity is the name in the block |
+| omission, `ABSENT` | `aws_cloudwatch_log_group.never_applied` and `aws_security_group_rule.https`, declared and never applied |
+| omission, `UNOWNED` | the two log groups the `unowned[]` section also carries |
+| unowned, adoptable | `aws_cloudwatch_log_group.adoptable`, with the two tag values that would claim it |
+| unowned, held elsewhere | `aws_cloudwatch_log_group.held_elsewhere`, carrying `other-estate` |
+| owned orphan | `aws_s3_bucket.data` in the listing, `declared: false` after `storage.tf` was removed |
+| listing gap | `aws_security_group_rule.https`, on the declaration-carried rung |
+
+## Two things the recording could not do as a chant live root would
+
+**The sidecar was not present during the recording.** `live-plan -json` is
+choudoufu's `-estate` form only, and that form refuses to run against a
+configuration that names its own estate: `choudoufu live-plan -estate=X` on a
+root with a `live` block or an `estate.chdf.hcl` sidecar answers "Estate named
+by both the live block and -estate", while plain `choudoufu plan -json` under
+one answers "Machine-readable output is not available under live resource
+markers yet" (`internal/command/live_plan.go` and `live_mode.go`). So the
+documents were recorded with the sidecar absent and `-estate` passed, and the
+sidecar was added afterwards to make this directory the live root chant sees.
+The documents themselves are byte-identical either way: the same estate, the
+same resources, the same sections.
+
+**The plan document's leading progress lines are not part of it.**
+`live-plan -json` prints its refresh progress to stdout ahead of the document.
+`../live-plan.json` is the document alone, from the first line that is a bare
+`{`.

package/src/__fixtures__/live-estate/compute.tf

@@ -0,0 +1,10 @@
+# Coverage: fungible count (aws_eip.pool, count = 2). Two rather than the
+# main estate's three — enough to prove slot markers survive a plain apply
+# without re-proving count-scale-down's exactness, which is step 9's job
+# against the main estate.
+
+resource "aws_eip" "pool" {
+  count = 2
+
+  domain = "vpc"
+}

package/src/__fixtures__/live-estate/estate.chdf.hcl

@@ -0,0 +1 @@
+estate = "stateless-e2e-block"

package/src/__fixtures__/live-estate/logs.tf

@@ -0,0 +1,8 @@
+# Coverage: client-named path (aws_cloudwatch_log_group — identity is the
+# log group name in config). No conditional-idiom instance here (the main
+# estate's aws_cloudwatch_log_group.optional already covers that row).
+
+resource "aws_cloudwatch_log_group" "app" {
+  name              = "/stateless-e2e-block/app"
+  retention_in_days = 1
+}

package/src/__fixtures__/live-estate/network.tf

@@ -0,0 +1,24 @@
+# Coverage: marker path (aws_vpc, aws_subnet, aws_security_group) — the same
+# admission row the main estate's network.tf covers. No for_each here (the
+# main estate's aws_subnet.this carries that row already); one subnet is
+# enough for this fixture's purpose, which is proving plain plan/apply, not
+# re-proving admission coverage.
+#
+# No tags argument on any resource below, unlike the main estate: this is the
+# point of estate-block (README.md) — every marker here is one stamping
+# writes at apply time, never one hand-written in config.
+
+resource "aws_vpc" "main" {
+  cidr_block = "10.99.0.0/16"
+}
+
+resource "aws_subnet" "app" {
+  vpc_id     = aws_vpc.main.id
+  cidr_block = "10.99.1.0/24"
+}
+
+resource "aws_security_group" "main" {
+  name        = "stateless-e2e-block-main"
+  description = "estate-block fixture security group"
+  vpc_id      = aws_vpc.main.id
+}

package/src/__fixtures__/live-estate/rule.tf

@@ -0,0 +1,11 @@
+# aws_security_group_rule carries no tags argument at all, so no ownership
+# marker was ever written for it: live-ls reports it as a gap on the
+# declaration-carried rung rather than as an absence.
+resource "aws_security_group_rule" "https" {
+  type              = "ingress"
+  from_port         = 443
+  to_port           = 443
+  protocol          = "tcp"
+  cidr_blocks       = ["10.99.0.0/16"]
+  security_group_id = aws_security_group.main.id
+}

package/src/__fixtures__/live-estate/unowned.tf

@@ -0,0 +1,21 @@
+# A live log group that exists in the account carrying no marker at all:
+# live-plan reports it unowned at a declared identity with the exact tag
+# write that would adopt it.
+resource "aws_cloudwatch_log_group" "adoptable" {
+  name              = "/stateless-e2e-block/adoptable"
+  retention_in_days = 1
+}
+
+# A live log group carrying another estate's marker: unowned, and not this
+# run's to adopt.
+resource "aws_cloudwatch_log_group" "held_elsewhere" {
+  name              = "/stateless-e2e-block/held-elsewhere"
+  retention_in_days = 1
+}
+
+# Declared and never applied: nothing exists at this identity, so the plan
+# omits it with reason ABSENT and proposes creating it.
+resource "aws_cloudwatch_log_group" "never_applied" {
+  name              = "/stateless-e2e-block/never-applied"
+  retention_in_days = 1
+}

package/src/__fixtures__/live-estate/versions.tf

@@ -0,0 +1,31 @@
+# Provider wiring for the live-root fixture. Derived from choudoufu's own
+# live/e2e/estate-block/versions.tf; the estate name is declared in the
+# estate.chdf.hcl sidecar beside this file rather than in a `live` block
+# here, for the reason README.md gives.
+#
+# Same environment-variable wiring as choudoufu's own fixture
+# (AWS_ENDPOINT_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION);
+# the provider block carries only the flags with no env-var form.
+
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "= 6.58.0"
+    }
+  }
+}
+
+provider "aws" {
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+
+  # skip_requesting_account_id deliberately absent — same rationale as the
+  # main estate's versions.tf (live/e2e/estate/versions.tf): letting the
+  # provider resolve the account keeps tag-filtered discovery honest about
+  # what real AWS would do.
+
+  s3_use_path_style = true
+}

package/src/__fixtures__/live-ls.json

@@ -0,0 +1,98 @@
+{
+  "estate": "stateless-e2e-block",
+  "consistent": true,
+  "stabilized": true,
+  "attempts": 2,
+  "config_dir": ".",
+  "items": [
+    {
+      "id": "arn:aws:logs:us-east-1:000000000000:log-group:/stateless-e2e-block/app",
+      "type": "aws_cloudwatch_log_group",
+      "address": "aws_cloudwatch_log_group.app",
+      "declared": true,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_cloudwatch_log_group.app",
+        "tofu-estate": "stateless-e2e-block"
+      }
+    },
+    {
+      "id": "arn:aws:ec2:us-east-1:000000000000:elastic-ip/eipalloc-956f58ee85678c4a2",
+      "type": "aws_eip",
+      "address": "aws_eip.pool[0]",
+      "slot": "0",
+      "declared": true,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_eip.pool:0",
+        "tofu-estate": "stateless-e2e-block",
+        "tofu-slot": "0"
+      }
+    },
+    {
+      "id": "arn:aws:ec2:us-east-1:000000000000:elastic-ip/eipalloc-eb84912f9550b202b",
+      "type": "aws_eip",
+      "address": "aws_eip.pool[1]",
+      "slot": "1",
+      "declared": true,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_eip.pool:1",
+        "tofu-estate": "stateless-e2e-block",
+        "tofu-slot": "1"
+      }
+    },
+    {
+      "id": "arn:aws:s3:::tofu-stateless-e2e-block-data",
+      "type": "aws_s3_bucket",
+      "address": "aws_s3_bucket.data",
+      "declared": false,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_s3_bucket.data",
+        "tofu-estate": "stateless-e2e-block"
+      }
+    },
+    {
+      "id": "arn:aws:ec2:us-east-1:000000000000:security-group/sg-5fbb2850b62304cee",
+      "type": "aws_security_group",
+      "address": "aws_security_group.main",
+      "declared": true,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_security_group.main",
+        "tofu-estate": "stateless-e2e-block"
+      }
+    },
+    {
+      "id": "arn:aws:ec2:us-east-1:000000000000:subnet/subnet-4d624e84",
+      "type": "aws_subnet",
+      "address": "aws_subnet.app",
+      "declared": true,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_subnet.app",
+        "tofu-estate": "stateless-e2e-block"
+      }
+    },
+    {
+      "id": "arn:aws:ec2:us-east-1:000000000000:vpc/vpc-c1733cf7",
+      "type": "aws_vpc",
+      "address": "aws_vpc.main",
+      "declared": true,
+      "source": "tagging",
+      "tags": {
+        "tofu-address": "aws_vpc.main",
+        "tofu-estate": "stateless-e2e-block"
+      }
+    }
+  ],
+  "gaps": [
+    {
+      "address": "aws_security_group_rule.https",
+      "type": "aws_security_group_rule",
+      "rung": "declaration-carried",
+      "detail": "aws_security_group_rule has no settable tags argument, so no ownership marker was ever written for it - live/MARKERS.md's tier definitions (#417) name this the declaration-carried tier. Its identity comes entirely from configuration."
+    }
+  ]
+}