@intentius/chant 0.79.0 → 0.80.0

package/src/workspace/records.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json",
+  "title": "chant workspace records output",
+  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "$defs": {
+    "result": {
+      "description": "The read worked. Exit code 0, even when some records are invalid.",
+      "type": "object",
+      "required": ["$schema", "contract", "kind", "at", "current", "records", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "kind": {
+          "type": "object",
+          "required": ["name", "schema", "file"],
+          "properties": {
+            "name": { "type": "string", "description": "The kind's name, such as \"decision\"." },
+            "schema": { "type": "string", "description": "The `$id` of the schema each record was validated against." },
+            "file": { "type": "string", "description": "The kind file, relative to the repository root, with / separators." }
+          }
+        },
+        "at": {
+          "description": "The full commit id the records were read at (--at), or null for the working tree.",
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "records": {
+          "description": "One entry per file the kind locates, sorted by path.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/record" }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["total", "valid", "invalid", "superseded"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0, "description": "Entries in records." },
+            "valid": { "type": "integer", "minimum": 0 },
+            "invalid": { "type": "integer", "minimum": 0 },
+            "superseded": { "type": "integer", "minimum": 0, "description": "Records a closed record supersedes, counted before --current leaves them out." }
+          }
+        }
+      }
+    },
+    "record": {
+      "type": "object",
+      "required": ["id", "path", "state", "valid", "reasons", "supersededBy", "data"],
+      "properties": {
+        "id": { "type": ["string", "null"], "description": "Null when the front matter could not be parsed or has no string id." },
+        "path": { "type": "string", "description": "From the repository root, with / separators." },
+        "state": { "type": ["string", "null"], "description": "The state as the record writes it. Supersession is reported in supersededBy, not here." },
+        "valid": { "type": "boolean", "description": "True exactly when reasons is empty." },
+        "reasons": { "type": "array", "items": { "$ref": "#/$defs/reason" } },
+        "supersededBy": {
+          "type": ["string", "null"],
+          "description": "The id of the closed record whose supersedes link replaces this one. Derived from that record's link, never from this record's own fields."
+        },
+        "data": {
+          "type": ["object", "null"],
+          "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "valid": { "const": true } } },
+          "then": { "properties": { "reasons": { "type": "array", "maxItems": 0 }, "data": { "type": "object" }, "id": { "type": "string" } } },
+          "else": { "properties": { "reasons": { "type": "array", "minItems": 1 } } }
+        }
+      ]
+    },
+    "reason": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "enum": [
+            "record-unparseable",
+            "record-schema-invalid",
+            "record-id-duplicate",
+            "record-supersedes-unknown",
+            "record-supersedes-conflict"
+          ]
+        },
+        "message": { "type": "string" }
+      }
+    },
+    "failure": {
+      "description": "The read failed and returned no records. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": { "type": "string" }
+          }
+        },
+        "records": false
+      }
+    }
+  }
+}

package/src/workspace/records.test.ts

