@intentius/chant-lexicon-aws 0.0.6 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "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.5",
+  "@intentius/chant": "0.0.9",
   "fflate": "^0.8.2",
   "js-yaml": "^4.1.0"
 },

package/src/actions/actions.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect } from "bun:test";
+import { S3Actions } from "./s3";
+import { LambdaActions } from "./lambda";
+import { DynamoDBActions } from "./dynamodb";
+import { SQSActions } from "./sqs";
+import { SNSActions } from "./sns";
+import { IAMActions } from "./iam";
+import { ECRActions } from "./ecr";
+import { LogsActions } from "./logs";
+import { ECSActions } from "./ecs";
+
+const allConstants = {
+  S3Actions,
+  LambdaActions,
+  DynamoDBActions,
+  SQSActions,
+  SNSActions,
+  IAMActions,
+  ECRActions,
+  LogsActions,
+  ECSActions,
+};
+
+describe("Action Constants", () => {
+  for (const [name, constant] of Object.entries(allConstants)) {
+    describe(name, () => {
+      test("every action string matches serviceName:actionName pattern", () => {
+        for (const [group, actions] of Object.entries(constant)) {
+          for (const action of actions) {
+            expect(action).toMatch(
+              /^[a-z][a-z0-9]*:[A-Z*][A-Za-z0-9*]*$/,
+            );
+          }
+        }
+      });
+
+      test("no duplicate actions within a group", () => {
+        for (const [group, actions] of Object.entries(constant)) {
+          const unique = new Set(actions);
+          expect(unique.size).toBe(
+            actions.length,
+          );
+        }
+      });
+    });
+  }
+
+  describe("S3Actions broad groups are supersets", () => {
+    test("ReadWrite contains all ReadOnly actions", () => {
+      for (const action of S3Actions.ReadOnly) {
+        expect(S3Actions.ReadWrite).toContain(action);
+      }
+    });
+
+    test("ReadWrite contains all WriteOnly actions", () => {
+      for (const action of S3Actions.WriteOnly) {
+        expect(S3Actions.ReadWrite).toContain(action);
+      }
+    });
+  });
+
+  describe("DynamoDBActions broad groups are supersets", () => {
+    test("ReadWrite contains all ReadOnly actions", () => {
+      for (const action of DynamoDBActions.ReadOnly) {
+        expect(DynamoDBActions.ReadWrite).toContain(action);
+      }
+    });
+
+    test("ReadWrite contains all WriteOnly actions", () => {
+      for (const action of DynamoDBActions.WriteOnly) {
+        expect(DynamoDBActions.ReadWrite).toContain(action);
+      }
+    });
+  });
+});

package/src/actions/dynamodb.ts

@@ -0,0 +1,36 @@
+export const DynamoDBActions = {
+  // Broad groups
+  ReadOnly: [
+    "dynamodb:GetItem",
+    "dynamodb:BatchGetItem",
+    "dynamodb:Query",
+    "dynamodb:Scan",
+    "dynamodb:DescribeTable",
+    "dynamodb:ConditionCheckItem",
+  ],
+  WriteOnly: [
+    "dynamodb:PutItem",
+    "dynamodb:UpdateItem",
+    "dynamodb:DeleteItem",
+    "dynamodb:BatchWriteItem",
+  ],
+  ReadWrite: [
+    "dynamodb:GetItem",
+    "dynamodb:BatchGetItem",
+    "dynamodb:Query",
+    "dynamodb:Scan",
+    "dynamodb:DescribeTable",
+    "dynamodb:ConditionCheckItem",
+    "dynamodb:PutItem",
+    "dynamodb:UpdateItem",
+    "dynamodb:DeleteItem",
+    "dynamodb:BatchWriteItem",
+  ],
+  Full: ["dynamodb:*"],
+
+  // Operation-specific
+  GetItem: ["dynamodb:GetItem", "dynamodb:BatchGetItem"],
+  PutItem: ["dynamodb:PutItem", "dynamodb:BatchWriteItem"],
+  Query: ["dynamodb:Query"],
+  Scan: ["dynamodb:Scan"],
+} as const;

package/src/actions/ecr.ts

@@ -0,0 +1,9 @@
+export const ECRActions = {
+  Pull: [
+    "ecr:GetAuthorizationToken",
+    "ecr:BatchCheckLayerAvailability",
+    "ecr:GetDownloadUrlForLayer",
+    "ecr:BatchGetImage",
+  ],
+  Full: ["ecr:*"],
+} as const;

