@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/intent.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/intent/v1/intent.schema.json",
   "title": "chant workspace graph --intent output",
-  "description": "What `chant workspace graph --intent <region> --json` prints: the intent graph over one region of a workspace (#2651, #2650 section C1, #2524 D8 and D15). The region, the commits that touched it, the decisions whose constrains cover it and their supersession chains, the artifacts those decisions pin, the units, contracts and evidence a plugin joins to the commits, the member links of the region's member, and findings as nodes with closed codes. chant emits it and a reader such as hud draws it. Readers ignore fields and node or edge kinds they do not know; a field is only ever added within a version. The finding, reason and error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2651; a chant without --intent refuses the flag. Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace graph --intent <region> --json` prints: the intent graph over one region of a workspace (#2651, #2650 section C1, #2524 D8 and D15). The region, the commits that touched it, the decisions whose constrains cover it and their supersession chains, the work items whose constrains cover it (#2683), the artifacts those decisions pin, the units, contracts and evidence a plugin joins to the commits, the member links of the region's member, and findings as nodes with closed codes. chant emits it and a reader such as hud draws it. Readers ignore fields and node or edge kinds they do not know; a field is only ever added within a version. The finding, reason and error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2651; a chant without --intent refuses the flag. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -116,7 +116,7 @@
               },
               "name": {
                 "type": "string",
-                "description": "The kind's name: the record kind's name, or the file's name without .kind.mjs for a plugin with no records. A plugin's findings use it as their namespace, plugin:<name>:<code> (#2656). Added within version 1, so an older document may lack it."
+                "description": "The kind's name: the file's commitJoinsName export when it has one (#2663), else the record kind's name, or the file's name without .kind.mjs for a plugin with no records. A plugin's findings use it as their namespace, plugin:<name>:<code> (#2656). Added within version 1, so an older document may lack it."
               },
               "records": {
                 "type": [
@@ -126,6 +126,7 @@
                 "description": "The record kind's name, or null for a plugin with no records."
               },
               "joins": {
+                "description": "The form of the file's commitJoins export: a function commitJoins(commit, context), whose context has read(path) for a file and list(dir) for a directory's entries, both from the workspace root in the tree read (#2663); data, naming the trailers and record paths core reads, with every value of the evidence trailer read; or null when it has none.",
                 "enum": [
                   "function",
                   "data",
@@ -204,6 +205,9 @@
         {
           "$ref": "#/$defs/decision"
         },
+        {
+          "$ref": "#/$defs/work"
+        },
         {
           "$ref": "#/$defs/artifact"
         },
@@ -713,6 +717,240 @@
         }
       }
     },
