@intentius/chant-lexicon-aws 0.0.2

package/src/intrinsics.ts

@@ -0,0 +1,223 @@
+import { INTRINSIC_MARKER, resolveIntrinsicValue, type Intrinsic } from "@intentius/chant/intrinsic";
+import { buildInterpolatedString, defaultInterpolationSerializer } from "@intentius/chant/intrinsic-interpolation";
+
+/**
+ * Fn::Sub intrinsic function implementation
+ * Supports template string interpolation with AttrRefs, Declarables, and pseudo-parameters
+ */
+export class SubIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private templateParts: string[];
+  private values: unknown[];
+
+  constructor(templateParts: string[], values: unknown[]) {
+    this.templateParts = templateParts;
+    this.values = values;
+  }
+
+  toJSON(): { "Fn::Sub": string } {
+    const serialize = defaultInterpolationSerializer(
+      (name, attr) => `\${${name}.${attr}}`,
+      (ref) => `\${${ref}}`,
+    );
+    return { "Fn::Sub": buildInterpolatedString(this.templateParts, this.values, serialize) };
+  }
+}
+
+/**
+ * Tagged template function for creating Fn::Sub intrinsics
+ * Usage: Sub`${AWS.StackName}-bucket` or Sub`${bucket.arn}`
+ */
+export function Sub(
+  templateParts: TemplateStringsArray,
+  ...values: unknown[]
+): SubIntrinsic {
+  return new SubIntrinsic([...templateParts], values);
+}
+
+/**
+ * Ref intrinsic function
+ * References a parameter or resource by logical name
+ */
+export class RefIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  toJSON(): { Ref: string } {
+    return { Ref: this.name };
+  }
+}
+
+/**
+ * Create a Ref intrinsic
+ */
+export function Ref(name: string): RefIntrinsic {
+  return new RefIntrinsic(name);
+}
+
+/**
+ * Fn::GetAtt intrinsic function
+ * Gets an attribute from a resource
+ */
+export class GetAttIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private logicalName: string;
+  private attribute: string;
+
+  constructor(logicalName: string, attribute: string) {
+    this.logicalName = logicalName;
+    this.attribute = attribute;
+  }
+
+  toJSON(): { "Fn::GetAtt": [string, string] } {
+    return { "Fn::GetAtt": [this.logicalName, this.attribute] };
+  }
+}
+
+/**
+ * Create a GetAtt intrinsic
+ */
+export function GetAtt(logicalName: string, attribute: string): GetAttIntrinsic {
+  return new GetAttIntrinsic(logicalName, attribute);
+}
+
+/**
+ * Fn::If intrinsic function
+ * Conditional value based on a condition
+ */
+export class IfIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private conditionName: string;
+  private valueIfTrue: unknown;
+  private valueIfFalse: unknown;
+
+  constructor(conditionName: string, valueIfTrue: unknown, valueIfFalse: unknown) {
+    this.conditionName = conditionName;
+    this.valueIfTrue = valueIfTrue;
+    this.valueIfFalse = valueIfFalse;
+  }
+
+  toJSON(): { "Fn::If": [string, unknown, unknown] } {
+    return { "Fn::If": [this.conditionName, resolveIntrinsicValue(this.valueIfTrue), resolveIntrinsicValue(this.valueIfFalse)] };
+  }
+}
+
+
+/**
+ * Create an If intrinsic
+ */
+export function If(conditionName: string, valueIfTrue: unknown, valueIfFalse: unknown): IfIntrinsic {
+  return new IfIntrinsic(conditionName, valueIfTrue, valueIfFalse);
+}
+
+/**
+ * Fn::Join intrinsic function
+ * Joins values with a delimiter
+ */
+export class JoinIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private delimiter: string;
+  private values: unknown[];
+
+  constructor(delimiter: string, values: unknown[]) {
+    this.delimiter = delimiter;
+    this.values = values;
+  }
+
+  toJSON(): { "Fn::Join": [string, unknown[]] } {
+    return { "Fn::Join": [this.delimiter, this.values.map(resolveIntrinsicValue)] };
+  }
+}
+
+/**
+ * Create a Join intrinsic
+ */
+export function Join(delimiter: string, values: unknown[]): JoinIntrinsic {
+  return new JoinIntrinsic(delimiter, values);
+}
+
+/**
+ * Fn::Select intrinsic function
+ * Selects a value from a list by index
+ */
+export class SelectIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private index: number;
+  private values: unknown[];
+
+  constructor(index: number, values: unknown[]) {
+    this.index = index;
+    this.values = values;
+  }
+
+  toJSON(): { "Fn::Select": [string, unknown[]] } {
+    return { "Fn::Select": [String(this.index), this.values.map(resolveIntrinsicValue)] };
+  }
+}
+
+/**
+ * Create a Select intrinsic
+ */
+export function Select(index: number, values: unknown[]): SelectIntrinsic {
+  return new SelectIntrinsic(index, values);
+}
+
+/**
+ * Fn::Split intrinsic function
+ * Splits a string by delimiter
+ */
+export class SplitIntrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private delimiter: string;
+  private source: string | Intrinsic;
+
+  constructor(delimiter: string, source: string | Intrinsic) {
+    this.delimiter = delimiter;
+    this.source = source;
+  }
+
+  toJSON(): { "Fn::Split": [string, unknown] } {
+    const sourceValue = typeof this.source === "string"
+      ? this.source
+      : (this.source as Intrinsic & { toJSON(): unknown }).toJSON();
+    return { "Fn::Split": [this.delimiter, sourceValue] };
+  }
+}
+
+/**
+ * Create a Split intrinsic
+ */
+export function Split(delimiter: string, source: string | Intrinsic): SplitIntrinsic {
+  return new SplitIntrinsic(delimiter, source);
+}
+
+/**
+ * Fn::Base64 intrinsic function
+ * Encodes a string to Base64
+ */
+export class Base64Intrinsic implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private value: string | Intrinsic;
+
+  constructor(value: string | Intrinsic) {
+    this.value = value;
+  }
+
+  toJSON(): { "Fn::Base64": unknown } {
+    const innerValue = typeof this.value === "string"
+      ? this.value
+      : (this.value as Intrinsic & { toJSON(): unknown }).toJSON();
+    return { "Fn::Base64": innerValue };
+  }
+}
+
+/**
+ * Create a Base64 intrinsic
+ */
+export function Base64(value: string | Intrinsic): Base64Intrinsic {
+  return new Base64Intrinsic(value);
+}

