@intentius/chant-lexicon-terraform 0.60.0 → 0.62.0

package/src/describe-resources.ts

@@ -13,6 +13,34 @@
  * and the marker on the resource is the ownership answer. The two halves are
  * two adapters over the same `observeEntities` harness, picked per root.
  *
+ * ## Which of the two answered is on the wire (#2267)
+ *
+ * They are different claims. `terraform show -json` says what the last apply
+ * recorded; `choudoufu live-plan -json` says what the account holds now. A
+ * renderer that paints an observation as drift and cannot tell them apart
+ * paints a state read green, which reads as "the account matches" when all it
+ * says is "the apply finished". For an estate that has decided state is never
+ * the system of record, a state-backed observation is not a weaker answer, it
+ * is a different one.
+ *
+ * So the returned `ObservationResult` carries `sources`, keyed by chant entity
+ * name, with one of exactly two values:
+ *
+ * - `"state"` — this entity's root was read with `terraform show -json`.
+ * - `"live"` — this entity's root was read with `choudoufu live-plan -json`.
+ *
+ * Three guarantees a consumer may rely on. Every entity `describeResources`
+ * was asked about that belongs to a root has an entry, whatever verdict it
+ * came back with: present, absent and not-observed alike, because which read
+ * was attempted is a fact independent of what it found. The value equals the
+ * declared entity's own `props.mode` (`./hcl/parse.ts`), since one fact
+ * decides both, so `props.mode` is also a valid join key for a consumer
+ * holding the declared graph and no observation. And a project mixing stock
+ * and live roots gets both values in one document, which is why this is a map
+ * and not a field on the result as a whole.
+ *
+ * An entity with no root gets no entry, for the same reason it gets no read.
+ *
  * ## The state file is the ownership answer, on a stock root
  *
  * Every other lexicon in chant stamps a tag or a label at synthesis and reads
@@ -54,6 +82,7 @@
  * | `bound[]`, any other source | present, `owned` by derivation, record, or cache; noted as such, and no marker is surfaced because none was read |
  * | `unowned[]` with `adopt_*` | present, `unknown`; an adoptable match, carrying the exact two tag values #2105 would write |
  * | `unowned[]` without | present, `foreign`; a live resource is in the way at a declared identity and the plan will not touch it |
+ * | `adoptable[]` | present, `unknown`; the same adoptable verdict, for a live resource the sweep content-matched to a declaration that carries no identity of its own (choudoufu #962, chant #2241) |
  * | `omissions[]` | not-observed, `ABSENT` excepted (see below) |
  *
  * The ownership channel this declares is `./live-ownership.ts`'s
@@ -282,6 +311,27 @@ export interface LivePlanUnownedRow {
   adoptAddress?: string;
 }
 
+/**
+ * One `adoptable[]` entry: a live resource the estate-wide sweep matched to a
+ * declared instance by content rather than by reading a declared identity
+ * (choudoufu #962). The declaration names no identity at all, so this is the
+ * only row the document has for it and the paired omission says
+ * `NEEDS_DISCOVERY`.
+ *
+ * Same fields as {@link LivePlanUnownedRow} minus `heldBy`, which cannot
+ * apply: a row here carries no marker for any estate, or the sweep would have
+ * called it foreign instead of unclaimed.
+ */
+export interface LivePlanAdoptableRow {
+  addr: string;
+  type?: string;
+  identity?: string;
+  adoptEstate?: string;
+  adoptAddress?: string;
+  /** `matched[]`: the arguments the declaration and the live resource agreed on exactly. */
+  matched?: Array<{ attribute: string; value: string }>;
+}
+
 /** A `live-plan -json` document, indexed by declared instance address. */
 export interface LivePlanIndex {
   /** `estate`: the estate every section was computed against. */
@@ -289,6 +339,13 @@ export interface LivePlanIndex {
   bound: Map<string, LivePlanBoundRow>;
   omissions: Map<string, LivePlanOmissionRow>;
   unowned: Map<string, LivePlanUnownedRow>;
+  adoptable: Map<string, LivePlanAdoptableRow>;
+  /**
+   * `swept[]`: the resource types the estate-wide sweep listed in full. Empty
+   * on every observation read, which asks for no sweep, so an empty
+   * `adoptable` beside it says nothing was asked rather than nothing found.
+   */
+  swept: string[];
   /** Every address any section named, so a block can find its own instances. */
   addresses: string[];
   /** `diagnostics[]` summaries, for the observation's run-level notes. */
@@ -307,6 +364,8 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
     bound: new Map(),
     omissions: new Map(),
     unowned: new Map(),
+    adoptable: new Map(),
+    swept: asArray(doc.swept).filter((t): t is string => typeof t === "string"),
     addresses: [],
     diagnostics: [],
   };
@@ -348,6 +407,24 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
     });
   }
 
