@intentius/chant 0.95.0 → 0.96.0

package/src/workspace/intent.schema.json

@@ -542,6 +542,7 @@
         "provenance",
         "decided_by",
         "decided_on",
+        "decidedIn",
         "reviews",
         "supersededBy",
         "supersedes",
@@ -651,6 +652,10 @@
             "null"
           ]
         },
+        "decidedIn": {
+          "$ref": "#/$defs/decidedIn",
+          "description": "Its window opens at this commit, or, when null, at the commit that added the record."
+        },
         "reviews": {
           "type": "object",
           "required": [
@@ -1254,7 +1259,8 @@
                 "schema-id-mismatch",
                 "schema-invalid",
                 "location-missing",
-                "intent-region-invalid"
+                "intent-region-invalid",
+                "intent-record-unknown"
               ]
             },
             "message": {
@@ -1442,6 +1448,32 @@
           "description": "The linked record's state, or null when no record has the id."
         }
       }
+    },
+    "decidedIn": {
+      "description": "Added in contract 1. The commit that last moved the record into an approved state and kept it there: a state the kind's approval ranks above 0, or one of its closedStates when it has no approval. Read from the history of the record's file reachable from the revision read, or HEAD in the working tree. A record added approved was decided by the commit that added it. Null when the record is not approved in that history.",
+      "type": [
+        "object",
+        "null"
+      ],
+      "required": [
+        "sha",
+        "date",
+        "subject"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "sha": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "date": {
+          "type": "string",
+          "description": "The author date, ISO 8601."
+        },
+        "subject": {
+          "type": "string"
+        }
+      }
     }
   }
 }

package/src/workspace/intent.ts

@@ -44,6 +44,7 @@ import { loadKindRegistry } from "./kinds";
 import { resolveLinks, type LinkTableRow } from "./links";
 import { sourceMemberHandles } from "./member-handles";
 import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
+import type { DecidedIn } from "./record-decided";
 import { importKindModule, loadRecordKind, parseFrontMatter, RecordReadError, supersedesTargets, type LoadedRecordKind } from "./records";
 import { queryRecords, type RecordView } from "./records-cli";
 import { isPluginCode, type PluginCode, type ReasonCode } from "./reason-codes";
@@ -120,6 +121,8 @@ export const INTENT_ERROR_CODES = [
   "location-missing",
   /** The region's path, or its line range, does not exist in the tree read. */
   "intent-region-invalid",
+  /** --record names an id no record of a decision kind read has. */
+  "intent-record-unknown",
 ] as const satisfies readonly ReasonCode[];
 export type IntentErrorCode = (typeof INTENT_ERROR_CODES)[number];
 
