@intentius/chant 0.13.0 → 0.15.0

package/src/components/component-schema.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Validates the Component JSON Schema (draft 2020-12) itself, plus every
+ * fixture under __fixtures__/ against it.
+ *
+ * The schema is the portable contract described in
+ * docs/src/content/docs/components/component-contract.mdx and
+ * composition-and-wiring.mdx — see #551 (epic) and #553 (this schema).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import Ajv2020 from "ajv/dist/2020";
+import componentSchema from "./component.schema.json";
+
+const FIXTURES_DIR = join(import.meta.dirname, "__fixtures__");
+
+function loadFixtures(): Array<{ name: string; data: unknown }> {
+  return readdirSync(FIXTURES_DIR)
+    .filter((f) => f.endsWith(".json"))
+    .sort()
+    .map((name) => ({
+      name,
+      data: JSON.parse(readFileSync(join(FIXTURES_DIR, name), "utf-8")),
+    }));
+}
+
+describe("Component JSON Schema", () => {
+  const ajv = new Ajv2020({ strict: true, allErrors: true });
+  const validate = ajv.compile(componentSchema);
+
+  it("is itself a valid draft 2020-12 schema document", () => {
+    expect(componentSchema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(ajv.validateSchema(componentSchema)).toBe(true);
+  });
+
+  it("has a stable $id and a contract version", () => {
+    expect(componentSchema.$id).toBe(
+      "https://intentius.io/chant/schemas/component/v1/component.schema.json",
+    );
+    expect(componentSchema.properties.contractVersion.const).toBe("1.0.0");
+  });
+
+  const fixtures = loadFixtures();
+
+  it("finds fixtures to validate", () => {
+    expect(fixtures.length).toBeGreaterThanOrEqual(4);
+    expect(fixtures.length).toBeLessThanOrEqual(7);
+  });
+
+  it.each(fixtures.map((f) => [f.name, f.data] as const))(
+    "fixture %s validates against the schema",
+    (name, data) => {
+      const valid = validate(data);
+      if (!valid) {
+        throw new Error(`${name} failed schema validation: ${ajv.errorsText(validate.errors)}`);
+      }
+      expect(valid).toBe(true);
+    },
+  );
+
+  it("rejects a component missing the required `deploy` field", () => {
+    const invalid = { name: "broken", dependsOn: [] };
+    expect(validate(invalid)).toBe(false);
+  });
+
+  it("rejects a component name that is not kebab-case", () => {
+    const invalid = { name: "Not_Kebab", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };
+    expect(validate(invalid)).toBe(false);
+  });
+
+  it("rejects an unknown top-level field (additionalProperties: false)", () => {
+    const invalid = {
+      name: "x",
+      dependsOn: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+      notAField: true,
+    };
+    expect(validate(invalid)).toBe(false);
+  });
+
+  it("accepts a producer-library component whose deploy is publish-only", () => {
+    const producer = {
+      name: "jar-lib",
+      archetype: "producer-library",
+      dependsOn: [],
+      build: { kind: "jvm-build" },
+      deploy: [{ phase: "Publish", steps: [{ kind: "publish-artifact", from: "archive", to: "$env.s3" }] }],
+    };
+    expect(validate(producer)).toBe(true);
+  });
+
+  it("accepts an infra component with no build", () => {
+    const infra = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(infra)).toBe(true);
+  });
+
+  it("accepts an optional liveNames mapping (#598)", () => {
+    const withLiveNames = {
+      name: "search-svc",
+      archetype: "service",
+      dependsOn: [],
+      liveNames: ["search-service-v2"],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(withLiveNames)).toBe(true);
+  });
+
+  it("accepts several liveNames for a component that owns multiple live entities (#598)", () => {
+    const fanOutLiveNames = {
+      name: "neo4j-cluster",
+      archetype: "infra",
+      dependsOn: [],
+      liveNames: ["cluster-node-1", "cluster-node-2"],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(fanOutLiveNames)).toBe(true);
+  });
+
+  it("omitting liveNames still validates (backward-compatible default)", () => {
+    const noLiveNames = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(noLiveNames)).toBe(true);
+  });
+
+  it("rejects an empty liveNames array (minItems: 1)", () => {
+    const invalid = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      liveNames: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(invalid)).toBe(false);
+  });
+
+  it("rejects an invalid archetype value", () => {
+    const invalid = {
+      name: "x",
+      archetype: "worker",
+      dependsOn: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+    };
+    expect(validate(invalid)).toBe(false);
+  });
+
+  it("accepts a gate step inside a phase", () => {
+    const withGate = {
+      name: "gated",
+      dependsOn: [],
+      deploy: [
+        {
+          phase: "Approve",
+          steps: [{ kind: "gate", signalName: "approve-gated", description: "confirm", timeout: "24h" }],
+        },
+      ],
+    };
+    expect(validate(withGate)).toBe(true);
+  });
+
+  it("rejects a gate step missing signalName", () => {
+    const invalid = {
+      name: "gated",
+      dependsOn: [],
+      deploy: [{ phase: "Approve", steps: [{ kind: "gate" }] }],
+    };
+    expect(validate(invalid)).toBe(false);
+  });
+
+  it("accepts a stackOutput cross-stack reference", () => {
+    const withStackOutput = {
+      name: "svc",
+      dependsOn: ["shared-alb"],
+      deploy: [
+        {
+          phase: "Apply",
+          steps: [
+            {
+              kind: "cfn-deploy",
+              inputs: { listenerArn: { stackOutput: { stack: "shared-alb", name: "ListenerArn" } } },
+            },
+          ],
+        },
+      ],
+    };
+    expect(validate(withStackOutput)).toBe(true);
+  });
+
+  it("accepts a fan-out phase nesting a mini-composition", () => {
+    const fanOut = {
+      name: "cluster",
+      dependsOn: [],
+      deploy: [
+        {
+          phase: "Rolling",
+          steps: [
+            { phase: "Node 1", steps: [{ kind: "cfn-deploy", template: "t.json" }] },
+            { phase: "Node 2", steps: [{ kind: "cfn-deploy", template: "t.json" }] },
+          ],
+        },
+      ],
+    };
+    expect(validate(fanOut)).toBe(true);
+  });
+
+  it("accepts parallel steps within a phase", () => {
+    const parallelPhase = {
+      name: "svc",
+      dependsOn: [],
+      deploy: [
+        {
+          phase: "Verify",
+          parallel: true,
+          steps: [{ kind: "wait-for-stack", stack: "a" }, { kind: "wait-endpoint", url: "b" }],
+        },
+      ],
+    };
+    expect(validate(parallelPhase)).toBe(true);
+  });
+
+  describe("wiring reference forms", () => {
+    function componentWith(imageRef: unknown) {
+      return {
+        name: "svc",
+        dependsOn: [],
+        deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", imageRef }] }],
+      };
+    }
+
+    it("accepts a prior-step reference (@Phase.field)", () => {
+      expect(validate(componentWith("@Publish.digest"))).toBe(true);
+    });
+
+    it("accepts a cross-component artifact reference (@component.publish.uri|digest|key)", () => {
+      expect(validate(componentWith("@jar-lib.publish.uri"))).toBe(true);
+      expect(validate(componentWith("@jar-lib.publish.digest"))).toBe(true);
+      expect(validate(componentWith("@jar-lib.publish.key"))).toBe(true);
+    });
+
+    it("accepts an $env.* reference", () => {
+      expect(validate(componentWith("$env.registry"))).toBe(true);
+    });
+
+    it("accepts a plain literal string with no reference sigil", () => {
+      expect(validate(componentWith("sha256:abc123"))).toBe(true);
+    });
+
+    it("rejects a cross-component reference to an unrecognized artifact field", () => {
+      expect(validate(componentWith("@jar-lib.publish.nonsense"))).toBe(false);
+    });
+
+    it("rejects a malformed @ reference with no dotted path", () => {
+      expect(validate(componentWith("@justaname"))).toBe(false);
+    });
+  });
+});

