@intentius/chant 0.91.0 → 0.93.0

package/src/workspace/answers-ledger.ts

@@ -0,0 +1,118 @@
+/**
+ * Answer records held on the lifecycle ledger (#2786).
+ *
+ * A steward's writes never touch the checkout's index or working tree
+ * (`../op/steward.ts`): the working tree is the coding agent's. A decision
+ * point asked in a steward's turn still has to leave its question somewhere a
+ * person finds it after the turn ends, and an Op's leased worktree is removed
+ * with the run. So a question asked in a steward's turn is written to
+ * `chant/lifecycle`, beside the lease histories and run records, under
+ * `_answers/<kind name>/<id>.md` in the ledger of the member that owns the
+ * answer kind. The file is the same Markdown record the kind's directory
+ * would hold, and it is written with git plumbing, like every ledger write.
+ *
+ * Readers see the ledger's answers as if they sat in the kind's directory:
+ * {@link withLedgerAnswers} lays them over the working tree, so `points`,
+ * `points --open`, a later `points ask` of the same question and `points
+ * answer` all find them. A record on the ledger wins over a file of the same
+ * name in the tree, because the ledger copy is the one a steward rewrote.
+ * People's answer to a question held on the ledger is written back there, so
+ * answering through hud in a box does not touch the checkout either.
+ *
+ * `points --at <rev>` reads a revision of the working branch, which the
+ * ledger is not part of, so it lists the tree's records only.
+ */
+
+import { basename, dirname } from "node:path";
+import { fetchLifecycleStatus, ledgerDir, listFilesInDir, pushLifecycle, readBlobBySha, readPathSha, writeBlobToPath } from "../lifecycle/git";
+import type { RecordSource } from "./record-source";
+import { overlay } from "./records-write";
+
+/** The directory on `chant/lifecycle`, under the member's prefix, that holds answer records. */
+export const ANSWERS_LEDGER_DIR = "_answers";
+
+const BRANCH = "chant/lifecycle";
+
+/** One answer record on the ledger. */
+export interface LedgerAnswer {
+  /** Where the record reads as being: the kind's directory, from the repository root. */
+  path: string;
+  /** Where it is: `chant/lifecycle:<path on the branch>`, which `git show` reads. */
+  ledger: string;
+  text: string;
+  /** Its blob sha, for a compare-and-set rewrite. */
+  sha: string;
+}
+
+/** The answer records one kind holds on the ledger. */
+export interface LedgerAnswers {
+  /** Where the ledger is resolved from: the kind file's directory, so the member owning the kind owns its answers. */
+  cwd: string;
+  /** The directory on the branch, relative to the member's prefix. */
+  dir: string;
+  /** The kind's records directory, from the repository root. */
+  dirRel: string;
+  /** By the path each record reads as. */
+  byPath: Map<string, LedgerAnswer>;
+}
+
+/** The ledger directory of the kind named `kindName`. */
+export function answersLedgerDir(kindName: string): string {
+  return `${ANSWERS_LEDGER_DIR}/${kindName.replace(/[^A-Za-z0-9._-]/g, "_")}`;
+}
+
+function treePath(dirRel: string, name: string): string {
+  return dirRel === "." ? name : `${dirRel}/${name}`;
+}
+
+/**
+ * Read the answer records the kind at `kindFile` holds on the ledger. Empty
+ * when there are none, when there is no ledger branch, and outside a git
+ * repository.
+ */
+export async function readLedgerAnswers(kind: { file: string; name: string; dirRel: string }): Promise<LedgerAnswers> {
+  const cwd = dirname(kind.file);
+  const dir = answersLedgerDir(kind.name);
+  const out: LedgerAnswers = { cwd, dir, dirRel: kind.dirRel, byPath: new Map() };
+  try {
+    const names = (await listFilesInDir(dir, { cwd })).filter((n) => n.endsWith(".md"));
+    if (names.length === 0) return out;
+    const full = await ledgerDir(dir, { cwd });
+    for (const name of names) {
+      const sha = await readPathSha(dir, name, { cwd });
+      const text = sha ? await readBlobBySha(sha, { cwd }) : null;
+      if (sha === null || text === null) continue;
+      const path = treePath(kind.dirRel, name);
+      out.byPath.set(path, { path, ledger: `${BRANCH}:${full}/${name}`, text, sha });
+    }
+  } catch {
+    // No repository, or a member ledger that can't be placed: the tree's records are all there is.
+  }
+  return out;
+}
+
+/** `base` with each ledger answer at the path it reads as, over any file of the same name. */
+export function withLedgerAnswers(base: RecordSource, answers: LedgerAnswers): RecordSource {
+  let source = base;
+  for (const a of answers.byPath.values()) source = overlay(source, a.path, a.text);
+  return source;
+}
+
+/** Fetch `chant/lifecycle` before a ledger write when it fast-forwards, so a question another clone asked is found. Best effort. */
+export async function refreshLedger(kindFile: string): Promise<void> {
+  await fetchLifecycleStatus({ cwd: dirname(kindFile) }).catch(() => undefined);
+}
+
+/**
+ * Write the record read as `path` to the ledger, expecting the blob it had
+ * when it was read (`prior`, null for a new record), then push the branch.
+ * A changed blob throws `RefCASConflictError` from `../lifecycle/git`. The
+ * push is best effort: a question that did not reach the remote is still
+ * open here. Returns where the record went.
+ */
+export async function writeLedgerAnswer(answers: LedgerAnswers, path: string, text: string, message: string, prior: string | null): Promise<{ ledger: string; pushed: boolean }> {
+  const name = basename(path);
+  await writeBlobToPath(answers.dir, name, text, message, { cwd: answers.cwd, expectPriorPathSha: prior });
+  const pushed = await pushLifecycle({ cwd: answers.cwd }).catch(() => false);
+  return { ledger: `${BRANCH}:${await ledgerDir(answers.dir, { cwd: answers.cwd })}/${name}`, pushed };
+}

