@intentius/chant 0.21.0 → 0.23.0

package/src/components/cli-support.test.ts

@@ -8,16 +8,45 @@
  * rather than going through the CLI arg-parsing/handler dispatch layer.
  */
 
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdir, writeFile, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import Ajv2020 from "ajv/dist/2020";
 import componentSchema from "./component.schema.json";
-import { listComponents, describeComponent, computeComponentGraph, runComponents, findComponentGate } from "./cli-support";
+import {
+  listComponents,
+  describeComponent,
+  computeComponentGraph,
+  runComponents,
+  findComponentGate,
+  resolveComponentTargets,
+  generateComponentsPipeline,
+} from "./cli-support";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import type { DriverComponent, RunProgressEvent } from "./driver";
 
+// A minimal stand-in for the real gitlab lexicon plugin, satisfying
+// `isLexiconPlugin` (../lexicon.ts) — used only by the `generateComponentsPipeline`
+// buildParams test below, so that test doesn't depend on how `@intentius/
+// chant-lexicon-gitlab`'s own real module resolves under the test runner.
+vi.mock("@intentius/chant-lexicon-gitlab", () => ({
+  gitlab: {
+    name: "gitlab",
+    serializer: { name: "gitlab", rulePrefix: "GL", serialize: () => "" },
+    generate: () => {},
+    validate: () => [],
+    coverage: () => ({ total: 0, covered: 0 }),
+    package: () => "gitlab",
+    generateComponentPipeline: (components: DriverComponent[]) => ({
+      yaml: components.map((c) => c.name).join(","),
+      stages: ["wave-1"],
+      jobs: components.map((c) => ({ jobName: c.name, component: c.name, stage: "wave-1", needs: [] })),
+    }),
+  },
+}));
+
 describe("listComponents", () => {
   let testDir: string;
 
@@ -578,6 +607,195 @@ describe("runComponents", () => {
   });
 });
 
