@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/declaration.ts

@@ -128,6 +128,23 @@ export interface LinkDeclaration {
   pointer: string;
 }
 
+/**
+ * A record kind the declaration names (#2680): the workspace's own, in the
+ * top-level `records`, or a member's, in that member's `records`.
+ */
+export interface RecordKindDeclaration {
+  /** The kind file as the entry writes it: relative to the member's directory, or to the workspace root for the workspace's own. */
+  kind: string;
+  /** The kind file from the workspace root, with / separators. */
+  path: string;
+  /** The name the entry gives the kind, or null when readers use the kind file's own `recordKind.name`. */
+  name: string | null;
+  /** The member that declares it, or null for the workspace's own. */
+  member: string | null;
+  /** The entry's JSON Pointer in the file, for messages. */
+  pointer: string;
+}
+
 export interface Member {
   type: "member";
   name: string;
@@ -141,6 +158,8 @@ export interface Member {
   outputs: string[] | null;
   /** The links this member states as a consumer, in file order (#2539). */
   links: LinkDeclaration[];
+  /** The record kinds this member declares, in file order (#2680). */
+  records: RecordKindDeclaration[];
   upstream: string | null;
   because: string | null;
   suppress: Suppression[];
@@ -179,6 +198,10 @@ export interface Declaration {
   pins: Pin[];
   /** Severities set for declaration checks, keyed by `WSP` id (#2535). */
   checks: Record<string, CheckSeverity>;
+  /** How many verdicts besides the decider's a record needs, or null when the declaration names none (#2671). */
+  quorum: number | null;
+  /** The workspace's own record kinds, from the top-level `records`, in file order (#2680). A member's are on the member. */
+  records: RecordKindDeclaration[];
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -390,6 +413,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       kind: l.kind ?? null,
       pointer: `${pointer}/links/${j}`,
     }));
+    const records = recordKindsOf(e.records, e.dir as string, e.name as string, `${pointer}/records`);
     return {
       type: "member",
       name: e.name as string,
@@ -399,6 +423,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       generated,
       outputs: e.outputs === undefined ? null : [...(e.outputs as string[])],
       links,
+      records,
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
       suppress,
@@ -468,6 +493,21 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     }
   }
 
+  // A kind file is declared once, and a name the declaration gives a kind is
+  // given once (#2680): readers key the kinds by both.
+  const ownRecords = recordKindsOf(obj.records, ".", null, "/records");
+  const byPath = new Map<string, RecordKindDeclaration>();
+  const byName = new Map<string, RecordKindDeclaration>();
+  for (const r of [...ownRecords, ...members.flatMap((m) => m.records)]) {
+    const first = byPath.get(r.path);
+    if (first) throw new WorkspaceReadError("declaration-invalid", `the record kind ${r.path} is already declared at ${first.pointer}`, at(`${r.pointer}/kind`));
+    byPath.set(r.path, r);
+    if (r.name === null) continue;
+    const named = byName.get(r.name);
+    if (named) throw new WorkspaceReadError("declaration-invalid", `the record kind name ${JSON.stringify(r.name)} is already given at ${named.pointer}`, at(`${r.pointer}/name`));
+    byName.set(r.name, r);
+  }
+
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
     version: p.version ?? null,
@@ -484,10 +524,32 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     groups: entries.filter((e): e is Group => e.type === "group"),
     pins,
     checks: { ...((obj.checks as Record<string, CheckSeverity> | undefined) ?? {}) },
+    quorum: typeof obj.quorum === "number" ? obj.quorum : null,
+    records: ownRecords,
     file,
   };
 }
 
