@intentius/chant 0.27.0 → 0.29.0

package/src/stack-output.test.ts

@@ -41,9 +41,9 @@ describe("stackOutput", () => {
     expect(out.description).toBe("Primary VPC id");
   });
 
-  test("throws for a value that is neither AttrRef-like nor an Intrinsic", () => {
-    expect(() => stackOutput("not-a-ref" as unknown as AttrRef)).toThrow(
-      "stackOutput(ref): ref must be an attribute reference or an intrinsic wrapping one",
+  test("throws for a value that is neither AttrRef-like, Intrinsic, nor a string literal", () => {
+    expect(() => stackOutput(42 as unknown as AttrRef)).toThrow(
+      "stackOutput(ref): ref must be an attribute reference, an intrinsic wrapping one, or a literal string",
     );
   });
 
@@ -97,6 +97,61 @@ describe("stackOutput", () => {
     expect(out.lexicon).toBe("aws");
     vi.resetModules();
   });
+
+  // chant #1152 — a CloudFormation Parameter carries no attributes at all, so
+  // `Ref(param)` (an intrinsic wrapping the Parameter Declarable directly, not
+  // one of its attributes) could never contain a nested AttrRef for the old
+  // AttrRef-only anchor search to find. Before the fix that meant `firstAttrRef`
+  // always came back empty for this shape and the output's `lexicon` silently
+  // became `"unknown"` — not a thrown error (a Parameter-wrapping `Ref` already
+  // carries the `Intrinsic` marker, so the input-validation guard always
+  // accepted it), but `"unknown"` isn't any real lexicon's partition, so the
+  // output was silently dropped from every serializer's `Outputs` section.
+  const param: Declarable = {
+    lexicon: "aws",
+    entityType: "AWS::CloudFormation::Parameter",
+    [DECLARABLE_MARKER]: true,
+  };
+
+  test("derives lexicon from a Declarable referenced directly by a wrapping intrinsic (Ref(param))", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+
+    const out = stackOutput(ref, { exportName: "EnvironmentName" });
+    expect(out.lexicon).toBe("aws");
+    expect(out.sourceRef).toBe(ref);
+    expect(out.exportName).toBe("EnvironmentName");
+  });
+
+  test("derives lexicon from a Declarable referenced directly, nested inside a further intrinsic (Sub interpolating Ref(param))", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+    const sub = {
+      [INTRINSIC_MARKER]: true as const,
+      values: [ref],
+      toJSON: () => ({ "Fn::Sub": "env-${environment}" }),
+    };
+
+    const out = stackOutput(sub);
+    expect(out.lexicon).toBe("aws");
+  });
+
+  test("an explicit options.lexicon still wins over a Declarable-derived anchor", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+
+    const out = stackOutput(ref, { lexicon: "gcp" });
+    expect(out.lexicon).toBe("gcp");
+  });
 });
 
 describe("isStackOutput", () => {
@@ -116,3 +171,21 @@ describe("isStackOutput", () => {
     expect(isStackOutput(42)).toBe(false);
   });
 });
+
+describe("stackOutput export names and literals", () => {
+  test("carries exportName through to the declaration", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    const out = stackOutput(ref, { exportName: "my-stack-VpcId" });
+    expect(out.exportName).toBe("my-stack-VpcId");
+  });
+
+  test("accepts a literal string with an explicit lexicon", () => {
+    const out = stackOutput("22", { lexicon: "aws", exportName: "my-stack-OpenSSHPort" });
+    expect(out.sourceRef).toBe("22");
+    expect(out.lexicon).toBe("aws");
+  });
+
+  test("rejects a literal without a lexicon", () => {
+    expect(() => stackOutput("22")).toThrow(/options\.lexicon/);
+  });
+});

package/src/stack-output.ts

@@ -6,7 +6,7 @@
  * it via `nestedStack().outputs.name`.
  */
 
-import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { DECLARABLE_MARKER, isDeclarable, type Declarable } from "./declarable";
 import { AttrRef } from "./attrref";
 import { isIntrinsic, type Intrinsic } from "./intrinsic";
 import { isAttrRefLike } from "./utils";
@@ -26,31 +26,56 @@ export interface StackOutput extends Declarable {
   readonly lexicon: string;
   readonly entityType: string;
   readonly kind: "output";
-  /** The exported value: a bare attribute reference, or an intrinsic wrapping
-   * one (e.g. `Join(",", zone.NameServers)`). */
-  readonly sourceRef: AttrRef | Intrinsic;
+  /** The exported value: a bare attribute reference, an intrinsic wrapping
+   * one (e.g. `Join(",", zone.NameServers)`), or a literal string. */
+  readonly sourceRef: AttrRef | Intrinsic | string;
   readonly description?: string;
+  /** When set, the serializer emits a cross-stack export under this name
+   * (CloudFormation `Output.Export.Name`) in addition to the plain output. */
+  readonly exportName?: string;
 }
 
