@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/ls-contract.test.ts

@@ -129,7 +129,7 @@ describe("chant workspace ls on built workspaces", () => {
       ["tools", false, "kind-probe-failed"],
       ["vendor", true, null],
     ]);
-    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, other, workspace/);
+    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, design, other, workspace/);
     expect(doc.members[0].roles).toEqual([{ name: "frontend", path: "src" }]);
     expect(doc.groups[0].reason?.code).toBe("no-matches");
     expect(doc.summary).toEqual({ members: 5, unreadable: 3, groups: 1, matches: 0 });
@@ -269,3 +269,86 @@ describe("chant workspace ls on built workspaces", () => {
     expect(result(listWorkspace({ cwd: root })).members).toEqual([]);
   });
 });
+
+describe("chant workspace ls: generated files and job names (#3050)", () => {
+  const workflow = [
+    "name: ci",
+    "jobs:",
+    "  build:",
+    "    runs-on: ubuntu-latest",
+    "  deploy:",
+    "    name: Deploy to prod",
+    "    runs-on: ubuntu-latest",
+    "",
+  ].join("\n");
+  const gitlab = ["stages: [build]", "variables:", "  A: b", ".hidden:", "  script: [x]", "api-build:", "  stage: build", "  script: [x]", ""].join("\n");
+
+  function build(prefix: string) {
+    const p = (path: string) => (prefix === "" ? path : `${prefix}/${path}`);
+    const record = {
+      schema: 1,
+      files: [
+        { path: ".github/workflows/chant-api-prod.yml", command: "chant build --components --generate github --env prod", env: "prod" },
+        { path: ".gitlab/ci/chant-api-prod.gitlab-ci.yml", command: "chant build --components --generate gitlab --env prod", env: "prod" },
+        { path: p("services/api/dist/out.json"), command: "chant build" },
+      ],
+    };
+    return repo({
+      [p("chant.workspace.json")]: declaration([
+        { name: "api", dir: "services/api", kind: "other", because: "an api", generated: [{ path: "dist/out.json", generator: "chant build --out dist/out.json" }, { path: "NOTES.md", generator: "x", handWritten: { because: "kept by hand" } }] },
+        { name: "docs", dir: "docs", kind: "other", because: "the docs" },
+      ]),
+      [p("services/api/.chant/generated.json")]: JSON.stringify(record),
+      [p(".github/workflows/chant-api-prod.yml")]: workflow,
+      [p(".gitlab/ci/chant-api-prod.gitlab-ci.yml")]: gitlab,
+      [p("docs/README.md")]: "x",
+    });
+  }
+
+  test("lists each member's generated files with the job names in its CI files", () => {
+    const root = build("");
+    const doc = result(listWorkspace({ cwd: root }));
+    expectValid(doc);
+    const api = doc.members.find((m) => m.name === "api")!;
+    expect(api.generated).toEqual([
+      { path: ".github/workflows/chant-api-prod.yml", command: "chant build --components --generate github --env prod", env: "prod", jobs: ["build", "Deploy to prod"] },
+      { path: ".gitlab/ci/chant-api-prod.gitlab-ci.yml", command: "chant build --components --generate gitlab --env prod", env: "prod", jobs: ["api-build"] },
+      { path: "services/api/dist/out.json", command: "chant build --out dist/out.json", env: null, jobs: null },
+    ]);
+    expect(doc.members.find((m) => m.name === "docs")!.generated).toEqual([]);
+  });
+
+  test("names paths from the repository root for a workspace below it", () => {
+    const root = build("infra");
+    const doc = result(listWorkspace({ cwd: join(root, "infra") }));
+    expectValid(doc);
+    const api = doc.members.find((m) => m.name === "api")!;
+    expect(api.generated.map((g) => g.path)).toEqual([
+      ".github/workflows/chant-api-prod.yml",
+      ".gitlab/ci/chant-api-prod.gitlab-ci.yml",
+      "infra/services/api/dist/out.json",
+    ].sort());
+    expect(api.generated.find((g) => g.path.endsWith("chant-api-prod.yml"))!.jobs).toBeNull();
+  });
+
+  test("reads the job names at a revision", () => {
+    const root = build("");
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "x");
+    const rev = git(root, "rev-parse", "HEAD");
+    const doc = result(listWorkspace({ cwd: root, at: rev }));
+    expectValid(doc);
+    expect(doc.members.find((m) => m.name === "api")!.generated[0].jobs).toEqual(["build", "Deploy to prod"]);
+  });
+
+  test("lists a CI file with null jobs when it can't be parsed, and nothing when there is no record", () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "api", dir: "api", kind: "other", because: "x" }]),
+      "api/.chant/generated.json": JSON.stringify({ schema: 1, files: [{ path: ".github/workflows/x.yml", command: "c" }] }),
+      ".github/workflows/x.yml": "jobs: [unclosed",
+    });
+    const doc = result(listWorkspace({ cwd: root }));
+    expectValid(doc);
+    expect(doc.members[0].generated).toEqual([{ path: ".github/workflows/x.yml", command: "c", env: null, jobs: null }]);
+  });
+});

