@intentius/chant 0.101.0 → 0.104.0

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

@@ -402,6 +402,19 @@
             "$ref": "#/$defs/recordRef"
           },
           "description": "Each other decision whose window holds the commit and whose path: entries cover one of the commit's files."
+        },
+        "joins": {
+          "$ref": "#/$defs/trailerJoins"
+        },
+        "runs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/runRef"
+          },
+          "description": "The agent runs that made the commit (#3033). Added within version 1, so an older document may lack it."
+        },
+        "squash": {
+          "$ref": "#/$defs/squash"
         }
       }
     },
@@ -463,7 +476,8 @@
         "code": {
           "enum": [
             "intent-history-shallow",
-            "intent-plugin-failed"
+            "intent-plugin-failed",
+            "squash-unfollowed"
           ]
         },
         "message": {
@@ -524,6 +538,327 @@
         },
         "commits": false
       }
+    },
+    "trailerJoins": {
+      "type": "object",
+      "description": "What chant's own commit trailers join the commit to (#3149, ws-075). Added within version 1, so an older document may lack it.",
+      "required": [
+        "agent",
+        "lease",
+        "run",
+        "records",
+        "applied"
+      ],
+      "properties": {
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Agent: the agent session that wrote the commit (ws-067)."
+        },
+        "lease": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "token",
+                "item"
+              ],
+              "properties": {
+                "token": {
+                  "type": "string",
+                  "description": "Chant-Lease: the work lease's fencing token."
+                },
+                "item": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The work item a lease history on the local chant/lifecycle branch names for the token, or null when none does."
+                }
+              }
+            }
+          ]
+        },
+        "run": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Run: the agent run that made the commit (#3033)."
+        },
+        "records": {
+          "type": "array",
+          "description": "Each well-formed Chant-Record value, <kind>:<id>, in order.",
+          "items": {
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "node"
+            ],
+            "properties": {
+              "kind": {
+                "type": "string",
+                "description": "The record kind's name."
+              },
+              "id": {
+                "type": "string"
+              },
+              "node": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The id of the record's node, record:<kind>/<id>, when a kind read has the record; null otherwise."
+              }
+            }
+          }
+        },
+        "applied": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "by",
+                "at",
+                "commit"
+              ],
+              "properties": {
+                "by": {
+                  "type": "string",
+                  "description": "Chant-Applied-By: who applied the branch."
+                },
+                "at": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-At, ISO 8601, or null when it is missing."
+                },
+                "commit": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-Commit: the applied branch's tip, or null when it is missing or not a commit id."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "runRef": {
+      "type": "object",
+      "description": "An agent run that made the commit (#3033).",
+      "required": [
+        "id",
+        "recorded",
+        "state",
+        "harness",
+        "model",
+        "provider",
+        "by",
+        "agent",
+        "unit",
+        "joinedBy"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "recorded": {
+          "type": "boolean",
+          "description": "Whether the run ledger on the local chant/lifecycle branch has the run. When false, only the id is known."
+        },
+        "state": {
+          "enum": [
+            "running",
+            "ended",
+            null
+          ]
+        },
+        "harness": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "provider": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "by": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The principal the run worked for."
+        },
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "unit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The work item it worked on."
+        },
+        "joinedBy": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "trailer",
+              "record",
+              "patch-id",
+              "squash"
+            ]
+          },
+          "description": "trailer: the commit carries Chant-Run with the run's id. record: the run's end lists the commit. patch-id: neither holds, and the commit's git patch-id --stable equals a commit's the run's end recorded, as after a rebase or a cherry-pick that dropped the trailer (#3036); never alongside the others. Added within version 1. squash: the commit squashes a pull request whose original commits join the run one of those ways, and the read was asked to follow squashes (#3035); via names them. Added within version 1."
+        },
+        "recordedAs": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "For a patch-id join (#3036): the commit the run's end recorded with the same patch-id, which this one rewrites. Added within version 1."
+        },
+        "via": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40,64}$"
+          },
+          "description": "For a squash join (#3035): the pull request's original commits through which the commit joins the run, oldest first. Added within version 1."
+        }
+      }
+    },
+    "squash": {
+      "type": "object",
+      "description": "Present only when the read follows squashes (--follow-squash, #3035) and the commit squashes a pull request: its subject ends with (#<n>), it has one parent, and the pull request's head is not in its history. The commit carries what the original commits' trailers carry and joins their runs. Added within version 1.",
+      "required": [
+        "pullRequest",
+        "forge",
+        "ref",
+        "head",
+        "fetched",
+        "followed",
+        "commits"
+      ],
+      "properties": {
+        "pullRequest": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "forge": {
+          "enum": [
+            "github",
+            "forgejo",
+            null
+          ],
+          "description": "The forge origin points at, from its URL, or null for one chant doesn't know or no origin. Both keep the pull request's head at refs/pull/<n>/head."
+        },
+        "ref": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The local ref the head was read from: refs/chant/pull/<n>/head where a read fetched it, refs/pull/<n>/head, or refs/remotes/origin/pr/<n>. Null when none could be read."
+        },
+        "head": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^[0-9a-f]{40,64}$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The pull request's head commit, or null."
+        },
+        "fetched": {
+          "type": "boolean",
+          "description": "Whether this read fetched the ref from origin."
+        },
+        "followed": {
+          "type": "boolean",
+          "description": "Whether the original commits were read. When false, squash-unfollowed in reasons says why, and commits is empty."
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "sha",
+              "subject",
+              "author",
+              "date",
+              "trailers",
+              "joins"
+            ],
+            "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"
+              },
+              "trailers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "joins": {
+                "$ref": "#/$defs/trailerJoins"
+              }
+            }
+          },
+          "description": "The original commits, oldest first: the head's commits the squash's parent doesn't have, merges left out."
+        }
+      }
     }
   }
 }

