@intentius/chant 0.82.0 → 0.84.0

package/src/workspace/graph.schema.json

@@ -218,14 +218,17 @@
         },
         "links": {
           "type": "array",
-          "description": "Member links (#2524 D6, #2539): the ones declared on a consumer and the ones inferred from join keys, resolved against the composed graph. A reader draws a row from its `from` node to its `to` node when both are set.",
+          "description": "Member links (#2524 D6, #2539): the ones declared on a consumer and the ones inferred from join keys, resolved against the composed graph. A reader draws a row from its `from` node to its `to` node when both are set. With --kind, the links of the records read follow (#2549): an `asset` row for each file a record pins by hash, and a `constrains` row for each member or path it governs. These rows have `record` and `target` instead of `consumer` and `producer`.",
           "items": {
             "$ref": "#/$defs/link"
           }
         },
         "records": {
           "type": "array",
-          "description": "Record sections (#2524 D4). Empty until record kinds join the graph."
+          "description": "The records read with --kind (#2524 D4, #2549), sorted by path; empty without it. A record link in `links` names its record by id.",
+          "items": {
+            "$ref": "#/$defs/record"
+          }
         }
       }
     },
@@ -655,8 +658,134 @@
               }
             }
           }
+        },
+        {
+          "type": "object",
+          "description": "A record link (#2549): from a current record to a file it pins (kind asset) or to a member or path it constrains (kind constrains). Superseded records have none. A reader finds the artifacts behind a file by taking the decisions whose constrains cover it and then their asset rows.",
+          "required": [
+            "kind",
+            "origin",
+            "resolves",
+            "recordKind",
+            "record",
+            "recordPath",
+            "target",
+            "member",
+            "status",
+            "reason"
+          ],
+          "properties": {
+            "kind": {
+              "enum": [
+                "asset",
+                "constrains"
+              ]
+            },
+            "origin": {
+              "const": "declared"
+            },
+            "resolves": {
+              "const": "source"
+            },
+            "recordKind": {
+              "type": "string",
+              "description": "The record's kind, such as decision."
+            },
+            "record": {
+              "type": "string",
+              "description": "The record's id."
+            },
+            "recordPath": {
+              "type": "string",
+              "description": "The record file, from the repository root."
+            },
+            "target": {
+              "type": "string",
+              "description": "For asset, the pinned path from the workspace root. For constrains, the entry as written: member:<name> or path:<path>."
+            },
+            "member": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The member the target names or sits in; null when no member does."
+            },
+            "status": {
+              "enum": [
+                "pinned",
+                "drifted",
+                "missing",
+                "stale",
+                "resolved"
+              ],
+              "description": "For asset: pinned, drifted, missing or stale, as records reports the pin. For constrains: resolved, or missing when the member is not declared or the path does not exist."
+            },
+            "reason": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Why the row is not pinned or resolved, or null."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "For asset: the pinned hash."
+            },
+            "actual": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "For asset: the hash of the file in the tree read, or null when it is missing."
+            }
+          }
         }
       ]
+    },
+    "record": {
+      "type": "object",
+      "required": [
+        "kind",
+        "id",
+        "path",
+        "state",
+        "valid",
+        "supersededBy"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "description": "The record kind's name, such as decision."
+        },
+        "id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, from the repository root, with / separators."
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "valid": {
+          "type": "boolean",
+          "description": "As chant workspace records reports it."
+        },
+        "supersededBy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
     }
   }
 }

package/src/workspace/intent-cli.ts

