@intentius/chant 0.102.0 → 0.104.1

package/src/workspace/change-set.schema.json

@@ -0,0 +1,460 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
+  "title": "change-set document",
+  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu and warden members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "contract",
+    "digest",
+    "members",
+    "entries",
+    "summary"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json"
+    },
+    "contract": {
+      "const": 1
+    },
+    "chant": {
+      "type": "string",
+      "description": "The chant that composed the document."
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$",
+      "description": "computePlanDigest(\"change-set\", \u2026) over the members' { member, planDigest } pairs sorted by member, provisional members left out. What a gate over the whole run binds."
+    },
+    "members": {
+      "type": "array",
+      "description": "Sorted by member. Each name appears once.",
+      "items": {
+        "$ref": "#/$defs/member"
+      }
+    },
+    "entries": {
+      "type": "array",
+      "description": "Sorted by member, address, deposed key and action.",
+      "items": {
+        "$ref": "#/$defs/entry"
+      }
+    },
+    "sideEffects": {
+      "type": "array",
+      "description": "Provider-defined actions an apply runs (Terraform actions blocks), sorted by member and address. Absent when none.",
+      "items": {
+        "type": "object",
+        "required": ["member", "address", "type"],
+        "properties": {
+          "member": { "type": "string" },
+          "address": { "type": "string" },
+          "type": { "type": "string" },
+          "trigger": { "type": "string" },
+          "event": { "type": "string" }
+        }
+      }
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    }
+  },
+  "$defs": {
+    "member": {
+      "type": "object",
+      "required": [
+        "member",
+        "lexicon",
+        "planner",
+        "status",
+        "planDigest",
+        "holes"
+      ],
+      "properties": {
+        "member": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The workspace member, or the root a set plan names."
+        },
+        "lexicon": {
+          "type": "string"
+        },
+        "planner": {
+          "enum": [
+            "terraform",
+            "tofu",
+            "choudoufu",
+            "chant",
+            "warden"
+          ]
+        },
+        "scope": {
+          "type": "string",
+          "description": "The estate, environment or org the member plans into."
+        },
+        "status": {
+          "enum": [
+            "planned",
+            "failed"
+          ]
+        },
+        "error": {
+          "type": "string"
+        },
+        "planDigest": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "What a gate on this member alone binds. null when it failed to plan."
+        },
+        "nativeDigest": {
+          "type": "string",
+          "description": "The planner's own digest of the same plan, such as choudoufu's per-root digest."
+        },
+        "provisional": {
+          "const": true,
+          "description": "Planned before what it reads applied, so it may hold stand-in values (a Terragrunt dependent planned on mock_outputs). Left out of the document's digest, refused by a wave's set digest, and never grouped with real plans."
+        },
+        "holes": {
+          "type": "array",
+          "description": "What the planner could not read, so the plan says nothing about it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "address",
+              "reason"
+            ],
+            "properties": {
+              "address": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": [
+        "member",
+        "lexicon",
+        "planner",
+        "address",
+        "type",
+        "action",
+        "attributes"
+      ],
+      "properties": {
+        "member": {
+          "type": "string"
+        },
+        "lexicon": {
+          "type": "string"
+        },
+        "planner": {
+          "enum": [
+            "terraform",
+            "tofu",
+            "choudoufu",
+            "chant",
+            "warden"
+          ]
+        },
+        "address": {
+          "type": "string",
+          "description": "The planner's address, unique within the member with deposed."
+        },
+        "type": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string",
+          "description": "The resource name without module path or index."
+        },
+        "index": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "integer"
+            }
+          ],
+          "description": "A count or for_each index."
+        },
+        "module": {
+          "type": "string"
+        },
+        "deposed": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string",
+          "description": "The provider's id, when the planner reports one."
+        },
+        "importing": {
+          "const": true,
+          "description": "The entry also imports the object into state; action is what else the plan does to it."
+        },
+        "action": {
+          "enum": [
+            "create",
+            "update",
+            "replace",
+            "delete",
+            "read",
+            "no-op",
+            "forget"
+          ]
+        },
+        "disruption": {
+          "enum": [
+            "in-place",
+            "rolling",
+            "replace",
+            "destroy",
+            "unknown"
+          ],
+          "description": "Set on update, replace and delete."
+        },
+        "region": {
+          "type": "string"
+        },
+        "scope": {
+          "type": "string"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/attribute"
+          }
+        }
+      }
+    },
+    "attribute": {
+      "type": "object",
+      "required": [
+        "path"
+      ],
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "before": {},
+        "after": {},
+        "unknown": {
+          "const": true,
+          "description": "The value is known only after apply."
+        },
+        "sensitive": {
+          "const": true,
+          "description": "Marked sensitive: neither value is carried."
+        },
+        "forcesReplacement": {
+          "const": true
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "members",
+        "entries",
+        "actions",
+        "types",
+        "byMember",
+        "deletes",
+        "replacements",
+        "failed",
+        "holes"
+      ],
+      "properties": {
+        "members": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "entries": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "actions": {
+          "type": "object",
+          "required": [
+            "create",
+            "update",
+            "replace",
+            "delete",
+            "read",
+            "no-op",
+            "forget"
+          ],
+          "properties": {
+            "create": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "update": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "replace": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "delete": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "read": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "no-op": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "forget": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "additionalProperties": false
+        },
+        "types": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "propertyNames": {
+              "enum": [
+                "create",
+                "update",
+                "replace",
+                "delete",
+                "read",
+                "no-op",
+                "forget"
+              ]
+            },
+            "additionalProperties": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "byMember": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "propertyNames": {
+              "enum": [
+                "create",
+                "update",
+                "replace",
+                "delete",
+                "read",
+                "no-op",
+                "forget"
+              ]
+            },
+            "additionalProperties": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "deletes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "member",
+              "address",
+              "type"
+            ],
+            "properties": {
+              "member": {
+                "type": "string"
+              },
+              "address": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "deposed": {
+                "type": "string"
+              },
+              "disruption": {
+                "enum": [
+                  "in-place",
+                  "rolling",
+                  "replace",
+                  "destroy",
+                  "unknown"
+                ]
+              }
+            }
+          }
+        },
+        "replacements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "member",
+              "address",
+              "type"
+            ],
+            "properties": {
+              "member": {
+                "type": "string"
+              },
+              "address": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "deposed": {
+                "type": "string"
+              },
+              "disruption": {
+                "enum": [
+                  "in-place",
+                  "rolling",
+                  "replace",
+                  "destroy",
+                  "unknown"
+                ]
+              }
+            }
+          }
+        },
+        "failed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "holes": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/src/workspace/chant-migrations.e2e.test.ts