-/** Find the first AttrRef anywhere inside a value (walking intrinsics/objects/
- * arrays), so a wrapping intrinsic can still borrow its parent's lexicon.
- * Duck-type, not `instanceof` (chant #1137): a lexicon built against a
- * separate copy of `@intentius/chant` produces AttrRefs that fail
- * `instanceof AttrRef` here but carry the same shape — missing one would
- * make the walk recurse into the AttrRef's own (unhelpful) fields instead
- * of stopping on it, silently failing to find the anchor. */
-function firstAttrRef(value: unknown, seen = new Set<unknown>()): AttrRef | undefined {
+/** What a wrapping intrinsic's lexicon gets derived from: either a nested
+ * AttrRef (borrow its parent's `.lexicon`) or a Declarable referenced
+ * directly (use its own `.lexicon`). Two shapes, not one, because
+ * `Ref(someEntity)` (chant #1152) wraps the entity itself — a
+ * CloudFormation Parameter carries no attributes at all, so `Ref(param)`
+ * can never contain a nested AttrRef for a single-shape search to find. */
+type Anchor = { readonly kind: "attrRef"; readonly ref: AttrRef } | { readonly kind: "declarable"; readonly entity: Declarable };
+
+/** Find the first AttrRef or directly-referenced Declarable anywhere inside a
+ * value (walking intrinsics/objects/arrays), so a wrapping intrinsic can
+ * still borrow its source's lexicon. Duck-type, not `instanceof` (chant
+ * #1137): a lexicon built against a separate copy of `@intentius/chant`
+ * produces AttrRefs/Declarables that fail `instanceof` here but carry the
+ * same shape (`isDeclarable`'s `Symbol.for` marker is already dual-copy-safe
+ * on its own) — missing one would make the walk recurse into its own
+ * (unhelpful) fields instead of stopping on it, silently failing to find the
+ * anchor. */
+function findAnchor(value: unknown, seen = new Set<unknown>()): Anchor | undefined {
   if (value === null || typeof value !== "object" || seen.has(value)) return undefined;
-  if (isAttrRefLike(value)) return value;
+  if (isAttrRefLike(value)) return { kind: "attrRef", ref: value };
+  if (isDeclarable(value)) return { kind: "declarable", entity: value };
   seen.add(value);
   const children = Array.isArray(value) ? value : Object.values(value as Record<string, unknown>);
   for (const child of children) {
-    const found = firstAttrRef(child, seen);
+    const found = findAnchor(child, seen);
     if (found) return found;
   }
   return undefined;
 }
 
+/** Derive the lexicon an anchor belongs to: an AttrRef borrows its (deref'd)
+ * parent's `.lexicon`; a directly-referenced Declarable reports its own. */
+function anchorLexicon(anchor: Anchor | undefined): string {
+  if (!anchor) return "unknown";
+  if (anchor.kind === "declarable") return anchor.entity.lexicon;
+  const parent = anchor.ref.parent.deref();
+  return parent && typeof (parent as Record<string, unknown>).lexicon === "string"
+    ? ((parent as Record<string, unknown>).lexicon as string)
+    : "unknown";
+}
+
 /**
  * Type guard for StackOutput.
  */
@@ -82,8 +107,8 @@ export function isStackOutput(value: unknown): value is StackOutput {
  * ```
  */
 export function stackOutput(
-  ref: AttrRef | Intrinsic,
-  options?: { description?: string },
+  ref: AttrRef | Intrinsic | string,
+  options?: { description?: string; exportName?: string; lexicon?: string },
 ): StackOutput {
   // Duck-type, not `instanceof` (chant #1137): AttrRef also implements
   // Intrinsic (a global-symbol marker), so `isIntrinsic(ref)` alone already
@@ -92,19 +117,26 @@ export function stackOutput(
   // so the guard's own logic states the invariant explicitly ("ref must be
   // AttrRef-like or Intrinsic") rather than relying on that coincidence,
   // matching the anchor selection right below it, which does misbehave.
-  if (!isAttrRefLike(ref) && !isIntrinsic(ref)) {
-    throw new Error("stackOutput(ref): ref must be an attribute reference or an intrinsic wrapping one");
+  if (typeof ref !== "string" && !isAttrRefLike(ref) && !isIntrinsic(ref)) {
+    throw new Error(
+      "stackOutput(ref): ref must be an attribute reference, an intrinsic wrapping one, or a literal string",
+    );
+  }
+  if (typeof ref === "string" && !options?.lexicon) {
+    throw new Error(
+      "stackOutput(literal): a literal output has no entity to derive its lexicon from — pass options.lexicon",
+    );
   }
   // Derive lexicon from the referenced entity — for a bare AttrRef, its parent;
-  // for an intrinsic (Join etc.), the first AttrRef nested inside it. A
-  // foreign-copy AttrRef failing raw `instanceof` here would fall to
-  // `firstAttrRef`, which (before its own #1137 fix) would also miss it —
+  // for an intrinsic (Join etc.), the first AttrRef or directly-referenced
+  // Declarable nested inside it (chant #1152: `Ref(param)`/`Ref(resource)`
+  // wrap the entity itself, not one of its attributes). A foreign-copy
+  // AttrRef/Declarable failing raw `instanceof` here would fall to
+  // `findAnchor`, which (before its own #1137 fix) would also miss it —
   // silently anchoring on nothing and recording `lexicon: "unknown"`.
-  const anchor = isAttrRefLike(ref) ? ref : firstAttrRef(ref);
-  const parent = anchor?.parent.deref();
-  const lexicon = parent && typeof (parent as Record<string, unknown>).lexicon === "string"
-    ? (parent as Record<string, unknown>).lexicon as string
-    : "unknown";
+  const anchor: Anchor | undefined =
+    typeof ref === "string" ? undefined : isAttrRefLike(ref) ? { kind: "attrRef", ref } : findAnchor(ref);
+  const lexicon = options?.lexicon ?? anchorLexicon(anchor);
 
   const output: StackOutput = {
     [STACK_OUTPUT_MARKER]: true,
@@ -114,6 +146,7 @@ export function stackOutput(
     kind: "output",
     sourceRef: ref,
     description: options?.description,
+    exportName: options?.exportName,
   };
 
   return output;