@intentius/chant-lexicon-aws 0.124.51 → 0.124.54

package/dist/index-identity.js

@@ -0,0 +1,79 @@
+/**
+ * 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";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+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) {
+    return GLOBAL_TYPE_PREFIXES.some((p) => type.startsWith(p));
+}
+let cachedManifest;
+/** The manifest keyed by type, or an empty one in a checkout that has not generated (every type is then `unsupported-kind`). */
+function defaultManifest() {
+    if (cachedManifest)
+        return cachedManifest;
+    try {
+        const manifest = require("./generated/lexicon-aws.json");
+        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, props, manifest = defaultManifest()) {
+    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 = [];
+    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 = {
+    substrate: "aws",
+    declaredIdentity: (entityType, props) => awsDeclaredIdentity(entityType, props),
+};

package/dist/index-import.d.ts

@@ -0,0 +1,17 @@
+import type { IndexImportCodegen, IndexImportTarget } from "@intentius/chant/lifecycle/index-import";
+/** One `lexicon-aws.json` entry, the fields this seam reads. */
+export interface ImportManifestEntry {
+    resourceType: string;
+    kind: string;
+    /** GetAtt name -> CloudFormation attribute: the schema's `readOnlyProperties`. */
+    attrs?: Record<string, string>;
+}
+/** The properties a declaration of `type` can hold, from an indexed node's attrs. */
+export declare function awsImportProperties(type: string, attrs: Record<string, unknown>, manifest?: ReadonlyMap<string, ImportManifestEntry>): Record<string, unknown>;
+/** `value` as a reference to `target`, or undefined. */
+export declare function awsImportReference(value: string, target: IndexImportTarget, manifest?: ReadonlyMap<string, ImportManifestEntry>): unknown | undefined;
+/** The resource attributes `chant import --index` writes on every resource it imports (#4536). */
+export declare const ADOPTED_RESOURCE_ATTRIBUTES: Readonly<Record<string, string>>;
+export declare function createAwsIndexImport(manifest?: ReadonlyMap<string, ImportManifestEntry>): IndexImportCodegen;
+export declare const awsIndexImport: IndexImportCodegen;
+//# sourceMappingURL=index-import.d.ts.map

package/dist/index-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-import.d.ts","sourceRoot":"","sources":["../src/index-import.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAKrG,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAiCD,qFAAqF;AACrF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,GAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAqB,GACrE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAQD,wDAAwD;AACxD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,EACzB,QAAQ,GAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAqB,GACrE,OAAO,GAAG,SAAS,CAUrB;AAED,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAA+D,CAAC;AAEzI,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,kBAAkB,CA0B5G;AAED,eAAO,MAAM,cAAc,EAAE,kBAA2C,CAAC"}

package/dist/index-import.js

@@ -0,0 +1,115 @@
+/**
+ * The aws lexicon's index import seam (#4524, `chant import --index`).
+ *
+ * behold's lister reads AWS through Cloud Control, which returns each
+ * object's CloudFormation resource model, and #4521 normalizes it with this
+ * lexicon's deep hooks. So an indexed node's `attrs` already are
+ * CloudFormation properties, and the import IR is the one the CloudFormation
+ * template parser writes (`{ __intrinsic: "Ref" }` and so on), which
+ * `CFGenerator` turns into source.
+ *
+ * - Properties the schema lists in `readOnlyProperties` (the registry's
+ *   `attrs`) are left out, because no declaration can set them. Tags whose
+ *   key starts with `aws:` are left out too: CloudFormation sets them and
+ *   refuses them in a template.
+ * - A value that names another imported resource becomes `Ref` when it is
+ *   that resource's Cloud Control identifier (a single-part one; for the
+ *   types the catalog joins, Ref returns that identifier), and
+ *   `GetAtt(<id>, "Arn")` when it is the resource's ARN and the type has an
+ *   `Arn` attribute. Anything else stays a literal.
+ * - A masked value becomes a `String` parameter with `NoEcho`.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedManifest;
+/** The generated registry keyed by type, or an empty map in a checkout that has not generated. */
+function defaultManifest() {
+    if (cachedManifest)
+        return cachedManifest;
+    try {
+        const manifest = require("./generated/lexicon-aws.json");
+        cachedManifest = new Map(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => [e.resourceType, e]));
+    }
+    catch {
+        cachedManifest = new Map();
+    }
+    return cachedManifest;
+}
+const CFN_TYPE = /^AWS::[A-Za-z0-9]+::[A-Za-z0-9]+$/;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Tags without the `aws:` ones, in either shape CloudFormation uses (a Key/Value list or a map). */
+function withoutAwsTags(tags) {
+    if (Array.isArray(tags)) {
+        return tags.filter((t) => !(isRecord(t) && typeof t.Key === "string" && t.Key.startsWith("aws:")));
+    }
+    if (isRecord(tags)) {
+        return Object.fromEntries(Object.entries(tags).filter(([k]) => !k.startsWith("aws:")));
+    }
+    return tags;
+}
+/** The properties a declaration of `type` can hold, from an indexed node's attrs. */
+export function awsImportProperties(type, attrs, manifest = defaultManifest()) {
+    const readOnly = new Set(Object.values(manifest.get(type)?.attrs ?? {}).map((a) => a.split(".")[0]));
+    const out = {};
+    for (const key of Object.keys(attrs).sort()) {
+        if (readOnly.has(key))
+            continue;
+        const value = key === "Tags" ? withoutAwsTags(attrs[key]) : attrs[key];
+        if (key === "Tags" && ((Array.isArray(value) && value.length === 0) || (isRecord(value) && Object.keys(value).length === 0)))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/** True when `type` exposes `Arn` to GetAtt, or when there is no registry to ask. */
+function hasArnAttribute(type, manifest) {
+    if (manifest.size === 0)
+        return true;
+    return Object.values(manifest.get(type)?.attrs ?? {}).includes("Arn");
+}
+/** `value` as a reference to `target`, or undefined. */
+export function awsImportReference(value, target, manifest = defaultManifest()) {
+    const node = target.node;
+    if (node.nativeId !== undefined && value === node.nativeId && !value.includes("|")) {
+        return { __intrinsic: "Ref", name: target.logicalId };
+    }
+    const isArn = (node.facts?.cloudIds ?? []).some((c) => c.kind === "arn" && c.value === value);
+    if (isArn && hasArnAttribute(node.kind, manifest)) {
+        return { __intrinsic: "GetAtt", logicalId: target.logicalId, attribute: "Arn" };
+    }
+    return undefined;
+}
+/** The resource attributes `chant import --index` writes on every resource it imports (#4536). */
+export const ADOPTED_RESOURCE_ATTRIBUTES = { DeletionPolicy: "Retain", UpdateReplacePolicy: "Retain" };
+export function createAwsIndexImport(manifest) {
+    const m = () => manifest ?? defaultManifest();
+    return {
+        resource(node) {
+            if (!CFN_TYPE.test(node.kind))
+                return { unsupported: `${node.kind} is not a CloudFormation resource type` };
+            // Retain on every imported resource until a person changes it in source
+            // (#4536, ruled on choudoufu#2284 Q4): CloudFormation deletes at stack
+            // level and reads no per-resource marker, so an adopted object is never
+            // deleted on the stack's word alone. Import requires a DeletionPolicy.
+            return { type: node.kind, properties: awsImportProperties(node.kind, node.attrs ?? {}, m()), attributes: { ...ADOPTED_RESOURCE_ATTRIBUTES } };
+        },
+        reference: (value, target) => awsImportReference(value, target, m()),
+        secretParameter(name, context) {
+            return {
+                name,
+                type: "String",
+                description: `${context.path} of ${context.node.id}, masked in the index`,
+                constraints: { NoEcho: true },
+            };
+        },
+        parameterReference: (name) => ({ __intrinsic: "Ref", name }),
+        typeLabel(node) {
+            const last = node.kind.split("::").pop() ?? "Resource";
+            return last.charAt(0).toUpperCase() + last.slice(1);
+        },
+    };
+}
+export const awsIndexImport = createAwsIndexImport();

package/dist/integrity.json

@@ -1,8 +1,8 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "c32fdc442ad95fe1498bf3b3f185bd992e31930166bb0a95cb3e5b45cd7ae71f",
-    "meta.json": "6f48557ed4203cbdeafdb47e7270fdf3533f6d6e6189987246301ed8e72170e9",
+    "manifest.json": "ce95b454998a3f0d965ce16cb3ff3063159ea5505535e05a86e311988c8f163a",
+    "meta.json": "5a61f147f0c79262967f826c69a53b8b21fe6c41c6142e6c6c235b595482357f",
     "types/index.d.ts": "8651f9ae166668f4311eea1fe61c3fe235f345947951c1d23d1df24a4fd3384f",
     "rules/hardcoded-region.ts": "957eadcaa9f39cc17d21437565d7a94607d9b082cf28918b178fa067f07498a9",
     "rules/iam-wildcard.ts": "10f5065fa2bbf2c8ce23dfb475a56df33f280df87784e44fec641b2584cbf333",
@@ -75,5 +75,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "8780b94ce60aded935938d5ef20ea667738354051da1bf9ca6d70d9886f65d21"
   },
-  "composite": "8ee7219a12f52d63705c15d96a7f2b1d5dfdbab8612241e884d8a8a159e67d56"
+  "composite": "e81efc6cc87353d56bddf1aa86498a99f27a75992d078ce95e8e18691101d16b"
 }

package/dist/listed-types.d.ts

@@ -0,0 +1,11 @@
+import type { ListedTypeMapping } from "@intentius/chant/lifecycle/type-listing";
+/**
+ * The aws kind for a Cloud Control type, or undefined. With no kind set (no
+ * generated registry) every well-formed CloudFormation type maps, which is
+ * what the rest of the lexicon assumes before `chant generate` has run.
+ */
+export declare function awsKindForListedType(listedType: string, kinds?: ReadonlySet<string> | null): string | undefined;
+/** The inverse, for tests and for a reader naming what to list: the same name. */
+export declare function awsListedTypeForKind(kind: string): string;
+export declare const awsListedTypes: ListedTypeMapping;
+//# sourceMappingURL=listed-types.d.ts.map

package/dist/listed-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listed-types.d.ts","sourceRoot":"","sources":["../src/listed-types.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAsBjF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAuB,GAAG,MAAM,GAAG,SAAS,CAIjI;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,eAAO,MAAM,cAAc,EAAE,iBAG5B,CAAC"}

package/dist/listed-types.js

@@ -0,0 +1,52 @@
+/**
+ * Cloud Control's type names as aws lexicon kinds (#4521).
+ *
+ * behold#1029 lists AWS through Cloud Control `ListResources`, which names
+ * each object by its CloudFormation type (`AWS::S3::Bucket`), and the aws
+ * lexicon's kinds are those same names. So the mapping is the identity, kept
+ * to the types the lexicon generated: a type outside `lexicon-aws.json` (one
+ * newer than the pinned registry, or a third-party type) has no kind here and
+ * stays an unknown-kind node. Cloud Control returns the CloudFormation
+ * resource model, which is the tree the deep reader returns too
+ * (./deep-observe.ts), so no reshaping.
+ */
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+// A CloudFormation type name: `<Organization>::<Service>::<Resource>`. The
+// organization is not always AWS (`Alexa::ASK::Skill`), so it is not pinned.
+const CFN_TYPE = /^[A-Za-z0-9]+::[A-Za-z0-9]+::[A-Za-z0-9]+$/;
+let cachedKinds;
+/** The resource kinds `chant generate` wrote, or null in a checkout that has not generated. */
+function generatedKinds() {
+    if (cachedKinds !== undefined)
+        return cachedKinds;
+    try {
+        const manifest = require("./generated/lexicon-aws.json");
+        cachedKinds = new Set(Object.values(manifest).filter((e) => e.kind === "resource").map((e) => e.resourceType));
+    }
+    catch {
+        cachedKinds = null;
+    }
+    return cachedKinds;
+}
+/**
+ * The aws kind for a Cloud Control type, or undefined. With no kind set (no
+ * generated registry) every well-formed CloudFormation type maps, which is
+ * what the rest of the lexicon assumes before `chant generate` has run.
+ */
+export function awsKindForListedType(listedType, kinds = generatedKinds()) {
+    if (!CFN_TYPE.test(listedType))
+        return undefined;
+    if (kinds && !kinds.has(listedType))
+        return undefined;
+    return listedType;
+}
+/** The inverse, for tests and for a reader naming what to list: the same name. */
+export function awsListedTypeForKind(kind) {
+    return kind;
+}
+export const awsListedTypes = {
+    substrate: "aws",
+    kindFor: (listedType) => awsKindForListedType(listedType),
+};

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.124.51",
+  "version": "0.124.54",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [