@intentius/chant 0.91.0 → 0.94.0

package/src/workspace/answers-ledger.ts

@@ -0,0 +1,118 @@
+/**
+ * Answer records held on the lifecycle ledger (#2786).
+ *
+ * A steward's writes never touch the checkout's index or working tree
+ * (`../op/steward.ts`): the working tree is the coding agent's. A decision
+ * point asked in a steward's turn still has to leave its question somewhere a
+ * person finds it after the turn ends, and an Op's leased worktree is removed
+ * with the run. So a question asked in a steward's turn is written to
+ * `chant/lifecycle`, beside the lease histories and run records, under
+ * `_answers/<kind name>/<id>.md` in the ledger of the member that owns the
+ * answer kind. The file is the same Markdown record the kind's directory
+ * would hold, and it is written with git plumbing, like every ledger write.
+ *
+ * Readers see the ledger's answers as if they sat in the kind's directory:
+ * {@link withLedgerAnswers} lays them over the working tree, so `points`,
+ * `points --open`, a later `points ask` of the same question and `points
+ * answer` all find them. A record on the ledger wins over a file of the same
+ * name in the tree, because the ledger copy is the one a steward rewrote.
+ * People's answer to a question held on the ledger is written back there, so
+ * answering through hud in a box does not touch the checkout either.
+ *
+ * `points --at <rev>` reads a revision of the working branch, which the
+ * ledger is not part of, so it lists the tree's records only.
+ */
+
+import { basename, dirname } from "node:path";
+import { fetchLifecycleStatus, ledgerDir, listFilesInDir, pushLifecycle, readBlobBySha, readPathSha, writeBlobToPath } from "../lifecycle/git";
+import type { RecordSource } from "./record-source";
+import { overlay } from "./records-write";
+
+/** The directory on `chant/lifecycle`, under the member's prefix, that holds answer records. */
+export const ANSWERS_LEDGER_DIR = "_answers";
+
+const BRANCH = "chant/lifecycle";
+
+/** One answer record on the ledger. */
+export interface LedgerAnswer {
+  /** Where the record reads as being: the kind's directory, from the repository root. */
+  path: string;
+  /** Where it is: `chant/lifecycle:<path on the branch>`, which `git show` reads. */
+  ledger: string;
+  text: string;
+  /** Its blob sha, for a compare-and-set rewrite. */
+  sha: string;
+}
+
+/** The answer records one kind holds on the ledger. */
+export interface LedgerAnswers {
+  /** Where the ledger is resolved from: the kind file's directory, so the member owning the kind owns its answers. */
+  cwd: string;
+  /** The directory on the branch, relative to the member's prefix. */
+  dir: string;
+  /** The kind's records directory, from the repository root. */
+  dirRel: string;
+  /** By the path each record reads as. */
+  byPath: Map<string, LedgerAnswer>;
+}
+
+/** The ledger directory of the kind named `kindName`. */
+export function answersLedgerDir(kindName: string): string {
+  return `${ANSWERS_LEDGER_DIR}/${kindName.replace(/[^A-Za-z0-9._-]/g, "_")}`;
+}
+
+function treePath(dirRel: string, name: string): string {
+  return dirRel === "." ? name : `${dirRel}/${name}`;
+}
+
+/**
+ * Read the answer records the kind at `kindFile` holds on the ledger. Empty
+ * when there are none, when there is no ledger branch, and outside a git
+ * repository.
+ */
+export async function readLedgerAnswers(kind: { file: string; name: string; dirRel: string }): Promise<LedgerAnswers> {
+  const cwd = dirname(kind.file);
+  const dir = answersLedgerDir(kind.name);
+  const out: LedgerAnswers = { cwd, dir, dirRel: kind.dirRel, byPath: new Map() };
+  try {
+    const names = (await listFilesInDir(dir, { cwd })).filter((n) => n.endsWith(".md"));
+    if (names.length === 0) return out;
+    const full = await ledgerDir(dir, { cwd });
+    for (const name of names) {
+      const sha = await readPathSha(dir, name, { cwd });
+      const text = sha ? await readBlobBySha(sha, { cwd }) : null;
+      if (sha === null || text === null) continue;
+      const path = treePath(kind.dirRel, name);
+      out.byPath.set(path, { path, ledger: `${BRANCH}:${full}/${name}`, text, sha });
+    }
+  } catch {
+    // No repository, or a member ledger that can't be placed: the tree's records are all there is.
+  }
+  return out;
+}
+
+/** `base` with each ledger answer at the path it reads as, over any file of the same name. */
+export function withLedgerAnswers(base: RecordSource, answers: LedgerAnswers): RecordSource {
+  let source = base;
+  for (const a of answers.byPath.values()) source = overlay(source, a.path, a.text);
+  return source;
+}
+
+/** Fetch `chant/lifecycle` before a ledger write when it fast-forwards, so a question another clone asked is found. Best effort. */
+export async function refreshLedger(kindFile: string): Promise<void> {
+  await fetchLifecycleStatus({ cwd: dirname(kindFile) }).catch(() => undefined);
+}
+
+/**
+ * Write the record read as `path` to the ledger, expecting the blob it had
+ * when it was read (`prior`, null for a new record), then push the branch.
+ * A changed blob throws `RefCASConflictError` from `../lifecycle/git`. The
+ * push is best effort: a question that did not reach the remote is still
+ * open here. Returns where the record went.
+ */
+export async function writeLedgerAnswer(answers: LedgerAnswers, path: string, text: string, message: string, prior: string | null): Promise<{ ledger: string; pushed: boolean }> {
+  const name = basename(path);
+  await writeBlobToPath(answers.dir, name, text, message, { cwd: answers.cwd, expectPriorPathSha: prior });
+  const pushed = await pushLifecycle({ cwd: answers.cwd }).catch(() => false);
+  return { ledger: `${BRANCH}:${await ledgerDir(answers.dir, { cwd: answers.cwd })}/${name}`, pushed };
+}

