@intentius/chant 0.81.0 → 0.83.0

package/src/workspace/records.ts

@@ -22,7 +22,9 @@ import yaml from "js-yaml";
 import { z } from "zod";
 import { importLexiconModule, registerLexiconDeclarations } from "../lexicon-module";
 import type { ReasonCode } from "./reason-codes";
+import { checkPins, pinEntries, type AssetPin } from "./record-assets";
 import type { RecordSource } from "./record-source";
+import type { WorkspaceTree } from "./tree";
 
 // ── Reason codes ─────────────────────────────────────────────────────────────
 
@@ -44,6 +46,30 @@ export const RECORD_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type RecordReasonCode = (typeof RECORD_REASON_CODES)[number];
 
+/**
+ * Why a record carries a warning. Closed, like the reason codes. A warning
+ * never makes a record invalid, and `--current` still lists the record.
+ */
+export const RECORD_WARNING_CODES = [
+  /** A pinned file's bytes no longer hash to the pinned sha256 (#2549). */
+  "asset-drift",
+  /** A pinned file does not exist in the tree read (#2549). */
+  "asset-missing",
+  /**
+   * A pinned file is unchanged since a record this one supersedes pinned it at
+   * the same hash: the decision changed and the artifact did not follow (#2549).
+   */
+  "asset-stale",
+  /** A supersedes link from a record whose state is weaker than the one it names, so it has no effect yet (#2524 D4). */
+  "record-supersedes-pending",
+] as const satisfies readonly ReasonCode[];
+export type RecordWarningCode = (typeof RECORD_WARNING_CODES)[number];
+
+export interface RecordWarning {
+  code: RecordWarningCode;
+  message: string;
+}
+
 /**
  * Why the read as a whole failed. Also closed. The command exits 1 with one of
  * these and returns no records.
@@ -114,11 +140,34 @@ export const recordKindSchema = z
     closedStates: z.array(z.string().min(1)),
     /** The front-matter list of links to superseded records, and the key in each entry that holds the target id. */
     supersedes: z.object({ field: z.string().min(1), key: z.string().min(1) }).strict(),
+    /**
+     * How strongly each state is approved (#2524 D4). With it, a supersedes
+     * link takes effect when the new record's rank is above 0 and at least the
+     * old record's, "under an equal or stricter approval rule". A state it
+     * leaves out ranks 0. Without it, a link takes effect only from a record
+     * in a closed state.
+     */
+    approval: z.record(z.string(), z.number().int().min(0)).optional(),
+    /**
+     * The front-matter list whose entries may pin a workspace file, as
+     * `{path, sha256}` (#2549). Optional: a kind without it pins nothing.
+     */
+    pins: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter list of what a record governs. Its `member:<name>` and
+     * `path:<path>` entries are the record's links in `chant workspace graph`
+     * (#2549). Optional.
+     */
+    constrains: z.object({ field: z.string().min(1) }).strict().optional(),
   })
   .strict()
   .refine((k) => k.closedStates.every((s) => k.states.includes(s)), {
     message: "every closed state must be listed in states",
     path: ["closedStates"],
+  })
+  .refine((k) => Object.keys(k.approval ?? {}).every((s) => k.states.includes(s)), {
+    message: "every state approval ranks must be listed in states",
+    path: ["approval"],
   });
 
 export type RecordKind = z.infer<typeof recordKindSchema>;
