@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/src/op/activity-contracts.test.ts

@@ -0,0 +1,147 @@
+import { describe, test, expect } from "vitest";
+import { isActivityContract, validateActivitySteps, validateStepOutputRefs, stepOutput, type ActivityContract } from "@intentius/chant/op";
+import * as contracts from "./activity-contracts";
+import * as activities from "./activities";
+
+const CONTRACTS: Map<string, ActivityContract> = new Map(
+  Object.values(contracts).filter(isActivityContract).map((c) => [c.name, c]),
+);
+
+/**
+ * The activities this lexicon contributes to the run-time registry — every
+ * exported function that is one, as `collectActivities` keys them.
+ * `terraformInitCommand` and friends are pure builders the tests assert on,
+ * not activities a step can name, so the list is spelled out rather than
+ * derived from the module's exports.
+ */
+const ACTIVITY_NAMES = [
+  "terraformInit",
+  "terraformPlan",
+  "terraformApply",
+  "terraformShow",
+  "choudoufuLivePlan",
+  "choudoufuLiveLs",
+  "choudoufuLiveCheck",
+  "choudoufuAdopt",
+];
+
+describe("terraform activity contracts (#2101)", () => {
+  test("every activity this lexicon ships has a contract", () => {
+    for (const name of ACTIVITY_NAMES) {
+      expect(CONTRACTS.get(name), `no contract declared for ${name}`).toBeDefined();
+    }
+  });
+
+  test("each name in ACTIVITY_NAMES really is an exported activity", () => {
+    for (const name of ACTIVITY_NAMES) {
+      expect(typeof (activities as unknown as Record<string, unknown>)[name]).toBe("function");
+    }
+  });
+
+  test("the module exports nothing but contracts", () => {
+    for (const [key, value] of Object.entries(contracts)) {
+      expect(isActivityContract(value), `${key} is not an ActivityContract`).toBe(true);
+    }
+  });
+
+  test("every contract declares a return schema — OPS013 needs one to validate a reference", () => {
+    for (const name of ACTIVITY_NAMES) {
+      expect(CONTRACTS.get(name)?.returns, `${name} declares no return schema`).toBeDefined();
+    }
+  });
+
+  test("`root` is declared as the entity every step touches (#2022)", () => {
+    for (const name of ACTIVITY_NAMES) {
+      expect(CONTRACTS.get(name)?.entities).toEqual(["root"]);
+    }
+  });
+
+  // ── The failure classes the contracts exist to catch ───────────────────
+
+  const op = (steps: unknown[]) => ({
+    name: "app-apply",
+    phases: [{ name: "Phase", steps: steps as never[] }],
+  });
+
+  test("a misspelled arg key is an error, not a silently dropped field", () => {
+    const issues = validateActivitySteps(
+      op([{ kind: "activity", fn: "terraformPlan", args: { root: "app", planfile: "chant.tfplan" } }]),
+      CONTRACTS,
+    );
+    expect(issues.some((i) => i.message.includes("planfile"))).toBe(true);
+  });
+
+  test("a missing `root` is an error", () => {
+    const issues = validateActivitySteps(
+      op([{ kind: "activity", fn: "terraformApply", args: {} }]),
+      CONTRACTS,
+    );
+    expect(issues.length).toBeGreaterThan(0);
+  });
+
+  test("the args the examples' composites build validate clean", () => {
+    const issues = validateActivitySteps(
+      op([
+        { kind: "activity", fn: "terraformInit", args: { root: "app" }, profile: "longInfra" },
+        { kind: "activity", fn: "terraformPlan", args: { root: "app", planFile: "chant.tfplan" }, id: "plan", profile: "longInfra" },
+        { kind: "activity", fn: "terraformShow", args: { root: "app", planFile: stepOutput("plan", "planFile") }, profile: "fastIdempotent" },
+        { kind: "activity", fn: "terraformApply", args: { root: "app", planFile: stepOutput("plan", "planFile") }, profile: "longInfra" },
+      ]),
+      CONTRACTS,
+    );
+    expect(issues).toEqual([]);
+  });
+
+  test("`plan.out.planFile` resolves against terraformPlan's declared return type", () => {
+    const issues = validateStepOutputRefs(
+      op([
+        { kind: "activity", fn: "terraformPlan", args: { root: "app" }, id: "plan" },
+        { kind: "activity", fn: "terraformApply", args: { root: "app", planFile: stepOutput("plan", "planFile") } },
+      ]),
+      CONTRACTS,
+    );
+    expect(issues).toEqual([]);
+  });
+
+  test("`plan.out.text` — the field a finding mode posts — resolves too", () => {
+    const issues = validateStepOutputRefs(
+      op([
+        { kind: "activity", fn: "terraformPlan", args: { root: "app" }, id: "plan" },
+        { kind: "activity", fn: "reconcilePr", args: { env: "app", body: stepOutput("plan", "text") } },
+      ]),
+      CONTRACTS,
+    );
+    expect(issues).toEqual([]);
+  });
+
+  test("a live watch's three outcome attributes exist on choudoufuLivePlan's return type", () => {
+    const issues = validateActivitySteps(
+      op([
+        {
+          kind: "activity",
+          fn: "choudoufuLivePlan",
+          args: { root: "app" },
+          id: "plan",
+          outcomeAttribute: [
+            { name: "Drift", from: "drift" },
+            { name: "Unowned", from: "unowned" },
+            { name: "Adoptable", from: "adoptable" },
+          ],
+        },
+      ]),
+      CONTRACTS,
+    );
+    expect(issues).toEqual([]);
+  });
+
+  test("a reference into terraform's own `-json` document does not resolve, by design", () => {
+    const issues = validateStepOutputRefs(
+      op([
+        { kind: "activity", fn: "terraformPlan", args: { root: "app" }, id: "plan" },
+        { kind: "activity", fn: "reconcilePr", args: { env: "app", body: stepOutput("plan", "json.resource_changes") } },
+      ]),
+      CONTRACTS,
+    );
+    expect(issues.some((i) => i.message.includes("does not exist"))).toBe(true);
+  });
+});