+    "work": {
+      "description": "A work item (#2683), a record of a kind with a work block: in the graph when its constrains cover the region as a decision's would, or when a work item there implements, needs or addresses it. Read only when a work kind is passed with --kind.",
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "recordKind",
+        "record",
+        "path",
+        "title",
+        "state",
+        "closed",
+        "valid",
+        "reasons",
+        "provenance",
+        "owner",
+        "ready",
+        "blockedBy",
+        "implements",
+        "needs",
+        "source",
+        "supersededBy",
+        "constrains",
+        "warnings"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^record:"
+        },
+        "kind": {
+          "const": "work"
+        },
+        "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"
+          ]
+        },
+        "closed": {
+          "type": "boolean",
+          "description": "Whether the kind counts the state as closed, such as done or dropped."
+        },
+        "valid": {
+          "type": "boolean"
+        },
+        "reasons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "record-unparseable",
+                  "record-schema-invalid",
+                  "record-id-duplicate",
+                  "record-supersedes-unknown",
+                  "record-supersedes-conflict"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "provenance": {
+          "type": "object",
+          "required": [
+            "level",
+            "commit",
+            "reason"
+          ],
+          "properties": {
+            "level": {
+              "enum": [
+                "attested",
+                "attested-unverifiable-here",
+                "adopted",
+                "unattested"
+              ]
+            },
+            "commit": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{40,64}$"
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        },
+        "owner": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The principal the record names as its owner, or null."
+        },
+        "ready": {
+          "type": "boolean",
+          "description": "As records reports it: valid, not superseded, in the kind's open state, and every need done."
+        },
+        "blockedBy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/workLink"
+          },
+          "description": "Each need that is not done, with its state."
+        },
+        "implements": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/workLink"
+          },
+          "description": "Each decision the item implements, with its state."
+        },
+        "needs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The work ids the item's needs list names."
+        },
+        "source": {
+          "description": "The gap the item came from, when its source names one: a finding code, the region it fired on, and optionally the decision and artifact it concerned. Null for an item whose source is an issue or the workspace.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "finding",
+                "region"
+              ],
+              "properties": {
+                "finding": {
+                  "type": "string"
+                },
+                "region": {
+                  "type": "string"
+                },
+                "decision": {
+                  "type": "string"
+                },
+                "artifact": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        },
+        "supersededBy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "constrains": {
+          "type": "array",
+          "description": "The entries that cover the region, with their granularity, matched as a decision's are. Empty for an item in the graph only through a link.",
+          "items": {
+            "type": "object",
+            "required": [
+              "entry",
+              "granularity"
+            ],
+            "properties": {
+              "entry": {
+                "type": "string"
+              },
+              "granularity": {
+                "enum": [
+                  "path",
+                  "member",
+                  "contract",
+                  "issue"
+                ]
+              }
+            }
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "description": "The item's work warnings as records reports them, and work-done-gap-open: the item is done and the finding in its source still fires on its region. records raises it too, by walking the source's region with this code (#2686).",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "work-needs-unknown",
+                  "work-implements-unknown",
+                  "work-needs-cycle",
+                  "work-implements-undecided",
+                  "work-done-unpinned",
+                  "work-closed-without-date",
+                  "work-done-gap-open"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
     "artifact": {
       "description": "A workspace file a decision in the graph pins. Artifacts reach the region only through decisions (#2549).",
       "type": "object",
@@ -850,14 +1088,19 @@
                 "intent-commit-bare",
                 "intent-pin-drifted",
                 "intent-pin-missing",
+                "intent-pin-stale",
                 "intent-artifact-unpinned",
                 "intent-decision-superseded-live",
                 "intent-decision-provisional",
+                "intent-decision-contested",
                 "intent-constraint-coarse",
                 "intent-constraint-lost",
                 "intent-evidence-unpinned",
                 "intent-trailer-unverified",
-                "intent-region-unconstrained"
+                "intent-region-unconstrained",
+                "intent-decision-unimplemented",
+                "intent-work-blocked",
+                "intent-work-open-decided-code"
               ]
             },
             {
@@ -887,11 +1130,42 @@
             "type": "string"
           },
           "description": "For a plugin's finding: the refs as the plugin gave them. Those that name a node in the graph are resolved to its id in concerns, after the commit the finding was returned for."