package/src/lint/post-synth/cf-refs.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared utility for extracting CloudFormation resource references
+ * from template properties.
+ *
+ * Used by WAW010 (redundant DependsOn) and COR020 (circular deps).
+ */
+
+/**
+ * Parsed CloudFormation template structure.
+ */
+export interface CFTemplate {
+  AWSTemplateFormatVersion?: string;
+  Resources?: Record<string, CFResource>;
+  [key: string]: unknown;
+}
+
+export interface CFResource {
+  Type: string;
+  Properties?: Record<string, unknown>;
+  DependsOn?: string | string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Parse a serialized CloudFormation template from build output.
+ * Accepts either a raw string or a SerializerResult (extracts primary).
+ */
+export function parseCFTemplate(output: string | { primary: string }): CFTemplate | null {
+  const raw = typeof output === "string" ? output : output.primary;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null) {
+      return parsed as CFTemplate;
+    }
+  } catch {
+    // Not valid JSON
+  }
+  return null;
+}
+
+/**
+ * Recursively walk a CloudFormation property value and extract all logical IDs
+ * referenced via Ref and Fn::GetAtt.
+ *
+ * Skips pseudo-parameters (those starting with "AWS::").
+ */
+export function findResourceRefs(value: unknown): Set<string> {
+  const refs = new Set<string>();
+  walkValue(value, refs);
+  return refs;
+}
+
+function walkValue(value: unknown, refs: Set<string>): void {
+  if (value === null || value === undefined) return;
+  if (typeof value !== "object") return;
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      walkValue(item, refs);
+    }
+    return;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  // Check for Ref
+  if ("Ref" in obj && typeof obj.Ref === "string") {
+    if (!obj.Ref.startsWith("AWS::")) {
+      refs.add(obj.Ref);
+    }
+  }
+
+  // Check for Fn::GetAtt
+  if ("Fn::GetAtt" in obj) {
+    const getAtt = obj["Fn::GetAtt"];
+    if (Array.isArray(getAtt) && getAtt.length >= 1 && typeof getAtt[0] === "string") {
+      refs.add(getAtt[0]);
+    } else if (typeof getAtt === "string") {
+      // Dot-delimited form: "LogicalId.Attribute"
+      const logicalId = getAtt.split(".")[0];
+      if (logicalId) refs.add(logicalId);
+    }
+  }
+
+  // Recurse into all object values (including intrinsic function arguments)
+  for (const val of Object.values(obj)) {
+    if (typeof val === "object" && val !== null) {
+      walkValue(val, refs);
+    }
+  }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * COR020: Circular Resource Dependencies
+ *
+ * Builds a directed dependency graph from Ref, Fn::GetAtt, and DependsOn
+ * entries in the synthesized CloudFormation template. Detects cycles using
+ * DFS with three-color marking (white/gray/black).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { detectCycles } from "@intentius/chant/discovery/cycles";
+import { parseCFTemplate, findResourceRefs } from "./cf-refs";
+
+export const cor020: PostSynthCheck = {
+  id: "COR020",
+  description: "Circular resource dependency — detects cycles in the resource dependency graph",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      const template = parseCFTemplate(output);
+      if (!template?.Resources) continue;
+
+      const resourceIds = new Set(Object.keys(template.Resources));
+
+      // Build adjacency list: resource → set of resources it depends on
+      const graph = new Map<string, Set<string>>();
+
+      for (const [logicalId, resource] of Object.entries(template.Resources)) {
+        const deps = new Set<string>();
+
+        // Refs from Properties
+        const propertyRefs = findResourceRefs(resource.Properties);
+        for (const ref of propertyRefs) {
+          if (resourceIds.has(ref) && ref !== logicalId) {
+            deps.add(ref);
+          }
+        }
+
+        // Explicit DependsOn
+        if (resource.DependsOn) {
+          const dependsOn = Array.isArray(resource.DependsOn)
+            ? resource.DependsOn
+            : [resource.DependsOn];
+          for (const target of dependsOn) {
+            if (resourceIds.has(target) && target !== logicalId) {
+              deps.add(target);
+            }
+          }
+        }
+
+        graph.set(logicalId, deps);
+      }
+
+      // Detect cycles
+      const cycles = detectCycles(graph);
+      for (const cycle of cycles) {
+        // Add trailing node for display: "A -> B -> C -> A"
+        const chain = [...cycle, cycle[0]].join(" -> ");
+        diagnostics.push({
+          checkId: "COR020",
+          severity: "error",
+          message: `Circular resource dependency: ${chain}`,
+          entity: cycle[0],
+          lexicon: "aws",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { ext001 } from "./ext001";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("EXT001: Extension Constraint Violation", () => {
+  test("check metadata", () => {
+    expect(ext001.id).toBe("EXT001");
+    expect(ext001.description).toContain("constraint");
+  });
+
+  test("no diagnostics on empty template", () => {
+    const ctx = makeCtx({ Resources: {} });
+    const diags = ext001.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostics on unknown resource type", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyCustom: {
+          Type: "Custom::MyResource",
+          Properties: { Foo: "bar" },
+        },
+      },
+    });
+    const diags = ext001.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  // The following tests exercise the constraint validation logic directly
+  // by testing the check function. Whether diagnostics fire depends on
+  // the lexicon having constraints for the resource types used.
+  // Since we may not have the lexicon JSON in test environments,
+  // we verify the function at least runs without errors.
+  test("handles resource with no properties gracefully", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: {
+          Type: "AWS::S3::Bucket",
+        },
+      },
+    });
+    // Should not throw, diagnostics depend on lexicon data
+    const diags = ext001.check(ctx);
+    expect(Array.isArray(diags)).toBe(true);
+  });
+
+  test("handles invalid JSON output gracefully", () => {
+    const ctx: PostSynthContext = {
+      outputs: new Map([["aws", "not json"]]),
+      entities: new Map(),
+      buildResult: {
+        outputs: new Map([["aws", "not json"]]),
+        entities: new Map(),
+        warnings: [],
+        errors: [],
+        sourceFileCount: 0,
+      },
+    };
+    const diags = ext001.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,222 @@
+/**
+ * EXT001: Extension Constraint Violation
+ *
+ * Validates CloudFormation resource properties against cross-property
+ * constraints from cfn-lint extension schemas.
+ *
+ * Constraint types:
+ * - if_then: if condition properties match, then requirement must hold
+ * - dependent_excluded: if property A exists, property B must not
+ * - required_or: at least one of the listed properties must exist
+ * - required_xor: exactly one of the listed properties must exist
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, type CFResource } from "./cf-refs";
+
+interface ExtensionConstraint {
+  name: string;
+  type: "if_then" | "dependent_excluded" | "required_or" | "required_xor";
+  condition?: unknown;
+  requirement?: unknown;
+}
+
+interface LexiconEntry {
+  kind: string;
+  cfn?: string;
+  constraints?: ExtensionConstraint[];
+  [key: string]: unknown;
+}
+
+/**
+ * Load lexicon JSON to get constraints per resource type.
+ */
+function loadLexiconConstraints(): Map<string, ExtensionConstraint[]> {
+  const map = new Map<string, ExtensionConstraint[]>();
+  try {
+    const { readFileSync } = require("fs");
+    const { join, dirname } = require("path");
+    const { fileURLToPath } = require("url");
+
+    // Navigate from src/lint/post-synth/ up to the package root
+    const pkgDir = join(__dirname, "..", "..", "..");
+    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-aws.json");
+    const content = readFileSync(lexiconPath, "utf-8");
+    const data = JSON.parse(content) as Record<string, LexiconEntry>;
+
+    for (const [_name, entry] of Object.entries(data)) {
+      if (entry.kind === "resource" && entry.cfn && entry.constraints && entry.constraints.length > 0) {
+        map.set(entry.cfn, entry.constraints);
+      }
+    }
+  } catch {
+    // Lexicon not available — skip constraint checking
+  }
+  return map;
+}
+
+/**
+ * Check if a JSON schema "if" condition matches resource properties.
+ */
+function matchesCondition(condition: unknown, properties: Record<string, unknown>): boolean {
+  if (!condition || typeof condition !== "object") return false;
+  const cond = condition as Record<string, unknown>;
+
+  // { properties: { PropName: { const: value } } }
+  if (cond.properties && typeof cond.properties === "object") {
+    const condProps = cond.properties as Record<string, unknown>;
+    for (const [propName, schema] of Object.entries(condProps)) {
+      if (!schema || typeof schema !== "object") continue;
+      const s = schema as Record<string, unknown>;
+
+      if ("const" in s) {
+        if (properties[propName] !== s.const) return false;
+      }
+      if ("enum" in s && Array.isArray(s.enum)) {
+        if (!s.enum.includes(properties[propName])) return false;
+      }
+    }
+  }
+
+  // { required: ["PropName"] } — check the properties exist
+  if (Array.isArray(cond.required)) {
+    for (const req of cond.required) {
+      if (!(req in properties)) return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Check if a JSON schema "then" requirement holds for resource properties.
+ */
+function checkRequirement(requirement: unknown, properties: Record<string, unknown>): string | null {
+  if (!requirement || typeof requirement !== "object") return null;
+  const req = requirement as Record<string, unknown>;
+
+  // { required: ["PropName"] }
+  if (Array.isArray(req.required)) {
+    const missing = req.required.filter((r: string) => !(r in properties));
+    if (missing.length > 0) {
+      return `missing required properties: ${missing.join(", ")}`;
+    }
+  }
+
+  return null;
+}
+
+function validateResource(
+  logicalId: string,
+  resource: CFResource,
+  constraints: ExtensionConstraint[],
+): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+  const props = resource.Properties ?? {};
+
+  for (const constraint of constraints) {
+    switch (constraint.type) {
+      case "if_then": {
+        if (matchesCondition(constraint.condition, props)) {
+          const error = checkRequirement(constraint.requirement, props);
+          if (error) {
+            diagnostics.push({
+              checkId: "EXT001",
+              severity: "error",
+              message: `Resource "${logicalId}" (${resource.Type}): constraint "${constraint.name}" violated — ${error}`,
+              entity: logicalId,
+              lexicon: "aws",
+            });
+          }
+        }
+        break;
+      }
+
+      case "dependent_excluded": {
+        // { PropA: ["PropB", "PropC"] } — if PropA exists, PropB and PropC must not
+        const req = constraint.requirement as Record<string, string[]> | undefined;
+        if (req) {
+          for (const [propName, excluded] of Object.entries(req)) {
+            if (propName in props) {
+              const present = excluded.filter((e) => e in props);
+              if (present.length > 0) {
+                diagnostics.push({
+                  checkId: "EXT001",
+                  severity: "error",
+                  message: `Resource "${logicalId}" (${resource.Type}): "${propName}" excludes [${present.join(", ")}] but both are present`,
+                  entity: logicalId,
+                  lexicon: "aws",
+                });
+              }
+            }
+          }
+        }
+        break;
+      }
+
+      case "required_or": {
+        // ["PropA", "PropB"] — at least one must exist
+        const required = constraint.requirement as string[] | undefined;
+        if (required && Array.isArray(required)) {
+          const present = required.filter((r) => r in props);
+          if (present.length === 0) {
+            diagnostics.push({
+              checkId: "EXT001",
+              severity: "error",
+              message: `Resource "${logicalId}" (${resource.Type}): at least one of [${required.join(", ")}] must be specified`,
+              entity: logicalId,
+              lexicon: "aws",
+            });
+          }
+        }
+        break;
+      }
+
+      case "required_xor": {
+        // ["PropA", "PropB"] — exactly one must exist
+        const required = constraint.requirement as string[] | undefined;
+        if (required && Array.isArray(required)) {
+          const present = required.filter((r) => r in props);
+          if (present.length !== 1) {
+            diagnostics.push({
+              checkId: "EXT001",
+              severity: "error",
+              message: `Resource "${logicalId}" (${resource.Type}): exactly one of [${required.join(", ")}] must be specified (found ${present.length})`,
+              entity: logicalId,
+              lexicon: "aws",
+            });
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const ext001: PostSynthCheck = {
+  id: "EXT001",
+  description: "Extension constraint violation — cross-property validation from cfn-lint extension schemas",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const lexiconConstraints = loadLexiconConstraints();
+    if (lexiconConstraints.size === 0) return [];
+
+    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)) {
+        const constraints = lexiconConstraints.get(resource.Type);
+        if (!constraints) continue;
+
+        diagnostics.push(...validateResource(logicalId, resource, constraints));
+      }
+    }
+
+    return diagnostics;
+  },
+};