@intentius/chant 0.19.0 → 0.20.0

package/dist/lint/rules/evl003-dynamic-property-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evl003-dynamic-property-access.d.ts","sourceRoot":"","sources":["../../../src/lint/rules/evl003-dynamic-property-access.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAA+B,MAAM,SAAS,CAAC;AA8BrE,eAAO,MAAM,+BAA+B,EAAE,QAU7C,CAAC"}
+{"version":3,"file":"evl003-dynamic-property-access.d.ts","sourceRoot":"","sources":["../../../src/lint/rules/evl003-dynamic-property-access.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAA+B,MAAM,SAAS,CAAC;AAuCrE,eAAO,MAAM,+BAA+B,EAAE,QAU7C,CAAC"}

package/dist/params.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Build-time parameters — the runtime binding source references (chant #1064,
+ * follow-up to epic #1019's fold work).
+ *
+ * This is deliberately NOT `Parameter` (`lexicons/aws/src/parameter.ts`), which
+ * is a deploy-time CloudFormation parameter: it emits a `Parameters:` block and
+ * resolves when the STACK deploys. A build-time parameter resolves before the
+ * template is even synthesized — its value can change WHICH resources are
+ * produced at all (loomster's `LOOM_TIER` selecting `light` vs `production` vs
+ * `production-ha`), which a deploy-time `Parameter` structurally cannot do.
+ *
+ * Project source never reads `process.env` directly to vary a build — that
+ * reads ambient state at module-evaluation time, which `fold()` correctly
+ * cannot reduce to a value (see ../fold/fold.ts). Instead it imports this
+ * module's `params` object:
+ *
+ * ```ts
+ * import { params } from "@intentius/chant/params";
+ * export const tier = params.tier as Tier;
+ * ```
+ *
+ * `params` is declared, validated (type + optional `enum`), and resolved by
+ * the CLI BEFORE discovery ever touches a project file (../build-params.ts's
+ * `resolveBuildParams`, driven by `chant build --param`/`--params-file`/a
+ * declared `env` mapping/`chant.config.ts`'s `buildParams` defaults). Two
+ * consumers read the resolved values, and both see the identical object:
+ *
+ *  - The FOLD path (../discovery/fold-import.ts's `buildExternals`) recognizes
+ *    a named `params` import resolving to *this* module and substitutes the
+ *    already-resolved values directly, with zero import performed — so
+ *    `params.tier` folds to a LITERAL, not a symbolic node. This is the entire
+ *    point: the value is known at build invocation, so there is nothing left
+ *    to defer.
+ *  - The RUN path (a run-fallback file that imports this module for real)
+ *    gets the exact same values, because `setBuildParams` below is called
+ *    once, in-process, before ANY project file is imported or folded —
+ *    mutating this shared object in place rather than replacing the binding,
+ *    so a live-imported reference always observes the current build's values.
+ */
+import type { BuildParamValue } from "./build-params.js";
+export type { BuildParamValue };
+/**
+ * The current build's resolved parameter values, keyed by declared name.
+ * Empty until a build populates it via {@link setBuildParams}. Mutated IN
+ * PLACE (never reassigned) so a real `import { params }` in a run-fallback
+ * file — which captures this exact object reference at import time — always
+ * observes whatever the current build resolved, even though the import
+ * happens after this module was first loaded.
+ */
+export declare const params: Record<string, BuildParamValue>;
+/**
+ * Replace the shared {@link params} object's contents in place. Called once
+ * per build (../discovery/index.ts's `discover()`), before any project file
+ * is imported or folded, with the CLI/config-resolved values
+ * (../build-params.ts's `resolveBuildParams`). Never called from project
+ * source — this is chant's own build-invocation plumbing, not a public
+ * authoring API.
+ */
+export declare function setBuildParams(values: Readonly<Record<string, BuildParamValue>>): void;
+//# sourceMappingURL=params.d.ts.map

package/dist/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../src/params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAM,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GAAG,IAAI,CAGtF"}

package/dist/provenance.d.ts

@@ -8,6 +8,12 @@
  * This is entity-level provenance (which file declared it, and which composite
  * expanded it), not a YAML-line source map. It answers "where did this resource
  * come from?", which is the question an agent asks before changing it.
+ *
+ * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
+ * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
+ * the question ambient `process.env` reads used to answer invisibly. See
+ * ../build-params.ts for declaration/resolution and ../build.ts's
+ * `BuildResult.buildParams` for where a build surfaces it.
  */
 export interface EntityProvenance {
     /** Absolute path of the source file that declared (or exported) the entity. */
@@ -30,4 +36,19 @@ export interface EntityProvenance {
 export declare function setProvenance(entity: object, prov: EntityProvenance): void;
 /** Read an entity's build provenance, if any was stamped. */
 export declare function getProvenance(entity: object): EntityProvenance | undefined;
+/**
+ * One resolved build-time parameter (chant #1064, see ../build-params.ts): its
+ * final value and which source won it, so a build's parameter inputs are
+ * auditable rather than inferred. `source` records precedence, most to least
+ * specific: an explicit `--param`/`--params-file` value beats a declared `env`
+ * mapping, which beats `chant.config.ts`'s `default`.
+ */
+export interface BuildParamProvenance {
+    /** The declared parameter name (a key of `chant.config.ts`'s `buildParams`). */
+    name: string;
+    /** The resolved, type-coerced value actually bound to `params.<name>` for this build. */
+    value: string | number | boolean;
+    /** Which input supplied the value. */
+    source: "cli" | "params-file" | "env" | "default";
+}
 //# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAe1E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAe1E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE1E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,sCAAsC;IACtC,MAAM,EAAE,KAAK,GAAG,aAAa,GAAG,KAAK,GAAG,SAAS,CAAC;CACnD"}

package/dist/terraform/aws-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aws-resources.d.ts","sourceRoot":"","sources":["../../src/terraform/aws-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,+DAA+D;AAC/D,KAAK,SAAS,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,CAAC;AAE/E,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,kBAAkB,iCAAiC,CAAC;AAajE,eAAO,MAAM,eAAe,EAAE,YAAY,EA8DzC,CAAC;AAIF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAErE;AASD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAoB1D"}
+{"version":3,"file":"aws-resources.d.ts","sourceRoot":"","sources":["../../src/terraform/aws-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,+DAA+D;AAC/D,KAAK,SAAS,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,CAAC;AAE/E,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,kBAAkB,iCAAiC,CAAC;AAajE,eAAO,MAAM,eAAe,EAAE,YAAY,EA0HzC,CAAC;AAIF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAErE;AASD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAoB1D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,6 +76,7 @@
   },
   "dependencies": {
     "@dagrejs/dagre": "^3.0.0",
+    "esbuild": "^0.27.0",
     "fflate": "^0.8.2",
     "picomatch": "^4.0.3",
     "tsx": "^4.0.0",

package/src/build-params.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "vitest";
+import { resolveBuildParams, buildParamValues, type BuildParamsConfig } from "./build-params";
+
+const TIER_DEF: BuildParamsConfig = {
+  tier: { type: "string", default: "light", enum: ["light", "production", "production-ha"] },
+};
+
+describe("resolveBuildParams — precedence", () => {
+  test("cli beats params-file beats env beats default", () => {
+    const defs: BuildParamsConfig = { name: { type: "string", default: "d", env: "NAME_ENV" } };
+
+    const cliOnly = resolveBuildParams(defs, { cli: { name: "from-cli" } });
+    expect(cliOnly.errors).toEqual([]);
+    expect(cliOnly.provenance).toEqual([{ name: "name", value: "from-cli", source: "cli" }]);
+
+    const cliOverFile = resolveBuildParams(defs, { cli: { name: "from-cli" }, fromFile: { name: "from-file" } });
+    expect(cliOverFile.provenance).toEqual([{ name: "name", value: "from-cli", source: "cli" }]);
+
+    const fileOverEnv = resolveBuildParams(defs, { fromFile: { name: "from-file" }, env: { NAME_ENV: "from-env" } });
+    expect(fileOverEnv.provenance).toEqual([{ name: "name", value: "from-file", source: "params-file" }]);
+
+    const envOverDefault = resolveBuildParams(defs, { env: { NAME_ENV: "from-env" } });
+    expect(envOverDefault.provenance).toEqual([{ name: "name", value: "from-env", source: "env" }]);
+
+    const defaultOnly = resolveBuildParams(defs, {});
+    expect(defaultOnly.provenance).toEqual([{ name: "name", value: "d", source: "default" }]);
+  });
+
+  test("a parameter with no env mapping ignores an unrelated env var of the same name", () => {
+    const defs: BuildParamsConfig = { name: { type: "string", default: "d" } };
+    const result = resolveBuildParams(defs, { env: { name: "should-not-be-used" } });
+    expect(result.provenance).toEqual([{ name: "name", value: "d", source: "default" }]);
+  });
+});
+
+describe("resolveBuildParams — validation", () => {
+  test("missing value with no default is a build error naming the parameter", () => {
+    const defs: BuildParamsConfig = { tier: { type: "string" } };
+    const result = resolveBuildParams(defs, {});
+    expect(result.provenance).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toContain('"tier"');
+    expect(result.errors[0]).toContain("--param tier=");
+  });
+
+  test("enum violation names the parameter and the allowed values", () => {
+    const result = resolveBuildParams(TIER_DEF, { cli: { tier: "bogus" } });
+    expect(result.provenance).toEqual([]);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]).toContain('"tier"');
+    expect(result.errors[0]).toContain("light");
+    expect(result.errors[0]).toContain("bogus");
+  });
+
+  test("enum success resolves normally", () => {
+    const result = resolveBuildParams(TIER_DEF, { cli: { tier: "production" } });
+    expect(result.errors).toEqual([]);
+    expect(result.provenance).toEqual([{ name: "tier", value: "production", source: "cli" }]);
+  });
+
+  test("unknown --param key (not declared) is a build error", () => {
+    const result = resolveBuildParams(TIER_DEF, { cli: { bogusName: "x" } });
+    expect(result.errors.some((e) => e.includes('"bogusName"') && e.includes("--param"))).toBe(true);
+  });
+
+  test("unknown --params-file key (not declared) is a build error", () => {
+    const result = resolveBuildParams(TIER_DEF, { fromFile: { bogusName: "x" } });
+    expect(result.errors.some((e) => e.includes('"bogusName"') && e.includes("--params-file"))).toBe(true);
+  });
+
+  test("number type coercion, including a non-numeric failure", () => {
+    const defs: BuildParamsConfig = { count: { type: "number" } };
+    const ok = resolveBuildParams(defs, { cli: { count: "42" } });
+    expect(ok.errors).toEqual([]);
+    expect(ok.provenance).toEqual([{ name: "count", value: 42, source: "cli" }]);
+
+    const bad = resolveBuildParams(defs, { cli: { count: "not-a-number" } });
+    expect(bad.provenance).toEqual([]);
+    expect(bad.errors[0]).toContain('"count"');
+    expect(bad.errors[0]).toContain("number");
+  });
+
+  test("boolean type coercion, including an invalid string", () => {
+    const defs: BuildParamsConfig = { flag: { type: "boolean" } };
+    const trueVal = resolveBuildParams(defs, { cli: { flag: "true" } });
+    expect(trueVal.provenance).toEqual([{ name: "flag", value: true, source: "cli" }]);
+
+    const falseVal = resolveBuildParams(defs, { cli: { flag: "false" } });
+    expect(falseVal.provenance).toEqual([{ name: "flag", value: false, source: "cli" }]);
+
+    const bad = resolveBuildParams(defs, { cli: { flag: "nope" } });
+    expect(bad.provenance).toEqual([]);
+    expect(bad.errors[0]).toContain("boolean");
+  });
+
+  test("params-file value must be a scalar, not an object/array", () => {
+    const defs: BuildParamsConfig = { thing: { type: "string" } };
+    const result = resolveBuildParams(defs, { fromFile: { thing: { nested: true } as unknown as string } });
+    expect(result.provenance).toEqual([]);
+    expect(result.errors[0]).toContain('"thing"');
+  });
+
+  test("every failure across multiple parameters is reported at once", () => {
+    const defs: BuildParamsConfig = {
+      a: { type: "string" },
+      b: { type: "number" },
+    };
+    const result = resolveBuildParams(defs, { cli: { b: "nan" } });
+    expect(result.errors).toHaveLength(2);
+  });
+
+  test("no declared params at all — empty resolution, no errors", () => {
+    const result = resolveBuildParams(undefined, {});
+    expect(result).toEqual({ provenance: [], errors: [] });
+  });
+
+  test("required: false — an unresolved optional parameter is simply omitted, not an error", () => {
+    const defs: BuildParamsConfig = { hostedZoneId: { type: "string", required: false } };
+    const result = resolveBuildParams(defs, {});
+    expect(result.errors).toEqual([]);
+    expect(result.provenance).toEqual([]);
+  });
+
+  test("required: false — a supplied value still resolves normally", () => {
+    const defs: BuildParamsConfig = { hostedZoneId: { type: "string", required: false } };
+    const result = resolveBuildParams(defs, { cli: { hostedZoneId: "Z123" } });
+    expect(result.errors).toEqual([]);
+    expect(result.provenance).toEqual([{ name: "hostedZoneId", value: "Z123", source: "cli" }]);
+  });
+});
+
+describe("buildParamValues", () => {
+  test("projects provenance records down to a plain value map", () => {
+    const provenance = [
+      { name: "tier", value: "light" as const, source: "default" as const },
+      { name: "count", value: 3 as const, source: "cli" as const },
+    ];
+    expect(buildParamValues(provenance)).toEqual({ tier: "light", count: 3 });
+  });
+
+  test("empty provenance yields an empty map", () => {
+    expect(buildParamValues([])).toEqual({});
+  });
+});

package/src/build-params.ts

@@ -0,0 +1,207 @@
+import type { BuildParamProvenance } from "./provenance";
+
+/**
+ * Build-time parameter declaration + resolution (chant #1064, follow-up to
+ * epic #1019's fold work — see issue #1064's "DECISION: option 1" comment).
+ *
+ * A build-time parameter is declared in `chant.config.ts`'s `buildParams`
+ * (name, type, optional `default`/`enum`/`env` mapping), supplied to `chant
+ * build` (a `--param name=value` flag, a `--params-file` JSON file, or a
+ * declared `env` var), and referenced from source as `params.<name>` (see
+ * ./params.ts) — never as an ambient `process.env` read. This module owns
+ * declaration + precedence + validation; ./params.ts is the plain runtime
+ * object source references; ../discovery/fold-import.ts is what makes a
+ * `params.<name>` reference fold to a literal instead of a symbolic node.
+ *
+ * This is NOT the deploy-time `Parameter` class (`lexicons/aws/src/parameter.ts`)
+ * — that resolves when a CloudFormation stack deploys; this resolves before
+ * the template is even synthesized, so its value can change which resources
+ * are produced at all. See ./params.ts's module doc for the full distinction.
+ */
+
+/** A build-time parameter's resolved (and declared-default/enum) value — always a scalar. */
+export type BuildParamValue = string | number | boolean;
+
+/**
+ * One declared build-time parameter (`chant.config.ts`'s `buildParams.<name>`).
+ */
+export interface BuildParamDef {
+  /** The value's declared type — supplied strings (CLI flags, env vars, JSON-file strings) are coerced to it. */
+  type: "string" | "number" | "boolean";
+  /** Value used when no `--param`/`--params-file`/declared `env` var supplies one. Omit to require an explicit value every build. */
+  default?: BuildParamValue;
+  /**
+   * Allowed values — a resolved value outside this list is a build error
+   * naming the parameter (never a thrown error from user source). Replaces
+   * the hand-written `if (!VALID.includes(raw)) throw ...` pattern loomster's
+   * `params.ts` files used before migrating to this mechanism.
+   */
+  enum?: readonly BuildParamValue[];
+  /**
+   * Opt-in, EXPLICITLY declared environment-variable fallback — e.g. `env:
+   * "LOOM_TIER"`. This is the only place an env var may feed a build-time
+   * parameter: reading `process.env` directly from project source is never
+   * supported (see ./params.ts's module doc and ../fold/fold.ts's pointed
+   * error for a bare `process` reference). Consulted only when no
+   * `--param`/`--params-file` value was supplied for this parameter.
+   */
+  env?: string;
+  /**
+   * Set `false` to make an unresolved value NOT a build error: `params.<name>`
+   * is simply omitted (reads as plain JS `undefined` — a normal, un-erroring
+   * property access on an object missing that key), instead of the default
+   * behavior of requiring every declared parameter to resolve to something.
+   * For a value that is genuinely optional with no meaningful default (an ARN
+   * that references an existing resource only on some deploys, a CIDR
+   * override, a JSON blob) — the same "unset means the composite decides"
+   * shape a hand-written `process.env.X || undefined` used to express.
+   * Default `true` (a declared parameter must resolve to a value).
+   */
+  required?: boolean;
+  /** Human-readable description, surfaced in error messages and docs generation. */
+  description?: string;
+}
+
+/** A project's full set of declared build-time parameters, keyed by name. */
+export type BuildParamsConfig = Record<string, BuildParamDef>;
+
+/** Raw, not-yet-validated inputs {@link resolveBuildParams} resolves against a project's declared {@link BuildParamsConfig}. */
+export interface BuildParamsInput {
+  /** `--param name=value` flags, repeated — highest precedence. */
+  cli?: Record<string, string>;
+  /** Parsed contents of a `--params-file` JSON file — second precedence. */
+  fromFile?: Record<string, unknown>;
+  /** The process environment, consulted only for a parameter that declares an `env` mapping, and only once `cli`/`fromFile` have no value for it. */
+  env?: Record<string, string | undefined>;
+}
+
+/** Result of resolving a project's declared parameters against one build invocation's inputs. */
+export interface BuildParamsResolution {
+  /** Every successfully resolved parameter — see {@link BuildParamProvenance}. Empty when the project declares none. */
+  provenance: BuildParamProvenance[];
+  /**
+   * Validation failures, each naming the offending parameter — an unknown
+   * `--param`/`--params-file` key, a missing required value, a type mismatch,
+   * or a value outside a declared `enum`. Reported by the CLI as a build
+   * error (chant #1064's acceptance criterion: "not a thrown error inside
+   * user source"); never thrown from here.
+   */
+  errors: string[];
+}
+
+function formatValue(value: unknown): string {
+  return typeof value === "string" ? `"${value}"` : String(value);
+}
+
+/** Coerce `raw` to `def.type`, appending a located error and returning `undefined` on failure. */
+function coerce(name: string, raw: BuildParamValue, def: BuildParamDef, errors: string[]): BuildParamValue | undefined {
+  if (def.type === "string") return String(raw);
+
+  if (def.type === "number") {
+    const n = typeof raw === "number" ? raw : Number(raw);
+    if (Number.isNaN(n)) {
+      errors.push(`build parameter "${name}" must be a number, got ${formatValue(raw)}`);
+      return undefined;
+    }
+    return n;
+  }
+
+  // def.type === "boolean"
+  if (typeof raw === "boolean") return raw;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  errors.push(`build parameter "${name}" must be a boolean ("true" or "false"), got ${formatValue(raw)}`);
+  return undefined;
+}
+
+/**
+ * Resolve a project's declared build-time parameters against one build's
+ * supplied inputs. Precedence per parameter, most to least specific:
+ * `cli` (`--param name=value`) > `fromFile` (`--params-file`) > the
+ * parameter's own declared `env` mapping (only if set) > `def.default`.
+ *
+ * A parameter with no declared `default` and no value from any source is a
+ * build error, not a silently-`undefined` value — a build-time parameter
+ * exists specifically so a project never has an invisible dependency on
+ * ambient state; leaving one unresolved would just reintroduce that under a
+ * different name. Every failure is collected (not thrown), each naming the
+ * offending parameter, so a single invocation reports every problem at once.
+ *
+ * The one opt-out is `def.required: false` — for a parameter that is
+ * genuinely optional with no meaningful default (an ARN that only applies to
+ * a reference-existing deploy, a CIDR override), an unresolved value is
+ * simply omitted from `provenance`/`params` rather than an error; source
+ * reads it as plain `undefined`, same as before migrating off
+ * `process.env.X || undefined`.
+ */
+export function resolveBuildParams(defs: BuildParamsConfig | undefined, input: BuildParamsInput): BuildParamsResolution {
+  const declared = defs ?? {};
+  const cli = input.cli ?? {};
+  const fromFile = input.fromFile ?? {};
+  const env = input.env ?? {};
+  const errors: string[] = [];
+  const provenance: BuildParamProvenance[] = [];
+
+  for (const key of Object.keys(cli)) {
+    if (!(key in declared)) {
+      errors.push(`unknown build parameter "${key}" (from --param) — not declared in chant.config.ts's buildParams`);
+    }
+  }
+  for (const key of Object.keys(fromFile)) {
+    if (!(key in declared)) {
+      errors.push(`unknown build parameter "${key}" (from --params-file) — not declared in chant.config.ts's buildParams`);
+    }
+  }
+
+  for (const [name, def] of Object.entries(declared)) {
+    let raw: BuildParamValue | undefined;
+    let source: BuildParamProvenance["source"] | undefined;
+
+    if (name in cli) {
+      raw = cli[name];
+      source = "cli";
+    } else if (name in fromFile) {
+      const fileValue = fromFile[name];
+      if (typeof fileValue !== "string" && typeof fileValue !== "number" && typeof fileValue !== "boolean") {
+        errors.push(`build parameter "${name}" (from --params-file) must be a string, number, or boolean`);
+        continue;
+      }
+      raw = fileValue;
+      source = "params-file";
+    } else if (def.env && env[def.env] !== undefined) {
+      raw = env[def.env];
+      source = "env";
+    } else if (def.default !== undefined) {
+      raw = def.default;
+      source = "default";
+    }
+
+    if (raw === undefined || source === undefined) {
+      if (def.required === false) continue; // omitted entirely — params.<name> reads as undefined, not an error
+      const envHint = def.env ? `, set ${def.env}` : "";
+      errors.push(
+        `build parameter "${name}" has no value — pass --param ${name}=<value>, use --params-file${envHint}, or add a default in chant.config.ts's buildParams`,
+      );
+      continue;
+    }
+
+    const value = coerce(name, raw, def, errors);
+    if (value === undefined) continue;
+
+    if (def.enum && !def.enum.includes(value)) {
+      errors.push(
+        `build parameter "${name}" must be one of ${def.enum.map(formatValue).join(", ")}, got ${formatValue(value)}`,
+      );
+      continue;
+    }
+
+    provenance.push({ name, value, source });
+  }
+
+  return { provenance, errors };
+}
+
+/** Project the resolved provenance records down to a plain `{ name: value }` map — what actually gets bound to `params.<name>` (see ./params.ts). */
+export function buildParamValues(provenance: readonly BuildParamProvenance[]): Record<string, BuildParamValue> {
+  return Object.fromEntries(provenance.map((p) => [p.name, p.value]));
+}

package/src/build.test.ts

@@ -64,6 +64,44 @@ export const testEntity = {
     expect(result.entities.size).toBe(1);
     expect(result.entities.has("testEntity")).toBe(true);
     expect(result.errors.length).toBe(0);
+    expect(result.foldDecisions).toEqual([]);
+  });
+
+  test("#1022 — --fold folds a leaf-only module and surfaces foldDecisions", async () => {
+    const { dirname, resolve: resolvePath } = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const runtimePath = resolvePath(thisDir, "runtime");
+
+    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" });
+      `
+    );
+
+    const mockSerializer: Serializer = {
+      name: "aws",
+      rulePrefix: "TEST",
+      serialize: (entities) => JSON.stringify([...entities.keys()]),
+    };
+
+    const result = await build(testDir, [mockSerializer], undefined, { fold: true });
+
+    expect(result.errors).toEqual([]);
+    expect(result.entities.size).toBe(1);
+    expect(result.entities.has("bucket")).toBe(true);
+    const mainDecision = result.foldDecisions.find((d) => d.file.endsWith("main.ts"));
+    expect(mainDecision?.mode).toBe("fold");
   });
 
   test("handles discovery errors", async () => {