package/src/actions/ecs.ts

@@ -0,0 +1,5 @@
+export const ECSActions = {
+  RunTask: ["ecs:RunTask", "ecs:StopTask", "ecs:DescribeTasks"],
+  Service: ["ecs:CreateService", "ecs:UpdateService", "ecs:DeleteService", "ecs:DescribeServices"],
+  Full: ["ecs:*"],
+} as const;

package/src/actions/iam.ts

@@ -0,0 +1,3 @@
+export const IAMActions = {
+  PassRole: ["iam:PassRole"],
+} as const;

package/src/actions/index.ts

@@ -0,0 +1,9 @@
+export { S3Actions } from "./s3";
+export { LambdaActions } from "./lambda";
+export { DynamoDBActions } from "./dynamodb";
+export { SQSActions } from "./sqs";
+export { SNSActions } from "./sns";
+export { IAMActions } from "./iam";
+export { ECRActions } from "./ecr";
+export { LogsActions } from "./logs";
+export { ECSActions } from "./ecs";

package/src/actions/lambda.ts

@@ -0,0 +1,11 @@
+export const LambdaActions = {
+  Invoke: ["lambda:InvokeFunction", "lambda:InvokeAsync"],
+  ReadOnly: [
+    "lambda:GetFunction",
+    "lambda:GetFunctionConfiguration",
+    "lambda:GetPolicy",
+    "lambda:ListVersionsByFunction",
+    "lambda:ListAliases",
+  ],
+  Full: ["lambda:*"],
+} as const;

package/src/actions/logs.ts

@@ -0,0 +1,4 @@
+export const LogsActions = {
+  Write: ["logs:CreateLogStream", "logs:PutLogEvents"],
+  Full: ["logs:*"],
+} as const;

package/src/actions/s3.ts

@@ -0,0 +1,34 @@
+export const S3Actions = {
+  // Broad groups (from AWS managed policies)
+  ReadOnly: [
+    "s3:GetObject",
+    "s3:GetObjectVersion",
+    "s3:GetBucketLocation",
+    "s3:ListBucket",
+    "s3:ListBucketVersions",
+  ],
+  WriteOnly: [
+    "s3:PutObject",
+    "s3:DeleteObject",
+    "s3:PutObjectAcl",
+    "s3:AbortMultipartUpload",
+  ],
+  ReadWrite: [
+    "s3:GetObject",
+    "s3:GetObjectVersion",
+    "s3:GetBucketLocation",
+    "s3:ListBucket",
+    "s3:ListBucketVersions",
+    "s3:PutObject",
+    "s3:DeleteObject",
+    "s3:PutObjectAcl",
+    "s3:AbortMultipartUpload",
+  ],
+  Full: ["s3:*"],
+
+  // Operation-specific
+  GetObject: ["s3:GetObject", "s3:GetObjectVersion"],
+  PutObject: ["s3:PutObject", "s3:AbortMultipartUpload"],
+  DeleteObject: ["s3:DeleteObject", "s3:DeleteObjectVersion"],
+  ListObjects: ["s3:ListBucket", "s3:ListBucketVersions"],
+} as const;

package/src/actions/sns.ts

@@ -0,0 +1,5 @@
+export const SNSActions = {
+  Publish: ["sns:Publish"],
+  Subscribe: ["sns:Subscribe", "sns:Unsubscribe"],
+  Full: ["sns:*"],
+} as const;

package/src/actions/sqs.ts

@@ -0,0 +1,15 @@
+export const SQSActions = {
+  SendMessage: [
+    "sqs:SendMessage",
+    "sqs:GetQueueUrl",
+    "sqs:GetQueueAttributes",
+  ],
+  ReceiveMessage: [
+    "sqs:ReceiveMessage",
+    "sqs:DeleteMessage",
+    "sqs:ChangeMessageVisibility",
+    "sqs:GetQueueUrl",
+    "sqs:GetQueueAttributes",
+  ],
+  Full: ["sqs:*"],
+} as const;

package/src/codegen/__snapshots__/snapshot.test.ts.snap

