@intentius/chant 0.71.1 → 0.72.1

package/src/discovery/fold-import.ts

@@ -17,6 +17,8 @@ import {
   FoldableFunction,
   isFoldableFunction,
   locate,
+  collectSameFileFunctions,
+  constResolvesToResource,
   type FoldedResource,
   type FoldedValue,
   type FoldedIntrinsic,
@@ -307,6 +309,19 @@ export function createFoldSession(
   buildParams?: Readonly<Record<string, BuildParamValue>>,
   lexicons: readonly string[] = [],
   sandbox = false,
+  /**
+   * chant#2438 — package specifiers to allow verbatim, alongside the ones
+   * derived from `lexicons`.
+   *
+   * A chant build's active packages are always `@intentius/chant-lexicon-*`,
+   * so naming lexicons is the whole story there. A caller embedding the fold
+   * path against a host that is not a chant lexicon has packages the naming
+   * convention cannot express: the specification's conformance harness supplies
+   * `@tsad/shapes`, which is its host's own specifier. The boundary is
+   * unchanged, an explicitly named package of this build, only now it can be
+   * named as a specifier rather than only as a lexicon.
+   */
+  lexiconPackages: readonly string[] = [],
 ): FoldSession {
   return {
     intrinsics,
@@ -315,7 +330,7 @@ export function createFoldSession(
     importCache: new Map(),
     resolvePathCache: new Map(),
     buildParams,
-    lexiconPackages: new Set(lexicons.map(lexiconPackageName)),
+    lexiconPackages: new Set([...lexicons.map(lexiconPackageName), ...lexiconPackages]),
     sandbox,
     factoryModules: new Map(),
   };
@@ -764,14 +779,6 @@ function collectLocalBindings(sourceFile: ts.SourceFile): Map<string, LocalBindi
 }
 
 /** `(x) => …` / `function (x) {…}`, possibly wrapped in parens/`as`/`satisfies` — the initializer shapes that make a `const` a function binding. */
-function unwrapFunctionInitializer(node: ts.Expression): ts.ArrowFunction | ts.FunctionExpression | undefined {
-  let current = node;
-  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
-    current = current.expression;
-  }
-  return ts.isArrowFunction(current) || ts.isFunctionExpression(current) ? current : undefined;
-}
-
 /**
  * chant #1373 — every top-level function a file declares, exported or not, as
  * a {@link FoldableFunction}: `function f(...) {...}` and `const f = (...) =>
@@ -786,29 +793,10 @@ function unwrapFunctionInitializer(node: ts.Expression): ts.ArrowFunction | ts.F
  * module-level resource through `externals` only.
  */
 function collectLocalFunctions(sourceFile: ts.SourceFile, ctx: ResolveCtx): Map<string, FoldableFunction> {
-  const consts = new Map(ctx.consts);
-  for (const [name] of [...consts]) {
-    if (constResolvesToResource(ctx.consts, name, new Set())) consts.delete(name);
-  }
-  const functions = new Map<string, FoldableFunction>();
-  const add = (name: string, fn: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression): void => {
-    functions.set(name, new FoldableFunction(name, fn, ctx.file, consts, ctx.externals, ctx.crossFileFailures));
-  };
-
-  for (const statement of sourceFile.statements) {
-    if (ts.isFunctionDeclaration(statement)) {
-      if (statement.name && statement.body) add(statement.name.text, statement);
-      continue;
-    }
-    if (!ts.isVariableStatement(statement)) continue;
-    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
-    for (const decl of statement.declarationList.declarations) {
-      if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
-      const fn = unwrapFunctionInitializer(decl.initializer);
-      if (fn) add(decl.name.text, fn);
-    }
-  }
-  return functions;
+  // chant#2436 — the walk itself, and the `new`-bound stripping that makes it
+  // correct, live in ../fold/fold.ts so a unit-level fold with no externals of
+  // its own binds exactly what a build binds.
+  return collectSameFileFunctions(sourceFile, ctx.consts, ctx.file, ctx.externals, ctx.crossFileFailures);
 }
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -1869,6 +1857,16 @@ interface InterpretableFactory {
   fn: ts.ArrowFunction | ts.FunctionExpression;
   /** `Composite()`'s second argument, or `"anonymous"` when it has none — matching {@link Composite}'s own default. */
   compositeName: string;
+  /**
+   * chant#2442 — the registration form came from a HOST the caller named
+   * ({@link FoldSession.lexiconPackages}), not from chant.
+   *
+   * The members are then the host's own, so they are returned as the factory
+   * produced them rather than wrapped in chant's {@link Composite}, whose
+   * member validation asks for chant's own `Declarable` and would reject an
+   * entity carrying a different marker. Chant's own form is untouched.
+   */
+  hostForm: boolean;
 }
 
 /**
@@ -1939,27 +1937,6 @@ function factoryModuleScopeResolved(
   return scope.resolved;
 }
 
-/**
- * True when a module-level `const` is (transitively) bound to a
- * `new Type(...)`. Mirrors `fold()`'s own `resolvesToResource`, but follows an
- * identifier chain (`const a = new T(); const b = a;`) so aliasing can't smuggle
- * a module-level resource into a factory body — see
- * {@link FactoryModuleScope.consts}.
- */
-function constResolvesToResource(
-  consts: Map<string, ts.Expression>,
-  name: string,
-  seen: Set<string>,
-): boolean {
-  if (seen.has(name)) return false;
-  seen.add(name);
-  const init = consts.get(name);
-  if (init === undefined) return false;
-  if (ts.isNewExpression(init)) return true;
-  if (ts.isIdentifier(init)) return constResolvesToResource(consts, init.text, seen);
-  return false;
-}
-
 /**
  * Find `export const <exportName> = Composite(<fn>, "<name>")` at the top level
  * of `scope`'s module, verifying that `Composite` really is chant's own in that
@@ -1970,7 +1947,7 @@ function findCompositeDefinition(
   scope: FactoryModuleScope,
   exportName: string,
   ctx: ResolveCtx,
-): { fn: ts.ArrowFunction | ts.FunctionExpression; compositeName: string } | undefined {
+): { fn: ts.ArrowFunction | ts.FunctionExpression; compositeName: string; hostForm: boolean } | undefined {
   for (const statement of scope.sourceFile.statements) {
     if (!ts.isVariableStatement(statement)) continue;
     if (!hasExportModifier(statement)) continue;
@@ -1988,7 +1965,16 @@ function findCompositeDefinition(
       // call to it is not a registered composite.
       const compositeBinding = scope.imports.get(init.expression.text);
       if (!compositeBinding || compositeBinding.imported !== "Composite") return undefined;
-      if (!isChantOwnedHelperBinding(compositeBinding, { ...ctx, file: scope.file })) return undefined;
+      // chant's own is the answer for every chant project, and #1082's
+      // provenance question is why: a project-local `function Composite(...)`
+      // shadowing the name is not chant's. chant#2442 adds the case chant had
+      // never had to consider, a HOST supplying the form (`F-Host-Composite`),
+      // which only a caller that named its own host packages can reach. For a
+      // chant build the set holds only `@intentius/chant-lexicon-*`, and no
+      // lexicon exports a `Composite`, so nothing about a chant project moves.
+      const chantOwned = isChantOwnedHelperBinding(compositeBinding, { ...ctx, file: scope.file });
+      const hostOwned = activeLexiconPackage(compositeBinding.specifier, ctx.lexiconPackages) !== undefined;
+      if (!chantOwned && !hostOwned) return undefined;
 
       const [fnArg, nameArg] = init.arguments;
       if (!fnArg || (!ts.isArrowFunction(fnArg) && !ts.isFunctionExpression(fnArg))) return undefined;
@@ -1996,7 +1982,7 @@ function findCompositeDefinition(
       // COR017 requires the literal in practice; anything that is not a plain
       // string literal is not something to guess at.
       if (nameArg !== undefined && !ts.isStringLiteral(nameArg)) return undefined;
-      return { fn: fnArg, compositeName: nameArg ? nameArg.text : "anonymous" };
+      return { fn: fnArg, compositeName: nameArg ? nameArg.text : "anonymous", hostForm: !chantOwned };
     }
   }
   return undefined;
@@ -2044,7 +2030,7 @@ async function resolveInterpretableFactory(
   // Rules 3-5.
   if (findFactorySubsetViolation(definition.fn) !== undefined) return undefined;
 
-  return { scope, fn: definition.fn, compositeName: definition.compositeName };
+  return { scope, fn: definition.fn, compositeName: definition.compositeName, hostForm: definition.hostForm };
 }
 
 /**
@@ -2398,10 +2384,17 @@ async function interpretCompositeFactory(
     // one per module, as the run path has) is the single visible difference:
     // `_id` is a fresh symbol, which nothing outside `CompositeRegistry` — used
     // only by tests — reads.
-    const definition = Composite<void, CompositeMembers>(() => members as CompositeMembers, factory.compositeName);
-    const instance = definition();
+    // chant#2442 — a HOST's registration form produces the host's own members,
+    // so they are returned as the factory built them. Wrapping them in chant's
+    // `Composite` would run chant's member validation, which asks for chant's
+    // own `Declarable` and rejects an entity carrying a different marker —
+    // 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
+      : (Composite<void, CompositeMembers>(() => members as CompositeMembers, factory.compositeName))();
     executionCounts.factoryInterpretations += 1;
-    return { value: instance };
+    return { value };
   } catch (err) {
     // Every other failure here means "this body did not interpret" and the
     // caller invokes instead. Exhausting the depth bound means "we stopped
@@ -4099,6 +4092,20 @@ export interface FoldProjectOptions {
   readonly buildParams?: Readonly<Record<string, BuildParamValue>>;
   /** chant #1093: this build asked for the sandbox, so fold may not reach outside the trusted allowlist. */
   readonly sandbox?: boolean;
+  /**
+   * chant#2438 — package specifiers to follow a bare import into, verbatim,
+   * alongside whatever `lexicons` names.
+   *
+   * For a chant project this is never needed: an active package is always
+   * `@intentius/chant-lexicon-<name>`, which `lexicons` already expresses. It
+   * is here for a caller driving the fold path against a host of its own, where
+   * the package has a name chant's convention cannot spell. The specification's
+   * conformance harness is the first such caller, with `@tsad/shapes`.
+   *
+   * The boundary does not move. This is still an allowlist the caller states
+   * outright, matched by text, and absent it nothing bare resolves at all.
+   */
+  readonly lexiconPackages?: readonly string[];
 }
 
 /** One file's place in a whole-build fold, as {@link foldProject} reports it. */
