@intentius/chant 0.84.0 → 0.86.0

package/src/workspace/record-sessions.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 { recordTextDigest, type RecordEntry, type RecordFormat, type RecordKind } from "./records";
+
+/** A subject record's review entry that names a session in its `session` field. */
+export interface SessionCitation {
+  /** The subject record's id. */
+  id: string;
+  /** The subject record's path, from the repository root. */
+  path: string;
+  /** The entry's position in the subject's reviews list, from 0. */
+  index: number;
+  /** The reviewer as the entry writes it, or null when it names none. */
+  reviewer: string | null;
+  /** The verdict as the entry writes it, or null when it names none. */
+  verdict: string | null;
+}
+
+/**
+ * The seal of a session record: {@link recordTextDigest} with the seal field
+ * in place of the reviews list. That is the lowercase hex SHA-256 of the
+ * file's text with LF line endings and without the front-matter line that
+ * holds the seal, a quoted string on one line. Every other byte, the `---`
+ * lines and the body included, is kept.
+ *
+ * `awk 'NR==1&&/^---$/{f=1;print;next} f&&/^---$/{f=0} f&&/^closed_digest:/{next} {print}' S-0001.md | shasum -a 256`
+ * gives the same value for a file with LF line endings that ends in one.
+ * For a session kind of format json (ws-053), the seal member is removed by
+ * the JSON rule of {@link recordTextDigest} instead.
+ */
+export function sessionSeal(text: string, field: string, format: RecordFormat = "markdown-front-matter"): string {
+  return recordTextDigest(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 subject records 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: RecordKind, entries: RecordEntry[], texts: Map<string, string>, subjects: { records: RecordEntry[]; reviews: string } | null): void {
+  const decl = kind.session;
+  if (!decl) return;
+  const closed = new Set(kind.closedStates);
+  const subjectIds = new Set(subjects?.records.map((s) => s.id).filter((id): id is string => id !== null) ?? []);
+  const citations = new Map<string, SessionCitation[]>();
+  for (const s of subjects?.records ?? []) {
+    if (s.id === null) continue;
+    const reviews = s.data?.[subjects!.reviews];
+    if (!Array.isArray(reviews)) continue;
+    reviews.forEach((r, index) => {
+      if (r === null || typeof r !== "object") return;
+      const entry = r as Record<string, unknown>;
+      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: `${decl.seal} is ${seal}, but the text hashes 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 as Record<string, unknown>).record;
+      if (typeof record === "string" && !subjectIds.has(record)) {
+        e.reasons.push({ code: "session-verdict-unknown-record", message: `${decl.verdicts}[${i}] names ${record}, which no ${decl.subjects.kind} record has` });
+      }
+    });
+  }
+}

package/src/workspace/record-source.ts

@@ -16,6 +16,8 @@ export interface RecordSource {
   list(dir: string): string[] | undefined;
   /** The text of a file listed by `list`. */
   read(path: string): string;
+  /** The bytes of a file listed by `list`, for a content-addressed id (ws-053). */
+  bytes(path: string): Uint8Array;
 }
 
 /** Records in the working tree under `root`. */
@@ -34,6 +36,9 @@ export function workingTreeSource(root: string): RecordSource {
     read(path) {
       return readFileSync(join(root, path), "utf-8");
     },
+    bytes(path) {
+      return readFileSync(join(root, path));
+    },
   };
 }
 
@@ -68,7 +73,12 @@ export function resolveRevision(root: string, rev: string): string {
 
 /** Records as they were at `commit`, read from the object store of the repository at `root`. */
 export function gitRevisionSource(root: string, commit: string): RecordSource {
-  const blobs = new Map<string, string>();
+  const blobs = new Map<string, Buffer>();
+  const blob = (path: string): Buffer => {
+    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) {
@@ -102,16 +112,15 @@ export function gitRevisionSource(root: string, commit: string): RecordSource {
           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).toString("utf-8"));
+          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) {
-      const text = blobs.get(path);
-      if (text === undefined) throw new Error(`${path} was not listed at ${commit}`);
-      return text;
+      return blob(path).toString("utf-8");
     },
+    bytes: blob,
   };
 }

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

@@ -0,0 +1,167 @@
+{
+  "$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. Empty when the fields set change nothing, and then nothing is written."
+        },
+        "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"
+          }
+        },
+        "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"
+          ]
+        },
+        "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-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "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."
+            }
+          }
+        },
+        "path": false
+      }
+    }
+  }
+}