@intentius/chant-lexicon-aws 0.124.32 → 0.124.34

package/src/lint/post-synth/waw070.ts

@@ -0,0 +1,89 @@
+/**
+ * WAW070: Ref or Fn::GetAtt names something the template doesn't declare
+ *
+ * A `Ref` must name a resource, a parameter or an `AWS::` pseudo-parameter,
+ * and a `Fn::GetAtt` must name a resource. CloudFormation rejects a template
+ * whose reference names neither (cfn-lint E1012/E1010). chant built such a
+ * template when a value read another lexicon's resource (#4180); the
+ * serializer now turns that into a parameter, and this check catches any
+ * reference still left dangling.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+interface DanglingRef {
+  target: string;
+  via: "Ref" | "Fn::GetAtt";
+}
+
+function collectRefs(value: unknown, out: DanglingRef[], seen = new Set<unknown>()): void {
+  if (value === null || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) collectRefs(item, out, seen);
+    return;
+  }
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.Ref === "string" && Object.keys(obj).length === 1) {
+    out.push({ target: obj.Ref, via: "Ref" });
+    return;
+  }
+  const getAtt = obj["Fn::GetAtt"];
+  if (getAtt !== undefined && Object.keys(obj).length === 1) {
+    const target = Array.isArray(getAtt) ? getAtt[0] : typeof getAtt === "string" ? getAtt.split(".")[0] : undefined;
+    if (typeof target === "string") out.push({ target, via: "Fn::GetAtt" });
+    if (Array.isArray(getAtt)) collectRefs(getAtt.slice(1), out, seen);
+    return;
+  }
+  for (const v of Object.values(obj)) collectRefs(v, out, seen);
+}
+
+export function checkDanglingRefs(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [lexicon, output] of ctx.outputs) {
+    if (lexicon !== "aws") continue;
+    const template = parseCFTemplate(output);
+    if (!template?.Resources || typeof template.Resources !== "object") continue;
+
+    const resources = new Set(Object.keys(template.Resources));
+    const parameters = new Set(Object.keys((template.Parameters as Record<string, unknown> | undefined) ?? {}));
+
+    const report = (where: string, value: unknown) => {
+      const refs: DanglingRef[] = [];
+      collectRefs(value, refs);
+      for (const ref of refs) {
+        const known = ref.via === "Ref"
+          ? resources.has(ref.target) || parameters.has(ref.target) || ref.target.startsWith("AWS::")
+          : resources.has(ref.target);
+        if (known) continue;
+        diagnostics.push({
+          checkId: "WAW070",
+          severity: "error",
+          message: `${where} has ${ref.via} "${ref.target}", which is not ${ref.via === "Ref" ? "a resource, a parameter or a pseudo-parameter" : "a resource"} in this template`,
+          entity: where.replace(/^(Resource|Output) /, "").replace(/"/g, ""),
+          lexicon: "aws",
+        });
+      }
+    };
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      report(`Resource "${logicalId}"`, resource.Properties);
+    }
+    for (const [name, out] of Object.entries((template.Outputs as Record<string, { Value?: unknown }> | undefined) ?? {})) {
+      report(`Output "${name}"`, out?.Value);
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw070: PostSynthCheck = {
+  id: "WAW070",
+  description: "Ref or Fn::GetAtt names something the template doesn't declare",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkDanglingRefs(ctx);
+  },
+};

package/src/plugin.ts

@@ -911,6 +911,14 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
   /** The noise rules the deep pass applies to both the live and declared trees. */
   deepNormalizationHooks: awsDeepNormalizationHooks,
 