@@ -4146,6 +4153,7 @@ export async function foldProject(
     options.buildParams,
     options.lexicons ?? [],
     options.sandbox ?? false,
+    options.lexiconPackages ?? [],
   );
   const attempts = new Map<string, FoldFileResult>();
   for (const file of files) attempts.set(file, await tryFoldFile(file, intrinsics, session));

package/src/fold/fold.test.ts

@@ -688,11 +688,17 @@ describe("fold — registered call-form intrinsics (#1044)", () => {
     expect(() => fold(expr, consts, [REF])).toThrow(FoldError);
   });
 
-  test("a registered name SHADOWED by a local const is rejected — the local binding wins, and it isn't the lexicon's", () => {
+  test("a registered name SHADOWED by a local const folds as the LOCAL function, never the lexicon's", () => {
+    // chant#2436 — the local binding wins, which is what this has always
+    // asserted. It used to win by rejecting, because `fold()` had no way to
+    // call a local function; now it wins by being called, which is what a
+    // build does with this file. The registered meaning is still not applied:
+    // the lexicon's `Ref` produces `{ __intrinsic: "Ref" }`, this produces the
+    // arrow's own object.
     const consts = parseConsts(`const Ref = (n) => ({ mine: n }); const x = Ref("db");`);
     const expr = consts.get("x");
     if (!expr) throw new Error("fixture error");
-    expect(() => fold(expr, consts, [REF])).toThrow(FoldError);
+    expect(fold(expr, consts, [REF])).toEqual({ mine: "db" });
   });
 
   test("an unfoldable argument still rejects the whole call", () => {
@@ -765,11 +771,14 @@ describe("fold — registered authoring helpers (#1082)", () => {
     expect((error as FoldError).message).toContain("function call as a value is not foldable: compose(...)");
   });
 
-  test("a registered name SHADOWED by a local const is rejected — the local binding wins, and it isn't chant's", () => {
+  test("a registered name SHADOWED by a local const folds as the LOCAL function, never chant's", () => {
+    // chant#2436 — see the matching case under the intrinsic registry above.
+    // chant's own `phase(name, steps)` yields `{ phase, steps }`; the absence
+    // of `steps` here is what proves the shadowing arrow was the one called.
     const consts = parseConsts(`const phase = (n) => ({ phase: n }); const x = phase("Apply");`);
     const expr = consts.get("x");
     if (!expr) throw new Error("fixture error");
-    expect(() => fold(expr, consts)).toThrow(FoldError);
+    expect(fold(expr, consts)).toEqual({ phase: "Apply" });
   });
 
   test("a registered name used as a METHOD (`ns.phase(...)`) is rejected — only a bare identifier callee folds", () => {
@@ -835,11 +844,13 @@ describe("fold: the ConvergeOp rule builders are registered helpers (#2171)", ()
     }
   });
 
-  test("a rule builder SHADOWED by a local const is still rejected", () => {
+  test("a rule builder SHADOWED by a local const folds as the LOCAL function", () => {
+    // chant#2436 — the builder's own shape is `{ field, op, value }`; this
+    // yields the arrow's `{ f, v }`, so the shadowing binding is the one used.
     const consts = parseConsts(`const gt = (f, v) => ({ f, v }); const x = gt("updateCount", 0);`);
     const expr = consts.get("x");
     if (!expr) throw new Error("fixture error");
-    expect(() => fold(expr, consts)).toThrow(FoldError);
+    expect(fold(expr, consts)).toEqual({ f: "updateCount", v: 0 });
   });
 });
 
@@ -1244,3 +1255,85 @@ describe("constructions as values (chant #1169)", () => {
     });
   });
 });
+
+/**
+ * chant#2436 — a unit-level fold binds the file's own functions.
+ *
+ * The build has bound them since #1373: `fold-import.ts` puts a
+ * {@link FoldableFunction} in `externals` for every top-level declaration
+ * before folding anything. A caller with no module graph, and so no
+ * `externals`, had no way to call one, so `fold()` alone answered `run` for a
+ * shape the build folds. The spec's conformance adapter is exactly such a
+ * caller.
+ *
+ * The binding is derived from the node's own source file, and only when the
+ * caller passed no `externals` at all: a caller that passed one is managing
+ * its own bindings and may have left a name out on purpose.
+ */
+describe("fold — same-file functions without externals (chant#2436)", () => {
+  const foldSource = (src: string): unknown => {
+    const sourceFile = ts.createSourceFile("m.ts", src, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const expr = consts.get("x");
+    if (!expr) throw new Error("fixture has no `x`");
+    return fold(expr, consts);
+  };
+
+  test("a function declaration, exported or not", () => {
+    expect(foldSource("function twice(n) { return n * 2; } const x = twice(21);")).toBe(42);
+    expect(foldSource("export function twice(n) { return n * 2; } const x = twice(21);")).toBe(42);
+  });
+
+  test("an arrow const", () => {
+    expect(foldSource('const label = (s) => ({ label: s }); const x = label("k");')).toEqual({ label: "k" });
+  });
+
+  test("a sibling calling a sibling", () => {
+    expect(foldSource("function a(n) { return b(n) + 1; } function b(n) { return n * 2; } const x = a(10);")).toBe(21);
+  });
+
+  test("recursion terminates on its own base case", () => {
+    expect(foldSource("function down(n) { return n <= 0 ? 0 : down(n - 1); } const x = down(3);")).toBe(0);
+  });
+
+  describe("falls back to run rather than producing a value", () => {
+    const rejects = (src: string) => expect(() => foldSource(src)).toThrow(FoldError);
+
+    test("a body that reads a `new`-bound const, so no duplicate resource is built", () => {
+      // The stripping this relies on is why `collectSameFileFunctions` has one
+      // implementation: the body must read the live instance out of
+      // `externals`, never re-fold the initializer. With no externals there is
+      // no instance to read, so the only correct answer is to fall back.
+      rejects("class B { constructor(_p) {} } const b = new B({}); function f() { return b; } const x = f();");
+    });
+
+    test("through an alias of one, so aliasing cannot smuggle it in", () => {
+      rejects(
+        "class B { constructor(_p) {} } const b = new B({}); const alias = b; function f() { return alias; } const x = f();",
+      );
+    });
+
+    test("a body reading an import, which needs a module graph this entry does not have", () => {
+      rejects('import { thing } from "./other"; function f() { return thing; } const x = f();');
+    });
+
+    test("a body with a statement outside the subset", () => {
+      rejects("function f() { for (;;) {} } const x = f();");
+    });
+
+    test("a name the file never binds", () => {
+      rejects("const x = missing(1);");
+    });
+  });
+
+  test("an imported project-local function is still not called here — that needs the module graph", () => {
+    expect(() => foldSource('import { twice } from "./pure"; const x = twice(21);')).toThrow(FoldError);
+  });
+
+  test("an explicit `externals` is left alone, even when it omits the name", () => {
+    const sourceFile = ts.createSourceFile("m.ts", "function twice(n) { return n * 2; } const x = twice(21);", ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    // The caller said "these are the bindings" and did not include `twice`.
+    expect(() => fold(consts.get("x")!, consts, [], new Map())).toThrow(FoldError);
+  });
+});

package/src/fold/fold.ts

@@ -471,6 +471,131 @@ function carriesLiveObject(value: unknown, seen = new Set<unknown>()): boolean {
   return false;
 }
 
+/**
+ * True when a module-level `const` is (transitively) bound to a `new Type(...)`.
+ * Follows an identifier chain (`const a = new T(); const b = a;`) so aliasing
+ * cannot smuggle a module-level resource into a function body.
+ *
+ * chant#2436 moved this here from ../discovery/fold-import.ts so the two places
+ * that build {@link FoldableFunction}s share one implementation rather than two
+ * that can drift.
+ */
+export function constResolvesToResource(
+  consts: ReadonlyMap<string, ts.Expression>,
+  name: string,
+  seen: Set<string> = new Set(),
+): boolean {
+  if (seen.has(name)) return false;
+  seen.add(name);
+  const init = consts.get(name);
+  if (init === undefined) return false;
+  if (ts.isNewExpression(init)) return true;
+  if (ts.isIdentifier(init)) return constResolvesToResource(consts, init.text, seen);
+  return false;
+}
+
+/** `const f = (…) => …`, through parentheses / `as` / `satisfies`. */
+function unwrapFunctionInitializer(node: ts.Expression): ts.ArrowFunction | ts.FunctionExpression | undefined {
+  let current = node;
+  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
+    current = current.expression;
+  }
+  return ts.isArrowFunction(current) || ts.isFunctionExpression(current) ? current : undefined;
+}
+
+/**
+ * Every top-level function a file declares, exported or not, as a
+ * {@link FoldableFunction}: `function f(...) {...}` and `const f = (...) => …`.
+ *
+ * The markers carry `externals` BY REFERENCE, so the caller may keep filling it
+ * after this returns (which is how a sibling function, or a resource built
+ * later, becomes reachable from a body).
+ *
+ * `consts` drops every `new`-bound const, transitively through aliases: a body
+ * that mentions one must read the live instance out of `externals`, the same
+ * object the module's own fold registered, never re-fold the initializer and
+ * construct a duplicate of a resource discovery already has.
+ *
+ * chant#2436 — one implementation, called both by ../discovery/fold-import.ts
+ * during a build and by {@link fold} when a unit-level fold has no externals of
+ * its own. Getting the `new`-bound stripping wrong yields a wrong value rather
+ * than a fallback to run, which is why there is only one copy of it.
+ */
+export function collectSameFileFunctions(
+  sourceFile: ts.SourceFile,
+  consts: ReadonlyMap<string, ts.Expression>,
+  file: string,
+  externals: ReadonlyMap<string, unknown>,
+  failures?: ReadonlyMap<string, string>,
+): Map<string, FoldableFunction> {
+  const bodyConsts = new Map(consts);
+  for (const [name] of [...bodyConsts]) {
+    if (constResolvesToResource(consts, name, new Set())) bodyConsts.delete(name);
+  }
+
+  const functions = new Map<string, FoldableFunction>();
+  const add = (name: string, fn: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression): void => {
+    functions.set(name, new FoldableFunction(name, fn, file, bodyConsts, externals, failures));
+  };
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(statement)) {
+      if (statement.name && statement.body) add(statement.name.text, statement);
+      continue;
+    }
+    if (!ts.isVariableStatement(statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const decl of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
+      const fn = unwrapFunctionInitializer(decl.initializer);
+      if (fn) add(decl.name.text, fn);
+    }
+  }
+  return functions;
+}
+
+/**
+ * The same-file functions in scope at `node`, for a fold with no `externals`.
+ *
+ * Memoized per (source file, consts map), both of which are objects the caller
+ * holds for the duration of a fold, so a file with many calls walks its
+ * statements once. `undefined` when the node has no file to read, which is the
+ * pre-#2436 answer: the call is not foldable.
+ *
+ * The map is its own `externals`, so a function can call a sibling.
+ */
+function sameFileFunctions(
+  node: ts.Node,
+  consts: Map<string, ts.Expression>,
+): Map<string, FoldableFunction> | undefined {
+  let sourceFile: ts.SourceFile | undefined;
+  try {
+    sourceFile = node.getSourceFile();
+  } catch {
+    return undefined;
+  }
+  if (!sourceFile) return undefined;
+
+  let byConsts = sameFileFunctionCache.get(sourceFile);
+  if (!byConsts) {
+    byConsts = new WeakMap();
+    sameFileFunctionCache.set(sourceFile, byConsts);
+  }
+  const cached = byConsts.get(consts);
+  if (cached) return cached;
+
+  const scope = new Map<string, unknown>();
+  const functions = collectSameFileFunctions(sourceFile, consts, sourceFile.fileName, scope);
+  for (const [name, fn] of functions) scope.set(name, fn);
+  byConsts.set(consts, functions);
+  return functions;
+}
+
+const sameFileFunctionCache = new WeakMap<
+  ts.SourceFile,
+  WeakMap<Map<string, ts.Expression>, Map<string, FoldableFunction>>
+>();
+
 export function isFoldableFunction(value: unknown): value is FoldableFunction {
   return value instanceof FoldableFunction;
 }
@@ -1430,6 +1555,20 @@ export function fold(
       if (isFoldableFunction(callee)) {
         return callFoldableFunction(callee, node, consts, intrinsics, externals);
       }
+      // chant#2436 — the same shape, reached without a build. A caller that
+      // supplied no `externals` has no module graph and so no markers, and a
+      // same-file call fell through to the throw below even though a build
+      // folds it. Derive the file's own functions and call one.
+      //
+      // Only when `externals` is absent. A caller that passed one is managing
+      // its own bindings (a build, which already put the markers there before
+      // folding anything), and second-guessing it here could bind a name it
+      // deliberately left out. A same-file function only: an imported one needs
+      // module resolution, which this module does not do and will not start.
+      if (externals === undefined) {
+        const local = sameFileFunctions(node, consts)?.get(node.expression.text);
+        if (local) return callFoldableFunction(local, node, consts, intrinsics, local.externals);
+      }
     }
 
     // chant #1966 — the fourth call shape: a lexicon-package function its