@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/compose-graph.js

@@ -0,0 +1,235 @@
+/**
+ * The composed workspace IR that `chant workspace graph` prints (#2537, #2524
+ * D8, ws-009, ws-018, ws-022).
+ *
+ * Each member is read through its own `chant graph --format ir`, under its
+ * own toolchain. This module takes those documents and composes them:
+ *
+ * - Every node id becomes `<member>/<id>`. Member names can't hold `/`, and
+ *   `::` keeps its meaning for stacks inside a member (`app/web::Bucket`).
+ *   Edge ends, `$ref` values in attributes, `compositeInstance`,
+ *   `runtimeOwner` and export and import nodes are rewritten the same way.
+ * - `groups.byMember` maps each member to its node ids. `byLexicon` and
+ *   `byComposite` keep their keys (a lexicon or composite type is the same
+ *   thing in every member) and merge the ids. `byStack`, `byContainer` and
+ *   `byWave` name things inside one member, so their keys are prefixed too.
+ * - `links` holds the member links (#2524 D6, #2539): the declared links and
+ *   the joins inferred from members' `imports` and `exports` with the core
+ *   `joinKey()`, labelled `exact` or `folded` (`./links.ts`). A declared link
+ *   suppresses the inferred edge it covers. `records` holds the records
+ *   read through a record kind (`--kind`, #2549), and their `asset` and
+ *   `constrains` links follow the member links in `links`.
+ *
+ * A member's IR with no `version` field comes from a chant older than #2529.
+ * It is version 1, and it is upgraded in place by stamping that version. An IR
+ * newer than {@link GRAPH_IR_VERSION} can't be read safely, so that member is
+ * listed with a reason code and left out, like any other member that can't be
+ * read (#2524 D15).
+ *
+ * `chant graph` itself is untouched: this is the only place members compose.
+ */
+import { graphLinks } from "./links.js";
+import { GRAPH_IR_VERSION } from "../graph-ir.js";
+/** The version of the composed document `chant workspace graph` writes. */
+export const WORKSPACE_GRAPH_VERSION = 1;
+/**
+ * Why a member is missing from the composed graph, or from any per-member
+ * run. Closed, like the `ls` reason codes: a new code is a contract change.
+ */
+export const MEMBER_RUN_REASON_CODES = [
+    /** The member's kind is one the workspace commands don't run, such as `other`. */
+    "kind-not-run",
+    /** The member's directory does not exist. */
+    "dir-missing",
+    /** No installed kind has the member's kind name. */
+    "unknown-kind",
+    /** The directory is not what its kind reads. */
+    "kind-probe-failed",
+    /** The member's command exited with a failure. */
+    "command-failed",
+    /** The member's command printed something that isn't the document asked for. */
+    "output-unreadable",
+    /** The member's IR has a version this chant can't read. */
+    "ir-version-unsupported",
+];
+/** The meta key a lexicon's `graphMeta` hook answers the collector under. */
+export const COLLECTOR_META_KEY = "collector";
+/** Read one member's `chant graph --format ir` output, upgrading an unversioned (v1) IR in place. */
+export function readMemberIr(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { reason: { code: "output-unreadable", message: "chant graph --format ir printed something that is not JSON" } };
+    }
+    if (raw === null || typeof raw !== "object" || !Array.isArray(raw.nodes) || !Array.isArray(raw.edges)) {
+        return { reason: { code: "output-unreadable", message: "chant graph --format ir printed JSON with no nodes and edges" } };
+    }
+    const ir = raw;
+    const printed = ir.version;
+    if (printed === undefined) {
+        ir.version = 1;
+    }
+    else if (typeof printed !== "number" || printed > GRAPH_IR_VERSION) {
+        return {
+            reason: {
+                code: "ir-version-unsupported",
+                message: `the member's chant printed IR version ${String(printed)}, and this chant reads up to version ${GRAPH_IR_VERSION}`,
+            },
+        };
+    }
+    ir.groups ?? (ir.groups = {});
+    return { ir, irVersion: printed === undefined ? null : printed };
+}
+const prefix = (member, id) => `${member}/${id}`;
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+const records = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "object" && x !== null) : [];
+/**
+ * A member's collector topology from its IR meta, or null when the meta holds
+ * none or something that isn't one. Read defensively: the topology comes from
+ * a lexicon the member's own toolchain loaded, which may be newer or older
+ * than this chant.
+ */
+function readCollector(member, value) {
+    if (typeof value !== "object" || value === null || !Array.isArray(value.pipelines))
+        return null;
+    const v = value;
+    return {
+        member,
+        pipelines: records(v.pipelines).map((p) => ({
+            id: String(p.id),
+            signal: String(p.signal),
+            receivers: strings(p.receivers),
+            processors: strings(p.processors),
+            exporters: strings(p.exporters),
+        })),
+        components: records(v.components).map((c) => ({
+            id: String(c.id),
+            kind: String(c.kind),
+            type: String(c.type),
+            endpoints: strings(c.endpoints),
+            protocols: strings(c.protocols),
+            pipelines: strings(c.pipelines),
+        })),
+        exporters: records(v.exporters).map((e) => ({
+            id: String(e.id),
+            type: String(e.type),
+            endpoints: strings(e.endpoints),
+            pipelines: strings(e.pipelines),
+            signals: strings(e.signals),
+        })),
+    };
+}
+function prefixRefs(value, member) {
+    if (Array.isArray(value))
+        return value.map((v) => prefixRefs(v, member));
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = k === "$ref" && typeof v === "string" ? prefix(member, v) : prefixRefs(v, member);
+    }
+    return out;
+}
+function mergeInto(target, key, ids) {
+    (target[key] ?? (target[key] = [])).push(...ids);
+}
+function sorted(rec) {
+    const out = {};
+    for (const k of Object.keys(rec).sort())
+        out[k] = [...rec[k]].sort();
+    return out;
+}
+/**
+ * Compose the members' IRs into the workspace document. Members keep the
+ * order they are given in. With `links`, the `links` section is filled from
+ * the declaration; `kinds` lets a member that isn't composed but whose kind
+ * lists its outputs (`other`, kinds from a package) be a link target.
+ */
+export function composeWorkspaceGraph(workspace, inputs, links) {
+    const nodes = [];
+    const edges = [];
+    const exports = [];
+    const imports = [];
+    const byMember = {};
+    const shared = { byLexicon: {}, byComposite: {} };
+    const scoped = { byStack: {}, byContainer: {}, byWave: {} };
+    const derivedAttrs = {};
+    const collectors = [];
+    for (const { member, ir } of inputs) {
+        if (!ir)
+            continue;
+        const m = member.name;
+        const ids = [];
+        for (const node of ir.nodes) {
+            const composed = { ...node, id: prefix(m, node.id), member: m, attrs: prefixRefs(node.attrs ?? {}, m) };
+            if (node.compositeInstance)
+                composed.compositeInstance = prefix(m, node.compositeInstance);
+            if (node.runtimeOwner)
+                composed.runtimeOwner = prefix(m, node.runtimeOwner);
+            nodes.push(composed);
+            ids.push(composed.id);
+        }
+        byMember[m] = ids.sort();
+        for (const edge of ir.edges)
+            edges.push({ ...edge, from: prefix(m, edge.from), to: prefix(m, edge.to), member: m });
+        for (const key of ["byLexicon", "byComposite"]) {
+            for (const [k, v] of Object.entries(ir.groups[key] ?? {}))
+                mergeInto(shared[key], k, v.map((id) => prefix(m, id)));
+        }
+        for (const key of ["byStack", "byContainer", "byWave"]) {
+            for (const [k, v] of Object.entries(ir.groups[key] ?? {}))
+                mergeInto(scoped[key], prefix(m, k), v.map((id) => prefix(m, id)));
+        }
+        for (const e of ir.exports ?? [])
+            exports.push({ ...e, ...(e.node ? { node: prefix(m, e.node) } : {}), member: m });
+        for (const i of ir.imports ?? [])
+            imports.push({ ...i, node: prefix(m, i.node), member: m });
+        for (const [kind, attrs] of Object.entries(ir.derivedAttrs ?? {}))
+            for (const a of attrs)
+                (derivedAttrs[kind] ?? (derivedAttrs[kind] = new Set())).add(a);
+        if (ir.meta) {
+            // The collector topology has a section of its own; the rest of the meta stays on the member.
+            const { [COLLECTOR_META_KEY]: collector, ...rest } = ir.meta;
+            const read = readCollector(m, collector);
+            if (read)
+                collectors.push(read);
+            if (!read)
+                member.meta = ir.meta;
+            else if (Object.keys(rest).length > 0)
+                member.meta = rest;
+        }
+        if (ir.pipeline)
+            member.pipeline = ir.pipeline;
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    const edgeKey = (e) => `${e.from}\u0000${e.to}\u0000${e.viaAttr ?? ""}`;
+    edges.sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+    const groups = { byMember };
+    for (const key of ["byLexicon", "byComposite"])
+        if (Object.keys(shared[key]).length)
+            groups[key] = sorted(shared[key]);
+    for (const key of ["byStack", "byContainer", "byWave"])
+        if (Object.keys(scoped[key]).length)
+            groups[key] = sorted(scoped[key]);
+    const doc = {
+        version: WORKSPACE_GRAPH_VERSION,
+        workspace,
+        members: inputs.map((i) => i.member),
+        nodes,
+        edges,
+        groups,
+        exports,
+        imports,
+        links: links
+            ? graphLinks(links.declaration, { composed: inputs.filter((i) => i.ir).map((i) => i.member.name), collectors, exports, imports }, links.kinds)
+            : [],
+        collectors,
+        records: [],
+    };
+    if (Object.keys(derivedAttrs).length) {
+        doc.derivedAttrs = Object.fromEntries(Object.keys(derivedAttrs).sort().map((k) => [k, [...derivedAttrs[k]].sort()]));
+    }
+    return doc;
+}

package/dist/workspace/compose-reports.js

@@ -0,0 +1,146 @@
+/**
+ * Merging per-member lint and audit output (#2537, #2524 D16, ws-025, ws-026).
+ *
+ * `chant workspace lint --format sarif` prints one SARIF log with one run per
+ * member, each run being what that member's own `chant lint --format sarif`
+ * printed. `chant workspace audit --format json` prints one document whose
+ * findings each carry a `member` field. Both keep what the member's chant
+ * said and only add where it came from.
+ */
+import { isAbsolute, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+const SARIF_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json";
+/** A root-relative path for a URI a member's SARIF wrote. Other URIs pass through. */
+function rootRelativeUri(uri, memberDir, root) {
+    let abs;
+    if (uri.startsWith("file://")) {
+        try {
+            abs = fileURLToPath(uri);
+        }
+        catch {
+            return uri;
+        }
+    }
+    else if (isAbsolute(uri)) {
+        abs = uri;
+    }
+    if (abs !== undefined) {
+        const rel = relative(root, abs).split("\\").join("/");
+        return rel.startsWith("..") || isAbsolute(rel) ? uri : rel;
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(uri))
+        return uri;
+    return memberDir === "." ? uri : `${memberDir}/${uri}`;
+}
+function rewriteUris(value, memberDir, root) {
+    if (Array.isArray(value))
+        return value.map((v) => rewriteUris(v, memberDir, root));
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = k === "artifactLocation" && v && typeof v === "object" && typeof v.uri === "string"
+            ? { ...v, uri: rootRelativeUri(v.uri, memberDir, root) }
+            : rewriteUris(v, memberDir, root);
+    }
+    return out;
+}
+/** A run for a member whose lint printed no SARIF: no results, and the failure as a notification. */
+function failedRun(unit, why) {
+    const tail = unit.stderr.trim().split("\n").slice(-20).join("\n");
+    return {
+        tool: { driver: { name: "chant", informationUri: "https://intentius.io/chant" } },
+        automationDetails: { id: `${unit.id}/` },
+        properties: { member: unit.member, dir: unit.dir },
+        invocations: [
+            {
+                executionSuccessful: false,
+                exitCode: unit.exitCode,
+                toolExecutionNotifications: [{ level: "error", message: { text: tail ? `${why}\n${tail}` : why } }],
+            },
+        ],
+        results: [],
+    };
+}
+/**
+ * One SARIF log with one run per member. A member's own log normally holds
+ * one run; if it holds more, their results are folded into the first so the
+ * member still has exactly one. Artifact URIs become relative to the
+ * workspace root, and each run's `automationDetails.id` is `<member>/`, the
+ * SARIF way to tell runs of one tool apart.
+ */
+export function mergeSarif(units, root) {
+    const runs = [];
+    for (const unit of units) {
+        let log;
+        try {
+            log = JSON.parse(unit.stdout);
+        }
+        catch {
+            runs.push(failedRun(unit, `chant lint exited ${unit.exitCode} and printed no SARIF`));
+            continue;
+        }
+        const own = Array.isArray(log.runs) ? log.runs : [];
+        if (own.length === 0) {
+            runs.push(failedRun(unit, "chant lint printed a SARIF log with no runs"));
+            continue;
+        }
+        const [first, ...rest] = own.map((r) => rewriteUris(r, unit.dir, root));
+        const results = [...(first.results ?? [])];
+        for (const r of rest) {
+            for (const res of r.results ?? []) {
+                // A rule index points into its own run's rules; folded in, it would point at the wrong one.
+                const { ruleIndex: _dropped, ...kept } = res;
+                results.push(kept);
+            }
+        }
+        runs.push({
+            ...first,
+            results,
+            automationDetails: { ...(first.automationDetails ?? {}), id: `${unit.id}/` },
+            properties: { ...(first.properties ?? {}), member: unit.member, dir: unit.dir },
+        });
+    }
+    return { $schema: SARIF_SCHEMA, version: "2.1.0", runs };
+}
+/**
+ * Merge each member's `chant audit --format json` report. Every finding keeps
+ * its fields, with `file` still relative to its member, and gains `member`.
+ */
+export function mergeAudit(units, workspace) {
+    const members = [];
+    const findings = [];
+    const versions = new Set();
+    for (const unit of units) {
+        let report;
+        try {
+            report = JSON.parse(unit.stdout);
+        }
+        catch {
+            if (unit.exitCode === 0) {
+                // `chant audit` says so in plain text when a directory holds nothing it audits.
+                members.push({ member: unit.id, dir: unit.dir, exitCode: 0, status: "ok", summary: null, error: null, note: unit.stdout.trim() });
+                continue;
+            }
+            const tail = unit.stderr.trim().split("\n").slice(-5).join("\n");
+            members.push({ member: unit.id, dir: unit.dir, exitCode: unit.exitCode, status: "failed", summary: null, error: tail || "chant audit printed no JSON report" });
+            continue;
+        }
+        if (typeof report.schemaVersion === "string")
+            versions.add(report.schemaVersion);
+        const own = report.findings ?? [];
+        const kept = own.filter((f) => !unit.exclude?.some((d) => typeof f.file === "string" && (f.file === d || f.file.startsWith(`${d}/`))));
+        members.push({
+            member: unit.id,
+            dir: unit.dir,
+            exitCode: unit.exitCode,
+            status: report.status === "no-lexicons" ? "no-lexicons" : "ok",
+            summary: report.summary ?? null,
+            error: null,
+            ...(kept.length < own.length ? { leftToMembers: own.length - kept.length } : {}),
+        });
+        for (const f of kept)
+            findings.push({ ...f, member: unit.id });
+    }
+    return { schemaVersion: versions.size === 1 ? [...versions][0] : null, workspace, members, findings };
+}

package/dist/workspace/composites.js

@@ -0,0 +1,264 @@
+/**
+ * `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.
+ *
+ * Each component also lists the runtimes it can deploy on (#2674,
+ * `runtimes.ts`): `local`, and each lexicon its member configures that hosts
+ * `chant run --components`, with the command line for each.
+ *
+ * And each component lists the environments it may deploy to (#2695,
+ * `environments.ts`): `local`, the environments its member's config declares,
+ * and those with a release in the member's ledger on `chant/lifecycle`, with
+ * the command line for each.
+ */
+import { formatError } from "../cli/format.js";
+import { joinLabel } from "../join-key.js";
+import { readMemberIr } from "./compose-graph.js";
+import { workspaceGraph } from "./graph-cli.js";
+import { emitDocument } from "./member-commands.js";
+import { readerVersion, WORKSPACE_ERROR_CODES } from "./declaration.js";
+import { componentEnvironments, ENVIRONMENT_REASON_CODES, memberEnvironments, readLedgerEnvironments } from "./environments.js";
+import { componentRuntimes, readRuntimesIn, RUNTIME_REASON_CODES } from "./runtimes.js";
+/** `$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 declaration's codes, as for
+ * the graph. The composites never read live, so the graph's own
+ * `live-at-revision` (#2875) can't reach them.
+ */
+export const COMPOSITES_ERROR_CODES = WORKSPACE_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",
+];
+/** Why a member's runtimes are only `local`, or leave out a lexicon its config lists (#2674). Closed. */
+export const COMPOSITES_RUNTIME_REASON_CODES = RUNTIME_REASON_CODES;
+/** Why a member's environments are only `local`, or leave out one its ledger has (#2695). Closed. */
+export const COMPOSITES_ENVIRONMENT_REASON_CODES = ENVIRONMENT_REASON_CODES;
+/** Read one member's component graph run into components, or the reason it can't be read. */
+function readComponents(member, dir, run, runtimes, environments) {
+    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 = [];
+    for (const n of read.ir.nodes) {
+        if (n.kind !== "Component")
+            continue;
+        const attrs = n.attrs ?? {};
+        const composites = Array.isArray(attrs.composites) ? attrs.composites.filter((c) => 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,
+            runtimes: componentRuntimes(n.id, runtimes),
+            // The component's own environments (#3153): their sites, and any the member doesn't list; a reason lands on the member.
+            environments: componentEnvironments(n.id, environments, runtimes?.default, declaredEnvironments(attrs.environments), runtimes?.lexicons ?? [], environments?.reasons ?? []),
+        });
+    }
+    return { components };
+}
+/** A component's declared environments from its IR attrs (#3153), keeping only well-formed entries. */
+function declaredEnvironments(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const text = (v) => (typeof v === "string" && v.length > 0 ? v : undefined);
+    return raw
+        .filter((e) => e !== null && typeof e === "object" && typeof e.name === "string")
+        .map((e) => ({ name: e.name, runtime: text(e.runtime), url: text(e.url), domain: text(e.domain), lifecycle: text(e.lifecycle) }));
+}
+/** The composite instances in a composed graph, without their components. */
+export function compositeInstances(graph) {
+    const byId = new Map();
+    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, components, links) {
+    const linked = new Set();
+    for (const r of links) {
+        if ("consumer" in r && "producer" in r && r.status === "resolved")
+            linked.add(`${r.consumer}\u0000${r.producer}`);
+    }
+    const via = (c, i) => c.member === i.member ? "member" : linked.has(`${c.member}\u0000${i.member}`) ? "link" : "unlinked";
+    return instances.map((i) => {
+        const matches = [];
+        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;
+            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, componentReason, runtimes, environments) {
+    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, runtimeReasons: runtimes?.reasons ?? [], environmentReasons: environments?.reasons ?? [] };
+}
+/** Read the workspace's composites and components, and build the document. Never throws a `WorkspaceReadError`. */
+export async function workspaceComposites(query) {
+    const head = { $schema: COMPOSITES_OUTPUT_SCHEMA_ID, contract: COMPOSITES_CONTRACT_VERSION, chant: readerVersion() };
+    let runtimes = new Map();
+    const { loadPlugin, readLedgerEnvironments: readLedger = readLedgerEnvironments, ...graphQuery } = query;
+    const { doc: graph, failed, components: runs } = await workspaceGraph({
+        ...graphQuery,
+        // The composites read source only; a live flag never reaches the members.
+        ...(graphQuery.args ? { args: { ...graphQuery.args, live: false, overlay: false, traffic: undefined } } : {}),
+        components: true,
+        inTree: async (root, members) => {
+            runtimes = await readRuntimesIn(root, members, loadPlugin);
+        },
+    });
+    // With no live read, the graph fails only with a declaration code.
+    if ("error" in graph)
+        return { doc: { ...head, error: { ...graph.error, code: graph.error.code } }, failed: true };
+    const byMember = new Map((runs ?? []).map((r) => [r.unit.member, r]));
+    const members = [];
+    const components = [];
+    let componentsFailed = false;
+    for (const m of graph.members) {
+        const run = m.status === "composed" ? byMember.get(m.name) : undefined;
+        // The ledger is the local chant/lifecycle branch, read from the working tree even with --at, as workspace status reads it.
+        const memberRuntimes = runtimes.get(m.name);
+        const environments = memberRuntimes ? memberEnvironments(memberRuntimes, readLedger(m, query.cwd)) : undefined;
+        let reason = null;
+        if (run) {
+            const read = readComponents(m.name, m.dir, run, memberRuntimes, environments);
+            if ("reason" in read) {
+                reason = read.reason;
+                componentsFailed = true;
+            }
+            else
+                components.push(...read.components);
+        }
+        members.push(memberEntry(m, reason, memberRuntimes, environments));
+    }
+    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 = [];
+    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, cwd) {
+    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;
+}