@intentius/chant-lexicon-aws 0.0.2

package/src/spec/parse.ts

@@ -0,0 +1,202 @@
+/**
+ * CloudFormation Registry JSON Schema parser.
+ *
+ * Parses each CFNSchema into typed structures suitable for code generation:
+ * resources with properties and attributes, property types from definitions,
+ * and enum types from string enum definitions.
+ */
+
+import type { CFNSchema, SchemaProperty, SchemaDefinition } from "./fetch";
+import {
+  resolvePropertyType as coreResolvePropertyType,
+  extractConstraints as coreExtractConstraints,
+  constraintsIsEmpty as coreConstraintsIsEmpty,
+  isEnumDefinition as coreIsEnumDefinition,
+  type PropertyConstraints,
+  type JsonSchemaDocument,
+  type JsonSchemaProperty,
+  type JsonSchemaDefinition,
+} from "@intentius/chant/codegen/json-schema";
+
+export type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
+
+export interface ParsedProperty {
+  name: string;
+  tsType: string;
+  required: boolean;
+  description?: string;
+  enum?: string[];
+  constraints: PropertyConstraints;
+}
+
+export interface ParsedAttribute {
+  name: string;
+  tsType: string;
+}
+
+export interface ParsedPropertyType {
+  name: string;
+  cfnType: string;
+  properties: ParsedProperty[];
+}
+
+export interface ParsedEnum {
+  name: string;
+  values: string[];
+}
+
+export interface ParsedResource {
+  typeName: string;
+  properties: ParsedProperty[];
+  attributes: ParsedAttribute[];
+  createOnly: string[];
+  writeOnly: string[];
+  primaryIdentifier: string[];
+}
+
+export interface SchemaParseResult {
+  resource: ParsedResource;
+  propertyTypes: ParsedPropertyType[];
+  enums: ParsedEnum[];
+}
+
+/**
+ * Parse a CloudFormation Registry JSON Schema into typed structures.
+ */
+export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
+  const schema: CFNSchema = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+
+  const requiredSet = new Set<string>(schema.required ?? []);
+  const shortName = cfnShortName(schema.typeName);
+
+  // Parse top-level properties
+  const props: ParsedProperty[] = [];
+  if (schema.properties) {
+    for (const [name, prop] of Object.entries(schema.properties)) {
+      const tsType = resolvePropertyType(prop, schema);
+      props.push({
+        name,
+        tsType,
+        required: requiredSet.has(name),
+        description: prop.description,
+        enum: prop.enum,
+        constraints: extractConstraints(prop),
+      });
+    }
+  }
+
+  // Parse readOnlyProperties as attributes
+  const attrs: ParsedAttribute[] = [];
+  for (const path of schema.readOnlyProperties ?? []) {
+    const attrName = stripPointerPath(path);
+    // Skip nested paths (contain "/" after stripping prefix, or ".")
+    if (attrName.includes("/") || attrName.includes(".")) continue;
+
+    // Try to find type from properties, default to string
+    let tsType = "string";
+    if (schema.properties?.[attrName]) {
+      tsType = resolvePropertyType(schema.properties[attrName], schema);
+    }
+    attrs.push({ name: attrName, tsType });
+  }
+
+  // Parse definitions into property types and enums
+  const propertyTypes: ParsedPropertyType[] = [];
+  const enums: ParsedEnum[] = [];
+
+  if (schema.definitions) {
+    for (const [defName, def] of Object.entries(schema.definitions)) {
+      if (isEnumDefinition(def)) {
+        enums.push({
+          name: `${shortName}_${defName}`,
+          values: def.enum!,
+        });
+        continue;
+      }
+
+      if (def.properties) {
+        const defRequired = new Set<string>(def.required ?? []);
+        const defProps: ParsedProperty[] = [];
+        for (const [propName, prop] of Object.entries(def.properties)) {
+          const tsType = resolvePropertyType(prop, schema);
+          defProps.push({
+            name: propName,
+            tsType,
+            required: defRequired.has(propName),
+            description: prop.description,
+            enum: prop.enum,
+            constraints: extractConstraints(prop),
+          });
+        }
+        propertyTypes.push({
+          name: `${shortName}_${defName}`,
+          cfnType: defName,
+          properties: defProps,
+        });
+      }
+    }
+  }
+
+  return {
+    resource: {
+      typeName: schema.typeName,
+      properties: props,
+      attributes: attrs,
+      createOnly: stripPointerPaths(schema.createOnlyProperties ?? []),
+      writeOnly: stripPointerPaths(schema.writeOnlyProperties ?? []),
+      primaryIdentifier: stripPointerPaths(schema.primaryIdentifier ?? []),
+    },
+    propertyTypes,
+    enums,
+  };
+}
+
+// --- Type resolution (delegated to core) ---
+
+function resolvePropertyType(prop: SchemaProperty | undefined, schema: CFNSchema): string {
+  const shortName = cfnShortName(schema.typeName);
+  return coreResolvePropertyType(
+    prop as JsonSchemaProperty | undefined,
+    schema as unknown as JsonSchemaDocument,
+    (defName) => `${shortName}_${defName}`,
+  );
+}
+
+function extractConstraints(prop: SchemaProperty): PropertyConstraints {
+  return coreExtractConstraints(prop as JsonSchemaProperty);
+}
+
+export const constraintsIsEmpty = coreConstraintsIsEmpty;
+
+function isEnumDefinition(def: SchemaDefinition): boolean {
+  return coreIsEnumDefinition(def as JsonSchemaDefinition);
+}
+
+/**
+ * Extract short resource name: "AWS::S3::Bucket" → "Bucket"
+ */
+export function cfnShortName(typeName: string): string {
+  const parts = typeName.split("::");
+  return parts.length >= 3 ? parts[2] : typeName;
+}
+
+/**
+ * Extract service name: "AWS::S3::Bucket" → "S3"
+ */
+export function cfnServiceName(typeName: string): string {
+  const parts = typeName.split("::");
+  return parts.length >= 2 ? parts[1] : typeName;
+}
+
+/**
+ * Strip JSON pointer path prefix: "/properties/BucketName" → "BucketName"
+ */
+function stripPointerPath(path: string): string {
+  const prefix = "/properties/";
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+
+function stripPointerPaths(paths: string[]): string[] {
+  if (paths.length === 0) return [];
+  return paths.map(stripPointerPath);
+}

package/src/testdata/load-fixtures.ts

@@ -0,0 +1,17 @@
+import { readFileSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+export function loadSchemaFixtures(): Map<string, Buffer> {
+  const schemasDir = join(dirname(fileURLToPath(import.meta.url)), "schemas");
+  const schemas = new Map<string, Buffer>();
+  for (const file of readdirSync(schemasDir)) {
+    if (!file.endsWith(".json")) continue;
+    const data = readFileSync(join(schemasDir, file));
+    const parsed = JSON.parse(data.toString("utf-8"));
+    if (parsed.typeName) {
+      schemas.set(parsed.typeName, Buffer.from(data));
+    }
+  }
+  return schemas;
+}

package/src/testdata/roundtrip/conditions.json

@@ -0,0 +1,21 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Template with conditions",
+  "Parameters": {
+    "Environment": {
+      "Type": "String",
+      "Default": "dev"
+    }
+  },
+  "Conditions": {
+    "IsProd": { "Fn::Equals": [{ "Ref": "Environment" }, "prod"] }
+  },
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": { "Fn::If": ["IsProd", "prod-bucket", "dev-bucket"] }
+      }
+    }
+  }
+}