@@ -255,6 +304,10 @@ export interface RecordEntry {
   supersededBy: string | null;
   /** The front matter as JSON, or null when it could not be parsed. */
   data: Record<string, unknown> | null;
+  /** Each workspace file the record pins, checked against the tree read (#2549). Empty when nothing was checked. */
+  assets: AssetPin[];
+  /** Findings that leave the record valid, such as a pinned file that changed (#2549). */
+  warnings: RecordWarning[];
 }
 
 export interface ReadRecordsOptions {
@@ -263,6 +316,25 @@ export interface ReadRecordsOptions {
   source: RecordSource;
   /** Leave out records a closed record supersedes. */
   current?: boolean;
+  /**
+   * The workspace root the kind's pins resolve in: the working tree, or the
+   * revision read (#2549). Without it no pin is checked.
+   */
+  assets?: WorkspaceTree;
+  /**
+   * When files last changed and records were recorded, in the history of the
+   * revision read, for `asset-stale` (#2549). Without it only the hashes are
+   * compared.
+   */
+  history?: RecordHistory;
+}
+
+/** Commit times, in seconds since the epoch, read from git. */
+export interface RecordHistory {
+  /** The last commit that changed `path` (from the workspace root), or null when unknown. */
+  fileChanged(path: string): number | null;
+  /** The commit that added the record at `path` (from the repository root), or null when it is not committed. */
+  recorded(path: string): number | null;
 }
 
 export interface ReadRecordsResult {
@@ -304,7 +376,7 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   const entries: RecordEntry[] = [];
   for (const name of names.filter((n) => match.test(n)).sort()) {
     const path = dirRel === "." ? name : `${dirRel}/${name}`;
-    const entry: RecordEntry = { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, data: null };
+    const entry: RecordEntry = { id: null, path, state: null, valid: true, reasons: [], supersededBy: null, data: null, assets: [], warnings: [] };
     entries.push(entry);
     const fm = parseFrontMatter(options.source.read(path));
     if (!fm.ok) {
@@ -320,6 +392,11 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     if (!result.ok) {
       entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
     }
+    if (kind.pins && options.assets) {
+      const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
+      entry.assets = checked.assets;
+      entry.warnings = checked.warnings;
+    }
   }
 
   // Ids: the first file in path order keeps an id; later ones are flagged.
@@ -332,10 +409,14 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
   }
 
   // Supersession comes from the new record's links, never from the old record.
-  // A link takes effect only from a closed record (#2555: a later ratified
-  // decision replaces an earlier one), and a record is superseded at most once
-  // (#2524 D4).
+  // With approval ranks, a link takes effect under an equal or stricter
+  // approval rule: from a record ranked above 0 and at least as high as the
+  // one it names (#2524 D4). Without them, only from a closed record (#2555).
+  // A record is superseded at most once.
   const closed = new Set(kind.closedStates);
+  const rank = (state: string | null): number => (state === null ? 0 : (kind.approval?.[state] ?? 0));
+  const takesEffect = (from: RecordEntry, to: RecordEntry): boolean =>
+    kind.approval ? rank(from.state) > 0 && rank(from.state) >= rank(to.state) : from.state !== null && closed.has(from.state);
   for (const e of entries) {
     const links = e.data?.[kind.supersedes.field];
     if (!Array.isArray(links)) continue;
@@ -348,7 +429,16 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
         e.reasons.push({ code: "record-supersedes-unknown", message: `supersedes ${target}, which no record has` });
         continue;
       }
-      if (e.state === null || !closed.has(e.state) || old === e) continue;
+      if (old === e) continue;
+      if (!takesEffect(e, old)) {
+        if (kind.approval) {
+          e.warnings.push({
+            code: "record-supersedes-pending",
+            message: `supersedes ${target}, which is ${old.state ?? "stateless"}; a ${e.state ?? "stateless"} record can't supersede it, so the link takes effect once this record is approved at least as strongly`,
+          });
+        }
+        continue;
+      }
       if (old.supersededBy !== null && old.supersededBy !== e.id) {
         e.reasons.push({
           code: "record-supersedes-conflict",
@@ -360,6 +450,26 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     }
   }
 
+  // A pin that still matches, at the hash a record this one supersedes
+  // pinned, while the file has not changed since this record was recorded:
+  // the decision moved on and the artifact did not (#2549).
+  for (const e of entries) {
+    for (const a of e.assets) {
+      if (a.state !== "pinned") continue;
+      const old = entries.find((o) => o.supersededBy !== null && o.supersededBy === e.id && o.assets.some((p) => p.path === a.path && p.sha256 === a.sha256));
+      if (!old) continue;
+      const changed = options.history?.fileChanged(a.path) ?? null;
+      const recorded = options.history ? options.history.recorded(e.path) : null;
+      // A record not yet committed is recorded now, after every commit.
+      if (changed !== null && recorded !== null && changed > recorded) continue;
+      a.state = "stale";
+      e.warnings.push({
+        code: "asset-stale",
+        message: `${a.path} is pinned at the hash ${old.id} pinned, and it has not changed since: ${e.id} supersedes ${old.id}, and the artifact did not follow`,
+      });
+    }
+  }
+
   for (const e of entries) e.valid = e.reasons.length === 0;
   const records = options.current ? entries.filter((e) => e.supersededBy === null) : entries;
   return {

package/src/workspace/template-pins.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Re-pinning records after template substitution (#2549): a pin that held in
+ * the template follows the substituted file, one that didn't stays, and the
+ * rest of the record is kept byte for byte.
+ */
+
+import { createHash } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { repinSubstituted } from "./template-pins";
+
+const sha = (s: string) => createHash("sha256").update(s).digest("hex");
+const buf = (s: string) => Buffer.from(s, "utf-8");
+
+function record(pins: [string, string][]): string {
+  const evidence = pins.map(([path, hash]) => `  - title: "t"\n    path: "${path}"\n    sha256: "${hash}"\n`).join("");
+  return `---\nschema: 1\nid: "ref-002"\nevidence:\n  - title: "a link"\n    url: "https://example.com"\n${evidence}constrains:\n  - "member:design"\n---\n\n# Body mentions ${pins[0]?.[1] ?? ""}\n`;
+}
+
+describe("repinSubstituted", () => {
+  const before = "title {{chant:name}}\n";
+  const after = "title Acme\n";
+  const other = "unchanged\n";
+
+  test("a pin that held on a substituted file gets the new hash; nothing else in the file changes", () => {
+    const text = record([["design/home.json", sha(before)], ["design/other.json", sha(other)]]);
+    const original = new Map([
+      ["chant.workspace.json", buf("{}")],
+      ["design/home.json", buf(before)],
+      ["design/other.json", buf(other)],
+      ["decisions/ref-002-x.md", buf(text)],
+    ]);
+    const substituted = new Map(original).set("design/home.json", buf(after));
+    const { files, repinned } = repinSubstituted(original, substituted, ["design/home.json"]);
+    expect(repinned).toEqual([{ record: "decisions/ref-002-x.md", paths: ["design/home.json"] }]);
+    const expected = text.replace(`    sha256: "${sha(before)}"`, `    sha256: "${sha(after)}"`);
+    expect(files.get("decisions/ref-002-x.md")!.toString("utf-8")).toBe(expected);
+    // The body's copy of the old hash is not front matter, so it stays.
+    expect(expected).toContain(`# Body mentions ${sha(before)}`);
+  });
+
+  test("a pin that was already drifted in the template stays drifted", () => {
+    const text = record([["design/home.json", sha("something else")]]);
+    const original = new Map([
+      ["design/home.json", buf(before)],
+      ["decisions/ref-002-x.md", buf(text)],
+    ]);
+    const substituted = new Map(original).set("design/home.json", buf(after));
+    const { files, repinned } = repinSubstituted(original, substituted, ["design/home.json"]);
+    expect(repinned).toEqual([]);
+    expect(files.get("decisions/ref-002-x.md")!.toString("utf-8")).toBe(text);
+  });
+
+  test("paths resolve from the workspace declaration nearest above the record", () => {
+    const text = record([["design/home.json", sha(before)]]);
+    const original = new Map([
+      ["ws/chant.workspace.json", buf("{}")],
+      ["ws/design/home.json", buf(before)],
+      ["ws/decisions/ref-002-x.md", buf(text)],
+    ]);
+    const substituted = new Map(original).set("ws/design/home.json", buf(after));
+    const { repinned } = repinSubstituted(original, substituted, ["ws/design/home.json"]);
+    expect(repinned).toEqual([{ record: "ws/decisions/ref-002-x.md", paths: ["design/home.json"] }]);
+  });
+
+  test("nothing substituted, nothing re-pinned", () => {
+    const original = new Map([["decisions/ref-002-x.md", buf(record([["design/home.json", sha(before)]]))]]);
+    expect(repinSubstituted(original, original, []).repinned).toEqual([]);
+  });
+});

package/src/workspace/template-pins.ts

@@ -0,0 +1,117 @@
+/**
+ * Re-pinning records after template parameters are substituted (#2549, #2627).
+ *
+ * A template's decision records may pin a file of the template by hash. When
+ * `chant init --from` or `chant workspace upgrade` fills that file's
+ * `{{chant:<name>}}` placeholders, the copy's bytes differ from the
+ * template's, and every copy would report the pin as drifted on day one. So
+ * after substitution, each pin that held in the template and names a
+ * substituted file gets the hash of the substituted content.
+ *
+ * A record is any Markdown file whose front matter has an `evidence` list
+ * with path pins. Its paths resolve from the nearest directory above it that
+ * holds a workspace declaration, as `chant workspace records` resolves them.
+ * A pin that did not hold in the template stays as it is: re-pinning follows
+ * the substitution and never hides drift the template already had. Only the
+ * `sha256` value on the pin's line changes; the rest of the file is kept byte
+ * for byte.
+ */
+
+import { sha256Hex } from "../content-digest";
+import { pinEntries } from "./record-assets";
+import { parseFrontMatter } from "./records";
+
+const DECLARATIONS = ["chant.workspace.json", "chant.workspace.jsonc"];
+const EVIDENCE = "evidence";
+
+/** A record whose pins were rewritten: its path in the template, and the pinned paths, from its workspace root. */
+export interface RepinnedRecord {
+  record: string;
+  paths: string[];
+}
+
+const dirOf = (path: string) => (path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "");
+
+/** The nearest directory at or above `dir` holding a workspace declaration in `files`, or "" for the root. */
+function workspaceRootOf(files: ReadonlyMap<string, Buffer>, dir: string): string {
+  for (let d = dir; ; d = dirOf(d)) {
+    if (DECLARATIONS.some((name) => files.has(d === "" ? name : `${d}/${name}`))) return d;
+    if (d === "") return "";
+  }
+}
+
+/**
+ * Rewrite, in `substituted`, the pins of every record that name a file in
+ * `changed` and held against `original`. Returns the files with the records
+ * rewritten, and which records were.
+ */
+export function repinSubstituted(
+  original: ReadonlyMap<string, Buffer>,
+  substituted: ReadonlyMap<string, Buffer>,
+  changed: readonly string[],
+): { files: Map<string, Buffer>; repinned: RepinnedRecord[] } {
+  const files = new Map(substituted);
+  const repinned: RepinnedRecord[] = [];
+  if (changed.length === 0) return { files, repinned };
+  const changedSet = new Set(changed);
+  for (const [recordPath, data] of [...substituted].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!recordPath.endsWith(".md")) continue;
+    const text = data.toString("utf-8");
+    const fm = parseFrontMatter(text);
+    if (!fm.ok) continue;
+    const root = workspaceRootOf(substituted, dirOf(recordPath));
+    const full = (p: string) => (root === "" ? p : `${root}/${p}`);
+    const updates = new Map<string, { from: string; to: string }>();
+    for (const pin of pinEntries(fm.value, EVIDENCE)) {
+      const file = full(pin.path);
+      if (!changedSet.has(file)) continue;
+      const before = original.get(file);
+      const after = substituted.get(file);
+      if (!before || !after || sha256Hex(before) !== pin.sha256) continue;
+      updates.set(pin.path, { from: pin.sha256, to: sha256Hex(after) });
+    }
+    if (updates.size === 0) continue;
+    const rewritten = rewritePins(text, updates);
+    // Only a rewrite that reads back with every update applied is kept.
+    const check = parseFrontMatter(rewritten);
+    const pins = check.ok ? pinEntries(check.value, EVIDENCE) : [];
+    if (![...updates].every(([path, u]) => pins.some((p) => p.path === path && p.sha256 === u.to))) continue;
+    files.set(recordPath, Buffer.from(rewritten, "utf-8"));
+    repinned.push({ record: recordPath, paths: [...updates.keys()].sort() });
+  }
+  return { files, repinned };
+}
+
+/**
+ * Replace the `sha256` of each updated pin in the front matter. A pin is a
+ * list entry, from its `- ` line to the next one at the same indentation or
+ * less, holding both `path: "<path>"` and `sha256: "<old>"`.
+ */
+function rewritePins(text: string, updates: ReadonlyMap<string, { from: string; to: string }>): string {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split(eol);
+  const end = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || end < 0) return text;
+  const starts: number[] = [];
+  for (let i = 1; i < end; i++) if (/^\s*- /.test(lines[i])) starts.push(i);
+  for (let s = 0; s < starts.length; s++) {
+    const from = starts[s];
+    const indent = lines[from].search(/-/);
+    let to = end;
+    for (let i = from + 1; i < end; i++) {
+      const lead = lines[i].search(/\S/);
+      if (lead >= 0 && lead <= indent) {
+        to = i;
+        break;
+      }
+    }
+    const entry = lines.slice(from, to).join("\n");
+    const path = entry.match(/(?:^|\n)\s*(?:- )?path: "([^"]*)"/)?.[1];
+    const update = path !== undefined ? updates.get(path) : undefined;
+    if (!update) continue;
+    for (let i = from; i < to; i++) {
+      if (new RegExp(`^(\\s*(?:- )?sha256: )"${update.from}"\\s*$`).test(lines[i])) lines[i] = lines[i].replace(update.from, update.to);
+    }
+  }
+  return lines.join(eol);
+}

package/src/workspace/tree.ts

@@ -19,6 +19,11 @@ export interface WorkspaceTree {
   list(path: string): { name: string; type: "file" | "dir" }[] | undefined;
   /** The text of the file at `path`. Throws when it can't be read. */
   read(path: string): string;
+  /**
+   * The bytes of the file at `path`, for hashing (#2549). Throws when it can't
+   * be read. A tree without it is read as UTF-8 text.
+   */
+  bytes?(path: string): Uint8Array;
 }
 
 /** Join tree-relative path parts, leaving out `""` and `"."`. */
@@ -63,6 +68,9 @@ export function workingTree(root: string): WorkspaceTree {
     read(path) {
       return readFileSync(join(root, path), "utf-8");
     },
+    bytes(path) {
+      return readFileSync(join(root, path));
+    },
   };
 }
 
@@ -123,6 +131,10 @@ export function gitTree(top: string, commit: string, prefix = ""): WorkspaceTree
       if (entries.get(path) !== "file") throw new Error(`${path} is not a file${` at ${commit.slice(0, 8)}`}`);
       return git(top, ["cat-file", "blob", `${commit}:${joinPath(prefix, path)}`]);
     },
+    bytes(path) {
+      if (entries.get(path) !== "file") throw new Error(`${path} is not a file${` at ${commit.slice(0, 8)}`}`);
+      return execFileSync("git", ["cat-file", "blob", `${commit}:${joinPath(prefix, path)}`], { cwd: top, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+    },
   };
 }