+  for (const entry of asArray(doc.adoptable)) {
+    const row = asRecord(entry);
+    const addr = asString(row.addr);
+    if (!addr) continue;
+    const matched = asArray(row.matched)
+      .map((m) => asRecord(m))
+      .filter((m) => asString(m.attribute))
+      .map((m) => ({ attribute: asString(m.attribute)!, value: asString(m.value) ?? "" }));
+    index.adoptable.set(addr, {
+      addr,
+      ...(asString(row.type) ? { type: asString(row.type) } : {}),
+      ...(asString(row.identity) ? { identity: asString(row.identity) } : {}),
+      ...(asString(row.adopt_tofu_estate) ? { adoptEstate: asString(row.adopt_tofu_estate) } : {}),
+      ...(asString(row.adopt_tofu_address) ? { adoptAddress: asString(row.adopt_tofu_address) } : {}),
+      ...(matched.length > 0 ? { matched } : {}),
+    });
+  }
+
   for (const entry of asArray(doc.diagnostics)) {
     const row = asRecord(entry);
     const summary = asString(row.summary);
@@ -355,7 +432,12 @@ export function indexLivePlan(document: unknown): LivePlanIndex {
   }
 
   index.addresses = [
-    ...new Set([...index.bound.keys(), ...index.omissions.keys(), ...index.unowned.keys()]),
+    ...new Set([
+      ...index.bound.keys(),
+      ...index.omissions.keys(),
+      ...index.unowned.keys(),
+      ...index.adoptable.keys(),
+    ]),
   ].sort();
   return index;
 }