package/src/testdata/roundtrip/intrinsic-calls.json

@@ -0,0 +1,31 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Template with GetAtt and Ref intrinsic calls",
+  "Resources": {
+    "LambdaRole": {
+      "Type": "AWS::IAM::Role",
+      "Properties": {
+        "RoleName": "lambda-role",
+        "AssumeRolePolicyDocument": {
+          "Version": "2012-10-17",
+          "Statement": [
+            {
+              "Effect": "Allow",
+              "Principal": { "Service": "lambda.amazonaws.com" },
+              "Action": "sts:AssumeRole"
+            }
+          ]
+        }
+      }
+    },
+    "MyFunction": {
+      "Type": "AWS::Lambda::Function",
+      "Properties": {
+        "FunctionName": "my-function",
+        "Runtime": "nodejs18.x",
+        "Handler": "index.handler",
+        "Role": { "Fn::GetAtt": ["LambdaRole", "Arn"] }
+      }
+    }
+  }
+}

package/src/testdata/roundtrip/intrinsics.json

@@ -0,0 +1,18 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Template with intrinsic functions",
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": { "Fn::Sub": "${AWS::StackName}-data" }
+      }
+    },
+    "MyQueue": {
+      "Type": "AWS::SQS::Queue",
+      "Properties": {
+        "QueueName": { "Fn::Join": ["-", ["my", "queue", { "Ref": "AWS::Region" }]] }
+      }
+    }
+  }
+}

package/src/testdata/roundtrip/multi-resource.json

