@intentius/chant-lexicon-aws 0.49.0 → 0.51.0

package/src/disruption.ts

@@ -0,0 +1,154 @@
+/**
+ * Replacement semantics for a pending update (#1665).
+ *
+ * CloudFormation already knows this and says so in the Registry schema:
+ * `createOnlyProperties` is the type's complete list of properties that cannot
+ * be updated without building a new resource, and `replacementStrategy` says
+ * whether the new one is created before the old is removed or after. The
+ * codegen compiles both into `lexicon-aws.json` alongside the types, which is
+ * why this is a lookup rather than a rule anyone maintains by hand.
+ *
+ * `conditionalCreateOnlyProperties` is the interesting case: the schema is
+ * saying "depends on the value", which is not an answer, so it degrades to
+ * `unknown` with the property named. That is the whole point of the contract
+ * having an `unknown` — a maybe reported as `in-place` is worse than no
+ * report.
+ *
+ * `rolling` is not produced here. Nothing in the Registry schema expresses a
+ * workload roll; that verdict belongs to a lexicon whose spec does.
+ */
+import { createRequire } from "module";
+import type { DisruptionQuery, DisruptionVerdict } from "@intentius/chant/lexicon";
+
+const require = createRequire(import.meta.url);
+
+/** The slice of a `lexicon-aws.json` entry that carries replacement semantics. */
+export interface DisruptionSpec {
+  resourceType: string;
+  kind: string;
+  /** Read-only attributes (TS key → CF attr name). An output changing is a symptom, never a cause. */
+  attrs?: Record<string, string>;
+  createOnly?: string[];
+  conditionalCreateOnly?: string[];
+  replacementStrategy?: "delete_then_create" | "create_then_delete";
+}
+
+/**
+ * Classify one pending update against the type's compiled schema. Pure — the
+ * spec table is passed in, so this is testable without generated artifacts.
+ */
+export function classifyAwsChange(
+  query: DisruptionQuery,
+  specs: Map<string, DisruptionSpec>,
+): DisruptionVerdict {
+  const spec = query.type ? specs.get(query.type) : undefined;
+  if (!spec || spec.kind !== "resource") {
+    return {
+      disruption: "unknown",
+      detail: query.type
+        ? `no CloudFormation registry schema on record for ${query.type}`
+        : "the observation reported no resource type",
+    };
+  }
+
+  const readOnly = readOnlyNames(spec);
+  const considered: Array<{ path: string; property: string }> = [];
+  for (const delta of query.deltas) {
+    const property = propertyName(delta.path);
+    if (!property || readOnly.has(property)) continue;
+    considered.push({ path: delta.path, property });
+  }
+
+  const createOnly = new Set(spec.createOnly?.map(headSegment));
+  const forced = considered.filter((c) => createOnly.has(c.property));
+  if (forced.length > 0) {
+    const names = [...new Set(forced.map((c) => c.property))];
+    const destroys = spec.replacementStrategy === "delete_then_create";
+    return {
+      disruption: destroys ? "destroy" : "replace",
+      because: forced.map((c) => c.path),
+      detail: destroys
+        ? `${names.join(", ")} is create-only and ${spec.resourceType} replaces by deleting first — the resource is gone before the new one exists`
+        : `${names.join(", ")} is create-only — CloudFormation builds a new ${spec.resourceType} and removes the old one`,
+    };
+  }
+
+  const conditional = new Set(spec.conditionalCreateOnly?.map(headSegment));
+  const maybe = considered.filter((c) => conditional.has(c.property));
+  if (maybe.length > 0) {
+    const names = [...new Set(maybe.map((c) => c.property))];
+    return {
+      disruption: "unknown",
+      because: maybe.map((c) => c.path),
+      detail: `the schema marks ${names.join(", ")} conditionally create-only — whether this replaces depends on the value, and the schema does not say which way`,
+    };
+  }
+
+  if (considered.length === 0) {
+    return {
+      disruption: "in-place",
+      detail: "no configured property differs — only status, identity, or read-only attributes changed",
+    };
+  }
+
+  return {
+    disruption: "in-place",
+    detail: `no create-only property of ${spec.resourceType} changed`,
+  };
+}
+
+/**
+ * `LexiconPlugin.classifyDisruption` for aws. Loads the compiled registry once
+ * and answers every query from it. A registry that cannot be read leaves every
+ * change `unknown` — the honest answer, and the one the contract requires.
+ */
+export function awsDisruption(options: {
+  environment: string;
+  changes: DisruptionQuery[];
+}): Record<string, DisruptionVerdict> {
+  const specs = registryByType();
+  const out: Record<string, DisruptionVerdict> = {};
+  for (const change of options.changes) {
+    out[change.name] = classifyAwsChange(change, specs);
+  }
+  return out;
+}
+
+let cached: Map<string, DisruptionSpec> | undefined;
+
+function registryByType(): Map<string, DisruptionSpec> {
+  if (cached) return cached;
+  try {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, DisruptionSpec>;
+    cached = new Map(Object.values(manifest).map((e) => [e.resourceType, e]));
+  } catch {
+    cached = new Map();
+  }
+  return cached;
+}
+
+/** Every read-only attribute name the schema declares, top segment only. */
+function readOnlyNames(spec: DisruptionSpec): Set<string> {
+  const names = new Set<string>();
+  for (const attr of Object.values(spec.attrs ?? {})) names.add(attr.split(".")[0]);
+  return names;
+}
+
+/**
+ * The property a core delta path names, or undefined when the path is not
+ * about a property at all. Core's own observation fields (`status`,
+ * `physicalId`, `lastUpdated`) sit at the root of the change and say nothing
+ * about configuration; only what is under `attributes.` was read off the
+ * resource.
+ */
+function propertyName(path: string): string | undefined {
+  const prefix = "attributes.";
+  if (!path.startsWith(prefix)) return undefined;
+  const rest = path.slice(prefix.length);
+  return rest ? headSegment(rest) : undefined;
+}
+
+/** The first segment of a JSON-pointer-ish property path (`Config/Engine` → `Config`). */
+function headSegment(path: string): string {
+  return path.split(/[/.]/)[0];
+}

