@intentius/chant-lexicon-aws 0.0.12 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "license": "Apache-2.0",
   "type": "module",
   "files": ["src/", "dist/"],
@@ -22,7 +22,7 @@
   "prepack": "bun run bundle && bun run validate"
 },
 "dependencies": {
-  "@intentius/chant": "0.0.11",
+  "@intentius/chant": "0.0.13",
   "fflate": "^0.8.2",
   "js-yaml": "^4.1.0"
 },

package/src/codegen/docs.ts

@@ -149,22 +149,23 @@ When you reference a resource or attribute from another file (e.g. \`dataBucket.
 
 CloudFormation parameters let you customize a stack at deploy time. Export a \`Parameter\` to add it to the template's \`Parameters\` section:
 
-{{file:docs-snippets/src/parameter-ref.ts}}
+{{file:docs-snippets/src/parameter-declaration.ts}}
 
 Produces:
 
 \`\`\`json
 "Parameters": {
-  "Name": {
+  "Environment": {
     "Type": "String",
-    "Description": "Project name used in resource naming"
+    "Default": "dev",
+    "Description": "Deployment environment"
   }
 }
 \`\`\`
 
 Reference parameters with \`Ref\`:
 
-{{file:docs-snippets/src/parameter-ref.ts}}
+{{file:docs-snippets/src/parameter-cross-file-ref.ts}}
 
 ## Outputs
 
@@ -201,7 +202,7 @@ Runtime context values available in every template, accessed via the \`AWS\` nam
 
 ## Intrinsic functions
 
-The lexicon provides 8 intrinsic functions (\`Sub\`, \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`) that map directly to CloudFormation \`Fn::\` calls. See [Intrinsic Functions](../intrinsics/) for full usage examples.
+The lexicon provides 9 intrinsic functions (\`Sub\`, \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`, \`GetAZs\`) that map directly to CloudFormation \`Fn::\` calls. See [Intrinsic Functions](../intrinsics/) for full usage examples.
 
 ## Dependencies
 
@@ -369,7 +370,13 @@ Splits a string by a delimiter:
 
 Encodes a string to Base64, commonly used for EC2 user data:
 
-{{file:docs-snippets/src/intrinsics-detail.ts:23-27}}`,
+{{file:docs-snippets/src/intrinsics-detail.ts:23-27}}
+
+## \`GetAZs\` — availability zones
+
+Returns the list of Availability Zones for a region:
+
+{{file:docs-snippets/src/intrinsics-detail.ts:29-31}}`,
       },
       {
         slug: "composites",
@@ -407,6 +414,7 @@ The AWS lexicon ships ready-to-use composites for common patterns. Import them f
 | \`FargateAlb\` | \`cluster\`, \`executionRole\`, \`taskRole\`, \`logGroup\`, \`taskDef\`, \`albSg\`, \`taskSg\`, \`alb\`, \`targetGroup\`, \`listener\`, \`service\` | Fargate service behind an ALB. Accepts VPC outputs as props. |
 | \`AlbShared\` | \`cluster\`, \`executionRole\`, \`albSg\`, \`alb\`, \`listener\` | Shared ALB infrastructure (ECS cluster, execution role, ALB, listener with 404 default). Created once, consumed by multiple \`FargateService\` instances. |
 | \`FargateService\` | \`taskRole\`, \`logGroup\`, \`taskDef\`, \`taskSg\`, \`targetGroup\`, \`rule\`, \`service\` | Per-service Fargate resources with listener rule routing. Wire to an \`AlbShared\` instance for multi-service ALB patterns. |
+| \`RdsInstance\` | \`subnetGroup\`, \`sg\`, \`db\` (+ \`parameterGroup\` if configured) | RDS instance (postgres, mysql, mariadb) in private subnets. Creates DB subnet group, security group, and optionally a parameter group. Engine-specific defaults for port, username, and version. Encrypted by default. |
 
 All built-in composites accept \`ManagedPolicyArns\` and \`Policies\` for adding IAM permissions to the auto-created role.
 
@@ -749,6 +757,72 @@ WAW030: API Gateway Deployment "MyDeployment" has no DependsOn on any Method
 WAW030: ScalableTarget "MyTarget" targets DynamoDB but has no DependsOn on any Table
 \`\`\`
 
+### WAW018 — S3 Bucket Missing Public Access Block
+
+**Severity:** error | **Category:** security
+
+Flags S3 buckets without a \`PublicAccessBlockConfiguration\`. Without an explicit public access block, the bucket may be publicly accessible. Always set \`BlockPublicAcls\`, \`BlockPublicPolicy\`, \`IgnorePublicAcls\`, and \`RestrictPublicBuckets\` to \`true\`.
+
+### WAW019 — Security Group Unrestricted Ingress on Sensitive Ports
+
+**Severity:** error | **Category:** security
+
+Flags security group ingress rules that allow unrestricted access (\`0.0.0.0/0\` or \`::/0\`) on sensitive ports (22, 3389, 3306, 5432, 1433, 6379, 27017). Restrict ingress to known CIDR ranges or security groups.
+
+### WAW020 — IAM Policy Uses Wildcard Action
+
+**Severity:** warning | **Category:** security
+
+Flags IAM policy statements that use wildcard actions (\`"Action": "*"\` or \`"Action": "s3:*"\`). Use specific action names following the principle of least privilege.
+
+### WAW021 — RDS Storage Not Encrypted
+
+**Severity:** error | **Category:** security
+
+Flags RDS instances without \`StorageEncrypted: true\`. All RDS instances should encrypt data at rest to meet compliance and security requirements.
+
+### WAW022 — Lambda Not in VPC
+
+**Severity:** warning | **Category:** security
+
+Flags Lambda functions without a \`VpcConfig\`. Functions that access internal resources (databases, caches, internal APIs) should run inside a VPC. Functions that only call public APIs can safely skip VPC configuration.
+
+### WAW023 — CloudFront Without WAF
+
+**Severity:** warning | **Category:** security
+
+Flags CloudFront distributions without a \`WebACLId\`. Attaching a WAF web ACL protects your distribution from common web exploits and bots.
+
+### WAW024 — ALB Without Access Logging
+
+**Severity:** warning | **Category:** best practice
+
+Flags Application Load Balancers without access logging enabled. Enable \`access_logs.s3.enabled\` to capture request logs for debugging and compliance.
+
+### WAW025 — SNS Topic Not Encrypted
+
+**Severity:** warning | **Category:** security
+
+Flags SNS topics without \`KmsMasterKeyId\`. Encrypting topics at rest protects sensitive notification payloads.
+
+### WAW026 — SQS Queue Not Encrypted
+
+**Severity:** warning | **Category:** security
+
+Flags SQS queues without \`KmsMasterKeyId\` or \`SqsManagedSseEnabled\`. Encrypting queues at rest protects sensitive message payloads.
+
+### WAW027 — DynamoDB Missing Point-in-Time Recovery
+
+**Severity:** info | **Category:** best practice
+
+Flags DynamoDB tables without \`PointInTimeRecoverySpecification.PointInTimeRecoveryEnabled\` set to \`true\`. Point-in-time recovery provides continuous backups and protects against accidental writes or deletes.
+
+### WAW028 — EBS Volume Not Encrypted
+
+**Severity:** warning | **Category:** security
+
+Flags EBS volumes without \`Encrypted: true\`. All EBS volumes should encrypt data at rest for compliance and security.
+
 ## Running lint
 
 \`\`\`bash
@@ -953,7 +1027,19 @@ src/
 - **Composite presets** — \`SecureApi\` (low memory, short timeout) and \`HighMemoryApi\` (high memory, longer timeout)
 - **Custom lint rule** — \`api-timeout.ts\` enforces API Gateway's 29-second timeout limit (see [Custom Lint Rules](../custom-rules/))
 
-The example produces 10 CloudFormation resources: 1 S3 bucket + 3 composites × 3 members each.`,
+The example produces 10 CloudFormation resources: 1 S3 bucket + 3 composites × 3 members each.
+
+## RDS Instance
+
+\`examples/rds-postgres/\` — production RDS PostgreSQL instance using the \`RdsInstance\` composite with VPC networking and SSM parameter references.
+
+{{file:rds-postgres/src/params.ts}}
+
+{{file:rds-postgres/src/network.ts}}
+
+{{file:rds-postgres/src/database.ts}}
+
+Produces a complete RDS stack: VPC infrastructure (from \`VpcDefault\`), DB subnet group, security group, and RDS instance with encrypted storage.`,
       },
       {
         slug: "skills",

package/src/codegen/generate-typescript.ts

@@ -78,7 +78,7 @@ export function generateTypeScriptDeclarations(
       description: p.description,
     }));
     const dtsAttrs: DtsAttribute[] = r.resource.attributes.map((a) => ({
-      name: a.name,
+      name: a.name.replace(/\./g, "_").replace(/\*/g, "Item"),  // Subscribers.*.Status → Subscribers_Item_Status
       type: a.tsType,
     }));
 

