@intentius/chant-lexicon-aws 0.0.2

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, test } from "bun:test";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw010 } from "./waw010";
+import { waw011 } from "./waw011";
+import { cor020 } from "./cor020";
+import { findResourceRefs, parseCFTemplate } from "./cf-refs";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+// --- cf-refs utility tests ---
+
+describe("findResourceRefs", () => {
+  test("extracts Ref targets", () => {
+    const refs = findResourceRefs({ Ref: "MyBucket" });
+    expect(refs.has("MyBucket")).toBe(true);
+  });
+
+  test("extracts Fn::GetAtt array form", () => {
+    const refs = findResourceRefs({ "Fn::GetAtt": ["MyRole", "Arn"] });
+    expect(refs.has("MyRole")).toBe(true);
+  });
+
+  test("extracts Fn::GetAtt dot form", () => {
+    const refs = findResourceRefs({ "Fn::GetAtt": "MyRole.Arn" });
+    expect(refs.has("MyRole")).toBe(true);
+  });
+
+  test("skips pseudo-parameters", () => {
+    const refs = findResourceRefs({ Ref: "AWS::StackName" });
+    expect(refs.size).toBe(0);
+  });
+
+  test("recurses into nested structures", () => {
+    const refs = findResourceRefs({
+      "Fn::Join": ["-", [{ Ref: "A" }, { "Fn::GetAtt": ["B", "Arn"] }]],
+    });
+    expect(refs.has("A")).toBe(true);
+    expect(refs.has("B")).toBe(true);
+  });
+});
+
+describe("parseCFTemplate", () => {
+  test("parses valid JSON", () => {
+    const t = parseCFTemplate('{"Resources":{}}');
+    expect(t).toBeTruthy();
+    expect(t!.Resources).toEqual({});
+  });
+
+  test("returns null for invalid JSON", () => {
+    expect(parseCFTemplate("not json")).toBeNull();
+  });
+});
+
+// --- WAW010: Redundant DependsOn ---
+
+describe("WAW010: Redundant DependsOn", () => {
+  test("detects redundant DependsOn from Ref", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyFunction: {
+          Type: "AWS::Lambda::Function",
+          DependsOn: ["MyRole"],
+          Properties: {
+            Role: { "Fn::GetAtt": ["MyRole", "Arn"] },
+          },
+        },
+        MyRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {},
+        },
+      },
+    });
+
+    const diags = waw010.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW010");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("redundant DependsOn");
+    expect(diags[0].message).toContain("MyRole");
+  });
+
+  test("no diagnostic when DependsOn is not redundant", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyFunction: {
+          Type: "AWS::Lambda::Function",
+          DependsOn: ["MyTable"],
+          Properties: {
+            Role: { "Fn::GetAtt": ["MyRole", "Arn"] },
+          },
+        },
+        MyRole: { Type: "AWS::IAM::Role", Properties: {} },
+        MyTable: { Type: "AWS::DynamoDB::Table", Properties: {} },
+      },
+    });
+
+    const diags = waw010.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("handles string DependsOn (not array)", () => {
+    const ctx = makeCtx({
+      Resources: {
+        A: {
+          Type: "AWS::Lambda::Function",
+          DependsOn: "B",
+          Properties: { X: { Ref: "B" } },
+        },
+        B: { Type: "AWS::S3::Bucket", Properties: {} },
+      },
+    });
+
+    const diags = waw010.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+});
+
+// --- WAW011: Deprecated Lambda Runtime ---
+
+describe("WAW011: Deprecated Lambda Runtime", () => {
+  test("emits error for deprecated runtime", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyFunc: {
+          Type: "AWS::Lambda::Function",
+          Properties: { Runtime: "nodejs14.x" },
+        },
+      },
+    });
+
+    const diags = waw011.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW011");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("deprecated");
+    expect(diags[0].message).toContain("nodejs14.x");
+  });
+
+  test("emits warning for approaching-EOL runtime", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyFunc: {
+          Type: "AWS::Lambda::Function",
+          Properties: { Runtime: "nodejs18.x" },
+        },
+      },
+    });
+
+    const diags = waw011.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("approaching end-of-life");
+  });
+
+  test("no diagnostic for current runtime", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyFunc: {
+          Type: "AWS::Lambda::Function",
+          Properties: { Runtime: "nodejs22.x" },
+        },
+      },
+    });
+
+    const diags = waw011.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("skips non-Lambda resources", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { Runtime: "nodejs14.x" },
+        },
+      },
+    });
+
+    const diags = waw011.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// --- COR020: Circular Resource Dependencies ---
+
+describe("COR020: Circular Resource Dependencies", () => {
+  test("detects simple two-node cycle", () => {
+    const ctx = makeCtx({
+      Resources: {
+        A: {
+          Type: "AWS::Lambda::Function",
+          Properties: { X: { Ref: "B" } },
+        },
+        B: {
+          Type: "AWS::IAM::Role",
+          Properties: { Y: { Ref: "A" } },
+        },
+      },
+    });
+
+    const diags = cor020.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("COR020");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("Circular resource dependency");
+    // Should contain both nodes in the cycle
+    expect(diags[0].message).toContain("A");
+    expect(diags[0].message).toContain("B");
+  });
+
+  test("detects three-node cycle", () => {
+    const ctx = makeCtx({
+      Resources: {
+        A: {
+          Type: "AWS::Lambda::Function",
+          Properties: { X: { Ref: "B" } },
+        },
+        B: {
+          Type: "AWS::IAM::Role",
+          Properties: { Y: { Ref: "C" } },
+        },
+        C: {
+          Type: "AWS::S3::Bucket",
+          DependsOn: ["A"],
+          Properties: {},
+        },
+      },
+    });
+
+    const diags = cor020.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("A");
+    expect(diags[0].message).toContain("B");
+    expect(diags[0].message).toContain("C");
+  });
+
+  test("no diagnostic for acyclic graph", () => {
+    const ctx = makeCtx({
+      Resources: {
+        A: {
+          Type: "AWS::Lambda::Function",
+          Properties: { X: { Ref: "B" } },
+        },
+        B: {
+          Type: "AWS::IAM::Role",
+          Properties: { Y: { Ref: "C" } },
+        },
+        C: {
+          Type: "AWS::S3::Bucket",
+          Properties: {},
+        },
+      },
+    });
+
+    const diags = cor020.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("handles DependsOn-based cycles", () => {
+    const ctx = makeCtx({
+      Resources: {
+        A: {
+          Type: "AWS::Lambda::Function",
+          DependsOn: ["B"],
+          Properties: {},
+        },
+        B: {
+          Type: "AWS::IAM::Role",
+          DependsOn: ["A"],
+          Properties: {},
+        },
+      },
+    });
+
+    const diags = cor020.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+});

package/src/lint/post-synth/waw010.ts

@@ -0,0 +1,49 @@
+/**
+ * WAW010: Redundant DependsOn
+ *
+ * Detects DependsOn entries that are already implied by Ref or Fn::GetAtt
+ * references in the resource's Properties. CloudFormation automatically
+ * creates dependencies for these references, making explicit DependsOn redundant.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs } from "./cf-refs";
+
+export const waw010: PostSynthCheck = {
+  id: "WAW010",
+  description: "Redundant DependsOn — target is already referenced via Ref or Fn::GetAtt in Properties",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      const template = parseCFTemplate(output);
+      if (!template?.Resources) continue;
+
+      for (const [logicalId, resource] of Object.entries(template.Resources)) {
+        if (!resource.DependsOn) continue;
+
+        const dependsOn = Array.isArray(resource.DependsOn)
+          ? resource.DependsOn
+          : [resource.DependsOn];
+
+        // Find all refs in Properties
+        const propertyRefs = findResourceRefs(resource.Properties);
+
+        for (const target of dependsOn) {
+          if (propertyRefs.has(target)) {
+            diagnostics.push({
+              checkId: "WAW010",
+              severity: "warning",
+              message: `Resource "${logicalId}" has redundant DependsOn "${target}" — already referenced in Properties`,
+              entity: logicalId,
+              lexicon: "aws",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/waw011.ts

@@ -0,0 +1,49 @@
+/**
+ * WAW011: Deprecated Lambda Runtime
+ *
+ * Checks Lambda function resources for deprecated or approaching-EOL runtimes.
+ * Emits error for "deprecated" runtimes and warning for "approaching_eol".
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { Severity } from "@intentius/chant/lint/rule";
+import { parseCFTemplate } from "./cf-refs";
+import { lambdaRuntimeDeprecations } from "../../codegen/generate-lexicon";
+
+export const waw011: PostSynthCheck = {
+  id: "WAW011",
+  description: "Deprecated Lambda runtime — flags deprecated or approaching-EOL Lambda runtimes",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const deprecations = lambdaRuntimeDeprecations();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      const template = parseCFTemplate(output);
+      if (!template?.Resources) continue;
+
+      for (const [logicalId, resource] of Object.entries(template.Resources)) {
+        if (resource.Type !== "AWS::Lambda::Function") continue;
+
+        const runtime = resource.Properties?.Runtime;
+        if (typeof runtime !== "string") continue;
+
+        const status = deprecations[runtime];
+        if (!status) continue;
+
+        const severity: Severity = status === "deprecated" ? "error" : "warning";
+        const label = status === "deprecated" ? "deprecated" : "approaching end-of-life";
+
+        diagnostics.push({
+          checkId: "WAW011",
+          severity,
+          message: `Lambda "${logicalId}" uses ${label} runtime "${runtime}"`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/waw013.ts

@@ -0,0 +1,45 @@
+/**
+ * WAW013: Child project has no stackOutput() exports
+ *
+ * When a parent uses nestedStack() to reference a child project, the child
+ * must declare at least one stackOutput() — otherwise the parent can't
+ * reference any of its values.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isChildProject } from "@intentius/chant/child-project";
+import { isStackOutput } from "@intentius/chant/stack-output";
+
+export const waw013: PostSynthCheck = {
+  id: "WAW013",
+  description: "Child project has no stackOutput() exports — parent can't reference anything",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (isChildProject(entity) && entity.buildResult) {
+        // Check if the child has any StackOutput entities
+        let hasOutputs = false;
+        for (const [, childEntity] of entity.buildResult.entities) {
+          if (isStackOutput(childEntity)) {
+            hasOutputs = true;
+            break;
+          }
+        }
+
+        if (!hasOutputs) {
+          diagnostics.push({
+            checkId: "WAW013",
+            severity: "error",
+            message: `Nested stack "${name}" child project has no stackOutput() exports — parent can't reference any values`,
+            entity: name,
+            lexicon: "aws",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/waw014.ts

@@ -0,0 +1,50 @@
+/**
+ * WAW014: Nested stack outputs never referenced from parent
+ *
+ * Warns when a nestedStack() is declared but none of its outputs are
+ * referenced from the parent template. Could just be a separate build.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { isChildProject } from "@intentius/chant/child-project";
+
+export const waw014: PostSynthCheck = {
+  id: "WAW014",
+  description: "Nested stack outputs never referenced from parent — could just be a separate build",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Collect child project names
+    const childProjectNames = new Set<string>();
+    for (const [name, entity] of ctx.entities) {
+      if (isChildProject(entity)) {
+        childProjectNames.add(name);
+      }
+    }
+
+    if (childProjectNames.size === 0) return diagnostics;
+
+    // Parse the primary template to check for Fn::GetAtt on nested stacks
+    for (const [_lexicon, output] of ctx.outputs) {
+      const json = getPrimaryOutput(output);
+
+      for (const stackName of childProjectNames) {
+        // Check if any Fn::GetAtt references this stack's outputs
+        const hasRef = json.includes(`"Fn::GetAtt"`) && json.includes(`"${stackName}"`);
+        if (!hasRef) {
+          diagnostics.push({
+            checkId: "WAW014",
+            severity: "warning",
+            message: `Nested stack "${stackName}" outputs are never referenced — consider building it separately`,
+            entity: stackName,
+            lexicon: "aws",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/waw015.ts

@@ -0,0 +1,100 @@
+/**
+ * WAW015: Circular project references
+ *
+ * Detects when child projects form circular references through
+ * nestedStack() declarations. A → B → A would cause infinite recursion
+ * at build time.
+ *
+ * Note: The core build pipeline also detects this and emits a BuildError,
+ * but this lint check provides a clearer diagnostic message.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isChildProject } from "@intentius/chant/child-project";
+
+export const waw015: PostSynthCheck = {
+  id: "WAW015",
+  description: "Circular dependency between nested stacks would cause infinite build recursion",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // Build a dependency graph: stackName → set of child project paths
+    const stacks = new Map<string, string>();
+    for (const [name, entity] of ctx.entities) {
+      if (isChildProject(entity)) {
+        stacks.set(name, entity.projectPath);
+      }
+    }
+
+    if (stacks.size < 2) return diagnostics;
+
+    // Check for cycles by looking at child build results for nested ChildProjectInstances
+    const deps = new Map<string, Set<string>>();
+    for (const [name] of stacks) {
+      deps.set(name, new Set());
+    }
+
+    for (const [name, entity] of ctx.entities) {
+      if (isChildProject(entity) && entity.buildResult) {
+        for (const [, childEntity] of entity.buildResult.entities) {
+          if (isChildProject(childEntity)) {
+            // Check if the child references any of our known stacks
+            for (const [stackName, stackPath] of stacks) {
+              if (childEntity.projectPath === stackPath) {
+                deps.get(name)!.add(stackName);
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Detect cycles using DFS
+    const visited = new Set<string>();
+    const inPath = new Set<string>();
+
+    function dfs(node: string, path: string[]): string[] | null {
+      if (inPath.has(node)) {
+        const cycleStart = path.indexOf(node);
+        return path.slice(cycleStart);
+      }
+      if (visited.has(node)) return null;
+
+      visited.add(node);
+      inPath.add(node);
+      path.push(node);
+
+      for (const dep of deps.get(node) ?? []) {
+        const cycle = dfs(dep, path);
+        if (cycle) return cycle;
+      }
+
+      path.pop();
+      inPath.delete(node);
+      return null;
+    }
+
+    const reportedCycles = new Set<string>();
+    for (const [name] of stacks) {
+      if (!visited.has(name)) {
+        const cycle = dfs(name, []);
+        if (cycle) {
+          const cycleKey = [...cycle].sort().join(",");
+          if (!reportedCycles.has(cycleKey)) {
+            reportedCycles.add(cycleKey);
+            diagnostics.push({
+              checkId: "WAW015",
+              severity: "error",
+              message: `Circular dependency between nested stacks: ${cycle.join(" → ")} → ${cycle[0]}`,
+              entity: cycle[0],
+              lexicon: "aws",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/hardcoded-region.ts

@@ -0,0 +1,43 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * WAW001: Hardcoded AWS Region
+ *
+ * Detects hardcoded AWS region strings in code.
+ * Regions should use AWS.Region pseudo-parameter instead.
+ */
+export const hardcodedRegionRule: LintRule = {
+  id: "WAW001",
+  severity: "warning",
+  category: "security",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    // Common AWS region patterns
+    const regionPattern = /^(us|eu|ap|sa|ca|me|af|cn)-(north|south|east|west|central|northeast|southeast)-\d$/;
+
+    function visit(node: ts.Node): void {
+      if (ts.isStringLiteral(node)) {
+        const value = node.text;
+        if (regionPattern.test(value)) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "WAW001",
+            severity: "warning",
+            message: `Hardcoded region "${value}" detected. Use AWS.Region pseudo-parameter instead.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/iam-wildcard.ts

@@ -0,0 +1,66 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * WAW009: IAM Wildcard Resource
+ *
+ * Detects IAM policies with wildcard (*) resources.
+ * Policies should specify explicit resources for better security.
+ */
+export const iamWildcardRule: LintRule = {
+  id: "WAW009",
+  severity: "warning",
+  category: "security",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for Resource: "*" in object literals
+      if (ts.isPropertyAssignment(node)) {
+        const name = node.name;
+        if (ts.isIdentifier(name) || ts.isStringLiteral(name)) {
+          const propName = ts.isIdentifier(name) ? name.text : name.text;
+
+          // Check for Resource or Resources property
+          if (propName.toLowerCase() === "resource" || propName.toLowerCase() === "resources") {
+            // Check if value is "*"
+            if (ts.isStringLiteral(node.initializer) && node.initializer.text === "*") {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "WAW009",
+                severity: "warning",
+                message: "IAM policy uses wildcard (*) resource. Specify explicit resource ARNs for better security.",
+              });
+            }
+            // Check if array contains "*"
+            else if (ts.isArrayLiteralExpression(node.initializer)) {
+              for (const element of node.initializer.elements) {
+                if (ts.isStringLiteral(element) && element.text === "*") {
+                  const { line, character } = sourceFile.getLineAndCharacterOfPosition(element.getStart());
+                  diagnostics.push({
+                    file: sourceFile.fileName,
+                    line: line + 1,
+                    column: character + 1,
+                    ruleId: "WAW009",
+                    severity: "warning",
+                    message: "IAM policy uses wildcard (*) resource. Specify explicit resource ARNs for better security.",
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -0,0 +1,7 @@
+/**
+ * AWS-specific lint rules for chant projects
+ */
+
+export { hardcodedRegionRule } from "./hardcoded-region";
+export { s3EncryptionRule } from "./s3-encryption";
+export { iamWildcardRule } from "./iam-wildcard";