+/** The `records` list at `pointer`, already validated, with each kind file's path from the workspace root. */
+function recordKindsOf(raw: unknown, dir: string, member: string | null, pointer: string): RecordKindDeclaration[] {
+  return ((raw as { kind: string; name?: string }[] | undefined) ?? []).map((r, i) => ({
+    kind: r.kind,
+    path: dir === "." ? r.kind : `${dir}/${r.kind}`,
+    name: r.name ?? null,
+    member,
+    pointer: `${pointer}/${i}`,
+  }));
+}
+
+/**
+ * Every record kind the declaration names (#2680), in the order readers use
+ * them: the workspace's own first, then each member's, members in file order
+ * and each list in its own order.
+ */
+export function declaredRecordKinds(declaration: Declaration): RecordKindDeclaration[] {
+  return [...declaration.records, ...declaration.members.flatMap((m) => m.records)];
+}
+
 /** Whether `path` is `dir` or sits under it. Both are tree-relative; `"."` is the root. */
 export function isInside(path: string, dir: string): boolean {
   if (dir === ".") return true;

package/src/workspace/declared-kinds.test.ts

@@ -0,0 +1,321 @@
+/**
+ * chant #2680: the declaration names its record kinds. The declaration reads
+ * them, `ls --json` lists them, `check` fails on one that doesn't load
+ * (WSP115), and `records` and `graph --intent` read every one of them when
+ * `--kind` is not given, while `--kind` still overrides.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { parseArgs } from "../cli/main";
+import { cleanScratch, commitAll, contract, git, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { runDeclarationChecks } from "./checks";
+import { declaredRecordKinds, parseDeclaration, WorkspaceReadError } from "./declaration";
+import { intentGraph } from "./intent";
+import intentSchema from "./intent.schema.json";
+import { listWorkspace, listWorkspaceWithKinds, type LsDocument } from "./ls";
+import lsSchema from "./ls.schema.json";
+import { declaredKindFiles, queryDeclaredRecords, runWorkspaceRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import recordsSinceSchema from "./records-since.schema.json";
+import { runRecordsWrite } from "./records-write";
+
+afterAll(cleanScratch);
+
+const REF = join(import.meta.dirname, "..", "..", "..", "..", "reference-workspace", "decisions");
+const DECISION_KIND = readFileSync(join(REF, "decision.kind.mjs"), "utf-8");
+const DECISION_SCHEMA = readFileSync(join(REF, "decision.schema.json"), "utf-8");
+const REF_001 = readFileSync(join(REF, "ref-001-how-the-app-is-deployed.md"), "utf-8");
+
+/** The decision kind under another name, reading only `note-*.md`, so two kinds never read the same file. */
+const NOTE_KIND = DECISION_KIND.replace('name: "decision"', 'name: "note"').replace(/match: "[^"]*"/, 'match: "^note-[0-9]+\\\\.md$"');
+
+const members = (extra: Record<string, unknown> = {}) => [
+  { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+  { name: "design", dir: "design", kind: "other", because: "the design data member", ...extra },
+];
+
+const decl = (m: unknown[], extra: Record<string, unknown> = {}) => JSON.stringify({ name: "studio", schema: 1, members: m, ...extra }, null, 2);
+
+const BASE_FILES = {
+  "app/server.mjs": "export const port = 8080;\n",
+  "decisions/decision.kind.mjs": DECISION_KIND,
+  "decisions/decision.schema.json": DECISION_SCHEMA,
+  "decisions/ref-001-how-the-app-is-deployed.md": REF_001,
+  "design/notes/note.kind.mjs": NOTE_KIND,
+  "design/notes/decision.schema.json": DECISION_SCHEMA,
+  "design/notes/note-1.md": REF_001,
+};
+
+/** A workspace whose own records hold the decision kind, and whose design member holds the note kind. */
+function workspace(extraFiles: Record<string, string> = {}, designRecords: unknown[] = [{ kind: "notes/note.kind.mjs", name: "notes" }]): string {
+  return repo(
+    {
+      "chant.workspace.json": decl(members({ records: designRecords }), { records: [{ kind: "decisions/decision.kind.mjs" }] }),
+      ...BASE_FILES,
+      ...extraFiles,
+    },
+    true,
+  );
+}
+
+describe("the declaration's records (#2680)", () => {
+  test("the workspace's own and each member's, with paths from the workspace root, in reading order", () => {
+    const d = parseDeclaration(
+      decl(members({ records: [{ kind: "notes/note.kind.mjs", name: "notes" }] }), { records: [{ kind: "decisions/decision.kind.mjs" }] }),
+      "chant.workspace.json",
+    );
+    expect(d.records).toEqual([{ kind: "decisions/decision.kind.mjs", path: "decisions/decision.kind.mjs", name: null, member: null, pointer: "/records/0" }]);
+    expect(d.members.find((m) => m.name === "design")!.records).toEqual([
+      { kind: "notes/note.kind.mjs", path: "design/notes/note.kind.mjs", name: "notes", member: "design", pointer: "/members/1/records/0" },
+    ]);
+    expect(d.members.find((m) => m.name === "app")!.records).toEqual([]);
+    expect(declaredRecordKinds(d).map((k) => k.path)).toEqual(["decisions/decision.kind.mjs", "design/notes/note.kind.mjs"]);
+  });
+
+  test("a path outside the member, a path declared twice, a name given twice and an unknown field are declaration-invalid", () => {
+    const refused = (text: string) => {
+      try {
+        parseDeclaration(text, "chant.workspace.json");
+      } catch (err) {
+        expect(err).toBeInstanceOf(WorkspaceReadError);
+        return `${(err as WorkspaceReadError).code}: ${(err as WorkspaceReadError).message}`;
+      }
+      throw new Error("read");
+    };
+    expect(refused(decl(members({ records: [{ kind: "../decisions/decision.kind.mjs" }] })))).toMatch(/^declaration-invalid: .* is not a path inside the member/);
+    expect(refused(decl([{ name: "root", dir: ".", kind: "other", because: "x", records: [{ kind: "decisions/d.kind.mjs" }] }], { records: [{ kind: "decisions/d.kind.mjs" }] }))).toBe(
+      "declaration-invalid: the record kind decisions/d.kind.mjs is already declared at /records/0",
+    );
+    expect(refused(decl(members({ records: [{ kind: "a.kind.mjs", name: "x" }] }), { records: [{ kind: "b.kind.mjs", name: "x" }] }))).toBe(
+      'declaration-invalid: the record kind name "x" is already given at /records/0',
+    );
+    expect(refused(decl(members(), { records: [{ kind: "a.kind.mjs", file: "b" }] }))).toMatch(/^declaration-invalid: unknown field "file"/);
+  });
+});
+
+describe("workspace ls lists the declared kinds (#2680)", () => {
+  const { expectValid } = contract(lsSchema);
+  const result = (doc: LsDocument) => {
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    return doc;
+  };
+
+  test("with each kind file's name when it loads, and the reason when it doesn't", async () => {
+    const root = workspace({ "design/broken.kind.mjs": "export const nothing = 1;\n" }, [
+      { kind: "notes/note.kind.mjs", name: "notes" },
+      { kind: "gone.kind.mjs" },
+      { kind: "broken.kind.mjs" },
+    ]);
+    const doc = result(await listWorkspaceWithKinds({ cwd: root }));
+    expect(doc.contract).toBe(1);
+    expect(doc.workspace.records).toEqual([{ name: "decision", path: "decisions/decision.kind.mjs", kind: "decision", reason: null }]);
+    const design = doc.members.find((m) => m.name === "design")!;
+    expect(design.readable).toBe(true);
+    expect(design.records).toEqual([
+      { name: "notes", path: "design/notes/note.kind.mjs", kind: "note", reason: null },
+      { name: null, path: "design/gone.kind.mjs", kind: null, reason: { code: "kind-unreadable", message: "kind file design/gone.kind.mjs does not exist" } },
+      { name: null, path: "design/broken.kind.mjs", kind: null, reason: { code: "kind-invalid", message: "kind file design/broken.kind.mjs is not a record kind: it has no recordKind export" } },
+    ]);
+    expect(doc.members.find((m) => m.name === "app")!.records).toEqual([]);
+  });
+
+  test("listWorkspace lists them unloaded, and a workspace that names none lists empty arrays", async () => {
+    const doc = result(listWorkspace({ cwd: workspace() }));
+    expect(doc.workspace.records).toEqual([{ name: null, path: "decisions/decision.kind.mjs", kind: null, reason: null }]);
+    const none = result(await listWorkspaceWithKinds({ cwd: repo({ "chant.workspace.json": decl(members()), "app/x": "", "design/x": "" }) }));
+    expect(none.workspace.records).toEqual([]);
+    expect(none.members.map((m) => m.records)).toEqual([[], []]);
+  });
+
+  test("--at looks for the kind file in the revision", async () => {
+    const root = workspace();
+    const at = git(root, "rev-parse", "HEAD");
+    git(root, "rm", "-q", "design/notes/note.kind.mjs");
+    commitAll(root, "drop the note kind");
+    const now = result(await listWorkspaceWithKinds({ cwd: root }));
+    expect(now.members.find((m) => m.name === "design")!.records[0].reason?.code).toBe("kind-unreadable");
+    // The revision still has the file; it loads from the working tree, where it is gone.
+    const then = result(await listWorkspaceWithKinds({ cwd: root, at }));
+    expect(then.members.find((m) => m.name === "design")!.records[0].reason?.code).toBe("kind-unreadable");
+    expect(then.members.find((m) => m.name === "design")!.records[0].reason?.message).toContain("could not be loaded");
+  });
+});
+
+describe("WSP115: a declared kind that doesn't load (#2680)", () => {
+  test("fails check with the reason, pointing at the entry", async () => {
+    const root = workspace({ "design/broken.kind.mjs": "export const nothing = 1;\n" }, [{ kind: "gone.kind.mjs" }, { kind: "broken.kind.mjs" }]);
+    const report = await runDeclarationChecks(root);
+    const wsp115 = report.diagnostics.filter((d) => d.ruleId === "WSP115");
+    expect(wsp115.map((d) => [d.entity, d.message])).toEqual([
+      ["design", "member design declares the record kind gone.kind.mjs, which can't be loaded: kind-unreadable: kind file design/gone.kind.mjs does not exist"],
+      ["design", "member design declares the record kind broken.kind.mjs, which can't be loaded: kind-invalid: kind file design/broken.kind.mjs is not a record kind: it has no recordKind export"],
+    ]);
+    expect(wsp115.every((d) => d.severity === "error" && d.line > 1)).toBe(true);
+    expect(report.ok).toBe(false);
+  });
+
+  test("finds nothing when every declared kind loads, and the check can't be suppressed", async () => {
+    expect((await runDeclarationChecks(workspace())).diagnostics.filter((d) => d.ruleId === "WSP115")).toEqual([]);
+    const root = workspace({}, [{ kind: "gone.kind.mjs" }]);
+    writeFiles(root, {
+      "chant.workspace.json": decl(members({ records: [{ kind: "gone.kind.mjs" }], suppress: [{ check: "WSP115", because: "later" }] })),
+    });
+    const ids = (await runDeclarationChecks(root)).diagnostics.map((d) => d.ruleId);
+    expect(ids).toContain("WSP115");
+    expect(ids).toContain("WSP011");
+  });
+});
+
+describe("records without --kind reads every declared kind (#2680)", () => {
+  const { expectValid } = contract(recordsSchema);
+  let out: string[];
+  let err: string[];
+  beforeEach(() => {
+    out = [];
+    err = [];
+    vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => void out.push(a.join(" ")));
+    vi.spyOn(console, "error").mockImplementation((...a: unknown[]) => void err.push(a.join(" ")));
+  });
+  afterEach(() => vi.restoreAllMocks());
+  const run = (cwd: string, ...argv: string[]) => {
+    vi.spyOn(process, "cwd").mockReturnValue(cwd);
+    return runWorkspaceRecords({ args: parseArgs(["workspace", "records", ...argv]), plugins: [] } as never);
+  };
+
+  test("one document per kind in the declaration's order, as a set that validates", async () => {
+    const root = workspace();
+    const set = await queryDeclaredRecords(declaredKindFiles(root), { cwd: root, current: true });
+    expectValid(set);
+    expect(set.kinds.map((k) => ["error" in k ? k.error.code : k.kind.name, k.declared])).toEqual([
+      ["decision", { member: null, path: "decisions/decision.kind.mjs", name: null }],
+      ["note", { member: "design", path: "design/notes/note.kind.mjs", name: "notes" }],
+    ]);
+    expect(await run(root, "--json")).toBe(0);
+    const printed = JSON.parse(out.join("\n"));
+    expectValid(printed);
+    expect(printed.kinds.map((k: { records: { id: string }[] }) => k.records.map((r) => r.id))).toEqual([["ref-001"], ["ref-001"]]);
+  });
+
+  test("a kind that can't be read is listed with its error, the others are read, and the exit code is 1", async () => {
+    const root = workspace({}, [{ kind: "gone.kind.mjs" }]);
+    expect(await run(root, "--json")).toBe(1);
+    const printed = JSON.parse(out.join("\n"));
+    expectValid(printed);
+    expect(printed.kinds.map((k: { error?: { code: string }; records?: unknown[] }) => k.error?.code ?? k.records!.length)).toEqual([1, "kind-unreadable"]);
+  });
+
+  test("--kind overrides, and with neither --kind nor declared kinds the message is today's", async () => {
+    const root = workspace();
+    expect(await run(root, "--kind", "design/notes/note.kind.mjs", "--json")).toBe(0);
+    const one = JSON.parse(out.join("\n"));
+    expect(one.kind.name).toBe("note");
+    expect(one.kinds).toBeUndefined();
+
+    const bare = repo({ "chant.workspace.json": decl(members()), "app/x": "", "design/x": "" });
+    expect(await run(bare)).toBe(1);
+    expect(err.join("\n")).toContain("--kind <kind file> is required");
+    err.length = 0;
+    expect(await run(repo({ "x.md": "" }))).toBe(1);
+    expect(err.join("\n")).toContain("--kind <kind file> is required");
+  });
+
+  test("--since compares every declared kind too, one records-since document per kind (#2673)", async () => {
+    const root = workspace();
+    writeFiles(root, { "decisions/ref-009-another.md": REF_001.replace('id: "ref-001"', 'id: "ref-009"') });
+    expect(await run(root, "--since", "HEAD", "--json")).toBe(0);
+    const printed = JSON.parse(out.join("\n"));
+    contract(recordsSinceSchema).expectValid(printed);
+    expect(printed.kinds.map((k: { kind: { name: string }; declared: { path: string }; changes: { change: string; id: string }[] }) => [k.declared.path, k.kind.name, k.changes.map((c) => `${c.change} ${c.id}`)])).toEqual([
+      ["decisions/decision.kind.mjs", "decision", ["new ref-009"]],
+      ["design/notes/note.kind.mjs", "note", []],
+    ]);
+    out.length = 0;
+    expect(await run(root, "--since", "HEAD", "--kind", "design/notes/note.kind.mjs", "--json")).toBe(0);
+    expect(JSON.parse(out.join("\n")).kind.name).toBe("note");
+    expect(await run(root, "--since", "HEAD", "--current")).toBe(1);
+  });
+
+  test("text output heads each kind with its name and file", async () => {
+    expect(await run(workspace(), "--current")).toBe(0);
+    expect(out.filter((l) => l.includes("("))).toEqual(["decision (decisions/decision.kind.mjs)", "notes (design/notes/note.kind.mjs)"]);
+  });
+});
+
+describe("records new, amend and review without --kind (#2680)", () => {
+  let out: string[];
+  beforeEach(() => {
+    out = [];
+    vi.spyOn(console, "log").mockImplementation((...a: unknown[]) => void out.push(a.join(" ")));
+  });
+  afterEach(() => vi.restoreAllMocks());
+  const run = async (cwd: string, ...argv: string[]) => {
+    vi.spyOn(process, "cwd").mockReturnValue(cwd);
+    const status = await runRecordsWrite({ args: parseArgs(["workspace", "records", ...argv]), plugins: [] } as never);
+    return { status, doc: JSON.parse(out.join("\n")) };
+  };
+
+  test("write through the one kind the declaration names", async () => {
+    const root = workspace({}, []);
+    const reviewed = await run(root, "review", "ref-001", "--verdict", "agree", "--by", "bob", "--dry-run");
+    expect(reviewed).toMatchObject({ status: 0, doc: { path: expect.stringContaining("decisions/ref-001-"), review: { reviewer: "bob", verdict: "agree" }, dryRun: true } });
+    out.length = 0;
+    writeFiles(root, { "patch.json": JSON.stringify({ title: "Changed" }) });
+    const amended = await run(root, "amend", "ref-001", "--set", join(root, "patch.json"), "--dry-run");
+    expect(amended.doc.error?.code).not.toBe("write-usage-invalid");
+  });
+
+  test("are refused with the kinds named when the declaration names several, and --kind picks one", async () => {
+    const root = workspace();
+    const refused = await run(root, "review", "ref-001", "--verdict", "agree", "--by", "bob", "--dry-run");
+    expect(refused.status).toBe(1);
+    expect(refused.doc.error.code).toBe("write-usage-invalid");
+    expect(refused.doc.error.message).toContain("the declaration names 2 record kinds (decisions/decision.kind.mjs, design/notes/note.kind.mjs), so name the one to write with --kind");
+    out.length = 0;
+    const picked = await run(root, "review", "ref-001", "--kind", join(root, "decisions/decision.kind.mjs"), "--verdict", "agree", "--by", "bob", "--dry-run");
+    expect(picked.status).toBe(0);
+    out.length = 0;
+    const bare = repo({ "chant.workspace.json": decl(members()), "app/x": "", "design/x": "" });
+    const none = await run(bare, "review", "ref-001", "--verdict", "agree", "--by", "bob");
+    expect(none.doc.error.message).toMatch(/^--kind <kind file> is required/);
+  });
+});
+
+describe("graph --intent without --kind reads every declared kind (#2680)", () => {
+  const { expectValid } = contract(intentSchema);
+  /** Both kinds join a commit's Unit trailer: each to its own unit, and both to one contract. */
+  const joins = (unit: string, status: string) =>
+    `\nexport function commitJoins(commit) {\n  const id = commit.trailers["Unit"]?.[0];\n  if (!id) return undefined;\n  return { unit: { id: "${unit}-" + id }, contract: { id: "C-1", status: "${status}" } };\n}\n`;
+
+  test("in the declaration's order, and when two kinds join one commit both joins apply and the first kind's node data wins", async () => {
+    const root = workspace({
+      "decisions/decision.kind.mjs": DECISION_KIND + joins("D", "from-decisions"),
+      "design/notes/note.kind.mjs": NOTE_KIND + joins("N", "from-notes"),
+    });
+    writeFiles(root, { "app/server.mjs": "export const port = 9090;\n" });
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "move the port", "-m", "Unit: U-1");
+    const sha = git(root, "rev-parse", "HEAD");
+
+    const { doc } = await intentGraph({ cwd: root, region: "app/server.mjs" });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.kinds).toEqual([
+      { file: "decisions/decision.kind.mjs", name: "decision", records: "decision", joins: "function" },
+      { file: "design/notes/note.kind.mjs", name: "note", records: "note", joins: "function" },
+    ]);
+    const produced = doc.edges.filter((e) => e.kind === "produced-by" && e.from === `commit:${sha}`).map((e) => e.to);
+    expect(produced).toEqual(["unit:D-U-1", "unit:N-U-1"]);
+    const contractNode = doc.nodes.find((n) => n.id === "contract:C-1") as unknown as { plugin: string; data: { status: string } };
+    expect(contractNode.plugin).toBe("decisions/decision.kind.mjs");
+    expect(contractNode.data.status).toBe("from-decisions");
+
+    // --kind overrides the declaration, and an empty list reads none.
+    const one = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [join(root, "design/notes/note.kind.mjs")] });
+    expect("error" in one.doc ? [] : one.doc.kinds.map((k) => k.name)).toEqual(["note"]);
+    const none = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [] });
+    expect("error" in none.doc ? null : none.doc.kinds).toEqual([]);
+  });
+});

