@intentius/chant 0.108.1 → 0.109.0

package/src/composite.ts

@@ -134,6 +134,16 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
       }
     }
 
+    // chant#3608 — every member records the composite that built it, here,
+    // when the instance is made. A member destructured from the call
+    // (`export const { vpc } = VpcDefault({})`) is never expanded, so this is
+    // the only trace that a composite wrote it; `collectEntities` reads it
+    // through {@link compositeOfMember}. A nested instance recorded its own
+    // members first and the first record is kept, so a member keeps its
+    // innermost composite. Kept off the provenance record so the composite
+    // `expandComposite` records for an instance exported whole is unchanged.
+    markCompositeMembers(members, compositeName);
+
     // Define `members` and `_definition` as non-enumerable so spreading a
     // composite instance (`...someComposite`) only exposes the actual member
     // resources, not the framework's bookkeeping properties. Without this, a
@@ -156,6 +166,33 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
   return definition;
 }
 
+/** Non-enumerable, symbol-keyed: invisible to serializers, spreads and comparisons, like provenance. */
+const COMPOSITE_MEMBER_OF = Symbol.for("chant.composite.memberOf");
+
+/** Record `compositeName` on each declarable member, descending into nested instances. First record wins. */
+function markCompositeMembers(members: object, compositeName: string): void {
+  for (const member of Object.values(members)) {
+    if (isCompositeInstance(member)) {
+      markCompositeMembers(member.members, compositeName);
+    } else if (
+      isDeclarable(member) &&
+      Object.isExtensible(member) &&
+      !Object.prototype.hasOwnProperty.call(member, COMPOSITE_MEMBER_OF)
+    ) {
+      Object.defineProperty(member, COMPOSITE_MEMBER_OF, { value: compositeName, enumerable: false, configurable: true });
+    }
+  }
+}
+
+/**
+ * chant#3608 — the composite whose call built `entity`, or `undefined` for an
+ * entity no chant composite built.
+ */
+export function compositeOfMember(entity: object): string | undefined {
+  const name = (entity as Record<symbol, unknown>)[COMPOSITE_MEMBER_OF];
+  return typeof name === "string" ? name : undefined;
+}
+
 /**
  * Expands a CompositeInstance into a flat Map of prefixed entity names to Declarables.
  * Handles nested composites recursively.

package/src/discovery/collect.ts

@@ -1,6 +1,6 @@
 import { basename, dirname, relative, resolve } from "node:path";
 import { isDeclarable, type Declarable } from "../declarable";
-import { isCompositeInstance, expandComposite } from "../composite";
+import { isCompositeInstance, expandComposite, compositeOfMember } from "../composite";
 import { isLexiconOutput } from "../lexicon-output";
 import { DiscoveryError } from "../errors";
 import { setProvenance, type EntityProvenance } from "../provenance";
@@ -43,6 +43,16 @@ function stackPrefix(file: string, buildRoot: string | undefined): string {
  */
 const AUTHORED_ROOT: EntityProvenance["paths"] = { "": { kind: "authored" } };
 
+/**
+ * The record for an entity exported on its own. chant#3608: one destructured
+ * from a composite call also names that composite, so fold provenance reads
+ * its unattributed paths as `unknown` rather than as the file's own `direct`.
+ */
+function authoredProvenance(entity: Declarable, file: string): EntityProvenance {
+  const composite = compositeOfMember(entity);
+  return { sourceFile: file, ...(composite ? { composite } : {}), paths: AUTHORED_ROOT };
+}
+
 /** One entity to be placed into the map, produced by {@link enumerateEntries}. */
 interface PendingEntry {
   /** The un-disambiguated map key this entity would take (export name, indexed
@@ -82,12 +92,12 @@ function enumerateEntries(
     for (const [rawName, value] of sortedExports) {
       const name = exportKey(rawName, file);
       if (isDeclarable(value)) {
-        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
+        entries.push({ bareKey: name, value, file, provenance: authoredProvenance(value, file) });
       } else if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
           const item = value[i];
           if (isDeclarable(item)) {
-            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
+            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: authoredProvenance(item, file) });
           } else if (isCompositeInstance(item)) {
             const indexedName = `${name}_${i}`;
             for (const [expandedName, entity] of expandComposite(indexedName, item)) {

package/src/discovery/fold-import.ts

@@ -52,9 +52,13 @@ import {
   collectCompositeOrigins,
   collectParamDependencies,
   collectTagOrigins,
+  sourceLocationOf,
+  type CompositeCallSite,
   type CompositeParamScope,
 } from "./param-deps";
-import { getInterpolationFields, setPathProvenance } from "../provenance";
+import { getInterpolationFields, getProvenance, setPathProvenance, setProvenance } from "../provenance";
+import { foldProvenanceOfEntities, type FoldProvenance } from "../fold-provenance";
+import { collectEntities } from "./collect";
 import { intrinsicCallFoldsEagerly, intrinsicTagFolds, type IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
 
@@ -1479,6 +1483,13 @@ interface CompositeParamRecorder {
    * `fold()` sees them.
    */
   consts: Map<string, ts.Expression>;
+  /**
+   * chant #3597 — the composite call this body was reached from, when the
+   * fold saw it as written. A call made from already-folded values (the
+   * nested-value path, {@link resolveCompositeCall}) has no node, and its
+   * members record origins without locations.
+   */
+  call?: CompositeCallSite;
 }
 
 /** `{ value }` when `node`'s shape was recognized and resolved (value may itself be `undefined`/`null` — e.g. an optional composite member that wasn't created); `undefined` when the shape isn't one the live resolver understands (a plain literal, etc.) — callers fall back to the original, unchanged handling for that shape. */
