@intentius/chant-lexicon-terraform 0.124.44 → 0.124.46

package/src/effective-topology.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Core's effective-topology folds over a terraform root (chant #4362).
+ *
+ * `enrichEffectiveTopology` used to select nodes by CloudFormation kind, and
+ * every terraform resource is `Terraform::Resource`, so on a terraform root
+ * `attr:internetFacing=true` matched nothing. The fixture
+ * (`src/__fixtures__/effective-topology/`) holds three instances and writes
+ * each route spelling and each ingress spelling once, on a path of its own,
+ * so every test below fails when the code for its spelling is removed.
+ *
+ *   web    public (inline `route`), SSH open via a launch template's group (inline `ingress`)
+ *   batch  public (`aws_route`), HTTPS via `security_groups` (`aws_vpc_security_group_ingress_rule`)
+ *   db     private (NAT route), SSH open via `vpc_security_group_ids` (`aws_security_group_rule`)
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { buildGraphIr, type GraphIR } from "@intentius/chant/graph-ir";
+import { enrichEffectiveTopology, terraformResourceType } from "@intentius/chant/graph-effective";
+import { __searchInternals, runSearch } from "@intentius/chant/cli/handlers/search";
+import { renderTerraformRoots } from "./hcl/roots";
+import { terraformPlugin } from "./plugin";
+
+const FIXTURE = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "effective-topology");
+const QUERY = "attr:internetFacing=true attr:effectiveIngress=tcp:22:0.0.0.0/0";
+
+let ir: GraphIR;
+const attrs = (address: string): Record<string, unknown> =>
+  ir.nodes.find((n) => n.id === `net/${address}`)!.attrs as Record<string, unknown>;
+
+beforeAll(async () => {
+  const rendered = await renderTerraformRoots({ projectRoot: FIXTURE, roots: { net: { dir: "./net" } } });
+  expect(rendered.warnings).toEqual([]);
+  ir = enrichEffectiveTopology(buildGraphIr(rendered.entities));
+});
+
+describe("terraformResourceType", () => {
+  it("reads the provider type off a terraform resource's address, and nothing else's", () => {
+    const web = ir.nodes.find((n) => n.id === "net/aws_instance.web");
+    expect(terraformResourceType(web)).toBe("aws_instance");
+    expect(terraformResourceType({ id: "x", kind: "AWS::EC2::Instance", attrs: {} } as never)).toBeUndefined();
+  });
+
+  it("reads the lexicon's attrs.type first, and the address only without one (#4366)", () => {
+    expect(ir.nodes.find((n) => n.id === "net/aws_instance.web")?.attrs.type).toBe("aws_instance");
+    const node = (attrs: Record<string, unknown>) => ({ id: "r/x.y", kind: "Terraform::Resource", attrs }) as never;
+    expect(terraformResourceType(node({ type: "aws_subnet", address: "aws_instance.y" }))).toBe("aws_subnet");
+    expect(terraformResourceType(node({ address: "module.app.aws_instance.y" }))).toBe("aws_instance");
+  });
+});
+
+describe("internetFacing on terraform's AWS kinds", () => {
+  it("follows an inline `route` block to the internet gateway", () => {
+    expect(attrs("aws_instance.web").internetFacing).toBe(true);
+    expect(attrs("aws_instance.web").internetFacingVia).toBe(
+      "subnet route aws_subnet.public_a -> aws_route_table.public_inline -> aws_internet_gateway.main (inline route)",
+    );
+  });
+
+  it("follows a separate `aws_route` resource to the internet gateway", () => {
+    expect(attrs("aws_instance.batch").internetFacing).toBe(true);
+    expect(attrs("aws_instance.batch").internetFacingVia).toBe(
+      "subnet route aws_subnet.public_b -> aws_route_table.public_separate -> aws_internet_gateway.main (aws_route.public_separate_default)",
+    );
+  });
+
+  it("does not count a default route to a NAT gateway", () => {
+    expect(attrs("aws_instance.db").internetFacing).toBe(false);
+    expect(attrs("aws_instance.db").internetFacingVia).toBeUndefined();
+  });
+});
+
+describe("effectiveIngress on terraform's AWS kinds", () => {
+  it("reads an inline `ingress` block on a group reached through a launch template", () => {
+    expect(attrs("aws_instance.web").effectiveIngress).toEqual(["tcp:22:0.0.0.0/0"]);
+    expect(attrs("aws_instance.web").effectiveIngressVia).toBe(
+      "security groups aws_launch_template.web -> aws_security_group.web",
+    );
+  });
+
+  it("reads an `aws_security_group_rule` of type ingress, and skips its egress sibling", () => {
+    expect(attrs("aws_instance.db").effectiveIngress).toEqual(["tcp:22:0.0.0.0/0"]);
+  });
+
+  it("reads an `aws_vpc_security_group_ingress_rule` on a group reached through `security_groups`", () => {
+    expect(attrs("aws_instance.batch").effectiveIngress).toEqual(["tcp:443:0.0.0.0/0"]);
+  });
+
+  it("records the derived surface under the terraform type", () => {
+    expect(ir.derivedAttrs?.["aws_instance"]).toEqual(["internetFacing", "effectiveIngress"]);
+  });
+});
+
+describe(`search "${QUERY}"`, () => {
+  const { parseQuery, matchTerm, explain } = __searchInternals;
+  afterEach(() => vi.restoreAllMocks());
+
+  it("matches exactly the public instance with SSH open through its launch template", () => {
+    const terms = parseQuery(QUERY);
+    const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+    const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, byId)));
+    expect(matches.map((n) => n.id)).toEqual(["net/aws_instance.web"]);
+  });
+
+  it("--explain prints the inclusion evidence for the match", () => {
+    const lines: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((line: unknown) => void lines.push(String(line)));
+    const terms = parseQuery(QUERY);
+    const byId = new Map(ir.nodes.map((n) => [n.id, n]));
+    const matches = ir.nodes.filter((n) => terms.every((t) => matchTerm(n, t, ir, byId)));
+    explain(terms, matches, ir, byId, QUERY);
+    expect(lines).toContain(
+      "  ✓ net/aws_instance.web internetFacing via subnet route aws_subnet.public_a -> aws_route_table.public_inline -> aws_internet_gateway.main (inline route)",
+    );
+  });
+
+  it("end to end: reads the root from config and says the facts are declared-only", async () => {
+    const lines: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((line: unknown) => void lines.push(String(line)));
+    const cwd = process.cwd();
+    process.chdir(FIXTURE);
+    try {
+      const exit = await runSearch({ args: { path: QUERY } as never, plugins: [terraformPlugin], serializers: [] });
+      expect(exit).toBe(0);
+    } finally {
+      process.chdir(cwd);
+    }
+    expect(lines).toEqual([
+      "net/aws_instance.web  aws_instance",
+      "— declared only · no observation · physical ids unavailable · effectiveIngress, internetFacing derived from declared references",
+    ]);
+  });
+});

