@intentius/chant-lexicon-aws 0.34.1 → 0.37.0

package/src/api/read-client.test.ts

@@ -0,0 +1,203 @@
+/**
+ * The native AWS read transport (#1206).
+ *
+ * The transport is injected everywhere, so nothing here reaches a network. The
+ * XML cases are the ones worth being careful about: the applier's `xmlField`
+ * only ever handled flat scalars, and the read path needs `<member>` lists.
+ */
+import { describe, test, expect } from "vitest";
+import {
+  AwsReadError,
+  describeStackOutputs,
+  describeStackResources,
+  getResource,
+  listResources,
+  parseResourceDescription,
+  serviceUrl,
+  xmlLeaves,
+  xmlMembers,
+  xmlError,
+  type AwsReadHttp,
+} from "./read-client";
+
+const respond = (text: string, status = 200): ReturnType<AwsReadHttp> => Promise.resolve({ status, text });
+
+/** Records every call so a test can assert what went on the wire. */
+function recording(handler: (body: string, headers: Record<string, string>) => ReturnType<AwsReadHttp>) {
+  const calls: Array<{ url: string; headers: Record<string, string>; body: string }> = [];
+  const http: AwsReadHttp = (url, init) => {
+    calls.push({ url, headers: init.headers, body: init.body });
+    return handler(init.body, init.headers);
+  };
+  return { http, calls };
+}
+
+const stackXml = `
+<DescribeStackResourcesResponse><DescribeStackResourcesResult><StackResources>
+  <member>
+    <LogicalResourceId>dataBucket</LogicalResourceId>
+    <ResourceType>AWS::S3::Bucket</ResourceType>
+    <PhysicalResourceId>acme-assets</PhysicalResourceId>
+    <ResourceStatus>CREATE_COMPLETE</ResourceStatus>
+    <Timestamp>2026-01-01T00:00:00Z</Timestamp>
+  </member>
+  <member>
+    <LogicalResourceId>vpc</LogicalResourceId>
+    <ResourceType>AWS::EC2::VPC</ResourceType>
+    <PhysicalResourceId>vpc-01</PhysicalResourceId>
+    <ResourceStatus>CREATE_COMPLETE</ResourceStatus>
+  </member>
+</StackResources></DescribeStackResourcesResult></DescribeStackResourcesResponse>`;
+
+describe("serviceUrl", () => {
+  test("an override wins over the regional host, with exactly one trailing slash", () => {
+    expect(serviceUrl("cloudformation", "http://localhost:4566")).toBe("http://localhost:4566/");
+    expect(serviceUrl("cloudformation", "http://localhost:4566/")).toBe("http://localhost:4566/");
+  });
+
+  test("without an override it is the real regional host for that service", () => {
+    expect(serviceUrl("cloudcontrolapi", undefined, "eu-west-1")).toBe("https://cloudcontrolapi.eu-west-1.amazonaws.com/");
+  });
+});
+
+describe("the Query XML shapes", () => {
+  test("xmlLeaves flattens one fragment and decodes entities", () => {
+    expect(xmlLeaves("<A>1</A><B>x &amp; y</B>")).toEqual({ A: "1", B: "x & y" });
+  });
+
+  test("xmlLeaves keeps the first of a repeated tag", () => {
+    expect(xmlLeaves("<A>first</A><A>second</A>")).toEqual({ A: "first" });
+  });
+
+  test("xmlMembers reads a member list, which xmlField never could", () => {
+    expect(xmlMembers(stackXml, "StackResources")).toHaveLength(2);
+  });
+
+  test("xmlMembers is empty for an absent list rather than throwing", () => {
+    expect(xmlMembers("<Response/>", "StackResources")).toEqual([]);
+  });
+
+  test("xmlError finds a Query error document, and nothing in a success body", () => {
+    expect(xmlError("<ErrorResponse><Error><Code>ValidationError</Code><Message>nope</Message></Error></ErrorResponse>")).toEqual({
+      code: "ValidationError",
+      message: "nope",
+    });
+    expect(xmlError(stackXml)).toBeUndefined();
+  });
+});
+
+describe("describeStackResources", () => {
+  test("maps members onto the read path's shape, keeping optional fields optional", async () => {
+    const { http, calls } = recording(() => respond(stackXml));
+    const resources = await describeStackResources("local", { endpoint: "http://localhost:4566", http });
+
+    expect(resources).toEqual([
+      {
+        logicalId: "dataBucket",
+        type: "AWS::S3::Bucket",
+        physicalId: "acme-assets",
+        status: "CREATE_COMPLETE",
+        timestamp: "2026-01-01T00:00:00Z",
+      },
+      { logicalId: "vpc", type: "AWS::EC2::VPC", physicalId: "vpc-01", status: "CREATE_COMPLETE" },
+    ]);
+    expect(calls[0].url).toBe("http://localhost:4566/");
+    expect(calls[0].body).toContain("Action=DescribeStackResources");
+    expect(calls[0].body).toContain("StackName=local");
+  });
+
+  test("a Query error becomes a typed throw carrying the service's own code", async () => {
+    const { http } = recording(() =>
+      respond("<ErrorResponse><Error><Code>ValidationError</Code><Message>Stack with id local does not exist</Message></Error></ErrorResponse>", 400),
+    );
+    await expect(describeStackResources("local", { http })).rejects.toMatchObject({
+      name: "AwsReadError",
+      code: "ValidationError",
+      status: 400,
+    });
+  });
+
+  test("a non-2xx with no error document still throws rather than parsing as empty", async () => {
+    const { http } = recording(() => respond("<html>502</html>", 502));
+    await expect(describeStackResources("local", { http })).rejects.toBeInstanceOf(AwsReadError);
+  });
+});
+
+describe("describeStackOutputs", () => {
+  test("reads the output members as a flat record", async () => {
+    const { http } = recording(() =>
+      respond(`<DescribeStacksResponse><Outputs>
+        <member><OutputKey>VpcId</OutputKey><OutputValue>vpc-01</OutputValue></member>
+        <member><OutputKey>Empty</OutputKey></member>
+      </Outputs></DescribeStacksResponse>`),
+    );
+    expect(await describeStackOutputs("local", { http })).toEqual({ VpcId: "vpc-01", Empty: "" });
+  });
+});
+
+describe("Cloud Control", () => {
+  const description = (identifier: string, properties: Record<string, unknown>) => ({
+    Identifier: identifier,
+    Properties: JSON.stringify(properties),
+  });
+
+  test("getResource unwraps the doubly-encoded model and targets the JSON 1.0 operation", async () => {
+    const { http, calls } = recording(() =>
+      respond(JSON.stringify({ ResourceDescription: description("acme-assets", { BucketName: "acme-assets" }) })),
+    );
+    expect(await getResource("AWS::S3::Bucket", "acme-assets", { http })).toEqual({
+      identifier: "acme-assets",
+      properties: { BucketName: "acme-assets" },
+    });
+    expect(calls[0].headers["x-amz-target"]).toBe("CloudApiService.GetResource");
+    expect(calls[0].headers["content-type"]).toBe("application/x-amz-json-1.0");
+  });
+
+  test("a modelled error becomes a typed throw — UnsupportedOperation is not a miss", async () => {
+    const { http } = recording(() =>
+      respond(JSON.stringify({ __type: "UnsupportedOperation", message: "Operation GetResource is not supported." }), 400),
+    );
+    await expect(getResource("AWS::S3::Bucket", "b", { http })).rejects.toMatchObject({
+      code: "UnsupportedOperation",
+      status: 400,
+    });
+  });
+
+  test("a `__type` carrying a shape prefix is reported by its bare name", async () => {
+    const { http } = recording(() =>
+      respond(JSON.stringify({ __type: "com.amazonaws.cloudapi#ThrottlingException", message: "Rate exceeded" }), 400),
+    );
+    await expect(getResource("AWS::S3::Bucket", "b", { http })).rejects.toMatchObject({ code: "ThrottlingException" });
+  });
+
+  test("listResources follows NextToken to exhaustion", async () => {
+    let page = 0;
+    const { http, calls } = recording(() => {
+      page += 1;
+      return respond(
+        JSON.stringify(
+          page === 1
+            ? { ResourceDescriptions: [description("a", { BucketName: "a" })], NextToken: "more" }
+            : { ResourceDescriptions: [description("b", { BucketName: "b" })] },
+        ),
+      );
+    });
+    const all = await listResources("AWS::S3::Bucket", { http });
+    expect(all.map((r) => r.identifier)).toEqual(["a", "b"]);
+    expect(calls).toHaveLength(2);
+    expect(calls[1].body).toContain("more");
+  });
+
+  test("an unparseable description is dropped, not returned as an empty resource", async () => {
+    const { http } = recording(() =>
+      respond(JSON.stringify({ ResourceDescriptions: [{ Identifier: "a", Properties: "{oops" }] })),
+    );
+    expect(await listResources("AWS::S3::Bucket", { http })).toEqual([]);
+  });
+
+  test("parseResourceDescription refuses anything that is not a model object", () => {
+    expect(parseResourceDescription(null)).toBeNull();
+    expect(parseResourceDescription({ Identifier: "a" })).toBeNull();
+    expect(parseResourceDescription({ Properties: JSON.stringify(["not", "an", "object"]) })).toBeNull();
+  });
+});