package/src/workspace/changes-cli.ts

@@ -0,0 +1,56 @@
+/**
+ * `chant workspace check --changes <base>..<head> [--work <id>] [--severity
+ * off|warn|fail] [--kind <kind file>...] [--json]` (#2773): the forward
+ * coverage check (`changes.ts`), printed as JSON with `--json` or as one line
+ * per changed path, then the findings.
+ */
+
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { CHANGE_SEVERITIES, checkChanges, type ChangesDocument } from "./changes";
+import type { ChangeSeverity } from "./declaration";
+
+const USAGE = "chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
+
+type Result = Exclude<ChangesDocument, { error: unknown }>;
+
+/** One line per changed path, then the findings and a summary. */
+export function formatChanges(doc: Result): string {
+  const out: string[] = [];
+  const work = doc.work ? `, work item ${doc.work.record} in hand` : "";
+  out.push(`changes   ${doc.range.base.slice(0, 8)}..${doc.range.head.slice(0, 8)} (${doc.range.spec}), severity ${doc.severity}${work}`);
+  for (const p of doc.paths) {
+    const why =
+      p.status === "covered"
+        ? `by ${p.coveredBy.map((c) => `${c.record} (${c.entry})`).join(", ")}`
+        : p.status === "out-of-scope"
+          ? `by ${p.outOfScopeBy.map((c) => `${c.record} (${c.entry})`).join(", ")}`
+          : p.status === "ignored"
+            ? `by ${p.ignoredBy}`
+            : "";
+    out.push(`${p.status.padEnd(12)} ${p.change.padEnd(8)} ${p.path}${p.from ? ` (from ${p.from})` : ""}${why ? `; ${why}` : ""}`);
+  }
+  for (const f of doc.findings) out.push(`${f.severity === "fail" ? "error  " : "warning"}   ${f.code}: ${f.message}`);
+  const s = doc.summary;
+  out.push(`${s.paths} changed paths: ${s.covered} covered, ${s.uncovered} uncovered, ${s.outOfScope} out of scope, ${s.ignored} ignored, ${s.records} records; ${doc.findings.length} findings`);
+  return out.join("\n");
+}
+
+export async function runWorkspaceChanges(ctx: CommandContext, cwd: string): Promise<number> {
+  const { args } = ctx;
+  const severity = args.severity as ChangeSeverity | undefined;
+  if (severity !== undefined && !(CHANGE_SEVERITIES as readonly string[]).includes(severity)) {
+    console.error(formatError({ message: `--severity ${severity} is not off, warn or fail`, hint: USAGE }));
+    return 1;
+  }
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+  const { doc, failed } = await checkChanges({ cwd, range: args.changes!, kinds: kinds?.map((k) => resolve(k)), work: args.work, severity });
+  if (args.json || args.format === "json") console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if (!args.json && args.format !== "json") console.log(formatChanges(doc));
+  return failed ? 1 : 0;
+}

