@intentius/chant-lexicon-aws 0.0.6 → 0.0.9

package/src/serializer.ts

@@ -3,9 +3,11 @@ import { isPropertyDeclarable } from "@intentius/chant/declarable";
 import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
-import { toPascalCase } from "@intentius/chant/codegen/case";
 import { isChildProject, type ChildProjectInstance } from "@intentius/chant/child-project";
 import { isStackOutput, type StackOutput } from "@intentius/chant/stack-output";
+import { resolveDependsOn } from "@intentius/chant/resource-attributes";
+import { isDefaultTags, type TagEntry } from "./default-tags";
+import { loadTaggableResources } from "./taggable";
 
 /**
  * Check if a declarable is a CoreParameter
@@ -50,6 +52,10 @@ interface CFResource {
   Properties?: Record<string, unknown>;
   DependsOn?: string | string[];
   Condition?: string;
+  DeletionPolicy?: string;
+  UpdateReplacePolicy?: string;
+  UpdatePolicy?: unknown;
+  CreationPolicy?: unknown;
   Metadata?: Record<string, unknown>;
 }
 
@@ -68,7 +74,7 @@ interface CFOutput {
  */
 function cfnVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
   return {
-    attrRef: (name, attr) => ({ "Fn::GetAttr": [name, attr] }),
+    attrRef: (name, attr) => ({ "Fn::GetAtt": [name, attr] }),
     resourceRef: (name) => ({ Ref: name }),
     propertyDeclarable: (entity, walk) => {
       if (!("props" in entity) || typeof entity.props !== "object" || entity.props === null) {
@@ -78,26 +84,19 @@ function cfnVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
       const cfProps: Record<string, unknown> = {};
       for (const [key, value] of Object.entries(props)) {
         if (value !== undefined) {
-          const cfKey = toPascalCase(key);
-          cfProps[cfKey] = walk(value);
+          cfProps[key] = walk(value);
         }
       }
       return Object.keys(cfProps).length > 0 ? cfProps : undefined;
     },
-    transformKey: toPascalCase,
   };
 }
 
 /**
  * Convert a value to CF-compatible JSON using the generic walker.
  */
