@intentius/chant-lexicon-terraform 0.57.0

package/src/composites/terraform-watch-op.ts

@@ -0,0 +1,204 @@
+/**
+ * TerraformWatchOp composite (#2087): drift reporting for one root module,
+ * on a schedule.
+ *
+ * The observe position on the lifecycle dial. `TerraformApplyOp` next door
+ * changes the estate; this one never does: it inits, plans, and reports what
+ * the plan found. `terraform plan -detailed-exitcode` is the whole mechanism.
+ * Exit 0 is "the world matches the configuration", exit 2 is drift, and
+ * `terraformPlan` turns that into the boolean `changed`, which rides out of
+ * the Op as the `Drift` search attribute.
+ *
+ * Phases: Init, Plan, and (for a finding mode that opens something) Report.
+ *
+ * ## Only the human plan is ever posted
+ *
+ * `terraformPlan` returns two renders of the same plan: `json`, from
+ * `terraform show -json`, and `text`, from `terraform show -no-color`. The
+ * JSON one carries every resource attribute value the plan touches, including
+ * provider credentials that no `sensitive` marking covers, because
+ * `sensitive_values` describes the configuration's own declarations rather
+ * than everything a provider puts in a plan. So the issue and pull-request
+ * modes reference `plan.out.text` and nothing else. There is no option to
+ * post the JSON, and `terraform-watch-op.test.ts` asserts no reference to it
+ * reaches the finding step.
+ *
+ * ## Findings reuse `reconcilePr`
+ *
+ * `issue` and `pull-request` call the temporal lexicon's `reconcilePr`
+ * activity, the one place in chant that shells to `gh issue create` /
+ * `gh pr create`, rather than growing a second copy of those calls here.
+ * That activity built its own change-set summary and had no way to be handed
+ * one, so #2087 added a single field to it (`ReconcilePrArgs.body`), which is
+ * what carries the `-no-color` plan through. Note that the pull-request mode
+ * of `reconcilePr` regenerates chant TypeScript via `chant import`; a
+ * terraform-native regeneration of HCL from live state is #2089, so until
+ * then `findingMode: "issue"` is the mode with an end-to-end answer and
+ * `"pull-request"` opens a PR whose body is the plan.
+ *
+ * ## The schedule
+ *
+ * A cron makes this a `{ op, schedule }` pair, the shape
+ * `lexicons/temporal/src/composites/workflow-audit-op.ts` and
+ * `reconcile-op.ts` return. The schedule resource is `Temporal::Schedule`,
+ * built here through core's own `createResource` rather than imported from
+ * `@intentius/chant-lexicon-temporal`: no lexicon in this repo imports
+ * another lexicon's package at runtime, and a static import would mean a
+ * project that installs terraform and runs `chant run` on the local executor
+ * could not load `@intentius/chant-lexicon-terraform` at all without also
+ * installing temporal. The declarable is the same one temporal's
+ * `TemporalSchedule` produces (`createResource("Temporal::Schedule",
+ * "temporal", {})`, `lexicons/temporal/src/resources.ts`), so temporal's
+ * serializer renders it unchanged when a project has both.
+ *
+ * A project with no Temporal at all runs the same Op on a CI cron instead:
+ * `generateOpsPipeline` against the github lexicon turns the Op plus its cron
+ * into a workflow. `examples/scheduled-watch/` is that recipe.
+ *
+ * @example
+ * ```typescript
+ * import { TerraformWatchOp } from "@intentius/chant-lexicon-terraform";
+ *
+ * // one-shot, local executor: chant run app-watch
+ * export const { op } = TerraformWatchOp({ name: "app-watch", root: "app" });
+ *
+ * // nightly, opening an issue when the plan is non-empty
+ * export const { op, schedule } = TerraformWatchOp({
+ *   name: "app-watch",
+ *   root: "app",
+ *   schedule: "0 6 * * *",
+ *   findingMode: "issue",
+ * });
+ * ```
+ */
+
+import { Op, phase, OpResource, type ActivityStep } from "@intentius/chant/op";
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import { DEFAULT_PLAN_FILE } from "../op/activities/terraform";
+import { terraformInit as initStep, terraformPlan as planStep } from "../op/builders";
+
+/**
+ * What to do with a non-empty plan. A subset of core's `OpFindingMode`
+ * (`packages/core/src/lexicon.ts`): `merge-request` is GitLab's spelling of
+ * `pull-request` and is produced by the CI generator, not chosen here.
+ */
+export type TerraformFindingMode = "report" | "issue" | "pull-request";
+
+/**
+ * `Temporal::Schedule`, built without importing the temporal lexicon. See the
+ * module doc for why. Identical to `TemporalSchedule` in
+ * `lexicons/temporal/src/resources.ts`.
+ */
+const ScheduleResource = createResource("Temporal::Schedule", "temporal", {});
+
+/** `app-watch` becomes `appWatchWorkflow`, matching the temporal serializer's naming. */
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+export interface TerraformWatchOpConfig {
+  /** Op name (kebab-case). Also the default task queue and schedule id base. */
+  name: string;
+  /** Key into the project's `terraform.roots`. The root carries dir, workspace, var files and backend config. */
+  root: string;
+  /**
+   * Cron expression. When set, a `Temporal::Schedule` is returned alongside
+   * the Op; omit for one-shot `chant run` on the local executor, or for a CI
+   * cron built by `generateOpsPipeline`.
+   */
+  schedule?: string;
+  /**
+   * What to do when the plan proposes changes. Default: `"report"`, which
+   * opens nothing. The `Drift` search attribute and the run's own log are
+   * the report.
+   */
+  findingMode?: TerraformFindingMode;
+  /** Plan file the Plan step writes, relative to the root dir. Default: `chant.tfplan`. */
+  planFile?: string;
+  /** `-upgrade` on the Init step: re-resolve provider and module versions. */
+  upgrade?: boolean;
+  /**
+   * Directory each step starts the `chant.config.*` search from, which is
+   * what `terraform.roots` and the root's relative `dir` resolve against.
+   * Default: the running process's cwd, which is the project root under
+   * `chant run`. Same field, same meaning, as `TerraformApplyOpConfig.cwd`.
+   */
+  cwd?: string;
+  /** Issue / PR title. Default: `Terraform drift in root "<root>"`. */
+  title?: string;
+  /** Branch the pull-request mode opens from. Default: `reconcilePr`'s own. */
+  branch?: string;
+  /** Override the task queue. Defaults to `name`. */
+  taskQueue?: string;
+}
+
+export interface TerraformWatchOpResources {
+  /** Op resource. Generates the Init/Plan/[Report] workflow. */
+  op: InstanceType<typeof OpResource>;
+  /** `Temporal::Schedule`, present only when `schedule` was given. */
+  schedule?: Declarable;
+}
+
+export function TerraformWatchOp(config: TerraformWatchOpConfig): TerraformWatchOpResources {
+  const taskQueue = config.taskQueue ?? config.name;
+  const planFile = config.planFile ?? DEFAULT_PLAN_FILE;
+  const findingMode: TerraformFindingMode = config.findingMode ?? "report";
+  const where = config.cwd ? { cwd: config.cwd } : {};
+
+  // `id` is what makes `plan.out` legal, and `plan.out.text` is the only
+  // channel by which any part of the plan leaves this Op.
+  const plan = planStep(config.root, { planFile, ...where, id: "plan" });
+  plan.outcomeAttribute = { name: "Drift", from: "changed" };
+
+  const phases = [
+    phase("Init", [initStep(config.root, { ...where, ...(config.upgrade ? { upgrade: true } : {}) })]),
+    phase("Plan", [plan]),
+  ];
+
+  if (findingMode !== "report") {
+    // `env` is `reconcilePr`'s name for the thing being reconciled; for
+    // terraform that is the root, which with its workspace is the deployment
+    // target. `entries: []` and `body` together mean the activity opens what
+    // it is given rather than running `chant lifecycle plan` to find out.
+    const report: ActivityStep = {
+      kind: "activity",
+      fn: "reconcilePr",
+      args: {
+        env: config.root,
+        mode: findingMode,
+        entries: [],
+        title: config.title ?? `Terraform drift in root "${config.root}"`,
+        body: plan.out.text,
+        ...(config.branch ? { branch: config.branch } : {}),
+      },
+      outcomeAttribute:
+        findingMode === "pull-request" ? { name: "PR", from: "prUrl" } : { name: "Issue", from: "issueUrl" },
+    };
+    phases.push(phase("Report", [report]));
+  }
+
+  const op = Op({
+    name: config.name,
+    overview: `Plan the "${config.root}" terraform root and report drift`,
+    taskQueue,
+    searchAttributes: {
+      Watch: "true",
+      TerraformRoot: config.root,
+    },
+    phases,
+  });
+
+  if (!config.schedule) return { op };
+
+  const schedule = new ScheduleResource({
+    scheduleId: `${config.name}-schedule`,
+    spec: { cronExpressions: [config.schedule] },
+    action: {
+      workflowType: kebabToCamel(config.name) + "Workflow",
+      taskQueue,
+    },
+  });
+
+  return { op, schedule };
+}