package/src/workspace/intent-record.ts

@@ -17,7 +17,8 @@
  *
  * - `own`: the record's own work, as the region walk judges it: a commit a
  *   plugin joins to a unit whose unit or contract names the record, or that
- *   serves a contract the record constrains.
+ *   serves a contract the record constrains; or a commit whose own trailers
+ *   (#3149) name the record, or a work item that implements it.
  * - `worked`: inside the window of a work item that is not dropped and that
  *   implements the record, or whose `path:` entries cover a file the commit
  *   changed in the record's region.
@@ -28,12 +29,16 @@
  * `workedBy` and `alsoWithin` list every work item and other decision that
  * matched, whatever the bucket. `issue` and `contract` entries are listed and
  * not walked: they name no path. Git is read through a local `git`
- * subprocess only: no fetch, no network.
+ * subprocess only: no fetch, no network, unless the walk is asked to follow
+ * squashes (#3035). Then a squash commit lists its pull request's original
+ * commits, joins their runs and counts as the record's own work when one of
+ * them carries it, and a pull request ref the clone lacks is fetched from
+ * `origin`.
  */
 
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
 import { declaredKindFile } from "./declared-kinds";
-import { entityDecisions, runCommitJoins } from "./intent-joins";
+import { entityDecisions, runCommitJoins, type IntentCommit } from "./intent-joins";
 import {
   addingCommit,
   closingCommit,
@@ -52,6 +57,9 @@ import { constraintCovers, isWorkspacePath, memberHolding } from "./record-asset
 import type { DecidedIn } from "./record-decided";
 import { RecordReadError } from "./records";
 import type { RecordView } from "./records-cli";
+import { addSquashRuns, runsForCommits, type RunRef } from "./runs";
+import { followSquashes, type Forge, type SquashFollow } from "./squash";
+import { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
 import { joinPath } from "./tree";
 import { locateWorkspace } from "./which-chant";
 import { idList } from "./work";
@@ -91,6 +99,20 @@ export interface RecordCommit {
   pullRequest: number | null;
   /** The unit a plugin joined the commit to, or null. */
   unit: string | null;
+  /** What chant's own trailers join the commit to (#3149), as a commit node in `graph --intent` reports it. */
+  joins: CommitTrailerJoins;
+  /** The agent runs that made the commit (#3033): the one its Chant-Run names, and any whose record lists it. */
+  runs: RunRef[];
+  /** Only when the walk follows squashes (#3035) and the commit squashes a pull request: its original commits and what their trailers join. */
+  squash?: {
+    pullRequest: number;
+    forge: Forge | null;
+    ref: string | null;
+    head: string | null;
+    fetched: boolean;
+    followed: boolean;
+    commits: { sha: string; subject: string; author: { name: string; email: string }; date: string; trailers: Record<string, string[]>; joins: CommitTrailerJoins }[];
+  };
   /** The record's constrains entries whose history listed the commit. */
   entries: string[];
   /** The files the commit changed in the record's region, from the workspace root. Empty when git lists none, as for a merge that changed nothing against its first parent there. */
@@ -139,6 +161,8 @@ export interface IntentRecordQuery {
   record: string;
   at?: string;
   kinds?: string[];
+  /** Follow squash merges to their pull requests' original commits, fetching a missing pull request ref from `origin` (#3035). */
+  followSquash?: boolean;
 }
 
 export interface IntentRecordResult {
@@ -241,6 +265,13 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
   const own = decisionWindow(hit.kind, view);
   const shas = [...listed.keys()].filter((sha) => inWindow(own, sha));
   const details = commitDetails(top, shas);
+  // Squash merges, followed to the pull request's original commits when asked (#3035).
+  const follows = query.followSquash ? followSquashes(top, [...details.values()], { fetchMissing: true }) : new Map<string, SquashFollow>();
+  for (const f of follows.values()) {
+    if (f.problem) reasons.push({ code: "squash-unfollowed", message: `${f.sha.slice(0, 8)} squashes pull request #${f.pullRequest}, and ${f.problem}, so its original commits are not followed` });
+  }
+  const originalDetails = commitDetails(top, [...new Set([...follows.values()].flatMap((f) => f.commits))]);
+  const originalsOf = (sha: string): IntentCommit[] => (follows.get(sha)?.commits ?? []).map((o) => originalDetails.get(o)).filter((x): x is IntentCommit => x !== undefined);
   // Newest first by commit date, as git log lists them.
   const order = (shas.length > 0 ? tryGit(top, ["rev-list", "--no-walk=sorted", "--stdin"], `${shas.join("\n")}\n`) : "")?.split("\n").map((s) => s.trim()).filter(Boolean) ?? shas;
   shas.sort((a, b) => order.indexOf(a) - order.indexOf(b));
@@ -299,28 +330,62 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
   const failedPlugins = new Set<string>();
   const constrainedContracts = constrains.filter((c) => c.granularity === "contract").map((c) => c.entry);
   const commits: RecordCommit[] = [];
+  // chant's own trailers (#3149): the record named outright, or a work item that implements it.
+  const trailerJoins = readTrailerJoins(top, [...details.values(), ...originalDetails.values()]);
+  const recordKinds = new Map(kinds.filter((k) => k.records).map((k) => [k.records!.loaded.kind.name, k]));
+  const workKinds = kinds.filter((k) => k.records?.loaded.kind.work);
+  const runJoins = await runsForCommits(
+    top,
+    located.rootOnDisk,
+    [...new Set([...shas, ...originalDetails.keys()])].map((sha) => ({ sha, run: trailerJoins.get(sha)?.joins.run ?? null })),
+  );
+  addSquashRuns(runJoins.refs, follows);
+  const workImplements = (k: LoadedKind, id: string): boolean | undefined => {
+    const v = k.records!.views.find((x) => x.id === id);
+    return v ? idList(v.data, k.records!.loaded.kind.work!.implements).includes(view.id!) : undefined;
+  };
   for (const sha of shas) {
     const c = details.get(sha);
     if (!c) continue;
     let unit: string | null = null;
     let isOwn = false;
+    const joins = trailerJoins.get(sha)!.joins;
+    const originals = originalsOf(sha);
+    // The commit's own trailers, and a followed squash's original commits' (#3035).
+    for (const j of [joins, ...originals.map((o) => trailerJoins.get(o.sha)!.joins)]) {
+      for (const r of j.records) {
+        const k = recordKinds.get(r.kind);
+        if (!k || !k.records!.views.some((v) => v.id === r.id)) continue;
+        r.node = `record:${r.kind}/${r.id}`;
+        if (k.records!.loaded.kind.work ? workImplements(k, r.id) : r.kind === kind.name && r.id === view.id) isOwn = true;
+      }
+      const item = j.lease?.item;
+      if (item) {
+        const holding = workKinds.filter((k) => k.records!.views.some((v) => v.id === item));
+        if (holding.length === 1 && workImplements(holding[0], item)) isOwn = true;
+      }
+    }
+    const subjects: IntentCommit[] = [c, ...originals];
     for (const k of kinds) {
       if (!k.joins) continue;
-      let result;
-      try {
-        result = await runCommitJoins(k.joins, c, { read: readAt, list: listAt, at: located.at }, k.name);
-      } catch (err) {
-        const message = `${k.display}: commitJoins failed for ${sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
-        if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
-        failedPlugins.add(message);
-        continue;
+      for (const subject of subjects) {
+        let result;
+        try {
+          result = await runCommitJoins(k.joins, subject, { read: readAt, list: listAt, at: located.at }, k.name);
+        } catch (err) {
+          const message = `${k.display}: commitJoins failed for ${subject.sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
+          if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
+          failedPlugins.add(message);
+          continue;
+        }
+        if (!result.unit) continue;
+        unit ??= result.unit.id;
+        const named = [...entityDecisions(result.unit), ...entityDecisions(result.contract)];
+        if (named.some((x) => x === view.id || x === `${kind.name}/${view.id}`)) isOwn = true;
+        if (result.contract && constrainedContracts.includes(result.contract.id)) isOwn = true;
       }
-      if (!result.unit) continue;
-      unit ??= result.unit.id;
-      const named = [...entityDecisions(result.unit), ...entityDecisions(result.contract)];
-      if (named.some((x) => x === view.id || x === `${kind.name}/${view.id}`)) isOwn = true;
-      if (result.contract && constrainedContracts.includes(result.contract.id)) isOwn = true;
     }
+    const f = follows.get(sha);
     const changed = (files.get(sha) ?? []).map((f) => joinPath(workspacePrefix, f));
     const covers = (paths: string[]) => paths.some((p) => changed.some((f) => constraintCovers(p, f)));
     const workedBy = works.filter((w) => inWindow(w.window, sha) && (w.implementsRecord || covers(w.paths))).map((w) => w.ref);
@@ -334,6 +399,21 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
       trailers: c.trailers,
       pullRequest: pr ? Number(pr[1]) : null,
       unit,
+      joins,
+      runs: runJoins.refs.get(sha) ?? [],
+      ...(f
+        ? {
+            squash: {
+              pullRequest: f.pullRequest,
+              forge: f.forge,
+              ref: f.ref,
+              head: f.head,
+              fetched: f.fetched,
+              followed: f.followed,
+              commits: originals.map((o) => ({ sha: o.sha, subject: o.subject, author: o.author, date: o.date, trailers: o.trailers, joins: trailerJoins.get(o.sha)!.joins })),
+            },
+          }
+        : {}),
       entries: listed.get(sha)!,
       files: files.get(sha) ?? [],
       bucket: isOwn ? "own" : workedBy.length > 0 ? "worked" : alsoWithin.length > 0 ? "within-other" : "unexplained",

package/src/workspace/intent-reviews.test.ts

@@ -0,0 +1,76 @@
+/**
+ * From a commit back to the review that asked for it (#3154, E21 in
+ * arugula-salad/hud#823): a review session's comments[].follow_ups name a
+ * work item, a builder's commit carries that item with `Chant-Record:
+ * work:<id>`, and `graph --intent` lists the session on the work node.
+ *
+ * The workspace is a copy of the reference workspace, where W-001
+ * constrains design/screens/home.json, with one open review session added.
+ */
+
+import { cpSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, scratchDir } from "./__fixtures__/contract-repo";
+import { intentGraph, type CommitNode, type WorkNode } from "./intent";
+import intentSchema from "./intent.schema.json";
+
+afterAll(cleanScratch);
+
+const intent = contract(intentSchema);
+
+const SESSION = `---
+${JSON.stringify(
+  {
+    schema: 1,
+    id: "S-0002",
+    title: "Review of the home page",
+    state: "open",
+    agenda: [{ text: "The home page as built" }],
+    attendance: [{ principal: "alice", class: "person" }],
+    opened: "2026-10-03T10:00:00Z",
+    closed: null,
+    verdicts: [],
+    comments: [
+      { text: "The header is cut off." },
+      { text: "The hero image should follow the spec.", follow_ups: ["work:W-001"] },
+      { text: "Same for the footer.", follow_ups: ["work:W-001", "work:W-404"] },
+    ],
+  },
+  null,
+  2,
+)}
+---
+
+# Review of the home page
+`;
+
+function workspace(): string {
+  const root = scratchDir("chant-intent-reviews-");
+  cpSync(join(REPO, "reference-workspace"), root, { recursive: true, filter: (src) => !/[\\/](node_modules|dist)$/.test(src) });
+  writeFileSync(join(root, "design", "sessions", "S-0002-review-of-the-home-page.md"), SESSION);
+  const g = (...a: string[]) => git(root, ...a);
+  g("init", "-q");
+  g("add", "-A");
+  g("commit", "-q", "-m", "the workspace");
+  g("branch", "-M", "main");
+  writeFileSync(join(root, "design", "screens", "home.json"), `${JSON.stringify({ regions: ["header", "hero", "footer"] }, null, 2)}\n`);
+  g("add", "-A");
+  g("commit", "-q", "-m", "the hero follows the spec", "-m", "Chant-Record: work:W-001");
+  return root;
+}
+
+describe("graph --intent joins a work item back to the review that asked for it (#3154, E21)", () => {
+  test("the work node lists the session and the comments whose follow_ups name it, and the builder's commit carries the item", async () => {
+    const root = workspace();
+    const head = git(root, "rev-parse", "HEAD");
+    const { doc } = await intentGraph({ cwd: root, region: "design/screens/home.json" });
+    intent.expectValid(doc);
+    if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+    const w = doc.nodes.find((n) => n.id === "record:work/W-001") as WorkNode;
+    expect(w.reviews).toEqual([{ id: "record:session/S-0002", recordKind: "session", record: "S-0002", path: "design/sessions/S-0002-review-of-the-home-page.md", state: "open", comments: [2, 3] }]);
+    const c = doc.nodes.find((n) => n.id === `commit:${head}`) as CommitNode;
+    expect(c).toBeDefined();
+    expect(doc.edges).toContainEqual({ kind: "carries", from: c.id, to: w.id });
+  });
+});