package/src/hcl/parse.ts

@@ -25,6 +25,7 @@ import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable"
 import type { EntityReference } from "@intentius/chant/graph-ir";
 import type { SuppressionDirective } from "@intentius/chant/lint/suppressions";
 import type { TerraformDeleteMode } from "../config";
+import { redactSensitiveBody, redactSensitiveSource } from "./redact";
 import { scanSuppressions, directivesFor, type FileScan } from "./suppressions";
 
 /** A parsed HCL block body, as `@cdktn/hcl2json` encodes it. */
@@ -52,6 +53,16 @@ export interface TerraformEntity extends Declarable {
   readonly props: {
     /** Terraform address, e.g. `aws_s3_bucket.assets`, `var.region`, `module.cdn`. */
     readonly address: string;
+    /**
+     * A `resource` or `data` block's type and name, its two labels
+     * (`aws_instance` and `web` for `aws_instance.web`, `aws_ami` and `ubuntu`
+     * for `data.aws_ami.ubuntu`). Absent on every other block. Every resource
+     * is `Terraform::Resource` to chant, so this is what core's
+     * `terraformType()` reads for `chant search "kind:aws_instance"`,
+     * `--count-by kind` and the effective-topology folds (chant #4366).
+     */
+    readonly type?: string;
+    readonly name?: string;
     /** The block body, verbatim from hcl2json (interpolations survive as `"${...}"`). */
     readonly body: BlockBody;
     /** File the block came from, as named by the parse input. */
@@ -223,6 +234,9 @@ export function terraformEntity(
   suppressions?: readonly SuppressionDirective[],
 ): TerraformEntity {
   const expansion = expansionOf(body);
+  const labels = entityType === RESOURCE_TYPE ? blockLabels(address)
+    : entityType === DATA_TYPE && address.startsWith("data.") ? blockLabels(address.slice("data.".length))
+    : undefined;
   return {
     [DECLARABLE_MARKER]: true,
     lexicon: "terraform",
@@ -231,6 +245,7 @@ export function terraformEntity(
     stack: root,
     props: {
       address,
+      ...(labels ?? {}),
       body,
       file,
       root,
@@ -248,6 +263,13 @@ export function terraformEntity(
   };
 }
 
+/** The type and name labels of a resource address (`aws_instance.web`), or undefined when it is not two labels. */
+function blockLabels(address: string): { type: string; name: string } | undefined {
+  const dot = address.indexOf(".");
+  if (dot <= 0 || dot === address.length - 1 || address.indexOf(".", dot + 1) !== -1) return undefined;
+  return { type: address.slice(0, dot), name: address.slice(dot + 1) };
+}
+
 /** One `.tf` file's name and source. */
 export interface TerraformFile {
   name: string;
@@ -388,6 +410,9 @@ export async function blocksToEntities(
   const entities = new Map<string, Declarable>();
   const prefix = callers.length > 0 ? `${root}/${callers.join("/")}` : root;
 
+  /** Each file's text is carried by every entity of the file: redact it once. */
+  const redacted = new Map<string, string>();
+
   const add = (
     entityType: string,
     address: string,
@@ -397,10 +422,13 @@ export async function blocksToEntities(
     scanAddress: string = address,
   ): void => {
     const { line, suppressions } = directivesFor(scan, scanAddress);
+    let source = redacted.get(file.source);
+    if (source === undefined) redacted.set(file.source, (source = redactSensitiveSource(file.source)));
+    const plain = (typeof body === "object" && body !== null ? body : {}) as BlockBody;
     const entity = terraformEntity(
       entityType,
       address,
-      (typeof body === "object" && body !== null ? body : {}) as BlockBody,
+      entityType === VARIABLE_TYPE ? redactSensitiveBody(plain) : plain,
       file.name,
       root,
       {
@@ -409,7 +437,7 @@ export async function blocksToEntities(
         ...(modeOptions?.configEstate !== undefined ? { configEstate: modeOptions.configEstate } : {}),
         ...(callers.length > 0 ? { callers } : {}),
       },
-      file.source,
+      source,
       line,
       suppressions,
     );

package/src/hcl/redact.ts

@@ -0,0 +1,181 @@
+/**
+ * Leave a sensitive variable's literal default out of the IR (#4377).
+ *
+ * The lexicon puts the HCL text of the file a block lives in on each entity's
+ * `source`, and the parsed block on `body`. A `variable` declared
+ * `sensitive = true` with a literal `default` carried that default in both, so
+ * `chant graph`, `chant search --show` and `workspace graph` printed it. This
+ * replaces the default with {@link SENSITIVE_PLACEHOLDER} (the same text the
+ * plan read shows) before the entity is built, so every reader gets the
+ * redacted form.
+ *
+ * `body` keeps its `default` key: TF006 asks whether a sensitive variable
+ * declares a default, and that fact survives. Only the value goes.
+ *
+ * The source scanner skips strings (with `${}`), heredocs and comments, finds
+ * each top-level `variable` block, and inside it the `sensitive` and `default`
+ * attributes. The default's whole expression is replaced, whether it is a
+ * string, a number, a list or a map spanning lines. Only a literal
+ * `sensitive = true` counts. Ported from behold's src/terraform-redact.ts.
+ */
+
+export const SENSITIVE_PLACEHOLDER = "(sensitive)";
+
+const WORD = /[A-Za-z_][A-Za-z0-9_-]*/y;
+const HEREDOC = /<<-?([A-Za-z_][A-Za-z0-9_]*)[ \t]*\r?\n/y;
+
+/** Index just past the string opened at `i` (a `"`), interpolations included. */
+function skipString(t: string, i: number): number {
+  i++;
+  while (i < t.length) {
+    const c = t[i];
+    if (c === "\\") i += 2;
+    else if (c === "$" && t[i + 1] === "$" && t[i + 2] === "{") i += 3;
+    else if ((c === "$" || c === "%") && t[i + 1] === "{") i = skipBraces(t, i + 1);
+    else if (c === '"') return i + 1;
+    else i++;
+  }
+  return t.length;
+}
+
+/** Index just past the heredoc whose opener starts at `i`, or -1 when `i` is not one. */
+function skipHeredoc(t: string, i: number): number {
+  HEREDOC.lastIndex = i;
+  const m = HEREDOC.exec(t);
+  if (!m) return -1;
+  let p = HEREDOC.lastIndex;
+  while (p < t.length) {
+    let e = t.indexOf("\n", p);
+    if (e < 0) e = t.length;
+    if (t.slice(p, e).trim() === m[1]) return e;
+    p = e + 1;
+  }
+  return t.length;
+}
+
+/** Index just past a comment starting at `i`, or -1 when there is none. A line comment stops before its newline. */
+function skipComment(t: string, i: number): number {
+  if (t[i] === "#" || (t[i] === "/" && t[i + 1] === "/")) {
+    const e = t.indexOf("\n", i);
+    return e < 0 ? t.length : e;
+  }
+  if (t[i] === "/" && t[i + 1] === "*") {
+    const e = t.indexOf("*/", i + 2);
+    return e < 0 ? t.length : e + 2;
+  }
+  return -1;
+}
+
+/** Index just past the bracket group opened at `i` (`{`, `[` or `(`). */
+function skipBraces(t: string, i: number): number {
+  let depth = 0;
+  while (i < t.length) {
+    const c = t[i];
+    if (c === '"') { i = skipString(t, i); continue; }
+    const h = c === "<" && t[i + 1] === "<" ? skipHeredoc(t, i) : -1;
+    if (h >= 0) { i = h; continue; }
+    const k = skipComment(t, i);
+    if (k >= 0) { i = k; continue; }
+    if (c === "{" || c === "[" || c === "(") depth++;
+    else if (c === "}" || c === "]" || c === ")") {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+    i++;
+  }
+  return t.length;
+}
+
+/** End of the expression starting at `i`: the last token before a newline or comma outside brackets, or the block's closing brace. */
+function valueEnd(t: string, i: number, limit: number): number {
+  let last = i;
+  while (i < limit) {
+    const c = t[i];
+    if (c === "\n" || c === ",") break;
+    if (c === '"') { i = skipString(t, i); last = i; continue; }
+    const h = c === "<" && t[i + 1] === "<" ? skipHeredoc(t, i) : -1;
+    if (h >= 0) { i = h; last = i; continue; }
+    const k = skipComment(t, i);
+    if (k >= 0) { i = k; continue; }
+    if (c === "{" || c === "[" || c === "(") { i = skipBraces(t, i); last = i; continue; }
+    if (c !== " " && c !== "\t" && c !== "\r") last = i + 1;
+    i++;
+  }
+  return Math.min(last, limit);
+}
+
+interface Attr {
+  name: string;
+  from: number;
+  to: number;
+}
+
+/** The attributes written directly in a block body spanning [from, to). */
+function attributes(t: string, from: number, to: number): Attr[] {
+  const out: Attr[] = [];
+  let i = from;
+  while (i < to) {
+    const c = t[i];
+    if (c === '"') { i = skipString(t, i); continue; }
+    const k = skipComment(t, i);
+    if (k >= 0) { i = k; continue; }
+    if (c === "{" || c === "[" || c === "(") { i = skipBraces(t, i); continue; }
+    WORD.lastIndex = i;
+    const m = WORD.exec(t);
+    if (!m) { i++; continue; }
+    i = WORD.lastIndex;
+    let p = i;
+    while (t[p] === " " || t[p] === "\t") p++;
+    if (t[p] === "=" && t[p + 1] !== "=" && t[p + 1] !== ">") {
+      p++;
+      while (t[p] === " " || t[p] === "\t") p++;
+      const end = valueEnd(t, p, to);
+      out.push({ name: m[0], from: p, to: end });
+      i = Math.max(end, p);
+    }
+  }
+  return out;
+}
+
+/** `source` with the literal default of every `sensitive = true` variable replaced by `(sensitive)`. */
+export function redactSensitiveSource(source: string): string {
+  if (!source.includes("sensitive")) return source;
+  const spans: [number, number][] = [];
+  let i = 0;
+  let variable = false;
+  while (i < source.length) {
+    const c = source[i];
+    if (c === "\n") variable = false;
+    if (c === '"') { i = skipString(source, i); continue; }
+    const k = skipComment(source, i);
+    if (k >= 0) { i = k; continue; }
+    if (c === "{") {
+      const end = skipBraces(source, i);
+      if (variable) {
+        const attrs = attributes(source, i + 1, end - 1);
+        const sensitive = attrs.some((a) => a.name === "sensitive" && source.slice(a.from, a.to) === "true");
+        if (sensitive) for (const a of attrs) if (a.name === "default") spans.push([a.from, a.to]);
+      }
+      variable = false;
+      i = end;
+      continue;
+    }
+    WORD.lastIndex = i;
+    const m = WORD.exec(source);
+    if (m) {
+      variable = m[0] === "variable";
+      i = WORD.lastIndex;
+      continue;
+    }
+    i++;
+  }
+  let out = source;
+  for (const [a, b] of spans.reverse()) out = out.slice(0, a) + SENSITIVE_PLACEHOLDER + out.slice(b);
+  return out;
+}
+
+/** A variable body with its `default` replaced, when the variable is a literal `sensitive = true` with a default. Otherwise the body itself. */
+export function redactSensitiveBody<T extends Record<string, unknown>>(body: T): T {
+  if (body.sensitive !== true || !("default" in body)) return body;
+  return { ...body, default: SENSITIVE_PLACEHOLDER };
+}

package/src/live-plan-depth.acceptance.e2e.test.ts

@@ -0,0 +1,193 @@
+/**
+ * The plan depth on a live root against a real choudoufu (#4371).
+ *
+ * Copies `src/__fixtures__/live-estate/` into a temp project under a fresh
+ * estate name, so a re-run against the same emulator never meets an earlier
+ * run's resources. Setup is what the fixture's README records: apply with
+ * `unowned.tf`, `rule.tf` and `adoptable.tf` held back, create the two
+ * unowned log groups out of band, then drift two bound resources out of band
+ * (a log group's retention, a tag on the VPC) and give the VPC a tag from a
+ * `sensitive` variable whose value then changes. `adoptable.tf` stays out:
+ * its content match needs a sweep, which an observation read never asks for.
+ *
+ * Then one `describeResources` at the plan depth, with the real activities.
+ *
+ * Gated on a `choudoufu` on PATH, an `aws` CLI on PATH and
+ * `CHOUDOUFU_EMULATOR_ENDPOINT`, and skipped with the reason named otherwise,
+ * like the other acceptance suites (`__fixtures__/ACCEPTANCE.md`). An e2e
+ * file: an apply and two reads against the emulator take about a minute.
+ */
+
+import { execSync, spawnSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+import { normalizeObservation } from "@intentius/chant/observation";
+import type { Declarable } from "@intentius/chant/declarable";
+import { describeResources } from "./describe-resources";
+import { renderTerraformRoots } from "./hcl/roots";
+import { PLAN_READ_DIR_PREFIX } from "./op/activities/terraform";
+import { SENSITIVE_VALUE } from "./plan-observation";
+
+const FIXTURE = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__", "live-estate");
+const emulatorEndpoint = process.env.CHOUDOUFU_EMULATOR_ENDPOINT;
+
+function onPath(cmd: string): boolean {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const missing = !onPath("choudoufu")
+  ? "choudoufu is not on PATH"
+  : !onPath("aws")
+    ? "the aws CLI is not on PATH"
+    : !emulatorEndpoint
+      ? "CHOUDOUFU_EMULATOR_ENDPOINT is not set (bring up choudoufu's `just smoke` emulator stack and export it)"
+      : undefined;
+
+const workspaces: string[] = [];
+afterAll(() => {
+  for (const dir of workspaces) rmSync(dir, { recursive: true, force: true });
+});
+
+function env(): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    AWS_ENDPOINT_URL: process.env.AWS_ENDPOINT_URL ?? emulatorEndpoint,
+    AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID ?? "choudoufu-emulator",
+    AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY ?? "choudoufu-emulator",
+    AWS_DEFAULT_REGION: process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+    AWS_REGION: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1",
+    TF_IN_AUTOMATION: "1",
+  };
+}
+
+function run(cmd: string, args: string[], cwd: string): string {
+  const r = spawnSync(cmd, args, { cwd, encoding: "utf-8", env: env() });
+  if (r.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed (exit ${r.status}): ${r.stderr}`);
+  return r.stdout;
+}
+
+/** Every entry under `dir`, recursively, with its size and mtime: what "nothing new" compares. */
+function snapshot(dir: string): string[] {
+  return readdirSync(dir, { recursive: true })
+    .map(String)
+    .sort()
+    .map((rel) => {
+      const st = statSync(join(dir, rel));
+      return `${rel} ${st.isDirectory() ? "dir" : `${st.size} ${st.mtimeMs}`}`;
+    });
+}
+
+function planDirs(): string[] {
+  return readdirSync(tmpdir()).filter((n) => n.startsWith(PLAN_READ_DIR_PREFIX)).sort();
+}
+
+describe.skipIf(missing !== undefined)(
+  `the plan depth on a live root against a real choudoufu (#4371)${missing ? `: skipped, ${missing}` : ""}`,
+  () => {
+    it("puts the plan on bound blocks beside live-plan's ownership, redacts the secret, writes nothing in the root", async () => {
+      const estate = `chant-4371-${Date.now().toString(36)}`;
+      const dir = mkdtempSync(join(tmpdir(), "chant-live-plan-depth-"));
+      workspaces.push(dir);
+      const root = join(dir, "root");
+      cpSync(FIXTURE, root, { recursive: true });
+      rmSync(join(root, "README.md"));
+      for (const file of readdirSync(root)) {
+        const path = join(root, file);
+        writeFileSync(path, readFileSync(path, "utf-8").replaceAll("stateless-e2e-block", estate));
+      }
+      const network = join(root, "network.tf");
+      writeFileSync(
+        network,
+        readFileSync(network, "utf-8").replace(
+          'resource "aws_vpc" "main" {\n  cidr_block = "10.99.0.0/16"\n}',
+          'resource "aws_vpc" "main" {\n  cidr_block = "10.99.0.0/16"\n  tags       = { token = var.token }\n}',
+        ),
+      );
+      const secret = (value: string) =>
+        writeFileSync(join(root, "secret.tf"), `variable "token" {\n  type      = string\n  sensitive = true\n  default   = "${value}"\n}\n`);
+      secret(`old-${estate}`);
+      writeFileSync(
+        join(dir, "chant.config.json"),
+        JSON.stringify({ lexicons: ["terraform"], terraform: { binary: "choudoufu", observe: "plan", roots: { estate: { dir: "./root" } } } }),
+      );
+
+      // Apply with the three held back, as the fixture's README does.
+      const held = join(dir, "held");
+      mkdirSync(held);
+      for (const f of ["unowned.tf", "rule.tf", "adoptable.tf"]) renameSync(join(root, f), join(held, f));
+      run("choudoufu", ["init", "-input=false"], root);
+      run("choudoufu", ["apply", "-auto-approve", "-input=false"], root);
+      for (const f of ["unowned.tf", "rule.tf"]) renameSync(join(held, f), join(root, f));
+
+      run("aws", ["logs", "create-log-group", "--log-group-name", `/${estate}/adoptable`], root);
+      run("aws", ["logs", "create-log-group", "--log-group-name", `/${estate}/held-elsewhere`], root);
+      run("aws", ["logs", "tag-log-group", "--log-group-name", `/${estate}/held-elsewhere`, "--tags", "tofu-estate=other-estate,tofu-address=aws_cloudwatch_log_group.elsewhere"], root);
+      // Out-of-band drift on two bound resources.
+      run("aws", ["logs", "put-retention-policy", "--log-group-name", `/${estate}/app`, "--retention-in-days", "3"], root);
+      const vpc = run("aws", ["ec2", "describe-vpcs", "--filters", `Name=tag:tofu-estate,Values=${estate}`, "--query", "Vpcs[0].VpcId", "--output", "text"], root).trim();
+      expect(vpc).toMatch(/^vpc-/);
+      run("aws", ["ec2", "create-tags", "--resources", vpc, "--tags", "Key=drifted,Value=yes"], root);
+      // The live tag now holds the old secret; the configuration declares a new one.
+      secret(`new-${estate}`);
+
+      const { entities } = await renderTerraformRoots({ projectRoot: dir, roots: { estate: { dir: "./root" } }, binary: "choudoufu" });
+      const map = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+      for (const [key, entity] of entities) {
+        map.set(key, { entityType: entity.entityType, props: (entity as Declarable & { props: Record<string, unknown> }).props });
+      }
+
+      const before = snapshot(root);
+      const tempBefore = planDirs();
+      const saved = { ...process.env };
+      Object.assign(process.env, env());
+      let raw;
+      try {
+        raw = await describeResources({ environment: "prod", buildOutput: "", entityNames: [...map.keys()].sort(), entities: map, cwd: dir });
+      } finally {
+        process.env = saved;
+      }
+      const result = normalizeObservation(raw);
+
+      // The read adds nothing to the root: neither the plan file nor the
+      // live-plan document (#4379).
+      expect(snapshot(root)).toEqual(before);
+      expect(planDirs()).toEqual(tempBefore);
+      expect(result.notes.join("\n")).toMatch(/estate: the plan read answered \(`choudoufu plan -input=false -lock=false -out=<tmp>\/plan\.tfplan`\)/);
+      expect(new Set(Object.values(result.sources))).toEqual(new Set(["live+plan"]));
+
+      const meta = (name: string) => result.resources[`estate/${name}`]!;
+      const attrs = (name: string) => meta(name).attributes as Record<string, unknown>;
+      expect(meta("aws_vpc.main").ownership).toBe("owned");
+      expect(meta("aws_vpc.main").marker).toEqual({ stack: estate });
+      expect(attrs("aws_cloudwatch_log_group.app")).toMatchObject({
+        planAction: "update",
+        planChanges: [{ path: "retention_in_days", before: 3, after: 1 }],
+      });
+      expect(attrs("aws_vpc.main").planChanges).toEqual(
+        expect.arrayContaining([
+          { path: "tags.drifted", before: "yes", after: null },
+          { path: "tags.token", before: SENSITIVE_VALUE, after: SENSITIVE_VALUE },
+        ]),
+      );
+      expect(attrs("aws_eip.pool").planAction).toBe("no-op");
+      expect(attrs("aws_subnet.app").planAction).toBe("no-op");
+
+      expect(meta("aws_cloudwatch_log_group.held_elsewhere").ownership).toBe("foreign");
+      expect(attrs("aws_cloudwatch_log_group.held_elsewhere").planAction).toBeUndefined();
+      expect(meta("aws_cloudwatch_log_group.adoptable").ownership).toBe("unknown");
+      expect(attrs("aws_cloudwatch_log_group.adoptable").planAction).toBeUndefined();
+      expect(result.resources["estate/aws_cloudwatch_log_group.never_applied"]).toBeUndefined();
+
+      expect(JSON.stringify(raw)).not.toContain(`old-${estate}`);
+      expect(JSON.stringify(raw)).not.toContain(`new-${estate}`);
+    }, 600_000);
+  },
+);