@intentius/chant 0.13.1 → 0.15.0

package/src/components/component.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Unit tests for the typed `Component` authoring form (#560, epic #551):
+ * the `phase()`/`gate()`/`stackOutput()` builders, `isComponent`,
+ * `inferArchetype`, and `projectToJson`. Schema-validation and
+ * fixture-equality coverage for real components lives in
+ * `./component-schema.test.ts` and `./pilots/pilots.test.ts`; this file
+ * covers the authoring API's own behavior in isolation.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  phase,
+  gate,
+  stackOutput,
+  isComponent,
+  inferArchetype,
+  projectToJson,
+  type Component,
+} from "./component";
+
+describe("phase()", () => {
+  it("builds a Phase with no parallel flag by default", () => {
+    expect(phase("Apply", [{ kind: "shell" }])).toEqual({
+      phase: "Apply",
+      steps: [{ kind: "shell" }],
+    });
+  });
+
+  it("sets parallel: true when requested", () => {
+    expect(phase("Verify", [{ kind: "shell" }], { parallel: true })).toEqual({
+      phase: "Verify",
+      steps: [{ kind: "shell" }],
+      parallel: true,
+    });
+  });
+});
+
+describe("gate()", () => {
+  it("builds a minimal Gate", () => {
+    expect(gate("approve-x")).toEqual({ kind: "gate", signalName: "approve-x" });
+  });
+
+  it("carries optional timeout/description", () => {
+    expect(gate("approve-x", { timeout: "24h", description: "confirm" })).toEqual({
+      kind: "gate",
+      signalName: "approve-x",
+      timeout: "24h",
+      description: "confirm",
+    });
+  });
+});
+
+describe("stackOutput()", () => {
+  it("builds a StackOutputReference", () => {
+    expect(stackOutput("shared-alb", "ListenerArn")).toEqual({
+      stackOutput: { stack: "shared-alb", name: "ListenerArn" },
+    });
+  });
+});
+
+describe("isComponent()", () => {
+  it("accepts a minimal valid Component shape", () => {
+    expect(isComponent({ name: "x", dependsOn: [], deploy: [] })).toBe(true);
+  });
+
+  it("rejects null/non-objects", () => {
+    expect(isComponent(null)).toBe(false);
+    expect(isComponent(42)).toBe(false);
+    expect(isComponent("x")).toBe(false);
+    expect(isComponent(undefined)).toBe(false);
+  });
+
+  it("rejects an object missing dependsOn or deploy", () => {
+    expect(isComponent({ name: "x" })).toBe(false);
+    expect(isComponent({ name: "x", dependsOn: [] })).toBe(false);
+    expect(isComponent({ dependsOn: [], deploy: [] })).toBe(false);
+  });
+
+  it("rejects a plain non-Component object (e.g. a helper/const export)", () => {
+    expect(isComponent({ foo: "bar" })).toBe(false);
+  });
+});
+
+describe("inferArchetype()", () => {
+  it("infers infra when there is no build", () => {
+    expect(
+      inferArchetype({
+        deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+      }),
+    ).toBe("infra");
+  });
+
+  it("infers producer-library when build is present and every step is publish-family", () => {
+    expect(
+      inferArchetype({
+        build: { kind: "jvm-build" },
+        deploy: [phase("Publish", [{ kind: "publish-artifact" }])],
+      }),
+    ).toBe("producer-library");
+  });
+
+  it("infers producer-library when the only non-publish steps are gates", () => {
+    expect(
+      inferArchetype({
+        build: { kind: "docker-build" },
+        deploy: [phase("Publish", [gate("approve"), { kind: "publish-image" }])],
+      }),
+    ).toBe("producer-library");
+  });
+
+  it("infers service when build is present and an apply/verify step follows publish", () => {
+    expect(
+      inferArchetype({
+        build: { kind: "docker-build" },
+        deploy: [
+          phase("Publish", [{ kind: "publish-image" }]),
+          phase("Apply", [{ kind: "cfn-deploy" }]),
+        ],
+      }),
+    ).toBe("service");
+  });
+
+  it("infers service for load-image-on-host + a non-publish apply step (single-host compose shape)", () => {
+    expect(
+      inferArchetype({
+        build: { kind: "docker-build" },
+        deploy: [
+          phase("Publish", [{ kind: "load-image-on-host" }]),
+          phase("Apply", [{ kind: "remote-exec" }]),
+        ],
+      }),
+    ).toBe("service");
+  });
+
+  it("looks inside nested fan-out phases", () => {
+    expect(
+      inferArchetype({
+        build: { kind: "docker-build" },
+        deploy: [
+          phase("Rolling", [
+            phase("Node 1", [{ kind: "publish-image" }]),
+            phase("Node 2", [{ kind: "cfn-deploy" }]),
+          ]),
+        ],
+      }),
+    ).toBe("service");
+  });
+});
+
+describe("projectToJson()", () => {
+  it("fills in archetype via inferArchetype when the author omits it", () => {
+    const component: Component = {
+      name: "table",
+      dependsOn: [],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as { archetype: string };
+    expect(projected.archetype).toBe("infra");
+  });
+
+  it("keeps an explicit archetype as authored, even if it disagrees with the inferred shape", () => {
+    const component: Component = {
+      name: "table",
+      archetype: "service",
+      dependsOn: [],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as { archetype: string };
+    expect(projected.archetype).toBe("service");
+  });
+
+  it("drops undefined optional fields (build/verify/rollback) rather than emitting nulls", () => {
+    const component: Component = {
+      name: "table",
+      dependsOn: [],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as Record<string, unknown>;
+    expect("build" in projected).toBe(false);
+    expect("verify" in projected).toBe(false);
+    expect("rollback" in projected).toBe(false);
+  });
+
+  it("projects an explicit liveNames mapping through unchanged (#598)", () => {
+    const component: Component = {
+      name: "search-svc",
+      dependsOn: [],
+      liveNames: ["search-service-v2"],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as { liveNames?: string[] };
+    expect(projected.liveNames).toEqual(["search-service-v2"]);
+  });
+
+  it("omits liveNames from the projection when not authored (#598)", () => {
+    const component: Component = {
+      name: "table",
+      dependsOn: [],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as Record<string, unknown>;
+    expect("liveNames" in projected).toBe(false);
+  });
+
+  it("projects a stackOutput() wiring reference to its plain-JSON form", () => {
+    const component: Component = {
+      name: "svc",
+      dependsOn: ["shared-alb"],
+      deploy: [
+        phase("Apply", [
+          { kind: "cfn-deploy", inputs: { listenerArn: stackOutput("shared-alb", "ListenerArn") } },
+        ]),
+      ],
+    };
+    const projected = projectToJson(component) as {
+      deploy: Array<{ steps: Array<{ inputs: Record<string, unknown> }> }>;
+    };
+    expect(projected.deploy[0]!.steps[0]!.inputs.listenerArn).toEqual({
+      stackOutput: { stack: "shared-alb", name: "ListenerArn" },
+    });
+  });
+});
+
+describe("BuildSpec.sbom (#606 — component-level SBOM authoring hint)", () => {
+  it("projects an authored sbom hint through unchanged, riding BuildSpec's open additionalProperties shape", () => {
+    const component: Component = {
+      name: "search-service",
+      dependsOn: [],
+      build: { kind: "docker-build", context: ".", sbom: { format: "cyclonedx" } },
+      deploy: [phase("Publish", [{ kind: "publish-image" }])],
+    };
+    const projected = projectToJson(component) as { build: { sbom?: { format?: string; optOut?: boolean } } };
+    expect(projected.build.sbom).toEqual({ format: "cyclonedx" });
+  });
+
+  it("omits sbom from the projection when not authored (no behavior change for existing components)", () => {
+    const component: Component = {
+      name: "search-service",
+      dependsOn: [],
+      build: { kind: "docker-build", context: "." },
+      deploy: [phase("Publish", [{ kind: "publish-image" }])],
+    };
+    const projected = projectToJson(component) as { build: Record<string, unknown> };
+    expect("sbom" in projected.build).toBe(false);
+  });
+
+  it("supports an explicit opt-out hint", () => {
+    const build = { kind: "docker-build", sbom: { optOut: true } };
+    expect(build.sbom.optOut).toBe(true);
+  });
+});

package/src/components/component.ts

@@ -0,0 +1,255 @@
+/**
+ * Typed `Component` authoring form — Phase 2 (#560, epic #551).
+ *
+ * This is the real authoring frontend the docs (component-contract.mdx,
+ * composition-and-wiring.mdx) describe and that `pilots/authoring-shape.ts`
+ * (#555's stopgap) explicitly deferred to this issue. It mirrors
+ * `component.schema.json` field-for-field, so `projectToJson` stays a
+ * structural no-op — the interesting content lives in each component's
+ * composition, not in a bespoke serializer.
+ *
+ * See https://intentius.io/chant/components/component-contract/ and
+ * https://intentius.io/chant/components/composition-and-wiring/.
+ */
+
+/** Mirrors `$defs.Archetype` in component.schema.json. */
+export type Archetype = "service" | "infra" | "producer-library";
+
+/** Mirrors `$defs.StackOutputReference`. */
+export interface StackOutputReference {
+  stackOutput: { stack: string; name: string };
+}
+
+/**
+ * Mirrors `$defs.WiringValue` — a literal, or one of the reference forms
+ * (`$env.*`, `@Phase.field`, `@<component>.publish.uri|digest|key`, or a
+ * `{ stackOutput }` object), all resolved by the graph rather than by
+ * orchestrator code. Loosened to `string` for the literal/`$env`/prior-step/
+ * artifact-reference forms since they share one representation; only
+ * `stackOutput` needs its own shape.
+ */
+export type Wiring = string | StackOutputReference;
+
+/** Mirrors `$defs.BuildSpec`. */
+export interface BuildSpec {
+  /** Build capability verb, keyed by artifact type, e.g. "docker-build", "zip-package", "jvm-build". */
+  kind: string;
+  /** Build context path (e.g. a Docker build context directory). */
+  context?: string;
+  /** Build output always lands in the self-contained BuildArchive. */
+  into?: "archive";
+  /**
+   * Optional component-level SBOM authoring hint (#606, epic #551 follow-up
+   * to #564/#568) — not itself a `generate-sbom` step (that is composed
+   * explicitly in `deploy`/build tooling, see
+   * ../verbs/sbom.ts's `GenerateSbomInput`); this is metadata an authoring
+   * frontend or generator can read when deciding whether/how to compose
+   * that step for this component. Rides `BuildSpec`'s existing
+   * `additionalProperties: true` in component.schema.json — no schema change
+   * needed for this extension.
+   */
+  sbom?: {
+    /** Preferred SBOM format for this component, overriding `chant.config.ts`'s project-wide `sbom.format` default (see ../../config.ts's `resolveSbomFormat`). */
+    format?: "spdx" | "cyclonedx";
+    /** Set true to skip SBOM generation for this component even where a project default would otherwise include it. `generate-sbom` is never invoked implicitly — this only documents intent for whatever composes the component's build phase. */
+    optOut?: boolean;
+  };
+  [extra: string]: unknown;
+}
+
+/**
+ * Mirrors `$defs.Step` — one capability invocation, the leaf unit of a
+ * composition. `kind` selects the capability (a verb, e.g. "cfn-deploy",
+ * "publish-image", "ecs-update-service"); the remaining properties are that
+ * capability's typed input. `kind: "gate"` is reserved for `Gate` below, not
+ * a capability — use `gate()` to author one.
+ */
+export interface Step {
+  kind: string;
+  /** Reference to a published image digest, typically `"@Publish.digest"`. */
+  imageRef?: Wiring;
+  /** Reference to a published JAR/artifact location, e.g. `"@jar-lib.publish.uri"`. */
+  jar?: Wiring;
+  /** Reference to a published revision/bundle location for host/code-delivery capabilities. */
+  revision?: Wiring;
+  /** Named inputs passed into an apply step; each may be a literal or any wiring reference. */
+  inputs?: Record<string, Wiring>;
+  [param: string]: unknown;
+}
+
+/** Mirrors `$defs.Gate` — pauses the composition for an external signal (typically human approval). */
+export interface Gate {
+  kind: "gate";
+  signalName: string;
+  /** Duration string bounding the wait, e.g. "48h". Default: "48h". */
+  timeout?: string;
+  /** Human-readable description of the action required to unblock this gate. */
+  description?: string;
+}
+
+/**
+ * Mirrors `$defs.Phase` — one named phase of a deploy composition. A step may
+ * itself be a nested `Phase`, which is how a fan-out unit becomes a mini-
+ * composition (see composition-and-wiring.mdx).
+ */
+export interface Phase {
+  phase: string;
+  steps: Array<Step | Gate | Phase>;
+  /** Run all steps in this phase concurrently instead of sequentially. */
+  parallel?: boolean;
+  /** Compensation phases for this phase, executed in reverse order on failure. */
+  onFailure?: Phase[];
+}
+
+/**
+ * The typed `Component` authoring form — projects 1:1 to the JSON contract
+ * (component.schema.json). `archetype` is optional on both sides: when
+ * omitted here, `projectToJson` infers it structurally (see
+ * `inferArchetype`) so the JSON projection always carries an explicit value,
+ * matching how the merged fixtures are authored.
+ */
+export interface Component {
+  name: string;
+  /** Optional explicit archetype hint; inferred from the composition shape when omitted (see `inferArchetype`). */
+  archetype?: Archetype;
+  /** Other component names that must complete before this one runs. Ordering only — no logic. */
+  dependsOn: string[];
+  /** Optional: source -> BuildArchive. Omitted entirely for config-only / infra components. */
+  build?: BuildSpec;
+  /** The component's own composition over shared capabilities. */
+  deploy: Phase[];
+  /** Optional standalone verify phases, for components that separate verification from `deploy`. */
+  verify?: Phase[];
+  /** Optional explicit compensation phases, executed in reverse order on terminal failure of `deploy`. */
+  rollback?: Phase[];
+  /**
+   * Optional: the live lexicon entity/resource name(s) this component owns,
+   * when they differ from `name` (#598). `chant components status --live`
+   * joins the release ledger against live evidence by name; components and
+   * lexicon entities are different namespaces in general (see
+   * `../lifecycle/status.ts`), so a component whose deploy composition
+   * targets an entity/resource declared under a different name must say so
+   * explicitly here. A component that owns several entities (e.g. a fan-out
+   * cluster with one stack per node) may list them all — live evidence is
+   * aggregated across every name. Omitted entirely (the common case for the
+   * pilot components) falls back to `[name]`, preserving the original
+   * name == entity join with no behavior change.
+   */
+  liveNames?: string[];
+}
+
+/** Author a named phase. `steps` may mix capability `Step`s, `Gate`s, and nested `Phase`s (fan-out). */
+export function phase(name: string, steps: Array<Step | Gate | Phase>, opts?: { parallel?: boolean }): Phase {
+  return { phase: name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
+}
+
+/** Author a gate step — pauses the composition for an external signal (typically human approval). */
+export function gate(signalName: string, opts?: { timeout?: string; description?: string }): Gate {
+  return { kind: "gate", signalName, ...opts };
+}
+
+/**
+ * Author a cross-stack output reference — the TypeScript-side equivalent of
+ * the JSON contract's `{ stackOutput: { stack, name } }` (schema
+ * `StackOutputReference`), e.g. `stackOutput("shared-alb", "ListenerArn")`.
+ * Resolved by `chant graph --stacks`, never by orchestrator code.
+ */
+export function stackOutput(stack: string, name: string): StackOutputReference {
+  return { stackOutput: { stack, name } };
+}
+
+/**
+ * Every capability-family marker `inferArchetype` looks for, grouped the same
+ * way component-contract.mdx's archetype table groups phases. Kept as a plain
+ * list (not the full starter verb set) so this module has no dependency on
+ * `./registry`/`./verbs` — inference is a structural, name-based heuristic
+ * over the composition, not a capability-registry lookup.
+ */
+const BUILD_ONLY_HINT = new Set(["docker-build", "zip-package", "jvm-build"]);
+const PUBLISH_KIND_PREFIX = /^(publish-|load-image-on-host)/;
+
+/** True if a step's `kind` looks like a publish-family capability (`publish-image`, `publish-artifact`, `load-image-on-host`, ...). */
+function isPublishStep(step: Step): boolean {
+  return PUBLISH_KIND_PREFIX.test(step.kind);
+}
+
+/**
+ * Distinguishes a nested fan-out `Phase` from a `Step`/`Gate` within a
+ * phase's `steps` array. `Step` carries an open index signature
+ * (`[param: string]: unknown`), so a plain `"phase" in s` structural check
+ * cannot narrow `Step` away from `Phase` — checking the concrete field types
+ * (`phase` is a string, `steps` is an array) here is what actually
+ * disambiguates them.
+ */
+function isNestedPhase(s: Step | Gate | Phase): s is Phase {
+  return typeof (s as Phase).phase === "string" && Array.isArray((s as Phase).steps);
+}
+
+/** Flatten every step across every phase (including nested fan-out phases) into one list, for structural inspection. */
+function allSteps(phases: Phase[]): Array<Step | Gate> {
+  const out: Array<Step | Gate> = [];
+  const walk = (ps: Phase[]) => {
+    for (const p of ps) {
+      for (const s of p.steps) {
+        if (isNestedPhase(s)) walk([s]);
+        else out.push(s);
+      }
+      if (p.onFailure) walk(p.onFailure);
+    }
+  };
+  walk(phases);
+  return out;
+}
+
+/**
+ * Infer a component's archetype from the shape of its composition, when no
+ * explicit `archetype` is authored — matching the archetype table in
+ * component-contract.mdx:
+ *  - **producer-library**: has a `build`, and every step across `deploy` is a
+ *    publish-family step (or a gate) — build -> publish only, no apply.
+ *  - **service**: has a `build` and at least one non-publish, non-gate step
+ *    (an apply/verify step) — build -> publish -> apply -> verify.
+ *  - **infra**: no `build` — apply -> verify only.
+ *
+ * This is a structural heuristic, not a capability-registry lookup (see
+ * `BUILD_ONLY_HINT`/`isPublishStep` above): it only needs to distinguish
+ * "nothing but publish" from "something else happens after publish", which
+ * every merged pilot/fixture satisfies without consulting the registry.
+ */
+export function inferArchetype(component: Pick<Component, "build" | "deploy">): Archetype {
+  if (!component.build) return "infra";
+
+  const steps = allSteps(component.deploy);
+  const nonGateSteps = steps.filter((s): s is Step => s.kind !== "gate");
+  const hasNonPublishStep = nonGateSteps.some((s) => !isPublishStep(s));
+
+  return hasNonPublishStep ? "service" : "producer-library";
+}
+
+/**
+ * Project a typed `Component` to its plain-JSON contract form
+ * (component.schema.json). Field names already match the schema 1:1, so
+ * projection is mechanical: a deep `JSON.parse(JSON.stringify())` round-trip
+ * (dropping `undefined` optional fields) plus filling in `archetype` via
+ * `inferArchetype` when the author didn't supply one explicitly. Kept
+ * intentionally dumb beyond that inference — the schema/fixtures stay the
+ * source of truth for shape, not this function.
+ */
+export function projectToJson(component: Component): unknown {
+  const withArchetype: Component = {
+    ...component,
+    archetype: component.archetype ?? inferArchetype(component),
+  };
+  return JSON.parse(JSON.stringify(withArchetype));
+}
+
+/** Runtime type guard: true if `value` looks like a `Component` (has the required `name`/`dependsOn`/`deploy` shape). Used by discovery to pick exported `Component` values out of a `*.component.ts` module without requiring a class/marker symbol. */
+export function isComponent(value: unknown): value is Component {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.name === "string" &&
+    Array.isArray(v.dependsOn) &&
+    Array.isArray(v.deploy)
+  );
+}