@@ -1698,7 +1709,7 @@ async function resolveImportedCall(
 
   if (factory) {
     const args = await resolveCallArguments(node, calleeName, ctx);
-    const interpreted = await interpretCompositeFactory(factory, args, ctx);
+    const interpreted = await interpretCompositeFactory(factory, args, ctx, { file: ctx.file, node });
     if (interpreted) return interpreted.value;
     // Declined — the body's shape passed but something in it did not resolve
     // (an identifier the module's own imports don't reach, a constructor
@@ -1808,7 +1819,17 @@ async function invokeResolvedCallee(
   const packageInternal = ctx.packageRoot !== undefined && isUnderDirectory(modulePath, ctx.packageRoot);
   if (isProjectImport(binding.specifier, ctx.file) && !packageInternal) executionCounts.projectFactoryInvocations += 1;
 
-  return (Fn as (...fnArgs: unknown[]) => unknown)(...args);
+  const result = (Fn as (...fnArgs: unknown[]) => unknown)(...args);
+  // chant#3608 — a host composite invoked rather than interpreted (one the
+  // host publishes, or one whose body interpretation declined) returns the
+  // host's own instance. Mark it as the interpreted form is marked, so an
+  // instance exported whole is expanded and its members, whole or
+  // destructured, are known to come from a composite.
+  const compositeName = (Fn as { compositeName?: unknown }).compositeName;
+  if (typeof compositeName === "string" && isIndexableObject(result) && !isCompositeInstance(result)) {
+    markHostCompositeInstance(result, compositeName);
+  }
+  return result;
 }
 
 /**
@@ -2798,6 +2819,7 @@ function isLiteralPropertyNameNode(node: ts.PropertyName): boolean {
 function compositeParamRecorder(
   factory: InterpretableFactory,
   moduleConsts: ReadonlyMap<string, ts.Expression>,
+  call?: CompositeCallSite,
 ): CompositeParamRecorder {
   const whole = new Set<string>();
   const destructured = new Map<string, string>();
@@ -2828,7 +2850,7 @@ function compositeParamRecorder(
     }
   }
 
-  return { composite: factory.compositeName, scope: { whole, destructured }, consts };
+  return { composite: factory.compositeName, scope: { whole, destructured }, consts, ...(call ? { call } : {}) };
 }
 
 /**
@@ -2852,10 +2874,21 @@ function stampCompositeOrigins(entity: unknown, node: ts.NewExpression, ctx: Res
     }
   }
   if (!propsArg) return;
-  const origins = collectCompositeOrigins(propsArg, recorder.consts, recorder.scope, recorder.composite);
+  stampCompositeCall(entity, recorder);
+  const origins = collectCompositeOrigins(propsArg, recorder.consts, recorder.scope, recorder.composite, recorder.call);
   for (const [path, origin] of Object.entries(origins)) setPathProvenance(entity, path, origin);
 }
 
+/**
+ * chant #3597 — record where the composite call that expanded `entity` was
+ * written, beside the per-path origins and in the same pass. First writer
+ * wins, as for every provenance field, so the innermost call is kept.
+ */
+function stampCompositeCall(entity: object, recorder: CompositeParamRecorder): void {
+  if (!recorder.call) return;
+  setProvenance(entity, { compositeCall: sourceLocationOf(recorder.call.file, recorder.call.node) });
+}
+
 /**
  * chant #3212 — the same record for an entity a registered tag built inside an
  * interpreted factory body (`` table`CREATE TABLE ${props.name} ...` ``).
@@ -2873,7 +2906,16 @@ function stampTagOrigins(entity: unknown, node: ts.TaggedTemplateExpression, ctx
   const interpolations = ts.isTemplateExpression(node.template)
     ? node.template.templateSpans.map((span) => span.expression)
     : [];
-  const origins = collectTagOrigins(interpolations, fields, entity.props, recorder.consts, recorder.scope, recorder.composite);
+  stampCompositeCall(entity, recorder);
+  const origins = collectTagOrigins(
+    interpolations,
+    fields,
+    entity.props,
+    recorder.consts,
+    recorder.scope,
+    recorder.composite,
+    recorder.call,
+  );
   for (const [path, origin] of Object.entries(origins)) setPathProvenance(entity, path, origin);
 }
 
@@ -2892,6 +2934,7 @@ async function interpretCompositeFactory(
   factory: InterpretableFactory,
   args: readonly unknown[],
   ctx: ResolveCtx,
+  call?: CompositeCallSite,
 ): Promise<{ value: unknown } | undefined> {
   // A `Composite()` factory takes exactly one props argument. Anything else at
   // the call site means the callee is being used as something this doesn't
@@ -2932,7 +2975,7 @@ async function interpretCompositeFactory(
     interpretDepth: ctx.interpretDepth + 1,
     // chant #2161 — set unconditionally, and NOT inherited from `ctx`: a nested
     // composite records its own parameters, never the enclosing one's.
-    compositeParams: compositeParamRecorder(factory, scope.consts),
+    compositeParams: compositeParamRecorder(factory, scope.consts, call),
   };
 
   const bind = (name: string, value: unknown): void => {
@@ -2973,7 +3016,7 @@ async function interpretCompositeFactory(
     // rejecting it for not being chant's rather than for being malformed.
     // Chant's own form still goes through `Composite`, unchanged.
     const value = factory.hostForm
-      ? members
+      ? markHostCompositeInstance(members, factory.compositeName)
       : (Composite<void, CompositeMembers>(() => members as CompositeMembers, factory.compositeName))();
     executionCounts.factoryInterpretations += 1;
     return { value };
@@ -2987,6 +3030,53 @@ async function interpretCompositeFactory(
   }
 }
 
+/**
+ * chant#3598 — a host composite instance's own marker. Non-enumerable and
+ * symbol-keyed, like provenance, so nothing that serializes or compares the
+ * exports sees it. It carries the composite's name, which the members object
+ * otherwise has no record of once it is returned.
+ */
+const HOST_COMPOSITE_INSTANCE = Symbol.for("chant.fold.hostCompositeInstance");
+
+/**
+ * Mark `members` as the instance a host's composite produced, and return it
+ * unchanged.
+ *
+ * chant#3608 — every declarable member, and every member of a nested host
+ * instance, is also stamped with the composite, the way `expandComposite`
+ * stamps a chant instance's members. A destructured member is never expanded,
+ * so this is the only record it has that a composite wrote it, and without
+ * it a path the fold did not attribute reads as authored and so `direct`.
+ * `setProvenance` keeps the first writer, and a nested instance was marked
+ * when its own call returned, so a member keeps its innermost composite.
+ */
+function markHostCompositeInstance(members: Record<string, unknown>, compositeName: string): Record<string, unknown> {
+  if (Object.isExtensible(members) && !Object.prototype.hasOwnProperty.call(members, HOST_COMPOSITE_INSTANCE)) {
+    Object.defineProperty(members, HOST_COMPOSITE_INSTANCE, {
+      value: compositeName,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  stampHostCompositeMembers(members, compositeName);
+  return members;
+}
+
+/** Stamp `composite` on each declarable member of a host instance, descending into nested host instances. */
+function stampHostCompositeMembers(members: Record<string, unknown>, compositeName: string): void {
+  for (const member of Object.values(members)) {
+    if (isDeclarable(member)) setProvenance(member, { composite: compositeName });
+    else if (hostCompositeName(member) !== undefined) stampHostCompositeMembers(member as Record<string, unknown>, compositeName);
+  }
+}
+
+/** The composite name a host composite instance was marked with, or `undefined` for any other value. */
+function hostCompositeName(value: unknown): string | undefined {
+  if (!isIndexableObject(value)) return undefined;
+  const name = (value as Record<symbol, unknown>)[HOST_COMPOSITE_INSTANCE];
+  return typeof name === "string" ? name : undefined;
+}
+
 /** Evaluate an admissible factory body's statements in order, binding each `const`, and return the `return` expression's value. */
 async function interpretFactoryBody(
   fn: ts.ArrowFunction | ts.FunctionExpression,
@@ -4850,6 +4940,20 @@ export interface FoldProjectVerdict {
   readonly taintedBy?: { from: string; kind: TaintEdgeKind };
   /** The file's complete export namespace, present only when `verdict` is "fold". */
   readonly exports?: ReadonlyMap<string, unknown>;
+  /**
+   * chant#3598 — fold provenance for the entities this file contributes,
+   * keyed by entity name, in the shape `build()` reports as
+   * `BuildResult.foldProvenance`. Present only when `verdict` is "fold" and
+   * the folded files' entities could be collected (a duplicate entity name
+   * fails collection for the whole set, as it fails a build, and then no
+   * verdict carries it). A file that folds and declares nothing with
+   * properties carries `{}`.
+   *
+   * A "run" file has no entry: foldProject never executes one, so it has no
+   * entities to attribute. That holds under `sandbox` too, where nothing
+   * crosses the child-process wire because no child is started.
+   */
+  readonly foldProvenance?: FoldProvenance;
 }
 
 /**
@@ -4910,12 +5014,29 @@ export async function foldProject(
     })),
   );
 
+  const folded = files.filter((file) => attempts.get(file)?.ok === true && !plan.tainted.has(file));
+  const provenanceByFile = foldProvenanceByFile(
+    folded.map((file) => {
+      const attempt = attempts.get(file);
+      return {
+        file,
+        exports: attempt?.ok === true ? expandHostCompositeExports(Object.fromEntries(attempt.exportedValues)) : {},
+      };
+    }),
+  );
+
   const out = new Map<string, FoldProjectVerdict>();
   for (const file of files) {
     const attempt = attempts.get(file)!;
     const tentative = attempt.ok ? "fold" : "run";
     if (attempt.ok && !plan.tainted.has(file)) {
-      out.set(file, { verdict: "fold", tentative, exports: attempt.exportedValues });
+      const foldProvenance = provenanceByFile?.get(file);
+      out.set(file, {
+        verdict: "fold",
+        tentative,
+        exports: attempt.exportedValues,
+        ...(foldProvenance ? { foldProvenance } : {}),
+      });
       continue;
     }
     out.set(file, {
@@ -4927,3 +5048,124 @@ export async function foldProject(
   }
   return out;
 }
+
+/**
+ * chant#3598 — the folded files' fold provenance, split by declaring file.
+ *
+ * This is `build()`'s computation, not a second one: the same
+ * `collectEntities` over the same folded export namespaces `discover()` hands
+ * it, then `foldProvenanceOfEntities` with `getProvenance`. One call over the
+ * whole folded set rather than one per file, because composite expansion and
+ * cross-directory name disambiguation (#932) are decided over the set and an
+ * entity's name is part of what is being reported. The build root is the
+ * files' common directory, which is what `chant build <dir>` passes when every
+ * file sits under `<dir>`.
+ *
+ * Returns `undefined` when collection throws (a duplicate name), the case
+ * where a build has no entities either.
+ */
+function foldProvenanceByFile(
+  modules: Array<{ file: string; exports: Record<string, unknown> }>,
+): Map<string, FoldProvenance> | undefined {
+  if (modules.length === 0) return new Map();
+  let entities: Map<string, Declarable>;
+  try {
+    entities = collectEntities(modules, commonDirectory(modules.map((m) => m.file)));
+  } catch {
+    return undefined;
+  }
+
+  const byResolved = new Map<string, FoldProvenance>();
+  const out = new Map<string, FoldProvenance>();
+  for (const { file } of modules) {
+    const record: FoldProvenance = {};
+    byResolved.set(resolvePath(file), record);
+    out.set(file, record);
+  }
+
+  const all = foldProvenanceOfEntities(entities, getProvenance);
+  for (const [name, record] of Object.entries(all)) {
+    const sourceFile = getProvenance(entities.get(name) as Declarable)?.sourceFile;
+    const target = sourceFile === undefined ? undefined : byResolved.get(resolvePath(sourceFile));
+    if (target) target[name] = record;
+  }
+  return out;
+}
+
+/**
+ * chant#3598 — a file's exports with every host composite instance replaced by
+ * its members, for {@link foldProvenanceByFile} only.
+ *
+ * A host's registration form (chant#2442) returns the members object the
+ * factory built, not a chant `CompositeInstance`, because wrapping it would run
+ * chant's member validation against the host's own entities. `collectEntities`
+ * expands only chant's instances, so an instance exported whole
+ * (`export const store = Store({...})`) contributed no entity and therefore no
+ * record, while a destructured member, a plain declarable export, did.
+ *
+ * The members are named and stamped the way `expandComposite` names and stamps
+ * a chant instance: `${exportName}${Member}`, with a whole-entity `composite`
+ * origin under the paths the fold already attributed. That origin is written
+ * before `collectEntities` adds its `authored` one, and the first writer wins,
+ * so a path the fold did not attribute is `unknown` rather than `direct`.
+ *
+ * Only a top-level export is expanded. A host instance nested in another
+ * composite's body or placed in an array does not fold today, so its file is
+ * `run` and has no record to give.
+ *
+ * The exports a caller receives in the verdict are the originals.
+ */
+function expandHostCompositeExports(exports: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(exports)) {
+    if (hostCompositeName(value) === undefined) {
+      out[name] = value;
+      continue;
+    }
+    expandHostCompositeInstance(name, value as Record<string, unknown>, name, out);
+  }
+  return out;
+}
+
+/**
+ * chant#3608 — one host instance's members into `out`, a nested host instance
+ * expanded in place under its member's name (`siteMainBucket`), as
+ * `expandComposite` expands a nested chant instance. Every member belongs to
+ * the top-level `instance`; its composite is the innermost one, which
+ * {@link markHostCompositeInstance} already stamped, so the whole-entity
+ * origin names that composite too.
+ */
+function expandHostCompositeInstance(
+  prefix: string,
+  members: Record<string, unknown>,
+  instance: string,
+  out: Record<string, unknown>,
+): void {
+  const compositeName = hostCompositeName(members) as string;
+  for (const [memberName, member] of Object.entries(members)) {
+    if (memberName.length === 0) continue;
+    const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
+    if (hostCompositeName(member) !== undefined) {
+      expandHostCompositeInstance(fullName, member as Record<string, unknown>, instance, out);
+      continue;
+    }
+    if (!isDeclarable(member)) continue;
+    setProvenance(member, { composite: compositeName, compositeInstance: instance });
+    const composite = getProvenance(member)?.composite ?? compositeName;
+    setPathProvenance(member, "", { kind: "composite", composite, instance });
+    out[fullName] = member;
+  }
+}
+
+/** The deepest directory every one of `files` sits under. */
+function commonDirectory(files: readonly string[]): string {
+  const split = files.map((file) => dirname(resolvePath(file)).split(sep));
+  const first = split[0];
+  let depth = first.length;
+  for (const parts of split.slice(1)) {
+    let i = 0;
+    while (i < depth && i < parts.length && parts[i] === first[i]) i++;
+    depth = i;
+  }
+  return first.slice(0, depth).join(sep) || sep;
+}

package/src/discovery/fold-package-composite.test.ts

@@ -96,15 +96,28 @@ describe("lexicon-package and re-exported composites are interpreted (chant#3247
     expect(folded.errors).toEqual([]);
     expect(foldExecutionCounts()).toMatchObject({ factoryInterpretations: 1, factoryInvocations: 0 });
     const fields = folded.foldProvenance.sinkAssignmentActivityLogSink!.fields;
+    // chant#3597 — where the call and each argument were written in main.ts.
+    const file = join(srcDir, "main.ts");
+    const lines = CALL_SINK.split("\n");
+    const line = lines.findIndex((l) => l.includes("ActivityLogSink({")) + 1;
+    const at = (needle: string) => ({ file, line, column: lines[line - 1].indexOf(needle) + 1 });
+    const call = at("ActivityLogSink({");
+    const written: Record<string, string> = {
+      location: 'location: "eastus"',
+      workspaceId: 'workspaceId: "/subscriptions/s/workspaces/logs"',
+    };
     const param = (...parameters: string[]) => ({
       kind: "composite-parameter",
       composite: "ActivityLogSink",
       instance: "sink",
       parameters,
+      call,
+      arguments: parameters.map((parameter) => ({ parameter, ...at(written[parameter]), text: written[parameter] })),
     });
     expect(fields.location).toEqual(param("location"));
     expect(fields["parameters.logAnalytics.value"]).toEqual(param("workspaceId"));
-    expect(fields.name).toEqual({ kind: "composite-literal", composite: "ActivityLogSink", instance: "sink" });
+    expect(fields.name).toEqual({ kind: "composite-literal", composite: "ActivityLogSink", instance: "sink", call });
+    expect(folded.foldProvenance.sinkAssignmentActivityLogSink!.compositeCall).toEqual(call);
 
     // Interpreting is not a second evaluation: the run path writes the same bytes.
     const run = await build(srcDir, [propsSerializer("azure")], undefined, { fold: false, lexicons: ["azure"] });