package/src/op/activity-contracts.ts

@@ -0,0 +1,178 @@
+/**
+ * Activity contracts for this lexicon's own `op/activities` (chant #2101).
+ *
+ * The schema-shaped sibling of `./activities/index.ts`: that module is
+ * resolved by convention at `@intentius/chant-lexicon-terraform/op/activities`
+ * for the run-time registry, and this one at
+ * `@intentius/chant-lexicon-terraform/op/activity-contracts` for build-time
+ * validation. `loadActivityContracts`
+ * (`packages/core/src/op/activity-contract-registry.ts`) merges what it finds
+ * here into the map core's own OPS012 and OPS013 validate every `Chant::Op`
+ * step against. Since #2122 moved those checks into core they fire on every
+ * project that declares an Op, so an Op built out of terraform steps is
+ * checked wherever it is built. Before this existed, both examples that carry
+ * an Op had to keep it outside `src/` where `chant dev check-lexicon`'s
+ * example build could not see it.
+ *
+ * Each contract's `args` schema mirrors the corresponding `*Args` interface in
+ * `./activities/terraform.ts`, and each `returns` schema the corresponding
+ * `*Result`. Authored with `z.strictObject(...)`, never `z.object(...)`: the
+ * default form silently drops an unrecognized key instead of rejecting it, so
+ * a misspelled `planfile` would vanish rather than fail the build. The
+ * `returns` schemas are the half OPS013 needs — `plan.out.planFile` feeding an
+ * Apply step, `plan.out.text` feeding a `reconcilePr` body — so a field a step
+ * references has to be spelled here for the reference to validate.
+ *
+ * `json` is `z.unknown()` throughout: it is terraform's own `-json` document,
+ * whose shape is the provider's, not chant's. A dot-path reference into it
+ * therefore does not resolve, which is deliberate. Reference `text`, or one of
+ * the counts projected out of the document, instead of reaching into
+ * terraform's JSON from an Op.
+ */
+
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+
+/** `root` and `cwd`, the two fields every activity in this lexicon takes ({@link TerraformRootArgs}). */
+const rootArgs = { root: z.string(), cwd: z.string().optional() };
+
+/**
+ * `adds`/`changes`/`destroys`, the counts projected out of a plan's
+ * `resource_changes` ({@link PlanChangeCounts}).
+ */
+const planChangeCounts = { adds: z.number(), changes: z.number(), destroys: z.number() };
+
+/**
+ * One adoption candidate as `../adoption.ts` models it. Loose on purpose: an
+ * Op never reaches into a candidate's fields, it hands the whole array from a
+ * live-plan step to `choudoufuAdopt`, and a whole-value reference is validated
+ * without walking the shape.
+ */
+const adoptionCandidate = z.object({}).loose();
+
+/**
+ * The `root` arg names the terraform root module the step acts on — the
+ * estate-side thing every activity here touches — so op.json's IR resolves it
+ * into the step's `entities` (#2022) and a renderer can join the step to the
+ * root instead of guessing off `cwd`, which is only where the config search
+ * starts.
+ */
+const rootEntity = { entities: ["root"] };
+
+export const terraformInitContract = activityContract(
+  "terraformInit",
+  z.strictObject({
+    ...rootArgs,
+    upgrade: z.boolean().optional(),
+    reconfigure: z.boolean().optional(),
+  }),
+  z.object({ dir: z.string(), workspace: z.string().optional() }),
+  rootEntity,
+);
+
+export const terraformPlanContract = activityContract(
+  "terraformPlan",
+  z.strictObject({
+    ...rootArgs,
+    planFile: z.string().optional(),
+    destroy: z.boolean().optional(),
+  }),
+  z.object({
+    ...planChangeCounts,
+    changed: z.boolean(),
+    planFile: z.string(),
+    dir: z.string(),
+    json: z.unknown(),
+    text: z.string(),
+  }),
+  rootEntity,
+);
+
+export const terraformApplyContract = activityContract(
+  "terraformApply",
+  z.strictObject({ ...rootArgs, planFile: z.string().optional() }),
+  z.object({
+    planFile: z.string().optional(),
+    dir: z.string(),
+    applied: z.boolean(),
+    refused: z.enum(["approval-mismatch", "wrong-estate"]).optional(),
+    refusal: z.string().optional(),
+  }),
+  rootEntity,
+);
+
+export const terraformShowContract = activityContract(
+  "terraformShow",
+  z.strictObject({ ...rootArgs, planFile: z.string().optional() }),
+  z.object({
+    ...planChangeCounts,
+    source: z.enum(["plan", "state"]),
+    json: z.unknown(),
+    text: z.string(),
+    dir: z.string(),
+    planFile: z.string().optional(),
+  }),
+  rootEntity,
+);
+
+export const choudoufuLivePlanContract = activityContract(
+  "choudoufuLivePlan",
+  z.strictObject({
+    ...rootArgs,
+    estate: z.string().optional(),
+    adoptionOnly: z.boolean().optional(),
+  }),
+  z.object({
+    ...planChangeCounts,
+    unowned: z.number(),
+    adoptable: z.number(),
+    drift: z.boolean(),
+    json: z.unknown(),
+    text: z.string(),
+    ledger: z.string(),
+    finding: z.string(),
+    adoptions: z.array(adoptionCandidate),
+    contested: z.array(adoptionCandidate),
+    ambiguous: z.number(),
+    dir: z.string(),
+    documentPath: z.string(),
+    estate: z.string(),
+  }),
+  rootEntity,
+);
+
+export const choudoufuLiveLsContract = activityContract(
+  "choudoufuLiveLs",
+  z.strictObject({
+    ...rootArgs,
+    estate: z.string().optional(),
+    consistent: z.boolean().optional(),
+  }),
+  z.object({ json: z.unknown(), dir: z.string(), estate: z.string() }),
+  rootEntity,
+);
+
+export const choudoufuLiveCheckContract = activityContract(
+  "choudoufuLiveCheck",
+  z.strictObject({ ...rootArgs }),
+  z.object({ refused: z.boolean(), json: z.unknown(), text: z.string(), dir: z.string() }),
+  rootEntity,
+);
+
+export const choudoufuAdoptContract = activityContract(
+  "choudoufuAdopt",
+  z.strictObject({
+    ...rootArgs,
+    adoptions: z.array(adoptionCandidate),
+    contested: z.array(adoptionCandidate).optional(),
+  }),
+  z.object({
+    mechanism: z.literal("tag-write"),
+    adopted: z.array(z.string()),
+    adoptedCount: z.number(),
+    refused: z.array(z.object({ addr: z.string(), identity: z.string(), reason: z.string() })),
+    ambiguous: z.number(),
+    dir: z.string(),
+  }),
+  rootEntity,
+);