package/src/components/component.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/component/v1/component.schema.json",
+  "title": "Component",
+  "description": "The portable JSON contract for a chant component — a releasable unit (service, infra, or producer/library) declared as data. This document is the substrate: chant's TypeScript authoring form projects to it, and a non-chant or legacy component may hand-write it directly. See docs/src/content/docs/components/component-contract.mdx and composition-and-wiring.mdx, which are authoritative over this schema.",
+  "type": "object",
+  "required": ["name", "dependsOn", "deploy"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional self-reference to this schema's $id, for editor tooling and validators."
+    },
+    "contractVersion": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Version of the Component contract this document conforms to. Versioned independently of chant's own release train."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case component identifier, unique within the project. Used as the node name in the dependency graph and as the `@<component>` prefix in cross-component wiring references."
+    },
+    "dependsOn": {
+      "type": "array",
+      "description": "Other component names that must complete before this one runs. Ordering only — no logic. Resolved by `chant graph --stacks` into order and parallel-safe waves.",
+      "items": { "type": "string", "minLength": 1 },
+      "default": []
+    },
+    "build": { "$ref": "#/$defs/BuildSpec" },
+    "deploy": {
+      "type": "array",
+      "description": "The component's own composition over shared capabilities: an ordered list of phases. verify and rollback fall out of the capabilities used (e.g. a Verify phase, or a capability's own compensation) rather than being separate top-level fields.",
+      "items": { "$ref": "#/$defs/Phase" },
+      "minItems": 1
+    },
+    "verify": {
+      "type": "array",
+      "description": "Optional standalone verify phases, for components that separate verification from the main deploy composition (e.g. re-run as a health check outside a deploy). Most components instead include a Verify phase inline in `deploy`.",
+      "items": { "$ref": "#/$defs/Phase" }
+    },
+    "rollback": {
+      "type": "array",
+      "description": "Optional explicit compensation phases, executed in reverse order on terminal failure of `deploy` (a saga). Equivalent in shape to an Op's `onFailure`. Most rollback instead falls out of per-step `rollback`/compensation declared by the capabilities used; this field is for a component-level override or an escape-hatch capability with no native compensation.",
+      "items": { "$ref": "#/$defs/Phase" }
+    },
+    "archetype": {
+      "$ref": "#/$defs/Archetype",
+      "description": "Optional explicit archetype hint. When omitted, the archetype is inferred structurally from which phases/capability families are present (see the archetype table in component-contract.mdx)."
+    },
+    "liveNames": {
+      "type": "array",
+      "description": "Optional: the live lexicon entity/resource name(s) this component owns, when they differ from `name` (#598). `chant components status --live` reconciles the release ledger against live evidence by joining on this name; omitted entirely (the default), the join falls back to `name` itself with no behavior change. A component that owns several live entities (e.g. a fan-out cluster with one stack per node) may list them all.",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    }
+  },
+  "$defs": {
+    "Archetype": {
+      "type": "string",
+      "enum": ["service", "infra", "producer-library"],
+      "description": "The three first-class shapes `deploy` can take. service: build -> publish -> apply -> verify (e.g. an ECS service behind an ALB). infra: apply -> verify, no build (e.g. a DynamoDB table, an EMR cluster). producer-library: build -> publish only, no service apply — emits an artifact other components consume (e.g. a JAR published to S3 for EMR)."
+    },
+
+    "BuildSpec": {
+      "type": "object",
+      "description": "Optional: source -> BuildArchive. Omitted entirely for config-only / infra components that apply existing templates with no build step.",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Build capability verb, keyed by artifact type, e.g. \"docker-build\", \"zip-package\", \"jvm-build\". Not a closed enum — the capability registry is a plugin registry."
+        },
+        "context": {
+          "type": "string",
+          "description": "Build context path (e.g. a Docker build context directory)."
+        },
+        "into": {
+          "type": "string",
+          "const": "archive",
+          "description": "Build output always lands in the self-contained BuildArchive; this field documents that destination explicitly in the JSON projection."
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "Phase": {
+      "type": "object",
+      "description": "One named phase of a deploy composition, run in order relative to sibling phases. Steps within a phase run sequentially unless `parallel` is set.",
+      "required": ["phase", "steps"],
+      "additionalProperties": false,
+      "properties": {
+        "phase": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Phase display name (e.g. \"Publish\", \"Apply\", \"Verify\", \"Seed\", \"Node 1\"). Also the namespace prior-step wiring references key off (`@Phase.field`)."
+        },
+        "steps": {
+          "type": "array",
+          "description": "Ordered steps in this phase. A step may itself be a Step (a capability invocation), a Gate, or a nested Phase — a fan-out unit is itself a mini-composition (see composition-and-wiring.mdx).",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/Step" },
+              { "$ref": "#/$defs/Gate" },
+              { "$ref": "#/$defs/Phase" }
+            ]
+          },
+          "minItems": 1
+        },
+        "parallel": {
+          "type": "boolean",
+          "default": false,
+          "description": "Run all steps in this phase concurrently instead of sequentially."
+        },
+        "onFailure": {
+          "type": "array",
+          "description": "Compensation phases for this phase, executed in reverse order on failure (saga rollback). Capabilities that declare their own compensation get this for free; this field is for an explicit override.",
+          "items": { "$ref": "#/$defs/Phase" }
+        }
+      }
+    },
+
+    "Step": {
+      "type": "object",
+      "description": "A single 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. Capability-specific properties are open (the capability interface itself is out of scope for this schema — see #554); the handful of cross-cutting properties below are typed as WiringValue because they commonly carry a reference rather than a literal. `kind: \"gate\"` is reserved for the Gate step shape below, not a capability.",
+      "required": ["kind"],
+      "additionalProperties": true,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "minLength": 1,
+          "not": { "const": "gate" },
+          "description": "Capability verb this step dispatches to, e.g. \"docker-build\", \"publish-image\", \"cfn-deploy\", \"ecs-update-service\", \"emr-start-job-run\", \"code-deploy\", \"wait-steady-state\", \"health-gate\", \"shell\". Not a closed enum — the capability registry is a plugin registry; new verbs are added without changing this schema."
+        },
+        "imageRef": {
+          "$ref": "#/$defs/WiringValue",
+          "description": "Reference to a published image digest, typically a prior-step reference like \"@Publish.digest\"."
+        },
+        "jar": {
+          "$ref": "#/$defs/WiringValue",
+          "description": "Reference to a published JAR/artifact location, typically a cross-component artifact reference like \"@jar-lib.publish.uri\"."
+        },
+        "revision": {
+          "$ref": "#/$defs/WiringValue",
+          "description": "Reference to a published revision/bundle location for host/code-delivery capabilities (e.g. code-deploy)."
+        },
+        "inputs": {
+          "type": "object",
+          "description": "Named inputs passed into an apply step, each of which may be a literal or any WiringValue reference — most commonly a stackOutput reference imported from another component's stack.",
+          "additionalProperties": { "$ref": "#/$defs/WiringValue" }
+        }
+      }
+    },
+
+    "Gate": {
+      "type": "object",
+      "description": "Pauses the composition for an external signal (typically human approval) before continuing. A gate in a component's composition requires the durable (Temporal) execution backend; it cannot run on the local in-process executor.",
+      "required": ["kind", "signalName"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "type": "string", "const": "gate" },
+        "signalName": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Signal name the generated workflow waits for before continuing."
+        },
+        "timeout": {
+          "type": "string",
+          "description": "Duration string bounding the wait, e.g. \"48h\". Default: \"48h\"."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the action required to unblock this gate."
+        }
+      }
+    },
+
+    "WiringValue": {
+      "description": "A string value that is either a literal or one of the three reference forms components use to wire to configuration, prior steps, cross-stack outputs, or cross-component artifacts. All forms are resolved by the graph (`chant graph --stacks`), never by orchestrator code.",
+      "oneOf": [
+        { "type": "string", "not": { "pattern": "^(\\$env\\.|@)" } },
+        { "$ref": "#/$defs/EnvReference" },
+        { "$ref": "#/$defs/PriorStepReference" },
+        { "$ref": "#/$defs/ComponentArtifactReference" },
+        { "$ref": "#/$defs/StackOutputReference" }
+      ]
+    },
+
+    "EnvReference": {
+      "type": "string",
+      "pattern": "^\\$env\\.[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)*$",
+      "description": "Reference to the current deploy environment's config, e.g. \"$env.registry\", \"$env.cluster\"."
+    },
+
+    "PriorStepReference": {
+      "type": "string",
+      "pattern": "^@[A-Za-z0-9_ ]+\\.[A-Za-z0-9_]+(\\.[A-Za-z0-9_]+)*$",
+      "description": "Reference to a prior step's output within the same component, addressed by phase name, e.g. \"@Publish.digest\", \"@Submit.runId\". Does not contain a dot before the phase name, distinguishing it from a cross-component reference (\"@<component>.publish...\")."
+    },
+
+    "ComponentArtifactReference": {
+      "type": "string",
+      "pattern": "^@[a-z0-9]+(-[a-z0-9]+)*\\.publish\\.(uri|digest|key)$",
+      "description": "Reference to another component's published artifact output, e.g. \"@jar-lib.publish.uri\", \"@search-service.publish.digest\". The referenced component must appear in this component's dependsOn; the graph resolves the reference into this step, never the orchestrator."
+    },
+
+    "StackOutputReference": {
+      "type": "object",
+      "description": "Reference to a cross-stack (CloudFormation/ARM/...) output exported by another stack, resolved by the graph the same way `stackOutput()` is resolved in the TypeScript authoring form. Replaces a `describe-stacks | jq` pipeline step.",
+      "required": ["stackOutput"],
+      "additionalProperties": false,
+      "properties": {
+        "stackOutput": {
+          "type": "object",
+          "required": ["stack", "name"],
+          "additionalProperties": false,
+          "properties": {
+            "stack": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Name of the exporting component/stack, e.g. \"shared-alb\"."
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Name of the exported output, e.g. \"ListenerArn\", \"ClusterArn\"."
+            }
+          }
+        }
+      }
+    }
+  }
+}