package/src/workspace/box-intent.test.ts

@@ -0,0 +1,205 @@
+/**
+ * A box's intent (#2850): the decision record the box block names, as
+ * `status --json` reports it, as `check` finds it (WSP126, WSP127) and as
+ * `graph --intent` shows it for the box's files.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
+import { constrainsBox, constrainsWorkspace } from "./box-intent";
+import { runDeclarationChecks } from "./checks";
+import { parseDeclaration } from "./declaration";
+import { intentGraph } from "./intent";
+import { parseFrontMatter } from "./records";
+import { workspaceStatus, type StatusDocument } from "./status";
+import statusSchema from "./status.schema.json";
+
+afterAll(cleanScratch);
+
+const REF = join(REPO, "reference-workspace", "decisions");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value as Record<string, unknown>;
+})();
+
+const QUESTION = "What is this box for?";
+const CHOICE = { option: "a", reason: "The person who planted the box answered it." };
+const ANSWER = "a chant project with the docker lexicon";
+
+/** A decision record from ref-001: proposed with no choice, or decided by alex. JSON is YAML, so the front matter is JSON. */
+function decision(id: string, state: "proposed" | "decided", constrains: string[]): string {
+  const data = {
+    ...BASE,
+    id,
+    title: `Intent ${id}`,
+    state,
+    question: QUESTION,
+    choice: state === "decided" ? CHOICE : null,
+    rejected: [],
+    evidence: [],
+    decided_by: state === "decided" ? "alex" : null,
+    decided_on: state === "decided" ? "2026-09-26" : null,
+    constrains,
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function workspace(box: Record<string, unknown>, records: Record<string, string>, declareKind = true): string {
+  return repo({
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "acme",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "the box", box }],
+        ...(declareKind ? { records: [{ kind: "decisions/decision.kind.mjs" }] } : {}),
+      },
+      null,
+      2,
+    ),
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decision.schema.json"), "utf-8"),
+    ...records,
+  });
+}
+
+/**
+ * A workspace shaped like the studio template (studio#112, #2857): the box
+ * block sits on member `box`, the steward and its Ops, and a separate
+ * member `app` is the app the box runs. `records` overlays the decision
+ * files, keyed the same way `repo()` takes every other file.
+ */
+function studioShapedWorkspace(records: Record<string, string>): string {
+  return repo({
+    "chant.workspace.json": JSON.stringify(
+      {
+        name: "acme",
+        schema: 1,
+        members: [
+          { name: "box", dir: "box", kind: "other", because: "the box's steward and its Ops", box: { intent: "box-001" } },
+          { name: "app", dir: "app", kind: "other", because: "the app the box runs" },
+        ],
+        records: [{ kind: "decisions/decision.kind.mjs" }],
+      },
+      null,
+      2,
+    ),
+    "box/ops.mjs": "export const ops = true;\n",
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decision.schema.json"), "utf-8"),
+    ...records,
+  });
+}
+
+const intentFindings = async (root: string) =>
+  (await runDeclarationChecks(root)).diagnostics.filter((d) => d.ruleId === "WSP126" || d.ruleId === "WSP127").map((d) => [d.ruleId, d.severity, d.code, d.entity]);
+
+const status = contract(statusSchema);
+async function boxOf(root: string) {
+  const doc: StatusDocument = await workspaceStatus({ cwd: root, env: "prod" });
+  if ("error" in doc) throw new Error(doc.error.message);
+  status.expectValid(doc);
+  return doc.members[0].box;
+}
+
+describe("the box block's intent", () => {
+  test("is parsed into the box declaration, and is null when the block names none", () => {
+    const parse = (box: unknown) =>
+      parseDeclaration(JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "x", box }] }), "chant.workspace.json").members[0].box;
+    expect(parse({ intent: "box-001" })?.intent).toBe("box-001");
+    expect(parse({})?.intent).toBeNull();
+  });
+
+  test("covers the box through member:, or a path: at, above or inside its directory", () => {
+    const m = { name: "app", dir: "apps/app" };
+    expect(["member:app", "path:apps/app", "path:apps", "path:apps/app/server.mjs"].map((c) => constrainsBox(c, m))).toEqual([true, true, true, true]);
+    expect(["member:web", "path:apps/application", "path:web", "issue:1"].map((c) => constrainsBox(c, m))).toEqual([false, false, false, false]);
+  });
+
+  test("constrainsWorkspace: an entry names a member or path of the workspace whether or not it's the box's own (#2857)", () => {
+    const members = [
+      { name: "box", dir: "box" },
+      { name: "app", dir: "app" },
+    ];
+    expect(["member:box", "member:app", "path:app", "path:box/ops.mjs"].map((c) => constrainsWorkspace(c, members))).toEqual([true, true, true, true]);
+    expect(["member:web", "path:docs", "issue:1"].map((c) => constrainsWorkspace(c, members))).toEqual([false, false, false]);
+    expect(constrainsWorkspace("member:app", [])).toBe(false);
+  });
+});
+
+describe("a box planted as a question", () => {
+  test("a proposed intent reports its question and no answer, and passes the checks", async () => {
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "proposed", question: QUESTION, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect(await intentFindings(root)).toEqual([]);
+  });
+
+  test("a decided intent reports the answer and who gave it, and graph --intent shows it for the box's files", async () => {
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "decided", ["member:app"]) });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-001", state: "decided", question: QUESTION, choice: CHOICE, answer: ANSWER, decided_by: "alex", decided_on: "2026-09-26" });
+    expect(await intentFindings(root)).toEqual([]);
+    commitAll(root, "plant the box");
+    const { doc } = await intentGraph({ cwd: root, region: "app" });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.nodes.filter((n) => n.kind === "decision").map((n) => (n.kind === "decision" ? [n.record, n.state, n.decided_by] : []))).toEqual([["box-001", "decided", "alex"]]);
+  });
+
+  test("a decided intent whose choice names an option not in options[] reports a null answer", async () => {
+    const data = { ...BASE, id: "box-001", title: "Intent box-001", state: "decided", question: QUESTION, choice: { option: "z", reason: "no such option" }, rejected: [], evidence: [], decided_by: "alex", decided_on: "2026-09-26", constrains: ["member:app"] };
+    const record = `---\n${JSON.stringify(data, null, 2)}\n---\n\n# box-001\n`;
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": record });
+    expect((await boxOf(root))?.intent?.answer).toBeNull();
+  });
+
+  test("an intent no decision record has fails WSP126, and status reports only its id", async () => {
+    const root = workspace({ intent: "box-009" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
+    expect((await boxOf(root))?.intent).toEqual({ id: "box-009", state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null });
+    expect(await intentFindings(root)).toEqual([["WSP126", "error", "box-intent-unknown", "app"]]);
+    const [d] = (await runDeclarationChecks(root)).diagnostics.filter((x) => x.ruleId === "WSP126");
+    expect(d.message).toContain("no record of decisions/decision.kind.mjs has that id");
+  });
+
+  test("an intent in a workspace that declares no decision kind fails WSP126", async () => {
+    const root = workspace({ intent: "box-001" }, {}, false);
+    const [d] = (await runDeclarationChecks(root)).diagnostics.filter((x) => x.ruleId === "WSP126");
+    expect(d.message).toContain("the declaration names no record kind called decision");
+  });
+
+  test("an intent whose constrains names no member or path of the workspace warns WSP127", async () => {
+    const root = workspace({ intent: "box-001" }, { "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["path:docs"]) });
+    expect(await intentFindings(root)).toEqual([["WSP127", "warning", "box-intent-unconstrained", "app"]]);
+  });
+
+  test("an intent with empty constrains warns WSP127", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", []) });
+    expect(await intentFindings(root)).toEqual([["WSP127", "warning", "box-intent-unconstrained", "box"]]);
+    const d = (await runDeclarationChecks(root)).diagnostics.find((x) => x.ruleId === "WSP127")!;
+    expect(d.message).toContain("whose constrains is empty");
+    expect(d.message).toContain("add member:<name> for the member the intent is about");
+  });
+
+  test("an intent naming an unknown member warns WSP127", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:web"]) });
+    expect(await intentFindings(root)).toEqual([["WSP127", "warning", "box-intent-unconstrained", "box"]]);
+  });
+
+  test("an intent that constrains the app a box runs passes WSP127, on a workspace shaped like the studio template (#2857)", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["member:app"]) });
+    expect(await intentFindings(root)).toEqual([]);
+  });
+
+  test("an intent with a path: entry inside another member's directory passes WSP127 (#2857)", async () => {
+    const root = studioShapedWorkspace({ "decisions/box-001-what-app-is-for.md": decision("box-001", "proposed", ["path:app/server.mjs"]) });
+    expect(await intentFindings(root)).toEqual([]);
+  });
+
+  test("a box with no intent reports null", async () => {
+    const root = workspace({ capabilities: [] }, {});
+    expect((await boxOf(root))?.intent).toBeNull();
+    expect(await intentFindings(root)).toEqual([]);
+  });
+});