@@ -0,0 +1,95 @@
+/**
+ * `chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]`
+ * (#2651): the intent graph over one region (`intent.ts`), printed as JSON
+ * with `--json` or as a walk, one line per node, in the order of #2650
+ * section B: the region, its decisions, their artifacts, the commits, and the
+ * findings.
+ */
+
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode } from "./intent";
+
+const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
+
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+function edgesFrom(doc: Result, from: string, kind: IntentEdge["kind"]): IntentEdge[] {
+  return doc.edges.filter((e) => e.from === from && e.kind === kind);
+}
+
+function ofKind<K extends IntentNode["kind"]>(doc: Result, kind: K): Extract<IntentNode, { kind: K }>[] {
+  return doc.nodes.filter((n): n is Extract<IntentNode, { kind: K }> => n.kind === kind);
+}
+
+const short = (sha: string | null | undefined) => (sha ? sha.slice(0, 8) : "none");
+
+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 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(", ")}`}`;
+}
+
+function artifactLine(doc: Result, a: ArtifactNode): string {
+  const by = doc.edges
+    .filter((e): e is Extract<IntentEdge, { kind: "pins" }> => e.kind === "pins" && e.to === a.id)
+    .map((e) => `${e.from.slice(e.from.indexOf("/") + 1)} at ${short(e.pinnedSha256)} (${e.pinState})`);
+  return `artifact  ${a.path} ${a.pinState}; pinned by ${by.join(", ")}; now ${short(a.currentSha256)}`;
+}
+
+function commitLine(doc: Result, c: CommitNode): string[] {
+  const lines = c.lines && c.lines.length > 0 ? `, lines ${c.lines.map((l) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`)).join(", ")}` : "";
+  const out = [`commit    ${short(c.sha)} ${c.date.slice(0, 10)} ${c.author.name}: ${c.subject}${lines}; ${c.signature.level}`];
+  for (const e of edgesFrom(doc, c.id, "produced-by")) {
+    const unit = doc.nodes.find((n) => n.id === e.to);
+    out.push(`  unit      ${unit && "ref" in unit ? unit.ref : e.to}`);
+    for (const s of edgesFrom(doc, e.to, "serves")) out.push(`  contract  ${s.to.slice("contract:".length)}`);
+    for (const s of edgesFrom(doc, e.to, "cites-evidence")) out.push(`  evidence  ${s.to.slice("evidence:".length)}`);
+  }
+  return out;
+}
+
+/** The walk as text, one line each, in the order of #2650 section B. */
+export function formatIntent(doc: Result): string {
+  const out: string[] = [];
+  const region = doc.nodes.find((n) => n.id === doc.region);
+  if (region?.kind === "region") {
+    const lines = region.lines ? `:${region.lines.start}${region.lines.end === region.lines.start ? "" : `-${region.lines.end}`}` : "";
+    const where = doc.at ? `at ${short(doc.at)}` : "in the working tree";
+    out.push(`region    ${region.path}${lines} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
+  }
+  const files = ofKind(doc, "file");
+  if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
+  for (const d of ofKind(doc, "decision")) out.push(decisionLine(d));
+  for (const a of ofKind(doc, "artifact")) out.push(artifactLine(doc, a));
+  for (const c of ofKind(doc, "commit")) out.push(...commitLine(doc, c));
+  for (const l of ofKind(doc, "link")) {
+    const r = l.row;
+    out.push(`link      ${r.consumer} reads ${"producer" in r ? `${r.producer} ${r.output}` : r.input} (${r.status})`);
+  }
+  for (const f of ofKind(doc, "finding")) out.push(`finding   ${f.code}: ${f.message}`);
+  for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
+  const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
+  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
+  return out.join("\n");
+}
+
+export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Promise<number> {
+  const { args } = ctx;
+  if (!args.intent) {
+    console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
+    return 1;
+  }
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : []);
+  const { doc, failed } = await intentGraph({ cwd, region: args.intent, 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: USAGE }));
+    return 1;
+  }
+  if (!args.json) console.log(formatIntent(doc));
+  return failed ? 1 : 0;
+}

package/src/workspace/intent-joins.ts

