@intentius/chant-lexicon-aws 0.50.0 → 0.51.0

package/dist/disruption.d.ts

@@ -0,0 +1,26 @@
+import type { DisruptionQuery, DisruptionVerdict } from "@intentius/chant/lexicon";
+/** 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 declare function classifyAwsChange(query: DisruptionQuery, specs: Map<string, DisruptionSpec>): DisruptionVerdict;
+/**
+ * `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 declare function awsDisruption(options: {
+    environment: string;
+    changes: DisruptionQuery[];
+}): Record<string, DisruptionVerdict>;
+//# sourceMappingURL=disruption.d.ts.map

package/dist/disruption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../src/disruption.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAInF,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;CACnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACjC,iBAAiB,CAuDnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAOpC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "4ed3c883e89ff20517d344e836a3fdd6c35e52e8ea0276cb02c3157710823bba",
+    "manifest.json": "0c488f36f907e56798a03315c3dec265068b2db4233aa839f03db166e2c17b54",
     "meta.json": "e7c751a09a871dc5a16e9aeea0b0a149513a7a2a051c923e9a5acf193dc2aef8",
     "types/index.d.ts": "6d6b37bd14a9b40fb3ff5c66e1cb49be1ae1032de47a4e167cf5f411c943b7f5",
     "rules/hardcoded-region.ts": "5a0eaf7ab391231fe6cd51426ece29539cb4b36f31c8dd060956638fed55722a",
@@ -72,5 +72,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "0ae4376590db47979be144d3ac6cdcfd56c9640d0536421aacf7330459d38e52"
   },
-  "composite": "ba342596e044edf730f75709ef8b4f5bd2c614b6d2eba0e9f457c20f039bb70a"
+  "composite": "e03cda0c71c249a0fad0b4c921913fe533bf0f3ddcfc9c4758a0f8d66922fb2d"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAgL,MAAM,0BAA0B,CAAC;AAqC5O;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aAk9BvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAoN,MAAM,0BAA0B,CAAC;AAsChR;yEACyE;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBnD,eAAO,MAAM,SAAS,EAAE,aAg+BvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,7 +80,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.50.0",
+    "@intentius/chant": "^0.51.0",
     "typescript": "^5.9.3"
   }
 }

package/src/disruption.test.ts

@@ -0,0 +1,198 @@
+import { describe, test, expect } from "vitest";
+import { awsDisruption, classifyAwsChange, type DisruptionSpec } from "./disruption";
+import type { DisruptionQuery } from "@intentius/chant/lexicon";
+
+const specs = new Map<string, DisruptionSpec>([
+  [
+    "AWS::EC2::Instance",
+    {
+      resourceType: "AWS::EC2::Instance",
+      kind: "resource",
+      attrs: { InstanceId: "InstanceId", PublicIp: "PublicIp" },
+      createOnly: ["ImageId", "SubnetId", "KeyName"],
+      conditionalCreateOnly: ["InstanceType"],
+    },
+  ],
+  [
+    "AWS::RDS::DBInstance",
+    {
+      resourceType: "AWS::RDS::DBInstance",
+      kind: "resource",
+      createOnly: ["DBInstanceIdentifier"],
+      replacementStrategy: "delete_then_create",
+    },
+  ],
+  [
+    "AWS::S3::BucketPolicy",
+    { resourceType: "AWS::S3::BucketPolicy", kind: "resource" },
+  ],
+  [
+    "AWS::EC2::Instance.BlockDeviceMapping",
+    { resourceType: "AWS::EC2::Instance.BlockDeviceMapping", kind: "property" },
+  ],
+]);
+
+function query(type: string | undefined, paths: string[]): DisruptionQuery {
+  return {
+    name: "thing",
+    ...(type ? { type } : {}),
+    deltas: paths.map((path) => ({ path, oldValue: "a", newValue: "b" })),
+  };
+}
+
+describe("classifyAwsChange (#1665)", () => {
+  test("a create-only property is a replace, and says which one", () => {
+    const v = classifyAwsChange(query("AWS::EC2::Instance", ["attributes.ImageId"]), specs);
+    expect(v.disruption).toBe("replace");
+    expect(v.because).toEqual(["attributes.ImageId"]);
+    expect(v.detail).toContain("ImageId is create-only");
+  });
+
+  // `delete_then_create` is the destructive form: the old resource is gone
+  // before the new one exists.
+  test("delete_then_create replacement is a destroy", () => {
+    const v = classifyAwsChange(
+      query("AWS::RDS::DBInstance", ["attributes.DBInstanceIdentifier"]),
+      specs,
+    );
+    expect(v.disruption).toBe("destroy");
+    expect(v.detail).toContain("deleting first");
+  });
+
+  test("a mutable property is in-place", () => {
+    const v = classifyAwsChange(query("AWS::EC2::Instance", ["attributes.Monitoring"]), specs);
+    expect(v.disruption).toBe("in-place");
+    expect(v.detail).toContain("no create-only property of AWS::EC2::Instance changed");
+  });
+
+  test("replacement wins over an in-place property changing alongside it", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["attributes.Monitoring", "attributes.SubnetId"]),
+      specs,
+    );
+    expect(v.disruption).toBe("replace");
+    expect(v.because).toEqual(["attributes.SubnetId"]);
+  });
+
+  // The schema says "depends on the value", which is not an answer. Reporting
+  // that as in-place would be the exact failure the `unknown` level exists for.
+  test("a conditionally create-only property is unknown, not in-place", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["attributes.InstanceType"]),
+      specs,
+    );
+    expect(v.disruption).toBe("unknown");
+    expect(v.because).toEqual(["attributes.InstanceType"]);
+    expect(v.detail).toContain("conditionally create-only");
+  });
+
+  test("a type with no schema on record is unknown", () => {
+    const v = classifyAwsChange(query("AWS::Nowhere::Thing", ["attributes.Anything"]), specs);
+    expect(v.disruption).toBe("unknown");
+    expect(v.detail).toContain("no CloudFormation registry schema on record");
+  });
+
+  test("a property-type entry is not a resource, so it is unknown", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance.BlockDeviceMapping", ["attributes.Ebs"]),
+      specs,
+    );
+    expect(v.disruption).toBe("unknown");
+  });
+
+  test("an entry with no observed type is unknown", () => {
+    const v = classifyAwsChange(query(undefined, ["attributes.ImageId"]), specs);
+    expect(v.disruption).toBe("unknown");
+    expect(v.detail).toContain("no resource type");
+  });
+
+  // A read-only attribute changing is a symptom of something else, never the
+  // cause of a replacement — a re-created instance reports a new PublicIp.
+  test("read-only attributes are not evidence of anything", () => {
+    const v = classifyAwsChange(query("AWS::EC2::Instance", ["attributes.PublicIp"]), specs);
+    expect(v.disruption).toBe("in-place");
+    expect(v.detail).toContain("only status, identity, or read-only attributes changed");
+  });
+
+  test("core's own observation fields are not properties", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["status", "lastUpdated", "physicalId"]),
+      specs,
+    );
+    expect(v.disruption).toBe("in-place");
+    expect(v.detail).toContain("only status, identity, or read-only attributes changed");
+  });
+
+  test("a type whose schema declares no create-only property is in-place", () => {
+    const v = classifyAwsChange(query("AWS::S3::BucketPolicy", ["attributes.PolicyDocument"]), specs);
+    expect(v.disruption).toBe("in-place");
+  });
+
+  // createOnlyProperties can point at a nested pointer path (`Config/Engine`);
+  // the observation reports the top-level property.
+  test("a nested create-only pointer matches on its head segment", () => {
+    const nested = new Map<string, DisruptionSpec>([
+      [
+        "AWS::Fake::Thing",
+        { resourceType: "AWS::Fake::Thing", kind: "resource", createOnly: ["Config/Engine"] },
+      ],
+    ]);
+    const v = classifyAwsChange(query("AWS::Fake::Thing", ["attributes.Config"]), nested);
+    expect(v.disruption).toBe("replace");
+  });
+
+  test("duplicate hits name the property once but keep every path", () => {
+    const v = classifyAwsChange(
+      query("AWS::EC2::Instance", ["attributes.ImageId", "attributes.KeyName"]),
+      specs,
+    );
+    expect(v.because).toEqual(["attributes.ImageId", "attributes.KeyName"]);
+    expect(v.detail).toContain("ImageId, KeyName");
+  });
+});
+
+// The plugin method against the registry the codegen actually compiled — the
+// evidence that the verdicts come from CloudFormation's own schema and not
+// from a table in this file.
+describe("awsDisruption over the generated registry", () => {
+  const change = (name: string, type: string, paths: string[]): DisruptionQuery => ({
+    name,
+    type,
+    deltas: paths.map((path) => ({ path, oldValue: "a", newValue: "b" })),
+  });
+
+  test("classifies a whole batch off the compiled schema", () => {
+    const out = awsDisruption({
+      environment: "prod",
+      changes: [
+        // createOnlyProperties
+        change("web", "AWS::EC2::Instance", ["attributes.ImageId"]),
+        // conditionalCreateOnlyProperties — the schema says "it depends"
+        change("sized", "AWS::EC2::Instance", ["attributes.InstanceType"]),
+        // not create-only for this type
+        change("mon", "AWS::EC2::Instance", ["attributes.Monitoring"]),
+        // no schema on record
+        change("nope", "AWS::Nowhere::Thing", ["attributes.Whatever"]),
+      ],
+    });
+
+    expect(out.web.disruption).toBe("replace");
+    expect(out.web.because).toEqual(["attributes.ImageId"]);
+    expect(out.sized.disruption).toBe("unknown");
+    expect(out.sized.detail).toContain("conditionally create-only");
+    expect(out.mon.disruption).toBe("in-place");
+    expect(out.nope.disruption).toBe("unknown");
+  });
+
+  test("every query gets a verdict, so nothing silently drops out of the plan", () => {
+    const changes = [
+      change("a", "AWS::S3::Bucket", ["attributes.BucketName"]),
+      change("b", "AWS::IAM::Role", ["attributes.RoleName"]),
+    ];
+    const out = awsDisruption({ environment: "prod", changes });
+    expect(Object.keys(out).sort()).toEqual(["a", "b"]);
+    // BucketName and RoleName are both create-only in the Registry schema.
+    expect(out.a.disruption).toBe("replace");
+    expect(out.b.disruption).toBe("replace");
+  });
+});

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/lsp/hover.ts

@@ -62,11 +62,8 @@ function resourceHover(className: string, entry: LexiconEntry): HoverInfo | unde
   }
 
   // Declared and inferred deprecations rest on different evidence, so they
-  // read as separate lines rather than one merged list (#1701). The core
-  // `LexiconEntry` gains `inferredDeprecations` in the next core release; this
-  // lexicon builds against the published core, so widen locally until then.
-  const withBasis = entry as LexiconEntry & { inferredDeprecations?: string[] };
-  const inferred = new Set(withBasis.inferredDeprecations ?? []);
+  // 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) {

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