@intentius/chant-lexicon-aws 0.49.0 → 0.51.0

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

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw068, checkVpnGatewayRedundancy } from "./waw068";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW068: VPN Gateway Has A Single VPN Connection", () => {
+  test("check metadata", () => {
+    expect(waw068.id).toBe("WAW068");
+    expect(waw068.description).toContain("VPN Connection");
+  });
+
+  test("VPN Gateway with a single VPN connection → warning", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Vgw: { Type: "AWS::EC2::VPNGateway", Properties: { Type: "ipsec.1" } },
+        CustomerGw: { Type: "AWS::EC2::CustomerGateway", Properties: { Type: "ipsec.1", BgpAsn: 65000, IpAddress: "203.0.113.1" } },
+        VpnConnection: {
+          Type: "AWS::EC2::VPNConnection",
+          Properties: { Type: "ipsec.1", CustomerGatewayId: { Ref: "CustomerGw" }, VpnGatewayId: { Ref: "Vgw" } },
+        },
+      },
+    });
+    const diags = checkVpnGatewayRedundancy(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW068");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("Vgw");
+    expect(diags[0].message).toContain("VpnConnection");
+  });
+
+  test("Transit Gateway with a single VPN connection → warning", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Tgw: { Type: "AWS::EC2::TransitGateway", Properties: {} },
+        CustomerGw: { Type: "AWS::EC2::CustomerGateway", Properties: { Type: "ipsec.1", BgpAsn: 65000, IpAddress: "203.0.113.1" } },
+        VpnConnection: {
+          Type: "AWS::EC2::VPNConnection",
+          Properties: { Type: "ipsec.1", CustomerGatewayId: { Ref: "CustomerGw" }, TransitGatewayId: { Ref: "Tgw" } },
+        },
+      },
+    });
+    const diags = checkVpnGatewayRedundancy(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("Tgw");
+    expect(diags[0].message).toContain("Transit Gateway");
+  });
+
+  test("VPN Gateway with two VPN connections attached → no diagnostic", () => {
+    const ctx = makeCtx({
+      Resources: {
+        Vgw: { Type: "AWS::EC2::VPNGateway", Properties: { Type: "ipsec.1" } },
+        CustomerGwA: { Type: "AWS::EC2::CustomerGateway", Properties: { Type: "ipsec.1", BgpAsn: 65000, IpAddress: "203.0.113.1" } },
+        CustomerGwB: { Type: "AWS::EC2::CustomerGateway", Properties: { Type: "ipsec.1", BgpAsn: 65000, IpAddress: "203.0.113.2" } },
+        VpnConnectionA: {
+          Type: "AWS::EC2::VPNConnection",
+          Properties: { Type: "ipsec.1", CustomerGatewayId: { Ref: "CustomerGwA" }, VpnGatewayId: { Ref: "Vgw" } },
+        },
+        VpnConnectionB: {
+          Type: "AWS::EC2::VPNConnection",
+          Properties: { Type: "ipsec.1", CustomerGatewayId: { Ref: "CustomerGwB" }, VpnGatewayId: { Ref: "Vgw" } },
+        },
+      },
+    });
+    expect(checkVpnGatewayRedundancy(ctx)).toHaveLength(0);
+  });
+
+  test("no VPN connections at all → no diagnostic", () => {
+    const ctx = makeCtx({ Resources: { Vgw: { Type: "AWS::EC2::VPNGateway", Properties: { Type: "ipsec.1" } } } });
+    expect(checkVpnGatewayRedundancy(ctx)).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,78 @@
+/**
+ * WAW068: VPN Gateway Has A Single VPN Connection
+ *
+ * An `AWS::EC2::VPNConnection` always gets two tunnels from AWS, but that
+ * redundancy only covers the tunnel pair inside one connection — it does
+ * nothing if the connection's Customer Gateway, on-prem device, or the
+ * single site it terminates at goes down. The reliability boundary that
+ * matters is the connection itself: a `AWS::EC2::VPNGateway` (or a Transit
+ * Gateway used for VPN attachment) with only one `VPNConnection` attached
+ * has no fallback path for hybrid connectivity if that connection's
+ * Customer Gateway or on-prem side fails.
+ *
+ * Cross-resource join: group every declared `VPNConnection` by the gateway
+ * (`VpnGatewayId` or `TransitGatewayId`) it attaches to, and flag any
+ * gateway left with exactly one.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs, type CFTemplate } from "./cf-refs";
+
+export function checkVpnGatewayRedundancy(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template: CFTemplate | null = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+    const resources = template.Resources;
+
+    // gateway logical id -> the VPNConnection logical ids attached to it.
+    const connectionsByGateway = new Map<string, string[]>();
+
+    for (const [logicalId, resource] of Object.entries(resources)) {
+      if (resource.Type !== "AWS::EC2::VPNConnection") continue;
+      const props = resource.Properties ?? {};
+
+      const gatewayProp = props.VpnGatewayId !== undefined ? props.VpnGatewayId : props.TransitGatewayId;
+      if (gatewayProp === undefined) continue; // no declared gateway target — can't group, stay quiet
+
+      const gwRefs = findResourceRefs(gatewayProp);
+      if (gwRefs.size !== 1) continue;
+      const [gwId] = gwRefs;
+
+      const gw = resources[gwId];
+      if (!gw || (gw.Type !== "AWS::EC2::VPNGateway" && gw.Type !== "AWS::EC2::TransitGateway")) continue;
+
+      let list = connectionsByGateway.get(gwId);
+      if (!list) {
+        list = [];
+        connectionsByGateway.set(gwId, list);
+      }
+      list.push(logicalId);
+    }
+
+    for (const [gwId, connectionIds] of connectionsByGateway) {
+      if (connectionIds.length !== 1) continue;
+
+      const kind = resources[gwId].Type === "AWS::EC2::VPNGateway" ? "VPN Gateway" : "Transit Gateway";
+      diagnostics.push({
+        checkId: "WAW068",
+        severity: "warning",
+        message: `${kind} "${gwId}" has only one VPN connection ("${connectionIds[0]}") attached — no redundant path if this connection, its tunnels, or its Customer Gateway fail; attach a second VPNConnection (ideally to a separate Customer Gateway) for hybrid-connectivity redundancy`,
+        entity: gwId,
+        lexicon: "aws",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw068: PostSynthCheck = {
+  id: "WAW068",
+  description: "VPN Gateway or Transit Gateway has only one attached VPN Connection — no redundant path for hybrid connectivity",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkVpnGatewayRedundancy(ctx);
+  },
+};

package/src/lsp/hover.ts

@@ -61,9 +61,21 @@ function resourceHover(className: string, entry: LexiconEntry): HoverInfo | unde
     lines.push(`**Conditionally immutable:** ${entry.conditionalCreateOnly.map((p) => `\`${p}\``).join(", ")}`);
   }
 
-  if (entry.deprecatedProperties?.length) {
+  // Declared and inferred deprecations rest on different evidence, so they
+  // read as separate lines rather than one merged list.
+  const inferred = new Set(entry.inferredDeprecations ?? []);
+  const declared = (entry.deprecatedProperties ?? []).filter((p) => !inferred.has(p));
+
+  if (declared.length > 0) {
+    lines.push("");
+    lines.push(`**Deprecated properties:** ${declared.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  if (inferred.size > 0) {
     lines.push("");
-    lines.push(`**Deprecated properties:** ${entry.deprecatedProperties.map((p) => `\`${p}\``).join(", ")}`);
+    lines.push(
+      `**Possibly deprecated** (description text only, not declared by the Registry): ${[...inferred].map((p) => `\`${p}\``).join(", ")}`,
+    );
   }
 
   return { contents: lines.join("\n") };

package/src/op/builders.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Typed step-builder wrappers (chant #1288 Stage 2) — see
+ * `lexicons/k8s/src/op/builders.test.ts`'s module doc for what's asserted
+ * and why.
+ */
+
+import { describe, test, expect } from "vitest";
+import { awsApply as awsApplyOld, awsDelete as awsDeleteOld, flociUp as flociUpOld, flociDown as flociDownOld, stepOutput, type StepOutputRef } from "@intentius/chant/op";
+import { awsApply, awsDelete, flociUp, flociDown } from "./builders";
+
+describe("aws typed step builders (#1288 Stage 2)", () => {
+  test("awsApply: identical ActivityStep to core's original", () => {
+    const opts = { stackName: "my-stack" };
+    expect(awsApply("dist/template.json", opts)).toEqual(awsApplyOld("dist/template.json", opts));
+  });
+
+  test("awsApply: identical ActivityStep with more opts", () => {
+    const opts = { stackName: "my-stack", region: "us-west-2", capabilities: ["CAPABILITY_NAMED_IAM"], profile: "fastIdempotent" as const };
+    expect(awsApply("dist/template.json", opts)).toEqual(awsApplyOld("dist/template.json", opts));
+  });
+
+  test("awsDelete: identical ActivityStep to core's original", () => {
+    const opts = { stackName: "my-stack" };
+    expect(awsDelete("dist/template.json", opts)).toEqual(awsDeleteOld("dist/template.json", opts));
+  });
+
+  test("flociUp/flociDown: identical ActivityStep to core's original", () => {
+    expect(flociUp()).toEqual(flociUpOld());
+    expect(flociUp({ port: 4567 })).toEqual(flociUpOld({ port: 4567 }));
+    expect(flociDown()).toEqual(flociDownOld());
+  });
+
+  test("awsApply: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("resolve-region", "region");
+    const step = awsApply("dist/template.json", { stackName: "my-stack", region: ref });
+    expect(step.args?.region).toBe(ref);
+  });
+
+  test("awsApply: .out is reachable when an id is given", () => {
+    const step = awsApply("dist/template.json", { stackName: "my-stack", id: "apply" });
+    const ref: StepOutputRef = step.out.releaseName;
+    expect(ref.step).toBe("apply");
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — stackName is required (the activity fails without it);
+  // omitting opts entirely is no longer a way around that.
+  awsApply("dist/template.json");
+
+  // @ts-expect-error — "stackname" (wrong case) is not a key of AwsApplyArgs.
+  awsApply("dist/template.json", { stackname: "my-stack" });
+
+  // @ts-expect-error — capabilities must be string[], not a single string.
+  awsApply("dist/template.json", { stackName: "my-stack", capabilities: "CAPABILITY_NAMED_IAM" });
+
+  // @ts-expect-error — port must be a number.
+  flociUp({ port: "4566" });
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2). See `lexicons/k8s/src/op/builders.ts`'s module doc for why these
+ * live beside their `*Args` interfaces rather than in core or the temporal
+ * barrel: core cannot import a lexicon's types (lexicons depend on core, not
+ * the reverse), and wiring them into the cloud-agnostic temporal barrel
+ * would make it depend on every cloud lexicon at runtime. `opts`'s type in
+ * each wrapper below IS the activity's own `*Args` interface (via
+ * `Omit`/`WithStepRefs`) — never restated. `core`'s own
+ * `awsApply`/`awsDelete`/`flociUp`/`flociDown` are unchanged and produce
+ * byte-identical `ActivityStep` output; these are purely additive.
+ */
+
+import {
+  activity,
+  takeProfileAndId,
+  type ActivityStep,
+  type NamedActivityStep,
+  type WithStepRefs,
+} from "@intentius/chant/op";
+import type { AwsApplyArgs, AwsDeleteArgs } from "./activities/aws-apply";
+import type { FlociUpArgs, FlociDownArgs } from "./activities/floci";
+
+/** Extra opts every wrapper below accepts alongside its activity's own fields. */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Deploy a built CloudFormation template directly against the CFN API — the
+ * fully typed twin of core's `awsApply`. `opts` is {@link AwsApplyArgs}
+ * itself, minus the positional `templatePath`. Defaults to the `longInfra`
+ * profile.
+ */
+export const awsApply = (
+  templatePath: string,
+  opts: WithStepRefs<Omit<AwsApplyArgs, "templatePath">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("awsApply", { templatePath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Delete a CloudFormation stack — the inverse of {@link awsApply}, fully
+ * typed twin of core's `awsDelete`. `opts` is {@link AwsDeleteArgs} itself,
+ * minus the positional `templatePath`. Defaults to the `longInfra` profile.
+ */
+export const awsDelete = (
+  templatePath: string,
+  opts: WithStepRefs<Omit<AwsDeleteArgs, "templatePath">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("awsDelete", { templatePath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Boot the local Floci AWS emulator — the fully typed twin of core's
+ * `flociUp`. `opts` is {@link FlociUpArgs} itself. Defaults to the
+ * `longInfra` profile.
+ */
+export const flociUp = (opts?: WithStepRefs<FlociUpArgs> & StepOpts): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("flociUp", args, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/**
+ * Stop and remove the local Floci emulator container — the fully typed twin
+ * of core's `flociDown`. `opts` is {@link FlociDownArgs} itself. Defaults to
+ * the `fastIdempotent` profile.
+ */
+export const flociDown = (opts?: WithStepRefs<FlociDownArgs> & StepOpts): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("flociDown", args, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import { createRequire } from "module";
 import { detectTemplate } from "./detect";
-import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, IntrinsicDef, ObservationResult, DeepObservationResult, DependencyObservation, DisruptionQuery, DisruptionVerdict, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { TemplateParser } from "@intentius/chant/import/parser";
@@ -25,6 +25,7 @@ import {
   type StackResource,
 } from "./api/read-client";
 import { awsDeepNormalizationHooks, observeResourcesDeepAws } from "./deep-observe";
+import { awsDisruption } from "./disruption";
 import { awsReferenceCatalog } from "./reference-catalog";
 import { AMBIENT_KINDS } from "./ambient";
 import { canDescribe, describeOwnProperties, stampRegion } from "./properties";
@@ -765,6 +766,20 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     return observeAwsDependencies({ observed: options.observed, region: options.region });
   },
 
+  /**
+   * What a pending update costs (#1665), read off the Registry schema the
+   * codegen already compiled: a changed `createOnlyProperties` entry is a
+   * replacement, and `replacementStrategy: delete_then_create` makes it a
+   * destroy. A conditionally-create-only property is `unknown` on purpose —
+   * the schema says "depends on the value", which is not an answer.
+   */
+  classifyDisruption(options: {
+    environment: string;
+    changes: DisruptionQuery[];
+  }): Record<string, DisruptionVerdict> {
+    return awsDisruption(options);
+  },
+
   /**
    * Resources of a managed kind that exist without being declared or
    * referenced (#1278) — the account's default security groups, an unattached

package/src/spec/parse.test.ts

@@ -187,6 +187,80 @@ describe("parseCFNSchema", () => {
     });
     const result = parseCFNSchema(schema);
     expect(result.resource.deprecatedProperties).toEqual([]);
+    expect(result.resource.inferredDeprecations).toEqual([]);
+  });
+
+  // --- Deprecation basis (#1701) ---
+
+  test("a declared deprecation is not recorded as inferred", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Declared",
+      properties: {
+        OldProp: { type: "string", description: "An old property." },
+      },
+      deprecatedProperties: ["/properties/OldProp"],
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.deprecatedProperties).toEqual(["OldProp"]);
+    expect(result.resource.inferredDeprecations).toEqual([]);
+  });
+
+  test("a description-mined deprecation is recorded as inferred", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Mined",
+      properties: {
+        OldProp: { type: "string", description: "This property is deprecated. Use NewProp instead." },
+        NewProp: { type: "string", description: "The replacement property" },
+      },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.deprecatedProperties).toEqual(["OldProp"]);
+    expect(result.resource.inferredDeprecations).toEqual(["OldProp"]);
+  });
+
+  test("a property both declared and matched by the regex counts as declared", () => {
+    // sampleBucketSchema declares AccessControl and its description says "legacy".
+    const result = parseCFNSchema(sampleBucketSchema);
+    expect(result.resource.deprecatedProperties).toContain("AccessControl");
+    expect(result.resource.inferredDeprecations).not.toContain("AccessControl");
+  });
+
+  test("inferredDeprecations is a subset of deprecatedProperties", () => {
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Mixed",
+      properties: {
+        DeclaredProp: { type: "string", description: "Plain prose." },
+        MinedProp: { type: "string", description: "This is a legacy property." },
+      },
+      deprecatedProperties: ["/properties/DeclaredProp"],
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    const all = new Set(result.resource.deprecatedProperties);
+    for (const p of result.resource.inferredDeprecations) {
+      expect(all.has(p)).toBe(true);
+    }
+    expect(result.resource.inferredDeprecations).toEqual(["MinedProp"]);
+  });
+
+  test("a description naming a sibling's deprecation lands in inferred, not declared", () => {
+    // Shape of AWS::Neptune::DBCluster.DBPort, where the description announces
+    // that the sibling `Port` is going away and DBPort is the replacement.
+    const schema = JSON.stringify({
+      typeName: "AWS::Test::Sibling",
+      properties: {
+        DBPort: {
+          type: "integer",
+          description: "The port. Note: `Port` will soon be deprecated. Rename it to `DBPort`.",
+        },
+      },
+      additionalProperties: false,
+    });
+    const result = parseCFNSchema(schema);
+    expect(result.resource.inferredDeprecations).toEqual(["DBPort"]);
+    expect(result.resource.deprecatedProperties).toEqual(["DBPort"]);
   });
 
   // --- Tagging metadata ---

package/src/spec/parse.ts

@@ -30,6 +30,13 @@ export type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
  */
 const MAX_PROPERTY_TYPE_DEPTH = 3;
 
+/**
+ * Prose signals that a property description is describing a deprecation.
+ * A hit is a guess, not a reading — see `ParsedResource.inferredDeprecations`.
+ */
+const DEPRECATION_RE =
+  /\bdeprecated\b|\blegacy\b|no longer (available|recommended|used|supported)|is not recommended|has been discontinued/i;
+
 export interface ParsedProperty {
   name: string;
   tsType: string;
@@ -63,6 +70,13 @@ export interface ParsedResource {
   writeOnly: string[];
   primaryIdentifier: string[];
   deprecatedProperties: string[];
+  /**
+   * The subset of `deprecatedProperties` that no upstream declaration backs.
+   * These names come from {@link DEPRECATION_RE} matching the property
+   * description, so they are an inference rather than a reading. Kept apart so
+   * a consumer can tell the two apart and calibrate what it says (#1701).
+   */
+  inferredDeprecations: string[];
   conditionalCreateOnly: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
   tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
@@ -160,19 +174,24 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
     }
   }
 
-  // --- Deprecated properties: explicit + description-mined ---
+  // --- Deprecated properties: declared upstream, plus description-mined ---
+  // The declared half is what the Registry schema states. The mined half is a
+  // regex over English prose and is recorded separately (#1701): a description
+  // can mention the deprecation of a sibling property, of an enum value, or of
+  // something the property merely configures.
   const deprecatedSet = new Set<string>(
     stripPointerPaths(schema.deprecatedProperties ?? []),
   );
-
-  const DEPRECATION_RE = /\bdeprecated\b|\blegacy\b|no longer (available|recommended|used|supported)|is not recommended|has been discontinued/i;
+  const inferredDeprecations: string[] = [];
 
   // Mine top-level property descriptions
   if (schema.properties) {
     for (const [name, prop] of Object.entries(schema.properties)) {
-      if (prop.description && DEPRECATION_RE.test(prop.description)) {
-        deprecatedSet.add(name);
-      }
+      if (!prop.description || !DEPRECATION_RE.test(prop.description)) continue;
+      // A hit upstream already declares adds nothing, and is not an inference.
+      if (deprecatedSet.has(name)) continue;
+      deprecatedSet.add(name);
+      inferredDeprecations.push(name);
     }
   }
 
@@ -211,6 +230,7 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
       writeOnly: stripPointerPaths(schema.writeOnlyProperties ?? []),
       primaryIdentifier: stripPointerPaths(schema.primaryIdentifier ?? []),
       deprecatedProperties: [...deprecatedSet],
+      inferredDeprecations,
       conditionalCreateOnly: stripPointerPaths(schema.conditionalCreateOnlyProperties ?? []),
       ...(replacementStrategy && { replacementStrategy }),
       ...(tagging && { tagging }),