@intentius/chant 0.22.0 → 0.23.0

package/src/cli/build-params-cli.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for the CLI-layer build-time-parameter helpers factored out by chant
+ * #1108 (`parseParamFlags`/`resolveCliBuildParams`) — the exact sequence
+ * `chant build` (`./commands/build.ts`'s `buildCommand`) runs, now shared with
+ * the component deploy driver (`./handlers/run.ts`, `./handlers/build.ts`'s
+ * generate mode) so both resolve `--param`/`--params-file`/a declared `env`
+ * mapping/`chant.config.ts`'s `buildParams` defaults identically. Precedence
+ * itself is `../build-params.ts`'s `resolveBuildParams`'s responsibility
+ * (see `../build-params.test.ts`) — these tests cover the CLI-specific glue:
+ * flag parsing, `--params-file` reading, error formatting, and logging.
+ */
+import { describe, test, expect, vi } from "vitest";
+import { writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { parseParamFlags, resolveCliBuildParams } from "./build-params-cli";
+import type { BuildParamsConfig } from "../build-params";
+
+describe("parseParamFlags", () => {
+  test("undefined/empty input yields undefined (matches resolveBuildParams's 'no cli input' shape)", () => {
+    expect(parseParamFlags(undefined)).toBeUndefined();
+    expect(parseParamFlags([])).toBeUndefined();
+  });
+
+  test("parses repeated name=value flags into a flat record", () => {
+    expect(parseParamFlags(["tier=production", "replicas=3"])).toEqual({
+      tier: "production",
+      replicas: "3",
+    });
+  });
+
+  test("a value containing '=' keeps everything after the first '=' (only the first splits)", () => {
+    expect(parseParamFlags(["url=https://example.com?a=b"])).toEqual({
+      url: "https://example.com?a=b",
+    });
+  });
+
+  test("a flag with no '=' becomes an empty-string value", () => {
+    expect(parseParamFlags(["flag-only"])).toEqual({ "flag-only": "" });
+  });
+});
+
+describe("resolveCliBuildParams", () => {
+  test("cli beats params-file beats a declared env mapping beats the default — the exact chant build precedence", () => {
+    const defs: BuildParamsConfig = { tier: { type: "string", default: "light", env: "TIER_ENV" } };
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = resolveCliBuildParams(defs, { cli: { tier: "production" } });
+      expect(result).toEqual({
+        success: true,
+        provenance: [{ name: "tier", value: "production", source: "cli" }],
+        errors: [],
+      });
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("logs every resolved parameter as '[param] name = value (source)'", () => {
+    const defs: BuildParamsConfig = { tier: { type: "string", default: "light" } };
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      resolveCliBuildParams(defs, {});
+      const logged = errorSpy.mock.calls.map((call) => String(call[0]));
+      expect(logged.some((line) => line.includes("[param] tier") && line.includes("light") && line.includes("default"))).toBe(true);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("no declared params → success with empty provenance and no logging", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = resolveCliBuildParams(undefined, {});
+      expect(result).toEqual({ success: true, provenance: [], errors: [] });
+      expect(errorSpy).not.toHaveBeenCalled();
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("an unresolved required parameter is a formatted error, not a thrown exception", () => {
+    const defs: BuildParamsConfig = { tier: { type: "string" } };
+    const result = resolveCliBuildParams(defs, {});
+    expect(result.success).toBe(false);
+    expect(result.provenance).toEqual([]);
+    expect(result.errors.some((e) => e.includes('"tier"') && e.includes("--param"))).toBe(true);
+  });
+
+  test("an enum violation is a formatted error naming the parameter and the offending value", () => {
+    const defs: BuildParamsConfig = { tier: { type: "string", enum: ["light", "production"] } };
+    const result = resolveCliBuildParams(defs, { cli: { tier: "bogus" } });
+    expect(result.success).toBe(false);
+    expect(result.errors.some((e) => e.includes('"tier"') && e.includes("bogus"))).toBe(true);
+  });
+
+  test("an unknown --param name is a formatted error", () => {
+    const defs: BuildParamsConfig = { tier: { type: "string", default: "light" } };
+    const result = resolveCliBuildParams(defs, { cli: { nonexistent: "x" } });
+    expect(result.success).toBe(false);
+    expect(result.errors.some((e) => e.includes("nonexistent") && e.includes("--param"))).toBe(true);
+  });
+
+  describe("--params-file", () => {
+    let dir: string;
+
+    test("reads and resolves values from a JSON file (second precedence, after --param)", () => {
+      dir = mkdtempSync(join(tmpdir(), "chant-build-params-cli-test-"));
+      try {
+        const file = join(dir, "params.json");
+        writeFileSync(file, JSON.stringify({ tier: "from-file", env: "from-file-env" }));
+        const defs: BuildParamsConfig = {
+          tier: { type: "string", default: "light" },
+          env: { type: "string", default: "dev" },
+        };
+
+        const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+        try {
+          const result = resolveCliBuildParams(defs, { cli: { tier: "from-cli" }, paramsFile: file });
+          expect(result.success).toBe(true);
+          const byName = new Map(result.provenance.map((p) => [p.name, p]));
+          expect(byName.get("tier")).toEqual({ name: "tier", value: "from-cli", source: "cli" });
+          expect(byName.get("env")).toEqual({ name: "env", value: "from-file-env", source: "params-file" });
+        } finally {
+          errorSpy.mockRestore();
+        }
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    test("an unreadable/unparsable --params-file is a formatted error naming the path, not a thrown exception", () => {
+      const defs: BuildParamsConfig = { tier: { type: "string", default: "light" } };
+      const result = resolveCliBuildParams(defs, { paramsFile: "/nonexistent/path/params.json" });
+      expect(result.success).toBe(false);
+      expect(result.errors.some((e) => e.includes("--params-file") && e.includes("/nonexistent/path/params.json"))).toBe(true);
+    });
+  });
+});

package/src/cli/build-params-cli.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { resolveBuildParams, type BuildParamsConfig } from "../build-params";
+import type { BuildParamProvenance } from "../provenance";
+import { formatError, formatInfo } from "./format";
+
+/**
+ * Shared CLI-layer wiring for chant #1064's build-time parameters, factored
+ * out (chant #1108) so every command that discovers project source before
+ * running it resolves `chant.config.ts`'s declared `buildParams` the exact
+ * same way: `chant build` (`../commands/build.ts`'s `buildCommand`), the
+ * component deploy driver (`./handlers/run.ts`'s `chant run --components`
+ * local + `--temporal` paths), and generate mode (`./handlers/build.ts`'s
+ * `chant build --components --generate <lexicon>`).
+ *
+ * Before #1108, only `buildCommand` ran this sequence — `chant run
+ * --components` never resolved `--param`/`--params-file`/a declared `env`
+ * mapping at all, so a `*.component.ts` file reading `params.<name>`
+ * (`@intentius/chant/params`) always saw `{}`, no matter what a CI job
+ * exported into the environment. See ../build-params.ts's module doc for the
+ * full precedence rules this wraps.
+ */
+
+/** Parse repeated `--param name=value` flags into a flat `{ name: value }` record — the raw (unvalidated) strings {@link resolveCliBuildParams} resolves against a project's declared `buildParams`. `undefined` when no `--param` flag was given, matching `resolveBuildParams`'s "no cli input" shape. */
+export function parseParamFlags(entries?: string[]): Record<string, string> | undefined {
+  if (!entries?.length) return undefined;
+  return Object.fromEntries(
+    entries.map((entry) => {
+      const eq = entry.indexOf("=");
+      return eq === -1 ? [entry, ""] : [entry.slice(0, eq), entry.slice(eq + 1)];
+    }),
+  );
+}
+
+/** Inputs {@link resolveCliBuildParams} needs from a parsed CLI invocation — the `--param`/`--params-file` half of {@link resolveBuildParams}'s `BuildParamsInput` (the `env` half is always `process.env`, resolved internally). */
+export interface CliBuildParamsArgs {
+  /** Already-parsed `--param name=value` flags (see {@link parseParamFlags}), or the CLI's already-typed `Record<string,string>` (`chant build`'s own flag parsing does this itself — see `./handlers/build.ts`). */
+  cli?: Record<string, string>;
+  /** `--params-file <path>` — a JSON file of `{ "name": value }` values, read and parsed here. */
+  paramsFile?: string;
+}
+
+export interface CliBuildParamsResolution {
+  success: boolean;
+  /** Every successfully resolved parameter. Empty when the project declares none, or when `success` is `false`. */
+  provenance: BuildParamProvenance[];
+  /** `formatError`-wrapped messages, ready to print as-is. Empty when `success` is `true`. */
+  errors: string[];
+}
+
+/**
+ * Resolve this invocation's declared build-time parameters (`chant.config.ts`'s
+ * `buildParams`) against `args`/the process environment, and log each
+ * resolved value — the identical resolution + logging sequence `chant build`
+ * runs (`../commands/build.ts`'s `buildCommand`), factored out so every other
+ * command that discovers project source runs it too (chant #1108).
+ *
+ * A resolution failure (an unknown `--param`/`--params-file` name, a missing
+ * required value, a type/enum mismatch, or an unreadable `--params-file`) is
+ * returned as `{ success: false, errors }` — never thrown — so the caller can
+ * print each message and exit non-zero exactly like a build error, matching
+ * chant #1064's acceptance criterion that this never surfaces as a thrown
+ * error from inside user source.
+ *
+ * On success, every resolved parameter is logged via `console.error` as
+ * `[param] <name> = <value> (<source>)` — unconditional, not gated on
+ * `--verbose`, so a build's environment-varying inputs are always visible,
+ * the same way #1022's fold decisions are.
+ */
+export function resolveCliBuildParams(
+  buildParamsConfig: BuildParamsConfig | undefined,
+  args: CliBuildParamsArgs,
+): CliBuildParamsResolution {
+  const errors: string[] = [];
+
+  let fromFile: Record<string, unknown> | undefined;
+  if (args.paramsFile) {
+    try {
+      fromFile = JSON.parse(readFileSync(resolve(args.paramsFile), "utf-8"));
+    } catch (err) {
+      errors.push(
+        formatError({
+          message: `Failed to read/parse --params-file "${args.paramsFile}": ${err instanceof Error ? err.message : String(err)}`,
+        }),
+      );
+    }
+  }
+
+  const resolution = resolveBuildParams(buildParamsConfig, {
+    cli: args.cli,
+    fromFile,
+    env: process.env,
+  });
+  for (const message of resolution.errors) {
+    errors.push(formatError({ message }));
+  }
+
+  if (errors.length > 0) {
+    return { success: false, provenance: [], errors };
+  }
+
+  for (const p of resolution.provenance) {
+    console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
+  }
+
+  return { success: true, provenance: resolution.provenance, errors: [] };
+}

package/src/cli/commands/build.ts

@@ -1,13 +1,13 @@
 import { build } from "../../build";
 import { loadChantConfig, resolveOwnershipMarker, resolveFoldEnabled, resolveSandboxEnabled } from "../../config";
-import { resolveBuildParams } from "../../build-params";
+import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks } from "../../lint/post-synth";
 import { loadPolicyChecks } from "../../lint/policy";
 import { sortedJsonReplacer } from "../../utils";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
-import { writeFileSync, mkdirSync, readFileSync } from "fs";
+import { writeFileSync, mkdirSync } from "fs";
 import { resolve, dirname, join, relative } from "path";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 
@@ -155,44 +155,24 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // as fold, resolved independently.
   const sandbox = resolveSandboxEnabled(config, options.sandbox);
 
-  // #1064 — resolve declared build-time parameters (chant.config.ts's
-  // buildParams) against this invocation's --param/--params-file/declared
-  // env mapping, BEFORE calling build() — a resolution failure (an unknown
-  // name, a missing required value, a type/enum mismatch) is reported as a
-  // chant build error naming the parameter, never a thrown error from inside
-  // user source (which is what loomster's hand-rolled `tierFromEnv()`-style
-  // validators did before migrating to this mechanism).
-  let paramsFileContent: Record<string, unknown> | undefined;
-  if (options.paramsFile) {
-    try {
-      paramsFileContent = JSON.parse(readFileSync(resolve(options.paramsFile), "utf-8"));
-    } catch (err) {
-      errors.push(
-        formatError({
-          message: `Failed to read/parse --params-file "${options.paramsFile}": ${err instanceof Error ? err.message : String(err)}`,
-        }),
-      );
-    }
-  }
-  const paramsResolution = resolveBuildParams(config.buildParams, {
+  // #1064 (factored into ../build-params-cli.ts's resolveCliBuildParams by
+  // #1108, so the component deploy driver runs the identical sequence) —
+  // resolve declared build-time parameters (chant.config.ts's buildParams)
+  // against this invocation's --param/--params-file/declared env mapping,
+  // BEFORE calling build() — a resolution failure (an unknown name, a
+  // missing required value, a type/enum mismatch) is reported as a chant
+  // build error naming the parameter, never a thrown error from inside user
+  // source (which is what loomster's hand-rolled `tierFromEnv()`-style
+  // validators did before migrating to this mechanism). Also logs every
+  // resolved value (`[param] name = value (source)`) on success.
+  const paramsResolution = resolveCliBuildParams(config.buildParams, {
     cli: options.params,
-    fromFile: paramsFileContent,
-    env: process.env,
+    paramsFile: options.paramsFile,
   });
-  for (const message of paramsResolution.errors) {
-    errors.push(formatError({ message }));
-  }
-  if (errors.length > 0) {
+  if (!paramsResolution.success) {
+    errors.push(...paramsResolution.errors);
     return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
   }
-  // #1064 — build-provenance visibility: report every resolved build-time
-  // parameter (name, value, and which source won it) the same
-  // unconditional-log-not-gated-on---verbose way #1022's fold decisions are
-  // reported just below, so a build's environment-varying inputs are as
-  // visible as its fold-vs-run choices.
-  for (const p of paramsResolution.provenance) {
-    console.error(formatInfo(`[param] ${p.name} = ${JSON.stringify(p.value)} (${p.source})`));
-  }
 
   // #1039 — thread each loaded plugin's registered intrinsics (e.g. AWS's
   // `Sub`) through to the fold path, so a file using a registered intrinsic

package/src/cli/commands/lint.test.ts

@@ -332,6 +332,80 @@ describe("plugin integration", () => {
   });
 });
 
+/**
+ * chant #1106 — `runLint`'s EVL rules now receive the active lexicons'
+ * registered intrinsics (threaded from `loadAllPluginRules`'s
+ * `plugin.intrinsics?.()`, mirroring how `../commands/build.ts` gathers the
+ * same set for the fold path). Before this, `chant lint` flagged
+ * `Ref(...)` — a registered, opted-in call-form intrinsic (aws's
+ * `lexicons/aws/src/plugin.ts`) that `chant build --fold` folds cleanly —
+ * as EVL001, purely because EVL001's shared `../../fold/subset.ts`
+ * predicate never saw the registry. These use the real aws lexicon plugin
+ * (already a workspace dependency) rather than a mock, so the registration
+ * this asserts against is the one that actually ships.
+ */
+describe("lintCommand — EVL/intrinsic registry convergence (#1106)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-lint-intrinsics-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+    process.env.NO_COLOR = "1";
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    delete process.env.NO_COLOR;
+  });
+
+  test("a registered, opted-in intrinsic call (aws's Ref) is not flagged as EVL001", async () => {
+    await writeFile(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    await writeFile(
+      join(testDir, "index.ts"),
+      `
+import { Ref } from "@intentius/chant-lexicon-aws";
+
+class Queue {
+  constructor(_props: Record<string, unknown>) {}
+}
+
+export const environment = "prod";
+export const queue = new Queue({ name: Ref(environment) });
+      `,
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" });
+
+    expect(result.diagnostics.filter((d) => d.ruleId === "EVL001")).toHaveLength(0);
+  });
+
+  test("an unregistered call is still flagged as EVL001 in the same project", async () => {
+    await writeFile(join(testDir, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    await writeFile(
+      join(testDir, "index.ts"),
+      `
+import { Ref } from "@intentius/chant-lexicon-aws";
+
+class Queue {
+  constructor(_props: Record<string, unknown>) {}
+}
+
+function makeName(): string {
+  return "generated";
+}
+
+export const queue = new Queue({ name: makeName() });
+      `,
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" });
+
+    const evl001 = result.diagnostics.filter((d) => d.ruleId === "EVL001");
+    expect(evl001).toHaveLength(1);
+    expect(evl001[0].message).toContain("statically evaluable");
+  });
+});
+
 describe("lintCommand — project-root config resolution (scoped lint)", () => {
   let testDir: string;
 

package/src/cli/commands/lint.ts

@@ -3,6 +3,7 @@ import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
 import { execFileSync } from "child_process";
 import { runLint, parseDisableComments } from "../../lint/engine";
 import type { LintRule, LintDiagnostic, LintFix } from "../../lint/rule";
+import type { IntrinsicDef } from "../../lexicon";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatStylish, formatJson, formatSarif } from "../reporters/stylish";
 import { loadLocalRules } from "../../lint/rule-loader";
@@ -86,8 +87,17 @@ export async function loadPluginRules(
 
 /**
  * Load all lint rules: core COR/EVL rules, then lexicon plugin rules.
+ *
+ * Also returns the active lexicons' registered intrinsics (chant #1106) —
+ * gathered here because this is where the project's lexicon plugins are
+ * already resolved and loaded (`loadPlugins`), the same set `../commands/
+ * build.ts` reads `plugin.intrinsics?.()` off of for the fold path. Handed
+ * back alongside `rules` so `lintCommand` can thread it into every
+ * `runLint` call without loading plugins a second time.
  */
-async function loadAllPluginRules(projectPath: string): Promise<Map<string, LintRule>> {
+async function loadAllPluginRules(
+  projectPath: string,
+): Promise<{ rules: Map<string, LintRule>; intrinsics: IntrinsicDef[] }> {
   const rules = new Map<string, LintRule>();
 
   // Load core COR/EVL rules directly
@@ -106,6 +116,13 @@ async function loadAllPluginRules(projectPath: string): Promise<Map<string, Lint
   // Load only project lexicon plugins (no "chant" injection)
   const plugins = await loadPlugins(lexiconNames);
 
+  // chant #1106 — the same plugins' registered intrinsics (`Ref`, `GetAtt`,
+  // ...), so EVL001 can answer "does this call fold?" exactly like fold()
+  // does instead of flagging every call as a violation. A plugin's
+  // `intrinsics` is an optional extension (not every lexicon defines any),
+  // hence the guard.
+  const intrinsics = plugins.flatMap((plugin) => plugin.intrinsics?.() ?? []);
+
   for (const plugin of plugins) {
     if (plugin.lintRules) {
       for (const r of plugin.lintRules()) {
@@ -127,7 +144,7 @@ async function loadAllPluginRules(projectPath: string): Promise<Map<string, Lint
     rules.set(r.id, r);
   }
 
-  return rules;
+  return { rules, intrinsics };
 }
 
 /**
@@ -428,7 +445,14 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   const hasOverrides = config.overrides && config.overrides.length > 0;
 
   // Load all rules from lexicon plugins (core "chant" + lexicon-specific)
-  let allRules = await loadAllPluginRules(projectRoot);
+  const loaded = await loadAllPluginRules(projectRoot);
+  let allRules = loaded.rules;
+  // chant #1106 — the active lexicons' registered intrinsics, threaded into
+  // every runLint() call below so EVL001 answers exactly like fold() does
+  // for a registered, opted-in call (`Ref(...)`, `GetAtt(...)`) instead of
+  // flagging it. Computed once here regardless of which branch below runs,
+  // same as `allRules`.
+  const intrinsics = loaded.intrinsics;
 
   // Merge in any config-level plugin rules (custom .ts rule files)
   if (config.plugins && config.plugins.length > 0) {
@@ -443,7 +467,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   let diagnostics: LintDiagnostic[];
   let suppressed: Array<LintDiagnostic & { reason?: string }> = [];
   if (options.rules) {
-    const result = await runLint(files, options.rules, undefined);
+    const result = await runLint(files, options.rules, undefined, intrinsics);
     diagnostics = result.diagnostics;
     suppressed = result.suppressed;
   } else if (hasOverrides) {
@@ -451,13 +475,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     for (const file of files) {
       const relativePath = relative(projectRoot, file);
       const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
-      const result = await runLint([file], fileRules, ruleOptions);
+      const result = await runLint([file], fileRules, ruleOptions, intrinsics);
       diagnostics.push(...result.diagnostics);
       suppressed.push(...result.suppressed);
     }
   } else {
     const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
-    const result = await runLint(files, rules, ruleOptions);
+    const result = await runLint(files, rules, ruleOptions, intrinsics);
     diagnostics = result.diagnostics;
     suppressed = result.suppressed;
   }
@@ -491,7 +515,7 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
 
     // Re-lint after fixes to get updated diagnostics
     if (options.rules) {
-      const postResult = await runLint(files, options.rules, undefined);
+      const postResult = await runLint(files, options.rules, undefined, intrinsics);
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     } else if (hasOverrides) {
@@ -500,13 +524,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       for (const file of files) {
         const relativePath = relative(projectRoot, file);
         const { rules: fileRules, ruleOptions } = getDefaultRules(projectRoot, relativePath, allRules);
-        const postResult = await runLint([file], fileRules, ruleOptions);
+        const postResult = await runLint([file], fileRules, ruleOptions, intrinsics);
         diagnostics.push(...postResult.diagnostics);
         suppressed.push(...postResult.suppressed);
       }
     } else {
       const { rules, ruleOptions } = getDefaultRules(projectRoot, undefined, allRules);
-      const postResult = await runLint(files, rules, ruleOptions);
+      const postResult = await runLint(files, rules, ruleOptions, intrinsics);
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     }

package/src/cli/handlers/build.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Tests for `chant build --components --generate <lexicon>` (generate mode,
+ * #563) — specifically its chant #1108 build-time-parameter resolution,
+ * which was entirely missing before this fix: `generateComponentsPipeline`'s
+ * `discoverComponents` call never resolved `chant.config.ts`'s declared
+ * `buildParams`, so a `*.component.ts` file reading `params.<name>` always
+ * saw `{}` under `chant build --components --generate`, exactly like `chant
+ * run --components` (see ../handlers/run.test.ts's "build-time parameters"
+ * describe block for the equivalent local/`--temporal` coverage).
+ *
+ * Mocks `generateComponentsPipeline` and `loadChantConfig` and exercises the
+ * public `runBuild` dispatcher (`runGenerateComponents` itself isn't
+ * exported), mirroring `run.test.ts`'s style of driving the handler through
+ * its `CommandContext` entrypoint rather than reaching into private helpers.
+ */
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { ParsedArgs } from "../registry";
+
+const generateComponentsPipelineMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+
+vi.mock("../../components/cli-support", () => ({
+  generateComponentsPipeline: (...args: unknown[]) => generateComponentsPipelineMock(...args),
+}));
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args) };
+});
+
+const { runBuild } = await import("./build");
+
+function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return {
+    command: "build",
+    path: ".",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    components: true,
+    generate: "gitlab",
+    ...overrides,
+  };
+}
+
+function makeStderrSpy() {
+  const buf: string[] = [];
+  vi.spyOn(console, "error").mockImplementation((s: string) => { buf.push(s); });
+  return buf;
+}
+
+describe("runBuild --components --generate (chant #1108 build-time parameters)", () => {
+  beforeEach(() => {
+    generateComponentsPipelineMock.mockReset();
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: {} });
+  });
+
+  test("no declared buildParams → generateComponentsPipeline is called with an empty provenance array", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(".", "gitlab", { env: undefined }, undefined, []);
+    vi.restoreAllMocks();
+  });
+
+  test("chant.config.ts's declared buildParams resolve, log, and are forwarded to generateComponentsPipeline", async () => {
+    loadChantConfigMock.mockResolvedValue({
+      config: { buildParams: { tier: { type: "string", default: "light" } } },
+    });
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const stderr = makeStderrSpy();
+
+    const exit = await runBuild({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(
+      ".",
+      "gitlab",
+      { env: undefined },
+      undefined,
+      [{ name: "tier", value: "light", source: "default" }],
+    );
+    expect(stderr.join("\n")).toContain("[param] tier");
+    vi.restoreAllMocks();
+  });
+
+  test("--param overrides a declared default", async () => {
+    loadChantConfigMock.mockResolvedValue({
+      config: { buildParams: { tier: { type: "string", default: "light" } } },
+    });
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({
+      args: makeArgs({ param: ["tier=production"] }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(
+      ".",
+      "gitlab",
+      { env: undefined },
+      undefined,
+      [{ name: "tier", value: "production", source: "cli" }],
+    );
+    vi.restoreAllMocks();
+  });
+
+  test("an unresolved required build-time parameter → exit 1, never reaches generateComponentsPipeline", async () => {
+    loadChantConfigMock.mockResolvedValue({
+      config: { buildParams: { tier: { type: "string" } } },
+    });
+    const stderr = makeStderrSpy();
+
+    const exit = await runBuild({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toMatch(/"tier"/);
+    expect(generateComponentsPipelineMock).not.toHaveBeenCalled();
+  });
+
+  test("an enum violation on --param → exit 1, never reaches generateComponentsPipeline", async () => {
+    loadChantConfigMock.mockResolvedValue({
+      config: { buildParams: { tier: { type: "string", enum: ["light", "production"] } } },
+    });
+    const stderr = makeStderrSpy();
+
+    const exit = await runBuild({
+      args: makeArgs({ param: ["tier=bogus"] }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toMatch(/"tier"/);
+    expect(stderr.join("\n")).toMatch(/bogus/);
+    expect(generateComponentsPipelineMock).not.toHaveBeenCalled();
+  });
+});