@intentius/chant-lexicon-aws 0.0.2

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,175 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import { hardcodedRegionRule } from "./hardcoded-region";
+import { s3EncryptionRule } from "./s3-encryption";
+import { iamWildcardRule } from "./iam-wildcard";
+import type { LintContext } from "@intentius/chant/lint/rule";
+
+function createContext(code: string, fileName = "test.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(
+    fileName,
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  return {
+    sourceFile,
+    entities: [],
+    filePath: fileName,
+  };
+}
+
+describe("AWS Lint Rules", () => {
+  describe("WAW001: Hardcoded Region", () => {
+    test("detects hardcoded us-east-1", () => {
+      const context = createContext(`const region = "us-east-1";`);
+      const diagnostics = hardcodedRegionRule.check(context);
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("WAW001");
+      expect(diagnostics[0].message).toContain("us-east-1");
+    });
+
+    test("detects hardcoded eu-west-2", () => {
+      const context = createContext(`const region = "eu-west-2";`);
+      const diagnostics = hardcodedRegionRule.check(context);
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].message).toContain("eu-west-2");
+    });
+
+    test("detects hardcoded ap-southeast-1", () => {
+      const context = createContext(`const region = "ap-southeast-1";`);
+      const diagnostics = hardcodedRegionRule.check(context);
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].message).toContain("ap-southeast-1");
+    });
+
+    test("ignores non-region strings", () => {
+      const context = createContext(`const name = "my-bucket-name";`);
+      const diagnostics = hardcodedRegionRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("ignores AWS.Region reference", () => {
+      const context = createContext(`const region = AWS.Region;`);
+      const diagnostics = hardcodedRegionRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("has correct metadata", () => {
+      expect(hardcodedRegionRule.id).toBe("WAW001");
+      expect(hardcodedRegionRule.severity).toBe("warning");
+      expect(hardcodedRegionRule.category).toBe("security");
+    });
+  });
+
+  describe("WAW006: S3 Encryption", () => {
+    test("warns on Bucket without encryption", () => {
+      const context = createContext(`
+        const bucket = new Bucket({ bucketName: "my-bucket" });
+      `);
+      const diagnostics = s3EncryptionRule.check(context);
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("WAW006");
+      expect(diagnostics[0].message).toContain("encryption");
+    });
+
+    test("passes with bucketEncryption property", () => {
+      const context = createContext(`
+        const bucket = new Bucket({
+          bucketName: "my-bucket",
+          bucketEncryption: { serverSideEncryptionConfiguration: [] },
+        });
+      `);
+      const diagnostics = s3EncryptionRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("passes with encryption property", () => {
+      const context = createContext(`
+        const bucket = new Bucket({
+          bucketName: "my-bucket",
+          encryption: "AES256",
+        });
+      `);
+      const diagnostics = s3EncryptionRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("ignores non-Bucket constructors", () => {
+      const context = createContext(`
+        const fn = new Function({ functionName: "my-fn" });
+      `);
+      const diagnostics = s3EncryptionRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("has correct metadata", () => {
+      expect(s3EncryptionRule.id).toBe("WAW006");
+      expect(s3EncryptionRule.severity).toBe("warning");
+      expect(s3EncryptionRule.category).toBe("security");
+    });
+  });
+
+  describe("WAW009: IAM Wildcard", () => {
+    test("warns on Resource: '*'", () => {
+      const context = createContext(`
+        const policy = {
+          Statement: [{
+            Effect: "Allow",
+            Action: "s3:*",
+            Resource: "*",
+          }],
+        };
+      `);
+      const diagnostics = iamWildcardRule.check(context);
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0].ruleId).toBe("WAW009");
+      expect(diagnostics[0].message).toContain("wildcard");
+    });
+
+    test("warns on Resources array with '*'", () => {
+      const context = createContext(`
+        const policy = {
+          Statement: [{
+            Effect: "Allow",
+            Action: "s3:*",
+            Resources: ["*"],
+          }],
+        };
+      `);
+      const diagnostics = iamWildcardRule.check(context);
+      expect(diagnostics).toHaveLength(1);
+    });
+
+    test("passes with explicit ARN", () => {
+      const context = createContext(`
+        const policy = {
+          Statement: [{
+            Effect: "Allow",
+            Action: "s3:GetObject",
+            Resource: "arn:aws:s3:::my-bucket/*",
+          }],
+        };
+      `);
+      const diagnostics = iamWildcardRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("ignores unrelated properties", () => {
+      const context = createContext(`
+        const config = {
+          name: "*",
+          pattern: "*",
+        };
+      `);
+      const diagnostics = iamWildcardRule.check(context);
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test("has correct metadata", () => {
+      expect(iamWildcardRule.id).toBe("WAW009");
+      expect(iamWildcardRule.severity).toBe("warning");
+      expect(iamWildcardRule.category).toBe("security");
+    });
+  });
+});

package/src/lint/rules/s3-encryption.ts

@@ -0,0 +1,69 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * WAW006: S3 Bucket Encryption
+ *
+ * Detects S3 Bucket creation without encryption configuration.
+ * All S3 buckets should have server-side encryption enabled.
+ */
+export const s3EncryptionRule: LintRule = {
+  id: "WAW006",
+  severity: "warning",
+  category: "security",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for `new Bucket(...)` or `new aws.s3.Bucket(...)`
+      if (ts.isNewExpression(node)) {
+        const expression = node.expression;
+        let isBucket = false;
+
+        // Check for `new Bucket(...)`
+        if (ts.isIdentifier(expression) && expression.text === "Bucket") {
+          isBucket = true;
+        }
+        // Check for `new s3.Bucket(...)` or `new aws.s3.Bucket(...)`
+        else if (ts.isPropertyAccessExpression(expression)) {
+          if (expression.name.text === "Bucket") {
+            isBucket = true;
+          }
+        }
+
+        if (isBucket && node.arguments && node.arguments.length > 0) {
+          const props = node.arguments[0];
+          if (ts.isObjectLiteralExpression(props)) {
+            const hasEncryption = props.properties.some((prop) => {
+              if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                return prop.name.text === "bucketEncryption" ||
+                       prop.name.text === "encryption" ||
+                       prop.name.text === "serverSideEncryptionConfiguration";
+              }
+              return false;
+            });
+
+            if (!hasEncryption) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "WAW006",
+                severity: "warning",
+                message: "S3 Bucket created without encryption configuration. Enable server-side encryption.",
+              });
+            }
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "bun:test";
+import { awsCompletions } from "./completions";
+import type { CompletionContext } from "@intentius/chant/lsp/types";
+
+function makeCtx(overrides: Partial<CompletionContext>): CompletionContext {
+  return {
+    uri: "file:///test.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    wordAtCursor: "",
+    linePrefix: "",
+    ...overrides,
+  };
+}
+
+describe("awsCompletions", () => {
+  test("returns resource completions for `new ` prefix", () => {
+    const ctx = makeCtx({
+      linePrefix: "const b = new Bucket",
+      wordAtCursor: "Bucket",
+      content: "const b = new Bucket",
+      position: { line: 0, character: 20 },
+    });
+
+    const items = awsCompletions(ctx);
+    expect(items.length).toBeGreaterThan(0);
+
+    const bucketItem = items.find((i) => i.label === "Bucket");
+    expect(bucketItem).toBeDefined();
+    expect(bucketItem?.kind).toBe("resource");
+    expect(bucketItem?.detail).toContain("AWS::S3::Bucket");
+  });
+
+  test("filters resource completions by prefix", () => {
+    const ctx = makeCtx({
+      linePrefix: "const t = new Table",
+      wordAtCursor: "Table",
+      content: "const t = new Table",
+      position: { line: 0, character: 19 },
+    });
+
+    const items = awsCompletions(ctx);
+    // All items should start with "Table"
+    for (const item of items) {
+      expect(item.label.toLowerCase().startsWith("table")).toBe(true);
+    }
+  });
+
+  test("limits results to 50", () => {
+    const ctx = makeCtx({
+      linePrefix: "const x = new ",
+      wordAtCursor: "",
+      content: "const x = new ",
+      position: { line: 0, character: 14 },
+    });
+
+    const items = awsCompletions(ctx);
+    expect(items.length).toBeLessThanOrEqual(50);
+  });
+
+  test("returns empty for non-matching context", () => {
+    const ctx = makeCtx({
+      linePrefix: "const x = 42",
+      wordAtCursor: "42",
+      content: "const x = 42",
+      position: { line: 0, character: 13 },
+    });
+
+    const items = awsCompletions(ctx);
+    expect(items.length).toBe(0);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,18 @@
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-aws.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide AWS completions based on context.
+ */
+export function awsCompletions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "AWS CloudFormation resource");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "bun:test";
+import { awsHover } from "./hover";
+import type { HoverContext } from "@intentius/chant/lsp/types";
+
+function makeCtx(overrides: Partial<HoverContext>): HoverContext {
+  return {
+    uri: "file:///test.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    word: "",
+    lineText: "",
+    ...overrides,
+  };
+}
+
+describe("awsHover", () => {
+  test("returns hover info for Bucket", () => {
+    const ctx = makeCtx({ word: "Bucket" });
+    const info = awsHover(ctx);
+
+    expect(info).toBeDefined();
+    expect(info!.contents).toContain("Bucket");
+    expect(info!.contents).toContain("AWS::S3::Bucket");
+  });
+
+  test("shows attributes for resource types", () => {
+    const ctx = makeCtx({ word: "Bucket" });
+    const info = awsHover(ctx);
+
+    expect(info).toBeDefined();
+    expect(info!.contents).toContain("Attributes");
+  });
+
+  test("returns undefined for unknown word", () => {
+    const ctx = makeCtx({ word: "NotARealResource12345" });
+    const info = awsHover(ctx);
+    expect(info).toBeUndefined();
+  });
+
+  test("returns undefined for empty word", () => {
+    const ctx = makeCtx({ word: "" });
+    const info = awsHover(ctx);
+    expect(info).toBeUndefined();
+  });
+
+  test("returns info for Table resource", () => {
+    const ctx = makeCtx({ word: "Table" });
+    const info = awsHover(ctx);
+
+    expect(info).toBeDefined();
+    expect(info!.contents).toContain("AWS::DynamoDB::Table");
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,53 @@
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-aws.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide hover information for AWS resource types and properties.
+ */
+export function awsHover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  if (entry.kind !== "resource") return undefined;
+
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`CloudFormation type: \`${entry.resourceType}\``);
+
+  if (entry.attrs && Object.keys(entry.attrs).length > 0) {
+    lines.push("");
+    lines.push("**Attributes:**");
+    for (const [key, value] of Object.entries(entry.attrs)) {
+      lines.push(`- \`${key}\` → \`${value}\``);
+    }
+  }
+
+  if (entry.primaryIdentifier && entry.primaryIdentifier.length > 0) {
+    lines.push("");
+    lines.push(`**Primary identifier:** ${entry.primaryIdentifier.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  if (entry.createOnly && entry.createOnly.length > 0) {
+    lines.push("");
+    lines.push(`**Create-only:** ${entry.createOnly.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  if (entry.writeOnly && entry.writeOnly.length > 0) {
+    lines.push("");
+    lines.push(`**Write-only:** ${entry.writeOnly.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/nested-stack.test.ts

@@ -0,0 +1,83 @@
+import { describe, test, expect } from "bun:test";
+import { nestedStack, isNestedStackInstance, NestedStackOutputRef, NESTED_STACK_MARKER } from "./nested-stack";
+import { DECLARABLE_MARKER, isDeclarable } from "@intentius/chant/declarable";
+import { CHILD_PROJECT_MARKER, isChildProject } from "@intentius/chant/child-project";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+
+describe("nestedStack", () => {
+  test("creates a nested stack with correct markers", () => {
+    const stack = nestedStack("network", "/path/to/network");
+
+    expect(isNestedStackInstance(stack)).toBe(true);
+    expect(isChildProject(stack)).toBe(true);
+    expect(isDeclarable(stack)).toBe(true);
+    expect((stack as any)[NESTED_STACK_MARKER]).toBe(true);
+    expect((stack as any)[CHILD_PROJECT_MARKER]).toBe(true);
+    expect((stack as any)[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("has correct metadata", () => {
+    const stack = nestedStack("network", "/path/to/network");
+
+    expect(stack.lexicon).toBe("aws");
+    expect(stack.entityType).toBe("AWS::CloudFormation::Stack");
+    expect(stack.kind).toBe("resource");
+    expect(stack.logicalName).toBe("network");
+    expect(stack.projectPath).toBe("/path/to/network");
+  });
+
+  test("outputs proxy returns NestedStackOutputRef", () => {
+    const stack = nestedStack("network", "/path/to/network");
+
+    const ref = stack.outputs.vpcId;
+    expect(ref).toBeInstanceOf(NestedStackOutputRef);
+    expect((ref as NestedStackOutputRef).stackName).toBe("network");
+    expect((ref as NestedStackOutputRef).outputName).toBe("vpcId");
+  });
+
+  test("accepts options with parameters", () => {
+    const stack = nestedStack("network", "/path/to/network", {
+      parameters: { Environment: "prod" },
+    });
+
+    expect(stack.options).toEqual({ parameters: { Environment: "prod" } });
+  });
+
+  test("defaults options to empty object", () => {
+    const stack = nestedStack("network", "/path/to/network");
+    expect(stack.options).toEqual({});
+  });
+});
+
+describe("NestedStackOutputRef", () => {
+  test("stores stackName and outputName", () => {
+    const ref = new NestedStackOutputRef("network", "vpcId");
+    expect(ref.stackName).toBe("network");
+    expect(ref.outputName).toBe("vpcId");
+  });
+
+  test("has INTRINSIC_MARKER", () => {
+    const ref = new NestedStackOutputRef("network", "vpcId");
+    expect((ref as any)[INTRINSIC_MARKER]).toBe(true);
+  });
+
+  test("serializes to Fn::GetAtt", () => {
+    const ref = new NestedStackOutputRef("network", "vpcId");
+    expect(ref.toJSON()).toEqual({
+      "Fn::GetAtt": ["network", "Outputs.vpcId"],
+    });
+  });
+});
+
+describe("isNestedStackInstance", () => {
+  test("returns true for nested stack", () => {
+    const stack = nestedStack("test", "/path");
+    expect(isNestedStackInstance(stack)).toBe(true);
+  });
+
+  test("returns false for plain object", () => {
+    expect(isNestedStackInstance({})).toBe(false);
+    expect(isNestedStackInstance(null)).toBe(false);
+    expect(isNestedStackInstance("string")).toBe(false);
+  });
+});

package/src/nested-stack.ts

@@ -0,0 +1,125 @@
+/**
+ * AWS NestedStack — references a child project directory that builds
+ * to an independent CloudFormation template. The parent emits
+ * AWS::CloudFormation::Stack pointing at the child template.
+ *
+ * Cross-stack references are explicit: the child declares `stackOutput()`
+ * exports, and the parent reads them via `nestedStack().outputs.name`.
+ */
+
+import { CHILD_PROJECT_MARKER, type ChildProjectInstance } from "@intentius/chant/child-project";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+
+/**
+ * Marker symbol for nested stack identification.
+ */
+export const NESTED_STACK_MARKER = Symbol.for("chant.aws.nestedStack");
+
+/**
+ * Options for configuring a nested stack.
+ */
+export interface NestedStackOptions {
+  /** Explicit CloudFormation Parameters to pass to the child stack */
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * A reference to an output from a nested stack.
+ * Serializes to `{ "Fn::GetAtt": [stackLogicalName, "Outputs.OutputName"] }`.
+ */
+export class NestedStackOutputRef {
+  readonly [INTRINSIC_MARKER] = true as const;
+  readonly stackName: string;
+  readonly outputName: string;
+
+  constructor(stackName: string, outputName: string) {
+    this.stackName = stackName;
+    this.outputName = outputName;
+  }
+
+  toJSON(): { "Fn::GetAtt": [string, string] } {
+    return {
+      "Fn::GetAtt": [this.stackName, `Outputs.${this.outputName}`],
+    };
+  }
+}
+
+/**
+ * Type guard for NestedStackOutputRef.
+ */
+export function isNestedStackOutputRef(value: unknown): value is NestedStackOutputRef {
+  return value instanceof NestedStackOutputRef;
+}
+
+/**
+ * Extended ChildProjectInstance with AWS-specific marker.
+ */
+export interface NestedStackInstance extends ChildProjectInstance {
+  readonly [NESTED_STACK_MARKER]: true;
+}
+
+/**
+ * Type guard for NestedStackInstance.
+ */
+export function isNestedStackInstance(value: unknown): value is NestedStackInstance {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    NESTED_STACK_MARKER in value &&
+    (value as Record<symbol, unknown>)[NESTED_STACK_MARKER] === true
+  );
+}
+
+/**
+ * Create a nested stack that references a child project directory.
+ *
+ * The child directory must contain its own `_.ts` barrel and resource files.
+ * It can be built independently with `chant build`. Cross-stack outputs
+ * are declared in the child via `stackOutput()`.
+ *
+ * @param name - Logical name for the nested stack resource
+ * @param projectPath - Absolute path to the child project directory
+ * @param options - Optional parameters to pass to the child stack
+ * @returns A ChildProjectInstance with an `outputs` proxy for cross-stack refs
+ *
+ * @example
+ * ```ts
+ * const network = _.nestedStack("network", import.meta.dir + "/network", {
+ *   parameters: { Environment: "prod" },
+ * });
+ *
+ * export const handler = new _.Function({
+ *   vpcConfig: {
+ *     subnetIds: [network.outputs.subnetId],  // cross-stack ref
+ *   },
+ * });
+ * ```
+ */
+export function nestedStack(
+  name: string,
+  projectPath: string,
+  options?: NestedStackOptions,
+): NestedStackInstance {
+  const outputsProxy = new Proxy({} as Record<string, NestedStackOutputRef>, {
+    get(_, prop: string) {
+      if (typeof prop === "symbol") return undefined;
+      return new NestedStackOutputRef(name, prop);
+    },
+  });
+
+  const instance = {
+    [CHILD_PROJECT_MARKER]: true,
+    [DECLARABLE_MARKER]: true,
+    [NESTED_STACK_MARKER]: true,
+    lexicon: "aws",
+    entityType: "AWS::CloudFormation::Stack",
+    kind: "resource" as const,
+    projectPath,
+    logicalName: name,
+    outputs: outputsProxy,
+    options: options ?? {},
+  } as NestedStackInstance;
+
+  return instance;
+}