package/src/codegen/generate.ts

@@ -170,10 +170,11 @@ function generateRuntimeIndex(
     const tsName = naming.resolve(cfnType);
     if (!tsName) continue;
 
-    // Build attrs map
+    // Build attrs map: TS key (underscores) → CF attr name (dots)
     const attrs: Record<string, string> = {};
     for (const a of r.resource.attributes) {
-      attrs[a.name] = a.name;
+      const tsKey = a.name.replace(/\./g, "_").replace(/\*/g, "Item");  // Subscribers.*.Status → Subscribers_Item_Status
+      attrs[tsKey] = a.name;                      // maps to "Endpoint.Address" for GetAtt
     }
 
     resourceEntries.push({ tsName, resourceType: cfnType, attrs });

package/src/composites/composites.test.ts

@@ -13,6 +13,7 @@ import { VpcDefault } from "./vpc-default";
 import { FargateAlb } from "./fargate-alb";
 import { AlbShared } from "./alb-shared";
 import { FargateService } from "./fargate-service";
+import { RdsInstance } from "./rds-instance";
 
 const baseProps = {
   name: "TestFunc",
@@ -633,3 +634,150 @@ describe("FargateService", () => {
     expect(svcProps.DesiredCount).toBe(2);
   });
 });
+
+describe("RdsInstance", () => {
+  const rdsProps = {
+    vpcId: "vpc-123",
+    subnetIds: ["subnet-1", "subnet-2"],
+    masterPassword: "secret",
+  };
+
+  test("returns subnetGroup, sg, db members", () => {
+    const instance = RdsInstance(rdsProps);
+    const names = Object.keys(instance.members);
+    expect(names).toContain("subnetGroup");
+    expect(names).toContain("sg");
+    expect(names).toContain("db");
+    expect(names).toHaveLength(3);
+  });
+
+  test("expandComposite produces correct logical names", () => {
+    const expanded = expandComposite("myDb", RdsInstance(rdsProps));
+    expect(expanded.has("myDbSubnetGroup")).toBe(true);
+    expect(expanded.has("myDbSg")).toBe(true);
+    expect(expanded.has("myDbDb")).toBe(true);
+    expect(expanded.size).toBe(3);
+  });
+
+  test("with parameterGroupFamily, also returns parameterGroup", () => {
+    const instance = RdsInstance({
+      ...rdsProps,
+      parameterGroupFamily: "postgres16",
+      parameters: { shared_preload_libraries: "pg_stat_statements" },
+    });
+    const names = Object.keys(instance.members);
+    expect(names).toContain("parameterGroup");
+    expect(names).toHaveLength(4);
+  });
+
+  test("expandComposite with parameterGroup produces 4 entries", () => {
+    const expanded = expandComposite("pg", RdsInstance({
+      ...rdsProps,
+      parameterGroupFamily: "postgres16",
+    }));
+    expect(expanded.has("pgSubnetGroup")).toBe(true);
+    expect(expanded.has("pgSg")).toBe(true);
+    expect(expanded.has("pgDb")).toBe(true);
+    expect(expanded.has("pgParameterGroup")).toBe(true);
+    expect(expanded.size).toBe(4);
+  });
+
+  test("ingress from SG produces SourceSecurityGroupId rule", () => {
+    const instance = RdsInstance({
+      ...rdsProps,
+      ingressSourceSG: "sg-app123",
+    });
+    const sgProps = (instance.sg as any).props;
+    expect(sgProps.SecurityGroupIngress).toHaveLength(1);
+    const ingress = (sgProps.SecurityGroupIngress[0] as any).props;
+    expect(ingress.SourceSecurityGroupId).toBe("sg-app123");
+    expect(ingress.FromPort).toBe(5432);
+    expect(ingress.ToPort).toBe(5432);
+  });
+
+  test("ingress from CIDR produces CidrIp rule", () => {
+    const instance = RdsInstance({
+      ...rdsProps,
+      ingressCidr: "10.0.0.0/16",
+    });
+    const sgProps = (instance.sg as any).props;
+    expect(sgProps.SecurityGroupIngress).toHaveLength(1);
+    const ingress = (sgProps.SecurityGroupIngress[0] as any).props;
+    expect(ingress.CidrIp).toBe("10.0.0.0/16");
+    expect(ingress.FromPort).toBe(5432);
+  });
+
+  test("no ingress when neither SG nor CIDR provided", () => {
+    const instance = RdsInstance(rdsProps);
+    const sgProps = (instance.sg as any).props;
+    expect(sgProps.SecurityGroupIngress).toBeUndefined();
+  });
+
+  test("default engine is postgres with correct defaults", () => {
+    const instance = RdsInstance(rdsProps);
+    const dbProps = (instance.db as any).props;
+    expect(dbProps.Engine).toBe("postgres");
+    expect(dbProps.EngineVersion).toBe("16.6");
+    expect(dbProps.DBInstanceClass).toBe("db.t4g.micro");
+    expect(dbProps.AllocatedStorage).toBe("20");
+    expect(dbProps.StorageType).toBe("gp3");
+    expect(dbProps.StorageEncrypted).toBe(true);
+    expect(dbProps.MultiAZ).toBe(false);
+    expect(dbProps.BackupRetentionPeriod).toBe(7);
+    expect(dbProps.CopyTagsToSnapshot).toBe(true);
+    expect(dbProps.AutoMinorVersionUpgrade).toBe(true);
+    expect(dbProps.PubliclyAccessible).toBe(false);
+    expect(dbProps.DeletionProtection).toBe(false);
+    expect(dbProps.MasterUsername).toBe("postgres");
+  });
+
+  test("engine: mysql uses mysql-specific defaults", () => {
+    const instance = RdsInstance({
+      ...rdsProps,
+      engine: "mysql",
+      ingressCidr: "10.0.0.0/16",
+    });
+    const dbProps = (instance.db as any).props;
+    expect(dbProps.Engine).toBe("mysql");
+    expect(dbProps.EngineVersion).toBe("8.0.40");
+    expect(dbProps.MasterUsername).toBe("admin");
+    expect(dbProps.Port).toBe("3306");
+    const ingress = ((instance.sg as any).props.SecurityGroupIngress[0] as any).props;
+    expect(ingress.FromPort).toBe(3306);
+    expect(ingress.ToPort).toBe(3306);
+  });
+
+  test("engine: mariadb uses mariadb-specific defaults", () => {
+    const instance = RdsInstance({
+      ...rdsProps,
+      engine: "mariadb",
+    });
+    const dbProps = (instance.db as any).props;
+    expect(dbProps.Engine).toBe("mariadb");
+    expect(dbProps.EngineVersion).toBe("11.4.3");
+    expect(dbProps.MasterUsername).toBe("admin");
+    expect(dbProps.Port).toBe("3306");
+  });
+
+  test("custom port is applied to SG and DB", () => {
+    const instance = RdsInstance({
+      ...rdsProps,
+      port: 3306,
+      ingressCidr: "10.0.0.0/8",
+    });
+    const dbProps = (instance.db as any).props;
+    expect(dbProps.Port).toBe("3306");
+    const ingress = ((instance.sg as any).props.SecurityGroupIngress[0] as any).props;
+    expect(ingress.FromPort).toBe(3306);
+    expect(ingress.ToPort).toBe(3306);
+  });
+
+  test("db references subnet group and security group", () => {
+    const instance = RdsInstance(rdsProps);
+    const dbProps = (instance.db as any).props;
+    // Subnet group is passed as a resource instance (serializer resolves to { Ref: ... })
+    expect(dbProps.DBSubnetGroupName).toBe(instance.subnetGroup);
+    expect(dbProps.VPCSecurityGroups).toHaveLength(1);
+    expect(dbProps.VPCSecurityGroups[0]).toBeInstanceOf(AttrRef);
+  });
+});