package/src/workspace/ls-generated.ts

@@ -0,0 +1,111 @@
+/**
+ * The generated files a member owns, and the CI job names inside them, for
+ * `chant workspace ls --json` (#3050; read by INTENTIUS/github-warden#62).
+ *
+ * Two sources feed the list. The member's declared `generated` entries (#2541)
+ * are relative to the member's directory. The interim record
+ * `.chant/generated.json` that `chant build --components --generate` and
+ * `chant run --generate` write (#2542) holds repository-relative paths, which is
+ * how a forge CI file outside the member's directory is named. A path in both
+ * lists once, with the declared entry's command.
+ *
+ * The job names are what a forge shows as the check name, so a reader can
+ * require them: for GitHub, Forgejo and Gitea the job's `name`, else its id;
+ * for GitLab the job's key. chant parses the file and runs nothing.
+ */
+
+import yaml from "js-yaml";
+import type { Member } from "./declaration";
+import { isForgePath } from "./checks/pipelines";
+import { GENERATED_RECORD_FILE } from "./member-pipeline";
+import { joinPath, type WorkspaceTree } from "./tree";
+
+/** A generated file of a member, as `ls --json` lists it. */
+export interface LsGenerated {
+  /** From the repository root, with / separators, as a forge reads CI files. */
+  path: string;
+  /** The command that regenerates it, run in the member's directory. */
+  command: string;
+  /** The environment a component pipeline deploys, or null. */
+  env: string | null;
+  /** The check names of a forge CI file, or null for any other file and for one that can't be read or parsed. */
+  jobs: string[] | null;
+}
+
+/** Top-level GitLab keys that are not jobs. */
+const GITLAB_KEYWORDS = new Set(["stages", "variables", "default", "include", "workflow", "image", "services", "cache", "before_script", "after_script", "pages"]);
+
+/** The check names in a forge CI file, or null when the file is no workflow or can't be parsed. */
+export function jobNames(path: string, text: string): string[] | null {
+  let doc: unknown;
+  try {
+    doc = yaml.load(text);
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  const top = doc as Record<string, unknown>;
+  if (path.startsWith(".gitlab/ci/") || path === ".gitlab-ci.yml") {
+    return Object.entries(top)
+      .filter(([k, v]) => !k.startsWith(".") && !GITLAB_KEYWORDS.has(k) && v && typeof v === "object" && !Array.isArray(v))
+      .map(([k]) => k);
+  }
+  const jobs = top["jobs"];
+  if (!jobs || typeof jobs !== "object" || Array.isArray(jobs)) return null;
+  return Object.entries(jobs as Record<string, unknown>).map(([id, job]) => {
+    const name = job && typeof job === "object" ? (job as Record<string, unknown>)["name"] : undefined;
+    return typeof name === "string" && name !== "" ? name : id;
+  });
+}
+
+interface RecordFile {
+  path?: unknown;
+  command?: unknown;
+  env?: unknown;
+}
+
+/**
+ * The member's generated files. `prefix` is the workspace root relative to the
+ * repository root, `"."` when they are the same. Never throws for a record that
+ * is missing or malformed: that member lists what the declaration gives.
+ */
+export function memberGenerated(member: Member, tree: WorkspaceTree, prefix: string): LsGenerated[] {
+  const repoPath = (workspacePath: string) => joinPath(prefix, workspacePath);
+  const byPath = new Map<string, LsGenerated>();
+
+  const recordFile = joinPath(member.dir, GENERATED_RECORD_FILE);
+  if (tree.stat(recordFile) === "file") {
+    try {
+      const parsed = JSON.parse(tree.read(recordFile)) as { files?: RecordFile[] };
+      for (const f of Array.isArray(parsed.files) ? parsed.files : []) {
+        if (typeof f.path !== "string") continue;
+        byPath.set(f.path, {
+          path: f.path,
+          command: typeof f.command === "string" ? f.command : "",
+          env: typeof f.env === "string" ? f.env : null,
+          jobs: null,
+        });
+      }
+    } catch {
+      // an unreadable record lists nothing from itself
+    }
+  }
+  for (const g of member.generated) {
+    if (g.handWritten) continue;
+    const path = repoPath(joinPath(member.dir, g.path));
+    byPath.set(path, { path, command: g.generator, env: byPath.get(path)?.env ?? null, jobs: null });
+  }
+
+  const own = prefix === "." ? "" : `${prefix}/`;
+  for (const entry of byPath.values()) {
+    if (!isForgePath(entry.path) || !entry.path.startsWith(own)) continue;
+    const inTree = entry.path.slice(own.length);
+    if (tree.stat(inTree) !== "file") continue;
+    try {
+      entry.jobs = jobNames(entry.path, tree.read(inTree));
+    } catch {
+      entry.jobs = null;
+    }
+  }
+  return [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/src/workspace/ls.schema.json

@@ -104,6 +104,11 @@
           "type": "array",
           "items": { "$ref": "#/$defs/recordKind" }
         },
+        "generated": {
+          "description": "Added in contract 1 by #3050. The files the member generates, from its declared generated entries and from the record `chant build --components --generate` and `chant run --generate` write, sorted by path. A hand-written entry is not listed.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/generatedFile" }
+        },
         "reason": {
           "oneOf": [
             { "type": "null" },
@@ -165,6 +170,20 @@
         }
       }
     },
