@intentius/chant 0.18.11 → 0.18.12

package/dist/graph-ir.d.ts

@@ -93,15 +93,27 @@ export interface IRExport {
     /** Producer-side attribute the output reads (e.g. "Arn"). */
     attr?: string;
 }
+/** A cross-stack import this stack consumes — a `Parameter` fed from another
+ * stack's output at deploy time. A viewer matches an import `name` to another
+ * stack's export `name` to draw the cross-stack edge; the parameter's in-stack
+ * consumers are ordinary `$ref` edges to `node` (#513). */
+export interface IRImport {
+    /** Parameter name — the cross-stack handle (e.g. "clusterArn"). */
+    name: string;
+    /** Logical name of the parameter node. */
+    node: string;
+}
 /** The full graph IR for a project at the default (declarable) detail level. */
 export interface GraphIR {
     nodes: IRNode[];
     edges: IREdge[];
     groups: IRGroups;
-    /** Outputs this stack publishes for other stacks to import. Imports are already
-     * nodes (`AWS::CloudFormation::Parameter` etc.); a viewer matches an import's
-     * name to an export's name to draw the cross-stack edge to its producer (#513). */
+    /** Outputs this stack publishes for other stacks to import (#513). */
     exports?: IRExport[];
+    /** Parameters this stack imports from other stacks. A viewer matches an import's
+     * `name` to another stack's export `name` to draw the cross-stack edge; the
+     * parameter's in-stack consumers are ordinary `$ref` edges to it (#513). */
+    imports?: IRImport[];
 }
 /**
  * Build the graph IR from resolved entities (the output of `discover`). Pure and

package/dist/graph-ir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-ir.d.ts","sourceRoot":"","sources":["../src/graph-ir.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.18.11",
+  "version": "0.18.12",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/graph-ir.test.ts

@@ -5,11 +5,17 @@ import { AttrRef } from "./attrref";
 import { LexiconOutput } from "./lexicon-output";
 import { resolveAttrRefs } from "./discovery/resolve";
 import { setProvenance } from "./provenance";
+import { INTRINSIC_MARKER } from "./intrinsic";
 
 function decl<T extends object>(base: T): Declarable & T {
   return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
 }
 
+/** A `Ref`-style intrinsic (CloudFormation `{ Ref: name }` shape). */
+function ref(targetName: string): object {
+  return { [INTRINSIC_MARKER]: true, toJSON: () => ({ Ref: targetName }) };
+}
+
 describe("buildGraphIr", () => {
   test("emits a node per resource with kind, lexicon, and scrubbed attrs", () => {
     const vpc = decl({ lexicon: "gcp", entityType: "Vpc", props: { autoCreateSubnetworks: false } });
@@ -26,6 +32,35 @@ describe("buildGraphIr", () => {
     expect(ir.nodes[0].attrs).not.toHaveProperty("entityType");
   });
 
+  test("resolves a Ref-to-node intrinsic into an edge + $ref, and lists parameter imports (#513)", () => {
+    const cluster = decl({ lexicon: "aws", entityType: "AWS::CloudFormation::Parameter" });
+    const service = decl({ lexicon: "aws", entityType: "AWS::ECS::Service", props: { Cluster: ref("clusterArn") } });
+    const entities = new Map<string, Declarable>([
+      ["clusterArn", cluster],
+      ["service", service],
+    ]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    // The Ref becomes a real dependency edge, not a dropped intrinsic.
+    expect(ir.edges).toContainEqual({ from: "service", to: "clusterArn", kind: "ref", viaAttr: "Cluster" });
+    // attrs mirror the edge as a $ref envelope, not {$intrinsic}.
+    expect(ir.nodes.find((n) => n.id === "service")!.attrs.Cluster).toEqual({ $ref: "clusterArn" });
+    // Parameter nodes are surfaced as import handles.
+    expect(ir.imports).toEqual([{ name: "clusterArn", node: "clusterArn" }]);
+  });
+
+  test("a Ref to a non-node (pseudo-parameter) stays an opaque intrinsic — no phantom edge (#513)", () => {
+    const service = decl({ lexicon: "aws", entityType: "AWS::ECS::Service", props: { Region: ref("AWS::Region") } });
+    const entities = new Map<string, Declarable>([["service", service]]);
+    resolveAttrRefs(entities);
+
+    const ir = buildGraphIr(entities);
+    expect(ir.edges).toEqual([]);
+    expect(ir.nodes[0].attrs.Region).toEqual({ $intrinsic: true });
+    expect(ir.imports).toBeUndefined();
+  });
+
   test("derives ref edges labelled with the consumer property", () => {
     const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
     const subnet = decl({ lexicon: "gcp", entityType: "Subnet", props: { network: new AttrRef(vpc, "id") } });

package/src/graph-ir.ts

@@ -107,15 +107,28 @@ export interface IRExport {
   attr?: string;
 }
 
+/** A cross-stack import this stack consumes — a `Parameter` fed from another
+ * stack's output at deploy time. A viewer matches an import `name` to another
+ * stack's export `name` to draw the cross-stack edge; the parameter's in-stack
+ * consumers are ordinary `$ref` edges to `node` (#513). */
+export interface IRImport {
+  /** Parameter name — the cross-stack handle (e.g. "clusterArn"). */
+  name: string;
+  /** Logical name of the parameter node. */
+  node: string;
+}
+
 /** The full graph IR for a project at the default (declarable) detail level. */
 export interface GraphIR {
   nodes: IRNode[];
   edges: IREdge[];
   groups: IRGroups;
-  /** Outputs this stack publishes for other stacks to import. Imports are already
-   * nodes (`AWS::CloudFormation::Parameter` etc.); a viewer matches an import's
-   * name to an export's name to draw the cross-stack edge to its producer (#513). */
+  /** Outputs this stack publishes for other stacks to import (#513). */
   exports?: IRExport[];
+  /** Parameters this stack imports from other stacks. A viewer matches an import's
+   * `name` to another stack's export `name` to draw the cross-stack edge; the
+   * parameter's in-stack consumers are ordinary `$ref` edges to it (#513). */
+  imports?: IRImport[];
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */
@@ -134,6 +147,22 @@ function relFile(file: string | undefined, projectPath?: string): string | undef
   return file;
 }
 
+/** The logical name a `Ref`-style intrinsic points at, or undefined. Lexicon-
+ * agnostic: reads the intrinsic's `toJSON()` for the CloudFormation `{ Ref: name }`
+ * shape (aws `RefIntrinsic` etc.). A `Ref` to a node is a real dependency edge,
+ * not an opaque intrinsic (#513) — so we resolve it rather than flatten it. */
+function refIntrinsicTarget(value: unknown): string | undefined {
+  try {
+    const json = (value as { toJSON?: () => unknown }).toJSON?.();
+    if (json && typeof json === "object" && typeof (json as { Ref?: unknown }).Ref === "string") {
+      return (json as { Ref: string }).Ref;
+    }
+  } catch {
+    // Unresolvable at graph-build time — leave it as an opaque intrinsic.
+  }
+  return undefined;
+}
+
 /** Resolve the producer (logical name) an AttrRef points at. */
 function refTarget(ref: AttrRef, reverse: Map<object, string>): string | undefined {
   // Nested refs (under `props`) aren't assigned a logical name by resolveAttrRefs,
@@ -143,7 +172,7 @@ function refTarget(ref: AttrRef, reverse: Map<object, string>): string | undefin
 }
 
 /** Project a value into a JSON-safe, scrubbed form. References become `{ $ref }`. */
-function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string>): unknown {
+function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string>, nodeIds: Set<string>): unknown {
   if (value === null) return null;
   const t = typeof value;
   if (t === "string" || t === "number" || t === "boolean") return value;
@@ -157,8 +186,12 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
     const to = refTarget(value, reverse);
     return { $ref: to ? `${to}.${value.attribute}` : value.attribute } satisfies AttrRefEnvelope;
   }
-  // Other intrinsics (interpolations, pseudo-parameters): mark, don't inline.
   if ((value as Record<symbol, unknown>)[INTRINSIC_MARKER] === true) {
+    // A `Ref` to a known node is a real reference — surface it as `$ref` so attrs
+    // match the edge (#513). Other intrinsics (interpolations, pseudo-parameters,
+    // Ref to a non-node) stay opaque.
+    const to = refIntrinsicTarget(value);
+    if (to && nodeIds.has(to)) return { $ref: to } satisfies AttrRefEnvelope;
     return { $intrinsic: true };
   }
 
@@ -168,20 +201,20 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
   // Nested declarables (e.g. an inlined property-kind resource) keep their
   // config in a non-enumerable `props` bag, like top-level nodes — project that.
   if (isDeclarable(value)) {
-    const out = projectConfig(value, seen, reverse);
+    const out = projectConfig(value, seen, reverse, nodeIds);
     seen.delete(value);
     return out;
   }
 
   if (Array.isArray(value)) {
-    const out = value.map((v) => project(v, seen, reverse)).filter((v) => v !== undefined);
+    const out = value.map((v) => project(v, seen, reverse, nodeIds)).filter((v) => v !== undefined);
     seen.delete(value);
     return out;
   }
 
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    const p = project(v, seen, reverse);
+    const p = project(v, seen, reverse, nodeIds);
     if (p !== undefined) out[k] = p;
   }
   seen.delete(value);
@@ -212,10 +245,11 @@ function projectConfig(
   entity: Declarable,
   seen: Set<unknown>,
   reverse: Map<object, string>,
+  nodeIds: Set<string>,
 ): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   for (const [k, v] of configRoots(entity)) {
-    const p = project(v, seen, reverse);
+    const p = project(v, seen, reverse, nodeIds);
     if (p !== undefined) out[k] = p;
   }
   return out;
@@ -239,7 +273,13 @@ function collectEdges(
       }
       return;
     }
-    if ((value as Record<symbol, unknown>)[INTRINSIC_MARKER] === true) return;
+    if ((value as Record<symbol, unknown>)[INTRINSIC_MARKER] === true) {
+      // A `Ref` to a known node (a Parameter, or a resource) is a real dependency
+      // — resolve it to an edge instead of dropping it as an opaque intrinsic (#513).
+      const to = refIntrinsicTarget(value);
+      if (to && to !== from && nodeIds.has(to)) edges.push({ from, to, kind: "ref", viaAttr });
+      return;
+    }
     if (seen.has(value)) return;
     seen.add(value);
     if (Array.isArray(value)) {
@@ -287,7 +327,7 @@ export function buildGraphIr(
       id: name,
       kind: entity.entityType,
       lexicon: entity.lexicon,
-      attrs: projectConfig(entity, new Set(), reverse),
+      attrs: projectConfig(entity, new Set(), reverse, nodeIds),
     };
     if (prov?.composite) node.compositeParent = prov.composite;
     if (prov?.compositeInstance) node.compositeInstance = prov.compositeInstance;
@@ -339,8 +379,17 @@ export function buildGraphIr(
   }
   exports.sort((a, b) => a.name.localeCompare(b.name));
 
+  // Cross-stack imports: parameter nodes are the handles this stack imports by,
+  // matched to another stack's export names (#513). Detected by kind — the aws
+  // `Parameter` is the cross-stack input mechanism.
+  const imports: IRImport[] = nodes
+    .filter((n) => /(^|::)Parameter$/i.test(n.kind))
+    .map((n) => ({ name: n.id, node: n.id }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
   const ir: GraphIR = { nodes, edges, groups };
   if (exports.length) ir.exports = exports;
+  if (imports.length) ir.imports = imports;
   return ir;
 }