@intentius/chant 0.19.0 → 0.20.0

package/src/discovery/index.test.ts

@@ -1,8 +1,9 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { discover } from "./index";
 import { mkdir, writeFile, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { DECLARABLE_MARKER } from "../declarable";
 
 describe("discover", () => {
@@ -270,3 +271,192 @@ describe("discover", () => {
     expect(deps2?.size).toBe(0);
   });
 });
+
+describe("discover — fold mode (#1022, epic #1019)", () => {
+  let testDir: string;
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const runtimePath = resolve(thisDir, "../runtime");
+  const compositePath = resolve(thisDir, "../composite");
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-discover-fold-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("default (flag omitted) leaves foldDecisions empty and behavior unchanged", async () => {
+    await writeFile(
+      join(testDir, "app.ts"),
+      `
+        export const entity = {
+          entityType: "Entity",
+          [Symbol.for("chant.declarable")]: true,
+        };
+      `,
+    );
+
+    const result = await discover(testDir);
+
+    expect(result.entities.size).toBe(1);
+    expect(result.foldDecisions).toEqual([]);
+  });
+
+  test("folds a leaf-only module with zero execution (throw sentinel never fires)", async () => {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "main.ts"),
+      `
+        import { Bucket } from "./resources";
+        throw new Error("must never execute — sentinel for #1022 fold verification");
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `,
+    );
+
+    // Sanity check: running this directory the normal way really does fire
+    // the sentinel (a collected import error), proving fold isn't just
+    // accidentally skipping a no-op file.
+    const ran = await discover(testDir);
+    expect(ran.errors.some((e) => e.message.includes("must never execute"))).toBe(true);
+
+    const result = await discover(testDir, { fold: true });
+
+    expect(result.errors).toEqual([]);
+    expect(result.entities.size).toBe(1);
+    expect(result.entities.has("bucket")).toBe(true);
+    const bucket = result.entities.get("bucket")!;
+    expect((bucket as unknown as { lexicon: string }).lexicon).toBe("aws");
+    expect((bucket as unknown as { entityType: string }).entityType).toBe("Test::Bucket");
+
+    expect(result.foldDecisions).toHaveLength(2);
+    const mainDecision = result.foldDecisions.find((d) => d.file.endsWith("main.ts"));
+    expect(mainDecision?.mode).toBe("fold");
+    expect(mainDecision?.resourceCount).toBe(1);
+  });
+
+  // chant #1023 (epic #1019 Phase 5): a bare composite factory call now
+  // folds too — the factory is resolved through the file's imports and
+  // invoked for real with statically-folded props, exactly as a resource
+  // constructor already was (#1022). Fold and run must still agree
+  // byte-for-byte on the expanded entities (this is the unit-level version
+  // of the #1025 fold-vs-run differential).
+  test("a module instantiating a composite folds too; output is unchanged", async () => {
+    await writeFile(
+      join(testDir, "composites.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        import { Composite } from ${JSON.stringify(compositePath)};
+        const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+        export const MyStack = Composite<{ name: string }>((props) => {
+          const bucket = new Bucket({ name: props.name });
+          return { bucket };
+        }, "MyStack");
+      `,
+    );
+    await writeFile(
+      join(testDir, "stack.ts"),
+      `
+        import { MyStack } from "./composites";
+        export const stack = MyStack({ name: "composite-bucket" });
+      `,
+    );
+
+    const withoutFold = await discover(testDir);
+    const withFold = await discover(testDir, { fold: true });
+
+    expect(withFold.errors).toEqual([]);
+    expect(withFold.entities.size).toBe(withoutFold.entities.size);
+    expect([...withFold.entities.keys()].sort()).toEqual([...withoutFold.entities.keys()].sort());
+    expect(withFold.entities.has("stackBucket")).toBe(true);
+    const folded = withFold.entities.get("stackBucket")! as unknown as { props: { name: string } };
+    const run = withoutFold.entities.get("stackBucket")! as unknown as { props: { name: string } };
+    expect(folded.props).toEqual(run.props);
+
+    const stackDecision = withFold.foldDecisions.find((d) => d.file.endsWith("stack.ts"));
+    expect(stackDecision?.mode).toBe("fold");
+    expect(stackDecision?.resourceCount).toBe(1);
+  });
+
+  test("a composite factory defined locally (not resolvable via import) still falls back to run; output is unchanged", async () => {
+    await writeFile(
+      join(testDir, "stack.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        import { Composite } from ${JSON.stringify(compositePath)};
+        const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+        const LocalStack = Composite<{ name: string }>((props) => {
+          const bucket = new Bucket({ name: props.name });
+          return { bucket };
+        }, "LocalStack");
+        export const stack = LocalStack({ name: "composite-bucket" });
+      `,
+    );
+
+    const withoutFold = await discover(testDir);
+    const withFold = await discover(testDir, { fold: true });
+
+    expect(withFold.errors).toEqual([]);
+    expect(withFold.entities.size).toBe(withoutFold.entities.size);
+    expect([...withFold.entities.keys()].sort()).toEqual([...withoutFold.entities.keys()].sort());
+    expect(withFold.entities.has("stackBucket")).toBe(true);
+    const folded = withFold.entities.get("stackBucket")! as unknown as { props: { name: string } };
+    const run = withoutFold.entities.get("stackBucket")! as unknown as { props: { name: string } };
+    expect(folded.props).toEqual(run.props);
+
+    const stackDecision = withFold.foldDecisions.find((d) => d.file.endsWith("stack.ts"));
+    expect(stackDecision?.mode).toBe("run");
+    expect(stackDecision?.reason).toContain("LocalStack");
+  });
+
+  // chant #1020 — the full `discover()` pipeline, not just `tryFoldFile` in
+  // isolation: two files, one importing a resource attribute from the
+  // other, both fold, and `resolveAttrRefs` (the same identity-matching pass
+  // the run path always used) must assign the cross-file AttrRef the
+  // correct logical name with ZERO special-casing — proof the shared
+  // `FoldSession` this module wires into every top-level `tryFoldFile` call
+  // really does give `alb.ts` and `network.ts` the same `vpc` object.
+  test("cross-file resource reference resolves end-to-end: both files fold and the AttrRef gets the right logical name", async () => {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Vpc = createResource("Test::Vpc", "aws", { vpcId: "VpcId" });
+        export const Alb = createResource("Test::Alb", "aws", { albArn: "AlbArn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "network.ts"),
+      `
+        import { Vpc } from "./resources";
+        export const vpc = new Vpc({ cidr: "10.0.0.0/16" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "alb.ts"),
+      `
+        import { Alb } from "./resources";
+        import { vpc } from "./network";
+        export const alb = new Alb({ vpcId: vpc.vpcId });
+      `,
+    );
+
+    const result = await discover(testDir, { fold: true });
+
+    expect(result.errors).toEqual([]);
+    expect(result.foldDecisions.every((d) => d.mode === "fold")).toBe(true);
+    expect(result.entities.has("vpc")).toBe(true);
+    expect(result.entities.has("alb")).toBe(true);
+
+    const alb = result.entities.get("alb")! as unknown as { props: { vpcId: { getLogicalName(): string | undefined; attribute: string } } };
+    expect(alb.props.vpcId.getLogicalName()).toBe("vpc");
+    expect(alb.props.vpcId.attribute).toBe("VpcId");
+  });
+});

package/src/discovery/index.ts

@@ -1,10 +1,86 @@
 import type { Declarable } from "../declarable";
 import type { DiscoveryError } from "../errors";
+import type { IntrinsicDef } from "../lexicon";
 import { findInfraFiles } from "./files";
 import { importModule } from "./import";
 import { collectEntities } from "./collect";
 import { resolveAttrRefs } from "./resolve";
 import { buildDependencyGraph } from "./graph";
+import { tryFoldFile, planFoldTaint, createFoldSession } from "./fold-import";
+import { getProvenance } from "../provenance";
+import type { BuildParamProvenance } from "../provenance";
+import { buildParamValues } from "../build-params";
+import { setBuildParams } from "../params";
+
+/**
+ * Per-file fold-vs-run outcome (chant #1022, epic #1019), populated only
+ * when {@link DiscoveryOptions.fold} was requested. Lets a caller (`chant
+ * build --fold`) report which files skipped module execution and which
+ * fell back to the run path, and why.
+ */
+export interface FoldDecision {
+  /** Absolute path of the source file this decision covers. */
+  file: string;
+  /** "fold" — folded statically, zero execution. "run" — imported/executed as before. */
+  mode: "fold" | "run";
+  /** Why the file fell back to run. Present only when `mode === "run"` and fold was requested. */
+  reason?: string;
+  /** Number of entities the fold produced. Present only when `mode === "fold"`. */
+  resourceCount?: number;
+}
+
+/**
+ * Optional inputs to {@link discover}.
+ */
+export interface DiscoveryOptions {
+  /**
+   * chant #1022/#1023 (epic #1019) — opt-in: for each source file, try to
+   * fold it to `Declarable`/`CompositeInstance` entities statically (no
+   * module execution) before falling back to importing/running it. Anything
+   * the folder can't represent (a non-`new`, non-composite-call export, a
+   * cross-file-only reference, …) falls back per-file — see
+   * {@link planFoldTaint} for the one case where a file that WOULD fold in
+   * isolation is still forced back to run, to keep fold and run from ever
+   * disagreeing about a shared entity's identity. Default `false` — behavior
+   * is unchanged unless requested.
+   */
+  fold?: boolean;
+
+  /**
+   * chant #1039 — lexicon-registered intrinsic tags (e.g. AWS's `Sub`) to
+   * recognize while folding. Threaded down to `tryFoldFile`/the static
+   * folder so a registered tagged template folds instead of falling back to
+   * run. Only meaningful when {@link fold} is set; ignored otherwise.
+   * Default: none (an intrinsic-using file still folds up to that point,
+   * then falls back to run at the unregistered tag).
+   */
+  intrinsics?: IntrinsicDef[];
+
+  /**
+   * chant #1045 Phase 2 — opt-in: whatever would otherwise reach the
+   * in-process `importModule` step (every file, when {@link fold} isn't set;
+   * only the per-file run-fallback remainder, when it is) instead runs
+   * together, isolated, in one sandboxed child process — see
+   * `./sandbox/run.ts`. Folded files are unaffected: fold already executes
+   * zero of a file's own top-level code, so it stays in this process exactly
+   * as it does today. Default `false` — behavior, including performance
+   * (no bundling, no child process, no IPC), is unchanged unless requested.
+   */
+  sandbox?: boolean;
+
+  /**
+   * chant #1064 — this build's resolved build-time parameter values (see
+   * ../build-params.ts's `resolveBuildParams`, driven by the CLI's
+   * `--param`/`--params-file`/declared `env` mapping/`chant.config.ts`
+   * defaults). Populated into `../params.ts`'s shared `params` object
+   * (`setBuildParams`, below) before any project file is imported or folded,
+   * and threaded into the fold session so a `params.<name>` reference
+   * resolves to a literal instead of an unresolved identifier. Default: none
+   * — `params` stays empty, matching a project that declares no
+   * `buildParams` at all.
+   */
+  buildParams?: BuildParamProvenance[];
+}
 
 /**
  * Result of the discovery process
@@ -18,6 +94,11 @@ export interface DiscoveryResult {
   sourceFiles: string[];
   /** Array of errors encountered during discovery */
   errors: DiscoveryError[];
+  /**
+   * Per-file fold-vs-run decisions (#1022). Empty unless
+   * {@link DiscoveryOptions.fold} was set.
+   */
+  foldDecisions: FoldDecision[];
 }
 
 /**
@@ -26,11 +107,25 @@ export interface DiscoveryResult {
  * a dependency graph.
  *
  * @param path - The directory path to discover entities in
+ * @param options - Optional discovery behavior, e.g. {@link DiscoveryOptions.fold}
  * @returns DiscoveryResult with entities, dependencies, sourceFiles, and errors
  */
-export async function discover(path: string): Promise<DiscoveryResult> {
+export async function discover(path: string, options?: DiscoveryOptions): Promise<DiscoveryResult> {
   const errors: DiscoveryError[] = [];
   const sourceFiles: string[] = [];
+  const foldDecisions: FoldDecision[] = [];
+
+  // chant #1064 — populate the shared build-time-parameters object BEFORE any
+  // project file is imported or folded, so both paths observe the identical
+  // values: the fold path substitutes them directly (see
+  // fold-import.ts's `buildExternals`), and a run(-fallback) file that
+  // imports "@intentius/chant/params" for real sees them too, since
+  // `setBuildParams` mutates the shared object in place rather than
+  // rebinding it. Unconditional (not just when `buildParams` is set) so a
+  // stale value from a PRIOR `discover()` call in the same process (tests,
+  // `--watch`) never leaks into a build that supplied none.
+  const buildParamValuesMap = buildParamValues(options?.buildParams ?? []);
+  setBuildParams(buildParamValuesMap);
 
   // Step 1: Scan for TypeScript files
   const files = await findInfraFiles(path);
@@ -38,8 +133,63 @@ export async function discover(path: string): Promise<DiscoveryResult> {
 
   // Step 2: Import all modules
   const modules: Array<{ file: string; exports: Record<string, unknown> }> = [];
+  // chant #1045 Phase 2 — files that would reach the in-process importModule()
+  // call below are instead queued here when options.sandbox is set, and run
+  // together afterward in one isolated child (see the merge step after
+  // collectEntities).
+  const sandboxFiles: string[] = [];
+
+  // Fold path (#1022/#1023): try the static folder on EVERY file first,
+  // independently, before committing any decision. A file that folds
+  // successfully in isolation must still be forced back to run if some
+  // OTHER file that itself falls back to run imports it (directly or
+  // transitively) — otherwise the run-fallback file's real re-import
+  // produces a SECOND, non-identical copy of the same entities this file
+  // already folded, and cross-file AttrRefs between them can never resolve
+  // (see {@link planFoldTaint}'s doc for the full story). This is only
+  // knowable after every file's fold has been attempted, hence the two
+  // passes instead of committing per-file as they're visited.
+  const foldAttempts = new Map<string, Awaited<ReturnType<typeof tryFoldFile>>>();
+  // chant #1020 — ONE session, shared by every top-level `tryFoldFile` call
+  // below AND by any cross-file reference one file's fold attempt makes into
+  // another (see fold-import.ts's `FoldSession` doc): this is what guarantees
+  // a project file imported by several others is folded exactly once, so
+  // every referrer shares the identical constructed Declarable/
+  // CompositeInstance objects rather than each building its own copy.
+  const foldSession = options?.fold ? createFoldSession(options.intrinsics, buildParamValuesMap) : undefined;
+  if (options?.fold) {
+    for (const file of files) {
+      foldAttempts.set(file, await tryFoldFile(file, options.intrinsics, foldSession));
+    }
+  }
+  const taintedFiles = options?.fold
+    ? await planFoldTaint(
+        files,
+        new Map(files.map((file) => [file, foldAttempts.get(file)?.ok === true])),
+      )
+    : new Set<string>();
 
   for (const file of files) {
+    if (options?.fold) {
+      const folded = foldAttempts.get(file)!;
+      if (folded.ok && !taintedFiles.has(file)) {
+        const exportsObj: Record<string, unknown> = {};
+        for (const [name, value] of folded.entities) exportsObj[name] = value;
+        modules.push({ file, exports: exportsObj });
+        foldDecisions.push({ file, mode: "fold", resourceCount: folded.entities.length });
+        continue;
+      }
+      const reason = !folded.ok
+        ? folded.reason
+        : `would fold in isolation, but a file that imports it (directly or transitively) falls back to run — folding independently would create a duplicate, non-identical instance`;
+      foldDecisions.push({ file, mode: "run", reason });
+    }
+
+    if (options?.sandbox) {
+      sandboxFiles.push(file);
+      continue;
+    }
+
     try {
       const exports = await importModule(file);
       modules.push({ file, exports });
@@ -88,9 +238,90 @@ export async function discover(path: string): Promise<DiscoveryResult> {
       dependencies: new Map(),
       sourceFiles,
       errors,
+      foldDecisions,
     };
   }
 
+  // chant #1045 Phase 2 — run the queued sandbox files together, isolated, in
+  // one child process, and merge its already-named, already-ref-resolved
+  // entities in. The child performs its OWN collectEntities/resolveAttrRefs
+  // over just this subset (see ./sandbox/run.ts) rather than sharing live
+  // objects with the fold-only `entities` map above — a real object can't
+  // cross a process boundary, and `planFoldTaint` already guarantees no
+  // folded file is ever referenced by a run-fallback one (or vice versa), so
+  // the two subsets never share cross-references. A name collision between
+  // them is therefore always a genuine duplicate (never the same object
+  // legitimately re-exported), reported exactly like collectEntities' own
+  // same-key check above rather than silently overwritten. (One narrower gap
+  // than the single unified collectEntities call this replaces: cross-
+  // directory stack-prefix disambiguation, #932, is computed separately for
+  // each subset, so a bare-name collision that spans a folded directory and a
+  // run-fallback directory won't be disambiguated the same way a single
+  // combined call would. Not hit by any corpus entry today.)
+  if (options?.sandbox && sandboxFiles.length > 0) {
+    try {
+      // Dynamic, not static — `./sandbox/run` imports `esbuild`, a large CJS
+      // package with its own module-scope filesystem access (the same class
+      // of thing `entity-wire.ts`'s split from `entity-wire-codec.ts` avoids
+      // for `typescript`). `discover()` is re-exported from the package root
+      // (`@intentius/chant`), and project source commonly imports that root
+      // — a STATIC top-level import here would make `esbuild` transitively
+      // reachable, and therefore BUNDLED AND EAGERLY EVALUATED, by every
+      // project file the sandboxed child imports that happens to import
+      // chant itself. A dynamic import is only ever actually reached here,
+      // at runtime, when a caller opts into `sandbox: true` — never from
+      // inside a bundled project file (project code never calls `discover()`
+      // itself), so esbuild only ever bundles it as inert, un-evaluated code
+      // when it's pulled in transitively.
+      const { runFallbackFilesSandboxed } = await import("./sandbox/run");
+      const sandboxResult = await runFallbackFilesSandboxed(sandboxFiles, path);
+      errors.push(...sandboxResult.errors);
+      for (const [name, entity] of sandboxResult.entities) {
+        if (entities.has(name)) {
+          const { DiscoveryError: DiscoveryErrorClass } = await import("../errors");
+          const file = sandboxResult.provenanceByName[name] ?? path;
+          errors.push(new DiscoveryErrorClass(file, `Duplicate export name "${name}" found`, "resolution"));
+          continue;
+        }
+        entities.set(name, entity);
+      }
+
+      // Re-order the merged map to match original file discovery order.
+      // Without this, every fold entity (inserted above via the parent's own
+      // collectEntities call) sorts before every sandboxed entity (appended
+      // by the loop just above) — a fold-block-then-run-block order, not the
+      // per-file INTERLEAVED order a single unified collectEntities call
+      // over `files` would produce. Several downstream consumers iterate the
+      // entities map directly and are order-sensitive (e.g. a serializer's
+      // auto-detected cross-lexicon `Parameters`), so this isn't cosmetic —
+      // uncorrected, it's real, if harmless (still a valid template),
+      // byte-level drift. Ordered by each entity's OWN provenance
+      // (`../provenance.ts`) rather than by which loop produced it: a fold
+      // entity's provenance is read directly (a live object, still in this
+      // process); a sandboxed entity's provenance didn't survive the wire —
+      // `encodeEntitySet` deliberately drops build metadata, not declared
+      // configuration — so `sandboxResult.provenanceByName` (a side channel
+      // the child computes for exactly this, see ./sandbox/run.ts) is used
+      // instead. `Array.prototype.sort` is stable (guaranteed since ES2019),
+      // so entities from the same file (already correctly ordered by
+      // whichever collectEntities call produced them) keep their relative
+      // order — only which FILE's block comes first changes.
+      const fileOrder = new Map(files.map((file, i) => [file, i]));
+      const withIndex = [...entities.entries()].map(([name, entity]) => {
+        const sourceFile = getProvenance(entity)?.sourceFile ?? sandboxResult.provenanceByName[name];
+        const index = sourceFile !== undefined ? fileOrder.get(sourceFile) : undefined;
+        return { name, entity, index: index ?? Number.MAX_SAFE_INTEGER };
+      });
+      withIndex.sort((a, b) => a.index - b.index);
+      entities = new Map(withIndex.map(({ name, entity }) => [name, entity]));
+    } catch (error) {
+      const { DiscoveryError: DiscoveryErrorClass } = await import("../errors");
+      errors.push(
+        new DiscoveryErrorClass(path, error instanceof Error ? error.message : String(error), "resolution"),
+      );
+    }
+  }
+
   // Step 4: Resolve AttrRefs
   try {
     resolveAttrRefs(entities);
@@ -128,5 +359,6 @@ export async function discover(path: string): Promise<DiscoveryResult> {
     dependencies,
     sourceFiles,
     errors,
+    foldDecisions,
   };
 }