@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/work.ts

@@ -17,6 +17,9 @@
  * - `implements`: each decision it names, with that decision's state;
  * - `acceptance`, for a kind with acceptance criteria (#2772): how many of the
  *   record's criteria passing evidence of the expected verification meets;
+ * - `contract`, for a kind with a contract link (#3147): the contract record
+ *   the item builds, with its state, read from the contract kind at the same
+ *   revision;
  *
  * and each decision `implementedBy`, the work records naming it. The
  * warnings are closed codes. `work-done-gap-open` is not raised here: it
@@ -48,6 +51,12 @@ export const WORK_WARNING_CODES = [
   "work-acceptance-unmet",
   /** A passing `manual` verdict on a criterion names the record's implementer, so it does not count: a manual verdict comes from someone else (#2772). */
   "work-acceptance-self-verified",
+  /** The record names a contract no record of the kind's contract kind has (#3147). */
+  "work-contract-unknown",
+  /** The record names a contract whose state is not approved, such as a draft (#3147). */
+  "work-contract-undecided",
+  /** The record names a builder tier its kind's `work.tier.tiers` does not list (#3147). */
+  "work-tier-unknown",
 ] as const satisfies readonly ReasonCode[];
 export type WorkWarningCode = (typeof WORK_WARNING_CODES)[number];
 
@@ -58,6 +67,49 @@ export interface WorkLink {
   state: string | null;
 }
 
+/**
+ * One decision-point answer about a work item (#3147), as `records --json`
+ * joins it from the answer kind the work kind names: the answer records whose
+ * `constrains` names the item's id. The item never copies them.
+ */
+export interface WorkAnswer {
+  /** The answer record's id, such as understand-0123456789ab. */
+  id: string;
+  /** The decision point it answers. */
+  point: string | null;
+  /** escalated, proposed or answered. */
+  state: string | null;
+  /** The answer, or null while there is none. */
+  answer: string | boolean | null;
+  /** The people who answered or confirmed it, empty when a table or model did. */
+  answeredBy: string[];
+}
+
+/**
+ * The answers about each work item: every answer record whose `constrains`
+ * names the item's id, in path order, by item id.
+ */
+export function workAnswers(answerRecords: readonly RecordEntry[], ids: Iterable<string>): Map<string, WorkAnswer[]> {
+  const out = new Map<string, WorkAnswer[]>();
+  for (const id of ids) out.set(id, []);
+  for (const a of answerRecords) {
+    if (a.id === null || a.data === null) continue;
+    for (const target of idList(a.data, "constrains")) {
+      const list = out.get(target);
+      if (!list || list.some((x) => x.id === a.id)) continue;
+      const answer = a.data.answer;
+      list.push({
+        id: a.id,
+        point: typeof a.data.point === "string" ? a.data.point : null,
+        state: a.state,
+        answer: typeof answer === "string" || typeof answer === "boolean" ? answer : null,
+        answeredBy: idList(a.data, "answered_by"),
+      });
+    }
+  }
+  return out;
+}
+
 /** A decision as a work read lists it: its state and the work records implementing it. */
 export interface DecisionWork {
   id: string;
@@ -174,6 +226,16 @@ export async function applyWork(loaded: LoadedRecordKind, entries: RecordEntry[]
   for (const e of entries) if (e.id !== null && !byId.has(e.id)) byId.set(e.id, e);
   const closed = new Set(kind.closedStates);
 
+  // The contract kind a work item names its contract in (#3147), read at the same revision.
+  let contracts: { kind: LoadedRecordKind; byId: Map<string, RecordEntry> } | undefined;
+  if (work.contract) {
+    const contractKind = await loadRecordKind(work.contract.kind, dirname(loaded.file));
+    const contractRead = await readRecords(contractKind, { root: options.root, source: options.source });
+    const contractById = new Map<string, RecordEntry>();
+    for (const c of contractRead.records) if (c.id !== null && !contractById.has(c.id)) contractById.set(c.id, c);
+    contracts = { kind: contractKind, byId: contractById };
+  }
+
   // Records in a needs cycle: those that reach themselves.
   const inCycle = new Set<string>();
   for (const start of byId.keys()) {
@@ -242,6 +304,26 @@ export async function applyWork(loaded: LoadedRecordKind, entries: RecordEntry[]
         });
       }
     }
+    if (contracts && work.contract) {
+      const named = e.data[work.contract.field];
+      if (typeof named === "string" && named !== "") {
+        const c = contracts.byId.get(named);
+        e.contract = { id: named, state: c?.state ?? null };
+        if (!c) {
+          e.warnings.push({ code: "work-contract-unknown", message: `names the contract ${named}, which no record in ${work.contract.kind} has` });
+        } else if (!isDecided(contracts.kind.kind, c.state)) {
+          e.warnings.push({ code: "work-contract-undecided", message: `names the contract ${named}, which is ${c.state ?? "in no state"}: the work may build a contract nobody approved` });
+        }
+      } else {
+        e.contract = null;
+      }
+    }
+    if (work.tier) {
+      const tier = e.data[work.tier.field];
+      if (typeof tier === "string" && !work.tier.tiers.includes(tier)) {
+        e.warnings.push({ code: "work-tier-unknown", message: `names the builder tier ${tier}, which the kind's tiers (${work.tier.tiers.join(", ")}) do not list` });
+      }
+    }
     if (e.state !== null && closed.has(e.state) && typeof e.data[work.closedOn] !== "string") {
       e.warnings.push({ code: "work-closed-without-date", message: `${e.id ?? e.path} is ${e.state} and has no ${work.closedOn}` });
     }

package/src/workspace/workspace-principals.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/principals/v1/workspace-principals.schema.json",
+  "title": "workspace-principals.json",
+  "description": "Principal classes a plugin supplies (#2524 D5, #3080, ws-079). A package publishes this file as data at its ./workspace-principals subpath, beside ./workspace-kinds. chant reads it with the file system and never imports the package. A class is a name for the principals holding one role in the trust policy at base; the declaration's writeScope may then give it an entry.",
+  "type": "object",
+  "required": ["schema", "classes"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "An editor hint. chant ignores it."
+    },
+    "$comment": {
+      "type": "string",
+      "description": "A note for people. chant ignores it."
+    },
+    "schema": {
+      "const": 1,
+      "description": "The principal classes format version."
+    },
+    "classes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/class"
+      }
+    }
+  },
+  "patternProperties": {
+    "^x-": true
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "class": {
+      "type": "object",
+      "required": ["name", "description", "role"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
+          "description": "The class's name, as a key of the declaration's writeScope names it. human, agent, runner and service are the core classes and can't be supplied."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One line saying who is in the class, for listings and error messages."
+        },
+        "role": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "The role whose grant in the trust policy at base (.chant/trust.json roles) puts a principal in this class. The agent, runner and service roles belong to the core classes and can't be named here. One role puts a principal in one class."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/workspace/write-scope.test.ts

@@ -21,6 +21,7 @@ import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixture
 import { agentSession } from "./agent-cli";
 import agentSchema from "./agent.schema.json";
 import { checkChanges, type ChangesDocument } from "./changes";
+import { runDeclarationChecks } from "./checks";
 import changesSchema from "./changes.schema.json";
 import { formatChanges } from "./changes-cli";
 import { parseDeclaration, WorkspaceReadError } from "./declaration";
@@ -109,8 +110,8 @@ describe("the declaration's writeScope and agents (#2548)", () => {
   test("are read with their defaults", () => {
     const d = parseDeclaration(declaration(), "chant.workspace.json");
     expect(d.writeScope).toEqual({
-      agent: { members: null, records: { decision: ["new", "review"] }, pointer: "/writeScope/agent" },
-      runner: { members: ["app"], records: { decision: ["review"] }, pointer: "/writeScope/runner" },
+      agent: { members: null, records: { decision: ["new", "review"] }, protected: [], pointer: "/writeScope/agent" },
+      runner: { members: ["app"], records: { decision: ["review"] }, protected: [], pointer: "/writeScope/runner" },
     });
     expect(d.agents.map((a) => [a.name, a.member, a.principals])).toEqual([
       ["app-agent", "app", ["bot@example.com"]],
@@ -326,6 +327,7 @@ describe("chant workspace agent: what a session reloads from (#2548)", () => {
         { path: KIND, kind: "decision", name: null, member: null, verbs: ["new", "review"] },
         { path: DESIGN_KIND, kind: "decision", name: "screen", member: "design", verbs: ["new", "review"] },
       ],
+      protected: [],
     });
     expect(doc.spec.kinds.map((k) => k.path)).toEqual([KIND, DESIGN_KIND]);
     expect(doc.spec.records.map((r) => `${r.kind}/${r.id}`)).toContain("decision/ws-001");
@@ -338,3 +340,127 @@ describe("chant workspace agent: what a session reloads from (#2548)", () => {
     expect(code(doc)).toBe("agent-unknown");
   });
 });
+
+describe("principal classes a plugin defines (#3080)", () => {
+  const PLUGIN = "plugins/review";
+  const PRINCIPALS = JSON.stringify({ schema: 1, classes: [{ name: "reviewer", description: "people who review decisions", role: "reviewer" }] });
+  const REVIEWER_SCOPE = { reviewer: { members: ["design"], records: { decision: ["review"] } } };
+  let dom: string;
+  const at: Record<string, string> = {};
+
+  function domainDeclaration(scope: unknown): string {
+    return JSON.stringify({ ...JSON.parse(declaration(scope, [])), pins: [{ path: PLUGIN }] }, null, 2);
+  }
+  function commitIn(message: string, email?: string): string {
+    git(dom, "add", "-A");
+    git(dom, ...(email ? ["-c", `user.email=${email}`] : []), "commit", "-q", "-m", message);
+    return git(dom, "rev-parse", "HEAD");
+  }
+
+  beforeAll(() => {
+    const kind = readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8");
+    const schema = readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8");
+    dom = repo({
+      "chant.workspace.json": domainDeclaration(REVIEWER_SCOPE),
+      ".chant/trust.json": JSON.stringify({ schema: 1, roles: { reviewer: ["rev@example.com"] } }),
+      [`${PLUGIN}/package.json`]: JSON.stringify({ name: "review-classes", version: "1.0.0", exports: { "./workspace-principals": "./workspace-principals.json" } }),
+      [`${PLUGIN}/workspace-principals.json`]: PRINCIPALS,
+      [KIND]: kind,
+      "decisions/decision.schema.json": schema,
+      "decisions/ws-001-one.md": record(decided({ id: "ws-001", title: "One" })),
+      [DESIGN_KIND]: kind,
+      "design/decisions/decision.schema.json": schema,
+      "design/decisions/ws-001-screen.md": record(decided({ id: "ws-001", title: "Screen" })),
+      "app/server.mjs": "export const port = 8080;\n",
+      "design/spec.md": "# Spec\n",
+    });
+    at.base = commitIn("the workspace");
+    git(dom, "branch", "-M", "main");
+  });
+
+  test("writeScope takes a domain class's name as a key, in file order", () => {
+    const d = parseDeclaration(domainDeclaration({ reviewer: { records: { decision: ["review"] } }, human: {} }), "chant.workspace.json");
+    expect(Object.keys(d.writeScope!)).toEqual(["reviewer", "human"]);
+    expect(() => parseDeclaration(domainDeclaration({ "x-reviewer": {} }), "chant.workspace.json")).toThrow(WorkspaceReadError);
+    expect(() => parseDeclaration(domainDeclaration({ Reviewer: {} }), "chant.workspace.json")).toThrow(WorkspaceReadError);
+  });
+
+  test("a principal holding the class's role at base is held to its entry; anyone else is a human", async () => {
+    expect(code(await reviewRecord({ kind: KIND, id: "ws-001", verdict: "agree", by: "rev@example.com", cwd: dom, dryRun: true }))).toBeNull();
+    const proposed = await newRecord({ kind: KIND, fields: newDecision("Logs"), by: "rev@example.com", cwd: dom, dryRun: true });
+    expect(proposed).toMatchObject({ error: { code: "write-scope-kind", message: expect.stringContaining("rev@example.com (reviewer) may review decision records, and not new") } });
+    expect(code(await newRecord({ kind: KIND, fields: newDecision("Logs"), by: "lex00", cwd: dom, dryRun: true }))).toBeNull();
+  });
+
+  test("a path-pinned plugin's classes are read at base: remapping the class in the working tree changes nothing", async () => {
+    writeFiles(dom, { [`${PLUGIN}/workspace-principals.json`]: JSON.stringify({ schema: 1, classes: [{ name: "reviewer", description: "d", role: "nobody" }] }) });
+    try {
+      expect(code(await newRecord({ kind: KIND, fields: newDecision("Logs"), by: "rev@example.com", cwd: dom, dryRun: true }))).toBe("write-scope-kind");
+    } finally {
+      writeFiles(dom, { [`${PLUGIN}/workspace-principals.json`]: PRINCIPALS });
+    }
+  });
+
+  test("check --changes judges a commit by its author's domain class", async () => {
+    git(dom, "checkout", "-q", "-b", "work");
+    writeFiles(dom, { "app/server.mjs": "export const port = 9090;\n" });
+    at.outside = commitIn("app: a port", "rev@example.com");
+    writeFiles(dom, { "design/spec.md": "# Spec, reviewed\n" });
+    at.inside = commitIn("design: a note", "rev@example.com");
+    const { doc } = (await checkChanges({ cwd: dom, range: "main..work" })) as { doc: Exclude<ChangesDocument, { error: unknown }> };
+    contract(changesSchema).expectValid(doc);
+    expect(doc.scope).toMatchObject({ restricted: ["reviewer"] });
+    expect(doc.scope!.commits.map((c) => [c.commit, c.class])).toEqual([
+      [at.outside, "reviewer"],
+      [at.inside, "reviewer"],
+    ]);
+    expect(doc.scope!.findings.map((f) => [f.commit, f.code, f.path, f.class])).toEqual([[at.outside, "write-scope-member", "app/server.mjs", "reviewer"]]);
+    git(dom, "checkout", "-q", "main");
+  });
+
+  describe("a class no pinned package supplies fails closed", () => {
+    beforeAll(() => {
+      writeFiles(dom, { "chant.workspace.json": domainDeclaration({ ...REVIEWER_SCOPE, auditor: { members: ["design"] } }) });
+      at.unknown = commitIn("an auditor class no plugin supplies");
+    });
+
+    test("a writer judged human is refused; one in a known class is judged by it", async () => {
+      const refused = await newRecord({ kind: KIND, fields: newDecision("Logs"), by: "lex00", cwd: dom, dryRun: true });
+      expect(refused).toMatchObject({ error: { code: "write-scope-class-unknown", message: expect.stringContaining("writeScope.auditor") } });
+      expect(code(await newRecord({ kind: KIND, fields: newDecision("Logs"), cwd: dom, dryRun: true }))).toBe("write-scope-class-unknown");
+      expect(code(await reviewRecord({ kind: KIND, id: "ws-001", verdict: "agree", by: "rev@example.com", cwd: dom, dryRun: true }))).toBeNull();
+    });
+
+    test("check --changes reports the human's commit as a whole", async () => {
+      git(dom, "checkout", "-q", "-b", "audit");
+      writeFiles(dom, { "design/spec.md": "# Spec, by a person\n" });
+      const human = commitIn("a person's edit");
+      const { doc } = (await checkChanges({ cwd: dom, range: "main..audit" })) as { doc: Exclude<ChangesDocument, { error: unknown }> };
+      contract(changesSchema).expectValid(doc);
+      expect(doc.scope).toMatchObject({ restricted: ["reviewer", "auditor"] });
+      expect(doc.scope!.findings.map((f) => [f.id, f.path, f.class])).toEqual([[`finding:write-scope-class-unknown:${human}`, null, "human"]]);
+      git(dom, "checkout", "-q", "main");
+    });
+
+    test("workspace check reports the unknown class with WSP003", async () => {
+      const report = await runDeclarationChecks(dom, undefined, { gather: false });
+      const found = report.diagnostics.filter((d) => d.ruleId === "WSP003");
+      expect(found).toHaveLength(1);
+      expect(found[0].message).toMatch(/writeScope names the principal class auditor, which no core class or pinned package supplies/);
+      expect(found[0].message).toMatch(/known classes: human, agent, runner, service, reviewer/);
+    });
+  });
+
+  test("workspace check reports an unreadable principals file with WSP002", async () => {
+    const root = repo({
+      "chant.workspace.json": domainDeclaration(REVIEWER_SCOPE),
+      [`${PLUGIN}/package.json`]: JSON.stringify({ exports: { "./workspace-principals": "./workspace-principals.json" } }),
+      [`${PLUGIN}/workspace-principals.json`]: JSON.stringify({ schema: 1, classes: [{ name: "human", description: "d", role: "people" }] }),
+      "app/server.mjs": "",
+      "design/spec.md": "",
+    });
+    const report = await runDeclarationChecks(root, undefined, { gather: false });
+    expect(report.diagnostics.filter((d) => d.ruleId === "WSP002").map((d) => d.message)).toEqual([`${PLUGIN}: class human is a core class and can't be supplied by a package`]);
+    expect(report.diagnostics.filter((d) => d.ruleId === "WSP003").map((d) => d.message)).toEqual([expect.stringContaining("principal class reviewer")]);
+  });
+});