+    "generatedFile": {
+      "type": "object",
+      "required": ["path", "command", "env", "jobs"],
+      "properties": {
+        "path": { "type": "string", "description": "From the repository root, with / separators, which is how a forge reads a CI file. For a workspace below the git root, that includes the workspace root." },
+        "command": { "type": "string", "description": "The command that regenerates the file, run in the member's directory. Empty when a record names none." },
+        "env": { "type": ["string", "null"], "description": "The environment a component pipeline deploys, or null." },
+        "jobs": {
+          "description": "The check names a forge CI file declares: for GitHub, Forgejo and Gitea the job's name, else its id; for GitLab the job's key. Null for any other file, and for a CI file that is missing from the tree read or can't be parsed.",
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        }
+      }
+    },
     "diagram": {
       "description": "A diagram artifact the declaration names (#2764), pinned to the renderer its render was made with. chant runs no renderer; everything here comes straight from the declaration.",
       "type": "object",

package/src/workspace/ls.ts

@@ -21,7 +21,7 @@
  */
 
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import {
@@ -37,6 +37,7 @@ import {
   type WorkspaceErrorCode,
 } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import { memberGenerated, type LsGenerated } from "./ls-generated";
 import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { handToRootChant, locateWorkspace } from "./which-chant";
@@ -89,6 +90,8 @@ export interface LsRecordKind {
   acceptance: LsAcceptance[] | null;
 }
 
+export type { LsGenerated } from "./ls-generated";
+
 /** A work item's acceptance criteria, counted (#2772). */
 export interface LsAcceptance {
   item: string;
@@ -108,6 +111,8 @@ export interface LsMember {
   reason: { code: MemberReasonCode; message: string } | null;
   /** The record kinds the member declares, in file order (#2680). */
   records: LsRecordKind[];
+  /** The files the member generates, and the job names inside its forge CI files (#3050). */
+  generated: LsGenerated[];
 }
 
 /**
@@ -231,6 +236,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
     // for --at: they are read as data, never run (#2535).
     const kinds = query.kinds ?? loadKindRegistry(declaration.pins, rootOnDisk).registry;
     const groups = resolveGroups(declaration, tree);
+    const repoPrefix = isAbsolute(located.root) ? "." : located.root;
     const members: LsMember[] = declaration.members.map((m) => {
       const reason = memberReason(m, tree, kinds);
       return {
@@ -243,6 +249,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
         readable: reason === null,
         reason,
         records: unloaded(m.records),
+        generated: memberGenerated(m, tree, repoPrefix),
       };
     });
     const lsGroups: LsGroup[] = groups.map((g) => ({

package/src/workspace/member-commands.ts

@@ -222,7 +222,9 @@ export function planMembers(verb: WorkspaceVerb, root: string, options: PlanOpti
       const why =
         entry.kind === "workspace"
           ? "a nested workspace runs its own chant workspace commands"
-          : `chant workspace ${verb} runs members of kind chant, and this one is kind ${entry.kind}`;
+          : entry.kind === "design"
+            ? "a design member is data: chant reads its files for record pins and builds nothing"
+            : `chant workspace ${verb} runs members of kind chant, and this one is kind ${entry.kind}`;
       skipped.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason: { code: "kind-not-run", message: why } });
       continue;
     }

package/src/workspace/nested-graph.test.ts

@@ -0,0 +1,176 @@
+/**
+ * chant #2551 — read-only nested workspaces: the nested read's document is
+ * checked against the read contract, folded into the outer graph with
+ * `outer/inner/id` ids, and the outer upgrade never writes inside a nested
+ * workspace. The real read against the reference workspace is in
+ * read-contract.test.ts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { composeWorkspaceGraph, type ComposedMember, type WorkspaceGraph } from "./compose-graph";
+import { emptyLock, fileEntries, writeLock } from "./lineage-lock";
+import { stageUpgrade } from "./lineage-upgrade";
+import { foldNested, nestedArgv, readNestedDocument } from "./nested-graph";
+import { nestedWorkspaces, pathsInsideNested } from "./nesting";
+
+const SCHEMA = "https://intentius.io/chant/schemas/workspace/graph/v1/graph.schema.json";
+
+function member(name: string, over: Partial<ComposedMember> = {}): ComposedMember {
+  return { name, dir: name, kind: "chant", status: "composed", reason: null, chant: "1.0.0", irVersion: 1, live: false, ...over };
+}
+
+function innerGraph(): WorkspaceGraph & { contract: number } {
+  return {
+    contract: 1,
+    version: 1,
+    workspace: { name: "inner", root: "." },
+    members: [member("api", { dir: "services/api" }), member("docs", { kind: "other", status: "skipped", reason: { code: "kind-not-run", message: "other" } })],
+    nodes: [
+      { id: "api/Queue", kind: "Queue", lexicon: "aws", attrs: { dlq: { $ref: "api/Dlq" } }, member: "api", sourceLoc: { file: "src/q.ts", line: 3 } },
+      { id: "api/Dlq", kind: "Queue", lexicon: "aws", attrs: {}, member: "api", compositeInstance: "api/Pair" },
+    ],
+    edges: [{ from: "api/Queue", to: "api/Dlq", member: "api" } as WorkspaceGraph["edges"][number]],
+    groups: { byMember: { api: ["api/Dlq", "api/Queue"], docs: [] }, byLexicon: { aws: ["api/Dlq", "api/Queue"] }, byStack: { "api/main": ["api/Queue"] } },
+    exports: [{ name: "queueArn", node: "api/Queue", attr: "Arn", member: "api" } as WorkspaceGraph["exports"][number]],
+    imports: [],
+    links: [],
+    collectors: [],
+    records: [],
+  };
+}
+
+describe("readNestedDocument", () => {
+  test("accepts a graph document of the contract this chant reads", () => {
+    const r = readNestedDocument(JSON.stringify({ $schema: SCHEMA, chant: "1.2.3", ...innerGraph() }), 0, "", SCHEMA, 1);
+    expect(r).toMatchObject({ ok: true, chant: "1.2.3" });
+  });
+
+  test("refuses no JSON, another document, a newer contract and an error document, each with a reason code", () => {
+    expect(readNestedDocument("boom", 1, "line\nlast line", SCHEMA, 1)).toMatchObject({ ok: false, code: "command-failed", message: expect.stringContaining("last line") });
+    expect(readNestedDocument("{}", 0, "", SCHEMA, 1)).toMatchObject({ ok: false, code: "output-unreadable" });
+    expect(readNestedDocument(JSON.stringify({ $schema: SCHEMA, contract: 2, chant: "9.0.0" }), 0, "", SCHEMA, 1)).toMatchObject({
+      ok: false,
+      code: "ir-version-unsupported",
+      chant: "9.0.0",
+    });
+    expect(readNestedDocument(JSON.stringify({ $schema: SCHEMA, contract: 1, error: { code: "declaration-missing", message: "none" } }), 1, "", SCHEMA, 1)).toMatchObject({
+      ok: false,
+      code: "command-failed",
+      message: expect.stringContaining("declaration-missing"),
+    });
+  });
+
+  test("passes the read flags on, and never a write", () => {
+    expect(nestedArgv("/w/inner", { env: "dev", live: true, overlay: true, traffic: "10 rps", noCache: true, output: "x.json" }, "abc")).toEqual([
+      "workspace", "graph", "/w/inner", "--at", "abc", "--env", "dev", "--live", "--overlay", "--traffic", "10 rps", "--no-cache",
+    ]);
+  });
+});
+
+describe("foldNested", () => {
+  test("prefixes every id with the outer member, keeps the nested member on each node, and fills the member entry", () => {
+    const outer = composeWorkspaceGraph({ name: "outer", root: "." }, [
+      { member: member("platform", { kind: "workspace", status: "skipped", reason: { code: "kind-not-run", message: "nested" }, chant: null, irVersion: null }) },
+    ]);
+    const entry = outer.members[0];
+    foldNested(outer, entry, innerGraph());
+    expect(outer.nodes.map((n) => [n.id, n.member, n.nested])).toEqual([
+      ["platform/api/Dlq", "platform", "api"],
+      ["platform/api/Queue", "platform", "api"],
+    ]);
+    const queue = outer.nodes.find((n) => n.id === "platform/api/Queue")!;
+    expect(queue.attrs).toEqual({ dlq: { $ref: "platform/api/Dlq" } });
+    // sourceLoc is relative to the outer member's directory, the nested root.
+    expect(queue.sourceLoc).toEqual({ file: "services/api/src/q.ts", line: 3 });
+    expect(outer.nodes.find((n) => n.id === "platform/api/Dlq")!.compositeInstance).toBe("platform/api/Pair");
+    expect(outer.edges).toEqual([{ from: "platform/api/Queue", to: "platform/api/Dlq", member: "platform" }]);
+    expect(outer.exports).toEqual([{ name: "queueArn", node: "platform/api/Queue", attr: "Arn", member: "platform" }]);
+    expect(outer.groups.byMember.platform).toEqual(["platform/api/Dlq", "platform/api/Queue"]);
+    expect(outer.groups.byLexicon).toEqual({ aws: ["platform/api/Dlq", "platform/api/Queue"] });
+    expect(outer.groups.byStack).toEqual({ "platform/api/main": ["platform/api/Queue"] });
+    expect(entry).toMatchObject({ status: "composed", reason: null, nested: { name: "inner", contract: 1, links: [] } });
+    expect(entry.nested!.members.map((m) => m.name)).toEqual(["api", "docs"]);
+  });
+});
+
+describe("the outer workspace never writes inside a nested one", () => {
+  let root: string;
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  const ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" };
+  const git = (cwd: string, args: string[]) => execFileSync("git", args, { cwd, env: ENV, stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
+  const put = (base: string, rel: string, text: string) => {
+    mkdirSync(dirname(join(base, rel)), { recursive: true });
+    writeFileSync(join(base, rel), text);
+  };
+
+  test("finds nested members, and the paths inside them", () => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-nesting-")));
+    put(root, "chant.workspace.json", JSON.stringify({ name: "outer", schema: 1, members: [{ name: "kit", dir: "vendor/kit", kind: "workspace" }, { name: "docs", dir: "docs", kind: "other", because: "prose" }] }));
+    put(root, "vendor/kit/chant.workspace.json", JSON.stringify({ name: "kit", schema: 1, members: [] }));
+    mkdirSync(join(root, "docs"));
+    expect(nestedWorkspaces(root)).toEqual([{ name: "kit", dir: "vendor/kit" }]);
+    expect(pathsInsideNested(root, "", ["docs/a.md", "vendor/kit/x.ts", "vendor/kitten.ts"])).toEqual([{ member: "kit", path: "vendor/kit/x.ts" }]);
+    expect(pathsInsideNested(root, "infra", ["infra/vendor/kit/x.ts", "vendor/kit/x.ts"])).toEqual([{ member: "kit", path: "infra/vendor/kit/x.ts" }]);
+    expect(nestedWorkspaces(join(root, "docs"))).toEqual([]);
+  });
+
+  test("an upgrade whose patch reaches into a nested workspace is refused", async () => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-nesting-")));
+    const tpl = join(root, "tpl");
+    const ws = join(root, "ws");
+    mkdirSync(tpl);
+    git(tpl, ["init", "-q", "-b", "main"]);
+    put(tpl, "README.md", "one\n");
+    put(tpl, "kit/settings.json", "{}\n");
+    git(tpl, ["add", "-A"]);
+    git(tpl, ["commit", "-q", "-m", "v1"]);
+    git(tpl, ["tag", "v1.0.0"]);
+    put(tpl, "kit/settings.json", '{ "v": 2 }\n');
+    git(tpl, ["commit", "-q", "-am", "v2"]);
+    git(tpl, ["tag", "v2.0.0"]);
+
+    mkdirSync(ws);
+    git(ws, ["init", "-q", "-b", "main"]);
+    put(ws, "README.md", "one\n");
+    put(ws, "kit/settings.json", "{}\n");
+    put(ws, "kit/chant.workspace.json", JSON.stringify({ name: "kit", schema: 1, members: [] }));
+    put(ws, "chant.workspace.json", JSON.stringify({ name: "outer", schema: 1, members: [{ name: "kit", dir: "kit", kind: "workspace" }] }));
+    const lock = emptyLock();
+    const files = new Map([
+      ["README.md", Buffer.from("one\n")],
+      ["kit/settings.json", Buffer.from("{}\n")],
+    ]);
+    lock.scopes["."] = {
+      kind: "template",
+      template: tpl,
+      source: { type: "git", repo: tpl, url: "../tpl" },
+      ref: "v1.0.0",
+      address: { digest: `sha256:${"0".repeat(64)}`, commit: git(tpl, ["rev-parse", "v1.0.0"]) },
+      parameters: {},
+      migrations: [],
+      files: fileEntries(files),
+      manualSteps: [],
+    };
+    writeLock(ws, lock);
+    git(ws, ["add", "-A"]);
+    git(ws, ["commit", "-q", "-m", "made"]);
+    await expect(stageUpgrade({ root: ws, to: "v2.0.0", runChant: async () => ({ exitCode: 0, output: "" }) })).rejects.toThrow(
+      /inside the nested workspace kit \(kit\/settings\.json\).*never writes inside it/,
+    );
+    // The refusal leaves no staging worktree behind.
+    expect(git(ws, ["worktree", "list"]).split("\n")).toHaveLength(1);
+
+    // Naming the nested member from the outer root is refused too: it upgrades itself.
+    writeLock(join(ws, "kit"), lock);
+    git(ws, ["add", "-A"]);
+    git(ws, ["commit", "-q", "-m", "the nested workspace's own lock"]);
+    await expect(stageUpgrade({ root: ws, scope: "kit", to: "v2.0.0", runChant: async () => ({ exitCode: 0, output: "" }) })).rejects.toThrow(
+      /member "kit" is a nested workspace, which upgrades itself: run chant workspace upgrade in kit/,
+    );
+  });
+});

package/src/workspace/nested-graph.ts

@@ -0,0 +1,169 @@
+/**
+ * Read-only expansion of nested workspaces in `chant workspace graph`
+ * (#2551, #2524 D2, ws-007, ws-071).
+ *
+ * A member of kind `workspace` holds its own `chant.workspace.json`. The outer
+ * workspace never runs commands inside it and never writes there. It reads
+ * it the way it reads any member: through the nested workspace's own
+ * command, `chant workspace graph`, started in the nested root. That command
+ * hands itself to the nested workspace's own chant when it has one (ws-021),
+ * so the nested side is read under its own toolchain, and the answer is a
+ * document of the read contract the outer chant validates before using it.
+ *
+ * The nested document is folded into the outer one with every id prefixed by
+ * the outer member's name, so a node `delivery/web::Bucket` of the nested
+ * workspace becomes `reference-workspace/delivery/web::Bucket`: `outer/inner/id`.
+ * Each node keeps the nested member it came from in `nested`, and the outer
+ * member entry carries the nested workspace's own member list and links.
+ *
+ * Nothing here writes: the nested read is a read (its per-member cache lives
+ * in the user's cache directory, ws-059), and the outer side keeps nothing.
+ */
+
+import { spawn } from "node:child_process";
+import type { ParsedArgs } from "../cli/registry";
+import type { ComposedMember, ComposedNode, WorkspaceGraph } from "./compose-graph";
+
+export type { NestedWorkspace } from "./compose-graph";
+import { readerToolchain, type Toolchain } from "./member-commands";
+
+/** What reading one nested workspace gave. */
+export type NestedRead =
+  | { ok: true; chant: string | null; doc: WorkspaceGraph & { contract: number; chant?: string } }
+  | { ok: false; chant: string | null; code: "command-failed" | "output-unreadable" | "ir-version-unsupported"; message: string };
+
+/** The command line of the nested read: the outer command's own read flags, passed on. */
+export function nestedArgv(dir: string, args: Partial<ParsedArgs>, at: string | null | undefined): string[] {
+  return [
+    "workspace",
+    "graph",
+    dir,
+    ...(at ? ["--at", at] : []),
+    ...(args.env ? ["--env", args.env] : []),
+    ...(args.live ? ["--live"] : []),
+    ...(args.overlay ? ["--overlay"] : []),
+    ...(args.traffic !== undefined ? ["--traffic", String(args.traffic)] : []),
+    ...(args.noCache ? ["--no-cache"] : []),
+  ];
+}
+
+function spawnRead(command: string[], argv: string[], cwd: string): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const [bin, ...pre] = command;
+  return new Promise((done) => {
+    const child = spawn(bin, [...pre, ...argv], { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (b: Buffer) => out.push(b));
+    child.stderr.on("data", (b: Buffer) => err.push(b));
+    child.on("error", (e) => done({ exitCode: 127, stdout: "", stderr: `could not start ${bin}: ${e.message}\n` }));
+    child.on("close", (code) => done({ exitCode: code ?? 1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));
+  });
+}
+
+/** Check a nested read's output against the read contract this chant knows. */
+export function readNestedDocument(stdout: string, exitCode: number, stderr: string, schemaId: string, contract: number): NestedRead {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(stdout);
+  } catch {
+    const tail = stderr.trim().split("\n").slice(-5).join("\n");
+    return { ok: false, chant: null, code: exitCode === 0 ? "output-unreadable" : "command-failed", message: `the nested chant workspace graph exited ${exitCode} and printed no document${tail ? `: ${tail}` : ""}` };
+  }
+  const doc = raw as Record<string, unknown>;
+  const chant = typeof doc.chant === "string" ? doc.chant : null;
+  if (doc.$schema !== schemaId || typeof doc.contract !== "number") {
+    return { ok: false, chant, code: "output-unreadable", message: "the nested chant workspace graph printed something that is not a workspace graph document" };
+  }
+  if (doc.contract > contract) {
+    return { ok: false, chant, code: "ir-version-unsupported", message: `the nested workspace's chant printed graph contract ${doc.contract}, and this chant reads up to ${contract}` };
+  }
+  if (doc.error && typeof doc.error === "object") {
+    const e = doc.error as { code?: unknown; message?: unknown };
+    return { ok: false, chant, code: "command-failed", message: `the nested workspace could not be read: ${String(e.code)}: ${String(e.message)}` };
+  }
+  if (!Array.isArray(doc.nodes) || !Array.isArray(doc.edges) || !Array.isArray(doc.members)) {
+    return { ok: false, chant, code: "output-unreadable", message: "the nested workspace graph has no nodes, edges and members" };
+  }
+  return { ok: true, chant, doc: doc as unknown as WorkspaceGraph & { contract: number } };
+}
+
+/** Run the nested workspace's own `chant workspace graph` in `abs`. */
+export async function readNested(
+  abs: string,
+  args: Partial<ParsedArgs>,
+  at: string | null | undefined,
+  schemaId: string,
+  contract: number,
+  toolchain: Toolchain | undefined = undefined,
+): Promise<NestedRead & { stderr: string }> {
+  const r = await spawnRead((toolchain ?? readerToolchain()).command, nestedArgv(abs, args, at), abs);
+  return { ...readNestedDocument(r.stdout, r.exitCode, r.stderr, schemaId, contract), stderr: r.stderr };
+}
+
+const prefixed = (outer: string, id: string): string => `${outer}/${id}`;
+
+function prefixRefs(value: unknown, outer: string): unknown {
+  if (Array.isArray(value)) return value.map((v) => prefixRefs(v, outer));
+  if (value === null || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) out[k] = k === "$ref" && typeof v === "string" ? prefixed(outer, v) : prefixRefs(v, outer);
+  return out;
+}
+
+/**
+ * Fold a nested workspace's graph into the outer one, under the outer member
+ * `outer`, and fill that member's entry. The outer graph's other sections are
+ * left as they are, so links still resolve against the outer declaration.
+ */
+export function foldNested(graph: WorkspaceGraph, member: ComposedMember, inner: WorkspaceGraph & { contract: number }): void {
+  const outer = member.name;
+  const dirs = new Map(inner.members.map((m) => [m.name, m.dir]));
+  const ids: string[] = [];
+  for (const node of inner.nodes) {
+    const n: ComposedNode = {
+      ...node,
+      id: prefixed(outer, node.id),
+      member: outer,
+      nested: node.member,
+      attrs: prefixRefs(node.attrs ?? {}, outer) as Record<string, unknown>,
+    };
+    if (node.compositeInstance) n.compositeInstance = prefixed(outer, node.compositeInstance);
+    if (node.runtimeOwner) n.runtimeOwner = prefixed(outer, node.runtimeOwner);
+    if (node.compositeParent) n.compositeParent = node.compositeParent;
+    // sourceLoc is relative to the member's directory: the outer member's is the nested root.
+    const dir = dirs.get(node.member);
+    if (node.sourceLoc && dir && dir !== ".") n.sourceLoc = { ...node.sourceLoc, file: `${dir}/${node.sourceLoc.file}` };
+    graph.nodes.push(n);
+    ids.push(n.id);
+  }
+  for (const e of inner.edges) graph.edges.push({ ...e, from: prefixed(outer, e.from), to: prefixed(outer, e.to), member: outer });
+  for (const e of inner.exports ?? []) graph.exports.push({ ...e, ...(e.node ? { node: prefixed(outer, e.node) } : {}), member: outer });
+  for (const i of inner.imports ?? []) graph.imports.push({ ...i, node: prefixed(outer, i.node), member: outer });
+  graph.groups.byMember[outer] = ids.sort();
+  const groups = graph.groups as unknown as Record<string, Record<string, string[]> | undefined>;
+  const innerGroups = inner.groups as unknown as Record<string, Record<string, string[]> | undefined>;
+  for (const key of ["byLexicon", "byComposite"] as const) {
+    for (const [k, v] of Object.entries(innerGroups[key] ?? {})) {
+      const into = (groups[key] ??= {});
+      into[k] = [...(into[k] ?? []), ...v.map((id) => prefixed(outer, id))].sort();
+    }
+  }
+  for (const key of ["byStack", "byContainer", "byWave"] as const) {
+    for (const [k, v] of Object.entries(innerGroups[key] ?? {})) {
+      const into = (groups[key] ??= {});
+      into[prefixed(outer, k)] = v.map((id) => prefixed(outer, id)).sort();
+    }
+  }
+  for (const c of inner.collectors ?? []) graph.collectors.push({ ...c, member: prefixed(outer, c.member) });
+  for (const [kind, attrs] of Object.entries(inner.derivedAttrs ?? {})) {
+    const all = new Set([...(graph.derivedAttrs?.[kind] ?? []), ...attrs]);
+    graph.derivedAttrs = { ...(graph.derivedAttrs ?? {}), [kind]: [...all].sort() };
+  }
+  graph.nodes.sort((a, b) => a.id.localeCompare(b.id));
+  const edgeKey = (e: (typeof graph.edges)[number]) => `${e.from}\u0000${e.to}\u0000${e.viaAttr ?? ""}`;
+  graph.edges.sort((a, b) => edgeKey(a).localeCompare(edgeKey(b)));
+
+  member.status = "composed";
+  member.reason = null;
+  member.nested = { name: inner.workspace.name, contract: inner.contract, members: inner.members, links: inner.links ?? [] };
+}