package/src/workspace/declared-kinds.ts

@@ -0,0 +1,76 @@
+/**
+ * The record kinds a declaration names, loaded (#2680).
+ *
+ * `chant.workspace.json` may name the workspace's record kinds, in the
+ * top-level `records` and in each member's `records`, so a reader never has to
+ * guess which kind files exist. `chant workspace ls` lists them, `check` fails
+ * on one that doesn't load (WSP115), and `records` and `graph --intent` read
+ * every one of them when `--kind` is not given.
+ *
+ * A kind file is looked for in the tree read, which is the revision under
+ * `--at`, and loaded from the working tree, as `records --kind` loads one.
+ * Loading imports the file, so it runs only where a command already runs a
+ * kind file.
+ */
+
+import { join } from "node:path";
+import { declaredRecordKinds, type Declaration, type RecordKindDeclaration } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import type { WorkspaceTree } from "./tree";
+
+/** Why a declared kind can't be loaded: the codes `loadRecordKind` fails with. Closed, like every list of codes. */
+export const DECLARED_KIND_REASON_CODES = ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch"] as const satisfies readonly ReasonCode[];
+export type DeclaredKindReasonCode = (typeof DECLARED_KIND_REASON_CODES)[number];
+
+export interface DeclaredKind {
+  declared: RecordKindDeclaration;
+  /** The kind file on disk, absolute. */
+  file: string;
+  /** The kind file's `recordKind.name`, or null when it wasn't loaded. */
+  kind: string | null;
+  /** Why it can't be loaded, or null. */
+  reason: { code: DeclaredKindReasonCode; message: string } | null;
+}
+
+/** The kind file of `declared` on disk, under the workspace root `rootOnDisk`. */
+export function declaredKindFile(declared: RecordKindDeclaration, rootOnDisk: string): string {
+  return join(rootOnDisk, ...declared.path.split("/"));
+}
+
+/**
+ * Every kind the declaration names, in {@link declaredRecordKinds} order, each
+ * with its name or the reason it can't be loaded. A kind file missing from
+ * `tree` is `kind-unreadable` without a load. With `load: false`, nothing is
+ * imported and only that is checked.
+ */
+export async function loadDeclaredKinds(
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  rootOnDisk: string,
+  options: { load?: boolean } = {},
+): Promise<DeclaredKind[]> {
+  const declared = declaredRecordKinds(declaration);
+  if (declared.length === 0) return [];
+  const records = options.load === false ? undefined : await import("./records");
+  const out: DeclaredKind[] = [];
+  for (const d of declared) {
+    const file = declaredKindFile(d, rootOnDisk);
+    if (tree.stat(d.path) !== "file") {
+      out.push({ declared: d, file, kind: null, reason: { code: "kind-unreadable", message: `kind file ${d.path} does not exist${tree.label}` } });
+      continue;
+    }
+    if (!records) {
+      out.push({ declared: d, file, kind: null, reason: null });
+      continue;
+    }
+    try {
+      const loaded = await records.loadRecordKind(file);
+      out.push({ declared: d, file, kind: loaded.kind.name, reason: null });
+    } catch (err) {
+      if (!(err instanceof records.RecordReadError)) throw err;
+      // loadRecordKind names the file as it was given, here an absolute path: name it from the workspace root instead.
+      out.push({ declared: d, file, kind: null, reason: { code: err.code as DeclaredKindReasonCode, message: err.message.split(file).join(d.path) } });
+    }
+  }
+  return out;
+}