package/src/api/read-client.ts

@@ -0,0 +1,286 @@
+/**
+ * The native AWS read transport (#1206) — the read half of what
+ * `op/activities/aws-apply.ts` already does for writes.
+ *
+ * Every AWS observer shelled `aws …` once per entity, serially, and parsed
+ * stderr to find out what went wrong (#1085). The applier does not: `awsApply`
+ * speaks the CloudFormation Query protocol over `fetch`, honours an endpoint
+ * override, and is injectable for tests. This module is that same transport
+ * pointed at the two APIs the read path needs:
+ *
+ *   - **CloudFormation Query** (form-encoded POST, XML back) — the stack reads
+ *     `describeResources` and the deep pass both start from.
+ *   - **Cloud Control** (AWS JSON 1.0, `X-Amz-Target: CloudApiService.*`) — the
+ *     property-level reads (#1015).
+ *
+ * Both take the endpoint the same way the applier does, so `chant emulator` /
+ * behold `--local` keep working by construction rather than by each observer
+ * remembering to inject `--endpoint-url`.
+ *
+ * ## Signing
+ *
+ * Requests are unsigned, exactly like `awsApply`'s. That is what makes the
+ * emulator-first lanes work with no credential plumbing, and it is the reason
+ * this is scoped to the Floci lanes (#1198) rather than announced as a
+ * real-cloud read path: real AWS rejects an unsigned request. The CLI path
+ * remains available for a signed read until SigV4 lands here.
+ */
+
+const DEFAULT_REGION = "us-east-1";
+const CFN_API_VERSION = "2010-05-15";
+const CLOUD_CONTROL_TARGET_PREFIX = "CloudApiService";
+
+/** Injectable HTTP, mirroring `AwsHttp` in the applier so tests avoid the network. */
+export type AwsReadHttp = (
+  url: string,
+  init: { headers: Record<string, string>; body: string },
+  signal?: AbortSignal,
+) => Promise<{ status: number; text: string }>;
+
+const defaultHttp: AwsReadHttp = async (url, init, signal) => {
+  const res = await fetch(url, { method: "POST", headers: init.headers, body: init.body, signal });
+  return { status: res.status, text: await res.text() };
+};
+
+/** A failed read, carrying enough to classify it without parsing prose. */
+export class AwsReadError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    /** The API's own error code (`ValidationError`, `UnsupportedOperation`, …) when it sent one. */
+    readonly code?: string,
+  ) {
+    super(message);
+    this.name = "AwsReadError";
+  }
+}
+
+export interface AwsReadClientOptions {
+  /** Endpoint override (Floci `http://localhost:4566`). Omit for real AWS hosts. */
+  endpoint?: string;
+  /** Region for the real-AWS host and the Query `Version` context. */
+  region?: string;
+  http?: AwsReadHttp;
+  signal?: AbortSignal;
+}
+
+/** Service host for `service`, honouring an endpoint override. */
+export function serviceUrl(service: string, endpoint?: string, region = DEFAULT_REGION): string {
+  return `${(endpoint ?? `https://${service}.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
+}
+
+/* ── CloudFormation Query ─────────────────────────────────────────────────── */
+
+/**
+ * The `<Tag>text</Tag>` pairs of one XML fragment, as a flat record. Repeated
+ * tags keep the first occurrence, which is what a `<member>` body wants —
+ * nested lists inside a member are not modelled, because nothing the read path
+ * needs from `DescribeStackResources` / `DescribeStacks` is nested that deep.
+ */
+export function xmlLeaves(fragment: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const m of fragment.matchAll(/<([A-Za-z0-9]+)>([^<]*)<\/\1>/g)) {
+    const [, tag, value] = m;
+    if (tag && !(tag in out)) out[tag] = decodeXmlEntities(value ?? "");
+  }
+  return out;
+}
+
+/** The five predefined XML entities. Query responses carry them in ARNs and policy text. */
+function decodeXmlEntities(value: string): string {
+  return value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+/**
+ * Every `<member>…</member>` under `listTag`, each flattened by
+ * {@link xmlLeaves}. The Query protocol renders a list as repeated `<member>`
+ * elements, and `xmlField` in the applier deliberately does not handle them —
+ * it was written for scalar status fields.
+ */
+export function xmlMembers(xml: string, listTag: string): Array<Record<string, string>> {
+  const list = xml.match(new RegExp(`<${listTag}>([\\s\\S]*?)</${listTag}>`))?.[1];
+  if (!list) return [];
+  return [...list.matchAll(/<member>([\s\S]*?)<\/member>/g)].map((m) => xmlLeaves(m[1] ?? ""));
+}
+
+/** `<Error><Code>…</Code><Message>…</Message></Error>`, when the response carries one. */
+export function xmlError(xml: string): { code?: string; message?: string } | undefined {
+  if (!/<Error>/.test(xml)) return undefined;
+  const leaves = xmlLeaves(xml.match(/<Error>([\s\S]*?)<\/Error>/)?.[1] ?? "");
+  return { code: leaves.Code, message: leaves.Message };
+}
+
+/**
+ * One CloudFormation Query call. Returns the raw XML; throws
+ * {@link AwsReadError} for a non-2xx or an `<Error>` body, so a caller
+ * classifies a typed failure instead of matching on stderr.
+ */
+export async function cfnQuery(
+  action: string,
+  params: Record<string, string>,
+  options: AwsReadClientOptions = {},
+): Promise<string> {
+  const http = options.http ?? defaultHttp;
+  const url = serviceUrl("cloudformation", options.endpoint, options.region);
+  const body = new URLSearchParams({ Action: action, Version: CFN_API_VERSION, ...params }).toString();
+  const res = await http(url, { headers: { "content-type": "application/x-www-form-urlencoded" }, body }, options.signal);
+  const err = xmlError(res.text);
+  if (err || res.status >= 400) {
+    throw new AwsReadError(
+      err?.message ?? `${action} failed with HTTP ${res.status}`,
+      res.status,
+      err?.code,
+    );
+  }
+  return res.text;
+}
+
+/** One stack resource, as `DescribeStackResources` reports it. */
+export interface StackResource {
+  logicalId: string;
+  type: string;
+  physicalId?: string;
+  status?: string;
+  timestamp?: string;
+}
+
+/** `DescribeStackResources` for one stack, mapped off the Query XML. */
+export async function describeStackResources(
+  stackName: string,
+  options: AwsReadClientOptions = {},
+): Promise<StackResource[]> {
+  const xml = await cfnQuery("DescribeStackResources", { StackName: stackName }, options);
+  return xmlMembers(xml, "StackResources").map((m) => ({
+    logicalId: m.LogicalResourceId ?? "",
+    type: m.ResourceType ?? "",
+    ...(m.PhysicalResourceId ? { physicalId: m.PhysicalResourceId } : {}),
+    ...(m.ResourceStatus ? { status: m.ResourceStatus } : {}),
+    ...(m.Timestamp ? { timestamp: m.Timestamp } : {}),
+  }));
+}
+
+/** `DescribeStacks` outputs for one stack, as `key → value`. */
+export async function describeStackOutputs(
+  stackName: string,
+  options: AwsReadClientOptions = {},
+): Promise<Record<string, string>> {
+  const xml = await cfnQuery("DescribeStacks", { StackName: stackName }, options);
+  const outputs: Record<string, string> = {};
+  for (const m of xmlMembers(xml, "Outputs")) {
+    if (m.OutputKey) outputs[m.OutputKey] = m.OutputValue ?? "";
+  }
+  return outputs;
+}
+
+/* ── Cloud Control ────────────────────────────────────────────────────────── */
+
+/** One live resource, as Cloud Control describes it. */
+export interface CloudControlDescription {
+  identifier: string;
+  properties: Record<string, unknown>;
+}
+
+/**
+ * One Cloud Control call (AWS JSON 1.0). Throws {@link AwsReadError} carrying
+ * the service's `__type` so `UnsupportedOperation` — what Floci answers for
+ * `GetResource` — stays distinguishable from a credential or a genuine miss.
+ */
+async function cloudControl(
+  operation: "GetResource" | "ListResources",
+  payload: Record<string, unknown>,
+  options: AwsReadClientOptions = {},
+): Promise<Record<string, unknown>> {
+  const http = options.http ?? defaultHttp;
+  const url = serviceUrl("cloudcontrolapi", options.endpoint, options.region);
+  const res = await http(
+    url,
+    {
+      headers: {
+        "content-type": "application/x-amz-json-1.0",
+        "x-amz-target": `${CLOUD_CONTROL_TARGET_PREFIX}.${operation}`,
+      },
+      body: JSON.stringify(payload),
+    },
+    options.signal,
+  );
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(res.text);
+  } catch {
+    throw new AwsReadError(`unparseable ${operation} response`, res.status);
+  }
+  const body = isRecord(parsed) ? parsed : {};
+  const type = typeof body.__type === "string" ? body.__type.split("#").pop() : undefined;
+  if (type || res.status >= 400) {
+    const message = typeof body.message === "string" ? body.message : `${operation} failed with HTTP ${res.status}`;
+    throw new AwsReadError(message, res.status, type);
+  }
+  return body;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Cloud Control returns a resource model as a JSON *string* inside the
+ * envelope, so every description unwraps twice. Returns null when either level
+ * does not parse to an object — an unparseable body is a failed read, not an
+ * empty resource.
+ */
+export function parseResourceDescription(raw: unknown): CloudControlDescription | null {
+  if (!isRecord(raw)) return null;
+  const properties = typeof raw.Properties === "string" ? safeParseObject(raw.Properties) : undefined;
+  if (!properties) return null;
+  return {
+    identifier: typeof raw.Identifier === "string" ? raw.Identifier : "",
+    properties,
+  };
+}
+
+function safeParseObject(text: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** `GetResource` — the full live model for one identifier. */
+export async function getResource(
+  typeName: string,
+  identifier: string,
+  options: AwsReadClientOptions = {},
+): Promise<CloudControlDescription | null> {
+  const body = await cloudControl("GetResource", { TypeName: typeName, Identifier: identifier }, options);
+  return parseResourceDescription(body.ResourceDescription);
+}
+
+/** `ListResources` — every live resource of one type, paginated to exhaustion. */
+export async function listResources(
+  typeName: string,
+  options: AwsReadClientOptions = {},
+): Promise<CloudControlDescription[]> {
+  const out: CloudControlDescription[] = [];
+  let nextToken: string | undefined;
+  do {
+    const body = await cloudControl(
+      "ListResources",
+      { TypeName: typeName, ...(nextToken ? { NextToken: nextToken } : {}) },
+      options,
+    );
+    const descriptions = Array.isArray(body.ResourceDescriptions) ? body.ResourceDescriptions : [];
+    for (const d of descriptions) {
+      const parsed = parseResourceDescription(d);
+      if (parsed) out.push(parsed);
+    }
+    nextToken = typeof body.NextToken === "string" && body.NextToken.length > 0 ? body.NextToken : undefined;
+  } while (nextToken);
+  return out;
+}

package/src/codegen/docs.ts

@@ -110,7 +110,13 @@ export async function generateDocs(options?: { verbose?: boolean }): Promise<voi
     // 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"],
+    // `rules` is NOT suppressed: the hand-written `lint-rules` page below
+    // explains 26 of the lexicon's 50 rules in depth, and the whole WAW032+
+    // hardening pass had no entry there at all (#1312). The generated table is
+    // the complete, always-current list, so both ship — the overview/reference
+    // pairing temporal uses. Duplicating 24 descriptions into the prose page
+    // would just create a third copy to drift.
+    suppressPages: ["pseudo-parameters"],
     examplesDir: join(pkgDir, "examples"),
     extraPages: [
       {
@@ -330,11 +336,11 @@ Tag values support strings, \`Parameter\` references, and intrinsic functions (\
         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.
+        content: `See [Intrinsic Functions](../intrinsics/) for the generated reference table (name, description, output key, whether it's a tagged template, whether folding can reduce 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.
+Only \`Sub\` is a tagged template — the others below are plain function calls. Both forms fold on the [default build path](/chant/concepts/typescript-as-data/#folded-vs-run) ([#1044](https://github.com/INTENTIUS/chant/issues/1044)): every AWS intrinsic on this page is registered with its call form opted in, so using \`Ref\`, \`GetAtt\`, \`If\`, \`Join\`, \`Select\`, \`Split\`, \`Base64\`, or \`GetAZs\` in a resource's props no longer forces that file back to the run path. What folds is the call, not calls in general — the name has to be one this lexicon registered and opted in, imported from this lexicon by the file using it. A same-file resource passed to one (\`Ref(bucket)\` where \`bucket\` is declared in the same file) still falls back, since the intrinsic needs the real constructed resource.
 
 Here is a complete example using all intrinsic functions:
 
@@ -412,7 +418,7 @@ 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.
+A top-level composite call assigned directly to an export — like \`healthApi\` above — is one of the patterns [folding](/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
 
@@ -645,6 +651,12 @@ Most splitting use cases are better served by other mechanisms:
         description: "Built-in lint rules and post-synth checks for AWS CloudFormation",
         content: `The AWS lexicon ships lint rules that run during \`chant lint\` and post-synth checks that validate the serialized CloudFormation output after \`chant build\`.
 
+This page explains the most commonly hit rules in depth. For the complete list —
+every rule the lexicon registers, generated from the registration itself so it
+cannot fall behind — see [All Rules](../rules/). The security-hardening rules
+(WAW032 onward) also carry remediation guidance and upstream references in the
+[audit rules reference](/chant/lint-rules/audit-rules/).
+
 ## Lint rules
 
 Lint rules analyze your TypeScript source code before build.
@@ -1135,7 +1147,12 @@ The lexicon also provides MCP (Model Context Protocol) tools and resources that
       },
     ],
     sidebarExtra: [
+      // buildSidebar declines to link the generated `rules` page when a
+      // `lint-rules` extraPage exists, so the complete table needs an explicit
+      // entry — under a label that distinguishes it from the prose page.
+      { label: "All Rules (generated)", slug: "rules" },
       { label: "Deploying to EKS", slug: "eks-kubernetes" },
+      { label: "Nested Stacks", slug: "nested-stacks" },
     ],
   };