@@ -419,7 +501,7 @@ function liveModuleMembers(address: string, index: LivePlanIndex): string[] {
 /** One instance's verdict, before a block aggregates its instances. */
 type InstanceVerdict =
   | { kind: "owned"; row: LivePlanBoundRow }
-  | { kind: "adoptable"; row: LivePlanUnownedRow }
+  | { kind: "adoptable"; row: LivePlanAdoptableRow }
   | { kind: "foreign"; row: LivePlanUnownedRow }
   | { kind: "absent" }
   | { kind: "unobserved"; reason: UnobservedReason; detail: string };
@@ -428,6 +510,11 @@ type InstanceVerdict =
  * Classify one instance address against the document, `unowned[]` first: a
  * declared instance that also carries a `UNOWNED` omission is answered by the
  * section that has the verdict, not by the one that has the apology.
+ * `adoptable[]` sits under `bound[]` for the same reason, one rung further
+ * down: a content match is the answer for an instance nothing else could
+ * answer for, and its paired omission is always `NEEDS_DISCOVERY`, which on
+ * its own would read as unsupported-kind and hide a real, actionable verdict
+ * (choudoufu #962, chant #2241).
  */
 function classifyLiveInstance(address: string, index: LivePlanIndex): InstanceVerdict {
   const unowned = index.unowned.get(address);
@@ -440,6 +527,11 @@ function classifyLiveInstance(address: string, index: LivePlanIndex): InstanceVe
   const bound = index.bound.get(address);
   if (bound) return { kind: "owned", row: bound };
 
+  const matched = index.adoptable.get(address);
+  if (matched && (matched.adoptEstate || matched.adoptAddress)) {
+    return { kind: "adoptable", row: matched };
+  }
+
   const omission = index.omissions.get(address);
   if (omission) {
     const verdict = omissionVerdict(omission);
@@ -516,6 +608,13 @@ function readLiveResource(
           ...(adoptable.row.type ? { resourceType: adoptable.row.type } : {}),
           ...(adoptable.row.adoptEstate ? { adoptTofuEstate: adoptable.row.adoptEstate } : {}),
           ...(adoptable.row.adoptAddress ? { adoptTofuAddress: adoptable.row.adoptAddress } : {}),
+          // Present only on a content match: the arguments the sweep compared,
+          // which is the whole evidence for a match nobody read an identity
+          // for, and the thing an operator checks before letting a tag write
+          // claim the resource.
+          ...(adoptable.row.matched?.length
+            ? { matchedOn: adoptable.row.matched.map((m) => `${m.attribute}=${m.value}`) }
+            : {}),
         },
       },
       queried,
@@ -1091,12 +1190,20 @@ export async function describeResources(
 
   const parts = [];
   const notes: string[] = [];
+  // Which of the two reads answered, per entity (#2267). Filled for every
+  // entity of the root before the read runs, so the answer is on the wire
+  // whatever the verdict came back as: present, absent, or not-observed. A
+  // renderer joins observations to nodes, and painting `terraform show -json`
+  // over state the same green as a live read of the account is the drift lie
+  // an overlay exists to prevent.
+  const sources: Record<string, string> = {};
   for (const [root, declared] of byRoot) {
     // One fact decides the whole read, and the parse already recorded it on
     // every entity of the root (#2103). A root is live when its binary is
     // choudoufu AND it declares an estate, so a single entity carrying
     // `mode: "live"` settles it for the root.
     const live = declared.some((entity) => entity.mode === "live");
+    for (const entity of declared) sources[entity.name] = live ? "live" : "state";
     if (live) {
       notes.push(
         `terraform.roots.${root} is a live root: ownership came from choudoufu's tofu-estate/tofu-address markers via \`live-plan -json\`, not from a state file`,
@@ -1136,5 +1243,5 @@ export async function describeResources(
     }
   }
 
-  return observation(resources, unobserved, merged.queried, merged.notes);
+  return observation(resources, unobserved, merged.queried, merged.notes, undefined, sources);
 }

package/src/hcl/edges.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Reference resolution and the graph IR it feeds (chant #2265, #2266).
+ *
+ * Everything here goes through `renderTerraformRoots` and then core's own
+ * `buildGraphIr`, which is the exact pair `chant graph --format ir` runs, so
+ * what is asserted is what a renderer receives. The fixture is
+ * `src/__fixtures__/graph-roots/`: two roots, a local child module, and one
+ * instance of every decision these issues asked to have pinned.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildGraphIr, entityReferences, entityStack, type IREdge } from "@intentius/chant/graph-ir";
+import type { Declarable } from "@intentius/chant/declarable";
+import { renderTerraformRoots } from "./roots";
+import { referenceFromAccessor } from "./edges";
+import type { TerraformEntity } from "./parse";
+
+const TREE = join(dirname(fileURLToPath(import.meta.url)), "..", "__fixtures__", "graph-roots");
+
+let entities: Map<string, Declarable>;
+let edges: IREdge[];
+let groups: ReturnType<typeof buildGraphIr>["groups"];
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({
+    projectRoot: TREE,
+    roots: { app: { dir: "./app" }, network: { dir: "./network" } },
+  });
+  expect(rendered.warnings).toEqual([]);
+  entities = rendered.entities;
+  const ir = buildGraphIr(entities);
+  edges = ir.edges;
+  groups = ir.groups;
+});
+
+/** The edge between two nodes through one consumer attribute, if there is one. */
+function edge(from: string, to: string, viaAttr: string): IREdge | undefined {
+  return edges.find((e) => e.from === from && e.to === to && e.viaAttr === viaAttr);
+}
+
+describe("referenceFromAccessor", () => {
+  it("classifies every form that becomes an edge", () => {
+    expect(referenceFromAccessor("aws_vpc.main.id")).toEqual({ address: "aws_vpc.main", attr: "id" });
+    expect(referenceFromAccessor("module.cdn.url")).toEqual({ address: "module.cdn", attr: "url" });
+    expect(referenceFromAccessor("data.aws_ami.ubuntu.id")).toEqual({
+      address: "data.aws_ami.ubuntu",
+      attr: "id",
+    });
+    expect(referenceFromAccessor("var.region")).toEqual({ address: "var.region" });
+    expect(referenceFromAccessor("local.tags")).toEqual({ address: "local.tags" });
+  });
+
+  it("reads no reference out of the meta-arguments that are not one", () => {
+    // `count.index`, `each.value`, `path.module`, `terraform.workspace` and
+    // `self.x` all look like `<head>.<name>` and none of them names a block.
+    expect(referenceFromAccessor("count.index")).toBeUndefined();
+    expect(referenceFromAccessor("each.value")).toBeUndefined();
+    expect(referenceFromAccessor("path.module")).toBeUndefined();
+    expect(referenceFromAccessor("terraform.workspace")).toBeUndefined();
+    expect(referenceFromAccessor("self.private_ip")).toBeUndefined();
+  });
+});
+
+describe("edges out of a parsed estate (#2265)", () => {
+  it("emits the whole edge set, and only it", () => {
+    expect(
+      edges.map((e) => [e.from, e.to, e.viaAttr ?? "", e.toAttr ?? ""].join(" ")),
+    ).toEqual([
+      "app/aws_instance.web app/aws_s3_bucket.assets depends_on ",
+      "app/aws_instance.web app/data.aws_iam_policy.boundary tags arn",
+      "app/aws_instance.web app/module.cdn depends_on ",
+      "app/aws_instance.web app/var.subnets count ",
+      "app/aws_instance.web app/var.subnets subnet_id ",
+      "app/module.cdn/aws_cloudfront_distribution.cdn app/module.cdn/var.bucket origin_id ",
+      "app/module.cdn app/aws_s3_bucket.assets bucket id",
+      "app/output.cdn_url app/module.cdn value url",
+      "app/provider.aws app/var.region region ",
+      "network/aws_vpc.main network/locals tags ",
+      "network/aws_vpc.main network/var.cidr cidr_block ",
+      "network/output.vpc_id network/aws_vpc.main value id",
+    ]);
+  });
+
+  it("makes a `module` reference an edge to the call block, in both directions of use", () => {
+    // The call reads a resource; an output reads the call.
+    expect(edge("app/module.cdn", "app/aws_s3_bucket.assets", "bucket")).toEqual({
+      from: "app/module.cdn",
+      to: "app/aws_s3_bucket.assets",
+      kind: "ref",
+      viaAttr: "bucket",
+      toAttr: "id",
+    });
+    expect(edge("app/output.cdn_url", "app/module.cdn", "value")?.toAttr).toBe("url");
+  });
+
+  it("makes `depends_on` an edge with no producer attribute", () => {
+    const ordering = edges.filter((e) => e.viaAttr === "depends_on");
+    expect(ordering.map((e) => e.to).sort()).toEqual(["app/aws_s3_bucket.assets", "app/module.cdn"]);
+    for (const e of ordering) expect(e.toAttr).toBeUndefined();
+  });
+
+  it("keeps a `count` block one node, and its edges block-to-block", () => {
+    const web = entities.get("app/aws_instance.web") as TerraformEntity;
+    // `count = length(var.subnets)` over a list: the declaration is one block,
+    // so it is one node whatever the count evaluates to, and the expansion is
+    // recorded rather than left to be inferred from a node count.
+    expect(web.props.expansion).toBe("count");
+    expect([...entities.keys()].filter((k) => k.startsWith("app/aws_instance.web"))).toEqual([
+      "app/aws_instance.web",
+    ]);
+    // The meta-argument is an expression like any other, so it carries an edge.
+    expect(edge("app/aws_instance.web", "app/var.subnets", "count")).toBeDefined();
+    // ...and reading `var.subnets[count.index]` elsewhere in the block is a
+    // second edge through a second attribute, not a second instance.
+    expect(edge("app/aws_instance.web", "app/var.subnets", "subnet_id")).toBeDefined();
+  });
+
+  it("makes `var` and `local` edges, and resolves a local to the block that declares it", () => {
+    expect(edge("network/aws_vpc.main", "network/var.cidr", "cidr_block")).toBeDefined();
+    expect(edge("network/aws_vpc.main", "network/locals", "tags")).toBeDefined();
+  });
+
+  it("names the consumer attribute on every edge and the producer attribute only when one was read", () => {
+    for (const e of edges) expect(e.viaAttr).toBeTruthy();
+    // `data.aws_iam_policy.boundary.arn` named exactly one producer attribute.
+    expect(edge("app/aws_instance.web", "app/data.aws_iam_policy.boundary", "tags")?.toAttr).toBe("arn");
+    // `[aws_s3_bucket.assets]` named none.
+    expect(edge("app/aws_instance.web", "app/aws_s3_bucket.assets", "depends_on")?.toAttr).toBeUndefined();
+  });
+
+  it("resolves a child module's references inside the child's own scope", () => {
+    // `var.bucket` in `module.cdn` is the CHILD's variable. The root declares
+    // no `var.bucket` at all, so a scope-blind resolution would have produced
+    // no edge here rather than the wrong one; the assertion that matters is
+    // that the edge lands on the child's key.
+    expect(
+      edge(
+        "app/module.cdn/aws_cloudfront_distribution.cdn",
+        "app/module.cdn/var.bucket",
+        "origin_id",
+      ),
+    ).toBeDefined();
+  });
+
+  it("draws no edge for a `provider` meta-argument", () => {
+    // `provider = aws.replica` names a block by type AND alias, which this
+    // lexicon's `provider.<type>` key cannot be resolved to without guessing.
+    expect(edges.some((e) => e.viaAttr === "provider")).toBe(false);
+  });
+
+  it("draws no edge between two roots", () => {
+    const rootOf = (id: string): string => id.split("/")[0];
+    for (const e of edges) expect(rootOf(e.from)).toBe(rootOf(e.to));
+  });
+
+  it("publishes the references on the entity, in core's lexicon-neutral shape", () => {
+    // The channel core reads (#2265): an entity key, plus the two attribute
+    // names `IREdge` carries. Nothing terraform-shaped crosses the boundary.
+    expect(entityReferences(entities.get("app/output.cdn_url")!)).toEqual([
+      { to: "app/module.cdn", viaAttr: "value", toAttr: "url" },
+    ]);
+    // An entity that references nothing carries no channel at all.
+    expect(entityReferences(entities.get("app/var.region")!)).toEqual([]);
+  });
+
+  it("drops a reference to something outside the graph rather than dangling it", () => {
+    // Only ids that are nodes become edges, so an entity key that never made
+    // it into the IR cannot leave a half-edge behind.
+    const ids = new Set([...entities.keys()]);
+    for (const e of edges) {
+      expect(ids.has(e.from)).toBe(true);
+      expect(ids.has(e.to)).toBe(true);
+    }
+  });
+});
+
+describe("grouping by root (#2266)", () => {
+  it("keys byStack by root name, one entry per declared root", () => {
+    expect(Object.keys(groups.byStack ?? {})).toEqual(["app", "network"]);
+    expect(groups.byStack?.["network"]).toEqual([
+      "network/aws_vpc.main",
+      "network/locals",
+      "network/output.vpc_id",
+      "network/var.cidr",
+    ]);
+  });
+
+  it("keeps byLexicon saying terraform", () => {
+    expect(Object.keys(groups.byLexicon ?? {})).toEqual(["terraform"]);
+    expect(groups.byLexicon?.["terraform"].length).toBe(
+      (groups.byStack?.["app"].length ?? 0) + (groups.byStack?.["network"].length ?? 0),
+    );
+  });
+
+  it("puts every node in exactly one root's bucket, the one its id is prefixed with", () => {
+    for (const [root, ids] of Object.entries(groups.byStack ?? {})) {
+      for (const id of ids) expect(id.startsWith(`${root}/`)).toBe(true);
+    }
+  });
+
+  it("says which unit an entity belongs to on the entity, not by convention on its id", () => {
+    expect(entityStack(entities.get("app/module.cdn/var.bucket")!)).toBe("app");
+    expect(entityStack(entities.get("network/aws_vpc.main")!)).toBe("network");
+  });
+});