@intentius/chant 0.83.0 → 0.85.0

package/src/workspace/composites.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The read contract for `chant workspace graph --composites` (#2662): the
+ * schema is a valid draft 2020-12 document whose closed code lists match the
+ * code, and real output validates against it, for a built workspace whose
+ * members answer through a fake chant, for failures, for `--at`, and for each
+ * reason the list can be empty. The reference workspace runs a real chant
+ * (`read-contract.test.ts`).
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import type { GraphIR, IRNode } from "../graph-ir";
+import { cleanScratch, commitAll, contract, declaration, FAKE_FILE_GRAPH_CHANT, repo, validSchema } from "./__fixtures__/contract-repo";
+import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
+import {
+  COMPOSITES_CONTRACT_VERSION,
+  COMPOSITES_ERROR_CODES,
+  COMPOSITES_OUTPUT_SCHEMA_ID,
+  COMPOSITES_REASON_CODES,
+  compositeInstances,
+  joinComponents,
+  workspaceComposites,
+  type ComponentEntry,
+  type CompositesDocument,
+} from "./composites";
+import { GRAPH_ERROR_CODES } from "./graph-cli";
+import schema from "./composites.schema.json";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+type Result = Exclude<CompositesDocument, { error: unknown }>;
+
+function result(doc: CompositesDocument): Result {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const composite = (id: string, kind: string, instance: string, lexicon = "aws"): IRNode => ({ id, kind: "Resource", lexicon, attrs: {}, compositeParent: kind, compositeInstance: instance });
+
+const ir = (nodes: IRNode[], extra: Partial<GraphIR> = {}): string => `${JSON.stringify({ version: 1, nodes, edges: [], groups: {}, ...extra })}\n`;
+
+const componentIr = (components: { name: string; composites?: string[]; archetype?: string }[]): string =>
+  ir(
+    components.map((c) => ({
+      id: c.name,
+      kind: "Component",
+      lexicon: "chant",
+      attrs: { wave: 1, liveNames: [c.name], ...(c.composites ? { composites: c.composites } : {}), ...(c.archetype ? { archetype: c.archetype } : {}) },
+      sourceLoc: { file: `src/${c.name}.component.ts` },
+    })),
+    { groups: { byWave: { "wave-1": components.map((c) => c.name) } } },
+  );
+
+/**
+ * app declares three instances and exports ImageUri; delivery links to it and
+ * declares two components; jobs declares an instance and a component of its
+ * own; docs is kind other.
+ */
+function fixture(): string {
+  return repo({
+    "chant.workspace.json": declaration([
+      { name: "app", dir: "app", kind: "chant" },
+      { name: "delivery", dir: "delivery", kind: "chant", links: [{ member: "app", output: "ImageUri" }] },
+      { name: "jobs", dir: "jobs", kind: "chant" },
+      { name: "docs", dir: "docs", kind: "other", because: "prose" },
+    ]),
+    "app/chant.config.ts": "export default {};\n",
+    "app/ir.json": ir(
+      [
+        composite("backendRepo", "LoomBackend", "backend"),
+        composite("backendService", "LoomBackend", "backend"),
+        composite("siteBucket", "StaticSite", "site"),
+        composite("cacheCluster", "CacheCluster", "cache"),
+        { id: "Loose", kind: "Queue", lexicon: "aws", attrs: {} },
+      ],
+      { exports: [{ name: "ImageUri", node: "backendRepo", attr: "Uri" }] },
+    ),
+    "delivery/chant.config.ts": "export default {};\n",
+    "delivery/ir.json": ir([]),
+    "delivery/components.json": componentIr([
+      { name: "loom-backend", archetype: "service" },
+      { name: "edge", composites: ["StaticSite"], archetype: "infra" },
+    ]),
+    "jobs/chant.config.ts": "export default {};\n",
+    "jobs/ir.json": ir([composite("queueTopic", "WorkQueue", "queue")]),
+    "jobs/components.json": componentIr([{ name: "queue-runner", composites: ["WorkQueue", "CacheCluster"] }]),
+    "docs/README.md": "",
+    ".gitignore": "node_modules\n",
+    "node_modules/.bin/chant": { text: FAKE_FILE_GRAPH_CHANT, mode: 0o755 },
+  });
+}
+
+describe("composites output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(COMPOSITES_OUTPUT_SCHEMA_ID);
+    expect(COMPOSITES_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the reason and error codes the code can return", () => {
+    expect(schema.$defs.reason.properties.code.enum).toEqual([...COMPOSITES_REASON_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...COMPOSITES_ERROR_CODES]);
+    expect(COMPOSITES_ERROR_CODES).toEqual(GRAPH_ERROR_CODES);
+    expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_RUN_REASON_CODES]);
+  });
+});
+
+describe("the join", () => {
+  const instances = compositeInstances({
+    nodes: [
+      { ...composite("a/xBucket", "LoomBackend", "a/x"), member: "a" },
+      { ...composite("a/xRole", "OperatorRole", "a/x", "gcp"), member: "a" },
+      { ...composite("a/billingTable", "Table", "a/billing"), member: "a" },
+    ],
+  });
+  const component = (member: string, name: string, composites: string[] | null = null): ComponentEntry => ({ id: `${member}/${name}`, name, member, archetype: null, composites, file: null });
+
+  test("an instance carries every kind and lexicon of its nodes", () => {
+    expect(instances.map((i) => [i.id, i.instance, i.kinds, i.lexicons])).toEqual([
+      ["a/billing", "billing", ["Table"], ["aws"]],
+      ["a/x", "x", ["LoomBackend", "OperatorRole"], ["aws", "gcp"]],
+    ]);
+  });
+
+  test("declared composites match exactly, and stop name matching for that component", () => {
+    const rows = joinComponents(instances, [component("a", "loom-backend", ["Table"]), component("a", "other", ["LoomBackend"])], []);
+    expect(rows.find((r) => r.id === "a/x")!.components).toEqual([{ component: "a/other", by: "composites", against: "kind", value: "LoomBackend", label: "exact", via: "member" }]);
+    expect(rows.find((r) => r.id === "a/billing")!.components.map((m) => m.component)).toEqual(["a/loom-backend"]);
+  });
+
+  test("a component with no composites matches a kind by joinKey, then the instance's name", () => {
+    const rows = joinComponents(instances, [component("a", "loom-backend"), component("a", "Billing"), component("a", "nothing")], []);
+    expect(rows.find((r) => r.id === "a/x")!.components).toEqual([{ component: "a/loom-backend", by: "name", against: "kind", value: "LoomBackend", label: "folded", via: "member" }]);
+    expect(rows.find((r) => r.id === "a/billing")!.components).toEqual([{ component: "a/Billing", by: "name", against: "instance", value: "billing", label: "folded", via: "member" }]);
+  });
+
+  test("across members, a resolved link from the component's member makes it via link", () => {
+    const link = (status: "resolved" | "missing") => ({ consumer: "b", producer: "a", output: "O", kind: "output", origin: "declared" as const, label: "exact" as const, input: null, resolves: "source" as const, status, reason: null });
+    const c = [component("b", "table-deployer", ["Table"])];
+    expect(joinComponents(instances, c, [link("resolved")]).find((r) => r.id === "a/billing")!.components[0].via).toBe("link");
+    expect(joinComponents(instances, c, [link("missing")]).find((r) => r.id === "a/billing")!.components[0].via).toBe("unlinked");
+    expect(joinComponents(instances, c, []).find((r) => r.id === "a/x")!.components).toEqual([]);
+  });
+});
+
+describe("chant workspace graph --composites on a built workspace", () => {
+  test("lists each instance with the components that can deploy it, and an empty set for the gap", async () => {
+    const { doc, failed } = await workspaceComposites({ cwd: fixture() });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(false);
+    expect(g.members.map((m) => [m.name, m.status, m.reason?.code ?? null])).toEqual([
+      ["app", "read", null],
+      ["delivery", "read", null],
+      ["jobs", "read", null],
+      ["docs", "skipped", "kind-not-run"],
+    ]);
+    expect(g.components).toEqual([
+      { id: "delivery/edge", name: "edge", member: "delivery", archetype: "infra", composites: ["StaticSite"], file: "delivery/src/edge.component.ts" },
+      { id: "delivery/loom-backend", name: "loom-backend", member: "delivery", archetype: "service", composites: null, file: "delivery/src/loom-backend.component.ts" },
+      { id: "jobs/queue-runner", name: "queue-runner", member: "jobs", archetype: null, composites: ["WorkQueue", "CacheCluster"], file: "jobs/src/queue-runner.component.ts" },
+    ]);
+    const rows = Object.fromEntries(g.composites.map((c) => [c.id, c]));
+    expect(Object.keys(rows)).toEqual(["app/backend", "app/cache", "app/site", "jobs/queue"]);
+    expect(rows["app/backend"]).toMatchObject({ member: "app", instance: "backend", kinds: ["LoomBackend"], lexicons: ["aws"], nodes: ["app/backendRepo", "app/backendService"] });
+    expect(rows["app/backend"].components).toEqual([{ component: "delivery/loom-backend", by: "name", against: "kind", value: "LoomBackend", label: "folded", via: "link" }]);
+    expect(rows["app/site"].components).toEqual([{ component: "delivery/edge", by: "composites", against: "kind", value: "StaticSite", label: "exact", via: "link" }]);
+    // jobs does not link to app: the match is data, marked as crossing no link.
+    expect(rows["app/cache"].components).toEqual([{ component: "jobs/queue-runner", by: "composites", against: "kind", value: "CacheCluster", label: "exact", via: "unlinked" }]);
+    expect(rows["jobs/queue"].components.map((m) => [m.component, m.via])).toEqual([["jobs/queue-runner", "member"]]);
+    expect(g.reasons).toEqual([]);
+    expect(g.summary).toEqual({ composites: 4, withComponent: 4, withoutComponent: 0, components: 3 });
+  });
+
+  test("an instance no component names is listed with an empty set", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "components.json"), componentIr([]));
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    expect(g.composites.find((c) => c.id === "app/cache")!.components).toEqual([]);
+    expect(g.composites.find((c) => c.id === "jobs/queue")!.components).toEqual([]);
+    expect(g.summary).toMatchObject({ withComponent: 2, withoutComponent: 2 });
+  });
+
+  test("--at <rev> reads each member as it was at the revision", async () => {
+    const root = fixture();
+    const first = commitAll(root, "one");
+    writeFileSync(join(root, "delivery", "components.json"), componentIr([]));
+    const now = result((await workspaceComposites({ cwd: root })).doc);
+    expect(now.components.map((c) => c.id)).toEqual(["jobs/queue-runner"]);
+    const at = result((await workspaceComposites({ cwd: root, at: first })).doc);
+    expectValid(at);
+    expect(at.at).toBe(first);
+    expect(at.components.map((c) => c.id)).toEqual(["delivery/edge", "delivery/loom-backend", "jobs/queue-runner"]);
+  });
+
+  test("a member whose component graph fails is listed as failed, and the rest still join", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "components.json"), "FAIL\n");
+    const { doc, failed } = await workspaceComposites({ cwd: root });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(true);
+    expect(g.members.find((m) => m.name === "jobs")).toMatchObject({ status: "failed", reason: { code: "command-failed" } });
+    expect(g.members.find((m) => m.name === "jobs")!.reason!.message).toContain("chant graph --components exited 1");
+    expect(g.composites.find((c) => c.id === "jobs/queue")!.components).toEqual([]);
+    expect(g.components.map((c) => c.id)).toEqual(["delivery/edge", "delivery/loom-backend"]);
+  });
+});
+
+describe("why the list is empty", () => {
+  test("a workspace with no chant member says so", async () => {
+    const root = repo({ "chant.workspace.json": declaration([{ name: "docs", dir: "docs", kind: "other", because: "prose" }]), "docs/README.md": "" });
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    expect(g.composites).toEqual([]);
+    expect(g.reasons.map((r) => r.code)).toEqual(["composites-no-chant-member"]);
+  });
+
+  test("members with no composite and no component say both", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "api", dir: "api", kind: "chant" }]),
+      "api/chant.config.ts": "",
+      "api/ir.json": ir([{ id: "Queue", kind: "Queue", lexicon: "aws", attrs: {} }]),
+      ".gitignore": "node_modules\n",
+      "node_modules/.bin/chant": { text: FAKE_FILE_GRAPH_CHANT, mode: 0o755 },
+    });
+    const g = result((await workspaceComposites({ cwd: root })).doc);
+    expectValid(g);
+    expect(g.reasons.map((r) => r.code)).toEqual(["composites-none-declared", "composites-no-component"]);
+    expect(g.summary).toEqual({ composites: 0, withComponent: 0, withoutComponent: 0, components: 0 });
+  });
+
+  test("a declaration that can't be read is a failure document with a closed code", async () => {
+    const { doc, failed } = await workspaceComposites({ cwd: repo({}) });
+    expectValid(doc);
+    expect(failed).toBe(true);
+    expect("error" in doc && doc.error.code).toBe("declaration-missing");
+  });
+});

