@intentius/chant-lexicon-terraform 0.59.0 → 0.61.0

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

@@ -277,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 -json document moved to v0.14.0", async () => {
+  test("refuses a binary older than the floor, which the adoptable section moved to v0.15.0", async () => {
     const dir = liveProject();
-    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/);
+    replies.push({ match: "version", reply: { stdout: "choudoufu v0.14.0 (based on OpenTofu v1.13.0)\n", stderr: "" } });
+    await expect(choudoufuLiveCheck({ root: "estate", cwd: dir })).rejects.toThrow(/older than.*v0\.15\.0/);
   });
 
   test("passes at exactly the minimum version", async () => {

package/src/op/activities/terraform.ts

@@ -81,11 +81,20 @@ export const DEFAULT_LIVE_PLAN_DOCUMENT_FILE = "chant.live-plan.json";
  * 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.
+ * all. v0.15.0 brought the document's `adoptable` section and the `swept`
+ * list beside it
+ * ([choudoufu #962](https://github.com/INTENTIUS/choudoufu/issues/962), PR
+ * 963), which is the only place a content match reaches a machine: before it,
+ * a declared resource whose identity the provider assigns could never be
+ * adopted through the document at all, and `TerraformAdoptOp`'s own
+ * acceptance suite had never passed on any binary (#2241).
+ *
+ * {@link terraformApply} depends on the exit-3 refusal, `describeResources()`
+ * and both document-reading Ops depend on the document, and the adopt path
+ * depends on the `adoptable` section, so the floor is the release that
+ * shipped the last of the three.
  */
-export const MIN_CHOUDOUFU_VERSION = "0.14.0";
+export const MIN_CHOUDOUFU_VERSION = "0.15.0";
 
 /**
  * choudoufu's own refusal summary for `-out` on the `live-plan -estate`
@@ -185,6 +194,12 @@ export interface ChoudoufuLivePlanArgs extends TerraformRootArgs {
    * cost is that the second read asks the estate-wide sweep the account-bounded
    * question ("which live resources carry no ownership marker at all"), so it
    * is slower than the ordinary render, not faster.
+   *
+   * Since #2241 the flag also puts `TOFU_LIVE_COLLECT_UNCLAIMED=1` on the
+   * `-json` run, so the document carries the same sweep's answer as its
+   * `adoptable` and `swept` sections rather than only the render carrying it.
+   * That is what an adoption reads: the render's rows are prose, and the
+   * document's are addresses, marker values and a tagging command.
    */
   adoptionOnly?: boolean;
 }
@@ -276,11 +291,22 @@ export interface TerraformApplyResult {
   refusal?: string;
 }
 
-/** Counts projected out of `live-plan -json`'s `unowned` section. */
+/** Counts projected out of `live-plan -json`'s `unowned` and `adoptable` sections. */
 export interface LivePlanUnownedCounts {
-  /** Live resources at a declared identity carrying no ownership marker for this estate. */
+  /**
+   * `unowned[]`'s length: live resources sitting at an identity this
+   * configuration declares, carrying no ownership marker for this estate.
+   */
   unowned: number;
-  /** Of those, how many an exact content match makes adoptable. */
+  /**
+   * Every live resource this run could claim with a tag write, from both
+   * sections: the `unowned[]` rows choudoufu offered marker values for, plus
+   * the `adoptable[]` rows the estate-wide sweep content-matched to a
+   * declaration that carries no identity of its own (choudoufu #962). Those
+   * two sections are disjoint, so this is a sum and never a double count.
+   * `adoptable[]` is populated only on an adoption run (#2241), so an
+   * observation read's document contributes nothing to it.
+   */
   adoptable: number;
 }
 
@@ -306,7 +332,10 @@ export interface LivePlanUnownedCounts {
 export interface ChoudoufuLivePlanResult extends LivePlanUnownedCounts, PlanChangeCounts {
   /** `true` when `-detailed-exitcode` reported exit 2: the live plan proposes changes. */
   drift: boolean;
-  /** GitHub issue #788's JSON document (`bound`, `omissions`, `unowned`), captured whole. */
+  /**
+   * GitHub issue #788's JSON document (`bound`, `omissions`, `unowned`, and
+   * since choudoufu v0.15.0 `adoptable` and `swept`), captured whole.
+   */
   json: unknown;
   /**
    * The human-readable plan, from a second `live-plan` run without `-json`
@@ -334,6 +363,13 @@ export interface ChoudoufuLivePlanResult extends LivePlanUnownedCounts, PlanChan
   contested: AdoptionCandidate[];
   /** How many declared addresses are contested — the count `contested` above spells out. */
   ambiguous: number;
+  /**
+   * `swept[]`: the resource types the estate-wide sweep listed in full on this
+   * run. Empty on any run that did not ask for the sweep, which is every run
+   * without {@link ChoudoufuLivePlanArgs.adoptionOnly}, so an empty
+   * `adoptions` beside an empty `swept` means the question was never put.
+   */
+  swept: string[];
   /** Absolute path of the root module directory. */
   dir: string;
   /** Where the JSON document was written, relative to `dir`; {@link DEFAULT_LIVE_PLAN_DOCUMENT_FILE} unless overridden. */
@@ -549,14 +585,14 @@ export function choudoufuLiveCheckCommand(opts: { binary: string }): string {
  * (`adopt_tofu_estate`/`adopt_tofu_address` present).
  */
 export function countLivePlanUnowned(document: unknown): LivePlanUnownedCounts {
-  const unowned = (document as { unowned?: unknown } | null | undefined)?.unowned;
-  if (!Array.isArray(unowned)) return { unowned: 0, adoptable: 0 };
-  let adoptable = 0;
-  for (const entry of unowned) {
+  const doc = (document ?? {}) as { unowned?: unknown; adoptable?: unknown };
+  const unowned = Array.isArray(doc.unowned) ? doc.unowned : [];
+  const claimable = (entry: unknown): boolean => {
     const e = entry as { adopt_tofu_estate?: unknown; adopt_tofu_address?: unknown } | null | undefined;
-    if (e?.adopt_tofu_estate || e?.adopt_tofu_address) adoptable++;
-  }
-  return { unowned: unowned.length, adoptable };
+    return Boolean(e?.adopt_tofu_estate || e?.adopt_tofu_address);
+  };
+  const matched = Array.isArray(doc.adoptable) ? doc.adoptable.filter(claimable).length : 0;
+  return { unowned: unowned.length, adoptable: unowned.filter(claimable).length + matched };
 }
 
 /**
@@ -665,8 +701,8 @@ async function ensureChoudoufuVersion(binary: string, signal?: AbortSignal): Pro
     if (isOlderVersion(version, MIN_CHOUDOUFU_VERSION)) {
       throw new Error(
         `choudoufu ${version} is older than the minimum supported version v${MIN_CHOUDOUFU_VERSION} ` +
-          "(needed for live-plan -json, live-ls, live-check -json, and the approval artifact `plan -out` / " +
-          "`apply <planfile>` pair). Upgrade choudoufu.",
+          "(needed for live-plan -json, live-ls, live-check -json, the approval artifact `plan -out` / " +
+          "`apply <planfile>` pair, and the document's adoptable section). Upgrade choudoufu.",
       );
     }
   })();
@@ -1011,8 +1047,17 @@ export async function choudoufuLivePlan(
   let drift: boolean;
   let jsonStdout: string;
   const planCmd = choudoufuLivePlanCommand({ binary, ...estateFlag, json: true });
+  // The document's `adoptable` and `swept` sections are populated only on a
+  // run that asked the estate-wide sweep the account-bounded question, which
+  // `-adoption-only` implies and a `-json` run does not
+  // (`internal/command/live_collect_unclaimed.go`). `-adoption-only` cannot
+  // ride the `-json` invocation, so the env var is how a document-producing
+  // run asks for the same thing. Set only under `adoptionOnly`: the sweep is
+  // an account-wide list per admitted type, and an observation read has no use
+  // for it.
+  const planEnv = args.adoptionOnly ? { ...env, TOFU_LIVE_COLLECT_UNCLAIMED: "1" } : env;
   try {
-    const { stdout, stderr } = await run(planCmd, dir, env, signal);
+    const { stdout, stderr } = await run(planCmd, dir, planEnv, signal);
     report(stdout, stderr);
     drift = false;
     jsonStdout = stdout;
@@ -1069,9 +1114,12 @@ export async function choudoufuLivePlan(
 
   writeFileSync(join(dir, documentPath), document);
 
-  // The adoption commands only exist in the `-adoption-only` render, so a
-  // candidate off an ordinary run carries the two marker values and no
-  // command — which is the whole ownership contract either way.
+  // An `adoptable[]` row carries its own tagging command in the document
+  // (choudoufu #962). An `unowned[]` row does not, and the render is the only
+  // place one is printed for it, so the parse still runs on an adoption run
+  // and the map still feeds that half. A candidate off an ordinary run carries
+  // the two marker values and no command, which is the whole ownership
+  // contract either way.
   const ledger = readAdoptionLedger(json, args.adoptionOnly ? parseAdoptionCommands(text) : undefined);
   const ledgerText = renderAdoptionLedger(ledger, estate);
 
@@ -1084,6 +1132,7 @@ export async function choudoufuLivePlan(
     adoptions: ledger.adoptions,
     contested: ledger.contested,
     ambiguous: ledger.ambiguous,
+    swept: ledger.swept,
     dir,
     documentPath,
     estate,

package/src/op/adoption.test.ts

@@ -1,14 +1,22 @@
 /**
- * The adoption ledger (#2105): reading `live-plan -json`'s `unowned` section,
- * pairing it with the commands `-adoption-only` printed, and rendering it.
+ * The adoption ledger (#2105, #2241): reading `live-plan -json`'s `unowned`
+ * and `adoptable` sections, pairing the first with the commands
+ * `-adoption-only` printed, and rendering both.
  *
  * 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.
+ * from `views.StatelessUnowned` and `views.LivePlanAdoptable`'s json tags
+ * (`internal/command/live_plan.go`) and checked against the recorded document
+ * next door: 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.
+ *
+ * The last block reads `../__fixtures__/live-plan.json` itself, so the
+ * `adoptable` half is proved against a real v0.15.0 document rather than
+ * against a literal a test author typed.
  */
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { describe, test, expect } from "vitest";
 import { parseAdoptionCommands, readAdoptionLedger, renderAdoptionLedger } from "./adoption";
 
@@ -79,10 +87,110 @@ describe("readAdoptionLedger (#2105)", () => {
     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 });
+  test("a document with neither section, or none at all, is an empty ledger", () => {
+    const empty = { adoptions: [], contested: [], ambiguous: 0, swept: [] };
+    expect(readAdoptionLedger({ bound: [] })).toEqual(empty);
+    expect(readAdoptionLedger(undefined)).toEqual(empty);
+    expect(readAdoptionLedger({ unowned: "not a list", adoptable: 7, swept: "aws_vpc" })).toEqual(empty);
+  });
+});
+
+describe("readAdoptionLedger over the adoptable section (choudoufu #962, #2241)", () => {
+  const matched = (addr: string, identity: string) => ({
+    addr,
+    type: "aws_vpc",
+    identity,
+    matched: [{ attribute: "cidr_block", value: "10.77.0.0/16" }],
+    adopt_tofu_estate: "prod-networking",
+    adopt_tofu_address: addr,
+    adopt_command: `aws ec2 create-tags --resources '${identity}'`,
+  });
+
+  test("a content match is a candidate carrying its own command and what it matched on", () => {
+    const ledger = readAdoptionLedger({ unowned: [], adoptable: [matched("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",
+        command: "aws ec2 create-tags --resources 'vpc-0abc'",
+        matched: [{ attribute: "cidr_block", value: "10.77.0.0/16" }],
+      },
+    ]);
+  });
+
+  test("the document's own command wins: no render is parsed for this half", () => {
+    const ledger = readAdoptionLedger(
+      { adoptable: [matched("aws_vpc.main", "vpc-0abc")] },
+      new Map([["aws_vpc.main", "a command scraped off the render"]]),
+    );
+    expect(ledger.adoptions[0].command).toBe("aws ec2 create-tags --resources 'vpc-0abc'");
+  });
+
+  test("both sections feed one ledger, and one address in both is contested", () => {
+    const ledger = readAdoptionLedger({
+      unowned: [adoptable("aws_cloudwatch_log_group.app", "/estate/app", "aws_cloudwatch_log_group")],
+      adoptable: [matched("aws_vpc.main", "vpc-0abc"), matched("aws_cloudwatch_log_group.app", "/estate/app")],
+    });
+    expect(ledger.adoptions.map((c) => c.addr)).toEqual(["aws_vpc.main"]);
+    expect(ledger.contested.map((c) => c.addr)).toEqual([
+      "aws_cloudwatch_log_group.app",
+      "aws_cloudwatch_log_group.app",
+    ]);
+    expect(ledger.ambiguous).toBe(1);
+  });
+
+  test("swept comes back so an empty ledger can say which empty it is", () => {
+    expect(readAdoptionLedger({ swept: ["aws_vpc", 7, "aws_subnet"] }).swept).toEqual(["aws_vpc", "aws_subnet"]);
+    expect(readAdoptionLedger({ unowned: [] }).swept).toEqual([]);
+  });
+});
+
+describe("readAdoptionLedger over the recorded v0.15.0 document (#2241)", () => {
+  const document: unknown = JSON.parse(
+    readFileSync(join(import.meta.dirname, "..", "__fixtures__", "live-plan.json"), "utf-8"),
+  );
+  const ledger = readAdoptionLedger(document);
+
+  test("both halves of the real document reach the ledger", () => {
+    // The log group's identity is the name in its own block, so choudoufu read
+    // it and put it in `unowned[]`. The VPC's is assigned by EC2, so the sweep
+    // content-matched it and put it in `adoptable[]`. One ledger, both rows.
+    expect(ledger.adoptions.map((c) => c.addr).sort()).toEqual([
+      "aws_cloudwatch_log_group.adoptable",
+      "aws_vpc.adoptable",
+    ]);
+    expect(ledger.contested).toEqual([]);
+  });
+
+  test("the content match carries the cidr it rested on and choudoufu's own tagging command", () => {
+    const vpc = ledger.adoptions.find((c) => c.addr === "aws_vpc.adoptable")!;
+    expect(vpc.type).toBe("aws_vpc");
+    expect(vpc.identity).toMatch(/^vpc-/);
+    expect(vpc.markerEstate).toBe("stateless-e2e-block");
+    expect(vpc.markerAddress).toBe("aws_vpc.adoptable");
+    expect(vpc.matched).toEqual([{ attribute: "cidr_block", value: "10.88.0.0/16" }]);
+    expect(vpc.command).toContain("aws ec2 create-tags");
+  });
+
+  test("the declared-identity row carries no match and no command of its own", () => {
+    // `views.StatelessUnowned` has no command field, which is why
+    // `parseAdoptionCommands` still exists for this half alone.
+    const log = ledger.adoptions.find((c) => c.addr === "aws_cloudwatch_log_group.adoptable")!;
+    expect(log.matched).toBeUndefined();
+    expect(log.command).toBeUndefined();
+  });
+
+  test("the sweep's type list rides along, so nothing here is silence", () => {
+    expect(ledger.swept).toContain("aws_vpc");
+  });
+
+  test("the rendering names the match under its row", () => {
+    const text = renderAdoptionLedger(ledger, "stateless-e2e-block");
+    expect(text).toContain("Adoptable now: 2 live resources");
+    expect(text).toContain("      matched on: cidr_block=10.88.0.0/16");
   });
 });
 
@@ -139,6 +247,16 @@ describe("renderAdoptionLedger (#2105)", () => {
     expect(text).toContain("Adoptable now: nothing");
   });
 
+  test("an empty ledger off a run that swept nothing says it did not look", () => {
+    // The difference choudoufu's own view draws, and the reason `swept` is
+    // carried at all: no sweep means no answer, which is not the same answer
+    // as "nothing to adopt".
+    expect(renderAdoptionLedger(readAdoptionLedger({ unowned: [] }))).toContain("No estate-wide sweep ran");
+    expect(renderAdoptionLedger(readAdoptionLedger({ unowned: [], swept: ["aws_vpc"] }))).toContain(
+      "across 1 swept resource type (aws_vpc)",
+    );
+  });
+
   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")] }),
@@ -152,7 +270,7 @@ describe("renderAdoptionLedger (#2105)", () => {
     expect(contestedBlock).not.toContain("write: tofu-estate=");
   });
 
-  test("nothing outside the unowned section reaches the rendering", () => {
+  test("nothing outside the two adoption sections 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.