-function toCFValue(value: unknown, entityNames: Map<Declarable, string>, convertKeys = false): unknown {
-  const visitor = cfnVisitor(entityNames);
-  if (!convertKeys) {
-    // When not converting keys, use a visitor without transformKey
-    return walkValue(value, entityNames, { ...visitor, transformKey: undefined });
-  }
-  return walkValue(value, entityNames, visitor);
+function toCFValue(value: unknown, entityNames: Map<Declarable, string>): unknown {
+  return walkValue(value, entityNames, cfnVisitor(entityNames));
 }
 
 /**
@@ -116,8 +115,7 @@ function toProperties(
 
   for (const [key, value] of Object.entries(props)) {
     if (value !== undefined) {
-      const cfKey = toPascalCase(key);
-      cfProps[cfKey] = toCFValue(value, entityNames, true);
+      cfProps[key] = toCFValue(value, entityNames);
     }
   }
 
@@ -150,6 +148,14 @@ function serializeToTemplate(
     entityNames.set(entity, name);
   }
 
+  // Collect default tags
+  const defaultTagEntries: TagEntry[] = [];
+  for (const [, entity] of entities) {
+    if (isDefaultTags(entity)) {
+      defaultTagEntries.push(...entity.tags);
+    }
+  }
+
   // Process entities
   for (const [name, entity] of entities) {
     // Skip StackOutput entities — they go in the Outputs section
@@ -157,6 +163,11 @@ function serializeToTemplate(
       continue;
     }
 
+    // Skip DefaultTags entities — handled via tag injection below
+    if (isDefaultTags(entity)) {
+      continue;
+    }
+
     if (isCoreParameter(entity)) {
       if (!template.Parameters) {
         template.Parameters = {};
@@ -211,15 +222,56 @@ function serializeToTemplate(
         Type: entity.entityType,
       };
 
+      // Read resource-level attributes from the second constructor arg
+      const attrs = ("attributes" in entity && typeof entity.attributes === "object" && entity.attributes !== null)
+        ? entity.attributes as Record<string, unknown>
+        : 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
+        if (attrs.Condition) resource.Condition = attrs.Condition as string;
+        if (attrs.DeletionPolicy) resource.DeletionPolicy = attrs.DeletionPolicy as string;
+        if (attrs.UpdateReplacePolicy) resource.UpdateReplacePolicy = attrs.UpdateReplacePolicy as string;
+        if (attrs.UpdatePolicy) resource.UpdatePolicy = attrs.UpdatePolicy;
+        if (attrs.CreationPolicy) resource.CreationPolicy = attrs.CreationPolicy;
+        if (attrs.Metadata) resource.Metadata = toCFValue(attrs.Metadata, entityNames) as Record<string, unknown>;
+      }
+
       const properties = toProperties(entity, entityNames);
       if (properties) {
-        resource.Properties = 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 ?? []) as Array<{ Key: string }>;
+      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)) {
@@ -231,7 +283,7 @@ function serializeToTemplate(
       const logicalName = ref.getLogicalName();
       if (logicalName) {
         const output: CFOutput = {
-          Value: { "Fn::GetAttr": [logicalName, ref.attribute] },
+          Value: { "Fn::GetAtt": [logicalName, ref.attribute] },
         };
         if (stackOutput.description) {
           output.Description = stackOutput.description;
@@ -247,7 +299,7 @@ function serializeToTemplate(
     for (const output of outputs) {
       template.Outputs[output.outputName] = {
         Value: {
-          "Fn::GetAttr": [output.sourceEntity, output.sourceAttribute],
+          "Fn::GetAtt": [output.sourceEntity, output.sourceAttribute],
         },
       };
     }

package/src/spec/fetch.ts

@@ -15,6 +15,16 @@ export interface CFNSchema {
   createOnlyProperties?: string[];
   writeOnlyProperties?: string[];
   primaryIdentifier?: string[];
+  deprecatedProperties?: string[];
+  conditionalCreateOnlyProperties?: string[];
+  replacementStrategy?: string;
+  tagging?: {
+    taggable?: boolean;
+    tagOnCreate?: boolean;
+    tagUpdatable?: boolean;
+    cloudFormationSystemTags?: boolean;
+    tagProperty?: string;
+  };
   additionalProperties?: boolean;
 }
 

package/src/spec/parse.test.ts

@@ -20,6 +20,7 @@ const sampleBucketSchema = JSON.stringify({
     },
     AccessControl: {
       type: "string",
+      description: "This is a legacy property, and it is not recommended for most use cases.",
       enum: ["Private", "PublicRead", "PublicReadWrite"],
     },
   },
@@ -42,6 +43,7 @@ const sampleBucketSchema = JSON.stringify({
       additionalProperties: false,
     },
   },
+  deprecatedProperties: ["/properties/AccessControl"],
   readOnlyProperties: [
     "/properties/Arn",
     "/properties/DomainName",
@@ -134,6 +136,145 @@ describe("parseCFNSchema", () => {
     expect(result.resource.properties).toEqual([]);
     expect(result.resource.attributes).toEqual([]);
   });
+
+  // --- Deprecated properties ---
+
+  test("parses explicit deprecatedProperties", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+    expect(result.resource.deprecatedProperties).toContain("AccessControl");
+  });
+
+  test("mines deprecation from property description", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::DescMined",
+      properties: {
+        OldProp: { type: "string", description: "This property is deprecated. Use NewProp instead." },
+        NewProp: { type: "string", description: "The replacement property" },
+      },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.deprecatedProperties).toContain("OldProp");
+    expect(result.resource.deprecatedProperties).not.toContain("NewProp");
+  });
+
+  test("mines 'legacy' keyword from description", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Legacy",
+      properties: {
+        LegacyProp: { type: "string", description: "This is a legacy property, not recommended." },
+      },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.deprecatedProperties).toContain("LegacyProp");
+  });
+
+  test("deduplicates when both explicit and description flag same property", () => {
+    // sampleBucketSchema has AccessControl in both deprecatedProperties array and description
+    const result = parseCFNSchema(sampleBucketSchema);
+    const count = result.resource.deprecatedProperties.filter((p) => p === "AccessControl").length;
+    expect(count).toBe(1);
+  });
+
+  test("empty deprecatedProperties when none found", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Clean",
+      properties: {
+        Name: { type: "string", description: "A normal property" },
+      },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.deprecatedProperties).toEqual([]);
+  });
+
+  // --- Tagging metadata ---
+
+  test("parses tagging metadata when taggable", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Taggable",
+      properties: { Tags: { type: "array" } },
+      tagging: { taggable: true, tagOnCreate: true, tagUpdatable: true },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.tagging).toEqual({
+      taggable: true,
+      tagOnCreate: true,
+      tagUpdatable: true,
+    });
+  });
+
+  test("omits tagging when not taggable", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::NotTaggable",
+      properties: { Name: { type: "string" } },
+      tagging: { taggable: false },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.tagging).toBeUndefined();
+  });
+
+  test("omits tagging when absent", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::NoTagging",
+      properties: { Name: { type: "string" } },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.tagging).toBeUndefined();
+  });
+
+  // --- Replacement strategy ---
+
+  test("parses replacementStrategy", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::DeleteFirst",
+      properties: { Name: { type: "string" } },
+      replacementStrategy: "delete_then_create",
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.replacementStrategy).toBe("delete_then_create");
+  });
+
+  test("omits replacementStrategy when absent", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::NoStrategy",
+      properties: { Name: { type: "string" } },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.replacementStrategy).toBeUndefined();
+  });
+
+  // --- Conditional create-only ---
+
+  test("parses conditionalCreateOnlyProperties", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::ConditionalCreate",
+      properties: {
+        Name: { type: "string" },
+        Engine: { type: "string" },
+      },
+      conditionalCreateOnlyProperties: ["/properties/Engine"],
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.conditionalCreateOnly).toContain("Engine");
+  });
+
+  test("empty conditionalCreateOnly when absent", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::NoConditional",
+      properties: { Name: { type: "string" } },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.conditionalCreateOnly).toEqual([]);
+  });
 });
 
 describe("cfnShortName", () => {

package/src/spec/parse.ts

@@ -52,6 +52,10 @@ export interface ParsedResource {
   createOnly: string[];
   writeOnly: string[];
   primaryIdentifier: string[];
+  deprecatedProperties: string[];
+  conditionalCreateOnly: string[];
+  replacementStrategy?: "delete_then_create" | "create_then_delete";
+  tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
 }
 
 export interface SchemaParseResult {
@@ -137,6 +141,38 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
     }
   }
 
+  // --- Deprecated properties: explicit + description-mined ---
+  const deprecatedSet = new Set<string>(
+    stripPointerPaths(schema.deprecatedProperties ?? []),
+  );
+
+  const DEPRECATION_RE = /\bdeprecated\b|\blegacy\b|no longer (available|recommended|used|supported)|is not recommended|has been discontinued/i;
+
+  // Mine top-level property descriptions
+  if (schema.properties) {
+    for (const [name, prop] of Object.entries(schema.properties)) {
+      if (prop.description && DEPRECATION_RE.test(prop.description)) {
+        deprecatedSet.add(name);
+      }
+    }
+  }
+
+  // --- Tagging ---
+  let tagging: ParsedResource["tagging"];
+  if (schema.tagging && schema.tagging.taggable) {
+    tagging = {
+      taggable: true,
+      tagOnCreate: schema.tagging.tagOnCreate ?? false,
+      tagUpdatable: schema.tagging.tagUpdatable ?? false,
+    };
+  }
+
+  // --- Replacement strategy ---
+  let replacementStrategy: ParsedResource["replacementStrategy"];
+  if (schema.replacementStrategy === "delete_then_create" || schema.replacementStrategy === "create_then_delete") {
+    replacementStrategy = schema.replacementStrategy;
+  }
+
   return {
     resource: {
       typeName: schema.typeName,
@@ -145,6 +181,10 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
       createOnly: stripPointerPaths(schema.createOnlyProperties ?? []),
       writeOnly: stripPointerPaths(schema.writeOnlyProperties ?? []),
       primaryIdentifier: stripPointerPaths(schema.primaryIdentifier ?? []),
+      deprecatedProperties: [...deprecatedSet],
+      conditionalCreateOnly: stripPointerPaths(schema.conditionalCreateOnlyProperties ?? []),
+      ...(replacementStrategy && { replacementStrategy }),
+      ...(tagging && { tagging }),
     },
     propertyTypes,
     enums,

package/src/taggable.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared taggable resource lookup — loads from the generated lexicon JSON.
+ *
+ * Lazy-loaded and cached for the lifetime of the process.
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+
+interface LexiconEntry {
+  kind: string;
+  resourceType: string;
+  tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
+  [key: string]: unknown;
+}
+
+let _cached: Set<string> | undefined;
+
+/**
+ * Load taggable resource types from the lexicon JSON.
+ * Result is cached after first call.
+ */
+export function loadTaggableResources(): Set<string> {
+  if (_cached) return _cached;
+
+  const set = new Set<string>();
+  try {
+    const pkgDir = join(__dirname, "..");
+    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-aws.json");
+    const content = readFileSync(lexiconPath, "utf-8");
+    const data = JSON.parse(content) as Record<string, LexiconEntry>;
+
+    for (const [_name, entry] of Object.entries(data)) {
+      if (entry.kind === "resource" && entry.resourceType && entry.tagging?.taggable) {
+        set.add(entry.resourceType);
+      }
+    }
+  } catch {
+    // Lexicon not available — skip
+  }
+
+  _cached = set;
+  return set;
+}

package/src/testdata/nested-stacks/app.ts

@@ -0,0 +1,26 @@
+/**
+ * App layer — Lambda function in the parent template that references
+ * the network nested stack's outputs via cross-stack references
+ */
+
+import { Function, Sub, AWS, Ref, nestedStack } from "@intentius/chant-lexicon-aws";
+
+// nestedStack() references a child project directory
+const network = nestedStack("network", import.meta.dirname + "/network", {
+  parameters: { Environment: "prod" },
+});
+
+export const handler = new Function({
+  FunctionName: Sub`${AWS.StackName}-handler`,
+  Runtime: "nodejs20.x",
+  Handler: "index.handler",
+  Role: Ref("LambdaExecutionRole"),
+  Code: { ZipFile: "exports.handler = async () => ({ statusCode: 200 });" },
+  VpcConfig: {
+    SubnetIds: [network.outputs.subnetId],
+    SecurityGroupIds: [network.outputs.lambdaSgId],
+  },
+});
+
+// Re-export so discovery picks it up as an entity
+export { network };

package/src/testdata/nested-stacks/network/outputs.ts

@@ -0,0 +1,17 @@
+/**
+ * Cross-stack outputs — values the parent can reference
+ */
+
+import { stackOutput } from "@intentius/chant";
+import { vpc, subnet } from "./vpc";
+import { lambdaSg } from "./security";
+
+export const vpcId = stackOutput(vpc.VpcId, {
+  description: "VPC ID",
+});
+export const subnetId = stackOutput(subnet.SubnetId, {
+  description: "Public subnet ID",
+});
+export const lambdaSgId = stackOutput(lambdaSg.GroupId, {
+  description: "Lambda security group ID",
+});

package/src/testdata/nested-stacks/network/security.ts

@@ -0,0 +1,17 @@
+/**
+ * Security group for the Lambda function in the parent stack
+ */
+
+import { SecurityGroup, Sub, AWS } from "@intentius/chant-lexicon-aws";
+import { vpc } from "./vpc";
+
+export const lambdaSg = new SecurityGroup({
+  GroupDescription: Sub`${AWS.StackName} Lambda security group`,
+  VpcId: vpc.VpcId,
+  SecurityGroupEgress: [{
+    IpProtocol: "-1",
+    CidrIp: "0.0.0.0/0",
+    Description: "Allow all outbound",
+  }],
+  Tags: [{ Key: "Name", Value: Sub`${AWS.StackName}-lambda-sg` }],
+});

package/src/testdata/nested-stacks/network/vpc.ts

@@ -0,0 +1,54 @@
+/**
+ * Network resources — VPC, subnet, internet gateway, and routing
+ */
+
+import {
+  Vpc,
+  Subnet,
+  InternetGateway,
+  VPCGatewayAttachment,
+  RouteTable,
+  EC2Route,
+  SubnetRouteTableAssociation,
+  Sub,
+  AWS,
+} from "@intentius/chant-lexicon-aws";
+
+export const vpc = new Vpc({
+  CidrBlock: "10.0.0.0/16",
+  EnableDnsSupport: true,
+  EnableDnsHostnames: true,
+  Tags: [{ Key: "Name", Value: Sub`${AWS.StackName}-vpc` }],
+});
+
+export const subnet = new Subnet({
+  VpcId: vpc.VpcId,
+  CidrBlock: "10.0.1.0/24",
+  MapPublicIpOnLaunch: true,
+  Tags: [{ Key: "Name", Value: Sub`${AWS.StackName}-public` }],
+});
+
+export const igw = new InternetGateway({
+  Tags: [{ Key: "Name", Value: Sub`${AWS.StackName}-igw` }],
+});
+
+export const igwAttachment = new VPCGatewayAttachment({
+  VpcId: vpc.VpcId,
+  InternetGatewayId: igw.InternetGatewayId,
+});
+
+export const routeTable = new RouteTable({
+  VpcId: vpc.VpcId,
+  Tags: [{ Key: "Name", Value: Sub`${AWS.StackName}-public-rt` }],
+});
+
+export const defaultRoute = new EC2Route({
+  RouteTableId: routeTable.RouteTableId,
+  DestinationCidrBlock: "0.0.0.0/0",
+  GatewayId: igw.InternetGatewayId,
+});
+
+export const subnetRouteTableAssoc = new SubnetRouteTableAssociation({
+  SubnetId: subnet.SubnetId,
+  RouteTableId: routeTable.RouteTableId,
+});

package/dist/skills/aws-cloudformation.md

@@ -1,41 +0,0 @@
----
-name: aws-cloudformation
-description: AWS CloudFormation best practices and common patterns
----
-
-# AWS CloudFormation with Chant
-
-## Common Resource Types
-
-- `AWS::S3::Bucket` — Object storage
-- `AWS::Lambda::Function` — Serverless compute
-- `AWS::DynamoDB::Table` — NoSQL database
-- `AWS::IAM::Role` — Identity and access management
-- `AWS::SNS::Topic` — Pub/sub messaging
-- `AWS::SQS::Queue` — Message queue
-- `AWS::EC2::SecurityGroup` — Network firewall rules
-
-## Intrinsic Functions
-
-- `Sub` — String interpolation with `${}` syntax
-- `Ref` — Reference a resource or parameter
-- `GetAtt` — Get a resource attribute (e.g. ARN)
-- `If` — Conditional value based on a condition
-- `Join` — Join strings with a delimiter
-- `Select` — Pick an item from a list by index
-
-## Pseudo Parameters
-
-- `AWS::StackName` — Name of the current stack
-- `AWS::Region` — Current deployment region
-- `AWS::AccountId` — Current AWS account ID
-- `AWS::Partition` — Partition (aws, aws-cn, aws-us-gov)
-
-## Best Practices
-
-1. **Always enable encryption** — Use `BucketEncryption` for S3, `SSESpecification` for DynamoDB
-2. **Block public access** — Set `PublicAccessBlockConfiguration` on all S3 buckets
-3. **Use least-privilege IAM** — Avoid `*` in IAM policy actions and resources
-4. **Enable versioning** — Turn on `VersioningConfiguration` for data buckets
-5. **Use Sub for dynamic names** — `Sub\`\${AWS::StackName}-suffix\`` for unique naming
-6. **Share config via direct imports** — Put common settings in a config file and import directly