@intentius/chant-lexicon-aws 0.124.30 → 0.124.32

package/dist/serializer.js

@@ -0,0 +1,529 @@
+import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
+import { ownershipEntries } from "@intentius/chant/ownership";
+import { isEffectReceipt, receiptExpectation, referenceInputPaths, } from "@intentius/chant/effect-receipt";
+import { AWS_TAG_OWNERSHIP_KEYS, OWNERSHIP_METADATA_KEY } from "./ownership.js";
+import { AWS_EFFECT_RECEIPT_ENTITY_TYPE, EFFECT_RECEIPTS_METADATA_KEY, RECEIPT_UNRESOLVED_VALUE_NOTE, receiptParameterName, } from "./effect-receipt-row.js";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { isChildProject } from "@intentius/chant/child-project";
+import { isStackOutput } from "@intentius/chant/stack-output";
+import { isAttrRefLike } from "@intentius/chant/utils";
+import { resolveDependsOn } from "@intentius/chant/resource-attributes";
+import { conditionName, isCondition } from "./condition.js";
+import { isMapping } from "./mapping.js";
+import { isDefaultTags } from "./default-tags.js";
+import { isTemplateTransform } from "./template-transform.js";
+import { isTemplateSection } from "./template-sections.js";
+import { loadTaggableResources } from "./taggable.js";
+/**
+ * Check if a declarable is a CoreParameter
+ */
+function isCoreParameter(entity) {
+    return "parameterType" in entity;
+}
+/** Parameter constraint options and the CloudFormation keys they emit as. */
+const PARAMETER_CONSTRAINT_KEYS = [
+    ["allowedValues", "AllowedValues"],
+    ["allowedPattern", "AllowedPattern"],
+    ["constraintDescription", "ConstraintDescription"],
+    ["minLength", "MinLength"],
+    ["maxLength", "MaxLength"],
+    ["minValue", "MinValue"],
+    ["maxValue", "MaxValue"],
+    ["noEcho", "NoEcho"],
+];
+/**
+ * CloudFormation-specific visitor for the generic serializer walker.
+ */
+function cfnVisitor(entityNames) {
+    return {
+        attrRef: (name, attr) => ({ "Fn::GetAtt": [name, attr] }),
+        resourceRef: (name) => ({ Ref: name }),
+        propertyDeclarable: (entity, walk) => {
+            if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
+                return undefined;
+            }
+            const props = entity.props;
+            const cfProps = {};
+            for (const [key, value] of Object.entries(props)) {
+                if (value !== undefined) {
+                    cfProps[key] = walk(value);
+                }
+            }
+            return Object.keys(cfProps).length > 0 ? cfProps : undefined;
+        },
+    };
+}
+/**
+ * Convert a value to CF-compatible JSON using the generic walker.
+ */
+function toCFValue(value, entityNames) {
+    return walkValue(value, entityNames, cfnVisitor(entityNames));
+}
+/**
+ * Set logical names on any AttrRefs nested inside a value (e.g. inside a `Join`
+ * that a `stackOutput` exports). resolveAttrRefs only reaches entity attributes,
+ * not refs buried in an output's intrinsic — without this the walker would throw
+ * "logical name not set" for them (#517).
+ */
+function resolveNestedAttrRefs(value, entityNames, seen = new Set()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return;
+    seen.add(value);
+    if (isAttrRefLike(value)) {
+        if (!value.getLogicalName()) {
+            const parent = value.parent.deref();
+            const parentName = parent ? entityNames.get(parent) : undefined;
+            if (parentName)
+                value._setLogicalName(parentName);
+        }
+        return;
+    }
+    const children = Array.isArray(value) ? value : Object.values(value);
+    for (const child of children)
+        resolveNestedAttrRefs(child, entityNames, seen);
+}
+/**
+ * Convert entity props to CF properties
+ */
+function toProperties(entity, entityNames) {
+    if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
+        return undefined;
+    }
+    const props = entity.props;
+    const cfProps = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) {
+            cfProps[key] = toCFValue(value, entityNames);
+        }
+    }
+    return Object.keys(cfProps).length > 0 ? cfProps : undefined;
+}
+/** The rendered `Value`: the synthesis-time expectation when the receipt is
+ * fully static, a placeholder note when reference inputs resolve later —
+ * never a digest hashed over placeholders (epic #1703, decision 5). */
+function receiptRowValue(receipt) {
+    if (receipt.flavor === "hash" && referenceInputPaths(receipt).length > 0) {
+        return RECEIPT_UNRESOLVED_VALUE_NOTE;
+    }
+    return receiptExpectation(receipt);
+}
+/**
+ * Render the effect receipts (#1835) the build withheld from the apply-bound
+ * entity set (`SerializeContext.receipts`, #1832) as `AWS::SSM::Parameter`
+ * rows: plain `String`, named `/chant-receipts/<stack>/<env>/<effect>` from
+ * the resolved ownership marker (epic decision 4 — the same fields that stamp
+ * tags), carrying the ownership tags. Visibility only: the rows go under the
+ * template's `Metadata`, and the receipt store (./receipt-store.ts) is what
+ * actually writes the parameter — through the `effect()` step, on success,
+ * last.
+ *
+ * The env segment is explicit: a receipt with no resolved `ownership.env` is
+ * an error here, never a guessed path.
+ */
+function renderReceiptRows(receipts, ownership) {
+    const rows = {};
+    const names = [...receipts.keys()].join(", ");
+    if (!ownership) {
+        throw new Error(`aws receipts (${names}): no ownership marker resolved — the receipt path is ` +
+            `/chant-receipts/<stack>/<env>/<effect>, derived from the same ownership fields that ` +
+            `stamp markers (chant #1703, decision 4). Set ownership: { stack, env } in chant.config.ts.`);
+    }
+    if (!ownership.env) {
+        throw new Error(`aws receipts (${names}): ownership resolved no env — the receipt path's <env> segment is ` +
+            `explicit (chant #1703, decision 4). Set ownership.env in chant.config.ts (a literal, or ` +
+            `{ param: "env" } with --param env=<name>).`);
+    }
+    const tags = Object.entries(ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership)).map(([Key, Value]) => ({ Key, Value }));
+    for (const [name, entity] of receipts) {
+        if (!isEffectReceipt(entity))
+            continue;
+        rows[name] = {
+            Type: AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+            Properties: {
+                Name: receiptParameterName(ownership.stack, ownership.env, entity.effect),
+                Type: "String",
+                Value: receiptRowValue(entity),
+                Tags: tags,
+            },
+        };
+    }
+    return rows;
+}
+/**
+ * Serialize a set of entities into a CFTemplate object (without JSON.stringify).
+ */
+function serializeToTemplate(entities, outputs, extraParameters, extraOutputs, ownership, receiptRows) {
+    const template = {
+        AWSTemplateFormatVersion: "2010-09-09",
+        Resources: {},
+    };
+    // Add extra parameters (e.g. TemplateBasePath)
+    if (extraParameters && Object.keys(extraParameters).length > 0) {
+        template.Parameters = { ...extraParameters };
+    }
+    // Build reverse map: entity -> name
+    const entityNames = new Map();
+    for (const [name, entity] of entities) {
+        entityNames.set(entity, name);
+    }
+    // Collect default tags. The ownership marker is stamped as tags, seeded
+    // first so user default tags (and explicit per-resource tags) take precedence
+    // on key collisions.
+    const defaultTagEntries = [];
+    if (ownership) {
+        for (const [Key, Value] of Object.entries(ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership))) {
+            defaultTagEntries.push({ Key, Value });
+        }
+        // Also carry the marker at the template level (#1222): stack tags are a
+        // CreateStack/UpdateStack API parameter, not a template section, so the
+        // apply paths read this Metadata block and stamp it as the stack's own
+        // tags — what stack-level teardown verifies ownership on.
+        template.Metadata = {
+            [OWNERSHIP_METADATA_KEY]: ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership),
+        };
+    }
+    // Effect receipt rows (#1835) — visibility only, deliberately outside
+    // `Resources`: the applier's desired and prune sets both read `Resources`,
+    // and the `effect()` step is a receipt's sole writer (#1832, epic #1703
+    // decision 3). The observation leg (plugin.ts) reads the paths back from
+    // this block, so the identity is derived exactly once, here.
+    if (receiptRows && Object.keys(receiptRows).length > 0) {
+        template.Metadata = { ...(template.Metadata ?? {}), [EFFECT_RECEIPTS_METADATA_KEY]: receiptRows };
+    }
+    for (const [, entity] of entities) {
+        if (isDefaultTags(entity)) {
+            defaultTagEntries.push(...entity.tags);
+        }
+    }
+    // Collect top-level Transform macros (e.g. AWS::SecretsManager-2020-07-23),
+    // de-duplicated in declaration order. One → a string, several → a list,
+    // matching CloudFormation's own `Transform` shape.
+    const transforms = [];
+    for (const [, entity] of entities) {
+        if (isTemplateTransform(entity) && !transforms.includes(entity.transform)) {
+            transforms.push(entity.transform);
+        }
+    }
+    if (transforms.length === 1) {
+        template.Transform = transforms[0];
+    }
+    else if (transforms.length > 1) {
+        template.Transform = transforms;
+    }
+    // Template-level Description and Metadata declarations. Declared Metadata
+    // keys come first; the ownership marker and receipt rows written above are
+    // chant's own and win on a key collision.
+    const declaredMetadata = {};
+    for (const [, entity] of entities) {
+        if (!isTemplateSection(entity))
+            continue;
+        if (entity.section === "Description") {
+            template.Description = entity.value;
+        }
+        else {
+            Object.assign(declaredMetadata, toCFValue(entity.value, entityNames));
+        }
+    }
+    if (Object.keys(declaredMetadata).length > 0) {
+        template.Metadata = { ...declaredMetadata, ...(template.Metadata ?? {}) };
+    }
+    // Process entities
+    for (const [name, entity] of entities) {
+        // Skip StackOutput entities — they go in the Outputs section
+        if (isStackOutput(entity)) {
+            continue;
+        }
+        // Skip DefaultTags entities — handled via tag injection below
+        if (isDefaultTags(entity)) {
+            continue;
+        }
+        // Skip TemplateTransform entities — lifted to the top-level Transform above
+        if (isTemplateTransform(entity) || isTemplateSection(entity)) {
+            continue;
+        }
+        if (isCoreParameter(entity)) {
+            if (!template.Parameters) {
+                template.Parameters = {};
+            }
+            const param = {
+                Type: entity.parameterType,
+            };
+            if ("description" in entity && typeof entity.description === "string") {
+                param.Description = entity.description;
+            }
+            if ("defaultValue" in entity && entity.defaultValue !== undefined) {
+                param.Default = entity.defaultValue;
+            }
+            const constraints = entity.constraints;
+            if (constraints) {
+                for (const [option, key] of PARAMETER_CONSTRAINT_KEYS) {
+                    if (constraints[option] !== undefined)
+                        param[key] = constraints[option];
+                }
+            }
+            template.Parameters[name] = param;
+        }
+        else if (isMapping(entity)) {
+            // Mapping declarable -> Mappings section, read with FindInMap.
+            if (!template.Mappings) {
+                template.Mappings = {};
+            }
+            template.Mappings[entity.name ?? name] = toCFValue(entity.map, entityNames);
+        }
+        else if (isCondition(entity)) {
+            // Condition declarable → Conditions section (#2068), lifted the way
+            // Parameter is lifted into Parameters above.
+            if (!template.Conditions) {
+                template.Conditions = {};
+            }
+            template.Conditions[entity.name ?? name] = toCFValue(entity.expression, entityNames);
+        }
+        else if (isChildProject(entity)) {
+            // ChildProjectInstance → AWS::CloudFormation::Stack resource
+            const childProject = entity;
+            const childName = childProject.logicalName;
+            const filename = `${childName}.template.json`;
+            const properties = {
+                TemplateURL: {
+                    "Fn::Sub": `\${TemplateBasePath}/${filename}`,
+                },
+            };
+            // Build parameters: always pass TemplateBasePath down
+            const parameters = {
+                TemplateBasePath: { Ref: "TemplateBasePath" },
+            };
+            // Add user-specified parameters
+            const opts = childProject.options;
+            if (opts.parameters) {
+                for (const [key, value] of Object.entries(opts.parameters)) {
+                    parameters[key] = value;
+                }
+            }
+            properties.Parameters = parameters;
+            template.Resources[name] = {
+                Type: "AWS::CloudFormation::Stack",
+                Properties: properties,
+            };
+        }
+        else if (!isPropertyDeclarable(entity)) {
+            const resource = {
+                Type: entity.entityType,
+            };
+            // Read resource-level attributes from the second constructor arg
+            const attrs = (isResourceDeclarable(entity) && typeof entity.attributes === "object" && entity.attributes !== null)
+                ? entity.attributes
+                : undefined;
+            if (attrs) {
+                // DependsOn — resolve Declarable refs to logical names
+                if (attrs.DependsOn !== undefined) {
+                    const resolved = resolveDependsOn(attrs.DependsOn, entityNames, name);
+                    if (resolved.length > 0) {
+                        resource.DependsOn = resolved.length === 1 ? resolved[0] : resolved;
+                    }
+                }
+                // Pass-through attributes. Condition accepts the Condition declarable
+                // as well as a name string (#2068).
+                if (attrs.Condition) {
+                    resource.Condition = isCondition(attrs.Condition)
+                        ? conditionName(attrs.Condition, entityNames)
+                        : attrs.Condition;
+                }
+                if (attrs.DeletionPolicy)
+                    resource.DeletionPolicy = attrs.DeletionPolicy;
+                if (attrs.UpdateReplacePolicy)
+                    resource.UpdateReplacePolicy = attrs.UpdateReplacePolicy;
+                if (attrs.UpdatePolicy)
+                    resource.UpdatePolicy = attrs.UpdatePolicy;
+                if (attrs.CreationPolicy)
+                    resource.CreationPolicy = attrs.CreationPolicy;
+                if (attrs.Metadata)
+                    resource.Metadata = toCFValue(attrs.Metadata, entityNames);
+            }
+            const properties = toProperties(entity, entityNames);
+            if (properties) {
+                if (Object.keys(properties).length > 0) {
+                    resource.Properties = properties;
+                }
+            }
+            template.Resources[name] = resource;
+        }
+    }
+    // Inject default tags into taggable resources
+    if (defaultTagEntries.length > 0) {
+        const taggable = loadTaggableResources();
+        for (const [, resource] of Object.entries(template.Resources)) {
+            if (!taggable.has(resource.Type))
+                continue;
+            const resolved = defaultTagEntries.map(t => ({
+                Key: t.Key,
+                Value: toCFValue(t.Value, entityNames),
+            }));
+            const explicit = (resource.Properties?.Tags ?? []);
+            const explicitKeys = new Set(explicit.map(t => t.Key));
+            const merged = [...resolved.filter(t => !explicitKeys.has(t.Key)), ...explicit];
+            if (!resource.Properties)
+                resource.Properties = {};
+            resource.Properties.Tags = merged;
+        }
+    }
+    // Emit StackOutput entities as CF Outputs
+    for (const [name, entity] of entities) {
+        if (isStackOutput(entity)) {
+            if (!template.Outputs) {
+                template.Outputs = {};
+            }
+            const stackOutput = entity;
+            // Typed `unknown` so `isAttrRefLike` narrows cleanly regardless of how the
+            // AttrRef type resolves across the workspace/published boundary.
+            const ref = stackOutput.sourceRef;
+            let value;
+            if (typeof ref === "string") {
+                // Literal output (constants a stack publishes, e.g. a port number).
+                value = ref;
+            }
+            else if (isAttrRefLike(ref)) {
+                const logicalName = ref.getLogicalName();
+                if (!logicalName)
+                    continue;
+                // Use Ref for primary identifier ("Id") since not all resources
+                // support Fn::GetAtt for their primary identifier (e.g. ACM Certificate).
+                // Ref always returns the primary identifier for any CF resource.
+                value = ref.attribute === "Id" ? { Ref: logicalName } : { "Fn::GetAtt": [logicalName, ref.attribute] };
+            }
+            else {
+                // An intrinsic wrapping refs (e.g. Join(",", zone.NameServers), #517):
+                // resolve the nested AttrRefs' logical names from the entity map, then
+                // serialize through the CF walker → {Fn::Join:[",",{Fn::GetAtt:[…]}]}.
+                resolveNestedAttrRefs(ref, entityNames);
+                value = toCFValue(ref, entityNames);
+            }
+            const output = { Value: value };
+            if (stackOutput.description) {
+                output.Description = stackOutput.description;
+            }
+            // Read defensively: a project may pair this lexicon with an older
+            // published core whose StackOutput type predates exportName.
+            const exportName = stackOutput.exportName;
+            if (exportName) {
+                output.Export = { Name: exportName };
+            }
+            // Same defensive read: condition (#2068/#2069) postdates older cores.
+            const condition = stackOutput.condition;
+            if (condition) {
+                output.Condition = isCondition(condition)
+                    ? conditionName(condition, entityNames)
+                    : condition;
+            }
+            // Read defensively, like exportName: the name option postdates older cores.
+            template.Outputs[stackOutput.name ?? name] = output;
+        }
+    }
+    // Add CF Outputs for LexiconOutputs produced by this lexicon. Run the value
+    // through the CF walker so an AttrRef nested in an intrinsic (e.g.
+    // Join(",", [subnet1.SubnetId, …])) becomes Fn::GetAtt instead of leaking the
+    // generic `{__attrRef}` envelope — the same conversion resource Properties get
+    // (#935). A bare Fn::GetAtt value walks through unchanged.
+    if (outputs && outputs.length > 0) {
+        template.Outputs = template.Outputs ?? {};
+        for (const output of outputs) {
+            template.Outputs[output.outputName] = {
+                Value: toCFValue(output.getOutputValue(), entityNames),
+            };
+        }
+    }
+    // Add extra outputs (e.g. auto-wired cross-stack refs)
+    if (extraOutputs && Object.keys(extraOutputs).length > 0) {
+        template.Outputs = { ...template.Outputs, ...extraOutputs };
+    }
+    refuseImportEnvelopes(template);
+    return template;
+}
+/**
+ * Throw on an import IR envelope (`{ "__intrinsic": "FindInMap", ... }`) in
+ * the synthesized template. It is not CloudFormation, and a build that wrote
+ * one used to exit 0 with a template CloudFormation rejects.
+ */
+function refuseImportEnvelopes(value, path = []) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => refuseImportEnvelopes(item, [...path, String(i)]));
+        return;
+    }
+    const obj = value;
+    if (typeof obj.__intrinsic === "string") {
+        throw new Error(`${path.join(".")}: { __intrinsic: "${obj.__intrinsic}" } is an import envelope, not CloudFormation; ` +
+            `write the ${obj.__intrinsic} intrinsic instead`);
+    }
+    for (const [key, v] of Object.entries(obj))
+        refuseImportEnvelopes(v, [...path, key]);
+}
+/**
+ * AWS CloudFormation serializer implementation
+ */
+export const awsSerializer = {
+    name: "aws",
+    rulePrefix: "WAW",
+    serialize(entities, outputs, context) {
+        const ownership = context?.ownership;
+        // Effect receipts (#1835): withheld from `entities` by the build (#1832),
+        // rendered here as Metadata rows — never as `Resources` an applier would
+        // write. Env-less ownership is an error, not a guessed path segment.
+        const receiptRows = context?.receipts && context.receipts.size > 0
+            ? renderReceiptRows(context.receipts, ownership)
+            : undefined;
+        // Check if any entities are child projects (nested stacks)
+        const childProjects = new Map();
+        let hasChildProjects = false;
+        for (const [name, entity] of entities) {
+            if (isChildProject(entity)) {
+                childProjects.set(name, entity);
+                hasChildProjects = true;
+            }
+        }
+        // No nested stacks — use the simple path
+        if (!hasChildProjects) {
+            const template = serializeToTemplate(entities, outputs, undefined, undefined, ownership, receiptRows);
+            return JSON.stringify(template, null, 2);
+        }
+        // Has child projects — produce multi-file output
+        const allFiles = {};
+        // Add TemplateBasePath parameter to the parent template
+        const parentParams = {
+            TemplateBasePath: {
+                Type: "String",
+                Default: ".",
+                Description: "Base URL/path for nested stack templates",
+            },
+        };
+        // Collect child template files from build results
+        for (const [, childProject] of childProjects) {
+            if (childProject.buildResult) {
+                const childOutput = childProject.buildResult.outputs.get("aws");
+                if (childOutput) {
+                    const childName = childProject.logicalName;
+                    const filename = `${childName}.template.json`;
+                    if (typeof childOutput === "string") {
+                        allFiles[filename] = childOutput;
+                    }
+                    else {
+                        // SerializerResult — the child itself has child templates
+                        allFiles[filename] = childOutput.primary;
+                        if (childOutput.files) {
+                            for (const [childFile, content] of Object.entries(childOutput.files)) {
+                                allFiles[childFile] = content;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Serialize the parent template (ChildProjectInstance entities become CF::Stack resources)
+        const parentTemplate = serializeToTemplate(entities, outputs, parentParams, undefined, ownership, receiptRows);
+        const primary = JSON.stringify(parentTemplate, null, 2);
+        return {
+            primary,
+            files: allFiles,
+        };
+    },
+};