@@ -0,0 +1,243 @@
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { lexiconModulePath } from "../lexicon-module";
+import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
+import { loadRecordKind, parseFrontMatter, readRecords, RecordReadError, type LoadedRecordKind } from "./records";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const SAMPLE = readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8");
+
+/** A copy of a real decision with its id, state and supersedes links replaced. */
+function decision(id: string, state = "decided", supersedes: string[] = []): string {
+  const links = supersedes.length === 0 ? "supersedes: []" : `supersedes:\n${supersedes.map((d) => `  - decision: "${d}"`).join("\n")}`;
+  return SAMPLE.replace(/^id: .*$/m, `id: "${id}"`)
+    .replace(/^state: .*$/m, `state: "${state}"`)
+    .replace(/^supersedes:(?: \[\])?\n(?:  .*\n)*/m, `${links}\n`);
+}
+
+let dir: string;
+beforeEach(() => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-")));
+  mkdirSync(join(dir, "decisions"));
+  cpSync(join(DECISIONS, "decision.kind.mjs"), join(dir, "decisions", "decision.kind.mjs"));
+  cpSync(join(DECISIONS, "decision.schema.json"), join(dir, "decisions", "decision.schema.json"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function write(name: string, text: string): void {
+  writeFileSync(join(dir, "decisions", name), text);
+}
+
+async function read(options: { current?: boolean } = {}) {
+  const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+  return readRecords(loaded, { root: dir, source: workingTreeSource(dir), ...options });
+}
+
+const codes = (r: { reasons: Array<{ code: string }> }) => r.reasons.map((x) => x.code);
+
+describe("parseFrontMatter", () => {
+  test("reads the JSON subset of YAML, whatever the line endings", () => {
+    const fm = parseFrontMatter('---\r\nid: "a-001"\r\nn: 2\r\nok: true\r\nlist: []\r\n---\r\n# A\r\n');
+    expect(fm).toEqual({ ok: true, value: { id: "a-001", n: 2, ok: true, list: [] } });
+  });
+
+  test("an unquoted date stays a string", () => {
+    expect(parseFrontMatter("---\non: 2026-09-23\n---\n")).toEqual({ ok: true, value: { on: "2026-09-23" } });
+  });
+
+  test.each([
+    ["no front matter", "# Just a heading\n", /no front matter/],
+    ["an unclosed block", "---\nid: x\n", /no front matter/],
+    ["invalid YAML", "---\nid: [unclosed\n---\n", /not valid YAML/],
+    ["a duplicate key", "---\nid: a\nid: b\n---\n", /not valid YAML/],
+    ["a list at the top", "---\n- a\n---\n", /must be a mapping/],
+    ["an alias", "---\na: &x {k: 1}\nb: *x\n---\n", /aliases/],
+  ])("refuses %s", (_label, text, why) => {
+    const fm = parseFrontMatter(text);
+    expect(fm.ok).toBe(false);
+    if (!fm.ok) expect(fm.message).toMatch(why);
+  });
+});
+
+describe("readRecords", () => {
+  test("every well-formed decision is valid, in path order", async () => {
+    write("ws-002-b.md", decision("ws-002"));
+    write("ws-001-a.md", decision("ws-001"));
+    write("README.md", "# not a record\n");
+    const result = await read();
+    expect(result.records.map((r) => [r.id, r.path, r.valid, r.state])).toEqual([
+      ["ws-001", "decisions/ws-001-a.md", true, "decided"],
+      ["ws-002", "decisions/ws-002-b.md", true, "decided"],
+    ]);
+    expect(result.summary).toEqual({ total: 2, valid: 2, invalid: 0, superseded: 0 });
+    expect(result.records[0].data?.title).toBe("Seal scope");
+  });
+
+  test("a malformed file is returned with record-unparseable", async () => {
+    write("ws-001-a.md", "no front matter here\n");
+    const [r] = (await read()).records;
+    expect(r).toMatchObject({ id: null, state: null, valid: false, data: null });
+    expect(codes(r)).toEqual(["record-unparseable"]);
+  });
+
+  test("a schema violation is returned with record-schema-invalid, and keeps its data", async () => {
+    write("ws-001-a.md", decision("ws-001").replace(/^state: .*$/m, 'state: "maybe"'));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-schema-invalid"]);
+    expect(r.reasons[0].message).toMatch(/\/state/);
+    expect(r.id).toBe("ws-001");
+    expect(r.data).not.toBeNull();
+  });
+
+  test("a supersedes link to a missing id is record-supersedes-unknown", async () => {
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-404"]));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-supersedes-unknown"]);
+  });
+
+  test("a repeated id is flagged on the later file only", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    write("ws-001-b.md", decision("ws-001"));
+    const records = (await read()).records;
+    expect(records.map(codes)).toEqual([[], ["record-id-duplicate"]]);
+  });
+
+  test("supersession comes from a closed record's link, never from the old record's own state", async () => {
+    write("ws-001-a.md", decision("ws-001", "superseded"));
+    write("ws-002-b.md", decision("ws-002", "ratified"));
+    write("ws-003-c.md", decision("ws-003", "ratified"));
+    write("ws-004-d.md", decision("ws-004", "ratified", ["ws-003"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy])).toEqual([
+      ["ws-001", null],
+      ["ws-002", null],
+      ["ws-003", "ws-004"],
+      ["ws-004", null],
+    ]);
+    expect(all.summary.superseded).toBe(1);
+    const current = await read({ current: true });
+    expect(current.records.map((r) => r.id)).toEqual(["ws-001", "ws-002", "ws-004"]);
+  });
+
+  test("a link from a decided record does not supersede yet", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "decided", ["ws-001"]));
+    const current = await read({ current: true });
+    expect(current.records.map((r) => [r.id, r.valid])).toEqual([
+      ["ws-001", true],
+      ["ws-002", true],
+    ]);
+  });
+
+  test("a record superseded twice keeps the first and flags the second", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "ratified", ["ws-001"]));
+    write("ws-003-c.md", decision("ws-003", "ratified", ["ws-001"]));
+    const records = (await read()).records;
+    expect(records[0].supersededBy).toBe("ws-002");
+    expect(codes(records[2])).toEqual(["record-supersedes-conflict"]);
+  });
+
+  test("a missing records directory is location-missing", async () => {
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    const moved: LoadedRecordKind = { ...loaded, dir: join(dir, "nowhere") };
+    await expect(readRecords(moved, { root: dir, source: workingTreeSource(dir) })).rejects.toMatchObject({ code: "location-missing" });
+  });
+});
+
+describe("loadRecordKind", () => {
+  const load = () => loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+
+  test("the chant repo's decision kind loads with its schema", async () => {
+    const loaded = await loadRecordKind(join(DECISIONS, "decision.kind.mjs"));
+    expect(loaded.kind.name).toBe("decision");
+    expect(loaded.schema.$id).toBe("urn:intentius:chant:decision:1");
+    expect(loaded.dir).toBe(DECISIONS);
+  });
+
+  test("loads through the #2520 path loader and leaves nothing registered", async () => {
+    const file = join(DECISIONS, "decision.kind.mjs");
+    await loadRecordKind(file);
+    expect(lexiconModulePath(`record-kind:${file}`)).toBeUndefined();
+  });
+
+  test("a missing file is kind-unreadable", async () => {
+    await expect(loadRecordKind(join(dir, "none.kind.ts"))).rejects.toMatchObject({ code: "kind-unreadable" });
+  });
+
+  test("a module with no recordKind is kind-invalid", async () => {
+    writeFileSync(join(dir, "decisions", "decision.kind.mjs"), "export const other = 1;\n");
+    await expect(load()).rejects.toMatchObject({ code: "kind-invalid" });
+  });
+
+  test("an unknown field or a closed state outside states is kind-invalid", async () => {
+    const text = readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8");
+    writeFileSync(join(dir, "decisions", "decision.kind.mjs"), text.replace('closedStates: ["ratified", "superseded"]', 'closedStates: ["sealed"]'));
+    await expect(load()).rejects.toMatchObject({ code: "kind-invalid" });
+  });
+
+  test("a schema whose $id differs is schema-id-mismatch", async () => {
+    const schema = JSON.parse(readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"));
+    writeFileSync(join(dir, "decisions", "decision.schema.json"), JSON.stringify({ ...schema, $id: "urn:other" }));
+    await expect(load()).rejects.toMatchObject({ code: "schema-id-mismatch" });
+  });
+
+  test("an unreadable schema is schema-unreadable", async () => {
+    writeFileSync(join(dir, "decisions", "decision.schema.json"), "{ not json");
+    await expect(load()).rejects.toBeInstanceOf(RecordReadError);
+    await expect(load()).rejects.toMatchObject({ code: "schema-unreadable" });
+  });
+});
+
+describe("reading at a revision", () => {
+  const git = (...args: string[]) =>
+    execFileSync("git", args, {
+      cwd: dir,
+      encoding: "utf-8",
+      env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.com", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.com" },
+    }).trim();
+
+  test("reads the committed files, not the working tree", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    git("init", "-q", "-b", "main");
+    git("add", "-A");
+    git("commit", "-q", "-m", "one");
+    const first = git("rev-parse", "HEAD");
+    write("ws-002-b.md", decision("ws-002"));
+    write("ws-001-a.md", "broken now\n");
+
+    expect(gitRoot(join(dir, "decisions"))).toBe(dir);
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    const at = await readRecords(loaded, { root: dir, source: gitRevisionSource(dir, resolveRevision(dir, "main")) });
+    expect(at.records.map((r) => [r.id, r.valid])).toEqual([["ws-001", true]]);
+    expect(resolveRevision(dir, first.slice(0, 8))).toBe(first);
+
+    const tree = await readRecords(loaded, { root: dir, source: workingTreeSource(dir) });
+    expect(tree.records.map((r) => [r.path, r.valid])).toEqual([
+      ["decisions/ws-001-a.md", false],
+      ["decisions/ws-002-b.md", true],
+    ]);
+  });
+
+  test("an unknown revision is revision-unknown, and a directory missing at the revision is location-missing", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    writeFileSync(join(dir, "other.txt"), "x\n");
+    git("init", "-q", "-b", "main");
+    git("add", "other.txt");
+    git("commit", "-q", "-m", "no records yet");
+    expect(() => resolveRevision(dir, "no-such-ref")).toThrow(expect.objectContaining({ code: "revision-unknown" }));
+    expect(() => resolveRevision(dir, "--all")).toThrow(expect.objectContaining({ code: "revision-unknown" }));
+    const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
+    await expect(
+      readRecords(loaded, { root: dir, source: gitRevisionSource(dir, resolveRevision(dir, "HEAD")) }),
+    ).rejects.toMatchObject({ code: "location-missing" });
+  });
+
+  test("outside a repository there is no git root", () => {
+    expect(gitRoot(dir)).toBeUndefined();
+  });
+});