package/src/op/adoption.test.ts

@@ -0,0 +1,170 @@
+/**
+ * The adoption ledger (#2105): reading `live-plan -json`'s `unowned` section,
+ * pairing it with the commands `-adoption-only` printed, and rendering it.
+ *
+ * The document fragments below are the shape choudoufu actually emits, taken
+ * from `views.StatelessUnowned`'s json tags (`internal/command/live_plan.go`)
+ * and checked against the recorded document #2104 captured off the emulator:
+ * an adoptable row carries `adopt_tofu_estate`/`adopt_tofu_address`, and a row
+ * held by somebody else carries `tofu_estate` and neither of the other two.
+ */
+
+import { describe, test, expect } from "vitest";
+import { parseAdoptionCommands, readAdoptionLedger, renderAdoptionLedger } from "./adoption";
+
+const adoptable = (addr: string, identity: string, type = "aws_vpc") => ({
+  addr,
+  type,
+  identity,
+  adopt_tofu_estate: "prod-networking",
+  adopt_tofu_address: addr,
+});
+
+describe("readAdoptionLedger (#2105)", () => {
+  test("a row carrying both marker values is adoptable", () => {
+    const ledger = readAdoptionLedger({ unowned: [adoptable("aws_vpc.main", "vpc-0abc")] });
+    expect(ledger.adoptions).toEqual([
+      {
+        addr: "aws_vpc.main",
+        type: "aws_vpc",
+        identity: "vpc-0abc",
+        markerEstate: "prod-networking",
+        markerAddress: "aws_vpc.main",
+      },
+    ]);
+    expect(ledger.contested).toEqual([]);
+    expect(ledger.ambiguous).toBe(0);
+  });
+
+  test("a row held by another estate is neither adoptable nor contested", () => {
+    // Adoption was not this run's to offer, so there is no tag write to refuse.
+    const ledger = readAdoptionLedger({
+      unowned: [
+        {
+          addr: "aws_cloudwatch_log_group.held_elsewhere",
+          type: "aws_cloudwatch_log_group",
+          identity: "/estate/held-elsewhere",
+          tofu_estate: "other-estate",
+        },
+      ],
+    });
+    expect(ledger.adoptions).toEqual([]);
+    expect(ledger.contested).toEqual([]);
+  });
+
+  test("two live resources at one declared address are contested, never adoptable", () => {
+    const ledger = readAdoptionLedger({
+      unowned: [
+        adoptable("aws_vpc.main", "vpc-0abc"),
+        adoptable("aws_vpc.main", "vpc-0def"),
+        adoptable("aws_subnet.app", "subnet-01", "aws_subnet"),
+      ],
+    });
+    expect(ledger.adoptions.map((c) => c.addr)).toEqual(["aws_subnet.app"]);
+    expect(ledger.contested.map((c) => c.identity)).toEqual(["vpc-0abc", "vpc-0def"]);
+    // One address is contested, and both of its candidates are listed, so the
+    // report shows what the choice is between.
+    expect(ledger.ambiguous).toBe(1);
+  });
+
+  test("a command from the -adoption-only render rides on the matching candidate", () => {
+    const commands = new Map([["aws_vpc.main", "aws ec2 create-tags --resources 'vpc-0abc'"]]);
+    const ledger = readAdoptionLedger(
+      { unowned: [adoptable("aws_vpc.main", "vpc-0abc"), adoptable("aws_subnet.app", "subnet-01", "aws_subnet")] },
+      commands,
+    );
+    expect(ledger.adoptions.find((c) => c.addr === "aws_vpc.main")?.command).toBe(
+      "aws ec2 create-tags --resources 'vpc-0abc'",
+    );
+    expect(ledger.adoptions.find((c) => c.addr === "aws_subnet.app")?.command).toBeUndefined();
+  });
+
+  test("a document with no unowned section, or none at all, is an empty ledger", () => {
+    expect(readAdoptionLedger({ bound: [] })).toEqual({ adoptions: [], contested: [], ambiguous: 0 });
+    expect(readAdoptionLedger(undefined)).toEqual({ adoptions: [], contested: [], ambiguous: 0 });
+    expect(readAdoptionLedger({ unowned: "not a list" })).toEqual({ adoptions: [], contested: [], ambiguous: 0 });
+  });
+});
+
+describe("parseAdoptionCommands (#2105)", () => {
+  // The row shape `StatelessAdoptionHuman.adoptionSection` prints: the address
+  // line, then indented detail lines.
+  const RENDER = [
+    "",
+    "Adoptable now: 2 resource instances",
+    "",
+    "Each of these is a live resource this run found at a declared resource's identity.",
+    "",
+    "  aws_vpc.main <- aws_vpc vpc-0abc",
+    "      matched on: cidr_block=10.0.0.0/16",
+    "      adopt with: aws ec2 create-tags --resources 'vpc-0abc' --tags 'Key=tofu-estate,Value=prod'",
+    "      or write: tofu-estate=prod tofu-address=aws_vpc.main",
+    "  aws_iam_role.app <- aws_iam_role app-role",
+    "      or write: tofu-estate=prod tofu-address=aws_iam_role.app",
+    "",
+  ].join("\n");
+
+  test("pairs each address with the command printed under it", () => {
+    expect(parseAdoptionCommands(RENDER).get("aws_vpc.main")).toBe(
+      "aws ec2 create-tags --resources 'vpc-0abc' --tags 'Key=tofu-estate,Value=prod'",
+    );
+  });
+
+  test("an address with no printed command is absent, not empty", () => {
+    // IAM has its own tagging call, which choudoufu does not spell out.
+    const commands = parseAdoptionCommands(RENDER);
+    expect(commands.has("aws_iam_role.app")).toBe(false);
+    expect(commands.size).toBe(1);
+  });
+
+  test("a render with no adoptable section yields nothing", () => {
+    expect(parseAdoptionCommands("Adoption: 3 declared resource instances\n\nNo changes.\n").size).toBe(0);
+  });
+});
+
+describe("renderAdoptionLedger (#2105)", () => {
+  test("one line per adoptable match, carrying the address, identity and both marker values", () => {
+    const text = renderAdoptionLedger(
+      readAdoptionLedger({ unowned: [adoptable("aws_vpc.main", "vpc-0abc")] }),
+      "prod-networking",
+    );
+    expect(text).toContain(
+      "  aws_vpc.main <- aws_vpc vpc-0abc  write: tofu-estate=prod-networking tofu-address=aws_vpc.main",
+    );
+    expect(text).toContain('Adoptable now: 1 live resource, estate "prod-networking"');
+  });
+
+  test("an empty ledger still says so, rather than rendering nothing", () => {
+    const text = renderAdoptionLedger(readAdoptionLedger({ unowned: [] }), "prod-networking");
+    expect(text).toContain("Adoptable now: nothing");
+  });
+
+  test("contested addresses are listed under their own heading with no marker values offered", () => {
+    const text = renderAdoptionLedger(
+      readAdoptionLedger({ unowned: [adoptable("aws_vpc.main", "vpc-0abc"), adoptable("aws_vpc.main", "vpc-0def")] }),
+      "prod-networking",
+    );
+    expect(text).toContain("Ambiguous: 1 declared address with more than one candidate");
+    expect(text).toContain("  aws_vpc.main <- aws_vpc vpc-0abc");
+    expect(text).toContain("  aws_vpc.main <- aws_vpc vpc-0def");
+    // Nothing in the contested block offers a write: there is no single one.
+    const contestedBlock = text.slice(text.indexOf("Ambiguous:"));
+    expect(contestedBlock).not.toContain("write: tofu-estate=");
+  });
+
+  test("nothing outside the unowned section reaches the rendering", () => {
+    // The document carries every declared instance the plan bound and every
+    // one it could not read, with identities and reasons. The ledger is a
+    // projection of `unowned` alone, and this is what says so.
+    const document = {
+      unowned: [adoptable("aws_vpc.main", "vpc-0abc")],
+      bound: [{ addr: "aws_db_instance.prod", identity: "prod-db-0f1e2d3c" }],
+      omissions: [{ addr: "aws_kms_key.signing", detail: "provider error" }],
+    };
+    const text = renderAdoptionLedger(readAdoptionLedger(document), "prod-networking");
+    expect(text).not.toContain("aws_db_instance.prod");
+    expect(text).not.toContain("prod-db-0f1e2d3c");
+    expect(text).not.toContain("aws_kms_key.signing");
+    expect(text).not.toContain("adopt_tofu_estate");
+  });
+});