@intentius/chant 0.20.0 → 0.21.0

package/src/discovery/fold-import.ts

@@ -1,7 +1,7 @@
 import * as ts from "typescript";
 import { readFile } from "node:fs/promises";
 import { existsSync, statSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, basename, join, isAbsolute, resolve as resolvePath } from "node:path";
+import { dirname, basename, join, sep, isAbsolute, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { isDeclarable, type Declarable } from "../declarable";
@@ -16,8 +16,10 @@ import {
   type FoldedResource,
   type FoldedValue,
   type FoldedIntrinsic,
+  type FoldedHelperCall,
   type SymbolicValue,
 } from "../fold/fold";
+import { isChantOwnedSpecifier } from "../fold/foldable-helpers";
 import { importModule } from "./import";
 import type { IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
@@ -82,6 +84,20 @@ export type FoldFileResult =
        * exact same object every referencing file sees.
        */
       exportedValues: Map<string, unknown>;
+      /**
+       * chant #1044 — the OTHER project files whose exported OBJECTS this
+       * fold consumed (a cross-file `Declarable`, composite instance, or any
+       * other non-primitive reached through `buildExternals`/a re-export).
+       *
+       * Object identity is the thing that cannot survive one side of the
+       * build folding while the other runs, so `planFoldTaint` needs to know
+       * who consumed whose objects: if a file here is forced back to run, the
+       * instance THIS file already captured is not the instance discovery
+       * will collect, and serialization fails on an entity with no logical
+       * name. A primitive (string, number, boolean, null) is never recorded —
+       * it has no identity to disagree about.
+       */
+      liveSources: ReadonlySet<string>;
     }
   | { ok: false; reason: string };
 
@@ -1114,13 +1130,23 @@ async function resolveSymbolicValue(text: string, ctx: ResolveCtx): Promise<unkn
 }
 
 /**
- * Revive a folded value tree: replace any `{__intrinsic}`/`{__symbol}`
- * envelope with the real value it represents. `insideIntrinsic` tracks
- * whether the CURRENT node is (transitively) one of a `{__intrinsic}`'s own
- * `values` — see the module-doc note above on why `{__attrRef}` is only
- * rejected there, not everywhere.
+ * Revive a folded value tree: replace any
+ * `{__intrinsic}`/`{__helper}`/`{__symbol}` envelope with the real value it
+ * represents.
+ *
+ * `requireLiveRefs` tracks whether the CURRENT node is (transitively) an
+ * argument being handed to a real function that will inspect it — a
+ * `{__intrinsic}`'s own interpolated `values`, or a `{__helper}` call's
+ * arguments (chant #1082). In that position a symbolic `{__attrRef}` envelope
+ * is rejected rather than passed along: the receiving implementation needs a
+ * genuine `AttrRef` instance (`instanceof` checks, `WeakRef` derefs — see
+ * `SubIntrinsic`, and `LexiconOutput`'s constructor in ../lexicon-output.ts),
+ * and handing it a look-alike plain object produces output that is wrong
+ * rather than absent. Everywhere else the envelope is left untouched, because
+ * the serializer's generic walker already understands it — see the module-doc
+ * note above.
  */
