@intentius/chant-lexicon-aws 0.46.0 → 0.50.0

package/src/serializer.ts

@@ -2,7 +2,19 @@ import type { Declarable, CoreParameter } from "@intentius/chant/declarable";
 import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
 import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
 import { ownershipEntries, type OwnershipMarker } from "@intentius/chant/ownership";
+import {
+  isEffectReceipt,
+  receiptExpectation,
+  referenceInputPaths,
+  type EffectReceiptDeclaration,
+} from "@intentius/chant/effect-receipt";
 import { AWS_TAG_OWNERSHIP_KEYS, OWNERSHIP_METADATA_KEY } from "./ownership";
+import {
+  AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+  EFFECT_RECEIPTS_METADATA_KEY,
+  RECEIPT_UNRESOLVED_VALUE_NOTE,
+  receiptParameterName,
+} from "./effect-receipt-row";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { isChildProject, type ChildProjectInstance } from "@intentius/chant/child-project";
@@ -154,6 +166,80 @@ function toProperties(
 }
 
 
+/** One rendered receipt row — a CFN-resource-shaped object that lives in the
+ * template's `Metadata`, never in `Resources` (#1832: the applier writes from
+ * `Resources`, and the `effect()` step is a receipt's sole writer). */
+interface ReceiptRow {
+  Type: typeof AWS_EFFECT_RECEIPT_ENTITY_TYPE;
+  Properties: {
+    Name: string;
+    Type: "String";
+    Value: string;
+    Tags: Array<{ Key: string; Value: string }>;
+  };
+}
+
+/** The rendered `Value`: the synthesis-time expectation when the receipt is
+ * fully static, a placeholder note when reference inputs resolve later —
+ * never a digest hashed over placeholders (epic #1703, decision 5). */
+function receiptRowValue(receipt: EffectReceiptDeclaration): string {
+  if (receipt.flavor === "hash" && referenceInputPaths(receipt).length > 0) {
+    return RECEIPT_UNRESOLVED_VALUE_NOTE;
+  }
+  return receiptExpectation(receipt);
+}
+
+/**
+ * Render the effect receipts (#1835) the build withheld from the apply-bound
+ * entity set (`SerializeContext.receipts`, #1832) as `AWS::SSM::Parameter`
+ * rows: plain `String`, named `/chant-receipts/<stack>/<env>/<effect>` from
+ * the resolved ownership marker (epic decision 4 — the same fields that stamp
+ * tags), carrying the ownership tags. Visibility only: the rows go under the
+ * template's `Metadata`, and the receipt store (./receipt-store.ts) is what
+ * actually writes the parameter — through the `effect()` step, on success,
+ * last.
+ *
+ * The env segment is explicit: a receipt with no resolved `ownership.env` is
+ * an error here, never a guessed path.
+ */
+function renderReceiptRows(
+  receipts: ReadonlyMap<string, Declarable>,
+  ownership: OwnershipMarker | undefined,
+): Record<string, ReceiptRow> {
+  const rows: Record<string, ReceiptRow> = {};
+  const names = [...receipts.keys()].join(", ");
+  if (!ownership) {
+    throw new Error(
+      `aws receipts (${names}): no ownership marker resolved — the receipt path is ` +
+        `/chant-receipts/<stack>/<env>/<effect>, derived from the same ownership fields that ` +
+        `stamp markers (chant #1703, decision 4). Set ownership: { stack, env } in chant.config.ts.`,
+    );
+  }
+  if (!ownership.env) {
+    throw new Error(
+      `aws receipts (${names}): ownership resolved no env — the receipt path's <env> segment is ` +
+        `explicit (chant #1703, decision 4). Set ownership.env in chant.config.ts (a literal, or ` +
+        `{ param: "env" } with --param env=<name>).`,
+    );
+  }
+  const tags = Object.entries(ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership)).map(
+    ([Key, Value]) => ({ Key, Value }),
+  );
+  for (const [name, entity] of receipts) {
+    if (!isEffectReceipt(entity)) continue;
+    rows[name] = {
+      Type: AWS_EFFECT_RECEIPT_ENTITY_TYPE,
+      Properties: {
+        Name: receiptParameterName(ownership.stack, ownership.env, entity.effect),
+        Type: "String",
+        Value: receiptRowValue(entity),
+        Tags: tags,
+      },
+    };
+  }
+  return rows;
+}
+
 /**
  * Serialize a set of entities into a CFTemplate object (without JSON.stringify).
  */