package/src/workspace/composites.ts

@@ -0,0 +1,295 @@
+/**
+ * `chant workspace graph --composites` (#2662): each composite instance the
+ * workspace's members declare, joined to the components that can deploy it.
+ *
+ * The composed graph already knows which composite instances each member
+ * declares (a node's `compositeInstance` and `compositeParent`), and a
+ * member's `chant graph --components --format ir` knows its components and
+ * the composite kinds each names in its contract's `composites`. This module
+ * joins the two and prints the rows. chant supplies the data and never the
+ * choice (ws-052): the document says how each component matched, and a
+ * reader decides what to offer.
+ *
+ * A component matches an instance in one of two ways:
+ *
+ * - `composites`: the component's contract lists one of the instance's
+ *   composite kinds, compared exactly.
+ * - `name`: the component declares no `composites`, and its `name` joins the
+ *   instance's kind or the instance's own name with the core `joinKey()`
+ *   (`LoomBackend` and `loom-backend` join, labelled `folded`). This is the
+ *   naming convention the component contract documents for a component that
+ *   says nothing (#1492).
+ *
+ * Every match says how it crosses members (`via`): `member` when the
+ * component and the instance are in the same member, `link` when the
+ * component's member reads the instance's member through a resolved member
+ * link (#2539), and `unlinked` otherwise. An instance with no component is
+ * listed with an empty `components`, so the gap is visible.
+ *
+ * Each member runs under its own toolchain, as for `workspace graph`, and at
+ * the same revision with `--at`. Nothing is written and no listener starts.
+ */
+
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { joinLabel, type JoinLabel } from "../join-key";
+import type { ComposedMember, MemberReason, WorkspaceGraph } from "./compose-graph";
+import { readMemberIr } from "./compose-graph";
+import { GRAPH_ERROR_CODES, workspaceGraph, type GraphQuery } from "./graph-cli";
+import type { LinkRow } from "./links";
+import { emitDocument, type UnitResult } from "./member-commands";
+import { readerVersion, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const COMPOSITES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/composites/v1/composites.schema.json";
+
+/** The read-contract version the document follows. */
+export const COMPOSITES_CONTRACT_VERSION = 1;
+
+/** Why the composites couldn't be read at all: the graph's codes. */
+export const COMPOSITES_ERROR_CODES = GRAPH_ERROR_CODES;
+
+/** Why the list is empty, or why no instance has a component. Closed: part of the read contract. */
+export const COMPOSITES_REASON_CODES = [
+  /** No member of kind chant was read, so nothing declares a composite or a component. */
+  "composites-no-chant-member",
+  /** The members read declare no composite instance. */
+  "composites-none-declared",
+  /** The members read declare no component, so no instance has one. */
+  "composites-no-component",
+] as const satisfies readonly ReasonCode[];
+export type CompositesReasonCode = (typeof COMPOSITES_REASON_CODES)[number];
+
+export interface CompositesMember {
+  name: string;
+  dir: string;
+  kind: string;
+  /** `read` when both its graph and its component graph were read. */
+  status: "read" | "skipped" | "failed";
+  reason: MemberReason | null;
+  chant: string | null;
+}
+
+export interface ComponentEntry {
+  /** `<member>/<name>`. */
+  id: string;
+  name: string;
+  member: string;
+  /** Declared or inferred; null when the member's chant does not print it. */
+  archetype: string | null;
+  /** The contract's `composites`, or null when it declares none. */
+  composites: string[] | null;
+  /** The component's file from the workspace root, when the member's chant names it. */
+  file: string | null;
+}
+
+export interface ComponentMatch {
+  /** The {@link ComponentEntry} id. */
+  component: string;
+  by: "composites" | "name";
+  /** What was matched: one of the instance's kinds, or the instance's own name. */
+  against: "kind" | "instance";
+  value: string;
+  label: JoinLabel;
+  via: "member" | "link" | "unlinked";
+}
+
+export interface CompositeInstanceRow {
+  /** `<member>/<instance>`, the composed graph's `compositeInstance`. */
+  id: string;
+  member: string;
+  /** The instance's name in its member: the export name. */
+  instance: string;
+  /** The composite kinds its nodes came from; more than one when composites nest. */
+  kinds: string[];
+  lexicons: string[];
+  /** The composed ids of its nodes. */
+  nodes: string[];
+  components: ComponentMatch[];
+}
+
+interface Head {
+  $schema: string;
+  contract: number;
+  chant: string;
+}
+
+export type CompositesDocument =
+  | (Head & {
+      at: string | null;
+      workspace: { name: string; root: string };
+      members: CompositesMember[];
+      composites: CompositeInstanceRow[];
+      components: ComponentEntry[];
+      reasons: { code: CompositesReasonCode; message: string }[];
+      summary: { composites: number; withComponent: number; withoutComponent: number; components: number };
+    })
+  | (Head & { error: { code: WorkspaceErrorCode; message: string; location: ErrorLocation | null } });
+
+export interface CompositesResult {
+  doc: CompositesDocument;
+  failed: boolean;
+}
+
+/** Read one member's component graph run into components, or the reason it can't be read. */
+function readComponents(member: string, dir: string, run: UnitResult): { components: ComponentEntry[] } | { reason: MemberReason } {
+  if (run.exitCode !== 0) {
+    const tail = run.stderr.trim().split("\n").slice(-5).join("\n");
+    return { reason: { code: "command-failed", message: `chant graph --components exited ${run.exitCode}${tail ? `: ${tail}` : ""}` } };
+  }
+  const read = readMemberIr(run.stdout);
+  if ("reason" in read) return { reason: { ...read.reason, message: `chant graph --components: ${read.reason.message}` } };
+  const components: ComponentEntry[] = [];
+  for (const n of read.ir.nodes) {
+    if (n.kind !== "Component") continue;
+    const attrs = n.attrs ?? {};
+    const composites = Array.isArray(attrs.composites) ? (attrs.composites as unknown[]).filter((c): c is string => typeof c === "string") : null;
+    const file = n.sourceLoc?.file;
+    components.push({
+      id: `${member}/${n.id}`,
+      name: n.id,
+      member,
+      archetype: typeof attrs.archetype === "string" ? attrs.archetype : null,
+      composites: composites && composites.length > 0 ? composites : null,
+      file: file ? (dir === "." ? file : `${dir}/${file}`) : null,
+    });
+  }
+  return { components };
+}
+
+/** The composite instances in a composed graph, without their components. */
+export function compositeInstances(graph: Pick<WorkspaceGraph, "nodes">): CompositeInstanceRow[] {
+  const byId = new Map<string, { member: string; kinds: Set<string>; lexicons: Set<string>; nodes: string[] }>();
+  for (const n of graph.nodes) {
+    if (!n.compositeInstance) continue;
+    const row = byId.get(n.compositeInstance) ?? { member: n.member, kinds: new Set(), lexicons: new Set(), nodes: [] };
+    if (n.compositeParent) row.kinds.add(n.compositeParent);
+    row.lexicons.add(n.lexicon);
+    row.nodes.push(n.id);
+    byId.set(n.compositeInstance, row);
+  }
+  return [...byId.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([id, r]) => ({
+      id,
+      member: r.member,
+      instance: id.slice(r.member.length + 1),
+      kinds: [...r.kinds].sort(),
+      lexicons: [...r.lexicons].sort(),
+      nodes: r.nodes.sort(),
+      components: [],
+    }));
+}
+
+/**
+ * Join instances to components. `links` are the composed graph's member link
+ * rows: a component crosses to another member's instance `via: "link"` when
+ * its member is the consumer of a resolved link whose producer is the
+ * instance's member.
+ */
+export function joinComponents(instances: CompositeInstanceRow[], components: ComponentEntry[], links: WorkspaceGraph["links"]): CompositeInstanceRow[] {
+  const linked = new Set<string>();
+  for (const r of links) {
+    if ("consumer" in r && "producer" in r && (r as LinkRow).status === "resolved") linked.add(`${r.consumer}\u0000${(r as LinkRow).producer}`);
+  }
+  const via = (c: ComponentEntry, i: CompositeInstanceRow): ComponentMatch["via"] =>
+    c.member === i.member ? "member" : linked.has(`${c.member}\u0000${i.member}`) ? "link" : "unlinked";
+
+  return instances.map((i) => {
+    const matches: ComponentMatch[] = [];
+    for (const c of components) {
+      if (c.composites) {
+        const kind = i.kinds.find((k) => c.composites!.includes(k));
+        if (kind) matches.push({ component: c.id, by: "composites", against: "kind", value: kind, label: "exact", via: via(c, i) });
+        continue;
+      }
+      let match: Omit<ComponentMatch, "component" | "via"> | undefined;
+      for (const k of i.kinds) {
+        const label = joinLabel(c.name, k);
+        if (label && (!match || (label === "exact" && match.label !== "exact"))) match = { by: "name", against: "kind", value: k, label };
+      }
+      if (!match) {
+        const label = joinLabel(c.name, i.instance);
+        if (label) match = { by: "name", against: "instance", value: i.instance, label };
+      }
+      if (match) matches.push({ component: c.id, ...match, via: via(c, i) });
+    }
+    matches.sort((a, b) => a.component.localeCompare(b.component));
+    return { ...i, components: matches };
+  });
+}
+
+function memberEntry(m: ComposedMember, componentReason: MemberReason | null): CompositesMember {
+  const reason = m.reason ?? componentReason;
+  const status = m.status === "composed" ? (componentReason ? "failed" : "read") : m.status;
+  return { name: m.name, dir: m.dir, kind: m.kind, status, reason, chant: m.chant };
+}
+
+/** Read the workspace's composites and components, and build the document. Never throws a `WorkspaceReadError`. */
+export async function workspaceComposites(query: Omit<GraphQuery, "kind" | "components">): Promise<CompositesResult> {
+  const head: Head = { $schema: COMPOSITES_OUTPUT_SCHEMA_ID, contract: COMPOSITES_CONTRACT_VERSION, chant: readerVersion() };
+  const { doc: graph, failed, components: runs } = await workspaceGraph({ ...query, components: true });
+  if ("error" in graph) return { doc: { ...head, error: graph.error }, failed: true };
+
+  const byMember = new Map((runs ?? []).map((r) => [r.unit.member, r]));
+  const members: CompositesMember[] = [];
+  const components: ComponentEntry[] = [];
+  let componentsFailed = false;
+  for (const m of graph.members) {
+    const run = m.status === "composed" ? byMember.get(m.name) : undefined;
+    let reason: MemberReason | null = null;
+    if (run) {
+      const read = readComponents(m.name, m.dir, run);
+      if ("reason" in read) {
+        reason = read.reason;
+        componentsFailed = true;
+      } else components.push(...read.components);
+    }
+    members.push(memberEntry(m, reason));
+  }
+  components.sort((a, b) => a.id.localeCompare(b.id));
+
+  const composites = joinComponents(compositeInstances(graph), components, graph.links);
+  const read = members.filter((m) => m.status === "read");
+  const reasons: { code: CompositesReasonCode; message: string }[] = [];
+  if (!members.some((m) => m.kind === "chant" && m.status !== "skipped")) {
+    reasons.push({ code: "composites-no-chant-member", message: "no member of kind chant was read, so nothing declares a composite or a component" });
+  } else if (read.length > 0) {
+    const names = read.map((m) => m.name).join(", ");
+    if (composites.length === 0) reasons.push({ code: "composites-none-declared", message: `the members read (${names}) declare no composite instance` });
+    if (components.length === 0) reasons.push({ code: "composites-no-component", message: `the members read (${names}) declare no component in a *.component.ts file` });
+  }
+  const withComponent = composites.filter((c) => c.components.length > 0).length;
+  return {
+    doc: {
+      ...head,
+      at: graph.at,
+      workspace: graph.workspace,
+      members,
+      composites,
+      components,
+      reasons,
+      summary: { composites: composites.length, withComponent, withoutComponent: composites.length - withComponent, components: components.length },
+    },
+    failed: failed || componentsFailed,
+  };
+}
+
+/** `chant workspace graph --composites`: print the document as JSON, always, like the composed graph. */
+export async function runWorkspaceComposites(ctx: CommandContext, cwd: string): Promise<number> {
+  const { args } = ctx;
+  const { doc, failed } = await workspaceComposites({
+    cwd,
+    at: args.at,
+    members: args.members,
+    args,
+    onStderr: (text) => process.stderr.write(text),
+  });
+  emitDocument(doc, args.output);
+  if ("error" in doc) {
+    const l = doc.error.location;
+    console.error(formatError({ message: `${doc.error.code}: ${l ? `${l.file}:${l.line}:${l.column}: ` : ""}${doc.error.message}` }));
+  }
+  return failed ? 1 : 0;
+}

package/src/workspace/graph-cli.ts

@@ -5,6 +5,11 @@
  * document (`compose-graph.ts`). With `--kind`, the records of that kind and
  * their asset and constrains links join it (#2549, `record-assets.ts`).
  *
+ * With `--intent <path[:start-end]>` it prints the intent graph over one
+ * region instead (#2651, `intent.ts`), a document of its own in the read
+ * contract. With `--composites` it prints each composite instance with the
+ * components that can deploy it (#2662, `composites.ts`), another.
+ *
  * The document is part of the read contract, described by `graph.schema.json`
  * beside this file. It is printed for a failure too, with the error's reason
  * code, so a reader always has JSON to parse.
@@ -43,7 +48,8 @@ export const GRAPH_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/worksp
 /** Why the graph couldn't be read at all: the declaration's codes, `--at`'s included. */
 export const GRAPH_ERROR_CODES = WORKSPACE_ERROR_CODES;
 
-const USAGE = "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run]";
+const USAGE =
+  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
 
 interface Head {
   $schema: string;
@@ -73,12 +79,25 @@ export interface GraphQuery {
    * rows of `links`.
    */
   kind?: string;
+  /**
+   * Also run each member's `chant graph --components --format ir` (#2662),
+   * under the same toolchain and at the same revision, and return the answers
+   * in {@link GraphResult.components}. The document is unchanged.
+   */
+  components?: boolean;
 }
 
 export interface GraphResult {
   doc: GraphDocument;
   /** A member failed or couldn't be read, or the declaration couldn't be read. */
   failed: boolean;
+  /** With {@link GraphQuery.components}: each member's component graph run, in plan order. */
+  components?: UnitResult[];
+}
+
+/** The command line a member runs for its component graph (#2662). */
+export function componentGraphArgv(args: Partial<ParsedArgs>): string[] {
+  return ["graph", ".", "--components", "--format", "ir", ...(args.env ? ["--env", args.env] : [])];
 }
 
 /**
@@ -174,7 +193,12 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
       exported = exportRevision(located, plan.groups.flatMap((g) => g.units.map((u) => u.dir)));
       plan = planMembers("graph", exported, { only: query.members, reader: query.reader, tree: workingTree(exported) });
     }
-    const results = await executePlan(plan, (query.args ?? {}) as ParsedArgs);
+    const args = (query.args ?? {}) as ParsedArgs;
+    const [results, components] = await Promise.all([
+      executePlan(plan, args),
+      query.components ? executePlan(plan, args, () => componentGraphArgv(args)) : Promise.resolve(undefined),
+    ]);
+    for (const r of components ?? []) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     for (const r of results) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     const { inputs, failed } = compose(plan, results, query.members, declaration.members);
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
@@ -196,7 +220,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
         query.onStderr?.(`${formatError({ message: `--kind ${query.kind}: ${err.code}: ${err.message}`, hint: USAGE })}\n`);
       }
     }
-    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed };
+    return { doc: { ...head, at: located.at, ...graph }, failed: failed || recordsFailed, ...(components ? { components } : {}) };
   } catch (err) {
     if (!(err instanceof WorkspaceReadError)) throw err;
     return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };
@@ -216,6 +240,18 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
   const handed = await handToRootChant(cwd, args.at);
   if (handed !== undefined) return handed;
 
+  // Composite instances joined to components (#2662) are their own document.
+  if (args.composites) {
+    if (args.intent !== undefined || args.kind !== undefined) {
+      console.error(formatError({ message: "--composites takes neither --intent nor --kind", hint: USAGE }));
+      return 1;
+    }
+    if (!args.dryRun) return (await import("./composites")).runWorkspaceComposites(ctx, cwd);
+  }
+
+  // The intent graph over one region (#2651) is its own document.
+  if (args.intent !== undefined) return (await import("./intent-cli")).runWorkspaceIntent(ctx, cwd);
+
   if (args.dryRun) {
     let plan: MemberPlan;
     try {