-async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntrinsic: boolean): Promise<unknown> {
+async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, requireLiveRefs: boolean): Promise<unknown> {
   if (value === null || typeof value !== "object") return value;
 
   // chant #1020 — a REAL, already-constructed live object reached via
@@ -1141,7 +1167,7 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntr
 
   if (Array.isArray(value)) {
     const revived: unknown[] = [];
-    for (const el of value) revived.push(await reviveFoldedValue(el, ctx, insideIntrinsic));
+    for (const el of value) revived.push(await reviveFoldedValue(el, ctx, requireLiveRefs));
     return revived;
   }
 
@@ -1154,17 +1180,33 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntr
     const intrinsic = value as FoldedIntrinsic;
     const Fn = await resolveImportedExport(intrinsic.__intrinsic, ctx);
     if (typeof Fn !== "function") {
-      throw cheapError(`intrinsic tag "${intrinsic.__intrinsic}" did not resolve to a function`);
+      throw cheapError(`intrinsic "${intrinsic.__intrinsic}" did not resolve to a function`);
     }
-    const revivedValues: unknown[] = [];
-    for (const v of intrinsic.values) revivedValues.push(await reviveFoldedValue(v, ctx, true));
-    return (Fn as (...fnArgs: unknown[]) => unknown)(intrinsic.strings, ...revivedValues);
+    // Two authored forms, one envelope family (../fold/fold.ts's
+    // `FoldedIntrinsic`): the tagged template replays as
+    // `Name(strings, ...values)`, the plain call (chant #1044) as
+    // `Name(...args)`. Both hand their interior to the REAL function the
+    // file itself imported, with `requireLiveRefs` — an intrinsic inspects
+    // what it is given (`SubIntrinsic`'s `instanceof` checks, `Ref`'s
+    // `getLogicalName`), so a look-alike `{__attrRef}` envelope must be
+    // rejected here rather than silently serialized as something else.
+    const revived: unknown[] = [];
+    if ("args" in intrinsic) {
+      for (const a of intrinsic.args) revived.push(await reviveFoldedValue(a, ctx, true));
+      return (Fn as (...fnArgs: unknown[]) => unknown)(...revived);
+    }
+    for (const v of intrinsic.values) revived.push(await reviveFoldedValue(v, ctx, true));
+    return (Fn as (...fnArgs: unknown[]) => unknown)(intrinsic.strings, ...revived);
+  }
+
+  if ("__helper" in value) {
+    return reviveHelperCall(value as FoldedHelperCall, ctx);
   }
 
   if ("__attrRef" in value) {
-    if (insideIntrinsic) {
+    if (requireLiveRefs) {
       throw cheapError(
-        "a same-file resource reference inside a folded intrinsic's interpolation is not foldable yet",
+        "a same-file resource reference passed to a folded intrinsic or authoring helper is not foldable yet",
       );
     }
     return value;
@@ -1178,11 +1220,93 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntr
 
   const revived: Record<string, unknown> = {};
   for (const [key, v] of Object.entries(value)) {
-    revived[key] = await reviveFoldedValue(v as FoldedValue, ctx, insideIntrinsic);
+    revived[key] = await reviveFoldedValue(v as FoldedValue, ctx, requireLiveRefs);
   }
   return revived;
 }
 
+/**
+ * chant #1082 — the provenance half of the registered-authoring-helper check
+ * (the shape/name half is `fold()`'s, see ../fold/foldable-helpers.ts's module
+ * doc). Being in the allowlist is not permission to invoke whatever the name
+ * happens to be bound to: the name must be bound by THIS FILE'S OWN `import`,
+ * and that import must actually come from chant. Only then is the real
+ * function called, with the folded arguments — the same function the run path
+ * would have called, from the same module the source itself named, so fold
+ * cannot diverge from run by construction.
+ *
+ * Anything short of that throws, which falls the whole file back to run: a
+ * local `function phase(...)`, a `phase` imported from the project's own
+ * helpers, a chant-owned import that turns out not to be a function.
+ */
+async function reviveHelperCall(call: FoldedHelperCall, ctx: ResolveCtx): Promise<unknown> {
+  const name = call.__helper;
+  const binding = ctx.imports.get(name);
+  if (!binding) {
+    throw cheapError(`authoring helper "${name}(...)" is not a resolvable import`);
+  }
+  if (!isChantOwnedHelperBinding(binding, ctx)) {
+    throw cheapError(
+      `"${name}" is imported from "${binding.specifier}", which is not chant's own — ` +
+        `only chant's registered authoring helpers fold as calls`,
+    );
+  }
+
+  const Fn = await resolveImportedExport(name, ctx);
+  if (typeof Fn !== "function") {
+    throw cheapError(`authoring helper "${name}" did not resolve to a function`);
+  }
+
+  // `requireLiveRefs` — a helper receives its arguments as real values and may
+  // inspect them (`output()` derefs the ref's `WeakRef` parent), so a symbolic
+  // `{__attrRef}` envelope is rejected here rather than silently wrapped into
+  // a wrong result. A ref that resolved cross-file to a genuine live `AttrRef`
+  // passes straight through (see `reviveFoldedValue`'s early return).
+  const args: unknown[] = [];
+  for (const arg of call.args) args.push(await reviveFoldedValue(arg, ctx, true));
+  return (Fn as (...fnArgs: unknown[]) => unknown)(...args);
+}
+
+/**
+ * True when `binding` names a helper import chant itself owns: a published
+ * chant package specifier ({@link isChantOwnedSpecifier}), or — for in-repo
+ * and test callers, which import chant-core by relative/absolute path the way
+ * this module's own fixtures do — a specifier that resolves to a file inside
+ * chant-core's own tree.
+ *
+ * The path arm resolves only for a relative/absolute specifier, never a bare
+ * one: resolving an arbitrary bare specifier here would reintroduce the
+ * pathological cold-resolution cost chant#1020 measured (see
+ * {@link fastResolveBareSpecifier}), and a bare specifier chant publishes is
+ * already covered by the text arm.
+ */
+function isChantOwnedHelperBinding(binding: ImportBinding, ctx: ResolveCtx): boolean {
+  if (isChantOwnedSpecifier(binding.specifier)) return true;
+  if (!isProjectFileSpecifier(binding.specifier)) return false;
+  let targetPath: string;
+  try {
+    targetPath = resolveModulePathMemoized(binding.specifier, ctx.file, ctx.resolvePathCache);
+  } catch {
+    return false;
+  }
+  const root = chantCoreRoot();
+  return targetPath === root || targetPath.startsWith(root + sep);
+}
+
+/**
+ * chant-core's own module root — `packages/core/src` in this repo,
+ * `<pkg>/dist` in a published install — derived from THIS module's location.
+ * Pure string arithmetic on `import.meta.url`, no filesystem access at all, so
+ * it is safe in the #1045 sandbox child (which locks reads to an allowlist);
+ * lazy and memoized purely to avoid doing it per call.
+ */
+let chantCoreRootMemo: string | undefined;
+function chantCoreRoot(): string {
+  // .../<root>/discovery/fold-import.ts -> .../<root>
+  chantCoreRootMemo ??= dirname(dirname(fileURLToPath(import.meta.url)));
+  return chantCoreRootMemo;
+}
+
 /** Revive every value in a folded props/attributes object (see {@link reviveFoldedValue}). */
 async function reviveFoldedProps(
   props: { [key: string]: FoldedValue },
@@ -1220,11 +1344,27 @@ async function resolveResourceEntity(
   // real runtime values before constructing the entity. A no-op walk when
   // this file used no registered intrinsics (the overwhelming majority of
   // cases today).
-  let props: Record<string, unknown>;
-  let attributes: Record<string, unknown> | undefined;
+  //
+  // chant #1082 — when `spec.args` is present the constructor's argument list
+  // isn't the classic `(props)`/`(props, attributes)` shape (AWS's `Parameter`
+  // is `(type, props)`), so revive the whole list and spread it below instead
+  // of reviving `spec.props`, which in that case is only a view onto one of
+  // its entries and would be double-counted.
+  let ctorArgs: unknown[];
   try {
-    props = await reviveFoldedProps(spec.props, ctx);
-    attributes = spec.attributes ? await reviveFoldedProps(spec.attributes, ctx) : undefined;
+    if (spec.args) {
+      ctorArgs = [];
+      for (const arg of spec.args) ctorArgs.push(await reviveFoldedValue(arg, ctx, false));
+    } else {
+      const props = await reviveFoldedProps(spec.props, ctx);
+      // The runtime constructor's optional second argument (`attributes` —
+      // CFN's DependsOn/Condition/DeletionPolicy/…, see createResource in
+      // ../runtime.ts) is only present in `spec` when the source actually
+      // passed one (see foldResource in ../fold/fold.ts). Passing `undefined`
+      // when it's absent matches the run path's own default
+      // (`attributes ?? {}` inside the constructor).
+      ctorArgs = [props, spec.attributes ? await reviveFoldedProps(spec.attributes, ctx) : undefined];
+    }
   } catch (err) {
     return {
       ok: false,
@@ -1264,17 +1404,10 @@ async function resolveResourceEntity(
     return { ok: false, reason: `"${binding.imported}" from "${binding.specifier}" is not a constructor` };
   }
 
-  // The runtime constructor's optional second argument (`attributes` —
-  // CFN's DependsOn/Condition/DeletionPolicy/…, see createResource in
-  // ../runtime.ts) is only present in `spec` when the source actually passed
-  // one (see foldResource in ../fold/fold.ts). Passing `undefined` when it's
-  // absent matches the run path's own default (`attributes ?? {}` inside the
-  // constructor).
-  const ResourceCtor = Ctor as new (
-    props: Record<string, unknown>,
-    attributes?: Record<string, unknown>,
-  ) => Declarable;
-  const entity = new ResourceCtor(props, attributes);
+  // Constructed with exactly the arguments the source wrote (see the revival
+  // block above for how `ctorArgs` was built for each of the two shapes).
+  const ResourceCtor = Ctor as new (...ctorArguments: unknown[]) => Declarable;
+  const entity = new ResourceCtor(...ctorArgs);
   return { ok: true, entity };
 }
 
@@ -1394,9 +1527,11 @@ async function buildExternals(
   imports: Map<string, ImportBinding>,
   namespaceImports: Map<string, NamespaceImportBinding>,
   session: FoldSession,
-): Promise<{ externals: Map<string, unknown>; failures: Map<string, string> }> {
+): Promise<{ externals: Map<string, unknown>; failures: Map<string, string>; liveSources: Set<string> }> {
   const externals = new Map<string, unknown>();
   const failures = new Map<string, string>();
+  // chant #1044 — see `FoldFileResult.liveSources`.
+  const liveSources = new Set<string>();
 
   for (const [localName, binding] of imports) {
     // chant #1064 — a named `params` import that resolves to chant-core's own
@@ -1468,7 +1603,9 @@ async function buildExternals(
       continue;
     }
     if (result.exportedValues.has(binding.imported)) {
-      externals.set(localName, result.exportedValues.get(binding.imported));
+      const value = result.exportedValues.get(binding.imported);
+      externals.set(localName, value);
+      if (hasObjectIdentity(value)) liveSources.add(targetPath);
     } else {
       failures.set(
         localName,
@@ -1494,9 +1631,28 @@ async function buildExternals(
     // access on it (`ns.someExport`) is then just an ordinary bracket index,
     // exactly like on a real composite instance (see `isIndexableObject`).
     externals.set(localName, Object.fromEntries(result.exportedValues));
+    for (const value of result.exportedValues.values()) {
+      if (hasObjectIdentity(value)) {
+        liveSources.add(targetPath);
+        break;
+      }
+    }
   }
 
-  return { externals, failures };
+  return { externals, failures, liveSources };
+}
+
+/**
+ * True when `value` is something whose IDENTITY matters across the
+ * fold/run boundary — any object or function, as opposed to a primitive
+ * (chant #1044). Deliberately coarse: an object that merely *contains* a
+ * `Declarable` is as identity-bearing as the Declarable itself, and cheaply
+ * treating every object as such avoids a deep walk whose only payoff would
+ * be keeping a handful of extra files folded inside an entry that already
+ * falls back. See {@link FoldFileResult.liveSources}.
+ */
+function hasObjectIdentity(value: unknown): boolean {
+  return value !== null && (typeof value === "object" || typeof value === "function");
 }
 
 /**
@@ -1540,7 +1696,7 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
     if (scan.declarators.length === 0) return { ok: false, reason: "no foldable resource exports" };
 
     const collected = collectImports(sourceFile);
-    const { externals, failures } = await buildExternals(file, collected.named, collected.namespaces, session);
+    const { externals, failures, liveSources } = await buildExternals(file, collected.named, collected.namespaces, session);
 
     const ctx: ResolveCtx = {
       file,
@@ -1644,11 +1800,16 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
             reason: locatedMessage(decl.specifierNode, `"${imported}" is not exported by "${decl.specifier}"`),
           };
         }
-        applyResolvedValue(exportedName, result.exportedValues.get(imported), entities, exportedValues);
+        const value = result.exportedValues.get(imported);
+        // chant #1044 — a re-export hands another file's OBJECT straight
+        // through under this file's name, so it is a live-identity edge
+        // exactly like an imported binding is (see `liveSources`).
+        if (hasObjectIdentity(value)) liveSources.add(targetPath);
+        applyResolvedValue(exportedName, value, entities, exportedValues);
       }
     }
 
-    return { ok: true, entities, exportedValues };
+    return { ok: true, entities, exportedValues, liveSources };
   } catch (err) {
     // Any unexpected failure degrades to "fall back to run" rather than
     // taking discovery down with it — fold is opt-in, not a new failure mode.
@@ -1725,6 +1886,21 @@ export async function tryFoldFile(
  * the discovered files' relative-import graph, seeded from every file that
  * doesn't fold on its own.
  *
+ * chant #1044 adds the OTHER half of the same hazard, in the opposite
+ * direction along the same edges. Forward taint covers "a run file imports a
+ * folded file"; it does not cover "a FOLDED file consumed the objects of a
+ * file that later got forced to run". Once a plain-call intrinsic can fold,
+ * that second case is easy to reach: in `lexicons/aws/examples/lambda-api`,
+ * `health-api.ts` folds and captures `params.ts`'s real `Parameter` instance
+ * through `Ref(environment)`, while `params.ts` itself is forced to run
+ * because a DIFFERENT sibling (`data-bucket.ts`) imports it and falls back.
+ * Discovery then collects the run instance and serializes the folded one —
+ * the same "Logical name not set" crash described above, arriving from the
+ * other side. So `liveSources` (see {@link FoldFileResult}) contributes
+ * reverse edges here: a tainted file taints every folded file that captured
+ * one of its objects. Only object identity propagates — a file that imported
+ * a plain string from a tainted file has nothing to disagree about.
+ *
  * chant #1020 changes the calculus but not this function: `alb.ts` can now
  * often fold `network.vpc.VpcId` too (see `buildExternals`/`foldFileMemoized`
  * above), by reusing THE EXACT SAME `tryFoldFile("network.ts")` call (memoized
@@ -1740,6 +1916,7 @@ export async function tryFoldFile(
 export async function planFoldTaint(
   files: readonly string[],
   wouldFold: ReadonlyMap<string, boolean>,
+  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
 ): Promise<Set<string>> {
   const fileSet = new Set(files);
 
@@ -1789,6 +1966,22 @@ export async function planFoldTaint(
     edges.set(file, targets);
   }
 
+  // chant #1044 — reverse edges: consumed-file -> the folded files that
+  // captured its objects. Same taint set, same fixpoint walk; see this
+  // function's doc for the crash this closes.
+  for (const [consumer, sources] of liveSources ?? []) {
+    if (!fileSet.has(consumer)) continue;
+    for (const source of sources) {
+      if (!fileSet.has(source)) continue;
+      let back = edges.get(source);
+      if (!back) {
+        back = new Set<string>();
+        edges.set(source, back);
+      }
+      back.add(consumer);
+    }
+  }
+
   const tainted = new Set<string>(files.filter((f) => wouldFold.get(f) !== true));
   const queue = [...tainted];
   while (queue.length > 0) {

package/src/discovery/index.ts

@@ -166,6 +166,15 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
     ? await planFoldTaint(
         files,
         new Map(files.map((file) => [file, foldAttempts.get(file)?.ok === true])),
+        // chant #1044 — which files' OBJECTS each successful fold captured,
+        // so a file forced back to run also invalidates the folds that
+        // already hold its instances (see planFoldTaint's doc).
+        new Map(
+          files.flatMap((file) => {
+            const attempt = foldAttempts.get(file);
+            return attempt?.ok === true ? [[file, attempt.liveSources] as const] : [];
+          }),
+        ),
       )
     : new Set<string>();