@intentius/chant-lexicon-aws 0.124.52 → 0.124.54

package/src/importable.test.ts

@@ -0,0 +1,86 @@
+/**
+ * #4536: which CloudFormation types chant can import, from the registry
+ * `handlers` codegen keeps, plus AWS's hand lists; and the adoption
+ * refusals (not importable, create-only tags). Over an injected manifest.
+ */
+import { describe, expect, test } from "vitest";
+import { NamingStrategy } from "./codegen/naming";
+import { generateLexiconJSON } from "./codegen/generate-lexicon";
+import { parseCFNSchema } from "./spec/parse";
+import {
+  adoptionRefusal,
+  isImportable,
+  LEGACY_IMPORTABLE_TYPES,
+  NOT_IMPORTABLE_TYPES,
+  type ImportabilityManifestEntry,
+} from "./importable";
+
+const entry = (resourceType: string, extra: Partial<ImportabilityManifestEntry> = {}): [string, ImportabilityManifestEntry] => [
+  resourceType,
+  { resourceType, kind: "resource", ...extra },
+];
+const ALL = ["create", "delete", "list", "read", "update"];
+const manifest = new Map<string, ImportabilityManifestEntry>([
+  entry("AWS::S3::Bucket", { handlers: ALL, tagging: { taggable: true, tagUpdatable: true } }),
+  entry("AWS::EC2::KeyPair", { handlers: ALL, tagging: { taggable: true, tagUpdatable: false } }),
+  entry("AWS::IAM::Policy", { handlers: ["create", "delete", "update"] }),
+  entry("AWS::CodeBuild::Project"),
+  entry("AWS::AppSync::GraphQLApi", { handlers: ALL }),
+  entry("AWS::Logs::LogStream", { handlers: ["create", "read", "delete"] }),
+]);
+
+describe("isImportable (#4536)", () => {
+  test("a type with create and read handlers is importable", () => {
+    expect(isImportable("AWS::S3::Bucket", manifest)).toBe(true);
+    expect(isImportable("AWS::Logs::LogStream", manifest)).toBe(true);
+  });
+
+  test("a type without read, or a legacy type with no handlers, is not", () => {
+    expect(isImportable("AWS::IAM::Policy", manifest)).toBe(false);
+    expect(isImportable("AWS::CodeBuild::Project", manifest)).toBe(false);
+    expect(isImportable("AWS::Nope::Nope", manifest)).toBe(false);
+  });
+
+  test("AWS's hand lists win over the handlers", () => {
+    expect(isImportable("AWS::AppSync::GraphQLApi", manifest)).toBe(false);
+    for (const t of LEGACY_IMPORTABLE_TYPES) expect(isImportable(t, manifest)).toBe(true);
+    for (const t of NOT_IMPORTABLE_TYPES) expect(LEGACY_IMPORTABLE_TYPES.has(t)).toBe(false);
+  });
+});
+
+describe("adoptionRefusal (#4536)", () => {
+  test("an importable type with updatable tags is adopted", () => {
+    expect(adoptionRefusal("AWS::S3::Bucket", manifest)).toBeUndefined();
+  });
+
+  test("create-only tags are refused by name", () => {
+    expect(adoptionRefusal("AWS::EC2::KeyPair", manifest)).toMatch(/AWS::EC2::KeyPair's tags can only be set at create/);
+  });
+
+  test("a type CloudFormation cannot import, or one the lexicon does not know, is refused", () => {
+    expect(adoptionRefusal("AWS::IAM::Policy", manifest)).toMatch(/no create and read handlers/);
+    expect(adoptionRefusal("AWS::AppSync::GraphQLApi", manifest)).toMatch(/not supporting resource import/);
+    expect(adoptionRefusal("AWS::Nope::Nope", manifest)).toMatch(/not a type this aws lexicon generated/);
+  });
+});
+
+describe("the lexicon generator keeps handlers (#4536)", () => {
+  test("lexicon-aws.json carries each type's handler operations, and none for a legacy type", () => {
+    const results = [
+      parseCFNSchema(JSON.stringify({
+        typeName: "AWS::Test::Handled",
+        properties: { Name: { type: "string" } },
+        primaryIdentifier: ["/properties/Name"],
+        handlers: { create: { permissions: ["t:C"] }, read: { permissions: ["t:R"] }, delete: { permissions: [] } },
+        additionalProperties: false,
+      })),
+      parseCFNSchema(JSON.stringify({ typeName: "AWS::Test::Legacy", properties: { Name: { type: "string" } }, additionalProperties: false })),
+    ];
+    const json = JSON.parse(generateLexiconJSON(results, new NamingStrategy(results), new Map(), null)) as Record<string, ImportabilityManifestEntry>;
+    const byType = new Map(Object.values(json).filter((e) => e.kind === "resource").map((e) => [e.resourceType, e]));
+    expect(byType.get("AWS::Test::Handled")?.handlers).toEqual(["create", "delete", "read"]);
+    expect(byType.get("AWS::Test::Legacy")?.handlers).toBeUndefined();
+    expect(isImportable("AWS::Test::Handled", byType)).toBe(true);
+    expect(isImportable("AWS::Test::Legacy", byType)).toBe(false);
+  });
+});

package/src/importable.ts

@@ -0,0 +1,83 @@
+/**
+ * Which CloudFormation types chant can adopt into a stack with an IMPORT
+ * change set (#4536; ruled on INTENTIUS/choudoufu#2284 Q5, 2026-10-26).
+ *
+ * A registry type is importable when its schema has `create` and `read`
+ * handlers, which codegen keeps in `lexicon-aws.json` as `handlers`. AWS
+ * documents the exceptions on its "Resource type support" page
+ * (https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html),
+ * and the two short lists below are those exceptions, compared on 2026-10-26
+ * against the pinned spec (sha256:398259716cca…): one legacy type with no
+ * handlers that the page marks importable, and three types with create and
+ * read handlers that the page marks not importable.
+ *
+ * Adoption also needs to write chant's markers after the import, as a
+ * tags-only UPDATE. A type whose tags can only be set at create
+ * (`tagging.tagUpdatable` false) is refused by {@link adoptionRefusal},
+ * never replaced to mark it.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+
+const require = createRequire(moduleSourceUrl(import.meta.url));
+
+/** The slice of a `lexicon-aws.json` entry this module reads. */
+export interface ImportabilityManifestEntry {
+  resourceType: string;
+  kind: string;
+  handlers?: readonly string[];
+  primaryIdentifier?: readonly string[];
+  tagging?: { taggable: boolean; tagOnCreate?: boolean; tagUpdatable: boolean; tagProperty?: string; tagShape?: "list" | "map" };
+}
+
+/** Legacy types (no handlers in the registry schema) that AWS documents as importable. */
+export const LEGACY_IMPORTABLE_TYPES: ReadonlySet<string> = new Set(["AWS::IoTEvents::AlarmModel"]);
+
+/** Types with create and read handlers that AWS documents as not importable. */
+export const NOT_IMPORTABLE_TYPES: ReadonlySet<string> = new Set([
+  "AWS::AppSync::GraphQLApi",
+  "AWS::SES::ConfigurationSetEventDestination",
+  "AWS::SageMaker::Endpoint",
+]);
+
+let cachedManifest: ReadonlyMap<string, ImportabilityManifestEntry> | undefined;
+
+/** The generated registry keyed by type, or an empty map in a checkout that has not generated. */
+export function importabilityManifest(): ReadonlyMap<string, ImportabilityManifestEntry> {
+  if (cachedManifest) return cachedManifest;
+  try {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, ImportabilityManifestEntry>;
+    cachedManifest = new Map(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => [e.resourceType, e]));
+  } catch {
+    cachedManifest = new Map();
+  }
+  return cachedManifest;
+}
+
+/** Whether CloudFormation can import the type into a stack: create and read handlers, or AWS's hand list. */
+export function isImportable(type: string, manifest: ReadonlyMap<string, ImportabilityManifestEntry> = importabilityManifest()): boolean {
+  if (NOT_IMPORTABLE_TYPES.has(type)) return false;
+  if (LEGACY_IMPORTABLE_TYPES.has(type)) return true;
+  const handlers = manifest.get(type)?.handlers ?? [];
+  return handlers.includes("create") && handlers.includes("read");
+}
+
+/**
+ * Why chant refuses to adopt the type, or undefined when it can: not a
+ * generated type, not importable, or tags that can only be set at create
+ * (the marker UPDATE would replace the object). An untaggable type is
+ * adopted on the stack's word alone; the caller says so in its review.
+ */
+export function adoptionRefusal(type: string, manifest: ReadonlyMap<string, ImportabilityManifestEntry> = importabilityManifest()): string | undefined {
+  const entry = manifest.get(type);
+  if (!entry && !LEGACY_IMPORTABLE_TYPES.has(type)) return `${type} is not a type this aws lexicon generated`;
+  if (!isImportable(type, manifest)) {
+    return NOT_IMPORTABLE_TYPES.has(type)
+      ? `${type} is listed by AWS as not supporting resource import`
+      : `${type} has no create and read handlers, so CloudFormation cannot import it`;
+  }
+  if (entry?.tagging?.taggable && entry.tagging.tagUpdatable === false) {
+    return `${type}'s tags can only be set at create, so writing chant's markers would replace it`;
+  }
+  return undefined;
+}