@@ -105,14 +105,15 @@ function ledger(): GateLedgerPort & { approve(digest: string): void } {
 const passing: ChantRunner = async () => ({ exitCode: 0, output: "" });
 
 /** Stage, approve and apply the upgrade, and commit it. */
-async function upgrade(): Promise<void> {
+async function upgrade(runChant: ChantRunner = passing): Promise<NonNullable<Awaited<ReturnType<typeof upgradeCommand>>["staged"]>> {
   const l = ledger();
-  const first = await upgradeCommand({ root: proj, to: target(), runChant: passing, ledger: l, now: "2026-09-25T00:00:00Z" });
+  const first = await upgradeCommand({ root: proj, to: target(), runChant, ledger: l, now: "2026-09-25T00:00:00Z" });
   expect(first.outcome).toBe("gated");
   l.approve(first.staged!.digest);
-  const second = await upgradeCommand({ root: proj, to: target(), runChant: passing, ledger: l, now: "2026-09-25T00:00:00Z" });
+  const second = await upgradeCommand({ root: proj, to: target(), runChant, ledger: l, now: "2026-09-25T00:00:00Z" });
   expect(second.outcome).toBe("applied");
   commit("chud-lexicon-exit");
+  return second.staged!;
 }
 
 async function makeProject(from: "dir" | "git"): Promise<void> {
@@ -763,10 +764,21 @@ describe("the migrated delivery project, with this checkout's chant", () => {
   });
 
   test("builds, lints, rebuilds its CI, stops at the ship gate, ships each approved plan to Fly and records it once, and rolls back to the previous release", { timeout: 1_800_000 }, async () => {
-    await upgrade();
     const delivery = join(proj, "delivery");
-    symlinkSync(join(repoRoot, "node_modules"), join(delivery, "node_modules"));
     writeFileSync(join(proj, ".git/info/exclude"), "node_modules\n");
+    symlinkSync(join(repoRoot, "node_modules"), join(delivery, "node_modules"));
+    // The template's ci.yml was built by the chant of 84c8b21 (actions/checkout@v4). The upgrade rebuilds it with
+    // this chant (#3244), so its ci:check passes without anyone running ci:build: build and lint stay stubbed,
+    // and the workflow rebuild runs this checkout's chant.
+    expect(read(proj, ".github/workflows/ci.yml")).toContain("actions/checkout@v4");
+    const rebuilding: ChantRunner = async (command, cwd, args) => {
+      if (!args?.length) return passing(command, cwd);
+      const r = await chant(cwd, {}, command, ...args);
+      return { exitCode: r.status ?? 1, output: r.out };
+    };
+    const staged = await upgrade(rebuilding);
+    expect(staged.workflows).toEqual([expect.objectContaining({ member: "delivery", script: "ci:build", path: ".github/workflows/ci.yml", status: "rebuilt" })]);
+    expect(read(proj, ".github/workflows/ci.yml")).not.toContain("actions/checkout@v4");
     const fly = await flaps(join(root, "fly"));
     const env = { FLY_FLAPS_BASE_URL: fly.endpoint, FLY_API_TOKEN: "test", CHUD_FLY_APP_SECRET: "s3cret", GITHUB_ACTOR: "releaser" };
     /** The Machine's app over HTTP, on the host port its service is published on. */

package/src/workspace/checks/boxes.test.ts

@@ -160,6 +160,9 @@ describe("the box block in the declaration", () => {
       services: [],
       factory: null,
       listing: null,
+      publisher: null,
+      ship: null,
+      replicate: null,
       capabilities: [
         { name: "fountain", broker: "lobby", scope: ["agent", "vault"], pointer: "/members/0/box/capabilities/0" },
         { name: "inference", broker: null, scope: [], pointer: "/members/0/box/capabilities/1" },

package/src/workspace/checks.ts

@@ -45,7 +45,7 @@ import type { PostSynthDiagnostic } from "../lint/post-synth";
 import { readDeclaration, resolveGroups, WorkspaceReadError, type Declaration, type Entry, type ErrorLocation, type ResolvedGroup } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
-import { loadKindRegistry, probeKind, resolveKind, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { loadKindRegistry, probeKind, resolveKind, resolveMemberFields, type KindLoadProblem, type KindRegistry } from "./kinds";
 import { coreClassRegistry, loadClassRegistry, unknownScopeClasses, type ClassRegistry } from "./principal-classes";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { LINK_CHECKS, linkTable } from "./checks/links";
@@ -239,13 +239,20 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   {
     id: "WSP005",
     name: "kind-probe-failed",
-    description: "Every member's directory is what its kind reads, such as a chant config for a chant member.",
+    description: "Every member's directory is what its kind reads, such as a chant config for a chant member, and its fields are ones its kind declares, of the declared types (#3151).",
     severity: "error",
     configurable: true,
     check(ctx) {
-      return readableMembers(ctx)
+      const probes = readableMembers(ctx)
         .filter((m) => !probeKind(ctx.kinds.get(m.kind)!, ctx.tree, memberDir(m.dir)))
         .map((m) => entryFinding(this, m, "kind", `member ${m.name} (${m.dir}) is not ${ctx.kinds.get(m.kind)!.description}`));
+      // A member's fields (#3151): checked whether or not its directory exists, since they are the entry's own.
+      const fields = ctx.declaration.members.flatMap((m) =>
+        resolveMemberFields(ctx.kinds.get(m.kind), m.fields).problems.map((p) =>
+          entryFinding(this, m, p.path === "" ? "fields" : `fields/${p.path.split("/").map(pointerToken).join("/")}`, `member ${m.name}: ${p.message}`),
+        ),
+      );
+      return [...probes, ...fields];
     },
   },
   {

package/src/workspace/component-environments.test.ts

@@ -0,0 +1,105 @@
+/**
+ * #3153, ws-095: a component declares where each release goes, by
+ * environment (the runtime that hosts it, its URL, a custom domain and the
+ * git remote its lifecycle records go to), replacing studio's
+ * `studio.sites` key in delivery's chant.config.ts. The contract validates
+ * it, `chant graph --components` carries it, and `graph --composites` lists
+ * each environment with its site.
+ */
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { computeComponentGraph } from "../components/cli-support";
+import componentSchema from "../components/component.schema.json";
+import { componentEnvironments, memberEnvironments, type EnvironmentReason } from "./environments";
+import type { MemberRuntimes } from "./runtimes";
+
+const runtimes = (environments: MemberRuntimes["environments"], lexicons: string[] = []): MemberRuntimes => ({ lexicons, default: "local", reasons: [], environments });
+
+const SITES = [
+  { name: "prod", runtime: "local" },
+  { name: "fly", runtime: "fly", lifecycle: "origin", url: "https://shop.fly.dev", domain: "shop.example.com" },
+];
+
+describe("a component's environments in the contract (#3153)", () => {
+  const validate = new Ajv2020({ strict: false }).compile(componentSchema);
+  const base = { name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] };
+
+  test("are optional, each a name with an optional runtime, url, domain and lifecycle", () => {
+    expect(validate(base)).toBe(true);
+    expect(validate({ ...base, environments: SITES })).toBe(true);
+  });
+
+  test("refuse an empty list, an entry with no name, a url that isn't http and a field nobody reads", () => {
+    expect(validate({ ...base, environments: [] })).toBe(false);
+    expect(validate({ ...base, environments: [{ runtime: "fly" }] })).toBe(false);
+    expect(validate({ ...base, environments: [{ name: "fly", url: "shop.fly.dev" }] })).toBe(false);
+    expect(validate({ ...base, environments: [{ name: "fly", region: "ams" }] })).toBe(false);
+  });
+});
+
+describe("chant graph --components carries them (#3153)", () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-3153-${Date.now()}-${Math.random()}`);
+    await mkdir(dir, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("for a component that declares them, and not for one that doesn't", async () => {
+    await writeFile(
+      join(dir, "app.component.ts"),
+      `export const app = { name: "app", dependsOn: [], environments: ${JSON.stringify(SITES)}, deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] };\n` +
+        `export const db = { name: "db", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] };\n`,
+    );
+    const graph = await computeComponentGraph(dir);
+    expect(graph.success, graph.error).toBe(true);
+    expect(graph.environments).toEqual({ app: SITES });
+  });
+});
+
+describe("graph --composites lists each environment with the component's site (#3153)", () => {
+  test("an environment the config names takes the site, and the command runs on the site's runtime when the member hosts it", () => {
+    const member = memberEnvironments(runtimes(["prod", "fly"], ["fly"]), { envs: [], reason: null });
+    const envs = componentEnvironments("app", member, "local", SITES, ["fly"]);
+    expect(envs).toEqual([
+      { name: "local", default: true, source: "builtin", site: null, command: "chant run --components app" },
+      { name: "prod", default: false, source: "config", site: { runtime: "local", url: null, domain: null, lifecycle: null }, command: "chant run --components app --env prod" },
+      {
+        name: "fly",
+        default: false,
+        source: "config",
+        site: { runtime: "fly", url: "https://shop.fly.dev", domain: "shop.example.com", lifecycle: "origin" },
+        command: "chant run --components app --on fly --env fly",
+      },
+    ]);
+  });
+
+  test("a site whose runtime the member doesn't host runs on the default runtime", () => {
+    const member = memberEnvironments(runtimes(["fly"]), { envs: [], reason: null });
+    const fly = componentEnvironments("app", member, "local", SITES, []).find((e) => e.name === "fly")!;
+    expect(fly.command).toBe("chant run --components app --env fly");
+    expect(fly.site?.runtime).toBe("fly");
+  });
+
+  test("an environment only the component names is added when the config declares none, and left out with a reason when the config doesn't cover it", () => {
+    const open = memberEnvironments(runtimes([]), { envs: [], reason: null });
+    expect(componentEnvironments("app", open, "local", SITES).map((e) => `${e.name}:${e.source}`)).toEqual(["local:builtin", "prod:component", "fly:component"]);
+
+    const reasons: EnvironmentReason[] = [];
+    const closed = memberEnvironments(runtimes(["prod"]), { envs: [], reason: null });
+    expect(componentEnvironments("app", closed, "local", SITES, [], reasons).map((e) => e.name)).toEqual(["local", "prod"]);
+    expect(reasons).toEqual([{ code: "environments-component-undeclared", message: expect.stringMatching(/component app declares environment fly/) }]);
+  });
+
+  test("a pattern in the config covers a declared name", () => {
+    const member = memberEnvironments(runtimes(["pr-*"]), { envs: [], reason: null });
+    const envs = componentEnvironments("app", member, "local", [{ name: "pr-7", url: "https://pr-7.example.com" }]);
+    expect(envs.find((e) => e.name === "pr-7")).toMatchObject({ source: "component", site: { url: "https://pr-7.example.com" } });
+  });
+});