package/src/config.ts

@@ -0,0 +1,76 @@
+/**
+ * The `terraform` namespace in `chant.config.ts` (#1344).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-terraform";  // brings the `terraform` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["terraform"],
+ *   terraform: {
+ *     binary: "tofu",
+ *     roots: {
+ *       app: { dir: "./terraform/app", workspace: "prod", varFiles: ["prod.tfvars"] },
+ *     },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * One schema, three consumers: core validates the namespace against it at load,
+ * the type below is derived from it, and that derived type is what augments
+ * `ChantConfig`, so an unknown key fails at build time and at compile time for
+ * the same reason, rather than being silently ignored at both.
+ */
+
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+
+/**
+ * One Terraform root module chant reads. `dir` is the only required field:
+ * everything else names how the root is invoked rather than what it declares.
+ *
+ * `strictObject`, not `object`. Core applies `.strict()` to the top level of a
+ * declared namespace itself, but nested objects are the lexicon's own to make
+ * strict, and a root entry is exactly where a typo (`varfiles`) would
+ * otherwise land silently.
+ */
+export const terraformRootSchema = z.strictObject({
+  /** Root module directory, relative to the project root (where `chant.config.*` lives). */
+  dir: z.string(),
+  /** Terraform workspace to select for this root. Omitted means `default`. */
+  workspace: z.string().optional(),
+  /** `-var-file` arguments, in order, relative to `dir`. */
+  varFiles: z.array(z.string()).optional(),
+  /** `-backend-config` key/value pairs handed to `init`. */
+  backendConfig: z.record(z.string(), z.string()).optional(),
+});
+
+export const terraformConfigSchema = z.strictObject({
+  /**
+   * Which CLI drives the roots. The two are wire-compatible for everything
+   * this lexicon does, so the choice is recorded rather than inferred.
+   */
+  binary: z.enum(["terraform", "tofu"]).optional(),
+  /** Named root modules. The name is the entity-key prefix, so keep it stable. */
+  roots: z.record(z.string(), terraformRootSchema),
+});
+
+export type TerraformRootConfig = z.infer<typeof terraformRootSchema>;
+export type TerraformConfig = z.infer<typeof terraformConfigSchema>;
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    terraform?: TerraformConfig;
+  }
+}
+
+/**
+ * Compile-time proof that the augmentation above reaches `ChantConfig` (#1344).
+ *
+ * Without it this line is `Property 'terraform' does not exist on type
+ * 'ChantConfig'`, which is exactly the error a user's `chant.config.ts` gets.
+ * It lives here rather than in a test because the root tsconfig excludes test
+ * files from typechecking, so a compile-time claim asserted in one is checked
+ * by nothing.
+ */
+export type TerraformConfigNamespace = NonNullable<ChantConfig["terraform"]>;