+// ── build-time parameters (chant #1108) ──────────────────────────────────────
+//
+// Before #1108, `discoverComponents`'s callers here never resolved
+// `chant.config.ts`'s declared `buildParams` at all, so a `*.component.ts`
+// file reading `params.<name>` (`@intentius/chant/params`) always saw `{}` —
+// the exact probe from chant#1108's reproduction. These tests lock in that
+// `runComponents`/`resolveComponentTargets`/`generateComponentsPipeline` now
+// forward an already-resolved `buildParams` into discovery, so a component's
+// `params.<name>` read reflects it before any step dispatches.
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const paramsModulePath = resolvePath(thisDir, "../params");
+
+describe("runComponents — buildParams (chant #1108)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-run-components-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("the previously-{} case: a component's params.<name> read resolves when buildParams is passed", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: "svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing", tier: params.tier }] }],
+        };
+      `,
+    );
+
+    const capability = fakeCapability("deploy-thing");
+    const registry = new CapabilityRegistry();
+    registry.register(capability);
+
+    const result = await runComponents(testDir, "svc", {
+      registry,
+      buildParams: [{ name: "tier", value: "production", source: "cli" }],
+    });
+
+    expect(result.success).toBe(true);
+    expect(capability.calls[0]?.input).toMatchObject({ tier: "production" });
+  });
+
+  test("without buildParams, params.<name> is undefined (the bug this issue fixes, still true for a caller that resolves none)", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: "svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing", tier: params.tier ?? "unset" }] }],
+        };
+      `,
+    );
+
+    const capability = fakeCapability("deploy-thing");
+    const registry = new CapabilityRegistry();
+    registry.register(capability);
+
+    const result = await runComponents(testDir, "svc", { registry });
+
+    expect(result.success).toBe(true);
+    expect(capability.calls[0]?.input).toMatchObject({ tier: "unset" });
+  });
+
+  test("RunComponentsResult.buildParams echoes back the resolved provenance that was passed in", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing" }] }] };`,
+    );
+
+    const registry = fakeRegistry();
+    const result = await runComponents(testDir, "svc", {
+      registry,
+      buildParams: [{ name: "tier", value: "production", source: "cli" }],
+    });
+
+    expect(result.buildParams).toEqual([{ name: "tier", value: "production", source: "cli" }]);
+  });
+
+  test("selector 'all' also forwards buildParams into discovery", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = { name: "svc", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "deploy-thing", tier: params.tier }] }] };
+      `,
+    );
+
+    const capability = fakeCapability("deploy-thing");
+    const registry = new CapabilityRegistry();
+    registry.register(capability);
+
+    const result = await runComponents(testDir, "all", {
+      registry,
+      buildParams: [{ name: "tier", value: "staging", source: "env" }],
+    });
+
+    expect(result.success).toBe(true);
+    expect(capability.calls[0]?.input).toMatchObject({ tier: "staging" });
+  });
+});
+
+describe("resolveComponentTargets — buildParams (chant #1108)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-resolve-targets-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("forwards buildParams into discovery — the durable (--temporal) path's entrypoint", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: "svc",
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", stack: params.env }] }],
+        };
+      `,
+    );
+
+    const result = await resolveComponentTargets(testDir, "svc", undefined, [
+      { name: "env", value: "prod-a", source: "env" },
+    ]);
+
+    expect(result.success).toBe(true);
+    expect((result.targets[0].deploy[0].steps[0] as { stack?: unknown }).stack).toBe("prod-a");
+  });
+});
+
+describe("generateComponentsPipeline — buildParams (chant #1108)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-generate-components-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("forwards buildParams into discovery before synthesizing the pipeline", async () => {
+    await writeFile(
+      join(testDir, "svc.component.ts"),
+      `
+        import { params } from ${JSON.stringify(paramsModulePath)};
+        export const svc = {
+          name: String(params.name),
+          dependsOn: [],
+          deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+        };
+      `,
+    );
+
+    // Uses the mocked "gitlab" plugin above (see the `vi.mock` at the top of
+    // this file) — proves the component name `discoverComponents` resolved
+    // (via `params.name`) made it all the way through to the synthesized
+    // pipeline, not just to `discover()`'s own return value.
+    const result = await generateComponentsPipeline(
+      testDir,
+      "gitlab",
+      undefined,
+      undefined,
+      [{ name: "name", value: "named-from-params", source: "cli" }],
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.jobs?.map((j) => j.component)).toEqual(["named-from-params"]);
+    expect(result.buildParams).toEqual([{ name: "name", value: "named-from-params", source: "cli" }]);
+  });
+});
+
 describe("runComponents — onProgress (--progress-json wiring, M3)", () => {
   let testDir: string;
 

package/src/components/cli-support.ts

@@ -23,6 +23,7 @@
  */
 
 import { discoverComponents } from "./discover";
+import type { BuildParamProvenance } from "../provenance";
 import { projectToJson, type Archetype } from "./component";
 import {
   resolveComponentGraph,
@@ -185,6 +186,8 @@ export interface GenerateComponentsResult {
   /** Every generated job, for a machine-readable view (`--format json`). */
   jobs?: Array<{ jobName: string; component: string; stage: string; needs: string[] }>;
   error?: string;
+  /** This invocation's resolved build-time parameters (chant #1108) — the generate-mode counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Empty when the project declares/supplies none. */
+  buildParams?: BuildParamProvenance[];
 }
 
 /**
@@ -221,6 +224,15 @@ export async function generateComponentsPipeline(
   lexicon: GenerateLexicon,
   options?: ComponentPipelineOptions,
   sandbox?: boolean,
+  /**
+   * chant #1108 — this invocation's resolved build-time parameter values
+   * (../cli/handlers/build.ts resolves them, the same sequence `chant build`
+   * runs, BEFORE calling this function), forwarded into discovery so a
+   * `params.<name>` reference inside a discovered `*.component.ts` file
+   * resolves instead of reading `{}`. See `discoverComponents`'s
+   * `buildParams` option (./discover.ts) for the full doc.
+   */
+  buildParams?: BuildParamProvenance[],
 ): Promise<GenerateComponentsResult> {
   const plugin = await loadLexiconPlugin(lexicon);
   if (!plugin?.generateComponentPipeline) {
@@ -230,7 +242,7 @@ export async function generateComponentsPipeline(
     };
   }
 
-  const result = await discoverComponents(path, { sandbox });
+  const result = await discoverComponents(path, { sandbox, buildParams });
   if (result.errors.length > 0) {
     return { success: false, error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -243,7 +255,7 @@ export async function generateComponentsPipeline(
 
   try {
     const { yaml, stages, jobs } = plugin.generateComponentPipeline(driverComponents, options);
-    return { success: true, yaml, stages, jobs };
+    return { success: true, yaml, stages, jobs, buildParams };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, error: err.message };
@@ -344,6 +356,21 @@ export interface RunComponentsOptions {
    * `--progress-json`, in which case nothing changes.
    */
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * chant #1108 — this run's resolved build-time parameter values, resolved
+   * the exact same way `chant build` resolves them
+   * (../cli/build-params-cli.ts's `resolveCliBuildParams`, driven by
+   * `--param`/`--params-file`/a declared `env` mapping/`chant.config.ts`'s
+   * `buildParams` defaults). The CLI handler (../cli/handlers/run.ts)
+   * resolves + logs these BEFORE calling `runComponents`, the same
+   * sequencing `chant build` uses — this function only forwards the
+   * already-resolved values into discovery (`resolveComponentTargets` below,
+   * then `discoverComponents`); it does not resolve them itself, so
+   * `runComponents` stays free of CLI-flag-parsing/formatting concerns.
+   * Default: none — `params.*` stays `{}`, matching every caller (including
+   * every test in `cli-support.test.ts`) that doesn't supply this.
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -356,6 +383,8 @@ export interface RunComponentsResult {
   error?: string;
   /** Set when a selected component (or one of its `deploy`/`rollback` phases) contains a `gate` the local executor cannot run. */
   gateUnsupported?: { component: string; signalName: string };
+  /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
+  buildParams?: BuildParamProvenance[];
 }
 
 /**
@@ -404,8 +433,10 @@ export async function resolveComponentTargets(
   path: string,
   selector: string,
   sandbox?: boolean,
+  /** chant #1108 — this invocation's resolved build-time parameter values, forwarded into `discoverComponents` so a `params.<name>` reference inside a discovered `*.component.ts` file resolves instead of reading `{}`. See `discoverComponents`'s `buildParams` option (./discover.ts). */
+  buildParams?: BuildParamProvenance[],
 ): Promise<ResolvedComponentTargets> {
-  const result = await discoverComponents(path, { sandbox });
+  const result = await discoverComponents(path, { sandbox, buildParams });
   if (result.errors.length > 0) {
     return { success: false, targets: [], error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -433,7 +464,7 @@ export async function runComponents(
   selector: string,
   options: RunComponentsOptions = {},
 ): Promise<RunComponentsResult> {
-  const resolved = await resolveComponentTargets(path, selector, options.sandbox);
+  const resolved = await resolveComponentTargets(path, selector, options.sandbox, options.buildParams);
   if (!resolved.success) {
     return { success: false, selected: [], error: resolved.error };
   }
@@ -479,7 +510,7 @@ export async function runComponents(
   try {
     if (selector === "all") {
       const run = await runInterpretDriver(resolvedTargets, registry, { env, componentOutputs: seedOutputs, onProgress });
-      return { success: true, run, selected };
+      return { success: true, run, selected, buildParams: options.buildParams };
     }
 
     // Single-component invocation: run just this component, bypassing
@@ -518,7 +549,7 @@ export async function runComponents(
       failedComponent: componentResult.ok ? undefined : componentResult.component,
       componentOutputs,
     };
-    return { success: componentResult.ok, run, selected };
+    return { success: componentResult.ok, run, selected, buildParams: options.buildParams };
   } catch (err) {
     if (err instanceof DriverRunFailure) {
       return { success: false, run: err.result, selected, error: err.message };

package/src/components/discover.test.ts

@@ -11,9 +11,11 @@
 
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { mkdir, writeFile, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import { discoverComponents } from "./discover";
+import { params } from "../params";
 
 describe("discoverComponents", () => {
   let testDir: string;
@@ -349,4 +351,64 @@ describe("discoverComponents", () => {
     expect(result.components.has("first-svc")).toBe(true);
     expect(result.components.has("nested-svc")).toBe(false);
   });
+
+  // ── chant #1108 — build-time parameters populated before import ────────────
+
+  describe("buildParams (chant #1108)", () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const paramsPath = resolvePath(thisDir, "../params");
+
+    test("with no buildParams option, params.* stays empty (matches every non-run/generate caller today)", async () => {
+      await writeFile(
+        join(testDir, "svc.component.ts"),
+        `
+          export const svc = {
+            name: "svc",
+            dependsOn: [],
+            deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+          };
+        `,
+      );
+
+      const result = await discoverComponents(testDir);
+
+      expect(result.components.has("svc")).toBe(true);
+      expect(params).toEqual({});
+    });
+
+    test("populates params.* BEFORE importing *.component.ts, so a live import observes the resolved value", async () => {
+      await writeFile(
+        join(testDir, "svc.component.ts"),
+        `
+          import { params } from ${JSON.stringify(paramsPath)};
+          export const svc = {
+            name: "svc",
+            dependsOn: [],
+            deploy: [{ phase: "Apply", steps: [{ kind: "shell", command: String(params.tier) }] }],
+          };
+        `,
+      );
+
+      const result = await discoverComponents(testDir, {
+        buildParams: [{ name: "tier", value: "production", source: "cli" }],
+      });
+
+      expect(result.errors).toEqual([]);
+      const svc = result.components.get("svc");
+      expect((svc?.component.deploy[0].steps[0] as { command?: unknown }).command).toBe("production");
+    });
+
+    test("a second call with no buildParams resets params.* — no stale leak from a prior call in the same process", async () => {
+      await writeFile(
+        join(testDir, "a.component.ts"),
+        `export const a = { name: "a", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };`,
+      );
+
+      await discoverComponents(testDir, { buildParams: [{ name: "tier", value: "production", source: "cli" }] });
+      expect(params).toEqual({ tier: "production" });
+
+      await discoverComponents(testDir);
+      expect(params).toEqual({});
+    });
+  });
 });

package/src/components/discover.ts

@@ -46,6 +46,9 @@ import { pathToFileURL } from "node:url";
 import { existsSync } from "node:fs";
 import { DiscoveryError } from "../errors";
 import { isComponent, type Component } from "./component";
+import type { BuildParamProvenance } from "../provenance";
+import { buildParamValues } from "../build-params";
+import { setBuildParams } from "../params";
 
 /** One discovered component, paired with the file it was exported from. */
 export interface DiscoveredComponent {
@@ -75,6 +78,34 @@ export interface ComponentDiscoveryOptions {
    * requested.
    */
   sandbox?: boolean;
+
+  /**
+   * chant #1108 — this invocation's resolved build-time parameter values
+   * (../build-params.ts's `resolveBuildParams`, driven by the CLI's
+   * `--param`/`--params-file`/a declared `env` mapping/`chant.config.ts`'s
+   * `buildParams` defaults — see ../cli/build-params-cli.ts's
+   * `resolveCliBuildParams`, the exact resolution `chant build` runs).
+   * Populated into ../params.ts's shared `params` object (`setBuildParams`,
+   * below) before any `*.component.ts` file is scanned/imported, mirroring
+   * ../discovery/index.ts's `discover()` — the lexicon-resource counterpart
+   * of this function, and the thing chant #1108 exists to bring this one to
+   * parity with. Before #1108, no caller populated this, so a live `import {
+   * params } from "@intentius/chant/params"` inside a component file (e.g. a
+   * naming helper deriving a stack name) always saw `{}`.
+   *
+   * Default: none — `params` stays `{}`, matching every caller that doesn't
+   * resolve build-time parameters today (`chant list/describe/graph/lint
+   * --components`, `chant components status`); only the run and generate
+   * call sites (../cli/handlers/run.ts, ../cli/handlers/build.ts) pass a
+   * resolved value.
+   *
+   * Only takes effect for the in-process (non-sandboxed) import path below —
+   * `{ sandbox: true }`'s child process gets its own, unpopulated `params`
+   * module instance, the same pre-existing gap `discover({ sandbox: true })`
+   * has for lexicon resources (chant #1045 Phase 2 never threaded
+   * `buildParams` into its sandboxed child either; out of scope here too).
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 /** One already-imported `*.component.ts` module — the input to {@link collectComponents}. */
@@ -240,6 +271,17 @@ export async function discoverComponents(
   path: string,
   options?: ComponentDiscoveryOptions,
 ): Promise<ComponentDiscoveryResult> {
+  // chant #1108 — populate the shared build-time-parameters object BEFORE
+  // scanning/importing any *.component.ts file below, so a live `import {
+  // params } from "@intentius/chant/params"` inside a component file
+  // observes this invocation's resolved values instead of an empty object.
+  // Unconditional (not just when `buildParams` is set) so a stale value from
+  // a PRIOR discoverComponents() call in the same process (tests, several
+  // `--components` subcommands run back-to-back) never leaks into a call
+  // that supplied none — mirrors ../discovery/index.ts's `discover()`,
+  // identical rationale.
+  setBuildParams(buildParamValues(options?.buildParams ?? []));
+
   const sourceFiles = await findComponentFiles(path);
 
   if (options?.sandbox && sourceFiles.length > 0) {