@@ -3,7 +3,7 @@
 exports[`snapshot tests Bucket lexicon entry 1`] = `
 {
   "attrs": {
-    "arn": "Arn",
+    "Arn": "Arn",
   },
   "createOnly": [
     "BucketName",
@@ -27,7 +27,7 @@ exports[`snapshot tests Bucket lexicon entry 1`] = `
 exports[`snapshot tests Function lexicon entry 1`] = `
 {
   "attrs": {
-    "arn": "Arn",
+    "Arn": "Arn",
   },
   "kind": "resource",
   "lexicon": "aws",
@@ -79,8 +79,8 @@ exports[`snapshot tests Function lexicon entry 1`] = `
 exports[`snapshot tests Role lexicon entry 1`] = `
 {
   "attrs": {
-    "arn": "Arn",
-    "roleId": "RoleId",
+    "Arn": "Arn",
+    "RoleId": "RoleId",
   },
   "kind": "resource",
   "lexicon": "aws",
@@ -160,17 +160,17 @@ exports[`snapshot tests Bucket .d.ts class declaration 1`] = `
 "export declare class Bucket {
   constructor(props: {
     /** A name for the bucket. */
-    bucketName: string;
+    BucketName: string;
     /** The Amazon Resource Name (ARN) of the bucket. */
-    arn?: string;
+    Arn?: string;
     /** Specifies default encryption for a bucket. */
-    bucketEncryption?: Bucket_BucketEncryption;
+    BucketEncryption?: Bucket_BucketEncryption;
     /** An arbitrary set of tags (key-value pairs) for this S3 bucket. */
-    tags?: Bucket_Tag[];
+    Tags?: Bucket_Tag[];
     /** Enables multiple versions of all objects in this bucket. */
-    versioningConfiguration?: Bucket_VersioningConfiguration;
-  });
-  readonly arn: string;
+    VersioningConfiguration?: Bucket_VersioningConfiguration;
+  }, attributes?: CFResourceAttributes);
+  readonly Arn: string;
 }"
 `;
 
@@ -178,20 +178,20 @@ exports[`snapshot tests Function .d.ts class declaration 1`] = `
 "export declare class Function {
   constructor(props: {
     /** The code for the function. */
-    code: Function_Code;
+    Code: Function_Code;
     /** The ARN of the function's execution role. */
-    role: string;
+    Role: string;
     /** The ARN of the function. */
-    arn?: string;
+    Arn?: string;
     /** The name of the Lambda function. */
-    functionName?: string;
+    FunctionName?: string;
     /** The name of the method within your code that Lambda calls to run your function. */
-    handler?: string;
+    Handler?: string;
     /** The amount of memory available to the function at runtime. */
-    memorySize?: number;
+    MemorySize?: number;
     /** The identifier of the function's runtime. */
-    runtime?: "java17" | "java21" | "nodejs18.x" | "nodejs20.x" | "python3.11" | "python3.12";
-  });
-  readonly arn: string;
+    Runtime?: "java17" | "java21" | "nodejs18.x" | "nodejs20.x" | "python3.11" | "python3.12";
+  }, attributes?: CFResourceAttributes);
+  readonly Arn: string;
 }"
 `;

package/src/codegen/docs-links.test.ts

@@ -0,0 +1,143 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, basename } from "path";
+
+const docsDir = join(import.meta.dir, "..", "..", "docs", "src", "content", "docs");
+const docsSource = join(import.meta.dir, "docs.ts");
+const docsExist = existsSync(docsDir);
+
+/**
+ * Collect all page slugs from the generated docs directory.
+ */
+function getPageSlugs(): Set<string> {
+  if (!docsExist) return new Set();
+  const slugs = new Set<string>();
+  for (const file of readdirSync(docsDir)) {
+    if (file.endsWith(".mdx")) {
+      slugs.add(basename(file, ".mdx"));
+    }
+  }
+  return slugs;
+}
+
+/**
+ * Extract markdown links: [text](href)
+ */
+function extractMarkdownLinks(content: string): Array<{ text: string; href: string; line: number }> {
+  const links: Array<{ text: string; href: string; line: number }> = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let match;
+    while ((match = regex.exec(lines[i])) !== null) {
+      const href = match[2];
+      if (href.startsWith("http://") || href.startsWith("https://")) continue;
+      if (href.startsWith("#")) continue;
+      links.push({ text: match[1], href, line: i + 1 });
+    }
+  }
+  return links;
+}
+
+/**
+ * Check if a relative link target exists as a page slug.
+ */
+function resolveTarget(href: string, slugs: Set<string>): string | null {
+  const pathPart = href.split("#")[0].replace(/\/$/, "");
+  if (!pathPart) return null;
+
+  let target: string | undefined;
+  if (pathPart.startsWith("./")) target = pathPart.slice(2);
+  else if (pathPart.startsWith("../")) target = pathPart.slice(3);
+  else if (pathPart.startsWith("/chant/lexicons/aws/")) {
+    target = pathPart.replace("/chant/lexicons/aws/", "").replace(/\/$/, "") || "index";
+  } else if (!pathPart.includes("/") && !pathPart.startsWith(".")) {
+    target = pathPart;
+  }
+
+  if (target === undefined) return null;
+  return slugs.has(target) ? null : `target page "${target}" does not exist`;
+}
+
+describe("docs internal links", () => {
+  const slugs = getPageSlugs();
+
+  test("page slugs are discovered", () => {
+    if (!docsExist) return; // generated docs not present (e.g. CI)
+    expect(slugs.size).toBeGreaterThan(5);
+    expect(slugs.has("composites")).toBe(true);
+    expect(slugs.has("nested-stacks")).toBe(true);
+    expect(slugs.has("index")).toBe(true);
+  });
+
+  // Validate generated MDX files (skip if docs not generated)
+  for (const file of (docsExist ? readdirSync(docsDir) : [])) {
+    if (!file.endsWith(".mdx")) continue;
+    const slug = basename(file, ".mdx");
+
+    test(`${slug}.mdx — internal links resolve to existing pages`, () => {
+      const content = readFileSync(join(docsDir, file), "utf-8");
+      const links = extractMarkdownLinks(content);
+      const errors: string[] = [];
+      for (const link of links) {
+        const error = resolveTarget(link.href, slugs);
+        if (error) errors.push(`line ${link.line}: [${link.text}](${link.href}) — ${error}`);
+      }
+      if (errors.length > 0) {
+        throw new Error(`Broken links in ${file}:\n${errors.join("\n")}`);
+      }
+    });
+
+    test(`${slug}.mdx — non-index pages use ../ not ./ for cross-page links`, () => {
+      if (slug === "index") return;
+      const content = readFileSync(join(docsDir, file), "utf-8");
+      const links = extractMarkdownLinks(content);
+      const errors: string[] = [];
+      for (const link of links) {
+        const pathPart = link.href.split("#")[0];
+        if (pathPart.startsWith("./")) {
+          const target = pathPart.slice(2).replace(/\/$/, "");
+          if (slugs.has(target)) {
+            errors.push(`line ${link.line}: [${link.text}](${link.href}) — use "../${target}/" instead`);
+          }
+        }
+      }
+      if (errors.length > 0) {
+        throw new Error(`Broken ./ links in non-index page ${file}:\n${errors.join("\n")}`);
+      }
+    });
+  }
+
+  // Validate source docs.ts — catches broken links before regeneration
+  test("docs.ts source — cross-page links use ../ not ./", () => {
+    if (!docsExist) return; // needs generated slugs for validation
+    const content = readFileSync(docsSource, "utf-8");
+    const links = extractMarkdownLinks(content);
+    const errors: string[] = [];
+    for (const link of links) {
+      const pathPart = link.href.split("#")[0];
+      // Links in docs.ts extraPages are rendered on non-index pages,
+      // so they must use ../ to navigate to sibling pages
+      if (pathPart.startsWith("./") && slugs.has(pathPart.slice(2).replace(/\/$/, ""))) {
+        errors.push(`line ${link.line}: [${link.text}](${link.href}) — use "../" prefix for cross-page links`);
+      }
+    }
+    if (errors.length > 0) {
+      throw new Error(`docs.ts has ./ links that will break on non-index pages:\n${errors.join("\n")}`);
+    }
+  });
+
+  test("docs.ts source — link targets exist as pages", () => {
+    if (!docsExist) return; // needs generated slugs for validation
+    const content = readFileSync(docsSource, "utf-8");
+    const links = extractMarkdownLinks(content);
+    const errors: string[] = [];
+    for (const link of links) {
+      const error = resolveTarget(link.href, slugs);
+      if (error) errors.push(`line ${link.line}: [${link.text}](${link.href}) — ${error}`);
+    }
+    if (errors.length > 0) {
+      throw new Error(`docs.ts has links to non-existent pages:\n${errors.join("\n")}`);
+    }
+  });
+});