@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/record-sessions.js

@@ -0,0 +1,96 @@
+/**
+ * Review sessions (#2673, #2650 C10): a record kind whose records are the
+ * sessions a group reviewed records in. A session kind names, in its
+ * `session` declaration, the list of verdicts a session produced, the field
+ * that seals it once closed, and the kind file of the records its verdicts
+ * name (the subjects, such as decisions).
+ *
+ * On read, a closed session's seal has to match its text
+ * (`session-seal-mismatch`), and each verdict has to name a subject record
+ * that exists (`session-verdict-unknown-record`). Each session also lists the
+ * subjects' review entries that name it in their `session` field, as
+ * `citedBy`. This module only reads; nothing here writes a seal into a file.
+ */
+import { recordSeal, sessionSubjectKinds } from "./records.js";
+/**
+ * The seal of a session record: {@link recordSeal} with the seal field, the
+ * whole-file JCS/SHA-256 every closed record of a sealed kind carries
+ * (#2546, ws-063). Until #2546 it was the SHA-256 of the file's text without
+ * the seal line; a session sealed by that rule holds a bare hex value and
+ * reads as `session-seal-mismatch` now. Null when the front matter can't be
+ * parsed.
+ */
+export function sessionSeal(text, field, format = "markdown-front-matter") {
+    return recordSeal(text, field, format);
+}
+/**
+ * Check each session in `entries` against its seal and the subject records,
+ * and fill in `citedBy`. `texts` holds each entry's file text by path.
+ * `subjects` holds the records of each subject kind and the name of their
+ * reviews list; it is null when they were not read, and then no verdict is
+ * checked.
+ */
+export function joinSessions(kind, entries, texts, subjects) {
+    const decl = kind.session;
+    if (!decl)
+        return;
+    const closed = new Set(kind.closedStates);
+    const subjectIds = new Set((subjects ?? []).flatMap((k) => k.records.map((s) => s.id)).filter((id) => id !== null));
+    const citations = new Map();
+    for (const { s, reviewsField } of (subjects ?? []).flatMap((k) => k.records.map((s) => ({ s, reviewsField: k.reviews })))) {
+        if (s.id === null)
+            continue;
+        const reviews = s.data?.[reviewsField];
+        if (!Array.isArray(reviews))
+            continue;
+        reviews.forEach((r, index) => {
+            if (r === null || typeof r !== "object")
+                return;
+            const entry = r;
+            if (typeof entry.session !== "string")
+                return;
+            const list = citations.get(entry.session) ?? [];
+            list.push({
+                id: s.id,
+                path: s.path,
+                index,
+                reviewer: typeof entry.reviewer === "string" ? entry.reviewer : null,
+                verdict: typeof entry.verdict === "string" ? entry.verdict : null,
+            });
+            citations.set(entry.session, list);
+        });
+    }
+    for (const e of entries) {
+        e.citedBy = e.id === null ? [] : (citations.get(e.id) ?? []);
+        if (e.data === null)
+            continue;
+        if (e.state !== null && closed.has(e.state)) {
+            const seal = e.data[decl.seal];
+            const text = texts.get(e.path);
+            if (typeof seal === "string" && text !== undefined) {
+                const actual = sessionSeal(text, decl.seal, kind.format);
+                if (actual !== seal) {
+                    e.reasons.push({
+                        code: "session-seal-mismatch",
+                        message: /^[0-9a-f]{64}$/.test(seal)
+                            ? `${decl.seal} is ${seal}, a seal by the text rule chant used before #2546, and the session seals to ${actual} now: seal it again by hand, since a closed session is never rewritten by chant`
+                            : `${decl.seal} is ${seal}, but the session seals to ${actual}: the session changed after it closed`,
+                    });
+                }
+            }
+        }
+        if (subjects === null)
+            continue;
+        const verdicts = e.data[decl.verdicts];
+        if (!Array.isArray(verdicts))
+            continue;
+        verdicts.forEach((v, i) => {
+            if (v === null || typeof v !== "object")
+                return;
+            const record = v.record;
+            if (typeof record === "string" && !subjectIds.has(record)) {
+                e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${sessionSubjectKinds(decl).join(" or ")} record has` });
+            }
+        });
+    }
+}

package/dist/workspace/record-source.js

@@ -0,0 +1,114 @@
+/**
+ * Where records are read from: the working tree, or a commit's git objects
+ * (`--at <rev>`, #2536). Reading at a revision needs no checkout and no
+ * network; it asks the local git object store only.
+ */
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { RecordReadError } from "./records.js";
+/** Records in the working tree under `root`. */
+export function workingTreeSource(root) {
+    return {
+        label: "",
+        list(dir) {
+            try {
+                return readdirSync(join(root, dir), { withFileTypes: true })
+                    .filter((d) => d.isFile())
+                    .map((d) => d.name);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        read(path) {
+            return readFileSync(join(root, path), "utf-8");
+        },
+        bytes(path) {
+            return readFileSync(join(root, path));
+        },
+    };
+}
+function git(cwd, args, input) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        input,
+        stdio: ["pipe", "pipe", "pipe"],
+        maxBuffer: 256 * 1024 * 1024,
+    });
+}
+/** The top of the git repository holding `cwd`, or undefined outside one. */
+export function gitRoot(cwd) {
+    try {
+        return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The full commit id `rev` names in the repository at `root`. */
+export function resolveRevision(root, rev) {
+    if (rev.startsWith("-"))
+        throw new RecordReadError("revision-unknown", `--at ${rev} is not a revision`);
+    try {
+        return git(root, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim();
+    }
+    catch {
+        throw new RecordReadError("revision-unknown", `--at ${rev} names no commit in this repository`);
+    }
+}
+/** Records as they were at `commit`, read from the object store of the repository at `root`. */
+export function gitRevisionSource(root, commit) {
+    const blobs = new Map();
+    const blob = (path) => {
+        const bytes = blobs.get(path);
+        if (bytes === undefined)
+            throw new Error(`${path} was not listed at ${commit}`);
+        return bytes;
+    };
+    return {
+        label: ` at ${commit.slice(0, 8)}`,
+        list(dir) {
+            const treeish = dir === "." ? `${commit}^{tree}` : `${commit}:${dir}`;
+            try {
+                if (git(root, ["cat-file", "-t", treeish]).trim() !== "tree")
+                    return undefined;
+            }
+            catch {
+                return undefined;
+            }
+            const entries = git(root, ["ls-tree", "-z", treeish])
+                .split("\0")
+                .filter(Boolean)
+                .map((line) => {
+                const tab = line.indexOf("\t");
+                const [, type, oid] = line.slice(0, tab).split(" ");
+                return { type, oid, name: line.slice(tab + 1) };
+            })
+                .filter((e) => e.type === "blob");
+            // One `cat-file --batch` for the whole directory: records are small, and
+            // one process beats one per file.
+            if (entries.length > 0) {
+                const out = Buffer.from(execFileSync("git", ["cat-file", "--batch"], {
+                    cwd: root,
+                    input: entries.map((e) => e.oid).join("\n") + "\n",
+                    maxBuffer: 256 * 1024 * 1024,
+                }));
+                let at = 0;
+                for (const e of entries) {
+                    const nl = out.indexOf(0x0a, at);
+                    const size = Number(out.subarray(at, nl).toString("utf-8").split(" ")[2]);
+                    const start = nl + 1;
+                    blobs.set(dir === "." ? e.name : `${dir}/${e.name}`, out.subarray(start, start + size));
+                    at = start + size + 1;
+                }
+            }
+            return entries.map((e) => e.name);
+        },
+        read(path) {
+            return blob(path).toString("utf-8");
+        },
+        bytes: blob,
+    };
+}

package/dist/workspace/records-amend.schema.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records-amend/v1/records-amend.schema.json",
+  "title": "chant workspace records amend output",
+  "description": "What `chant workspace records amend <id> --kind <kind file> --set <file|->` prints (#2670): the record's path and id and the top-level fields the amendment changed, or the reason it wrote nothing. Version 1 of the write contract for records. The command writes one file or none and never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.86.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was written, or would be with --dry-run. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "kind",
+        "path",
+        "id",
+        "changed",
+        "dryRun",
+        "warnings"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-amend/v1/records-amend.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 the record was validated against."
+            },
+            "file": {
+              "type": "string",
+              "description": "The kind file, relative to the repository root, with / separators."
+            }
+          }
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, relative to the repository root (the working directory outside git), with / separators."
+        },
+        "id": {
+          "type": "string",
+          "description": "The record's id."
+        },
+        "changed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The top-level fields whose value differs from the record as it was, in the record's order, with seal last when the author seal was written or removed (#2688). Empty when the fields set change nothing, and then nothing is written."
+        },
+        "seal": {
+          "type": "object",
+          "description": "Added in contract 1 by #2688. With --sign only: the author seal written into the record's top-level seal field, an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<author>\\n<state>, in the ssh-keygen namespace chant-record. The author is the kind's reviews.decider field (decided_by for decisions), and the digest is the record's digest by the digest rule, which leaves the seal field out. The write does not check the key against the signers file; chant workspace records reports whether the seal verifies.",
+          "required": [
+            "signer",
+            "key",
+            "signature"
+          ],
+          "properties": {
+            "signer": {
+              "type": "string",
+              "description": "The record's author, as its reviews.decider field names them."
+            },
+            "key": {
+              "type": "string",
+              "pattern": "^SHA256:[A-Za-z0-9+/]+=*$",
+              "description": "The fingerprint of the key that signed, read back from the signature."
+            },
+            "signature": {
+              "type": "string",
+              "description": "The armored ssh signature."
+            }
+          }
+        },
+        "sealDropped": {
+          "type": "string",
+          "description": "Added in contract 1 by #2688. Present when the record carried an author seal, the amendment moved its digest and --sign was not given: the seal no longer covers the text, so it was removed, and this says so. changed then lists seal."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given and nothing was written."
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The written record's warnings, as chant workspace records reports them. A warning never refuses a write.",
+          "items": {
+            "$ref": "#/$defs/warning"
+          }
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Added in contract 1 by #3173. The record's digest after the write, as chant workspace records --json reports it (with --dry-run, the digest it would have). Pass it as --expect to the next amend, review or close of the record, so that write is refused with record-conflict if someone else wrote the record in between."
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run only: the whole text of the file the command would write."
+        },
+        "error": false
+      }
+    },
+    "warning": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "asset-drift",
+            "asset-missing",
+            "asset-stale",
+            "record-supersedes-pending",
+            "record-no-evidence",
+            "review-undigested",
+            "source-transcript-drift"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/records-amend/v1/records-amend.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",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "record-not-found",
+                "amend-id-immutable",
+                "record-closed",
+                "amend-supersede-instead",
+                "record-sign-failed",
+                "ratify-quorum-not-met",
+                "record-conflict",
+                "write-lock-timeout",
+                "write-lock-not-held",
+                "write-scope-member",
+                "write-scope-kind",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "record-remediates-unknown",
+                "record-remediates-not-closed",
+                "record-seal-mismatch",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "What was wrong, and what to do instead when there is something, such as writing a new record that supersedes this one."
+            }
+          }
+        },
+        "conflict": {
+          "type": "object",
+          "description": "Added in contract 1 by #3173. With record-conflict only: the record as it is now. Re-read it, and write again with --expect set to digest if the change still stands.",
+          "required": [
+            "id",
+            "path",
+            "expected",
+            "digest",
+            "lastWrite"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "expected": {
+              "type": "string",
+              "description": "The digest given with --expect."
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The record's digest now."
+            },
+            "lastWrite": {
+              "description": "The last chant write of the record file, from the write journal in the git directory, while the file still holds the text it left; null when the journal does not know it.",
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "verb",
+                    "by",
+                    "agent",
+                    "at"
+                  ],
+                  "properties": {
+                    "verb": {
+                      "type": "string",
+                      "description": "The write command, such as records amend or points answer."
+                    },
+                    "by": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The principal the write named, or null when it named none."
+                    },
+                    "agent": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "description": "The agent session it was made in (CHANT_AGENT), or null."
+                    },
+                    "at": {
+                      "type": "string",
+                      "description": "When, as an ISO 8601 time."
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}

package/dist/workspace/records-checkout.js

@@ -0,0 +1,76 @@
+/**
+ * The checkout a working-tree read is made in, and which records in it are
+ * uncommitted (#3160).
+ *
+ * Work in progress lives as uncommitted files in a work branch's working tree
+ * (#3158, #3145). A reader such as hud or studio shows "kept, not yet
+ * applied" from `records --json` alone: each record says whether it is
+ * committed, modified or new against `HEAD`, and the document names the
+ * branch, the commit `HEAD` names and the base that branch forked from. The
+ * reader never diffs git itself.
+ *
+ * Every git call here reads. None takes the index lock or refreshes the
+ * index (`--no-optional-locks`), so a read leaves the checkout as it was,
+ * `.git` included, which the reader conformance suite checks.
+ */
+import { execFileSync } from "node:child_process";
+import { resolveBase } from "./trust/provenance.js";
+function git(top, args) {
+    return execFileSync("git", ["--no-optional-locks", "--literal-pathspecs", ...args], {
+        cwd: top,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 256 * 1024 * 1024,
+    });
+}
+function tryGit(top, args) {
+    try {
+        return git(top, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The branch, head and base of the checkout at `top`. `explicitBase` is
+ * `--base`, as the trust policy takes it; otherwise the target branch is the
+ * one the policy is read at (`origin/HEAD`, then `main`, then `master`).
+ */
+export function readCheckoutHead(top, explicitBase) {
+    const branch = tryGit(top, ["symbolic-ref", "--quiet", "--short", "HEAD"])?.trim() || null;
+    const head = tryGit(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])?.trim() || null;
+    const target = resolveBase(top, explicitBase);
+    const base = head && target.commit ? tryGit(top, ["merge-base", head, target.commit])?.trim() || null : null;
+    return { branch, head, base, baseFrom: target.from };
+}
+/** NUL-separated git output as a list. */
+function zList(out) {
+    return (out ?? "").split("\0").filter(Boolean);
+}
+/**
+ * Each of `paths` (record files directly in `dir`, from the repository root)
+ * as committed, modified or new against `head`, and the files directly in
+ * `dir` at `head` whose names `match` and that `paths` leaves out: the
+ * records deleted in the working tree. With no head every path is new.
+ *
+ * Staged and unstaged changes count alike: anything `HEAD` does not hold is
+ * uncommitted. A rename is a new record and a deleted one.
+ */
+export function worktreeStates(top, head, dir, paths, match) {
+    const states = new Map();
+    if (head === null) {
+        for (const p of paths)
+            states.set(p, "new");
+        return { states, deleted: [] };
+    }
+    const prefix = dir === "." ? "" : `${dir}/`;
+    const direct = (p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/");
+    const spec = dir === "." ? "." : dir;
+    const atHead = new Set(zList(tryGit(top, ["ls-tree", "-r", "-z", "--name-only", head, "--", spec])).filter(direct));
+    const changed = new Set(zList(tryGit(top, ["diff", "--name-only", "-z", "--no-renames", head, "--", spec])));
+    for (const p of paths)
+        states.set(p, !atHead.has(p) ? "new" : changed.has(p) ? "modified" : "committed");
+    const present = new Set(paths);
+    const deleted = [...atHead].filter((p) => !present.has(p) && match.test(p.slice(prefix.length))).sort();
+    return { states, deleted };
+}