@intentius/chant-lexicon-aws 0.0.2

package/src/serializer.ts

@@ -0,0 +1,333 @@
+import type { Declarable, CoreParameter } from "@intentius/chant/declarable";
+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";
+
+/**
+ * Check if a declarable is a CoreParameter
+ */
+function isCoreParameter(entity: Declarable): entity is CoreParameter {
+  return "parameterType" in entity;
+}
+
+/**
+ * CloudFormation template structure
+ */
+interface CFTemplate {
+  AWSTemplateFormatVersion: "2010-09-09";
+  Description?: string;
+  Parameters?: Record<string, CFParameter>;
+  Resources: Record<string, CFResource>;
+  Outputs?: Record<string, CFOutput>;
+}
+
+/**
+ * CloudFormation parameter
+ */
+interface CFParameter {
+  Type: string;
+  Description?: string;
+  Default?: unknown;
+  AllowedValues?: unknown[];
+  AllowedPattern?: string;
+  ConstraintDescription?: string;
+  MaxLength?: number;
+  MaxValue?: number;
+  MinLength?: number;
+  MinValue?: number;
+  NoEcho?: boolean;
+}
+
+/**
+ * CloudFormation resource
+ */
+interface CFResource {
+  Type: string;
+  Properties?: Record<string, unknown>;
+  DependsOn?: string | string[];
+  Condition?: string;
+  Metadata?: Record<string, unknown>;
+}
+
+/**
+ * CloudFormation output
+ */
+interface CFOutput {
+  Value: unknown;
+  Description?: string;
+  Export?: { Name: unknown };
+  Condition?: string;
+}
+
+/**
+ * CloudFormation-specific visitor for the generic serializer walker.
+ */
+function cfnVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
+  return {
+    attrRef: (name, attr) => ({ "Fn::GetAttr": [name, attr] }),
+    resourceRef: (name) => ({ Ref: name }),
+    propertyDeclarable: (entity, walk) => {
+      if (!("props" in entity) || typeof entity.props !== "object" || entity.props === null) {
+        return undefined;
+      }
+      const props = entity.props as Record<string, unknown>;
+      const cfProps: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) {
+          const cfKey = toPascalCase(key);
+          cfProps[cfKey] = 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);
+}
+
+/**
+ * Convert entity props to CF properties
+ */
+function toProperties(
+  entity: Declarable,
+  entityNames: Map<Declarable, string>
+): Record<string, unknown> | undefined {
+  if (!("props" in entity) || typeof entity.props !== "object" || entity.props === null) {
+    return undefined;
+  }
+
+  const props = entity.props as Record<string, unknown>;
+  const cfProps: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(props)) {
+    if (value !== undefined) {
+      const cfKey = toPascalCase(key);
+      cfProps[cfKey] = toCFValue(value, entityNames, true);
+    }
+  }
+
+  return Object.keys(cfProps).length > 0 ? cfProps : undefined;
+}
+
+
+/**
+ * Serialize a set of entities into a CFTemplate object (without JSON.stringify).
+ */
+function serializeToTemplate(
+  entities: Map<string, Declarable>,
+  outputs?: LexiconOutput[],
+  extraParameters?: Record<string, CFParameter>,
+  extraOutputs?: Record<string, CFOutput>,
+): CFTemplate {
+  const template: CFTemplate = {
+    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<Declarable, string>();
+  for (const [name, entity] of entities) {
+    entityNames.set(entity, name);
+  }
+
+  // Process entities
+  for (const [name, entity] of entities) {
+    // Skip StackOutput entities — they go in the Outputs section
+    if (isStackOutput(entity)) {
+      continue;
+    }
+
+    if (isCoreParameter(entity)) {
+      if (!template.Parameters) {
+        template.Parameters = {};
+      }
+
+      const param: CFParameter = {
+        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;
+      }
+
+      template.Parameters[name] = param;
+    } else if (isChildProject(entity)) {
+      // ChildProjectInstance → AWS::CloudFormation::Stack resource
+      const childProject = entity as ChildProjectInstance;
+      const childName = childProject.logicalName;
+      const filename = `${childName}.template.json`;
+
+      const properties: Record<string, unknown> = {
+        TemplateURL: {
+          "Fn::Sub": `\${TemplateBasePath}/${filename}`,
+        },
+      };
+
+      // Build parameters: always pass TemplateBasePath down
+      const parameters: Record<string, unknown> = {
+        TemplateBasePath: { Ref: "TemplateBasePath" },
+      };
+
+      // Add user-specified parameters
+      const opts = childProject.options as { parameters?: Record<string, unknown> };
+      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: CFResource = {
+        Type: entity.entityType,
+      };
+
+      const properties = toProperties(entity, entityNames);
+      if (properties) {
+        resource.Properties = properties;
+      }
+
+      template.Resources[name] = resource;
+    }
+  }
+
+  // Emit StackOutput entities as CF Outputs
+  for (const [name, entity] of entities) {
+    if (isStackOutput(entity)) {
+      if (!template.Outputs) {
+        template.Outputs = {};
+      }
+      const stackOutput = entity as StackOutput;
+      const ref = stackOutput.sourceRef;
+      const logicalName = ref.getLogicalName();
+      if (logicalName) {
+        const output: CFOutput = {
+          Value: { "Fn::GetAttr": [logicalName, ref.attribute] },
+        };
+        if (stackOutput.description) {
+          output.Description = stackOutput.description;
+        }
+        template.Outputs[name] = output;
+      }
+    }
+  }
+
+  // Add CF Outputs for LexiconOutputs produced by this lexicon
+  if (outputs && outputs.length > 0) {
+    template.Outputs = template.Outputs ?? {};
+    for (const output of outputs) {
+      template.Outputs[output.outputName] = {
+        Value: {
+          "Fn::GetAttr": [output.sourceEntity, output.sourceAttribute],
+        },
+      };
+    }
+  }
+
+  // Add extra outputs (e.g. auto-wired cross-stack refs)
+  if (extraOutputs && Object.keys(extraOutputs).length > 0) {
+    template.Outputs = { ...template.Outputs, ...extraOutputs };
+  }
+
+  return template;
+}
+
+/**
+ * AWS CloudFormation serializer implementation
+ */
+export const awsSerializer: Serializer = {
+  name: "aws",
+  rulePrefix: "WAW",
+
+  serialize(entities: Map<string, Declarable>, outputs?: LexiconOutput[]): string | SerializerResult {
+    // Check if any entities are child projects (nested stacks)
+    const childProjects = new Map<string, ChildProjectInstance>();
+    let hasChildProjects = false;
+
+    for (const [name, entity] of entities) {
+      if (isChildProject(entity)) {
+        childProjects.set(name, entity as ChildProjectInstance);
+        hasChildProjects = true;
+      }
+    }
+
+    // No nested stacks — use the simple path
+    if (!hasChildProjects) {
+      const template = serializeToTemplate(entities, outputs);
+      return JSON.stringify(template, null, 2);
+    }
+
+    // Has child projects — produce multi-file output
+    const allFiles: Record<string, string> = {};
+
+    // Add TemplateBasePath parameter to the parent template
+    const parentParams: Record<string, CFParameter> = {
+      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);
+    const primary = JSON.stringify(parentTemplate, null, 2);
+
+    return {
+      primary,
+      files: allFiles,
+    };
+  },
+};

package/src/spec/fetch.test.ts

@@ -0,0 +1,27 @@
+import { describe, test, expect } from "bun:test";
+import { fetchSchemaZip } from "./fetch";
+
+describe("fetchSchemaZip", () => {
+  test("exports fetchSchemaZip function", () => {
+    expect(typeof fetchSchemaZip).toBe("function");
+  });
+
+  // Integration test - requires network, skip by default
+  test.skip("fetches schema zip from AWS (integration)", async () => {
+    const schemas = await fetchSchemaZip();
+
+    // Should have many resource schemas
+    expect(schemas.size).toBeGreaterThan(100);
+
+    // Should contain common resource types
+    expect(schemas.has("aws-s3-bucket.json")).toBe(true);
+    expect(schemas.has("aws-lambda-function.json")).toBe(true);
+
+    // Each schema should be valid JSON
+    for (const [name, buffer] of schemas) {
+      const text = new TextDecoder().decode(buffer);
+      const parsed = JSON.parse(text);
+      expect(parsed.typeName).toBeDefined();
+    }
+  });
+});

package/src/spec/fetch.ts

@@ -0,0 +1,107 @@
+import { homedir } from "os";
+import { join } from "path";
+import { fetchWithCache, extractFromZip, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Top-level CloudFormation Registry JSON Schema for a single resource type.
+ */
+export interface CFNSchema {
+  typeName: string;
+  description?: string;
+  properties?: Record<string, SchemaProperty>;
+  definitions?: Record<string, SchemaDefinition>;
+  required?: string[];
+  readOnlyProperties?: string[];
+  createOnlyProperties?: string[];
+  writeOnlyProperties?: string[];
+  primaryIdentifier?: string[];
+  additionalProperties?: boolean;
+}
+
+/**
+ * A single property in a CloudFormation Registry schema.
+ */
+export interface SchemaProperty {
+  type?: string | string[];
+  description?: string;
+  enum?: string[];
+  $ref?: string;
+  items?: SchemaProperty;
+  properties?: Record<string, SchemaProperty>;
+  oneOf?: unknown[];
+  anyOf?: unknown[];
+  required?: string[];
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  format?: string;
+  const?: unknown;
+  default?: unknown;
+}
+
+/**
+ * A named type within the definitions section.
+ */
+export interface SchemaDefinition {
+  type?: string | string[];
+  description?: string;
+  enum?: string[];
+  properties?: Record<string, SchemaProperty>;
+  required?: string[];
+  items?: SchemaProperty;
+}
+
+const SCHEMA_ZIP_URL = "https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip";
+const CACHE_DIR = join(homedir(), ".chant");
+const CACHE_FILE = join(CACHE_DIR, "CloudformationSchema.zip");
+
+/**
+ * Fetch the CloudFormation Registry schema zip and extract per-resource JSON schemas.
+ * Returns a Map keyed by typeName (e.g. "AWS::S3::Bucket") to raw JSON bytes.
+ *
+ * Uses a local cache with 24h TTL.
+ */
+export async function fetchSchemaZip(force = false): Promise<Map<string, Buffer>> {
+  const zipData = await fetchWithCache(
+    { url: SCHEMA_ZIP_URL, cacheFile: CACHE_FILE },
+    force,
+  );
+  return extractRawSchemas(zipData);
+}
+
+/**
+ * Extract raw JSON schema bytes from the zip, keyed by typeName.
+ */
+async function extractRawSchemas(zipData: Buffer): Promise<Map<string, Buffer>> {
+  const files = await extractFromZip(zipData, (name) => name.endsWith(".json"));
+
+  const schemas = new Map<string, Buffer>();
+  for (const [_name, data] of files) {
+    try {
+      const text = data.toString("utf-8");
+      const partial = JSON.parse(text) as { typeName?: string };
+      if (!partial.typeName) continue;
+      schemas.set(partial.typeName, data);
+    } catch {
+      // Skip files that can't be parsed
+    }
+  }
+
+  return schemas;
+}
+
+/**
+ * Get the cache file path (for testing)
+ */
+export function getCachePath(): string {
+  return CACHE_FILE;
+}
+
+/**
+ * Clear the cache (for testing)
+ */
+export function clearCache(): void {
+  clearCacheFile(CACHE_FILE);
+}

package/src/spec/parse.test.ts

@@ -0,0 +1,153 @@
+import { describe, test, expect } from "bun:test";
+import {
+  parseCFNSchema,
+  cfnShortName,
+  cfnServiceName,
+} from "./parse";
+
+// Sample Registry JSON Schema for testing
+const sampleBucketSchema = JSON.stringify({
+  typeName: "AWS::S3::Bucket",
+  description: "Creates an S3 bucket",
+  properties: {
+    BucketName: { type: "string", description: "Name of the bucket" },
+    Tags: {
+      type: "array",
+      items: { $ref: "#/definitions/Tag" },
+    },
+    VersioningConfiguration: {
+      $ref: "#/definitions/VersioningConfiguration",
+    },
+    AccessControl: {
+      type: "string",
+      enum: ["Private", "PublicRead", "PublicReadWrite"],
+    },
+  },
+  definitions: {
+    Tag: {
+      type: "object",
+      properties: {
+        Key: { type: "string" },
+        Value: { type: "string" },
+      },
+      required: ["Key", "Value"],
+      additionalProperties: false,
+    },
+    VersioningConfiguration: {
+      type: "object",
+      properties: {
+        Status: { type: "string", enum: ["Enabled", "Suspended"] },
+      },
+      required: ["Status"],
+      additionalProperties: false,
+    },
+  },
+  readOnlyProperties: [
+    "/properties/Arn",
+    "/properties/DomainName",
+    "/properties/RegionalDomainName",
+    "/properties/WebsiteURL",
+  ],
+  required: [],
+  primaryIdentifier: ["/properties/BucketName"],
+  additionalProperties: false,
+});
+
+describe("parseCFNSchema", () => {
+  test("parses resource type", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+
+    expect(result.resource.typeName).toBe("AWS::S3::Bucket");
+  });
+
+  test("parses properties", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+
+    expect(result.resource.properties.length).toBeGreaterThan(0);
+
+    const bucketName = result.resource.properties.find((p) => p.name === "BucketName");
+    expect(bucketName).toBeDefined();
+    expect(bucketName!.tsType).toBe("string");
+    expect(bucketName!.required).toBe(false);
+  });
+
+  test("parses attributes from readOnlyProperties", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+
+    expect(result.resource.attributes.length).toBe(4);
+    const arn = result.resource.attributes.find((a) => a.name === "Arn");
+    expect(arn).toBeDefined();
+  });
+
+  test("parses property types from definitions", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+
+    expect(result.propertyTypes.length).toBeGreaterThan(0);
+
+    const tag = result.propertyTypes.find((pt) => pt.name === "Bucket_Tag");
+    expect(tag).toBeDefined();
+    expect(tag!.properties.length).toBe(2);
+  });
+
+  test("parses enum values", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+
+    // AccessControl enum should be extracted from the property
+    const accessControl = result.resource.properties.find((p) => p.name === "AccessControl");
+    expect(accessControl).toBeDefined();
+    expect(accessControl!.enum).toContain("Private");
+    expect(accessControl!.enum).toContain("PublicRead");
+  });
+
+  test("parses array types", () => {
+    const result = parseCFNSchema(sampleBucketSchema);
+
+    const tags = result.resource.properties.find((p) => p.name === "Tags");
+    expect(tags).toBeDefined();
+    expect(tags!.tsType).toContain("[]");
+  });
+
+  test("parses required properties", () => {
+    const result = parseCFNSchema(JSON.stringify({
+      typeName: "AWS::Test::Resource",
+      properties: {
+        Name: { type: "string" },
+        Optional: { type: "string" },
+      },
+      required: ["Name"],
+      additionalProperties: false,
+    }));
+
+    const name = result.resource.properties.find((p) => p.name === "Name");
+    const optional = result.resource.properties.find((p) => p.name === "Optional");
+    expect(name!.required).toBe(true);
+    expect(optional!.required).toBe(false);
+  });
+
+  test("handles schema without properties", () => {
+    const result = parseCFNSchema(JSON.stringify({
+      typeName: "AWS::Test::Empty",
+      additionalProperties: false,
+    }));
+
+    expect(result.resource.typeName).toBe("AWS::Test::Empty");
+    expect(result.resource.properties).toEqual([]);
+    expect(result.resource.attributes).toEqual([]);
+  });
+});
+
+describe("cfnShortName", () => {
+  test("extracts short name from full type", () => {
+    expect(cfnShortName("AWS::S3::Bucket")).toBe("Bucket");
+    expect(cfnShortName("AWS::Lambda::Function")).toBe("Function");
+    expect(cfnShortName("AWS::IAM::Role")).toBe("Role");
+  });
+});
+
+describe("cfnServiceName", () => {
+  test("extracts service name from full type", () => {
+    expect(cfnServiceName("AWS::S3::Bucket")).toBe("S3");
+    expect(cfnServiceName("AWS::Lambda::Function")).toBe("Lambda");
+    expect(cfnServiceName("AWS::IAM::Role")).toBe("IAM");
+  });
+});