package/src/workspace/box-intent.ts

@@ -0,0 +1,159 @@
+/**
+ * A box's intent (#2850): the decision record its box block names.
+ *
+ * A new box starts as a question, and the first answer to it is what the box
+ * is for. That answer is a decision record, so the intent graph, hud and a
+ * box's runtime all read the same thing. The box block names the record's
+ * id in `intent`; the record is looked for among the records of every
+ * declared kind named `decision` (the entry's `name`, or the kind file's
+ * `recordKind.name`), read from the working tree through the same reader as
+ * `chant workspace records`.
+ *
+ * `chant workspace status --json` reports the record's state and answer
+ * under the member's `box.intent`, and `chant workspace check` fails when no
+ * decision record has the id (WSP126) and warns when the record constrains
+ * no member or path of this workspace at all (WSP127, #2857): the member it
+ * names need not be the box's own, since a decision naming another member
+ * can be what the box is for, such as the app it runs.
+ */
+
+import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
+import type { Declaration, Member } from "./declaration";
+import { constraintCovers, isWorkspacePath } from "./record-assets";
+import { workingTree } from "./tree";
+
+/** The declared kind name a box's intent is looked for in. */
+export const INTENT_KIND_NAME = "decision";
+
+/** A box's intent as `status --json` reports it: the record's id, state and answer. */
+export interface BoxIntent {
+  id: string;
+  /** The record's state, such as proposed or decided, or null when no decision record has the id. */
+  state: string | null;
+  question: string | null;
+  /** The record's choice as written, such as `{ option, reason }`, or null while it is proposed. */
+  choice: unknown;
+  /** The chosen option's label, from `options[]`, or null while no option is chosen. */
+  answer: string | null;
+  decided_by: string | null;
+  decided_on: string | null;
+}
+
+/** The decision record a box's intent names, as the checks read it. */
+export interface ResolvedBoxIntent {
+  member: string;
+  id: string;
+  /** The `intent` field's JSON Pointer in the declaration. */
+  pointer: string;
+  /** The record, or null when no decision record has the id. */
+  record: {
+    /** The kind file that holds it, from the workspace root. */
+    kind: string;
+    /** The record file, from the repository root. */
+    path: string;
+    /** The record's constrains entries, as written. */
+    constrains: string[];
+    intent: BoxIntent;
+  } | null;
+  /** Why no record was found when none was, such as no declared decision kind. Empty when one was found. */
+  why: string;
+}
+
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+
+/** The label of `options[]`'s entry whose id is `choice.option`, or null when no option is chosen. */
+function answerOf(choice: unknown, options: unknown): string | null {
+  const chosen = choice && typeof choice === "object" ? (choice as { option?: unknown }).option : null;
+  if (typeof chosen !== "string" || !Array.isArray(options)) return null;
+  const found = options.find((o): o is { id: unknown; label: unknown } => !!o && typeof o === "object" && (o as { id?: unknown }).id === chosen);
+  return found && typeof found.label === "string" ? found.label : null;
+}
+
+/** The intent of `id` with no record: every field but the id null. */
+export function unresolvedIntent(id: string): BoxIntent {
+  return { id, state: null, question: null, choice: null, answer: null, decided_by: null, decided_on: null };
+}
+
+/**
+ * Resolve the intent of every box that names one, reading the records of each
+ * declared decision kind once. `kinds` are the declared kinds already loaded,
+ * when the caller has them. Only the working tree is read.
+ */
+export async function resolveBoxIntents(declaration: Declaration, root: string, kinds?: readonly DeclaredKind[]): Promise<ResolvedBoxIntent[]> {
+  const boxes = declaration.members.filter((m): m is Member & { box: NonNullable<Member["box"]> & { intent: string } } => m.box?.intent != null);
+  if (boxes.length === 0) return [];
+  const loaded = kinds ?? (await loadDeclaredKinds(declaration, workingTree(root), root));
+  const decisionKinds = loaded.filter((k) => (k.declared.name ?? k.kind) === INTENT_KIND_NAME);
+  const found = new Map<string, NonNullable<ResolvedBoxIntent["record"]>>();
+  const problems: string[] = [];
+  const { readRecordsFor } = await import("./records-cli");
+  const { RecordReadError } = await import("./records");
+  for (const k of decisionKinds) {
+    if (k.reason) {
+      problems.push(`${k.declared.path} can't be loaded: ${k.reason.message}`);
+      continue;
+    }
+    try {
+      const read = await readRecordsFor({ kind: k.file, cwd: root, workGaps: false });
+      const field = read.loaded.kind.constrains?.field ?? "constrains";
+      for (const r of read.result.records) {
+        if (r.id === null || found.has(r.id)) continue;
+        const data = r.data ?? {};
+        const constrains = Array.isArray(data[field]) ? (data[field] as unknown[]).filter((c): c is string => typeof c === "string") : [];
+        found.set(r.id, {
+          kind: k.declared.path,
+          path: r.path,
+          constrains,
+          intent: {
+            id: r.id,
+            state: r.state,
+            question: str(data.question),
+            choice: data.choice ?? null,
+            answer: answerOf(data.choice, data.options),
+            decided_by: str(data.decided_by),
+            decided_on: str(data.decided_on),
+          },
+        });
+      }
+    } catch (err) {
+      if (!(err instanceof RecordReadError)) throw err;
+      problems.push(`${k.declared.path} can't be read: ${err.message}`);
+    }
+  }
+  const why =
+    decisionKinds.length === 0
+      ? `the declaration names no record kind called ${INTENT_KIND_NAME}`
+      : `no record of ${decisionKinds.map((k) => k.declared.path).join(" or ")} has that id` + (problems.length > 0 ? ` (${problems.join("; ")})` : "");
+  return boxes.map((m) => {
+    const record = found.get(m.box.intent) ?? null;
+    return { member: m.name, id: m.box.intent, pointer: `${m.box.pointer}/intent`, record, why: record ? "" : why };
+  });
+}
+
+/**
+ * Whether a constrains entry covers something of the box: `member:<name>`, or
+ * a `path:` entry that is the member's directory, a directory above it or a
+ * path inside it.
+ */
+export function constrainsBox(entry: string, member: { name: string; dir: string }): boolean {
+  if (entry === `member:${member.name}`) return true;
+  if (!entry.startsWith("path:")) return false;
+  const path = entry.slice("path:".length);
+  if (!isWorkspacePath(path)) return false;
+  // The root member holds every path.
+  if (member.dir === ".") return true;
+  return constraintCovers(path, member.dir) || constraintCovers(member.dir, path);
+}
+
+/**
+ * Whether a constrains entry names a member or path of this workspace at
+ * all: `member:<name>` for any declared member, or a `path:` entry that is
+ * some member's directory, a directory above it or a path inside it. An
+ * intent's constrains can govern a member other than the one whose box
+ * names it (a box run by one member can be what a decision about another
+ * member's app is for), so this asks only whether the entry is real, not
+ * whether it reaches a particular member.
+ */
+export function constrainsWorkspace(entry: string, members: readonly { name: string; dir: string }[]): boolean {
+  return members.some((m) => constrainsBox(entry, m));
+}