@@ -0,0 +1,37 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Template with multiple resource types",
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": "my-bucket"
+      }
+    },
+    "MyQueue": {
+      "Type": "AWS::SQS::Queue",
+      "Properties": {
+        "QueueName": "my-queue"
+      }
+    },
+    "MyTopic": {
+      "Type": "AWS::SNS::Topic",
+      "Properties": {
+        "TopicName": "my-topic"
+      }
+    },
+    "MyTable": {
+      "Type": "AWS::DynamoDB::Table",
+      "Properties": {
+        "TableName": "my-table",
+        "AttributeDefinitions": [
+          { "AttributeName": "id", "AttributeType": "S" }
+        ],
+        "KeySchema": [
+          { "AttributeName": "id", "KeyType": "HASH" }
+        ],
+        "BillingMode": "PAY_PER_REQUEST"
+      }
+    }
+  }
+}

package/src/testdata/roundtrip/parameters.json

@@ -0,0 +1,23 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Template with parameters",
+  "Parameters": {
+    "Environment": {
+      "Type": "String",
+      "Default": "dev",
+      "Description": "Deployment environment"
+    },
+    "BucketPrefix": {
+      "Type": "String",
+      "Description": "Prefix for bucket name"
+    }
+  },
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": { "Ref": "BucketPrefix" }
+      }
+    }
+  }
+}

package/src/testdata/roundtrip/simple.json

@@ -0,0 +1,12 @@
+{
+  "AWSTemplateFormatVersion": "2010-09-09",
+  "Description": "Simple S3 bucket",
+  "Resources": {
+    "MyBucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": "my-simple-bucket"
+      }
+    }
+  }
+}

package/src/testdata/sam-fixtures/api.yaml

@@ -0,0 +1,14 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM Api Gateway
+
+Resources:
+  MyApi:
+    Type: AWS::Serverless::Api
+    Properties:
+      StageName: prod
+      TracingEnabled: true
+      Cors:
+        AllowOrigin: "'*'"
+        AllowHeaders: "'Content-Type'"
+        AllowMethods: "'GET,POST'"

package/src/testdata/sam-fixtures/application.yaml

@@ -0,0 +1,13 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM Application (nested stack)
+
+Resources:
+  MyApp:
+    Type: AWS::Serverless::Application
+    Properties:
+      Location:
+        ApplicationId: arn:aws:serverlessrepo:us-east-1:123456789012:applications/my-app
+        SemanticVersion: 1.0.0
+      Parameters:
+        Stage: prod

package/src/testdata/sam-fixtures/function.yaml

@@ -0,0 +1,22 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM Function
+
+Resources:
+  MyFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      Runtime: nodejs18.x
+      CodeUri: s3://bucket/code.zip
+      MemorySize: 256
+      Timeout: 30
+      Environment:
+        Variables:
+          TABLE_NAME: my-table
+      Events:
+        ApiEvent:
+          Type: Api
+          Properties:
+            Path: /hello
+            Method: get

package/src/testdata/sam-fixtures/graphql-api.yaml

@@ -0,0 +1,13 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM GraphQL API
+
+Resources:
+  MyGraphQLApi:
+    Type: AWS::Serverless::GraphQLApi
+    Properties:
+      Name: my-graphql-api
+      SchemaUri: schema.graphql
+      Auth:
+        Type: API_KEY
+      XrayEnabled: true

package/src/testdata/sam-fixtures/http-api.yaml

@@ -0,0 +1,15 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM HTTP API
+
+Resources:
+  MyHttpApi:
+    Type: AWS::Serverless::HttpApi
+    Properties:
+      StageName: prod
+      CorsConfiguration:
+        AllowOrigins:
+          - "https://example.com"
+        AllowMethods:
+          - GET
+          - POST

package/src/testdata/sam-fixtures/layer-version.yaml

@@ -0,0 +1,15 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM Layer Version
+
+Resources:
+  MyLayer:
+    Type: AWS::Serverless::LayerVersion
+    Properties:
+      LayerName: my-layer
+      Description: Shared dependencies
+      ContentUri: s3://bucket/layer.zip
+      CompatibleRuntimes:
+        - nodejs18.x
+        - nodejs20.x
+      RetentionPolicy: Retain

package/src/testdata/sam-fixtures/multi-type-a.yaml

@@ -0,0 +1,23 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: Multi-type SAM template A - Function with API
+
+Resources:
+  MyApi:
+    Type: AWS::Serverless::Api
+    Properties:
+      StageName: prod
+
+  MyFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      Runtime: nodejs18.x
+      CodeUri: s3://bucket/code.zip
+      Events:
+        GetItems:
+          Type: Api
+          Properties:
+            Path: /items
+            Method: get
+            RestApiId: !Ref MyApi

package/src/testdata/sam-fixtures/multi-type-b.yaml