+  /** Runtime health (#4177): Route 53 health checks and ECS services. Implementation in ./health.ts. */
+  healthTypes: ["AWS::Route53::HealthCheck", "AWS::ECS::Service"],
+
+  async observeHealth(options) {
+    const { observeHealthAws } = await import("./health");
+    return observeHealthAws(options);
+  },
+
   async describeStackStatus(options: { environment: string; stack: string }): Promise<StackStatusObservation | null> {
     const { getRuntime } = await import("@intentius/chant/runtime-adapter");
     const rt = getRuntime();

package/src/serializer-foreign-attr.test.ts

@@ -0,0 +1,43 @@
+/**
+ * A value read from a resource this template doesn't hold, such as another
+ * lexicon's, is a parameter, not a dangling Fn::GetAtt (#4180).
+ */
+
+import { describe, expect, it } from "vitest";
+import { AttrRef } from "@intentius/chant";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { awsSerializer } from "./serializer";
+
+function entity(lexicon: string, entityType: string, props: Record<string, unknown> = {}): any {
+  return { [DECLARABLE_MARKER]: true, lexicon, entityType, kind: "resource", props };
+}
+
+describe("aws foreign attributes", () => {
+  it("turns another lexicon's attribute into a parameter and warns", () => {
+    const app = entity("azure", "Microsoft.App/containerApps", { name: "web" });
+    const fqdn = new AttrRef(app, "configuration.ingress.fqdn");
+    fqdn._setLogicalName("app");
+    const record = entity("aws", "AWS::Route53::RecordSet", { Type: "CNAME", ResourceRecords: [fqdn] });
+
+    const result = awsSerializer.serialize(new Map([["record", record]]));
+    expect(typeof result).toBe("object");
+    const { primary, warnings } = result as { primary: string; warnings?: string[] };
+    const template = JSON.parse(primary);
+
+    expect(template.Resources.record.Properties.ResourceRecords).toEqual([{ Ref: "appConfigurationIngressFqdn" }]);
+    expect(template.Parameters.appConfigurationIngressFqdn.Type).toBe("String");
+    expect(warnings).toHaveLength(1);
+    expect(warnings![0]).toContain('"app" is not in this template');
+  });
+
+  it("keeps Fn::GetAtt for a resource in the template", () => {
+    const bucket = entity("aws", "AWS::S3::Bucket");
+    const arn = new AttrRef(bucket, "Arn");
+    arn._setLogicalName("bucket");
+    const topic = entity("aws", "AWS::SNS::Topic", { TopicName: arn });
+
+    const result = awsSerializer.serialize(new Map([["bucket", bucket], ["topic", topic]]));
+    expect(typeof result).toBe("string");
+    expect(JSON.parse(result as string).Resources.topic.Properties.TopicName).toEqual({ "Fn::GetAtt": ["bucket", "Arn"] });
+  });
+});

package/src/serializer.ts

@@ -15,7 +15,7 @@ import {
   RECEIPT_UNRESOLVED_VALUE_NOTE,
   receiptParameterName,
 } from "./effect-receipt-row";
-import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { sanitizeLogicalId, type LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { isChildProject, type ChildProjectInstance } from "@intentius/chant/child-project";
 import { isStackOutput, type StackOutput } from "@intentius/chant/stack-output";
@@ -104,12 +104,47 @@ interface CFOutput {
   Condition?: string;
 }
 
+/**
+ * An attribute of a resource this template doesn't hold (#4180): another
+ * lexicon's, such as an Azure Container App's hostname read by a Route 53
+ * record. `Fn::GetAtt` can't name it, so the template takes the value as a
+ * parameter, named as the source lexicon's output for it is
+ * (`LexiconOutput.auto`), and whoever deploys passes that output in.
+ */
+interface ForeignAttr {
+  entity: string;
+  attribute: string;
+}
+
+/** Per template (keyed by its entity map): the foreign attributes its values read, by parameter name. */
+const foreignAttrs = new WeakMap<Map<Declarable, string>, Map<string, ForeignAttr>>();
+const namesIn = new WeakMap<Map<Declarable, string>, Set<string>>();
+
+function holds(entityNames: Map<Declarable, string>, name: string): boolean {
+  let names = namesIn.get(entityNames);
+  if (!names) {
+    names = new Set(entityNames.values());
+    namesIn.set(entityNames, names);
+  }
+  return names.has(name);
+}
+
 /**
  * CloudFormation-specific visitor for the generic serializer walker.
  */
 function cfnVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
   return {
-    attrRef: (name, attr) => ({ "Fn::GetAtt": [name, attr] }),
+    attrRef: (name, attr) => {
+      if (holds(entityNames, name)) return { "Fn::GetAtt": [name, attr] };
+      const param = sanitizeLogicalId(name, attr);
+      let foreign = foreignAttrs.get(entityNames);
+      if (!foreign) {
+        foreign = new Map();
+        foreignAttrs.set(entityNames, foreign);
+      }
+      foreign.set(param, { entity: name, attribute: attr });
+      return { Ref: param };
+    },
     resourceRef: (name) => ({ Ref: name }),
     propertyDeclarable: (entity, walk) => {
       if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
@@ -267,6 +302,7 @@ function serializeToTemplate(
   extraOutputs?: Record<string, CFOutput>,
   ownership?: OwnershipMarker,
   receiptRows?: Record<string, ReceiptRow>,
+  warnings: string[] = [],
 ): CFTemplate {
   const template: CFTemplate = {
     AWSTemplateFormatVersion: "2010-09-09",
@@ -560,6 +596,19 @@ function serializeToTemplate(
     template.Outputs = { ...template.Outputs, ...extraOutputs };
   }
 
+  // Values read from resources this template doesn't hold become parameters.
+  for (const [param, ref] of foreignAttrs.get(entityNames) ?? []) {
+    if (template.Resources[param] || template.Parameters?.[param]) continue;
+    template.Parameters = template.Parameters ?? {};
+    template.Parameters[param] = {
+      Type: "String",
+      Description: `${ref.entity}.${ref.attribute}, from another lexicon's output "${param}"`,
+    };
+    warnings.push(
+      `aws: "${ref.entity}" is not in this template, so its ${ref.attribute} is the parameter "${param}". Deploy "${ref.entity}" first and pass its output "${param}" in.`,
+    );
+  }
+
   refuseImportEnvelopes(template);
   return template;
 }
@@ -616,8 +665,10 @@ export const awsSerializer: Serializer = {
 
     // No nested stacks — use the simple path
     if (!hasChildProjects) {
-      const template = serializeToTemplate(entities, outputs, undefined, undefined, ownership, receiptRows);
-      return JSON.stringify(template, null, 2);
+      const warnings: string[] = [];
+      const template = serializeToTemplate(entities, outputs, undefined, undefined, ownership, receiptRows, warnings);
+      const primary = JSON.stringify(template, null, 2);
+      return warnings.length > 0 ? { primary, warnings } : primary;
     }
 
     // Has child projects — produce multi-file output
@@ -656,12 +707,14 @@ export const awsSerializer: Serializer = {
     }
 
     // Serialize the parent template (ChildProjectInstance entities become CF::Stack resources)
-    const parentTemplate = serializeToTemplate(entities, outputs, parentParams, undefined, ownership, receiptRows);
+    const warnings: string[] = [];
+    const parentTemplate = serializeToTemplate(entities, outputs, parentParams, undefined, ownership, receiptRows, warnings);
     const primary = JSON.stringify(parentTemplate, null, 2);
 
     return {
       primary,
       files: allFiles,
+      ...(warnings.length > 0 ? { warnings } : {}),
     };
   },
 };