package/src/index-identity.test.ts

@@ -0,0 +1,134 @@
+/**
+ * #4523 on the aws lexicon: never-deployed declarations matched to an
+ * indexed fixture by the CloudFormation `primaryIdentifier`. The fixture is
+ * the emulator check written out on INTENTIUS/behold#1025's design comment,
+ * in miniature: a bucket and a role made outside chant, then a source that
+ * declares them, a second bucket that does not exist, a queue and an
+ * instance.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { matchDeclaredToIndex, type IndexIdentity } from "@intentius/chant/lifecycle/identity-match";
+import { typeListing, type ListingLexicon, type ListingResult } from "@intentius/chant/lifecycle/type-listing";
+import { awsDeclaredIdentity, awsIndexIdentity, isGlobalAwsType, type IdentityManifestEntry } from "./index-identity";
+import { awsKindForListedType } from "./listed-types";
+import { awsPlugin } from "./plugin";
+
+// The manifest rows these types generate (`lexicon-aws.json`): primaryIdentifier
+// and the readOnlyProperties codegen writes as `attrs`, as surface.snapshot.json records them.
+const ROWS: IdentityManifestEntry[] = [
+  { resourceType: "AWS::S3::Bucket", kind: "resource", primaryIdentifier: ["BucketName"], attrs: { Arn: "Arn", DomainName: "DomainName", RegionalDomainName: "RegionalDomainName", WebsiteURL: "WebsiteURL" } },
+  { resourceType: "AWS::IAM::Role", kind: "resource", primaryIdentifier: ["RoleName"], attrs: { Arn: "Arn", RoleId: "RoleId" } },
+  { resourceType: "AWS::SQS::Queue", kind: "resource", primaryIdentifier: ["QueueUrl"], attrs: { Arn: "Arn", QueueUrl: "QueueUrl" } },
+  { resourceType: "AWS::EC2::Instance", kind: "resource", primaryIdentifier: ["InstanceId"], attrs: { InstanceId: "InstanceId", PrivateIp: "PrivateIp", PublicIp: "PublicIp" } },
+  { resourceType: "AWS::DynamoDB::Table", kind: "resource", primaryIdentifier: ["TableName"], attrs: { Arn: "Arn", StreamArn: "StreamArn" } },
+  { resourceType: "AWS::EC2::Route", kind: "resource", primaryIdentifier: ["RouteTableId", "CidrBlock"], attrs: { CidrBlock: "CidrBlock" } },
+];
+const MANIFEST: ReadonlyMap<string, IdentityManifestEntry> = new Map(ROWS.map((e) => [e.resourceType, e]));
+
+const identity: IndexIdentity = { ...awsIndexIdentity, declaredIdentity: (t, p) => awsDeclaredIdentity(t, p, MANIFEST) };
+const KINDS: ReadonlySet<string> = new Set(MANIFEST.keys());
+const aws: ListingLexicon = {
+  name: awsPlugin.name,
+  deepNormalizationHooks: awsPlugin.deepNormalizationHooks,
+  listedTypes: { ...awsPlugin.listedTypes!, kindFor: (t) => awsKindForListedType(t, KINDS) },
+};
+const listing = JSON.parse(readFileSync(join(import.meta.dirname, "testdata", "indexed", "identity.listing.json"), "utf-8")) as ListingResult;
+const doc = typeListing(listing, [aws]);
+
+const SOURCE = [
+  { name: "assets", entityType: "AWS::S3::Bucket", props: { BucketName: "cli-made-assets" } },
+  { name: "runner", entityType: "AWS::IAM::Role", props: { RoleName: "cli-made-role", AssumeRolePolicyDocument: {} } },
+  { name: "archive", entityType: "AWS::S3::Bucket", props: { BucketName: "never-made-archive" } },
+  { name: "jobs", entityType: "AWS::SQS::Queue", props: { QueueName: "cli-made-queue" } },
+  { name: "box", entityType: "AWS::EC2::Instance", props: { InstanceType: "t3.micro", ImageId: "ami-0abcdef1234567890" } },
+  { name: "carts", entityType: "AWS::DynamoDB::Table", props: { TableName: "carts" } },
+];
+
+describe("awsDeclaredIdentity", () => {
+  test("a declared name is the identifier", () => {
+    expect(awsDeclaredIdentity("AWS::S3::Bucket", { BucketName: "b1" }, MANIFEST)).toEqual({ kind: "identifier", listedType: "AWS::S3::Bucket", identifier: "b1", global: false });
+    expect(awsDeclaredIdentity("AWS::IAM::Role", { RoleName: "r1" }, MANIFEST)).toMatchObject({ identifier: "r1", global: true });
+  });
+
+  test("a server-assigned identity is refused, naming the read-only part", () => {
+    const queue = awsDeclaredIdentity("AWS::SQS::Queue", { QueueName: "q" }, MANIFEST);
+    expect(queue).toMatchObject({ kind: "unmatchable", reason: "no-binding" });
+    expect(queue.kind === "unmatchable" && queue.detail).toContain("QueueUrl");
+    // Even a declaration that spells an instance id cannot be trusted to name the instance.
+    expect(awsDeclaredIdentity("AWS::EC2::Instance", { InstanceId: "i-1" }, MANIFEST)).toMatchObject({ kind: "unmatchable", reason: "no-binding" });
+  });
+
+  test("a part the declaration leaves out, or spells with a Ref, is not in the declaration", () => {
+    expect(awsDeclaredIdentity("AWS::S3::Bucket", {}, MANIFEST)).toMatchObject({ reason: "no-binding", detail: expect.stringContaining("identity is not in the declaration") });
+    expect(awsDeclaredIdentity("AWS::S3::Bucket", { BucketName: { Ref: "Name" } }, MANIFEST)).toMatchObject({ reason: "no-binding" });
+  });
+
+  test("an identifier with a server-assigned part is refused even when the rest is declared", () => {
+    expect(awsDeclaredIdentity("AWS::EC2::Route", { RouteTableId: "rtb-1", DestinationCidrBlock: "0.0.0.0/0" }, MANIFEST)).toMatchObject({ reason: "no-binding" });
+  });
+
+  test("a type with no primary identifier on record is unsupported", () => {
+    expect(awsDeclaredIdentity("AWS::Made::Up", { Name: "x" }, MANIFEST)).toMatchObject({ kind: "unmatchable", reason: "unsupported-kind" });
+  });
+
+  test("global types are the ones behold's lister indexes at location global", () => {
+    expect(isGlobalAwsType("AWS::IAM::Role")).toBe(true);
+    expect(isGlobalAwsType("AWS::Route53::HostedZone")).toBe(true);
+    expect(isGlobalAwsType("AWS::S3::Bucket")).toBe(false);
+  });
+
+  test("the plugin declares it", () => {
+    expect(awsPlugin.indexIdentity?.substrate).toBe("aws");
+  });
+});
+
+describe("matchDeclaredToIndex on the aws fixture", () => {
+  const { matches } = matchDeclaredToIndex(SOURCE, [doc], identity, { region: "us-east-1" });
+
+  test("a never-deployed declared bucket and role bind to their indexed resources", () => {
+    expect(matches.assets).toMatchObject({ verdict: "bound", node: "aws/000000000000/us-east-1/AWS::S3::Bucket/cli-made-assets" });
+    expect(matches.runner).toMatchObject({ verdict: "bound", node: "aws/000000000000/global/AWS::IAM::Role/cli-made-role" });
+  });
+
+  test("a bucket the index listed and did not find is absent", () => {
+    expect(matches.archive).toMatchObject({ verdict: "absent", identifier: "never-made-archive", location: "us-east-1" });
+  });
+
+  test("a queue and an instance cannot match from source: no-binding, even though both are indexed", () => {
+    expect(matches.jobs).toMatchObject({ verdict: "not-observed", reason: "no-binding" });
+    expect(matches.box).toMatchObject({ verdict: "not-observed", reason: "no-binding" });
+  });
+
+  test("a type outside the index's --types is not observed (filtered), not absent", () => {
+    expect(matches.carts).toMatchObject({ verdict: "not-observed", reason: "filtered", listedType: "AWS::DynamoDB::Table" });
+  });
+
+  test("the same source over an index without the bucket type reports the buckets filtered", () => {
+    const narrowed: ListingResult = {
+      ...listing,
+      scope: { ...listing.scope, types: ["AWS::EC2::Instance", "AWS::IAM::Role", "AWS::SQS::Queue"] },
+      resources: listing.resources.filter((r) => r.listedType !== "AWS::S3::Bucket"),
+      coverage: listing.coverage.filter((c) => c.listedType !== "AWS::S3::Bucket"),
+    };
+    const { matches: m } = matchDeclaredToIndex(SOURCE, [typeListing(narrowed, [aws])], identity, { region: "us-east-1" });
+    expect(m.assets).toMatchObject({ verdict: "not-observed", reason: "filtered" });
+    expect(m.archive).toMatchObject({ verdict: "not-observed", reason: "filtered" });
+    expect(m.runner).toMatchObject({ verdict: "bound" });
+  });
+
+  test("two indexed buckets with the bucket's name are refused by name", () => {
+    const twice: ListingResult = {
+      ...listing,
+      scope: { ...listing.scope, locations: ["us-east-1", "us-west-2"] },
+      resources: [...listing.resources, { ...listing.resources[0], location: "us-west-2" }],
+      coverage: [...listing.coverage, { listedType: "AWS::S3::Bucket", location: "us-west-2", verdict: "listed" }],
+    };
+    const { matches: m } = matchDeclaredToIndex([SOURCE[0]], [typeListing(twice, [aws])], identity);
+    expect(m.assets).toMatchObject({
+      verdict: "refused",
+      candidates: ["aws/000000000000/us-east-1/AWS::S3::Bucket/cli-made-assets", "aws/000000000000/us-west-2/AWS::S3::Bucket/cli-made-assets"],
+    });
+  });
+});

package/src/index-identity.ts

@@ -0,0 +1,98 @@
+/**
+ * The aws lexicon's identity rule for indexed resources (#4523, rule written
+ * out on INTENTIUS/behold#1025's design comment).
+ *
+ * The same evidence the stack read's identity fallback uses (#1647,
+ * ./identity-observe.ts): the CloudFormation schema's `primaryIdentifier`,
+ * which codegen compiled into `lexicon-aws.json`, read off the declared
+ * props and `|`-joined the way Cloud Control spells an identifier. behold's
+ * lister (behold#1029) writes that Cloud Control `Identifier` as each indexed
+ * node's `nativeId`, so a never-deployed bucket declared with `BucketName`
+ * and a role declared with `RoleName` match their indexed objects by value.
+ *
+ * What cannot match:
+ * - an identifier part the schema lists in `readOnlyProperties` is assigned
+ *   by the service (`InstanceId` for `AWS::EC2::Instance`, `QueueUrl` for
+ *   `AWS::SQS::Queue`), so no declaration states it: `no-binding`;
+ * - a part the declaration leaves out or spells with a Ref or an intrinsic:
+ *   `no-binding`, "identity is not in the declaration";
+ * - a type with no primary identifier on record: `unsupported-kind`.
+ *
+ * Global types are the prefixes behold's aws lister lists once per account at
+ * location `global` (behold src/cloud-lister/aws.ts, `isGlobalAwsType`).
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import type { DeclaredIdentity, IndexIdentity } from "@intentius/chant/lifecycle/identity-match";
+
+const require = createRequire(moduleSourceUrl(import.meta.url));
+
+/** One `lexicon-aws.json` entry, the fields this rule reads. */
+export interface IdentityManifestEntry {
+  resourceType: string;
+  kind: string;
+  primaryIdentifier?: string[];
+  /** GetAtt name -> CloudFormation attribute: the schema's `readOnlyProperties`. */
+  attrs?: Record<string, string>;
+}
+
+const GLOBAL_TYPE_PREFIXES = ["AWS::IAM::", "AWS::CloudFront::", "AWS::Route53::", "AWS::Organizations::", "AWS::GlobalAccelerator::"];
+
+/** True for a type behold's lister indexes at location `global`. */
+export function isGlobalAwsType(type: string): boolean {
+  return GLOBAL_TYPE_PREFIXES.some((p) => type.startsWith(p));
+}
+
+let cachedManifest: ReadonlyMap<string, IdentityManifestEntry> | undefined;
+
+/** The manifest keyed by type, or an empty one in a checkout that has not generated (every type is then `unsupported-kind`). */
+function defaultManifest(): ReadonlyMap<string, IdentityManifestEntry> {
+  if (cachedManifest) return cachedManifest;
+  try {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, IdentityManifestEntry>;
+    cachedManifest = new Map(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => [e.resourceType, e]));
+  } catch {
+    cachedManifest = new Map();
+  }
+  return cachedManifest;
+}
+
+/**
+ * The identifier an aws declaration spells for the index, or why it spells
+ * none. `manifest` is the generated `lexicon-aws.json` keyed by type; a test
+ * passes a table.
+ */
+export function awsDeclaredIdentity(
+  entityType: string,
+  props: Record<string, unknown>,
+  manifest: ReadonlyMap<string, IdentityManifestEntry> = defaultManifest(),
+): DeclaredIdentity {
+  const entry = manifest.get(entityType);
+  const parts = entry?.primaryIdentifier;
+  if (!entry || entry.kind !== "resource" || !parts || parts.length === 0) {
+    return { kind: "unmatchable", reason: "unsupported-kind", detail: `${entityType} has no primary identifier on record` };
+  }
+  const readOnly = new Set(Object.values(entry.attrs ?? {}));
+  const serverAssigned = parts.filter((p) => readOnly.has(p));
+  if (serverAssigned.length > 0) {
+    return {
+      kind: "unmatchable",
+      reason: "no-binding",
+      detail: `the identity of ${entityType} (${parts.join(", ")}) is assigned by the service (${serverAssigned.join(", ")}), so no declaration states it`,
+    };
+  }
+  const values: string[] = [];
+  for (const part of parts) {
+    const v = props[part];
+    if ((typeof v !== "string" && typeof v !== "number") || String(v) === "") {
+      return { kind: "unmatchable", reason: "no-binding", detail: `identity is not in the declaration (${entityType} ${part})` };
+    }
+    values.push(String(v));
+  }
+  return { kind: "identifier", listedType: entityType, identifier: values.join("|"), global: isGlobalAwsType(entityType) };
+}
+
+export const awsIndexIdentity: IndexIdentity = {
+  substrate: "aws",
+  declaredIdentity: (entityType, props) => awsDeclaredIdentity(entityType, props),
+};