package/src/workspace/changes-cli.ts

@@ -0,0 +1,56 @@
+/**
+ * `chant workspace check --changes <base>..<head> [--work <id>] [--severity
+ * off|warn|fail] [--kind <kind file>...] [--json]` (#2773): the forward
+ * coverage check (`changes.ts`), printed as JSON with `--json` or as one line
+ * per changed path, then the findings.
+ */
+
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { CHANGE_SEVERITIES, checkChanges, type ChangesDocument } from "./changes";
+import type { ChangeSeverity } from "./declaration";
+
+const USAGE = "chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
+
+type Result = Exclude<ChangesDocument, { error: unknown }>;
+
+/** One line per changed path, then the findings and a summary. */
+export function formatChanges(doc: Result): string {
+  const out: string[] = [];
+  const work = doc.work ? `, work item ${doc.work.record} in hand` : "";
+  out.push(`changes   ${doc.range.base.slice(0, 8)}..${doc.range.head.slice(0, 8)} (${doc.range.spec}), severity ${doc.severity}${work}`);
+  for (const p of doc.paths) {
+    const why =
+      p.status === "covered"
+        ? `by ${p.coveredBy.map((c) => `${c.record} (${c.entry})`).join(", ")}`
+        : p.status === "out-of-scope"
+          ? `by ${p.outOfScopeBy.map((c) => `${c.record} (${c.entry})`).join(", ")}`
+          : p.status === "ignored"
+            ? `by ${p.ignoredBy}`
+            : "";
+    out.push(`${p.status.padEnd(12)} ${p.change.padEnd(8)} ${p.path}${p.from ? ` (from ${p.from})` : ""}${why ? `; ${why}` : ""}`);
+  }
+  for (const f of doc.findings) out.push(`${f.severity === "fail" ? "error  " : "warning"}   ${f.code}: ${f.message}`);
+  const s = doc.summary;
+  out.push(`${s.paths} changed paths: ${s.covered} covered, ${s.uncovered} uncovered, ${s.outOfScope} out of scope, ${s.ignored} ignored, ${s.records} records; ${doc.findings.length} findings`);
+  return out.join("\n");
+}
+
+export async function runWorkspaceChanges(ctx: CommandContext, cwd: string): Promise<number> {
+  const { args } = ctx;
+  const severity = args.severity as ChangeSeverity | undefined;
+  if (severity !== undefined && !(CHANGE_SEVERITIES as readonly string[]).includes(severity)) {
+    console.error(formatError({ message: `--severity ${severity} is not off, warn or fail`, hint: USAGE }));
+    return 1;
+  }
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+  const { doc, failed } = await checkChanges({ cwd, range: args.changes!, kinds: kinds?.map((k) => resolve(k)), work: args.work, severity });
+  if (args.json || args.format === "json") console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if (!args.json && args.format !== "json") console.log(formatChanges(doc));
+  return failed ? 1 : 0;
+}