@@ -232,6 +235,13 @@ export interface DecisionNode {
   provenance: { level: ProvenanceLevel; commit: string | null; reason: string };
   decided_by: string | null;
   decided_on: string | null;
+  /**
+   * The commit that last moved the record into an approved state and kept it
+   * there, from the history read (`record-decided.ts`), or null when the
+   * record is not approved there. Its window opens at this commit, or at the
+   * commit that added the record when this is null.
+   */
+  decidedIn: DecidedIn | null;
   reviews: { agree: number; dissent: number; abstain: number; openConcerns: number };
   supersededBy: string | null;
   /** The ids of the records this one's supersedes links name. */
@@ -389,7 +399,7 @@ function git(top: string, args: string[], input?: string): string {
   return execFileSync("git", args, { cwd: top, encoding: "utf-8", input, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
 }
 
-function tryGit(top: string, args: string[], input?: string): string | undefined {
+export function tryGit(top: string, args: string[], input?: string): string | undefined {
   try {
     return git(top, args, input);
   } catch {
@@ -409,7 +419,7 @@ function hunkRanges(patch: string): LineRange[] {
 }
 
 /** The commits that touched the region, newest first, with the lines each changed for a line range. */
-function regionHistory(top: string, rev: string, gitPath: string, type: "file" | "dir", lines: LineRange | null): { sha: string; lines: LineRange[] | null }[] {
+export function regionHistory(top: string, rev: string, gitPath: string, type: "file" | "dir", lines: LineRange | null): { sha: string; lines: LineRange[] | null }[] {
   if (lines) {
     const out = tryGit(top, ["log", `-L${lines.start},${lines.end}:${gitPath}`, "--format=%x00%H", "--no-color", rev]);
     if (out === undefined) return [];
@@ -433,7 +443,7 @@ function regionHistory(top: string, rev: string, gitPath: string, type: "file" |
 }
 
 /** Subject, body, author, date and trailers of each commit. */
-function commitDetails(top: string, shas: string[]): Map<string, IntentCommit> {
+export function commitDetails(top: string, shas: string[]): Map<string, IntentCommit> {
   const out = new Map<string, IntentCommit>();
   if (shas.length === 0) return out;
   const text = git(top, ["log", "--no-walk=unsorted", "--stdin", "--format=%x00%H%x1f%an%x1f%ae%x1f%aI%x1f%(trailers:only,unfold,separator=%x1e)%x1f%B"], `${shas.join("\n")}\n`);
@@ -462,7 +472,7 @@ function commitDetails(top: string, shas: string[]): Map<string, IntentCommit> {
 }
 
 /** The commit reachable from `rev` that last added `path` (from the repository root), or null. */
-function addingCommit(top: string, rev: string, path: string): string | null {
+export function addingCommit(top: string, rev: string, path: string): string | null {
   const out = tryGit(top, ["log", "--diff-filter=A", "-1", "--format=%H", rev, "--", path]);
   return out?.trim() || null;
 }
@@ -473,7 +483,7 @@ function addingCommit(top: string, rev: string, path: string): string | null {
  * `rev` (#2683). A record added in a closed state closes in the commit that
  * added it.
  */
-function closingCommit(top: string, rev: string, path: string, stateField: string, closed: readonly string[]): string | null {
+export function closingCommit(top: string, rev: string, path: string, stateField: string, closed: readonly string[]): string | null {
   const out = tryGit(top, ["log", "--format=%H", rev, "--", path]);
   let closing: string | null = null;
   for (const sha of (out ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
@@ -486,8 +496,13 @@ function closingCommit(top: string, rev: string, path: string, stateField: strin
   return closing;
 }
 
+/** The commit a decision record's window opens at: the one that decided it, or, when it is not approved, the one that added it. */
+export function windowOpening(top: string, rev: string, view: Pick<RecordView, "path" | "decidedIn">): string | null {
+  return view.decidedIn?.sha ?? addingCommit(top, rev, view.path);
+}
+
 /** `commit` and every commit between it and `rev` that has it as an ancestor. */
-function descendants(top: string, commit: string, rev: string): Set<string> {
+export function descendants(top: string, commit: string, rev: string): Set<string> {
   const out = new Set<string>([commit]);
   const text = tryGit(top, ["rev-list", "--ancestry-path", `${commit}..${rev}`]);
   for (const line of (text ?? "").split("\n")) if (line.trim()) out.add(line.trim());
@@ -592,7 +607,7 @@ async function resolveNodeFromGraph(cwd: string, at: string | undefined, member:
 
 // ── The walk ─────────────────────────────────────────────────────────────────
 
-interface LoadedKind {
+export interface LoadedKind {
   file: string;
   /** Relative to the repository root, for the document. */
   display: string;
@@ -602,7 +617,7 @@ interface LoadedKind {
   joins?: CommitJoins;
 }
 
-async function loadKinds(query: IntentQuery, top: string): Promise<LoadedKind[]> {
+export async function loadKinds(query: IntentQuery, top: string): Promise<LoadedKind[]> {
   const out: LoadedKind[] = [];
   for (const k of query.kinds ?? []) {
     const file = resolve(query.cwd, k);
@@ -822,6 +837,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       provenance: { level: v.provenance.level, commit: v.provenance.commit, reason: v.provenance.reason },
       decided_by: stringOr(v.data?.decided_by),
       decided_on: stringOr(v.data?.decided_on),
+      decidedIn: v.decidedIn ?? null,
       reviews: reviewSummary(v.data),
       supersededBy: v.supersededBy,
       supersedes,
@@ -988,14 +1004,15 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
   }
 
   // Which decisions covered the region at each commit's time: from the commit
-  // that added the record until the commit that added the record superseding it.
+  // that decided the record, or added it when it is not approved, until the
+  // commit that opened the window of the record superseding it.
   const windows = new Map<string, { from: Set<string>; until: Set<string> | null }>();
   if (rev) {
     for (const c of covering) {
-      const added = addingCommit(top, rev, c.view.path);
+      const opened = windowOpening(top, rev, c.view);
       const successor = c.view.supersededBy ? decisionById.get(`${c.node.recordKind}/${c.view.supersededBy}`) : undefined;
-      const replaced = successor ? addingCommit(top, rev, successor.view.path) : null;
-      windows.set(c.node.id, { from: added ? descendants(top, added, rev) : new Set(), until: replaced ? descendants(top, replaced, rev) : null });
+      const replaced = successor ? windowOpening(top, rev, successor.view) : null;
+      windows.set(c.node.id, { from: opened ? descendants(top, opened, rev) : new Set(), until: replaced ? descendants(top, replaced, rev) : null });
     }
   }
   // Work items (#2683): the records of each work kind whose constrains cover

package/src/workspace/ls-contract.test.ts

@@ -166,6 +166,12 @@ describe("chant workspace ls on built workspaces", () => {
             render: "docs/diagrams/boundary.svg",
             renderer: { tool: "graphviz", version: "9.0.0", args: [] },
           },
+          {
+            name: "flow",
+            title: "Request flow",
+            source: "docs/diagrams/flow.mmd",
+            renderer: { tool: "mermaid", version: "11.4.1" },
+          },
         ],
       }),
       "docs/README.md": "",
@@ -181,6 +187,14 @@ describe("chant workspace ls on built workspaces", () => {
         renderer: { tool: "graphviz", version: "9.0.0", args: [] },
         member: null,
       },
+      {
+        name: "flow",
+        title: "Request flow",
+        source: "docs/diagrams/flow.mmd",
+        render: null,
+        renderer: { tool: "mermaid", version: "11.4.1", args: [] },
+        member: null,
+      },
       {
         name: "architecture",
         title: "Studio architecture",

package/src/workspace/ls.schema.json

@@ -173,13 +173,13 @@
         "name": { "type": "string" },
         "title": { "type": "string" },
         "source": { "type": ["string", "null"], "description": "From the workspace root, with / separators. Null for an SVG with no source." },
-        "render": { "type": "string", "description": "From the workspace root, with / separators." },
+        "render": { "type": ["string", "null"], "description": "From the workspace root, with / separators. Null for a mermaid or excalidraw diagram with no committed render: a reader draws it from its source." },
         "renderer": {
           "type": "object",
           "required": ["tool", "version", "args"],
           "properties": {
-            "tool": { "enum": ["d2", "mermaid", "graphviz"] },
-            "version": { "type": "string", "description": "The exact release the render was made with, such as 0.9.0." },
+            "tool": { "enum": ["d2", "mermaid", "graphviz", "excalidraw"] },
+            "version": { "type": "string", "description": "The exact release the render was made with, such as 0.9.0. For mermaid or excalidraw, the release of the library a reader draws the source with." },
             "args": { "type": "array", "items": { "type": "string" }, "description": "Passed before the input and output paths, in order." }
           }
         },

package/src/workspace/ls.ts

@@ -122,8 +122,8 @@ export interface LsDiagram {
   title: string;
   /** From the workspace root, with / separators. Null for an SVG with no source. */
   source: string | null;
-  /** From the workspace root, with / separators. */
-  render: string;
+  /** From the workspace root, with / separators. Null for a mermaid or excalidraw diagram with no committed render: a reader draws it from its source. */
+  render: string | null;
   renderer: DiagramDeclaration["renderer"];
   /** The member that declares it, or null for the workspace's own. */
   member: string | null;
@@ -354,7 +354,7 @@ function formatLs(doc: Extract<LsDocument, { members: unknown }>): string {
   if (doc.diagrams.length > 0) {
     lines.push("");
     const rows = [["DIAGRAM", "MEMBER", "SOURCE", "RENDER", "RENDERER"]];
-    for (const d of doc.diagrams) rows.push([d.name, d.member ?? "(workspace)", d.source ?? "-", d.render, `${d.renderer.tool} ${d.renderer.version}`]);
+    for (const d of doc.diagrams) rows.push([d.name, d.member ?? "(workspace)", d.source ?? "-", d.render ?? "-", `${d.renderer.tool} ${d.renderer.version}`]);
     lines.push(...table(rows));
   }
   if (doc.groups.length > 0) {

package/src/workspace/patch.schema.json

@@ -0,0 +1,321 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/patch/v1/patch.schema.json",
+  "title": "chant workspace patch output",
+  "description": "What `chant workspace patch <range> --json` prints: each file a diff changes under the workspace root, with its line counts and hunks, cut to a size limit. The range is <base>..<head>, <base>...<head> (from the merge base), or one commit against its first parent, or against the empty tree for a root commit. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by workspace patch; a chant without the command refuses it. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The diff was read. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "workspace",
+        "range",
+        "paths",
+        "limits",
+        "files",
+        "summary"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/patch/v1/patch.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",
+            "form",
+            "base",
+            "head"
+          ],
+          "properties": {
+            "spec": {
+              "type": "string",
+              "description": "The range as given."
+            },
+            "form": {
+              "enum": [
+                "range",
+                "merge-base",
+                "commit",
+                "worktree"
+              ],
+              "description": "range: <base>..<head>. merge-base: <base>...<head>, so base is their merge base. commit: one commit, so base is its first parent, or the empty tree. worktree: --worktree, the working tree against one commit (HEAD unless given), untracked files that git does not ignore as added."
+            },
+            "base": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit, or for a root commit the empty tree, the diff starts from."
+            },
+            "head": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit the diff ends at; null for the working tree (worktree)."
+            }
+          }
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The --path filters, from the workspace root. Empty for the whole workspace."
+        },
+        "limits": {
+          "type": "object",
+          "required": [
+            "fileBytes",
+            "totalBytes"
+          ],
+          "properties": {
+            "fileBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The hunk text, headers included, one file gets: --max-bytes, or 65536."
+            },
+            "totalBytes": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "The hunk text every file gets together: 16 times fileBytes."
+            }
+          }
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/file"
+          },
+          "description": "In the order git lists them."
+        },
+        "summary": {
+          "type": "object",
+          "required": [
+            "files",
+            "additions",
+            "deletions",
+            "truncated"
+          ],
+          "properties": {
+            "files": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "additions": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "deletions": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "truncated": {
+              "type": "boolean",
+              "description": "Whether any file is truncated."
+            }
+          }
+        },
+        "error": false
+      }
+    },
+    "file": {
+      "type": "object",
+      "required": [
+        "path",
+        "change",
+        "from",
+        "binary",
+        "additions",
+        "deletions",
+        "hunkCount",
+        "bytes",
+        "hunks",
+        "truncated"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "From the workspace root."
+        },
+        "change": {
+          "enum": [
+            "added",
+            "modified",
+            "deleted",
+            "renamed",
+            "copied"
+          ]
+        },
+        "from": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "For a rename or a copy, the path it came from, from the workspace root."
+        },
+        "binary": {
+          "type": "boolean"
+        },
+        "additions": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0,
+          "description": "Lines added, as git counts them; null for a binary file."
+        },
+        "deletions": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0,
+          "description": "Lines deleted; null for a binary file."
+        },
+        "hunkCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many hunks git wrote for the file. hunks holds fewer when truncated."
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The bytes of hunk text git wrote for the file, headers included, before any cut."
+        },
+        "hunks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/hunk"
+          }
+        },
+        "truncated": {
+          "type": "boolean",
+          "description": "Whether hunks holds less than git wrote: the file's text passed fileBytes, or the total passed totalBytes. The last hunk kept may be cut short."
+        }
+      }
+    },
+    "hunk": {
+      "type": "object",
+      "required": [
+        "header",
+        "oldStart",
+        "oldLines",
+        "newStart",
+        "newLines",
+        "lines"
+      ],
+      "properties": {
+        "header": {
+          "type": "string",
+          "description": "The @@ line as git writes it."
+        },
+        "oldStart": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "oldLines": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "newStart": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "newLines": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "lines": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Each line with its leading space, +, - or backslash, without its newline."
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration could not be read, a revision is not a commit, or a --path is not inside the workspace, and nothing was read. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/patch/v1/patch.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",
+                "patch-path-invalid"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "files": false
+      }
+    }
+  }
+}