+        },
+        "openConcerns": {
+          "type": "object",
+          "description": "Added by #2686, on intent-decision-contested only: how many open concerns the decision's quorum reports, dissents neither addressed nor withdrawn, and the principals who raised them, normalised as the quorum compares them.",
+          "required": [
+            "count",
+            "principals"
+          ],
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "principals": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "addressed": {
+          "type": "boolean",
+          "description": "Added by #2683, present when a work kind was read: whether a work item addresses the finding, because the item's source names this finding code on a region that contains or is contained by this one, or because the item implements a decision the finding concerns. A finding with addressed false is work nobody has taken yet."
+        },
+        "addressedBy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/workLink"
+          },
+          "description": "Added by #2683, present when a work kind was read: the work items addressing the finding, each with its state. Each has an addressed-by edge from the finding."
         }
       }
     },
     "edge": {
-      "description": "constrains: decision to region, file or contract. pins: decision to artifact. touched-by: region to commit. produced-by: commit to unit. serves: unit to contract. supersedes: the newer decision to the one it replaces. cites-evidence: unit, contract or decision to evidence. links: consumer member to producer member. within: commit to a decision whose path window it falls in.",
+      "description": "constrains: decision or work item to region, file or contract. pins: decision to artifact. touched-by: region to commit. produced-by: commit to unit. serves: unit to contract. supersedes: the newer decision to the one it replaces. cites-evidence: unit, contract or decision to evidence. links: consumer member to producer member. within: commit to a decision whose path window it falls in, or to a work item whose window it falls in. implements: work item to the decision it carries out. needs: work item to a work item it waits on. addressed-by: finding to a work item that addresses it.",
       "oneOf": [
         {
           "$ref": "#/$defs/constrainsEdge"
@@ -1105,13 +1379,16 @@
             "serves",
             "supersedes",
             "cites-evidence",
-            "links"
+            "links",
+            "implements",
+            "needs",
+            "addressed-by"
           ]
         }
       }
     },
     "withinEdge": {
-      "description": "A commit made inside a decision's window, from the commit that added the decision's record until the one that added its successor (#2656). state is decided when the decision's own unit made the commit, and decided-by-window otherwise.",
+      "description": "A commit made inside a decision's window, from the commit that added the decision's record until the one that added its successor (#2656). state is decided when the decision's own unit made the commit, and decided-by-window otherwise. Added by #2683: a commit made inside a work item's window, from the commit that added the record to the commit that closed it, that commit included, or to the revision read while it is open, has state worked. A worked edge leaves the commit's own state as the decisions set it.",
       "type": "object",
       "required": [
         "kind",
@@ -1132,10 +1409,30 @@
         "state": {
           "enum": [
             "decided",
-            "decided-by-window"
+            "decided-by-window",
+            "worked"
           ]
         }
       }
+    },
+    "workLink": {
+      "type": "object",
+      "required": [
+        "id",
+        "state"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The linked record's state, or null when no record has the id."
+        }
+      }
     }
   }
 }

package/src/workspace/intent.test.ts

