@intentius/chant 0.95.1 → 0.96.0

package/src/workspace/intent-cli.ts

@@ -12,11 +12,14 @@
 import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
+import { intentRecord, type IntentRecordDocument } from "./intent-record";
 import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type WorkNode } from "./intent";
 
 const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
+const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]";
 
 type Result = Exclude<IntentDocument, { error: unknown }>;
+type RecordResult = Exclude<IntentRecordDocument, { error: unknown }>;
 
 function edgesFrom(doc: Result, from: string, kind: IntentEdge["kind"]): IntentEdge[] {
   return doc.edges.filter((e) => e.from === from && e.kind === kind);
@@ -53,9 +56,10 @@ function withinLines(doc: Result, d: DecisionNode): string[] {
 function decisionLine(d: DecisionNode): string {
   const via = d.constrains.length > 0 ? d.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through supersession only";
   const by = d.decided_by ? `, decided by ${d.decided_by}${d.decided_on ? ` on ${d.decided_on}` : ""}` : "";
+  const decidedIn = d.decidedIn ? ` in ${short(d.decidedIn.sha)}` : "";
   const reviews = `${d.reviews.agree} agree, ${d.reviews.dissent} dissent, ${d.reviews.abstain} abstain`;
   const superseded = d.supersededBy ? `, superseded by ${d.supersededBy}` : "";
-  return `decision  ${d.record} ${d.state ?? "stateless"}${superseded}: ${d.title ?? d.path}; constrains ${via}${by}; ${reviews}; ${d.provenance.level}${d.valid ? "" : `; invalid: ${d.reasons.map((r) => r.code).join(", ")}`}`;
+  return `decision  ${d.record} ${d.state ?? "stateless"}${superseded}: ${d.title ?? d.path}; constrains ${via}${by}${decidedIn}; ${reviews}; ${d.provenance.level}${d.valid ? "" : `; invalid: ${d.reasons.map((r) => r.code).join(", ")}`}`;
 }
 
 /** A work item, then the commits made inside its window (#2683). */
@@ -123,8 +127,50 @@ export function formatIntent(doc: Result): string {
   return out.join("\n");
 }
 
+/** The record walk as text: the record, its window, then each commit with its bucket, and the counts. */
+export function formatIntentRecord(doc: RecordResult): string {
+  const r = doc.record;
+  const out = [`record    ${r.record} ${r.state ?? "stateless"}${r.supersededBy ? `, superseded by ${r.supersededBy}` : ""}: ${r.title ?? r.path}`];
+  out.push(`window    ${doc.window.from ? `from ${short(doc.window.from)}` : "no history"}${doc.window.until ? ` until ${short(doc.window.until)}` : ""}${r.decidedIn ? `; decided in ${short(r.decidedIn.sha)} ${r.decidedIn.date.slice(0, 10)}: ${r.decidedIn.subject}` : "; not decided in the history read"}`);
+  for (const c of r.constrains) out.push(`entry     ${c.entry}${c.walked ? "" : c.exists === false ? " (not in the tree read)" : " (not walked)"}`);
+  for (const c of doc.commits) {
+    const why =
+      c.bucket === "own"
+        ? `unit ${c.unit}`
+        : c.bucket === "worked"
+          ? `worked by ${c.workedBy.map((w) => w.record).join(", ")}`
+          : c.bucket === "within-other"
+            ? `within ${c.alsoWithin.map((w) => w.record).join(", ")}`
+            : "nothing else accounts for it";
+    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}; ${c.files.join(", ") || c.entries.join(", ")}`);
+  }
+  for (const x of doc.reasons) out.push(`reason    ${x.code}: ${x.message}`);
+  const n = doc.counts;
+  out.push(`${n.commits} commits in the window: ${n.own} own, ${n.worked} worked, ${n.withinOther} within another record's window, ${n.unexplained} unexplained; ${n.outsideWindow} outside it`);
+  return out.join("\n");
+}
+
+async function runRecord(ctx: CommandContext, cwd: string, kinds: string[] | undefined): Promise<number> {
+  const { args } = ctx;
+  const { doc, failed } = await intentRecord({ cwd, record: args.record!, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: RECORD_USAGE }));
+    return 1;
+  }
+  if (!args.json) console.log(formatIntentRecord(doc));
+  return failed ? 1 : 0;
+}
+
 export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Promise<number> {
   const { args } = ctx;
+  if (args.record !== undefined) {
+    if (args.intent) {
+      console.error(formatError({ message: "--record walks a record, so --intent takes no region with it", hint: RECORD_USAGE }));
+      return 1;
+    }
+    return runRecord(ctx, cwd, args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined));
+  }
   if (!args.intent) {
     console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
     return 1;

package/src/workspace/intent-record.schema.json

@@ -0,0 +1,529 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/intent-record/v1/intent-record.schema.json",
+  "title": "chant workspace graph --intent --record output",
+  "description": "What `chant workspace graph --intent --record <id> --json` prints: the intent walk for one decision record over every path: and member: entry its constrains lists, each commit once, kept to the commits inside the record's window, each with one bucket relative to the record. The walk decides nothing: own, worked and within-other say what else accounts for a commit, and unexplained says nothing does. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by graph --intent --record; a chant without --record refuses the flag. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was read. Exit code 0, or 1 when a plugin failed; the document is printed either way.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "at",
+        "workspace",
+        "record",
+        "history",
+        "window",
+        "kinds",
+        "commits",
+        "counts",
+        "reasons"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/intent-record/v1/intent-record.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote the document."
+        },
+        "at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full commit id read with --at, or null for the working tree. History is read from this commit, or from HEAD for the working tree."
+        },
+        "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."
+            }
+          }
+        },
+        "record": {
+          "type": "object",
+          "required": [
+            "id",
+            "recordKind",
+            "record",
+            "path",
+            "title",
+            "state",
+            "supersededBy",
+            "decidedIn",
+            "constrains"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "pattern": "^record:",
+              "description": "record:<kind>/<id>, the id graph --intent gives the same record's node."
+            },
+            "recordKind": {
+              "type": "string"
+            },
+            "record": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "title": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "state": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "supersededBy": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "decidedIn": {
+              "$ref": "#/$defs/decidedIn"
+            },
+            "constrains": {
+              "type": "array",
+              "description": "Every entry of the record's constrains list, in order.",
+              "items": {
+                "$ref": "#/$defs/constraint"
+              }
+            }
+          }
+        },
+        "history": {
+          "type": "object",
+          "required": [
+            "rev",
+            "shallow"
+          ],
+          "properties": {
+            "rev": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit the history was read from, or null when the repository has no commits."
+            },
+            "shallow": {
+              "type": "boolean",
+              "description": "Whether the repository is a shallow clone. When true, reasons holds intent-history-shallow."
+            }
+          }
+        },
+        "window": {
+          "type": "object",
+          "required": [
+            "from",
+            "until"
+          ],
+          "properties": {
+            "from": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit the window opens at: decidedIn, or the commit that added the record when it is not approved. Null when the record has no history."
+            },
+            "until": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{40,64}$",
+              "description": "The commit that opened the window of the record superseding this one, which closes this one's, or null."
+            }
+          }
+        },
+        "kinds": {
+          "type": "array",
+          "description": "Each kind file read, as graph --intent lists them.",
+          "items": {
+            "type": "object",
+            "required": [
+              "file",
+              "name",
+              "records",
+              "joins"
+            ],
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "records": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "joins": {
+                "enum": [
+                  "function",
+                  "data",
+                  null
+                ]
+              }
+            }
+          }
+        },
+        "commits": {
+          "type": "array",
+          "description": "The commits inside the window that changed the record's region, newest first by commit date.",
+          "items": {
+            "$ref": "#/$defs/commit"
+          }
+        },
+        "counts": {
+          "type": "object",
+          "required": [
+            "commits",
+            "own",
+            "worked",
+            "withinOther",
+            "unexplained",
+            "outsideWindow"
+          ],
+          "properties": {
+            "commits": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "own": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "worked": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "withinOther": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Commits whose bucket is within-other."
+            },
+            "unexplained": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "outsideWindow": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Commits that changed the region outside the window, which commits leaves out."
+            }
+          }
+        },
+        "reasons": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/reason"
+          }
+        },
+        "error": false
+      }
+    },
+    "constraint": {
+      "type": "object",
+      "required": [
+        "entry",
+        "granularity",
+        "path",
+        "exists",
+        "walked"
+      ],
+      "properties": {
+        "entry": {
+          "type": "string"
+        },
+        "granularity": {
+          "enum": [
+            "path",
+            "member",
+            "contract",
+            "issue"
+          ]
+        },
+        "path": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "For a path entry, the path from the workspace root; for a member entry, the member's directory. Null for other entries, and for a member the declaration does not name."
+        },
+        "exists": {
+          "type": [
+            "boolean",
+            "null"
+          ],
+          "description": "For a path entry, whether the path is in the tree read; for a member entry, whether the declaration names the member. Null for an entry that names no path."
+        },
+        "walked": {
+          "type": "boolean",
+          "description": "Whether the entry's history was read. Contract and issue entries name no path and are never walked."
+        }
+      }
+    },
+    "commit": {
+      "type": "object",
+      "required": [
+        "sha",
+        "subject",
+        "author",
+        "date",
+        "trailers",
+        "pullRequest",
+        "unit",
+        "entries",
+        "files",
+        "bucket",
+        "workedBy",
+        "alsoWithin"
+      ],
+      "properties": {
+        "sha": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "subject": {
+          "type": "string"
+        },
+        "author": {
+          "type": "object",
+          "required": [
+            "name",
+            "email"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "email": {
+              "type": "string"
+            }
+          }
+        },
+        "date": {
+          "type": "string",
+          "description": "Author date, ISO 8601."
+        },
+        "trailers": {
+          "type": "object",
+          "description": "Every trailer git parses from the message, keyed as written. Core gives no key a meaning; a kind's commitJoins may.",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "pullRequest": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "The number in a (#n) that ends the subject, as a squash merge writes it, or null."
+        },
+        "unit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The unit a kind file's commitJoins joined the commit to, or null."
+        },
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The record's constrains entries whose history lists the commit."
+        },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The files the commit changed in the record's region, from the workspace root; for a merge, against its first parent."
+        },
+        "bucket": {
+          "enum": [
+            "own",
+            "worked",
+            "within-other",
+            "unexplained"
+          ],
+          "description": "The first that holds: own, the record's own work as graph --intent judges it (a unit or contract a plugin joins names the record, or serves a contract it constrains); worked, a work item in workedBy; within-other, a decision in alsoWithin; unexplained, none."
+        },
+        "workedBy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/recordRef"
+          },
+          "description": "Each work item that is not dropped, whose window holds the commit, and that implements the record or covers one of the commit's files by a path: entry. A work item's window runs from the commit that added it to the one that closed it, that one included."
+        },
+        "alsoWithin": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/recordRef"
+          },
+          "description": "Each other decision whose window holds the commit and whose path: entries cover one of the commit's files."
+        }
+      }
+    },
+    "recordRef": {
+      "type": "object",
+      "required": [
+        "recordKind",
+        "record",
+        "state"
+      ],
+      "properties": {
+        "recordKind": {
+          "type": "string"
+        },
+        "record": {
+          "type": "string"
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "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"
+        }
+      }
+    },
+    "reason": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "intent-history-shallow",
+            "intent-plugin-failed"
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration or a record kind could not be read, or no decision has the id, and nothing was walked. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/intent-record/v1/intent-record.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",
+                "intent-record-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "commits": false
+      }
+    }
+  }
+}