@intentius/chant-lexicon-aws 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.19.0",
+  "version": "0.20.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.19.0",
+    "@intentius/chant": "^0.20.0",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/docs.ts

@@ -102,7 +102,15 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
     overview,
     outputFormat,
     serviceFromType,
-    suppressPages: ["pseudo-parameters", "intrinsics", "rules"],
+    // "intrinsics" is no longer suppressed (chant #1067) — the reference
+    // table at that slug is now generated from the plugin's own
+    // `intrinsics()` registration (docsPipeline's generateIntrinsics, same
+    // mechanism azure/helm already use), so its "Folds?" column can never
+    // drift from the registration the way #1062's foldability matrix
+    // depends on. The hand-written usage guide with full worked examples
+    // moves to a separate "intrinsics-guide" page below — content
+    // unchanged, just no longer sharing a slug with generated data.
+    suppressPages: ["pseudo-parameters", "rules"],
     examplesDir: join(pkgDir, "examples"),
     extraPages: [
       {
@@ -210,7 +218,7 @@ Runtime context values available in every template, accessed via the \`AWS\` nam
 
 ## Intrinsic functions
 
-The lexicon provides 9 intrinsic functions (\`Sub\`, \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`, \`GetAZs\`) that map directly to CloudFormation \`Fn::\` calls. See [Intrinsic Functions](../intrinsics/) for full usage examples.
+The lexicon provides 9 intrinsic functions (\`Sub\`, \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`, \`GetAZs\`) that map directly to CloudFormation \`Fn::\` calls. See [Intrinsic Functions](../intrinsics/) for the reference table or the [Intrinsics Guide](../intrinsics-guide/) for full usage examples.
 
 ## Dependencies
 
@@ -319,10 +327,14 @@ No other changes needed — all taggable resources in the project get these tags
 Tag values support strings, \`Parameter\` references, and intrinsic functions (\`Sub\`, \`Ref\`, etc.).`,
       },
       {
-        slug: "intrinsics",
-        title: "Intrinsic Functions",
-        description: "CloudFormation intrinsic functions and their chant syntax",
-        content: `CloudFormation intrinsic functions are available as imports from the lexicon. They produce the corresponding \`Fn::\` calls in the serialized template.
+        slug: "intrinsics-guide",
+        title: "Intrinsics Guide",
+        description: "Worked examples for every CloudFormation intrinsic function and their chant syntax",
+        content: `See [Intrinsic Functions](../intrinsics/) for the generated reference table (name, description, output key, whether it's a tagged template, whether \`chant build --fold\` can fold it). This page is the worked-example companion — one \`Fn::\` intrinsic function per section, with real usage.
+
+CloudFormation intrinsic functions are available as imports from the lexicon. They produce the corresponding \`Fn::\` calls in the serialized template.
+
+Only \`Sub\` is a tagged template — the others below are plain function calls. That distinction matters for [\`chant build --fold\`](/chant/concepts/typescript-as-data/#folded-vs-run): a registered intrinsic tagged template is one of the shapes the static folder can reduce with no module execution. A plain function call is not, today — \`chant build --fold\` has no case for a bare call used as a value yet ([#1044](https://github.com/INTENTIUS/chant/issues/1044) tracks changing that, per intrinsic). Using \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`, or \`GetAZs\` anywhere in a resource's props forces that file back to the normal run path under \`--fold\` for now.
 
 Here is a complete example using all intrinsic functions:
 
@@ -400,6 +412,8 @@ Instantiate and export:
 
 During build, composites expand to flat CloudFormation resources: \`healthApiRole\`, \`healthApiFunc\`, \`healthApiPermission\`.
 
+A top-level composite call assigned directly to an export — like \`healthApi\` above — is one of the patterns [\`chant build --fold\`](/chant/concepts/typescript-as-data/#folded-vs-run) can reduce with no module execution (chant #1023). Defining a composite (the \`Composite(...)\` call inside \`lambda-api.ts\` itself) doesn't fold — its factory callback is a function, which is outside the fold subset — and neither does a composite call embedded as a nested value inside another resource's own properties; only a composite call that is itself a file's top-level export (or destructured/re-exported from one) is eligible.
+
 ## Built-in composites
 
 The AWS lexicon ships ready-to-use composites for common patterns. Import them from \`@intentius/chant-lexicon-aws\`:

package/src/codegen/package.ts

@@ -42,12 +42,16 @@ export async function packageLexicon(opts: PackageOptions = {}): Promise<Package
 
       buildManifest: (_genResult) => {
         // Lazy-import to avoid circular dependency
+        // Trust the plugin's own `isTag` registration (chant #1067) — this
+        // used to recompute `isTag: i.name === "Sub"` independently of
+        // ../plugin.ts, a second source of truth that could silently drift
+        // from the real registration (the exact shape of bug #1039 found).
         const intrinsics: IntrinsicDef[] = (awsPlugin.intrinsics?.() ?? []).map(
           (i: IntrinsicDef) => ({
             name: i.name,
             description: i.description,
             outputKey: intrinsicOutputKey(i.name),
-            isTag: i.name === "Sub",
+            isTag: i.isTag,
           }),
         );