@@ -443,6 +443,8 @@ describe("findings the fixture does not raise (#2651)", () => {
         expect(findings(doc).map(([c]) => c)).toEqual([
           "intent-commit-undecided",
           "intent-commit-bare",
+          // dec-002 supersedes dec-001 and pins the spec at the hash dec-001 pinned, unchanged since (#2686).
+          "intent-pin-stale",
           "intent-decision-provisional",
           "intent-constraint-coarse",
           "intent-constraint-lost",
@@ -564,3 +566,100 @@ describe("reads that fail, and parts that can't be read (#2651)", () => {
     expect(parseRegion("a/b.ts:0")).toHaveProperty("error");
   });
 });
+
+describe("commitJoins lists records and names its findings (#2663)", () => {
+  test("a plugin joins commits by listing its records, with no trailer at all (#2663)", async () => {
+    const SCAN = `
+export function commitJoins(commit, context) {
+  const walk = (dir) => (context.list(dir) ?? []).flatMap((p) => (p.endsWith("/") ? walk(p) : [p]));
+  for (const path of walk("unit-records")) {
+    const id = path.split("/").at(-1).replace(/\\.(json|md)$/, "");
+    const text = context.read(path);
+    if (path.endsWith(".json")) {
+      const record = JSON.parse(text);
+      if (record.result?.commit !== commit.sha) continue;
+      const probe = { missing: context.list("nope"), escape: context.list(".."), file: context.list(path), root: context.list(".").includes("unit-records/") };
+      return { unit: { id, path, probe }, contract: { id: record.contract } };
+    }
+    if (text.includes(commit.sha)) return { unit: { id, path } };
+  }
+  return undefined;
+}
+`;
+    writeFiles(root, {
+      "plugins/scan.kind.mjs": SCAN,
+      "unit-records/U-0100.json": JSON.stringify({ contract: "C-100", result: { commit: sha.c2 } }),
+      "unit-records/archive/U-0104.md": `---\nid: U-0104\n---\n\nLanded as ${sha.c4}.\n`,
+    });
+    commit(["record the units after their commits"]);
+    try {
+      const doc = await walk("app/server.mjs", { kinds: [KIND, "plugins/scan.kind.mjs"] });
+      // c4 carries no trailer; the markdown record in a subdirectory names it.
+      expect(node(doc, `commit:${sha.c4}`)).toMatchObject({ trailers: {} });
+      expect(doc.edges).toContainEqual({ kind: "produced-by", from: `commit:${sha.c4}`, to: "unit:U-0104" });
+      expect(node(doc, "unit:U-0104")).toMatchObject({ data: { path: "unit-records/archive/U-0104.md" } });
+      expect(doc.edges).toContainEqual({ kind: "produced-by", from: `commit:${sha.c2}`, to: "unit:U-0100" });
+      expect(doc.edges).toContainEqual({ kind: "serves", from: "unit:U-0100", to: "contract:C-100" });
+      expect(node(doc, "unit:U-0100")).toMatchObject({ data: { path: "unit-records/U-0100.json", probe: { root: true } } });
+      // Not a directory there, or outside the workspace: undefined.
+      expect((node(doc, "unit:U-0100") as { data: unknown }).data).toMatchObject({ probe: { missing: undefined, escape: undefined, file: undefined, root: true } });
+      expect(node(doc, `commit:${sha.c2b}`) && doc.edges.some((e) => e.kind === "produced-by" && e.from === `commit:${sha.c2b}`)).toBe(false);
+      expect(doc.reasons).toEqual([]);
+
+      // At c4 the records were not written yet: list answers from the tree read, so nothing joins.
+      const before = await walk("app/server.mjs", { kinds: [KIND, "plugins/scan.kind.mjs"], at: sha.c4 });
+      expect(before.nodes.filter((n) => n.kind === "unit")).toEqual([]);
+      expect(before.reasons).toEqual([]);
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+
+  test("commitJoinsName names a plugin's findings apart from its record kind's name (#2663)", async () => {
+    const NAMED = (name: string) => `
+export { recordKind } from "./decision.kind.mjs";
+export const commitJoinsName = ${JSON.stringify(name)};
+export function commitJoins(commit) {
+  if (commit.trailers["Unit"]?.[0] !== "U-0002") return undefined;
+  return { findings: [{ code: "plugin:studio:contract-moved", message: "moved", refs: [commit.sha] }] };
+}
+`;
+    writeFiles(root, { "decisions/studio.kind.mjs": NAMED("studio"), "decisions/other.kind.mjs": NAMED("other") });
+    commit(["name the findings"]);
+    try {
+      const doc = await walk("app/server.mjs", { kinds: ["decisions/studio.kind.mjs"] });
+      expect(doc.kinds).toEqual([{ file: "decisions/studio.kind.mjs", name: "studio", records: "decision", joins: "function" }]);
+      expect(doc.reasons).toEqual([]);
+      expect(doc.nodes).toContainEqual(expect.objectContaining({ kind: "finding", code: "plugin:studio:contract-moved", concerns: [`commit:${sha.c2b}`] }));
+      // The decisions still come from the record kind called decision.
+      expect(node(doc, "record:decision/dec-001")).toBeDefined();
+
+      // Under another name, the same code is outside the namespace, and the record kind's name is no longer it either.
+      const { doc: other, failed } = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [join(root, "decisions/other.kind.mjs")] });
+      expectValid(other);
+      if ("error" in other) throw new Error(other.error.message);
+      expect(failed).toBe(true);
+      expect(other.reasons).toEqual([{ code: "intent-plugin-failed", message: expect.stringContaining("plugin:other:<code>") }]);
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+
+  test("a malformed commitJoinsName is kind-invalid (#2663)", async () => {
+    writeFiles(root, { "plugins/badname.kind.mjs": `export const commitJoinsName = "a:b";\nexport function commitJoins() {}\n`, "plugins/nameonly.kind.mjs": `export const commitJoinsName = "x";\n` });
+    commit(["malformed names"]);
+    try {
+      for (const [file, text] of [
+        ["plugins/badname.kind.mjs", "no colon or space"],
+        ["plugins/nameonly.kind.mjs", "no commitJoins"],
+      ]) {
+        const { doc } = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [join(root, file)] });
+        expectValid(doc);
+        expect("error" in doc && doc.error.code).toBe("kind-invalid");
+        expect("error" in doc && doc.error.message).toContain(text);
+      }
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+});