package/src/generated/lexicon-aws.json

@@ -6222,6 +6222,9 @@
     "deprecatedProperties": [
       "DeleteStorageConnectors"
     ],
+    "inferredDeprecations": [
+      "DeleteStorageConnectors"
+    ],
     "tagging": {
       "taggable": true,
       "tagOnCreate": true,
@@ -11669,6 +11672,9 @@
     "deprecatedProperties": [
       "AccessControl"
     ],
+    "inferredDeprecations": [
+      "AccessControl"
+    ],
     "tagging": {
       "taggable": true,
       "tagOnCreate": true,
@@ -14989,6 +14995,9 @@
     "deprecatedProperties": [
       "ComputeModel"
     ],
+    "inferredDeprecations": [
+      "ComputeModel"
+    ],
     "replacementStrategy": "delete_then_create",
     "tagging": {
       "taggable": true,
@@ -15385,6 +15394,9 @@
     "deprecatedProperties": [
       "ComputeModel"
     ],
+    "inferredDeprecations": [
+      "ComputeModel"
+    ],
     "conditionalCreateOnly": [
       "DbNodes"
     ],
@@ -17085,6 +17097,9 @@
     "deprecatedProperties": [
       "Deprecated"
     ],
+    "inferredDeprecations": [
+      "Deprecated"
+    ],
     "tagging": {
       "taggable": true,
       "tagOnCreate": true,
@@ -29032,6 +29047,9 @@
       "TdeCredentialPassword",
       "DBSecurityGroups"
     ],
+    "inferredDeprecations": [
+      "DBSecurityGroups"
+    ],
     "conditionalCreateOnly": [
       "AutoMinorVersionUpgrade",
       "AvailabilityZone",
@@ -33246,6 +33264,9 @@
     "deprecatedProperties": [
       "ImageScanningConfiguration"
     ],
+    "inferredDeprecations": [
+      "ImageScanningConfiguration"
+    ],
     "tagging": {
       "taggable": true,
       "tagOnCreate": true,
@@ -41749,6 +41770,9 @@
     "deprecatedProperties": [
       "Runtime"
     ],
+    "inferredDeprecations": [
+      "Runtime"
+    ],
     "conditionalCreateOnly": [
       "DurableConfig"
     ],
@@ -49621,6 +49645,10 @@
       "ElasticGpuSpecifications",
       "ElasticInferenceAccelerators"
     ],
+    "inferredDeprecations": [
+      "ElasticGpuSpecifications",
+      "ElasticInferenceAccelerators"
+    ],
     "conditionalCreateOnly": [
       "AdditionalInfo",
       "Affinity",
@@ -64878,6 +64906,9 @@
     "deprecatedProperties": [
       "DBPort"
     ],
+    "inferredDeprecations": [
+      "DBPort"
+    ],
     "tagging": {
       "taggable": true,
       "tagOnCreate": true,
@@ -100101,6 +100132,9 @@
     "deprecatedProperties": [
       "State"
     ],
+    "inferredDeprecations": [
+      "State"
+    ],
     "tagging": {
       "taggable": true,
       "tagOnCreate": true,

package/src/index.ts

@@ -22,6 +22,14 @@ export type { AwsEffectReceiptDeclaration } from "./effect-receipt-row";
 export { awsReceiptStore, observeReceiptRows, ssmGetParameter, ssmPutParameter } from "./receipt-store";
 export type { AwsReceiptStoreOptions, ReceiptRowObservation } from "./receipt-store";
 
+// Typed Op step-builder wrappers (chant #1288 Stage 2) — awsApply/awsDelete/
+// flociUp/flociDown with authoring-time types derived from this lexicon's
+// own *Args interfaces (see ./op/builders.ts's module doc for why these live
+// here rather than in core or the temporal barrel). Opt-in:
+// `@intentius/chant-lexicon-temporal`'s same-named exports are core's
+// original untyped builders, unchanged, for cloud-agnostic authoring.
+export { awsApply, awsDelete, flociUp, flociDown } from "./op/builders";
+
 // Serializer
 export { awsSerializer } from "./serializer";
 

package/src/lint/audit-catalog.ts

@@ -78,4 +78,14 @@ export const awsAuditCatalog: Record<string, RuleMeta> = {
   WAW061: auditRule("WAW061", "merge-worthy", "guidance", "Subnet CidrBlock not contained in its VPC's CidrBlock", "Fix the subnet's CidrBlock so it falls within the VPC's CidrBlock range.", { category: "correctness" }),
   WAW062: auditRule("WAW062", "merge-worthy", "guidance", "Duplicate export name or explicit resource name within a template", "Give each duplicated Export/name a distinct literal value.", { category: "correctness" }),
   WAW063: auditRule("WAW063", "merge-worthy", "guidance", "IAM policy denies an action another attached policy on the same role allows", "Remove or narrow the Deny, or move the Allow off this role — the explicit Deny always wins.", { category: "correctness" }),
+
+  // #826 — network-topology resiliency (Well-Architected Reliability Pillar):
+  // TGW route hygiene, private-subnet and NAT-gateway cross-resource joins,
+  // VPN redundancy. No live state needed — all determinable from the
+  // declared template.
+  WAW064: auditRule("WAW064", "report-only", "guidance", "Transit Gateway route table declares a Blackhole route", "Confirm the traffic drop is intentional; remove the route if it isn't.", { category: "best-practice" }),
+  WAW065: auditRule("WAW065", "report-only", "guidance", "Transit Gateway route table wiring is incomplete", "Add the missing TransitGatewayRouteTablePropagation, or wire the orphaned attachment into a route table.", { category: "best-practice" }),
+  WAW066: auditRule("WAW066", "merge-worthy", "guidance", "Private subnet's route table has no working default route", "Add a 0.0.0.0/0 route to a NAT gateway/Transit Gateway that exists in the template.", { category: "correctness" }),
+  WAW067: auditRule("WAW067", "report-only", "guidance", "Single-AZ NAT gateway serves multi-AZ private subnets", "Add one NAT gateway per Availability Zone and point each AZ's subnets at its own.", { category: "best-practice" }),
+  WAW068: auditRule("WAW068", "report-only", "guidance", "VPN Gateway or Transit Gateway has only one attached VPN Connection", "Attach a second VPNConnection (ideally to a separate Customer Gateway) for redundancy.", { category: "best-practice" }),
 };

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

@@ -55,6 +55,11 @@ import { waw060 } from "./waw060";
 import { waw061 } from "./waw061";
 import { waw062 } from "./waw062";
 import { waw063 } from "./waw063";
+import { waw064 } from "./waw064";
+import { waw065 } from "./waw065";
+import { waw066 } from "./waw066";
+import { waw067 } from "./waw067";
+import { waw068 } from "./waw068";
 
 export const postSynthChecks: PostSynthCheck[] = [
   cor020,
@@ -112,4 +117,9 @@ export const postSynthChecks: PostSynthCheck[] = [
   waw061,
   waw062,
   waw063,
+  waw064,
+  waw065,
+  waw066,
+  waw067,
+  waw068,
 ];

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

@@ -1,16 +1,26 @@
 import { describe, test, expect } from "vitest";
 import { createPostSynthContext } from "@intentius/chant-test-utils";
-import { waw016, checkDeprecatedProperties } from "./waw016";
+import { waw016, checkDeprecatedProperties, type DeprecationBasis } from "./waw016";
 
 function makeCtx(template: object) {
   return createPostSynthContext({ aws: template });
 }
 
+function basisMap(entries: Array<[string, DeprecationBasis]>): Map<string, DeprecationBasis> {
+  return new Map(entries);
+}
+
 /** Synthetic deprecated-property map — no disk dependency. */
-function fakeDeprecated(): Map<string, Set<string>> {
+function fakeDeprecated(): Map<string, Map<string, DeprecationBasis>> {
   return new Map([
-    ["AWS::S3::Bucket", new Set(["AccessControl", "ObjectLockConfiguration"])],
-    ["AWS::Lambda::Function", new Set(["Code"])],
+    [
+      "AWS::S3::Bucket",
+      basisMap([
+        ["AccessControl", "declared"],
+        ["ObjectLockConfiguration", "declared"],
+      ]),
+    ],
+    ["AWS::Lambda::Function", basisMap([["Code", "declared"]])],
   ]);
 }
 
@@ -138,4 +148,51 @@ describe("WAW016: Deprecated Property Usage", () => {
     expect(diags[0].entity).toBe("Bucket");
     expect(diags[1].entity).toBe("Func");
   });
+
+  // --- Deprecation basis (#1701) ---
+
+  test("an inferred deprecation reports at info and names its basis", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Func: {
+          Type: "AWS::Lambda::Function",
+          Properties: { Runtime: "nodejs20.x" },
+        },
+      },
+    });
+    const deprecated = new Map([
+      ["AWS::Lambda::Function", basisMap([["Runtime", "inferred"]])],
+    ]);
+    const diags = checkDeprecatedProperties(ctx, deprecated);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW016");
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("Runtime");
+    expect(diags[0].message).toContain("does not declare it deprecated");
+  });
+
+  test("declared and inferred deprecations on one resource keep separate severities", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyBucket: {
+          Type: "AWS::S3::Bucket",
+          Properties: { AccessControl: "Private", ObjectLockConfiguration: {} },
+        },
+      },
+    });
+    const deprecated = new Map([
+      [
+        "AWS::S3::Bucket",
+        basisMap([
+          ["AccessControl", "declared"],
+          ["ObjectLockConfiguration", "inferred"],
+        ]),
+      ],
+    ]);
+    const diags = checkDeprecatedProperties(ctx, deprecated);
+    expect(diags).toHaveLength(2);
+    const bySeverity = new Map(diags.map((d) => [d.severity, d.message]));
+    expect(bySeverity.get("warning")).toContain("AccessControl");
+    expect(bySeverity.get("info")).toContain("ObjectLockConfiguration");
+  });
 });

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