@@ -0,0 +1,29 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: Multi-type SAM template B - Function with Table and Layer
+
+Resources:
+  SharedLayer:
+    Type: AWS::Serverless::LayerVersion
+    Properties:
+      LayerName: shared-deps
+      ContentUri: s3://bucket/layer.zip
+      CompatibleRuntimes:
+        - nodejs18.x
+
+  DataTable:
+    Type: AWS::Serverless::SimpleTable
+    Properties:
+      TableName: data-table
+
+  ProcessFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      Runtime: nodejs18.x
+      CodeUri: s3://bucket/code.zip
+      Layers:
+        - !Ref SharedLayer
+      Environment:
+        Variables:
+          TABLE_NAME: !Ref DataTable

package/src/testdata/sam-fixtures/simple-table.yaml

@@ -0,0 +1,12 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM Simple Table
+
+Resources:
+  MyTable:
+    Type: AWS::Serverless::SimpleTable
+    Properties:
+      TableName: my-table
+      PrimaryKey:
+        Name: id
+        Type: String

package/src/testdata/sam-fixtures/state-machine.yaml

@@ -0,0 +1,14 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: SAM State Machine
+
+Resources:
+  MyStateMachine:
+    Type: AWS::Serverless::StateMachine
+    Properties:
+      Name: my-state-machine
+      Type: STANDARD
+      DefinitionUri: statemachine/definition.asl.json
+      Policies:
+        - LambdaInvokePolicy:
+            FunctionName: my-function

package/src/testdata/schemas/aws-dynamodb-table.json

@@ -0,0 +1,126 @@
+{
+  "typeName": "AWS::DynamoDB::Table",
+  "description": "The AWS::DynamoDB::Table resource creates a DynamoDB table.",
+  "properties": {
+    "TableName": {
+      "type": "string",
+      "description": "A name for the table.",
+      "minLength": 3,
+      "maxLength": 255,
+      "pattern": "^[a-zA-Z0-9._-]+$"
+    },
+    "Arn": {
+      "type": "string",
+      "description": "The Amazon Resource Name (ARN) of the DynamoDB table."
+    },
+    "KeySchema": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/KeySchema"
+      },
+      "description": "Specifies the attributes that make up the primary key for the table."
+    },
+    "AttributeDefinitions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/AttributeDefinition"
+      },
+      "description": "A list of attributes that describe the key schema for the table."
+    },
+    "BillingMode": {
+      "type": "string",
+      "description": "Specify how you are charged for read and write throughput.",
+      "enum": ["PROVISIONED", "PAY_PER_REQUEST"]
+    },
+    "SSESpecification": {
+      "$ref": "#/definitions/SSESpecification",
+      "description": "Specifies the settings to enable server-side encryption."
+    },
+    "Tags": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Tag"
+      },
+      "description": "An array of key-value pairs to apply to this resource."
+    }
+  },
+  "definitions": {
+    "KeySchema": {
+      "type": "object",
+      "description": "Represents a single element of a key schema.",
+      "properties": {
+        "AttributeName": {
+          "type": "string",
+          "description": "The name of a key attribute.",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "KeyType": {
+          "type": "string",
+          "description": "The role that this key attribute will assume.",
+          "enum": ["HASH", "RANGE"]
+        }
+      },
+      "required": ["AttributeName", "KeyType"]
+    },
+    "AttributeDefinition": {
+      "type": "object",
+      "description": "Represents an attribute for describing the schema for the table.",
+      "properties": {
+        "AttributeName": {
+          "type": "string",
+          "description": "A name for the attribute.",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "AttributeType": {
+          "type": "string",
+          "description": "The data type for the attribute.",
+          "enum": ["S", "N", "B"]
+        }
+      },
+      "required": ["AttributeName", "AttributeType"]
+    },
+    "SSESpecification": {
+      "type": "object",
+      "description": "Represents the settings used to enable server-side encryption.",
+      "properties": {
+        "SSEEnabled": {
+          "type": "boolean",
+          "description": "Indicates whether server-side encryption is done using an AWS managed key or a customer managed key."
+        },
+        "SSEType": {
+          "type": "string",
+          "description": "Server-side encryption type.",
+          "enum": ["AES256", "KMS"]
+        },
+        "KMSMasterKeyId": {
+          "type": "string",
+          "description": "The KMS key that should be used for the KMS encryption."
+        }
+      },
+      "required": ["SSEEnabled"]
+    },
+    "Tag": {
+      "type": "object",
+      "description": "A key-value pair to associate with a resource.",
+      "properties": {
+        "Key": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "Value": {
+          "type": "string",
+          "maxLength": 256
+        }
+      },
+      "required": ["Key", "Value"]
+    }
+  },
+  "required": ["KeySchema", "AttributeDefinitions"],
+  "readOnlyProperties": ["/properties/Arn"],
+  "createOnlyProperties": ["/properties/TableName"],
+  "primaryIdentifier": ["/properties/TableName"],
+  "additionalProperties": false
+}