@intentius/chant 0.108.1 → 0.110.0

package/src/provenance.ts

@@ -32,6 +32,13 @@ export interface EntityProvenance {
    * collapse a composite to a single node at coarse diagram detail levels (#494).
    */
   compositeInstance?: string;
+  /**
+   * Where the composite call that expanded this entity was written (chant
+   * #3597): the `WebApp({...})` expression, not the factory body. Recorded
+   * only when the fold interpreted the factory at a call it could see; the
+   * run path and a nested call made from already-folded values leave it unset.
+   */
+  compositeCall?: SourceLocation;
   /**
    * Per-path origins within the entity's `props` (chant #1443). Read with
    * {@link originOfPath}, which does the prefix resolution these keys are
@@ -80,6 +87,12 @@ export interface EntityProvenance {
  *   expression for this path reads no parameter at all. The composite fixes
  *   this field, and no argument at the call site moves it.
  *
+ * - `host` — the authored expression for this path reads a value host code
+ *   produced (INTENTIUS/typescript-as-data#248): a method called on a real
+ *   receiver or an eager lexicon helper (`host-call`), or a value a lexicon
+ *   package exports (`host-value`). The author wrote the call, not the value,
+ *   so ./fold-provenance.ts answers `unknown` rather than `direct`.
+ *
  * The coarse `composite` and the two fine kinds are not alternatives. A build
  * records `composite` when it expanded a composite without interpreting its
  * body (the run path, an inadmissible factory), and that is why
@@ -90,8 +103,49 @@ export type PathOrigin =
   | { kind: "authored" }
   | { kind: "composite"; composite: string; instance: string }
   | { kind: "build-param"; params: string[] }
-  | { kind: "composite-parameter"; composite: string; parameters: string[] }
-  | { kind: "composite-literal"; composite: string };
+  | {
+      kind: "composite-parameter";
+      composite: string;
+      parameters: string[];
+      /**
+       * Where each parameter's argument was written at the composite call
+       * (chant #3597), in `parameters` order. Absent when the build did not
+       * see the call; see {@link ArgumentLocation} for the fallback.
+       */
+      arguments?: ArgumentLocation[];
+    }
+  | { kind: "composite-literal"; composite: string }
+  | { kind: "host"; reason: HostOriginReason };
+
+/** Which host code produced a value: a call it ran, or a value its package exports. */
+export type HostOriginReason = "host-call" | "host-value";
+
+/**
+ * A place in a source file. `file` is absolute, as
+ * {@link EntityProvenance.sourceFile} is; `line` and `column` are 1-based, the
+ * way an editor and `file:line:column` print them.
+ */
+export interface SourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+
+/**
+ * Where one composite parameter's argument was written at the call (chant
+ * #3597). When the call's argument object has a property at the parameter's
+ * path, the location is that property and `text` is the property as written
+ * (`replicas: 3`). When it does not (the parameter was left out, or arrived
+ * through a spread or a non-literal argument), the location is the call's own
+ * and `text` is absent: the call is the nearest place that governs it, and
+ * nothing claims a property that is not there.
+ */
+export interface ArgumentLocation extends SourceLocation {
+  /** The factory parameter path, as in `parameters` (`replicas`, `iam.path`). */
+  parameter: string;
+  /** The innermost property as written at the call, when one is. */
+  text?: string;
+}
 
 /** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
 function isPathPrefix(prefix: string, path: string): boolean {
@@ -114,6 +168,7 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
     existing.sourceFile ??= prov.sourceFile;
     existing.composite ??= prov.composite;
     existing.compositeInstance ??= prov.compositeInstance;
+    existing.compositeCall ??= prov.compositeCall;
     if (prov.paths) {
       existing.paths ??= {};
       for (const [path, origin] of Object.entries(prov.paths)) {
@@ -225,6 +280,8 @@ export function describePathOrigin(origin: PathOrigin): string {
       return `composite ${origin.composite} parameter ${origin.parameters.join(", ")}`;
     case "composite-literal":
       return `composite ${origin.composite} literal`;
+    case "host":
+      return origin.reason;
   }
 }
 

package/src/serializer-walker.test.ts

@@ -118,6 +118,16 @@ describe("walkValue", () => {
     });
   });
 
+  test("an __attrRef envelope naming a property reads the attribute that property's AttrRef carries", () => {
+    // A fold writes `db.Endpoint_Address` as the property name; the attribute
+    // is `Endpoint.Address`.
+    const TestDb = createResource("Test::Db", "test", { Endpoint_Address: "Endpoint.Address" });
+    const db = new TestDb({}) as unknown as Declarable;
+    const names = new Map<Declarable, string>([[db, "MyDB"]]);
+    const value = { __attrRef: { entity: "MyDB", attribute: "Endpoint_Address" } };
+    expect(walkValue(value, names, mockVisitor)).toEqual({ __getAtt: ["MyDB", "Endpoint.Address"] });
+  });
+
   test("resolves standalone __attrRef envelope in plain object", () => {
     const names = new Map<Declarable, string>();
     const value = { __attrRef: { entity: "MyBucket", attribute: "DomainName" } };

package/src/serializer-walker.ts

@@ -21,6 +21,22 @@ export interface SerializerVisitor {
   propertyDeclarable(entity: Declarable, walk: (v: unknown) => unknown): unknown;
 }
 
+/**
+ * The attribute an `{__attrRef}` envelope names. A fold writes the envelope
+ * with the property it read (`db.Endpoint_Address`), and the property's own
+ * AttrRef carries the attribute (`Endpoint.Address`); they differ when the
+ * attribute has a dot. The envelope's name is kept when the entity or
+ * property is not found.
+ */
+function envelopeAttribute(entityName: string, property: string, entityNames: Map<Declarable, string>): string {
+  for (const [entity, name] of entityNames) {
+    if (name !== entityName) continue;
+    const held = (entity as unknown as Record<string, unknown>)[property];
+    return isAttrRefLike(held) ? held.attribute : property;
+  }
+  return property;
+}
+
 /**
  * Recursively walk a value, converting AttrRefs, Intrinsics, Declarables,
  * arrays, and objects using the provided visitor.
@@ -100,7 +116,7 @@ export function walkValue(
   // Handle serialized AttrRef envelopes (produced by AttrRef.toJSON() inside intrinsics)
   if (typeof value === "object" && "__attrRef" in value) {
     const ref = (value as { __attrRef: { entity: string; attribute: string } }).__attrRef;
-    return visitor.attrRef(ref.entity, ref.attribute);
+    return visitor.attrRef(ref.entity, envelopeAttribute(ref.entity, ref.attribute, entityNames));
   }
 
   // Handle objects

package/src/stack-output.ts

@@ -37,6 +37,10 @@ export interface StackOutput extends Declarable {
    * `Output.Condition`) — a condition name, or the condition Declarable
    * itself, resolved to its logical name at serialization (#2068/#2069). */
   readonly condition?: string | Declarable;
+  /** The output's key in the template, when it is not the export name. A
+   * template may use one key for an output and a parameter or resource; a
+   * module cannot export both under that name (#3604). */
+  readonly name?: string;
 }
 
 /** What a wrapping intrinsic's lexicon gets derived from: either a nested
@@ -112,7 +116,7 @@ export function isStackOutput(value: unknown): value is StackOutput {
  */
 export function stackOutput(
   ref: AttrRef | Intrinsic | string,
-  options?: { description?: string; exportName?: string; lexicon?: string; condition?: string | Declarable },
+  options?: { description?: string; exportName?: string; lexicon?: string; condition?: string | Declarable; name?: string },
 ): StackOutput {
   // Duck-type, not `instanceof` (chant #1137): AttrRef also implements
   // Intrinsic (a global-symbol marker), so `isIntrinsic(ref)` alone already
@@ -152,6 +156,7 @@ export function stackOutput(
     description: options?.description,
     exportName: options?.exportName,
     condition: options?.condition,
+    ...(options?.name !== undefined ? { name: options.name } : {}),
   };
 
   return output;

package/src/yaml.test.ts

@@ -26,6 +26,12 @@ describe("emitYAML", () => {
     expect(emitYAML([undefined, 1], 0)).toBe("\n- null\n- 1");
   });
 
+  test("an empty mapping in a list is an item, not nothing", () => {
+    expect(emitYAML([{}], 0)).toBe("\n- {}");
+    expect(emitYAML({ egress: [{}] }, 0)).toBe("\negress:\n  - {}");
+    expect(emitYAML([{ a: undefined }, { b: 1 }], 0)).toBe("\n- {}\n- b: 1");
+  });
+
   test("booleans", () => {
     expect(emitYAML(true, 0)).toBe("true");
     expect(emitYAML(false, 0)).toBe("false");

package/src/yaml.ts

@@ -127,6 +127,10 @@ export function emitYAML(value: unknown, indent: number): string {
               lines.push(`${prefix}  ${key}: ${emitted}`);
             }
           }
+        } else {
+          // An empty mapping is still an item: `egress: [{}]` allows all
+          // egress, and dropping it leaves an empty list.
+          lines.push(`${prefix}- {}`);
         }
       } else {
         lines.push(`${prefix}- ${emitYAML(item, indent + 1).trimStart()}`);