package/src/describe-resources.test.ts

@@ -0,0 +1,342 @@
+/**
+ * terraform describeResources tests (#2087).
+ *
+ * The declared side is real: `renderTerraformRoots` parses
+ * `src/__fixtures__/with-module/` exactly as `buildRoots()` does, so the keys
+ * this reader matches against are the keys a build produces, not keys a test
+ * wrote down. The live side is `src/__fixtures__/show-state.json`, recorded
+ * from `terraform show -json` after applying that same root with terraform
+ * 1.15.8 against a local backend (`null_resource.third` was added to the HCL
+ * afterwards, which is why it is declared and not in state).
+ *
+ * Nothing here runs terraform: the `init`/`show` activities are injected.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { normalizeObservation } from "@intentius/chant/observation";
+import type { Declarable } from "@intentius/chant/declarable";
+import {
+  describeResources,
+  classifyStateOwnership,
+  indexStateResources,
+  TERRAFORM_STATE_OWNERSHIP_KEYS,
+  type TerraformReadDeps,
+} from "./describe-resources";
+import { renderTerraformRoots } from "./hcl/roots";
+import { terraformPlugin } from "./plugin";
+
+const fixtures = join(dirname(fileURLToPath(import.meta.url)), "__fixtures__");
+const STATE: unknown = JSON.parse(readFileSync(join(fixtures, "show-state.json"), "utf-8"));
+
+const ROOT_DIR = join(fixtures, "with-module");
+
+/** `buildRoots()`'s own render of the fixture root, keyed `<root>/<address>`. */
+async function declaredEntities(): Promise<Map<string, { entityType: string; props: Record<string, unknown> }>> {
+  const { entities } = await renderTerraformRoots({
+    projectRoot: fixtures,
+    roots: { app: { dir: "./with-module" } },
+  });
+  const out = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+  for (const [key, entity] of entities) {
+    out.set(key, {
+      entityType: entity.entityType,
+      props: (entity as Declarable & { props: Record<string, unknown> }).props,
+    });
+  }
+  return out;
+}
+
+/** Injected activities that answer from the recorded state, with no child process. */
+function deps(overrides?: Partial<TerraformReadDeps>): TerraformReadDeps {
+  return {
+    init: (async () => ({ dir: ROOT_DIR })) as TerraformReadDeps["init"],
+    show: (async () => ({
+      source: "state" as const,
+      json: STATE,
+      text: "",
+      dir: ROOT_DIR,
+      adds: 0,
+      changes: 0,
+      destroys: 0,
+    })) as TerraformReadDeps["show"],
+    ...overrides,
+  };
+}
+
+const failing = (message: string): TerraformReadDeps["show"] =>
+  (async () => {
+    throw new Error(message);
+  }) as TerraformReadDeps["show"];
+
+async function options(overrides?: { owned?: boolean; only?: string[] }) {
+  const entities = await declaredEntities();
+  const entityNames = overrides?.only ?? [...entities.keys()].sort();
+  return {
+    environment: "prod",
+    buildOutput: "",
+    entityNames,
+    entities,
+    ...(overrides?.owned ? { owned: true } : {}),
+  };
+}
+
+describe("indexStateResources (#2087)", () => {
+  it("indexes root-module and child-module rows by fully qualified address", () => {
+    const index = indexStateResources(STATE);
+    expect([...index.rows.keys()].sort()).toEqual([
+      "module.cdn.null_resource.edge",
+      "null_resource.first",
+      "null_resource.second",
+    ]);
+    expect(index.modules).toContain("module.cdn");
+  });
+
+  it("does not double-prefix an address terraform already qualified", () => {
+    // Real `terraform show -json` writes `module.cdn.null_resource.edge`
+    // inside `child_modules`, already qualified. See the fixture.
+    const index = indexStateResources(STATE);
+    expect(index.rows.has("module.cdn.module.cdn.null_resource.edge")).toBe(false);
+  });
+
+  it("prefixes a bare address, for an output shape that does not qualify it", () => {
+    const index = indexStateResources({
+      values: {
+        root_module: {
+          child_modules: [{ address: "module.cdn", resources: [{ address: "null_resource.edge" }] }],
+        },
+      },
+    });
+    expect([...index.rows.keys()]).toEqual(["module.cdn.null_resource.edge"]);
+  });
+
+  it("reads nothing from a document with no values at all", () => {
+    expect(indexStateResources({}).rows.size).toBe(0);
+    expect(indexStateResources(null).rows.size).toBe(0);
+  });
+});
+
+describe("classifyStateOwnership (#2087)", () => {
+  const index = indexStateResources(STATE);
+
+  it("an address in state is owned, since state membership IS the channel", () => {
+    expect(classifyStateOwnership("null_resource.first", index)).toBe("owned");
+    expect(classifyStateOwnership("module.cdn.null_resource.edge", index)).toBe("owned");
+  });
+
+  it("an address outside state is unknown, never foreign", () => {
+    // `foreign` would claim chant looked at a marker and found someone else's.
+    // There is no marker: the state simply has no row.
+    expect(classifyStateOwnership("null_resource.third", index)).toBe("unknown");
+    expect(classifyStateOwnership("module.cdn", index)).toBe("unknown");
+  });
+
+  it("the declared channel keys name the state, not a tag", () => {
+    expect(TERRAFORM_STATE_OWNERSHIP_KEYS.managedBy).toBe("terraform.state");
+    expect(terraformPlugin.ownershipChannel).toEqual({
+      keys: TERRAFORM_STATE_OWNERSHIP_KEYS,
+      reads: ["describeResources"],
+    });
+  });
+});
+
+describe("terraform describeResources (#2087)", () => {
+  it("maps state addresses onto the keys buildRoots() produces", async () => {
+    const { resources } = normalizeObservation(await describeResources(await options(), deps()));
+    expect(resources["app/null_resource.first"]).toMatchObject({
+      type: "Terraform::Resource",
+      physicalId: "1710777879587847269",
+      status: "managed",
+      ownership: "owned",
+    });
+    expect(resources["app/null_resource.second"].ownership).toBe("owned");
+    expect(resources["app/null_resource.first"].attributes).toEqual({
+      address: "null_resource.first",
+      root: "app",
+      resourceType: "null_resource",
+      mode: "managed",
+      provider: "registry.terraform.io/hashicorp/null",
+    });
+  });
+
+  it("never surfaces a state row's attribute values", async () => {
+    // `values` is the full attribute set, provider secrets included; only the
+    // `id` is read out of it, as the physical id.
+    const result = await describeResources(await options(), deps());
+    expect(JSON.stringify(result)).not.toContain("triggers");
+    for (const meta of Object.values(normalizeObservation(result).resources)) {
+      expect(meta.attributes).not.toHaveProperty("values");
+      expect(meta.attributes).not.toHaveProperty("triggers");
+    }
+  });
+
+  it("reports a declared resource with no state row as absent, not not-observed", async () => {
+    const { resources, unobserved, queried } = normalizeObservation(
+      await describeResources(await options(), deps()),
+    );
+    expect(resources).not.toHaveProperty("app/null_resource.third");
+    expect(unobserved).not.toHaveProperty("app/null_resource.third");
+    // Absence is spelled "in neither map", so `queried` is the only place it
+    // can say where it looked (#1620).
+    expect(queried["app/null_resource.third"]).toContain("null_resource.third");
+  });
+
+  it("reports a declared module block as present but unknown, since state has no row for it", async () => {
+    const { resources } = normalizeObservation(await describeResources(await options(), deps()));
+    expect(resources["app/module.cdn"]).toMatchObject({
+      type: "Terraform::Module",
+      physicalId: "module.cdn",
+      status: "module",
+      ownership: "unknown",
+    });
+  });
+
+  it("reports blocks that state does not record at all as unsupported-kind", async () => {
+    const { unobserved } = normalizeObservation(await describeResources(await options(), deps()));
+    for (const name of ["app/terraform", "app/provider.null", "app/var.region"]) {
+      expect(unobserved[name].reason).toBe("unsupported-kind");
+      expect(unobserved[name].detail).toContain("terraform state");
+    }
+  });
+
+  it("surfaces no ownership marker, because there is no marker channel to read one off", async () => {
+    const { resources } = normalizeObservation(await describeResources(await options(), deps()));
+    for (const meta of Object.values(resources)) expect(meta.marker).toBeUndefined();
+  });
+
+  it("names the root when the read is issued", async () => {
+    const { queried } = normalizeObservation(await describeResources(await options(), deps()));
+    expect(queried["app/null_resource.first"]).toBe(
+      'terraform show -json (root "app", address "null_resource.first")',
+    );
+  });
+});
+
+describe("terraform describeResources failed reads (#2087)", () => {
+  it("a failed show reports every declared entity of that root read-failed, naming the root", async () => {
+    const opts = await options();
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources(opts, deps({ show: failing("Error acquiring the state lock") })),
+    );
+    expect(Object.keys(resources)).toEqual([]);
+    expect(Object.keys(unobserved).sort()).toEqual([...opts.entityNames].sort());
+    for (const entry of Object.values(unobserved)) {
+      expect(entry.reason).toBe("read-failed");
+      expect(entry.detail).toContain("terraform.roots.app");
+      expect(entry.detail).toContain("Error acquiring the state lock");
+    }
+  });
+
+  it("a failed init is read-failed too, and no entity is ever absent", async () => {
+    const opts = await options();
+    const failingInit = (async () => {
+      throw new Error("Backend initialization required");
+    }) as TerraformReadDeps["init"];
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources(opts, deps({ init: failingInit })),
+    );
+    expect(Object.keys(resources)).toEqual([]);
+    for (const name of opts.entityNames) {
+      expect(unobserved[name].reason).toBe("read-failed");
+      expect(unobserved[name].detail).toContain("Backend initialization required");
+    }
+  });
+
+  it("one broken root does not un-observe a root that answered", async () => {
+    const entities = await declaredEntities();
+    entities.set("other/null_resource.away", {
+      entityType: "Terraform::Resource",
+      props: { address: "null_resource.away", root: "other", body: {}, file: "main.tf" },
+    });
+    const brokenRoot: TerraformReadDeps = {
+      init: (async (args: { root: string }) => {
+        if (args.root === "other") throw new Error("no backend configured");
+        return { dir: ROOT_DIR };
+      }) as TerraformReadDeps["init"],
+      show: deps().show,
+    };
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources(
+        {
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["app/null_resource.first", "other/null_resource.away"],
+          entities,
+        },
+        brokenRoot,
+      ),
+    );
+    expect(resources["app/null_resource.first"].ownership).toBe("owned");
+    expect(unobserved["other/null_resource.away"].reason).toBe("read-failed");
+    expect(unobserved["other/null_resource.away"].detail).toContain("terraform.roots.other");
+  });
+});
+
+describe("terraform describeResources --owned (#2087)", () => {
+  it("withholds a non-owned present entity as filtered, never as absent", async () => {
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources(await options({ owned: true }), deps()),
+    );
+    expect(resources).not.toHaveProperty("app/module.cdn");
+    expect(unobserved["app/module.cdn"].reason).toBe("filtered");
+    expect(Object.keys(resources).sort()).toEqual([
+      "app/null_resource.first",
+      "app/null_resource.second",
+    ]);
+  });
+});
+
+describeObservationConformance({
+  lexicon: "terraform",
+  ownershipChannel: terraformPlugin.ownershipChannel,
+  scenarios: [
+    {
+      name: "resources in state",
+      declared: ["app/null_resource.first", "app/null_resource.second"],
+      expectPresent: ["app/null_resource.first", "app/null_resource.second"],
+      expectNoMarker: ["app/null_resource.first"],
+      run: async () =>
+        describeResources(
+          await options({ only: ["app/null_resource.first", "app/null_resource.second"] }),
+          deps(),
+        ),
+    },
+    {
+      name: "declared but not in state",
+      declared: ["app/null_resource.third"],
+      expectAbsent: ["app/null_resource.third"],
+      run: async () => describeResources(await options({ only: ["app/null_resource.third"] }), deps()),
+    },
+    {
+      name: "the state lock is held",
+      declared: ["app/null_resource.first", "app/module.cdn"],
+      expectUnobserved: ["app/null_resource.first", "app/module.cdn"],
+      run: async () =>
+        describeResources(
+          await options({ only: ["app/null_resource.first", "app/module.cdn"] }),
+          deps({ show: failing("Error acquiring the state lock") }),
+        ),
+    },
+    {
+      name: "a block terraform state has no row for",
+      declared: ["app/provider.null"],
+      expectUnobserved: ["app/provider.null"],
+      run: async () => describeResources(await options({ only: ["app/provider.null"] }), deps()),
+    },
+    {
+      name: "owned read, with the module block filtered out",
+      declared: ["app/null_resource.first", "app/module.cdn"],
+      owned: true,
+      expectPresent: ["app/null_resource.first"],
+      expectUnobserved: ["app/module.cdn"],
+      run: async () =>
+        describeResources(
+          await options({ only: ["app/null_resource.first", "app/module.cdn"], owned: true }),
+          deps(),
+        ),
+    },
+  ],
+});