@intentius/chant 0.44.13 → 0.45.0

package/src/components/driver.test.ts

@@ -18,6 +18,8 @@ import {
   DriverGateUnsupportedError,
   DriverRunFailure,
   UnknownDependencyError,
+  accumulateComponentOutputs,
+  collectComponentOutputs,
   resolveComponentGraph,
   resolveWiring,
   runComponentDeploy,
@@ -411,6 +413,49 @@ describe("runComponentDeploy — output wiring", () => {
   });
 });
 
+describe("collectComponentOutputs / accumulateComponentOutputs — the shared accumulator (#700)", () => {
+  // Exported so the durable path's `accumulateComponentOutputs` activity
+  // (lexicons/temporal/src/component-op/activities.ts) captures outputs via
+  // the same function `runComponentDeploy` does — the accumulation twin of
+  // the already-shared `resolveStepInput`.
+  const phaseOutputs = {
+    Apply: { stackStatus: "CREATE_COMPLETE", outputs: { ClusterArn: "arn:cluster", ApiRepoUri: "repo" } },
+    Publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
+  };
+
+  it("namespaces publish outputs under `publish` and merges stack outputs at the top level", () => {
+    expect(collectComponentOutputs(phaseOutputs)).toEqual({
+      ClusterArn: "arn:cluster",
+      ApiRepoUri: "repo",
+      publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
+    });
+  });
+
+  it("returns undefined when no phase output looks like a publish or stack result", () => {
+    expect(collectComponentOutputs({ Verify: { ok: true } })).toBeUndefined();
+  });
+
+  it("records under the component name, merging over a seeded entry, and returns the map", () => {
+    const seeded = { "shared-alb": { Seeded: "keep" }, other: { x: 1 } };
+    const out = accumulateComponentOutputs(seeded, "shared-alb", phaseOutputs);
+    expect(out).toBe(seeded);
+    expect(out["shared-alb"]).toEqual({
+      Seeded: "keep",
+      ClusterArn: "arn:cluster",
+      ApiRepoUri: "repo",
+      publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
+    });
+    expect(out.other).toEqual({ x: 1 });
+    // Plain data throughout — survives the Temporal activity JSON boundary unchanged.
+    expect(JSON.parse(JSON.stringify(out))).toEqual(out);
+  });
+
+  it("is a no-op when the component exposed nothing", () => {
+    const map = { other: { x: 1 } };
+    expect(accumulateComponentOutputs(map, "svc", { Verify: { ok: true } })).toEqual({ other: { x: 1 } });
+  });
+});
+
 describe("runInterpretDriver — end to end", () => {
   it("runs a producer before its consumer and threads env/vars into every capability call", async () => {
     const registry = new CapabilityRegistry();

package/src/components/driver.ts

@@ -603,37 +603,77 @@ export async function runComponentDeploy(
     return { component: component.name, ok: false, records };
   }
 
-  // Publish-family outputs (publish-image / publish-artifact / load-image-on-host all
-  // return at least one of uri/digest/key — see ../verbs/publish.ts) become this
-  // component's `@<name>.publish.*` for downstream cross-component references.
-  const publishOutput = findPublishOutput(phaseOutputs);
-  if (publishOutput) {
-    componentOutputs[component.name] = { ...componentOutputs[component.name], publish: publishOutput };
-  }
+  // Publish-family and stack outputs become this component's entry in
+  // `componentOutputs` — through the same exported accumulator the durable
+  // path's `accumulateComponentOutputs` activity calls (#700), so local and
+  // Temporal runs can never diverge on what downstream references see.
+  accumulateComponentOutputs(componentOutputs, component.name, phaseOutputs);
+
+  return { component: component.name, ok: true, records };
+}
 
-  // Stack outputs from an apply step (cfn-deploy returns `CfnDeployOutput.outputs`)
-  // become resolvable by downstream components' `stackOutput(<name>, ...)`
-  // references — the cross-stack apply-order integration deferred in #556.
-  // Merged at the top level of this component's entry (peer to `publish`, which
-  // is namespaced under its own key), so `resolveWiring`'s stackOutput branch —
-  // `resolvePath(componentOutputs[stack], name)` — finds each output by name.
-  // Keyed by the component's own name, which by convention is the stack name a
-  // `stackOutput` reference targets (see the pilots and composition-and-wiring.mdx).
+/**
+ * Collect the cross-component outputs one finished component exposes to its
+ * downstream consumers, from every phase output it produced:
+ *
+ *   - publish-family outputs (publish-image / publish-artifact /
+ *     load-image-on-host all return at least one of uri/digest/key — see
+ *     ./verbs/publish.ts) are namespaced under `publish`, so downstream
+ *     `@<name>.publish.*` references resolve;
+ *   - stack outputs from an apply step (cfn-deploy returns
+ *     `CfnDeployOutput.outputs`) are merged at the top level, peer to
+ *     `publish`, so `resolveWiring`'s stackOutput branch —
+ *     `resolvePath(componentOutputs[stack], name)` — finds each output by
+ *     name (the cross-stack apply-order integration deferred in #556, closed
+ *     in #699). The entry is keyed by the component's own name, which by
+ *     convention is the stack name a `stackOutput` reference targets (see the
+ *     pilots and composition-and-wiring.mdx).
+ *
+ * Both halves are generic by output *shape*, not by capability `kind`, keeping
+ * the driver free of per-capability branching. Returns `undefined` when the
+ * component exposed nothing.
+ *
+ * Exported, like `resolveStepInput`, so the durable Temporal path
+ * (lexicons/temporal/src/component-op/activities.ts) accumulates outputs via
+ * this exact function rather than re-deriving it (#700). The resolver and the
+ * accumulator are the two halves of one contract; sharing only the resolver
+ * is how the cross-stack gap #699 closed locally could reopen durably.
+ */
+export function collectComponentOutputs(
+  phaseOutputs: Record<string, Record<string, unknown>>,
+): Record<string, unknown> | undefined {
+  const publishOutput = findPublishOutput(phaseOutputs);
   const stackOutputs = findStackOutputs(phaseOutputs);
-  if (stackOutputs) {
-    componentOutputs[component.name] = { ...componentOutputs[component.name], ...stackOutputs };
-  }
+  if (!publishOutput && !stackOutputs) return undefined;
+  return { ...(stackOutputs ?? {}), ...(publishOutput ? { publish: publishOutput } : {}) };
+}
 
-  return { component: component.name, ok: true, records };
+/**
+ * Record a finished component's outputs (`collectComponentOutputs`) into the
+ * shared `componentOutputs` map under the component's own name, merging over
+ * any seeded entry (`--seed-outputs`, or a durable parent workflow's
+ * thread-through). Mutates and returns `componentOutputs`, so a Temporal
+ * activity can hand the updated map back to its workflow over the JSON
+ * boundary — every value in it is plain activity-result data, so the map is
+ * serializable by construction. A no-op when the component exposed nothing.
+ */
+export function accumulateComponentOutputs(
+  componentOutputs: Record<string, Record<string, unknown>>,
+  componentName: string,
+  phaseOutputs: Record<string, Record<string, unknown>>,
+): Record<string, Record<string, unknown>> {
+  const collected = collectComponentOutputs(phaseOutputs);
+  if (collected) {
+    componentOutputs[componentName] = { ...componentOutputs[componentName], ...collected };
+  }
+  return componentOutputs;
 }
 
 /**
  * Find the output of the last step that looks like a publish result (carries
- * `uri`, `digest`, or `key`) across every phase this component ran, so the
- * driver can populate `@<component>.publish.*` for a downstream consumer.
- * Generic by shape, not by capability `kind` — any capability whose output
- * carries one of these fields is eligible, keeping the driver free of
- * per-capability branching.
+ * `uri`, `digest`, or `key`) across every phase this component ran, so
+ * `collectComponentOutputs` can populate `@<component>.publish.*` for a
+ * downstream consumer.
  */
 function findPublishOutput(
   phaseOutputs: Record<string, Record<string, unknown>>,
@@ -651,9 +691,6 @@ function findPublishOutput(
  * Find the stack `outputs` map produced by an apply-style step (cfn-deploy
  * returns `CfnDeployOutput.outputs`) across every phase this component ran, so
  * a deployed stack's outputs can seed downstream `stackOutput()` resolution.
- * Generic by shape — any output carrying an `outputs` record is eligible —
- * keeping the driver free of per-capability branching, the same way
- * `findPublishOutput` is.
  */
 function findStackOutputs(
   phaseOutputs: Record<string, Record<string, unknown>>,

package/src/components/index.ts

@@ -91,6 +91,8 @@ export {
   resolveComponentGraph,
   resolveWiring,
   resolveStepInput,
+  collectComponentOutputs,
+  accumulateComponentOutputs,
   runComponentDeploy,
   runInterpretDriver,
   DriverGateUnsupportedError,

package/src/components/starter-plugin.ts

@@ -100,8 +100,11 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
 export const starterCapabilityPlugin: CapabilityPlugin = {
   name: "starter",
   // The core package's own version (#1505) — lockstep releases bump it, so a
-  // literal here would go stale every `just release`.
-  version: ownPackageVersion(import.meta.url),
+  // literal here would go stale every `just release`. A getter, so the
+  // package.json read happens on first access rather than at import time.
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
   capabilities: starterCapabilities,
   families: () => STARTER_VERB_FAMILIES,
 };

package/src/config.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
 import {
   loadChantConfig,
   loadChantConfigUpward,
@@ -176,6 +176,61 @@ describe("loadChantConfigUpward (#1502 — lint fragments do not end the walk)",
     expect(result.config.ownership?.stack).toBe("nested");
   });
 
+  // #1711 — JSON has no comments, so a project explaining its rule disables
+  // reaches for an underscore key. Both CockroachDB examples carried
+  // `_ruleNotes` in every stack's fragment, and that one key stopped the walk:
+  // `chant build src/east` resolved the fragment, found no `buildParams`, and
+  // emitted `...@undefined.iam.gserviceaccount.com` without a word.
+  test("an underscore comment key does not turn a fragment into a project config", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({
+        extends: ["@intentius/chant/lint/presets/strict"],
+        _ruleNotes: { COR001: "inline objects read better here" },
+        rules: { COR001: "off" },
+      }),
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({
+        ownership: { stack: "crdb-multi-region" },
+        buildParams: { projectId: { type: "string", default: "my-project" } },
+      }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config.ownership?.stack).toBe("crdb-multi-region");
+    expect(result.config.buildParams?.projectId?.default).toBe("my-project");
+    expect(result.configPath).toBe(join(TEST_DIR, "chant.config.json"));
+  });
+
+  test("a non-comment unknown key still stops the walk, but says so", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ extends: ["@intentius/chant/lint/presets/strict"], ruleNotes: { a: "b" } }),
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "root" } }),
+    );
+
+    const warn = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await loadChantConfigUpward(SRC);
+      // Unchanged behaviour: the fragment is the project config. What is new is
+      // that the build no longer loses the root config in silence.
+      expect(result.configPath).toBe(join(SRC, "chant.config.json"));
+      expect(result.config.ownership).toBeUndefined();
+      const said = warn.mock.calls.flat().join("\n");
+      expect(said).toContain("declares no project-level key");
+      expect(said).toContain('"ruleNotes"');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   test("a fragment-only project resolves to the default config at the boundary", async () => {
     mkdirSync(SRC, { recursive: true });
     writeFileSync(join(TEST_DIR, "package.json"), JSON.stringify({ name: "boundary" }));

package/src/config.ts

@@ -7,6 +7,7 @@ import { DEFAULT_SBOM_FORMAT, type SbomFormat } from "./components/verbs/sbom-ge
 import type { Severity } from "./components/verbs/vuln-scan";
 import type { VulnPolicy } from "./components/verbs/vuln-gate";
 import type { BuildParamsConfig } from "./build-params";
+import type { BuildParamProvenance } from "./provenance";
 import { findProjectConfig } from "./project-root";
 import { evaluateProjectConfig } from "./config-sandbox";
 
@@ -22,6 +23,12 @@ import { evaluateProjectConfig } from "./config-sandbox";
  */
 export type EnvironmentDeclaration = string | { name: string; endpoint?: string };
 
+/**
+ * `ownership.env`: a literal environment identity, or a reference to a
+ * declared build parameter whose resolved value becomes the identity (#1396).
+ */
+export type OwnershipEnv = string | { param: string };
+
 /** The declared name of one `environments` entry, whichever form it takes. */
 export function environmentName(entry: EnvironmentDeclaration): string {
   return typeof entry === "string" ? entry : entry.name;
@@ -69,7 +76,7 @@ export const ChantConfigSchema = z.object({
   lint: z.record(z.string(), z.unknown()).optional(),
   ownership: z.object({
     stack: z.string().min(1).optional(),
-    env: z.string().min(1).optional(),
+    env: z.union([z.string().min(1), z.object({ param: z.string().min(1) })]).optional(),
     enabled: z.boolean().optional(),
   }).optional(),
   build: z.object({
@@ -193,8 +200,17 @@ export interface ChantConfig {
   ownership?: {
     /** Stack identity stamped onto resources (required to enable stamping). */
     stack?: string;
-    /** Optional environment identity. */
-    env?: string;
+    /**
+     * Optional environment identity. Either a literal, or a reference to one
+     * of this project's declared `buildParams` (`{ param: "env" }`), in which
+     * case the marker takes whatever value that parameter resolves to for the
+     * build — the same value `params.env` reads in source (#1396). A
+     * reference is the only way to make the marker follow `--param env=prod`:
+     * the config is evaluated before build parameters exist, so a literal
+     * computed from `process.env` here and a parameter mapped to the same
+     * variable are two sources of truth that nothing keeps in step.
+     */
+    env?: OwnershipEnv;
     /** Set false to disable stamping even when `stack` is present. */
     enabled?: boolean;
   };
@@ -414,6 +430,7 @@ export async function loadChantConfigUpward(startDir: string): Promise<ResolvedC
     if (parent === dir) break;
     ({ dir, configPath } = findProjectConfig(parent));
   }
+  if (configPath) warnIfFragmentShadowsProjectConfig(configPath);
   return loadChantConfig(dir);
 }
 
@@ -426,12 +443,25 @@ export async function loadChantConfigUpward(startDir: string): Promise<ResolvedC
  */
 const LINT_FRAGMENT_KEYS = new Set(["$schema", "extends", "rules", "overrides", "plugins", "policies"]);
 
+/**
+ * JSON has no comments, so a project that wants to explain why it disabled a
+ * rule reaches for an underscore-prefixed key. chant #1711: both CockroachDB
+ * examples carried a `_ruleNotes` object in every stack's fragment, and one
+ * unrecognized key was enough to stop the walk — `chant build src/east`
+ * resolved the fragment as the project config, found no `buildParams`, no
+ * `ownership` and no `lexicons`, and emitted
+ * `gke-crdb-east-crdb@undefined.iam.gserviceaccount.com`. Silently.
+ *
+ * An underscore key is a comment. It does not make a fragment a project config.
+ */
+const isCommentKey = (k: string): boolean => k.startsWith("_");
+
 function isLintOnlyFragment(configPath: string): boolean {
   if (!configPath.endsWith("chant.config.json")) return false;
   try {
     const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as unknown;
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
-    const keys = Object.keys(parsed);
+    const keys = Object.keys(parsed).filter((k) => !isCommentKey(k));
     return keys.length > 0 && keys.every((k) => LINT_FRAGMENT_KEYS.has(k));
   } catch {
     // Unreadable/unparseable JSON: let loadChantConfig surface the real error
@@ -441,13 +471,127 @@ function isLintOnlyFragment(configPath: string): boolean {
 }
 
 /**
- * Resolve the ownership marker to stamp from project config, or undefined when
- * ownership marking is off (no `stack`, or `enabled: false`).
+ * The `chant.config.json` the walk stopped at declares no project-level key at
+ * all — so it is about to be used as the project config while carrying none of
+ * the things a project config exists to carry.
+ *
+ * The comment-key rule above fixes the case that bit (chant #1711), but the
+ * hole it came from is general: any key outside {@link LINT_FRAGMENT_KEYS}
+ * turns a fragment into the project config, and the consequence is a build
+ * that silently loses every parameter, the ownership marker and the lexicon
+ * list. This says so, naming the key responsible, instead of leaving it to be
+ * discovered in the output.
+ */
+function warnIfFragmentShadowsProjectConfig(configPath: string): void {
+  if (!configPath.endsWith("chant.config.json")) return;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as Record<string, unknown>;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return;
+    const keys = Object.keys(parsed).filter((k) => !isCommentKey(k));
+    if (keys.some((k) => !LINT_FRAGMENT_KEYS.has(k)) && !keys.some((k) => PROJECT_CONFIG_KEYS.has(k))) {
+      const offenders = keys.filter((k) => !LINT_FRAGMENT_KEYS.has(k));
+      console.error(
+        `warning: ${configPath} is being used as the project config, but declares no project-level ` +
+          `key (${[...PROJECT_CONFIG_KEYS].slice(0, 4).join(", ")}, …). ` +
+          `${offenders.length === 1 ? "The key" : "The keys"} ${offenders.map((k) => `"${k}"`).join(", ")} ` +
+          `stopped the walk to the real one — any config above this file is being ignored. ` +
+          `Prefix a comment key with "_", or move the key to the project config. (chant #1711)`,
+      );
+    }
+  } catch {
+    // Unreadable/unparseable: loadChantConfig reports it properly.
+  }
+}
+
+/** Top-level keys that make a config a *project* config rather than a lint fragment. */
+const PROJECT_CONFIG_KEYS = new Set(Object.keys(ChantConfigSchema.shape).filter((k) => k !== "lint"));
+
+/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
+export function isOwnershipParamRef(env: OwnershipEnv | undefined): env is { param: string } {
+  return typeof env === "object" && env !== null && typeof env.param === "string";
+}
+
+/**
+ * The ownership stack identity alone — `ownership.stack` when marking is on
+ * (no `stack`, or `enabled: false`, means off). For callers that need the
+ * stack and nothing else (a field manager, a prune selector) and so have no
+ * build parameters to resolve `env` against.
  */
-export function resolveOwnershipMarker(config: ChantConfig): OwnershipMarker | undefined {
+export function resolveOwnershipStack(config: ChantConfig): string | undefined {
   const o = config.ownership;
   if (!o || !o.stack || o.enabled === false) return undefined;
-  return { stack: o.stack, env: o.env };
+  return o.stack;
+}
+
+/**
+ * Resolve the `env` half of the ownership marker (#1396). A literal is
+ * returned as-is. A `{ param }` reference is looked up in this build's resolved
+ * build parameters and must find one: a reference to a parameter that was
+ * never declared, or that resolved to no value, throws rather than quietly
+ * stamping a marker without an env — an env-less marker is exactly what lets
+ * a prod deployment go unseen by `--owned` filtering scoped to prod.
+ */
+export function resolveOwnershipEnv(
+  config: ChantConfig,
+  buildParams: readonly BuildParamProvenance[] | undefined,
+): string | undefined {
+  const env = config.ownership?.env;
+  if (!isOwnershipParamRef(env)) return env;
+  const name = env.param;
+  const declared = config.buildParams?.[name];
+  if (!declared) {
+    throw new Error(
+      `ownership.env references build parameter "${name}", which chant.config.ts's buildParams does not declare`,
+    );
+  }
+  const resolved = buildParams?.find((p) => p.name === name);
+  if (!resolved) {
+    throw new Error(
+      `ownership.env references build parameter "${name}", which resolved to no value for this build — pass --param ${name}=<value>${declared.env ? `, set ${declared.env}` : ""}, or give it a default`,
+    );
+  }
+  return String(resolved.value);
+}
+
+/**
+ * Resolve the ownership marker to stamp from project config, or undefined when
+ * ownership marking is off (no `stack`, or `enabled: false`). `buildParams` is
+ * this build's resolved parameters (`resolveBuildParams`'s provenance), which
+ * an `ownership.env: { param }` reference resolves against — see {@link
+ * resolveOwnershipEnv}; it throws when the reference cannot be satisfied.
+ */
+export function resolveOwnershipMarker(
+  config: ChantConfig,
+  buildParams?: readonly BuildParamProvenance[],
+): OwnershipMarker | undefined {
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) return undefined;
+  return { stack, env: resolveOwnershipEnv(config, buildParams) };
+}
+
+/**
+ * The divergence #1396 is about, made loud when it cannot be removed: a
+ * project whose `ownership.env` is a literal while it also declares a build
+ * parameter named `env` has two answers to "which environment is this", and
+ * the manifest carries both (the ownership marker from config, the labels
+ * from the parameter). Returns a warning naming both values when they differ;
+ * undefined when there is nothing to say (no literal, no `env` parameter, or
+ * the two agree). The fix is the `{ param: "env" }` reference.
+ */
+export function ownershipEnvDisagreement(
+  config: ChantConfig,
+  buildParams: readonly BuildParamProvenance[] | undefined,
+): string | undefined {
+  const literal = config.ownership?.env;
+  if (typeof literal !== "string") return undefined;
+  if (resolveOwnershipStack(config) === undefined) return undefined;
+  const param = buildParams?.find((p) => p.name === "env");
+  if (!param || String(param.value) === literal) return undefined;
+  return (
+    `ownership.env is "${literal}" but the env build parameter resolved to ${JSON.stringify(param.value)} (${param.source}) — ` +
+    `the ownership marker and params.env disagree about which environment this build is for. ` +
+    `Use ownership: { env: { param: "env" } } so the marker follows the parameter.`
+  );
 }
 
 /**