@@ -163,6 +249,7 @@ function serializeToTemplate(
   extraParameters?: Record<string, CFParameter>,
   extraOutputs?: Record<string, CFOutput>,
   ownership?: OwnershipMarker,
+  receiptRows?: Record<string, ReceiptRow>,
 ): CFTemplate {
   const template: CFTemplate = {
     AWSTemplateFormatVersion: "2010-09-09",
@@ -196,6 +283,14 @@ function serializeToTemplate(
       [OWNERSHIP_METADATA_KEY]: ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership),
     };
   }
+  // Effect receipt rows (#1835) — visibility only, deliberately outside
+  // `Resources`: the applier's desired and prune sets both read `Resources`,
+  // and the `effect()` step is a receipt's sole writer (#1832, epic #1703
+  // decision 3). The observation leg (plugin.ts) reads the paths back from
+  // this block, so the identity is derived exactly once, here.
+  if (receiptRows && Object.keys(receiptRows).length > 0) {
+    template.Metadata = { ...(template.Metadata ?? {}), [EFFECT_RECEIPTS_METADATA_KEY]: receiptRows };
+  }
   for (const [, entity] of entities) {
     if (isDefaultTags(entity)) {
       defaultTagEntries.push(...entity.tags);
@@ -412,6 +507,14 @@ export const awsSerializer: Serializer = {
   serialize(entities: Map<string, Declarable>, outputs?: LexiconOutput[], context?: SerializeContext): string | SerializerResult {
     const ownership = context?.ownership;
 
+    // Effect receipts (#1835): withheld from `entities` by the build (#1832),
+    // rendered here as Metadata rows — never as `Resources` an applier would
+    // write. Env-less ownership is an error, not a guessed path segment.
+    const receiptRows =
+      context?.receipts && context.receipts.size > 0
+        ? renderReceiptRows(context.receipts, ownership)
+        : undefined;
+
     // Check if any entities are child projects (nested stacks)
     const childProjects = new Map<string, ChildProjectInstance>();
     let hasChildProjects = false;
@@ -425,7 +528,7 @@ export const awsSerializer: Serializer = {
 
     // No nested stacks — use the simple path
     if (!hasChildProjects) {
-      const template = serializeToTemplate(entities, outputs, undefined, undefined, ownership);
+      const template = serializeToTemplate(entities, outputs, undefined, undefined, ownership, receiptRows);
       return JSON.stringify(template, null, 2);
     }
 
@@ -465,7 +568,7 @@ export const awsSerializer: Serializer = {
     }
 
     // Serialize the parent template (ChildProjectInstance entities become CF::Stack resources)
-    const parentTemplate = serializeToTemplate(entities, outputs, parentParams, undefined, ownership);
+    const parentTemplate = serializeToTemplate(entities, outputs, parentParams, undefined, ownership, receiptRows);
     const primary = JSON.stringify(parentTemplate, null, 2);
 
     return {

package/src/skills/chant-aws-carve-terraform.md

@@ -1,6 +1,6 @@
 ---
 skill: chant-aws-carve-terraform
-description: Demo carving a resource out of Terraform into native chant — advise, emit, bridge, apply — fully offline
+description: Demo carving a resource out of Terraform into native chant — advise, emit, audit, bridge, apply — fully offline
 user-invocable: true
 ---
 
@@ -15,7 +15,7 @@ graduation.
 ## When to use
 
 - Someone asks "how does chant move things off Terraform?"
-- You want to show the advise → emit → bridge → apply loop end to end.
+- You want to show the advise → emit → audit → bridge → apply loop end to end.
 - You are evaluating whether a Terraform estate is worth carving.
 
 ## Preconditions
@@ -27,7 +27,7 @@ graduation.
 ## The fastest path: run the bundled demo
 
 The `examples/terraform-carve-out` example ships a runnable estate + state and a
-script that runs all four steps with commentary:
+script that runs all five steps with commentary:
 
 ```bash
 cd examples/terraform-carve-out
@@ -54,28 +54,30 @@ From `examples/terraform-carve-out`, with `TF=./terraform`:
      --state ./terraform/terraform.tfstate --output ./carveout
    ```
    Show `./carveout/src/assets.ts` — a real `new Bucket({ BucketName, Tags })` with
-   CloudFormation-style properties mapped from the Terraform state attributes.
-   Emit also scaffolds `./carveout` into a buildable chant project
-   (`chant.config.ts`, `package.json`), so `npm install && npm run build` works
-   there as-is. Explain: a Terraform-managed resource is not in any
-   CloudFormation stack, so the correct source of its live shape is the state
-   file, not a cloud read.
-
-3. **Lint the inherited resource — optional, offer it.**
+   CloudFormation-style properties mapped from the Terraform state attributes,
+   and the `aws_s3_bucket_versioning` sub-resource folded into
+   `VersioningConfiguration`. Emit also scaffolds `./carveout` into a buildable
+   chant project (`chant.config.ts`, `package.json`) and persists a carve
+   manifest (`*.carve.json`) — bridge and apply read the target from it, so
+   `--select` is only needed once. Explain: a Terraform-managed resource is not
+   in any CloudFormation stack, so the correct source of its live shape is the
+   state file, not a cloud read.
+
+3. **Audit the inherited resource.**
    ```bash
-   chant lint ./carveout/src --lexicon aws
+   chant build ./carveout/src --lexicon aws
    ```
-   After emit, offer to lint the carved source. chant audits the resource you
-   inherited from Terraform against the AWS lexicon's rules. Findings have a
-   severity: `error` (must fix before `chant build` will emit — e.g. an S3
-   bucket with no public-access block) and `warning`/`info` (advisory — e.g.
-   DynamoDB point-in-time recovery). This is a feature of carving: chant
-   immediately tells the person what is wrong with what they adopted. Whether to
-   fix an advisory finding is their call; errors block the build until resolved.
+   The first build fails, deliberately: the post-synth audit refuses the
+   adopted bucket because Terraform managed it without a public-access block or
+   a TLS-only policy. This is a feature of carving: chant immediately tells the
+   person what is wrong with what they adopted. Show the fix (add
+   `PublicAccessBlockConfiguration` and a companion `S3BucketPolicy` with an
+   `aws:SecureTransport = false` Deny — the tutorial page has the exact code),
+   then re-run the build and show the valid CloudFormation template.
 
 4. **Bridge — patch the surviving Terraform.**
    ```bash
-   chant carve bridge --from ./terraform --select aws_s3_bucket.assets --output ./carveout
+   chant carve bridge --from ./terraform --output ./carveout
    ```
    Show the generated `data "aws_s3_bucket" "assets"` and the rewired survivor.
    Emphasize it is dry-run: nothing in `./terraform` changed. `--apply-rewrites`
@@ -83,11 +85,12 @@ From `examples/terraform-carve-out`, with `TF=./terraform`:
 
 5. **Apply — graduation plan.**
    ```bash
-   chant carve apply --from ./terraform --select aws_s3_bucket.assets --env prod --stack assets
+   chant carve apply --from ./terraform --output ./carveout --env prod --stack assets
    ```
    Show the ownership marker (`chant:managed-by/stack/env`) and the finalized
-   runbook. Stress this makes no cloud call — the apply is the person's own
-   lifecycle; chant just plans it.
+   runbook. `--write-source` additionally stamps the marker tags into the
+   emitted source. Stress this makes no cloud call — the apply is the person's
+   own lifecycle; chant just plans it.
 
 ## Key points to land
 

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 }),