package/src/index-import.test.ts

@@ -0,0 +1,242 @@
+/**
+ * #4524 on the aws lexicon: `chant import --index` over a fixture index.
+ *
+ * The fixture (testdata/indexed/import.listing.json) is a VPC with a subnet
+ * and a security group in it, an ECS task definition whose task role is an
+ * IAM role, an RDS instance whose master password the lister masked, a
+ * bucket, and one object of a type the lexicon does not generate. It is
+ * typed (#4521) and its edges derived (#4522, #4523) as `behold index` would
+ * write it, then imported through the aws seam and CFGenerator, the codegen
+ * `chant import <template>` uses.
+ *
+ * The emulator round trip (index, import, build, then the declared entities
+ * bind to their indexed resources through #4523 with no drift) is a
+ * maintainer run; the steps are in the #4524 issue comment.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { build } from "@intentius/chant/build";
+import { MASKED } from "@intentius/chant/deep-observation";
+import { deriveEdges } from "@intentius/chant/lifecycle/derive-edges";
+import { awsDeclaredIdentity, awsIndexIdentity, type IdentityManifestEntry } from "./index-identity";
+import type { IndexDocument } from "@intentius/chant/lifecycle/index-document";
+import { declaredNodes, planIndexImport, type IndexImportSelection } from "@intentius/chant/lifecycle/index-import";
+import { typeListing, type ListingLexicon, type ListingResult } from "@intentius/chant/lifecycle/type-listing";
+import { indexImportReportJson, renderIndexImport } from "@intentius/chant/cli/commands/import-index";
+import type { LexiconPlugin } from "@intentius/chant/lexicon";
+import { awsImportProperties, createAwsIndexImport } from "./index-import";
+import { awsKindForListedType } from "./listed-types";
+import { awsPlugin } from "./plugin";
+import { awsSerializer } from "./serializer";
+
+// The registry rows for the fixture's types: primaryIdentifier and the
+// schema's readOnlyProperties, which codegen writes as `attrs`.
+const ROWS: IdentityManifestEntry[] = [
+  { resourceType: "AWS::EC2::VPC", kind: "resource", primaryIdentifier: ["VpcId"], attrs: { VpcId: "VpcId", CidrBlockAssociations: "CidrBlockAssociations", DefaultNetworkAcl: "DefaultNetworkAcl", DefaultSecurityGroup: "DefaultSecurityGroup", Ipv6CidrBlocks: "Ipv6CidrBlocks" } },
+  { resourceType: "AWS::EC2::Subnet", kind: "resource", primaryIdentifier: ["SubnetId"], attrs: { SubnetId: "SubnetId", NetworkAclAssociationId: "NetworkAclAssociationId", Ipv6CidrBlocks: "Ipv6CidrBlocks" } },
+  { resourceType: "AWS::EC2::SecurityGroup", kind: "resource", primaryIdentifier: ["Id"], attrs: { GroupId: "GroupId", Id: "Id" } },
+  { resourceType: "AWS::IAM::Role", kind: "resource", primaryIdentifier: ["RoleName"], attrs: { Arn: "Arn", RoleId: "RoleId" } },
+  { resourceType: "AWS::ECS::TaskDefinition", kind: "resource", primaryIdentifier: ["TaskDefinitionArn"], attrs: { TaskDefinitionArn: "TaskDefinitionArn" } },
+  { resourceType: "AWS::RDS::DBInstance", kind: "resource", primaryIdentifier: ["DBInstanceIdentifier"], attrs: { DBInstanceArn: "DBInstanceArn", DbiResourceId: "DbiResourceId", Endpoint_Address: "Endpoint.Address", Endpoint_Port: "Endpoint.Port" } },
+  { resourceType: "AWS::S3::Bucket", kind: "resource", primaryIdentifier: ["BucketName"], attrs: { Arn: "Arn", DomainName: "DomainName", RegionalDomainName: "RegionalDomainName", WebsiteURL: "WebsiteURL" } },
+];
+const MANIFEST: ReadonlyMap<string, IdentityManifestEntry> = new Map(ROWS.map((e) => [e.resourceType, e]));
+const KINDS: ReadonlySet<string> = new Set(MANIFEST.keys());
+
+const listingLexicon: ListingLexicon = {
+  name: awsPlugin.name,
+  deepNormalizationHooks: awsPlugin.deepNormalizationHooks,
+  listedTypes: { ...awsPlugin.listedTypes!, kindFor: (t) => awsKindForListedType(t, KINDS) },
+};
+const identity = { ...awsIndexIdentity, declaredIdentity: (t: string, p: Record<string, unknown>) => awsDeclaredIdentity(t, p, MANIFEST) };
+const importLexicon = { name: "aws", indexImport: createAwsIndexImport(MANIFEST), indexIdentity: identity };
+// renderIndexImport needs the template generator, and the plan needs the seam with the test's registry rows.
+const plugin = { ...awsPlugin, indexImport: importLexicon.indexImport } as LexiconPlugin;
+
+const raw = readFileSync(join(import.meta.dirname, "testdata", "indexed", "import.listing.json"), "utf-8");
+
+/** The fixture as `behold index` writes it: typed, then derived edges. */
+function indexFrom(listing: ListingResult): IndexDocument {
+  return deriveEdges(typeListing(listing, [listingLexicon]), [
+    { name: "aws", referenceCatalog: awsPlugin.referenceCatalog, indexIdentity: identity },
+  ]);
+}
+const doc = indexFrom(JSON.parse(raw) as ListingResult);
+const ALL: IndexImportSelection = { all: true };
+
+function importOf(d: IndexDocument, selection: IndexImportSelection, declared?: ReadonlyMap<string, string>) {
+  const plan = planIndexImport([d], selection, [importLexicon], declared ? { declared } : {});
+  const { files, warnings } = renderIndexImport(plan, [plugin]);
+  return { plan, files, warnings };
+}
+
+/** Build the generated source and return the synthesized template. */
+async function synth(files: Array<{ path: string; content: string }>): Promise<Record<string, any>> {
+  const dir = mkdtempSync(join(import.meta.dirname, "../.index-import-tmp-"));
+  try {
+    const src = join(dir, "src");
+    mkdirSync(src);
+    for (const f of files) writeFileSync(join(src, f.path), f.content);
+    const result = await build(src, [awsSerializer]);
+    expect(result.errors.map((e) => e.message)).toEqual([]);
+    return JSON.parse(result.outputs.get("aws") as string);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const nodeById = new Map(doc.graph.nodes.map((n) => [n.id, n]));
+
+describe("chant import --index on the aws fixture", () => {
+  test("the edges the fixture should carry are derived", () => {
+    const rules = doc.graph.edges.map((e) => e.rule);
+    expect(rules).toContain("aws:AWS::EC2::Subnet:VpcId");
+    expect(rules).toContain("aws:AWS::EC2::SecurityGroup:VpcId");
+    expect(rules).toContain("aws:AWS::ECS::TaskDefinition:TaskRoleArn");
+  });
+
+  test("round trip: import, then synth, gives each resource the indexed properties", async () => {
+    const { plan, files } = importOf(doc, ALL);
+    expect(files.map((f) => f.path)).toEqual(["main.ts"]);
+    const template = await synth(files);
+
+    const imported = plan.report.resources.filter((r) => r.status === "imported");
+    expect(imported.map((r) => r.identity.listedType).sort()).toEqual([
+      "AWS::EC2::SecurityGroup",
+      "AWS::EC2::Subnet",
+      "AWS::EC2::VPC",
+      "AWS::ECS::TaskDefinition",
+      "AWS::IAM::Role",
+      "AWS::RDS::DBInstance",
+      "AWS::S3::Bucket",
+    ]);
+    const byLogical = new Map(imported.map((r) => [r.logicalId!, nodeById.get(r.node)!]));
+    const params = new Set(plan.report.parameters.map((p) => p.name));
+
+    // Each reference and parameter read back as the value it stands for.
+    const resolveBack = (v: unknown): unknown => {
+      if (Array.isArray(v)) return v.map(resolveBack);
+      if (v && typeof v === "object") {
+        const o = v as Record<string, unknown>;
+        if (typeof o.Ref === "string" && Object.keys(o).length === 1) {
+          if (params.has(o.Ref)) return MASKED;
+          const n = byLogical.get(o.Ref);
+          if (n) return n.nativeId;
+        }
+        if (Array.isArray(o["Fn::GetAtt"]) && Object.keys(o).length === 1) {
+          const [id, attr] = o["Fn::GetAtt"] as [string, string];
+          const n = byLogical.get(id);
+          if (n && attr === "Arn") return n.facts?.cloudIds?.find((c) => c.kind === "arn")?.value;
+        }
+        return Object.fromEntries(Object.entries(o).map(([k, x]) => [k, resolveBack(x)]));
+      }
+      return v;
+    };
+
+    for (const [logicalId, node] of byLogical) {
+      const built = template.Resources[logicalId];
+      expect(built.Type).toBe(node.kind);
+      const expected = awsImportProperties(node.kind, node.attrs, MANIFEST);
+      expect(resolveBack(built.Properties ?? {})).toEqual(expected);
+    }
+  });
+
+  test("every imported resource builds with DeletionPolicy and UpdateReplacePolicy Retain (#4536)", async () => {
+    const { plan, files } = importOf(doc, ALL);
+    const template = await synth(files);
+    for (const r of plan.report.resources.filter((x) => x.status === "imported")) {
+      expect(template.Resources[r.logicalId!]).toMatchObject({ DeletionPolicy: "Retain", UpdateReplacePolicy: "Retain" });
+    }
+  });
+
+  test("the same index and selection give byte-identical files, in any listing order", () => {
+    const first = importOf(doc, ALL);
+    const shuffled = JSON.parse(raw) as ListingResult;
+    shuffled.resources = [...shuffled.resources].reverse();
+    const again = importOf(indexFrom(shuffled), ALL);
+    expect(again.files).toEqual(first.files);
+    expect(indexImportReportJson(again.plan.report)).toBe(indexImportReportJson(first.plan.report));
+    expect(importOf(doc, ALL).files).toEqual(first.files);
+  });
+
+  test("a masked secret is written as a NoEcho parameter, never as a value", async () => {
+    const { plan, files } = importOf(doc, { types: ["AWS::RDS::DBInstance"] });
+    const source = files[0].content;
+    expect(source).not.toContain(MASKED);
+    expect(plan.report.parameters).toHaveLength(1);
+    const param = plan.report.parameters[0];
+    expect(param.path).toBe("MasterUserPassword");
+    expect(source).toContain(`fill in the parameter ${param.name}`);
+    const template = await synth(files);
+    expect(template.Parameters[param.name]).toMatchObject({ Type: "String", NoEcho: true });
+    const db = plan.report.resources.find((r) => r.status === "imported")!;
+    expect(template.Resources[db.logicalId!].Properties.MasterUserPassword).toEqual({ Ref: param.name });
+    expect(JSON.stringify(template)).not.toContain(MASKED);
+  });
+
+  test("derived edges become Ref and GetAtt between imported resources", async () => {
+    const { plan, files } = importOf(doc, ALL);
+    const template = await synth(files);
+    const logical = (type: string) => plan.report.resources.find((r) => r.identity.listedType === type)!.logicalId!;
+    const vpc = logical("AWS::EC2::VPC");
+    expect(template.Resources[logical("AWS::EC2::Subnet")].Properties.VpcId).toEqual({ Ref: vpc });
+    expect(template.Resources[logical("AWS::EC2::SecurityGroup")].Properties.VpcId).toEqual({ Ref: vpc });
+    expect(template.Resources[logical("AWS::ECS::TaskDefinition")].Properties.TaskRoleArn).toEqual({
+      "Fn::GetAtt": [logical("AWS::IAM::Role"), "Arn"],
+    });
+    const subnet = plan.report.resources.find((r) => r.identity.listedType === "AWS::EC2::Subnet")!;
+    expect(subnet.references).toContainEqual({
+      path: "VpcId",
+      target: "aws/000000000000/us-east-1/AWS::EC2::VPC/vpc-0imp",
+      rule: "aws:AWS::EC2::Subnet:VpcId",
+      written: "reference",
+    });
+  });
+
+  test("an edge to a resource outside the selection stays a literal, with a comment naming the edge", () => {
+    const { plan, files } = importOf(doc, { types: ["AWS::EC2::Subnet"] });
+    const source = files[0].content;
+    expect(source).toContain('"vpc-0imp"');
+    expect(source).toMatch(/VpcId = "vpc-0imp" stays a literal: derived edge aws:AWS::EC2::Subnet:VpcId to aws\/000000000000\/us-east-1\/AWS::EC2::VPC\/vpc-0imp; the target is not in the selection/);
+    const subnet = plan.report.resources[0];
+    expect(subnet.references?.[0]).toMatchObject({ path: "VpcId", written: "literal", reason: "the target is not in the selection" });
+  });
+
+  test("aws: tags and read-only properties are left out", () => {
+    const vpc = doc.graph.nodes.find((n) => n.kind === "AWS::EC2::VPC")!;
+    const props = awsImportProperties(vpc.kind, vpc.attrs, MANIFEST);
+    expect(props.VpcId).toBeUndefined();
+    expect(props.Tags).toEqual([{ Key: "Name", Value: "shop" }]);
+    const db = doc.graph.nodes.find((n) => n.kind === "AWS::RDS::DBInstance")!;
+    expect(awsImportProperties(db.kind, db.attrs, MANIFEST).Endpoint).toBeUndefined();
+  });
+
+  test("a declared bucket is reported as declared, not imported again", () => {
+    const declared = declaredNodes(
+      [doc],
+      new Map([["aws", [{ name: "assets", entityType: "AWS::S3::Bucket", props: { BucketName: "imp-assets" } }]]]),
+      [importLexicon],
+    );
+    const { plan, files } = importOf(doc, ALL, declared);
+    const bucket = plan.report.resources.find((r) => r.identity.listedType === "AWS::S3::Bucket")!;
+    expect(bucket).toMatchObject({ status: "declared", entity: "assets" });
+    expect(files[0].content).not.toContain("imp-assets");
+  });
+
+  test("an unmapped type is named as unsupported, with its identity and cloud ids in the report", () => {
+    const { plan } = importOf(doc, ALL);
+    const other = plan.report.resources.find((r) => r.identity.listedType === "AWS::Example::NotGenerated")!;
+    expect(other.status).toBe("unsupported");
+    expect(other.reason).toMatch(/no lexicon kind maps/);
+    const role = plan.report.resources.find((r) => r.identity.listedType === "AWS::IAM::Role")!;
+    expect(role.identity).toEqual({ substrate: "aws", scopeId: "000000000000", listedType: "AWS::IAM::Role", location: "global", nativeId: "imp-task-role" });
+    expect(role.cloudIds).toContainEqual({ kind: "arn", value: "arn:aws:iam::000000000000:role/imp-task-role" });
+    // The global role joins the only region, so one file holds everything.
+    expect(plan.groups.map((g) => g.dir)).toEqual([""]);
+  });
+
+  test("the plugin declares the seam", () => {
+    expect(awsPlugin.indexImport).toBeDefined();
+  });
+});