package/src/workspace/changes.schema.json

@@ -0,0 +1,472 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/changes/v1/changes.schema.json",
+  "title": "chant workspace check --changes output",
+  "description": "What `chant workspace check --changes <base>..<head> --json` prints: the forward coverage check (#2773). Each path the diff changes, mapped to the current records whose constrains cover it, and a finding for each path no current decided record or open work item covers (change-uncovered), or that a record in hand for the change puts out of scope (change-out-of-scope). Readers ignore fields they do not know; a field is only ever added within a version. The finding and error codes are closed lists, and every one is in the one closed list of `reason-codes.ts`. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2773; a chant without --changes refuses the flag.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The diff and the records were read. Exit code 0, or 1 when severity is fail and there is a finding; the document is printed either way.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "workspace",
+        "range",
+        "severity",
+        "ignore",
+        "work",
+        "kinds",
+        "paths",
+        "findings",
+        "summary",
+        "ok"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/changes/v1/changes.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote the document."
+        },
+        "workspace": {
+          "type": "object",
+          "required": [
+            "name",
+            "root"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "root": {
+              "type": "string",
+              "description": "The workspace root relative to the git root, \".\" for the git root."
+            }
+          }
+        },
+        "range": {
+          "type": "object",
+          "required": [
+            "spec",
+            "base",
+            "head"
+          ],
+          "properties": {
+            "spec": {
+              "type": "string",
+              "description": "The range as given: <base>..<head>, <base>...<head> or <base>."
+            },
+            "base": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit the diff starts from: <base>, or for <base>...<head> the merge base."
+            },
+            "head": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit the diff ends at. The declaration and the records are read here."
+            }
+          }
+        },
+        "severity": {
+          "enum": [
+            "off",
+            "warn",
+            "fail"
+          ],
+          "description": "From --severity, else the declaration's changes.severity, else warn. off reports no finding."
+        },
+        "ignore": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The declaration's changes.ignore globs."
+        },
+        "work": {
+          "description": "The work item in hand (--work), or null.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "record",
+                "state"
+              ],
+              "properties": {
+                "record": {
+                  "type": "string"
+                },
+                "state": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "kinds": {
+          "type": "array",
+          "description": "The record kinds read: the --kind files, or every kind the declaration names. role is work for a kind with a work block, decision for another kind with constrains, and other for a kind that covers nothing.",
+          "items": {
+            "type": "object",
+            "required": [
+              "file",
+              "name",
+              "role"
+            ],
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "role": {
+                "enum": [
+                  "decision",
+                  "work",
+                  "other"
+                ]
+              }
+            }
+          }
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/path"
+          }
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/finding"
+          }
+        },
+        "summary": {
+          "type": "object",
+          "required": [
+            "paths",
+            "covered",
+            "uncovered",
+            "outOfScope",
+            "ignored",
+            "records"
+          ],
+          "properties": {
+            "paths": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "covered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "uncovered": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "outOfScope": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "ignored": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "records": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "ok": {
+          "type": "boolean",
+          "description": "False only when severity is fail and there is a finding."
+        }
+      }
+    },
+    "path": {
+      "type": "object",
+      "required": [
+        "path",
+        "change",
+        "from",
+        "member",
+        "status",
+        "coveredBy",
+        "outOfScopeBy",
+        "ignoredBy"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "From the workspace root."
+        },
+        "change": {
+          "enum": [
+            "added",
+            "modified",
+            "deleted",
+            "renamed"
+          ]
+        },
+        "from": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "For a rename, the path at base."
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member whose directory holds the path."
+        },
+        "generated": {
+          "type": "boolean",
+          "description": "Added by #2794: whether the path is a generated file, declared in a member's generated entries or one core registers, as graph --intent reads a region's generated. The finding-triage point reads it as region.generated."
+        },
+        "status": {
+          "enum": [
+            "covered",
+            "uncovered",
+            "out-of-scope",
+            "ignored",
+            "record"
+          ],
+          "description": "record: the path is a record file of a kind read, so the change is to the records themselves. ignored: a changes.ignore glob matches it. out-of-scope takes precedence over covered."
+        },
+        "coveredBy": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "record",
+              "state",
+              "entry"
+            ],
+            "properties": {
+              "record": {
+                "type": "string",
+                "description": "The record, as <kind name>/<id>."
+              },
+              "state": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "entry": {
+                "type": "string",
+                "description": "The constrains entry that covers the path (path:<path> or member:<name>), or the out_of_scope path that puts it out."
+              }
+            }
+          },
+          "description": "The current records whose constrains cover the path: decisions not superseded and in a decided state, and work items not in a closed state."
+        },
+        "outOfScopeBy": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "record",
+              "state",
+              "entry"
+            ],
+            "properties": {
+              "record": {
+                "type": "string",
+                "description": "The record, as <kind name>/<id>."
+              },
+              "state": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "entry": {
+                "type": "string",
+                "description": "The constrains entry that covers the path (path:<path> or member:<name>), or the out_of_scope path that puts it out."
+              }
+            }
+          },
+          "description": "The records in hand whose out_of_scope lists the path or a directory above it."
+        },
+        "ignoredBy": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The glob that matched an ignored path."
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": [
+        "id",
+        "code",
+        "path",
+        "message",
+        "severity",
+        "records",
+        "triage"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "finding:<code>:<path>."
+        },
+        "code": {
+          "enum": [
+            "change-uncovered",
+            "change-out-of-scope"
+          ]
+        },
+        "path": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        },
+        "severity": {
+          "enum": [
+            "warn",
+            "fail"
+          ]
+        },
+        "records": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "For change-out-of-scope, the records that put the path out of scope."
+        },
+        "triage": {
+          "type": "object",
+          "required": [
+            "finding",
+            "region"
+          ],
+          "description": "The source a work item seeded from this finding carries: work.schema.json's sourceGap. The finding-triage decision point (#2741) reads it.",
+          "properties": {
+            "finding": {
+              "enum": [
+                "change-uncovered",
+                "change-out-of-scope"
+              ]
+            },
+            "region": {
+              "type": "string"
+            }
+          }
+        },
+        "addressed": {
+          "type": "boolean",
+          "description": "Added by #2794, present when a work kind was read: whether a work item addresses the finding, because the item's source.finding is this code and its source.region is this path or a directory above it, in any state, as graph --intent reads a gap source (#2683). The finding-triage point reads it as finding.addressed."
+        },
+        "addressedBy": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "record",
+              "state"
+            ],
+            "properties": {
+              "record": {
+                "type": "string",
+                "description": "The work item, as <kind name>/<id>."
+              },
+              "state": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          },
+          "description": "Added by #2794, present when a work kind was read: the work items addressing the finding, each with its state."
+        }
+      }
+    },
+    "failure": {
+      "description": "The range, the declaration, a record kind or the --work item could not be read, and nothing was checked. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/changes/v1/changes.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "work-item-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "paths": false
+      }
+    }
+  }
+}