@@ -0,0 +1,165 @@
+/**
+ * The commit-join hook of the intent graph (#2651; #2650 C1 and C13).
+ *
+ * Commits, decisions and artifacts come from core. Units of work, contracts
+ * and evidence come from a plugin, such as chud's development model, because
+ * core ships no model of them (#2555, "Core ships no decision kind"). A kind
+ * file passed to `chant workspace graph --intent --kind <file>` supplies them
+ * through one export, `commitJoins`, in one of two forms:
+ *
+ * - A function `commitJoins(commit, context)` that returns the unit, contract
+ *   and evidence for one commit, or nothing. It is given the commit's sha,
+ *   subject, body, author, date and trailers, and a `read` function for files
+ *   at the revision read.
+ * - Data, which core interprets with no plugin code: the trailer keys that
+ *   name a unit, a contract or evidence, the record paths to read for each
+ *   (`units/{id}.json`), and the trailer keys that claim authorship.
+ *
+ * Either way core never parses a plugin's own trailer or record format: it
+ * reads the trailers git reports and hands them over, and a key means
+ * something only because a kind file said so.
+ */
+
+import { z } from "zod";
+
+/** A commit as the hook sees it. */
+export interface IntentCommit {
+  sha: string;
+  subject: string;
+  body: string;
+  author: { name: string; email: string };
+  /** Author date, ISO 8601. */
+  date: string;
+  /** Every trailer git parses from the message, keyed as written, with each value in order. */
+  trailers: Record<string, string[]>;
+}
+
+export interface CommitJoinContext {
+  /** The text of a file from the workspace root, in the tree read; undefined when it is not a file there. */
+  read(path: string): string | undefined;
+  /** The full commit id read with `--at`, or null for the working tree. */
+  at: string | null;
+}
+
+/** A plugin's unit, contract or evidence: an id and whatever fields the plugin records. */
+export interface JoinedEntity {
+  id: string;
+  [field: string]: unknown;
+}
+
+/** What a join says about one commit. Every part is optional. */
+export interface CommitJoin {
+  /** The unit of work that produced the commit. */
+  unit?: JoinedEntity;
+  /** The contract the unit served. */
+  contract?: JoinedEntity;
+  /** The evidence the unit or contract cites. */
+  evidence?: JoinedEntity | JoinedEntity[];
+  /** Trailer keys on this commit that claim who wrote it, which the plugin vouches for. */
+  authorship?: string[];
+}
+
+export type CommitJoinsFunction = (commit: IntentCommit, context: CommitJoinContext) => CommitJoin | null | undefined | Promise<CommitJoin | null | undefined>;
+
+const trailerKey = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9-]*$/, "a trailer key holds letters, digits and dashes");
+const recordPath = z.string().min(1).refine((p) => p.includes("{id}") && !p.startsWith("/") && !p.split("/").includes(".."), "a record path is relative to the workspace root and holds {id}");
+
+/** The data form of `commitJoins`. */
+export const commitJoinsDataSchema = z
+  .object({
+    /** The trailer whose value is the id of the unit, contract or evidence. */
+    trailers: z.object({ unit: trailerKey.optional(), contract: trailerKey.optional(), evidence: trailerKey.optional() }).strict(),
+    /** Where each is recorded, from the workspace root, with `{id}` for the id. A JSON file there adds its fields. */
+    records: z.object({ unit: recordPath.optional(), contract: recordPath.optional(), evidence: recordPath.optional() }).strict().optional(),
+    /** Trailer keys that claim authorship, checked against the commit's provenance. */
+    authorship: z.array(trailerKey).optional(),
+  })
+  .strict();
+
+export type CommitJoinsData = z.infer<typeof commitJoinsDataSchema>;
+
+/** A kind file's `commitJoins` export, checked: a function, or data. */
+export type CommitJoins = { form: "function"; join: CommitJoinsFunction } | { form: "data"; data: CommitJoinsData };
+
+/** Read a kind module's `commitJoins` export. Undefined when it has none; a string when it is malformed. */
+export function readCommitJoins(mod: Record<string, unknown>): CommitJoins | string | undefined {
+  const value = mod.commitJoins;
+  if (value === undefined) return undefined;
+  if (typeof value === "function") return { form: "function", join: value as CommitJoinsFunction };
+  const parsed = commitJoinsDataSchema.safeParse(value);
+  if (!parsed.success) return parsed.error.issues.map((i) => `commitJoins${i.path.length ? `.${i.path.join(".")}` : ""}: ${i.message}`).join("; ");
+  return { form: "data", data: parsed.data };
+}
+
+/** The first value of trailer `key`, compared without case as git does. */
+export function trailerValue(trailers: Record<string, string[]>, key: string): string | undefined {
+  const want = key.toLowerCase();
+  for (const [k, values] of Object.entries(trailers)) if (k.toLowerCase() === want && values.length > 0) return values[0].trim() || undefined;
+  return undefined;
+}
+
+/** Whether the commit carries trailer `key`. */
+export function hasTrailer(trailers: Record<string, string[]>, key: string): boolean {
+  const want = key.toLowerCase();
+  return Object.keys(trailers).some((k) => k.toLowerCase() === want);
+}
+
+function recordFields(template: string | undefined, id: string, context: CommitJoinContext): Record<string, unknown> {
+  if (!template) return {};
+  const text = context.read(template.split("{id}").join(id));
+  if (text === undefined) return {};
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error(`${template.split("{id}").join(id)} is not JSON`);
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+  const { id: _id, ...rest } = value as Record<string, unknown>;
+  return rest;
+}
+
+/** Interpret the data form for one commit. Throws when a named record can't be read as JSON. */
+export function joinByData(data: CommitJoinsData, commit: IntentCommit, context: CommitJoinContext): CommitJoin {
+  const out: CommitJoin = {};
+  for (const part of ["unit", "contract", "evidence"] as const) {
+    const key = data.trailers[part];
+    const id = key ? trailerValue(commit.trailers, key) : undefined;
+    if (!id) continue;
+    const entity: JoinedEntity = { ...recordFields(data.records?.[part], id, context), id };
+    if (part === "evidence") out.evidence = entity;
+    else out[part] = entity;
+  }
+  const claimed = (data.authorship ?? []).filter((k) => hasTrailer(commit.trailers, k));
+  if (claimed.length > 0) out.authorship = claimed;
+  return out;
+}
+
+/** Run a kind's joins for one commit, checking what a function returns. */
+export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, context: CommitJoinContext): Promise<CommitJoin> {
+  if (joins.form === "data") return joinByData(joins.data, commit, context);
+  const result = await joins.join(commit, context);
+  if (result === null || result === undefined) return {};
+  if (typeof result !== "object") throw new Error("commitJoins returned something that is not an object");
+  const entity = (v: unknown, what: string): JoinedEntity | undefined => {
+    if (v === undefined || v === null) return undefined;
+    if (typeof v !== "object" || Array.isArray(v) || typeof (v as JoinedEntity).id !== "string" || (v as JoinedEntity).id === "") {
+      throw new Error(`commitJoins returned a ${what} with no string id`);
+    }
+    return v as JoinedEntity;
+  };
+  const out: CommitJoin = {};
+  const unit = entity(result.unit, "unit");
+  const contract = entity(result.contract, "contract");
+  if (unit) out.unit = unit;
+  if (contract) out.contract = contract;
+  if (result.evidence !== undefined && result.evidence !== null) {
+    const list = Array.isArray(result.evidence) ? result.evidence : [result.evidence];
+    out.evidence = list.map((e) => entity(e, "evidence")!).filter(Boolean);
+  }
+  if (result.authorship !== undefined) {
+    if (!Array.isArray(result.authorship) || !result.authorship.every((k) => typeof k === "string")) throw new Error("commitJoins returned authorship that is not a list of trailer keys");
+    out.authorship = result.authorship;
+  }
+  return out;
+}