@@ -2,7 +2,13 @@
  * WAW016: Deprecated Property Usage
  *
  * Flags properties marked as deprecated in the CloudFormation Registry.
- * Sources: explicit `deprecatedProperties` array + description text mining.
+ *
+ * Two bases feed this, and the finding says which one it stands on (#1701).
+ * A `declared` name comes from the Registry schema's own `deprecatedProperties`
+ * array. An `inferred` name comes from a regex over the property description,
+ * which also matches descriptions that mention the deprecation of a sibling
+ * property, an enum value, or the thing the property configures. Declared is a
+ * warning; inferred is reported at info and worded as a guess.
  */
 
 import { readFileSync } from "fs";
@@ -10,18 +16,23 @@ import { join } from "path";
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { parseCFTemplate } from "./cf-refs";
 
+/** What a deprecation classification rests on. */
+export type DeprecationBasis = "declared" | "inferred";
+
 interface LexiconEntry {
   kind: string;
   resourceType: string;
   deprecatedProperties?: string[];
+  inferredDeprecations?: string[];
   [key: string]: unknown;
 }
 
 /**
- * Load deprecated properties per resource type from the lexicon JSON.
+ * Load deprecated properties per resource type from the lexicon JSON, each
+ * tagged with the basis it was classified on.
  */
-function loadDeprecatedProperties(): Map<string, Set<string>> {
-  const map = new Map<string, Set<string>>();
+function loadDeprecatedProperties(): Map<string, Map<string, DeprecationBasis>> {
+  const map = new Map<string, Map<string, DeprecationBasis>>();
   try {
     const pkgDir = join(__dirname, "..", "..", "..");
     const lexiconPath = join(pkgDir, "src", "generated", "lexicon-aws.json");
@@ -29,9 +40,15 @@ function loadDeprecatedProperties(): Map<string, Set<string>> {
     const data = JSON.parse(content) as Record<string, LexiconEntry>;
 
     for (const [_name, entry] of Object.entries(data)) {
-      if (entry.kind === "resource" && entry.resourceType && entry.deprecatedProperties && entry.deprecatedProperties.length > 0) {
-        map.set(entry.resourceType, new Set(entry.deprecatedProperties));
+      if (entry.kind !== "resource" || !entry.resourceType) continue;
+      if (!entry.deprecatedProperties?.length) continue;
+
+      const inferred = new Set(entry.inferredDeprecations ?? []);
+      const byProp = new Map<string, DeprecationBasis>();
+      for (const propName of entry.deprecatedProperties) {
+        byProp.set(propName, inferred.has(propName) ? "inferred" : "declared");
       }
+      map.set(entry.resourceType, byProp);
     }
   } catch {
     // Lexicon not available — skip
@@ -44,7 +61,7 @@ function loadDeprecatedProperties(): Map<string, Set<string>> {
  */
 export function checkDeprecatedProperties(
   ctx: PostSynthContext,
-  deprecated: Map<string, Set<string>>,
+  deprecated: Map<string, Map<string, DeprecationBasis>>,
 ): PostSynthDiagnostic[] {
   if (deprecated.size === 0) return [];
 
@@ -60,15 +77,19 @@ export function checkDeprecatedProperties(
 
       const props = resource.Properties ?? {};
       for (const propName of Object.keys(props)) {
-        if (deprProps.has(propName)) {
-          diagnostics.push({
-            checkId: "WAW016",
-            severity: "warning",
-            message: `Resource "${logicalId}" (${resource.Type}) uses deprecated property "${propName}" — consider alternatives`,
-            entity: logicalId,
-            lexicon: "aws",
-          });
-        }
+        const basis = deprProps.get(propName);
+        if (!basis) continue;
+
+        diagnostics.push({
+          checkId: "WAW016",
+          severity: basis === "declared" ? "warning" : "info",
+          message:
+            basis === "declared"
+              ? `Resource "${logicalId}" (${resource.Type}) uses deprecated property "${propName}" — consider alternatives`
+              : `Resource "${logicalId}" (${resource.Type}) uses property "${propName}", whose description reads as deprecated — the CloudFormation Registry does not declare it deprecated, so confirm before changing it`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
       }
     }
   }

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

@@ -0,0 +1,79 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw064, checkTgwBlackholeRoute } from "./waw064";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW064: Transit Gateway Route Table Declares A Blackhole Route", () => {
+  test("check metadata", () => {
+    expect(waw064.id).toBe("WAW064");
+    expect(waw064.description).toContain("Blackhole");
+  });
+
+  test("TransitGatewayRoute with Blackhole: true → warning", () => {
+    const ctx = makeCtx({
+      Resources: {
+        QuarantineRoute: {
+          Type: "AWS::EC2::TransitGatewayRoute",
+          Properties: {
+            TransitGatewayRouteTableId: { Ref: "TgwRouteTable" },
+            DestinationCidrBlock: "10.99.0.0/16",
+            Blackhole: true,
+          },
+        },
+        TgwRouteTable: { Type: "AWS::EC2::TransitGatewayRouteTable", Properties: { TransitGatewayId: { Ref: "Tgw" } } },
+        Tgw: { Type: "AWS::EC2::TransitGateway", Properties: {} },
+      },
+    });
+    const diags = checkTgwBlackholeRoute(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW064");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("QuarantineRoute");
+    expect(diags[0].message).toContain("10.99.0.0/16");
+    expect(diags[0].lexicon).toBe("aws");
+  });
+
+  test("normal TransitGatewayRoute forwarding to an attachment → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        SpokeRoute: {
+          Type: "AWS::EC2::TransitGatewayRoute",
+          Properties: {
+            TransitGatewayRouteTableId: { Ref: "TgwRouteTable" },
+            DestinationCidrBlock: "10.0.1.0/24",
+            TransitGatewayAttachmentId: { Ref: "SpokeAttachment" },
+          },
+        },
+        TgwRouteTable: { Type: "AWS::EC2::TransitGatewayRouteTable", Properties: { TransitGatewayId: { Ref: "Tgw" } } },
+        Tgw: { Type: "AWS::EC2::TransitGateway", Properties: {} },
+        SpokeAttachment: { Type: "AWS::EC2::TransitGatewayVpcAttachment", Properties: {} },
+      },
+    });
+    expect(checkTgwBlackholeRoute(ctx)).toHaveLength(0);
+  });
+
+  test("Blackhole: false is not flagged", () => {
+    const ctx = makeCtx({
+      Resources: {
+        SpokeRoute: {
+          Type: "AWS::EC2::TransitGatewayRoute",
+          Properties: {
+            TransitGatewayRouteTableId: { Ref: "TgwRouteTable" },
+            DestinationCidrBlock: "10.0.1.0/24",
+            TransitGatewayAttachmentId: { Ref: "SpokeAttachment" },
+            Blackhole: false,
+          },
+        },
+      },
+    });
+    expect(checkTgwBlackholeRoute(ctx)).toHaveLength(0);
+  });
+
+  test("no TransitGatewayRoute resources → no diagnostic", () => {
+    const ctx = makeCtx({ Resources: { Vpc: { Type: "AWS::EC2::VPC", Properties: { CidrBlock: "10.0.0.0/16" } } } });
+    expect(checkTgwBlackholeRoute(ctx)).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,52 @@
+/**
+ * WAW064: Transit Gateway Route Table Declares A Blackhole Route
+ *
+ * `AWS::EC2::TransitGatewayRoute` with `Blackhole: true` silently drops any
+ * traffic matching its destination CIDR instead of forwarding it —
+ * CloudFormation deploys this without complaint, and the packet loss only
+ * surfaces downstream as unreachable hosts or a timeout nobody can explain
+ * from the template alone. A blackhole route is sometimes deliberate — an
+ * explicit deny for a CIDR range, or a placeholder pending real
+ * infrastructure — but it is also exactly what a copy-pasted route table or
+ * a forgotten cleanup step leaves behind. Warn so it stays a conscious
+ * choice rather than a silent accident.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+
+export function checkTgwBlackholeRoute(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.Type !== "AWS::EC2::TransitGatewayRoute") continue;
+
+      const props = resource.Properties ?? {};
+      if (props.Blackhole !== true) continue;
+
+      const cidr = typeof props.DestinationCidrBlock === "string" ? props.DestinationCidrBlock : "(unknown destination)";
+      diagnostics.push({
+        checkId: "WAW064",
+        severity: "warning",
+        message: `TransitGatewayRoute "${logicalId}" declares Blackhole: true for destination ${cidr} — traffic matching this route is silently dropped; confirm this is intentional`,
+        entity: logicalId,
+        lexicon: "aws",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw064: PostSynthCheck = {
+  id: "WAW064",
+  description: "Transit Gateway route table declares a Blackhole route — confirm the traffic drop is intentional, not an accident",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkTgwBlackholeRoute(ctx);
+  },
+};