package/src/composites/index.ts

@@ -22,3 +22,5 @@ export { AlbShared } from "./alb-shared";
 export type { AlbSharedProps } from "./alb-shared";
 export { FargateService } from "./fargate-service";
 export type { FargateServiceProps } from "./fargate-service";
+export { RdsInstance, RdsInstance as RdsPostgres } from "./rds-instance";
+export type { RdsInstanceProps, RdsInstanceProps as RdsPostgresProps } from "./rds-instance";

package/src/composites/rds-instance.ts

@@ -0,0 +1,173 @@
+import { Composite } from "@intentius/chant";
+import {
+  DbInstance,
+  RDSDBSubnetGroup,
+  RDSDBParameterGroup,
+  SecurityGroup,
+  SecurityGroup_Ingress,
+} from "../generated";
+
+const ENGINE_DEFAULTS: Record<string, { port: number; username: string; version: string; logExport: string }> = {
+  postgres: { port: 5432, username: "postgres", version: "16.6",  logExport: "postgresql" },
+  mysql:    { port: 3306, username: "admin",    version: "8.0.40", logExport: "general" },
+  mariadb:  { port: 3306, username: "admin",    version: "11.4.3", logExport: "general" },
+};
+
+export interface RdsInstanceProps {
+  // ── Engine ──────────────────────────────────────────────────────
+  engine?: "postgres" | "mysql" | "mariadb";
+
+  // ── Networking (required) ─────────────────────────────────────
+  vpcId: string;
+  subnetIds: string[];
+  ingressSourceSG?: string;
+  ingressCidr?: string;
+  port?: number;
+  publiclyAccessible?: boolean;
+
+  // ── Identity & auth (required) ────────────────────────────────
+  masterUsername?: string;
+  masterPassword: string;
+
+  // ── Engine version ──────────────────────────────────────────────
+  engineVersion?: string;
+  databaseName?: string;
+
+  // ── Instance sizing ───────────────────────────────────────────
+  instanceClass?: string;
+  allocatedStorage?: number;
+  storageType?: string;
+  maxAllocatedStorage?: number;
+
+  // ── High availability ─────────────────────────────────────────
+  multiAZ?: boolean;
+
+  // ── Encryption ────────────────────────────────────────────────
+  storageEncrypted?: boolean;
+  kmsKeyId?: string;
+
+  // ── Backup ────────────────────────────────────────────────────
+  backupRetentionPeriod?: number;
+  preferredBackupWindow?: string;
+  copyTagsToSnapshot?: boolean;
+
+  // ── Maintenance ───────────────────────────────────────────────
+  preferredMaintenanceWindow?: string;
+  autoMinorVersionUpgrade?: boolean;
+
+  // ── Monitoring ────────────────────────────────────────────────
+  enableCloudwatchLogs?: boolean;
+  enablePerformanceInsights?: boolean;
+  performanceInsightsRetentionPeriod?: number;
+
+  // ── Parameter group ───────────────────────────────────────────
+  parameterGroupFamily?: string;
+  parameters?: Record<string, string>;
+
+  // ── Protection ────────────────────────────────────────────────
+  deletionProtection?: boolean;
+}
+
+export const RdsInstance = Composite<RdsInstanceProps>((props) => {
+  const engine = props.engine ?? "postgres";
+  const defaults = ENGINE_DEFAULTS[engine];
+  const port = props.port ?? defaults.port;
+  const masterUsername = props.masterUsername ?? defaults.username;
+  const engineVersion = props.engineVersion ?? defaults.version;
+  const instanceClass = props.instanceClass ?? "db.t4g.micro";
+  const allocatedStorage = props.allocatedStorage ?? 20;
+  const storageType = props.storageType ?? "gp3";
+  const multiAZ = props.multiAZ ?? false;
+  const storageEncrypted = props.storageEncrypted ?? true;
+  const backupRetentionPeriod = props.backupRetentionPeriod ?? 7;
+  const copyTagsToSnapshot = props.copyTagsToSnapshot ?? true;
+  const autoMinorVersionUpgrade = props.autoMinorVersionUpgrade ?? true;
+  const publiclyAccessible = props.publiclyAccessible ?? false;
+  const deletionProtection = props.deletionProtection ?? false;
+
+  // DB Subnet Group
+  const subnetGroup = new RDSDBSubnetGroup({
+    DBSubnetGroupDescription: "Subnet group for RDS instance",
+    SubnetIds: props.subnetIds,
+  });
+
+  // Security Group
+  const ingressRules: InstanceType<typeof SecurityGroup_Ingress>[] = [];
+  if (props.ingressSourceSG) {
+    ingressRules.push(
+      new SecurityGroup_Ingress({
+        IpProtocol: "tcp",
+        FromPort: port,
+        ToPort: port,
+        SourceSecurityGroupId: props.ingressSourceSG,
+      }),
+    );
+  } else if (props.ingressCidr) {
+    ingressRules.push(
+      new SecurityGroup_Ingress({
+        IpProtocol: "tcp",
+        FromPort: port,
+        ToPort: port,
+        CidrIp: props.ingressCidr,
+      }),
+    );
+  }
+
+  const sg = new SecurityGroup({
+    GroupDescription: "Security group for RDS instance",
+    VpcId: props.vpcId,
+    SecurityGroupIngress: ingressRules.length > 0 ? ingressRules : undefined,
+  });
+
+  // Optional Parameter Group
+  let parameterGroup: InstanceType<typeof RDSDBParameterGroup> | undefined;
+  if (props.parameterGroupFamily) {
+    parameterGroup = new RDSDBParameterGroup({
+      Family: props.parameterGroupFamily,
+      Description: "Custom parameter group",
+      Parameters: props.parameters,
+    });
+  }
+
+  // DB Instance
+  const dbProps: Record<string, any> = {
+    Engine: engine,
+    EngineVersion: engineVersion,
+    DBInstanceClass: instanceClass,
+    MasterUsername: masterUsername,
+    MasterUserPassword: props.masterPassword,
+    AllocatedStorage: String(allocatedStorage),
+    StorageType: storageType,
+    DBSubnetGroupName: subnetGroup.Ref,
+    VPCSecurityGroups: [sg.GroupId],
+    Port: String(port),
+    PubliclyAccessible: publiclyAccessible,
+    MultiAZ: multiAZ,
+    StorageEncrypted: storageEncrypted,
+    BackupRetentionPeriod: backupRetentionPeriod,
+    CopyTagsToSnapshot: copyTagsToSnapshot,
+    AutoMinorVersionUpgrade: autoMinorVersionUpgrade,
+    DeletionProtection: deletionProtection,
+  };
+
+  if (props.databaseName) dbProps.DBName = props.databaseName;
+  if (props.kmsKeyId) dbProps.KmsKeyId = props.kmsKeyId;
+  if (props.maxAllocatedStorage) dbProps.MaxAllocatedStorage = props.maxAllocatedStorage;
+  if (props.preferredBackupWindow) dbProps.PreferredBackupWindow = props.preferredBackupWindow;
+  if (props.preferredMaintenanceWindow) dbProps.PreferredMaintenanceWindow = props.preferredMaintenanceWindow;
+  if (props.enableCloudwatchLogs) dbProps.EnableCloudwatchLogsExports = [defaults.logExport];
+  if (props.enablePerformanceInsights) {
+    dbProps.EnablePerformanceInsights = true;
+    if (props.performanceInsightsRetentionPeriod) {
+      dbProps.PerformanceInsightsRetentionPeriod = props.performanceInsightsRetentionPeriod;
+    }
+  }
+  if (parameterGroup) dbProps.DBParameterGroupName = parameterGroup.Ref;
+
+  const db = new DbInstance(dbProps);
+
+  const result: Record<string, any> = { subnetGroup, sg, db };
+  if (parameterGroup) result.parameterGroup = parameterGroup;
+
+  return result;
+}, "RdsInstance");

package/src/coverage.test.ts

@@ -0,0 +1,31 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const generatedDir = join(pkgDir, "src", "generated");
+const hasGenerated = existsSync(join(generatedDir, "lexicon-aws.json"));
+
+describe("coverage", () => {
+  test.skipIf(!hasGenerated)("computeCoverage function exists", async () => {
+    const { computeCoverage } = await import("./coverage");
+    expect(typeof computeCoverage).toBe("function");
+  });
+
+  test.skipIf(!hasGenerated)("overallPct function exists", async () => {
+    const { overallPct } = await import("./coverage");
+    expect(typeof overallPct).toBe("function");
+  });
+
+  test("handles missing generated files gracefully", async () => {
+    const { computeCoverage } = await import("./coverage");
+    if (!hasGenerated) {
+      try {
+        await computeCoverage(generatedDir);
+      } catch {
+        // Expected — no generated files
+      }
+    }
+  });
+});