@intentius/chant 0.19.0 → 0.20.0

package/src/composite.test.ts

@@ -181,6 +181,27 @@ describe("expandComposite", () => {
     expect(expanded.get("sBucket")).toBe(bucket);
   });
 
+  test("is idempotent — repeated expansion does not duplicate shared array props (#1032)", () => {
+    const member = new MockResource({ type: "Bucket", tags: [{ key: "app", value: "x" }] });
+    const Comp = Composite<{}>(() => ({ bucket: member as unknown as Declarable }));
+    const instance = propagate(
+      Comp({}) as never,
+      { tags: [{ key: "env", value: "prod" }] },
+    );
+
+    const first = expandComposite("s", instance);
+    const firstTags = (first.get("sBucket") as unknown as MockResource).props.tags as unknown[];
+    // Expand the SAME singleton instance again (what building one tree twice in a
+    // process does) — must not re-merge onto the already-merged props.
+    const second = expandComposite("s", instance);
+    const secondTags = (second.get("sBucket") as unknown as MockResource).props.tags as unknown[];
+
+    // shared [env] + member [app] = 2 tags, both times — not 3 on the second pass.
+    expect(firstTags).toHaveLength(2);
+    expect(secondTags).toHaveLength(2);
+    expect(secondTags).toEqual(firstTags);
+  });
+
   test("handles empty composite", () => {
     const Empty = Composite<{}>(() => ({} as Record<string, Declarable>));
     const expanded = expandComposite("e", Empty({}));

package/src/composite.ts

@@ -150,7 +150,20 @@ export function expandComposite(
   if (shared) {
     for (const entity of result.values()) {
       if ("props" in entity) {
-        const existing = entity.props as Record<string, unknown>;
+        // Merge shared props onto each member's ORIGINAL props, not its current
+        // props. Members are module-level singletons, so without stashing the
+        // original a second expansion (e.g. building the same tree twice in one
+        // process) would re-merge shared arrays like tags onto the already-merged
+        // value, duplicating them on every rebuild (#1032). Stashing the original
+        // once makes expansion idempotent: same input -> same output, every time.
+        const store = entity as unknown as Record<symbol, unknown>;
+        let existing = store[ORIGINAL_PROPS] as Record<string, unknown> | undefined;
+        if (existing === undefined) {
+          existing = entity.props as Record<string, unknown>;
+          Object.defineProperty(entity, ORIGINAL_PROPS, {
+            value: existing, enumerable: false, configurable: true,
+          });
+        }
         const merged: Record<string, unknown> = {};
         for (const [k, v] of Object.entries(shared)) {
           if (v !== undefined) {
@@ -216,6 +229,12 @@ export function withDefaults<P, M extends CompositeMembers, D extends Partial<P>
  */
 export const SHARED_PROPS = Symbol.for("chant.composite.shared");
 
+/**
+ * Symbol key stashing a member's original (pre-merge) props, so expandComposite()
+ * is idempotent across repeated expansions of the same singleton instance (#1032).
+ */
+export const ORIGINAL_PROPS = Symbol.for("chant.composite.origProps");
+
 /**
  * Attaches shared properties to a composite instance.
  * During expandComposite(), shared props are merged into every member's props.

package/src/config.ts

@@ -6,6 +6,7 @@ import type { OwnershipMarker } from "./ownership";
 import { DEFAULT_SBOM_FORMAT, type SbomFormat } from "./components/verbs/sbom-generator";
 import type { Severity } from "./components/verbs/vuln-scan";
 import type { VulnPolicy } from "./components/verbs/vuln-gate";
+import type { BuildParamsConfig } from "./build-params";
 
 /**
  * Zod schema for ChantConfig validation.
@@ -21,6 +22,20 @@ export const ChantConfigSchema = z.object({
     env: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
   }).optional(),
+  build: z.object({
+    fold: z.boolean().optional(),
+  }).optional(),
+  buildParams: z.record(
+    z.string(),
+    z.object({
+      type: z.enum(["string", "number", "boolean"]),
+      default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+      enum: z.array(z.union([z.string(), z.number(), z.boolean()])).optional(),
+      env: z.string().min(1).optional(),
+      required: z.boolean().optional(),
+      description: z.string().optional(),
+    }),
+  ).optional(),
   release: z.object({
     autoRecord: z.boolean().optional(),
   }).optional(),
@@ -117,6 +132,45 @@ export interface ChantConfig {
     enabled?: boolean;
   };
 
+  /**
+   * `chant build` behavior toggles (#1022, epic #1019).
+   */
+  build?: {
+    /**
+     * Opt-in: fold source modules statically instead of importing/running
+     * them, falling back to run per-file for anything the folder can't
+     * represent (composite factory calls, non-`new` exports, …). Default
+     * `false`. The `--fold` CLI flag overrides this per-invocation (a flag
+     * of `true` always wins; the flag cannot force fold *off* when this is
+     * `true`). See {@link resolveFoldEnabled}.
+     */
+    fold?: boolean;
+
+    /**
+     * chant #1045 Phase 2 — opt-in: run-fallback source files (or, when
+     * `fold` above isn't set, every file) execute together, isolated, in one
+     * sandboxed child process instead of in-process. Default `false`. The
+     * `--sandbox` CLI flag overrides this per-invocation (a flag of `true`
+     * always wins; the flag cannot force sandboxing *off* when this is
+     * `true`). See {@link resolveSandboxEnabled}.
+     */
+    sandbox?: boolean;
+  };
+
+  /**
+   * Build-time parameters (#1064) — values supplied to `chant build` (a
+   * `--param name=value` flag, a `--params-file` JSON file, or a declared
+   * `env` var mapping) and bound to `params.<name>` (`@intentius/chant/params`)
+   * for source to reference, instead of reading `process.env` at module
+   * scope. Distinct from the deploy-time `Parameter` class
+   * (`lexicons/aws/src/parameter.ts`, a CloudFormation `Parameters:` entry
+   * that resolves at stack deploy) — a build-time parameter resolves before
+   * the template is even synthesized, so it can change which resources are
+   * produced at all (e.g. a tier selecting `light` vs `production`). See
+   * {@link resolveBuildParams} in `./build-params.ts`.
+   */
+  buildParams?: BuildParamsConfig;
+
   /**
    * Release-ledger recording behavior (#597, epic #551). Auto-emitting a
    * release record on a successful `chant run --components <name> --env
@@ -265,6 +319,33 @@ export function resolveAutoReleaseDisabled(config: ChantConfig, cliFlag?: boolea
   return config.release?.autoRecord === false;
 }
 
+/**
+ * Whether `chant build` should use the fold path (#1022, epic #1019)
+ * instead of running each source module. Opt-in: off unless the CLI's
+ * `--fold` flag was passed (`cliFlag`) or the project config sets
+ * `build.fold: true` — the flag always wins for that one invocation,
+ * regardless of config.
+ */
+export function resolveFoldEnabled(config: ChantConfig, cliFlag?: boolean): boolean {
+  if (cliFlag) return true;
+  return config.build?.fold === true;
+}
+
+/**
+ * Whether `chant build` should run its run-fallback files (or, without
+ * `--fold`, every file) in an isolated sandboxed child process rather than
+ * in-process (chant #1045 Phase 2). Opt-in: off unless the CLI's `--sandbox`
+ * flag was passed (`cliFlag`) or the project config sets `build.sandbox:
+ * true` — the flag always wins for that one invocation, regardless of
+ * config. Independent of {@link resolveFoldEnabled}: sandboxing without
+ * folding isolates every discovered file; sandboxing with folding isolates
+ * only the per-file run-fallback remainder.
+ */
+export function resolveSandboxEnabled(config: ChantConfig, cliFlag?: boolean): boolean {
+  if (cliFlag) return true;
+  return config.build?.sandbox === true;
+}
+
 /**
  * Resolve which SBOM format a `generate-sbom` step should request (#606),
  * given the project's `chant.config.ts` `sbom.format` and an optional

package/src/discovery/collect.ts

@@ -47,8 +47,21 @@ interface PendingEntry {
 /**
  * Flatten every module's exports into the ordered list of entities they
  * contribute — declarables directly, arrays element-by-element (indexed names),
- * composite instances expanded into members, and LexiconOutputs. Order is
- * preserved so downstream serializers emit resources in a stable order.
+ * composite instances expanded into members, and LexiconOutputs. `modules`
+ * order (one discovered file after another) is preserved so downstream
+ * serializers emit resources in a stable, file-discovery-order sequence.
+ *
+ * Within one module, exports are visited in ascending name order rather than
+ * `Object.entries()`'s own — a real ECMAScript Module namespace object
+ * already enumerates its (non-default) string keys this way per spec
+ * (`[[OwnPropertyKeys]]`, sorted), regardless of source declaration order;
+ * sorting here just makes that the case EXPLICITLY, so this doesn't quietly
+ * depend on whichever loader imported the file preserving (or not) that spec
+ * behavior — chant #1045 Phase 2 found `vite-node` (vitest's own in-process
+ * transform) does NOT sort, unlike plain Node, which made comparing an
+ * in-process build against a real-subprocess one (its differential's whole
+ * point) spuriously "drift" on multi-export-per-file modules whenever the
+ * in-process side ran under vitest.
  */
 function enumerateEntries(
   modules: Array<{ file: string; exports: Record<string, unknown> }>,
@@ -56,7 +69,8 @@ function enumerateEntries(
   const entries: PendingEntry[] = [];
 
   for (const { file, exports } of modules) {
-    for (const [rawName, value] of Object.entries(exports)) {
+    const sortedExports = Object.entries(exports).sort(([a], [b]) => a.localeCompare(b));
+    for (const [rawName, value] of sortedExports) {
       const name = exportKey(rawName, file);
       if (isDeclarable(value)) {
         entries.push({ bareKey: name, value, file, provenance: { sourceFile: file } });