package/src/workspace/graph-cli.ts

@@ -85,6 +85,13 @@ export interface GraphQuery {
    * in {@link GraphResult.components}. The document is unchanged.
    */
   components?: boolean;
+  /**
+   * Called once the members have run, with the directory they were read from
+   * (the exported tree for `--at`, before it is removed) and the declared
+   * members the read covers. `--composites` reads each member's runtimes
+   * here (#2674).
+   */
+  inTree?: (root: string, members: readonly { name: string; dir: string; kind: string }[]) => Promise<void>;
 }
 
 export interface GraphResult {
@@ -198,6 +205,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
       executePlan(plan, args),
       query.components ? executePlan(plan, args, () => componentGraphArgv(args)) : Promise.resolve(undefined),
     ]);
+    if (query.inTree) await query.inTree(exported ?? located.rootOnDisk, declaration.members.filter((m) => !query.members?.length || query.members.includes(m.name)));
     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);

package/src/workspace/intent-cli.ts

@@ -5,13 +5,14 @@
  * section B: the region, its decisions, their artifacts, the commits, and the
  * findings. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
- * to the person about it (#2656).
+ * to the person about it (#2656). Without `--kind`, the walk reads every
+ * record kind the declaration names (#2680).
  */
 
 import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
-import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode } from "./intent";
+import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type WorkNode } from "./intent";
 
 const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
 
@@ -57,6 +58,22 @@ function decisionLine(d: DecisionNode): string {
   return `decision  ${d.record} ${d.state ?? "stateless"}${superseded}: ${d.title ?? d.path}; constrains ${via}${by}; ${reviews}; ${d.provenance.level}${d.valid ? "" : `; invalid: ${d.reasons.map((r) => r.code).join(", ")}`}`;
 }
 
+/** A work item, then the commits made inside its window (#2683). */
+function workLines(doc: Result, w: WorkNode): string[] {
+  const via = w.constrains.length > 0 ? w.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through a link only";
+  const implemented = w.implements.length > 0 ? `; implements ${w.implements.map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ")}` : "";
+  const readiness = w.ready ? "; ready" : w.blockedBy.length > 0 ? `; blocked by ${w.blockedBy.map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ")}` : "";
+  const owner = w.owner ? `, owned by ${w.owner}` : "";
+  const from = w.source ? `; from ${w.source.finding} on ${w.source.region}` : "";
+  const out = [`work      ${w.record} ${w.state ?? "stateless"}${owner}: ${w.title ?? w.path}; constrains ${via}${implemented}${readiness}${from}`];
+  for (const e of doc.edges.filter((x) => x.kind === "within" && x.to === w.id)) {
+    const c = doc.nodes.find((n): n is CommitNode => n.kind === "commit" && n.id === e.from);
+    if (c) out.push(`  worked    ${short(c.sha)} ${c.subject}; in ${w.record}'s window`);
+  }
+  for (const x of w.warnings) out.push(`  warning   ${x.code}: ${x.message}`);
+  return out;
+}
+
 function artifactLine(doc: Result, a: ArtifactNode): string {
   const by = doc.edges
     .filter((e): e is Extract<IntentEdge, { kind: "pins" }> => e.kind === "pins" && e.to === a.id)
@@ -88,16 +105,21 @@ export function formatIntent(doc: Result): string {
   const files = ofKind(doc, "file");
   if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
   for (const d of ofKind(doc, "decision")) out.push(decisionLine(d), ...withinLines(doc, d));
+  for (const w of ofKind(doc, "work")) out.push(...workLines(doc, w));
   for (const a of ofKind(doc, "artifact")) out.push(artifactLine(doc, a));
   for (const c of ofKind(doc, "commit")) out.push(...commitLine(doc, c));
   for (const l of ofKind(doc, "link")) {
     const r = l.row;
     out.push(`link      ${r.consumer} reads ${"producer" in r ? `${r.producer} ${r.output}` : r.input} (${r.status})`);
   }
-  for (const f of ofKind(doc, "finding")) out.push(`finding   ${f.code}: ${f.message}`);
+  for (const f of ofKind(doc, "finding")) {
+    const by = f.addressedBy && f.addressedBy.length > 0 ? `; addressed by ${f.addressedBy.map((w) => `${w.id} (${w.state ?? "unknown"})`).join(", ")}` : "";
+    out.push(`finding   ${f.code}: ${f.message}${by}`);
+  }
   for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
   const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
-  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
+  const work = ofKind(doc, "work").length;
+  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
   return out.join("\n");
 }
 
@@ -107,8 +129,9 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
     console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
     return 1;
   }
-  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : []);
-  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds.map((k) => resolve(k)) });
+  // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));