@intentius/chant 0.124.28 → 0.124.30

package/dist/workspace/intent.js

@@ -1,6 +1,6 @@
 /**
  * The intent graph over one region: `chant workspace graph --intent
- * <path[:start-end]|path#symbol>` (#2651; #2650 sections B and C1; #2524 D8,
+ * <path[:start-end]|path#symbol|member/node|sha>` (#2651; #2650 sections B and C1; #2524 D8,
  * D15; #3034).
  *
  * A person points at some code and asks how it got this way and who decided
@@ -75,6 +75,7 @@ import { followSquashes, squashLineOrigins } from "./squash.js";
 import { memberDirOnDisk, memberSymbolResolvers } from "./lexicon-symbols.js";
 import { resolveSymbol, symbolResolverFor } from "./symbols.js";
 import { readTrailerJoins } from "./trailer-joins.js";
+import { buildTrace } from "./intent-trace.js";
 import { joinPath, skippedDir, workingTree } from "./tree.js";
 import { activeAttestors } from "./trust/attestor.js";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance.js";
@@ -303,6 +304,24 @@ export function closingCommit(top, rev, path, stateField, closed) {
     }
     return closing;
 }
+/**
+ * The files a commit changed, from the workspace root (#4023): against its
+ * first parent, or every file for a root commit. Files outside the workspace
+ * are left out.
+ */
+export function changedFiles(top, sha, workspacePrefix) {
+    const out = tryGit(top, ["diff-tree", "--no-commit-id", "-r", "--name-only", "--root", "-m", "--first-parent", "-z", sha]) ?? "";
+    const files = new Set();
+    for (const f of out.split("\0")) {
+        if (!f)
+            continue;
+        if (workspacePrefix === "")
+            files.add(f);
+        else if (f.startsWith(`${workspacePrefix}/`))
+            files.add(f.slice(workspacePrefix.length + 1));
+    }
+    return [...files].sort();
+}
 /** 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, rev, view) {
     return view.decidedIn?.sha ?? addingCommit(top, rev, view.path);
@@ -504,6 +523,8 @@ export async function loadKinds(query, top) {
     }
     return out;
 }
+/** A commit sha as a region may give it: 7 to 64 hex digits. */
+const COMMIT_REGION = /^[0-9a-fA-F]{7,64}$/;
 async function resolveRegion(query, located, declaration) {
     const parsed = parseRegion(query.region);
     if ("error" in parsed)
@@ -553,9 +574,40 @@ async function resolveRegion(query, located, declaration) {
             return { path: file === "" ? "." : file, lines: loc.line ? { start: loc.line, end: loc.line } : null, node: query.region, symbol: null };
         }
     }
-    throw new IntentError("intent-region-invalid", `${query.region} is not a path in the workspace${located.tree.label}, a path#symbol, or a graph node id`);
+    // A commit sha, when no path or node has the name (#4023): the commit and the files it changed.
+    if (COMMIT_REGION.test(query.region) && located.top) {
+        const sha = tryGit(located.top, ["rev-parse", "--verify", "--quiet", `${query.region}^{commit}`])?.trim();
+        if (sha)
+            return { path: ".", lines: null, node: null, symbol: null, commit: sha };
+    }
+    throw new IntentError("intent-region-invalid", `${query.region} is not a path in the workspace${located.tree.label}, a path#symbol, a graph node id or a commit`);
 }
 /** Build the intent document. Never throws an {@link IntentError}, {@link WorkspaceReadError} or {@link RecordReadError}. */
+/**
+ * Give each work node the in-flight items it overlaps by file (#4025). Only a
+ * working-tree read, since the overlap is about the branches as they are now;
+ * a read that fails leaves the field off.
+ */
+async function addOverlaps(work, declaration, root, top, at) {
+    if (work.length === 0 || at !== null)
+        return;
+    let report;
+    try {
+        const { readOverlap } = await import("./overlap.js");
+        report = await readOverlap({ declaration, root, top, changeSets: [] });
+    }
+    catch {
+        return;
+    }
+    if (report === null)
+        return;
+    for (const n of work) {
+        const self = `${n.recordKind}:${n.record}`;
+        n.overlaps = report.pairs
+            .filter((p) => p.items.includes(self) && p.files.length > 0)
+            .map((p) => ({ with: p.items[0] === self ? p.items[1] : p.items[0], files: p.files }));
+    }
+}
 export async function intentGraph(query) {
     const head = { $schema: INTENT_OUTPUT_SCHEMA_ID, contract: INTENT_CONTRACT_VERSION, chant: readerVersion() };
     try {
@@ -575,7 +627,7 @@ async function walk(query, head) {
         throw new IntentError("not-a-git-repository", "the intent graph reads git history, and this directory is not in a git repository");
     const declaration = readDeclaration(located.tree, "", { rootChant: true });
     const region = await resolveRegion(query, located, declaration);
-    const type = region.path === "." ? "dir" : located.tree.stat(region.path);
+    const type = region.commit ? "commit" : region.path === "." ? "dir" : located.tree.stat(region.path);
     if (!type)
         throw new IntentError("intent-region-invalid", `${region.path} does not exist${located.tree.label}`);
     if (region.lines) {
@@ -601,8 +653,21 @@ async function walk(query, head) {
         findings.push({ id: `finding:${code}:${findings.filter((f) => f.code === code).length + 1}`, kind: "finding", code, message, concerns });
     };
     // The region, its files and its member.
-    const member = region.path === "." ? (declaration.members.find((m) => m.dir === ".")?.name ?? null) : memberHolding(region.path, declaration.members);
-    const rid = regionId(region.path, region.lines, region.symbol?.name);
+    // A commit region (#4023) covers the files the commit changed, from the workspace root, and the members holding them.
+    const workspacePrefix = located.root === "." ? "" : located.root;
+    const changed = region.commit ? changedFiles(top, region.commit, workspacePrefix) : [];
+    const changedMembers = [...new Set(changed.map((f) => memberHolding(f, declaration.members)).filter((m) => m !== null))];
+    const member = region.commit
+        ? changedMembers.length === 1
+            ? changedMembers[0]
+            : null
+        : region.path === "."
+            ? (declaration.members.find((m) => m.dir === ".")?.name ?? null)
+            : memberHolding(region.path, declaration.members);
+    const regionMembers = region.commit ? changedMembers : member ? [member] : [];
+    const rid = region.commit ? `region:commit:${region.commit}` : regionId(region.path, region.lines, region.symbol?.name);
+    /** How messages name the region: its path, or the commit. */
+    const regionLabel = region.commit ? `commit ${region.commit.slice(0, 8)}` : region.path;
     add({
         id: rid,
         kind: "region",
@@ -614,6 +679,7 @@ async function walk(query, head) {
         generated: type === "file" ? isGeneratedPath(declaration, region.path) : null,
         node: region.node,
         symbol: region.symbol,
+        ...(region.commit ? { commit: region.commit } : {}),
     });
     const files = type === "dir" ? filesUnder(located.tree, region.path) : [];
     for (const f of files)
@@ -629,9 +695,8 @@ async function walk(query, head) {
     const shallow = tryGit(top, ["rev-parse", "--is-shallow-repository"])?.trim() === "true";
     if (shallow)
         reasons.push({ code: "intent-history-shallow", message: "this is a shallow clone, so the history stops at its boundary and the oldest commit listed may stand for many" });
-    const workspacePrefix = located.root === "." ? "" : located.root;
     const gitPath = joinPath(workspacePrefix, region.path);
-    const touched = rev ? regionHistory(top, rev, gitPath, type, region.lines) : [];
+    const touched = region.commit ? [{ sha: region.commit, lines: null }] : rev && type !== "commit" ? regionHistory(top, rev, gitPath, type, region.lines) : [];
     // Who last wrote each current line of a file region (#3034). A commit blame
     // names and the history walk missed, as when a move confuses git log -L,
     // joins the commits that touched the region.
@@ -848,7 +913,11 @@ async function walk(query, head) {
                 if (!isWorkspacePath(p))
                     continue;
                 const full = joinPath(kindPrefix, p);
-                if (regionFull !== "" && constraintCovers(full, regionFull)) {
+                if (type === "commit") {
+                    if (changed.some((f) => constraintCovers(full, joinPath(workspacePrefix, f))))
+                        matched.push({ entry, granularity: "path", to: rid });
+                }
+                else if (regionFull !== "" && constraintCovers(full, regionFull)) {
                     matched.push({ entry, granularity: "path", to: rid });
                 }
                 else if (type === "dir" && full !== regionFull && (regionFull === "" || full.startsWith(`${regionFull}/`))) {
@@ -858,7 +927,7 @@ async function walk(query, head) {
                 }
             }
             else if (entry.startsWith("member:")) {
-                if (member !== null && entry.slice("member:".length) === member)
+                if (regionMembers.includes(entry.slice("member:".length)))
                     matched.push({ entry, granularity: "member", to: rid });
             }
             else {
@@ -1264,7 +1333,7 @@ async function walk(query, head) {
                 edges.push({ kind: "within", from: c.id, to: h.node.id, state: "worked" });
         }
         if (readsRecords && c.state === "undecided") {
-            find("intent-commit-undecided", `${t.sha.slice(0, 8)} changed the region when no decision constrained ${region.path} by path`, [c.id, rid]);
+            find("intent-commit-undecided", `${t.sha.slice(0, 8)} changed the region when no decision constrained ${regionLabel} by path`, [c.id, rid]);
         }
         if (readsRecords && !j.unit && j.carries.length === 0 && c.pullRequest === null && coveredAt(t.sha, ["path", "member", "contract", "issue"]).length === 0) {
             find("intent-commit-bare", `${t.sha.slice(0, 8)} names no unit, no record, no pull request and no decision`, [c.id]);
@@ -1278,13 +1347,13 @@ async function walk(query, head) {
     if (readsRecords) {
         const current = covering.filter((c) => c.node.supersededBy === null);
         if (covering.length === 0) {
-            find("intent-region-unconstrained", `no decision constrains ${region.path}`, [rid]);
+            find("intent-region-unconstrained", `no decision constrains ${regionLabel}`, [rid]);
         }
         else if (current.length === 0) {
-            find("intent-decision-superseded-live", `every decision constraining ${region.path} is superseded: ${covering.map((c) => `${c.node.record} by ${c.node.supersededBy}`).join(", ")}`, [rid, ...covering.map((c) => c.node.id)]);
+            find("intent-decision-superseded-live", `every decision constraining ${regionLabel} is superseded: ${covering.map((c) => `${c.node.record} by ${c.node.supersededBy}`).join(", ")}`, [rid, ...covering.map((c) => c.node.id)]);
         }
         else if (current.every((c) => !c.node.closed)) {
-            find("intent-decision-provisional", `the decisions constraining ${region.path} are ${[...new Set(current.map((c) => c.node.state ?? "stateless"))].join(" or ")}, and none is in a closed state`, [rid, ...current.map((c) => c.node.id)]);
+            find("intent-decision-provisional", `the decisions constraining ${regionLabel} are ${[...new Set(current.map((c) => c.node.state ?? "stateless"))].join(" or ")}, and none is in a closed state`, [rid, ...current.map((c) => c.node.id)]);
         }
         // A current decision with a dissent nobody addressed or withdrew (#2686), from its quorum.
         for (const c of current) {
@@ -1296,14 +1365,14 @@ async function walk(query, head) {
                 id: `finding:intent-decision-contested:${findings.filter((f) => f.code === "intent-decision-contested").length + 1}`,
                 kind: "finding",
                 code: "intent-decision-contested",
-                message: `${c.node.record} constrains ${region.path} and has ${open.length} open ${open.length === 1 ? "concern" : "concerns"}, from ${open.map((o) => o.reviewer).join(", ")}: a dissent neither addressed nor withdrawn`,
+                message: `${c.node.record} constrains ${regionLabel} and has ${open.length} open ${open.length === 1 ? "concern" : "concerns"}, from ${open.map((o) => o.reviewer).join(", ")}: a dissent neither addressed nor withdrawn`,
                 concerns: [c.node.id, rid],
                 openConcerns: { count: open.length, principals },
             });
         }
         const granularities = new Set(covering.flatMap((c) => c.node.constrains.map((x) => x.granularity)));
         if (covering.length > 0 && !granularities.has("path") && granularities.has("member")) {
-            find("intent-constraint-coarse", `${region.path} is constrained only through its member, ${member}`, [rid, ...covering.map((c) => c.node.id)]);
+            find("intent-constraint-coarse", `${regionLabel} is constrained only through its member, ${regionMembers.join(", ")}`, [rid, ...covering.map((c) => c.node.id)]);
         }
     }
     // Findings about work items (#2683).
@@ -1316,7 +1385,7 @@ async function walk(query, head) {
             const w = windows.get(c.node.id);
             if (w && touched.some((t) => w.from.has(t.sha) && !w.until?.has(t.sha)))
                 continue;
-            find("intent-decision-unimplemented", `${c.node.record} is ${c.node.state} and constrains ${region.path}, and no work item that is not dropped implements it, and no commit changed the region in its window`, [c.node.id, rid]);
+            find("intent-decision-unimplemented", `${c.node.record} is ${c.node.state} and constrains ${regionLabel}, and no work item that is not dropped implements it, and no commit changed the region in its window`, [c.node.id, rid]);
         }
         for (const h of workCovering) {
             const node = h.node;
@@ -1336,7 +1405,7 @@ async function walk(query, head) {
             const impl = implementersOf(d);
             if (impl.length === 0 || impl.some((h) => h.view.state === workSpec(h).done))
                 continue;
-            find("intent-work-open-decided-code", `${own.length} ${own.length === 1 ? "commit" : "commits"} in ${region.path} ${own.length === 1 ? "is" : "are"} ${d.record}'s own work, and ${impl.map((h) => `${h.view.id} is ${h.view.state ?? "stateless"}`).join(", ")}: the code says done and the queue says not`, [d.id, ...own, ...impl.map((h) => workNode(h).id)]);
+            find("intent-work-open-decided-code", `${own.length} ${own.length === 1 ? "commit" : "commits"} in ${regionLabel} ${own.length === 1 ? "is" : "are"} ${d.record}'s own work, and ${impl.map((h) => `${h.view.id} is ${h.view.state ?? "stateless"}`).join(", ")}: the code says done and the queue says not`, [d.id, ...own, ...impl.map((h) => workNode(h).id)]);
         }
     }
     // 5. Links: the declared member links that touch the region's member, read in source.
@@ -1412,6 +1481,8 @@ async function walk(query, head) {
             const kindPrefix = h.kind.records.workspaceRoot === "." ? "" : h.kind.records.workspaceRoot;
             const full = joinPath(kindPrefix, parsed.path);
             const contains = (a, b) => a === b || a === "" || b.startsWith(`${a}/`);
+            if (type === "commit")
+                return changed.some((f) => contains(full, joinPath(workspacePrefix, f)) || contains(joinPath(workspacePrefix, f), full));
             if (!contains(full, regionFull) && !contains(regionFull, full))
                 return false;
             if (full === regionFull && parsed.lines && region.lines)
@@ -1428,7 +1499,7 @@ async function walk(query, head) {
                 if (gap && h.view.state === workSpec(h).done) {
                     const node = workNode(h);
                     if (!node.warnings.some((w) => w.code === "work-done-gap-open")) {
-                        node.warnings.push({ code: "work-done-gap-open", message: `${node.record} is ${h.view.state}, and ${f.code}, the gap it came from, still fires on ${region.path}` });
+                        node.warnings.push({ code: "work-done-gap-open", message: `${node.record} is ${h.view.state}, and ${f.code}, the gap it came from, still fires on ${regionLabel}` });
                     }
                 }
             }
@@ -1474,15 +1545,63 @@ async function walk(query, head) {
     }
     for (const f of findings)
         nodes.set(f.id, f);
+    await addOverlaps([...nodes.values()].filter((n) => n.kind === "work"), declaration, located.rootOnDisk, top, located.at);
     const why = explain();
     const all = [...nodes.values()];
+    // The why chain (#4023): each commit's work item, ci tag, release, gate resolutions and deploys.
+    const workIds = new Map();
+    const workNodeIds = new Map();
+    for (const h of workAll) {
+        const name = h.kind.records.loaded.kind.name;
+        (workIds.get(name) ?? workIds.set(name, new Set()).get(name)).add(h.view.id);
+        if (h.node)
+            workNodeIds.set(`${name}:${h.view.id}`, h.node.id);
+    }
+    for (const k of workKinds)
+        if (!workIds.has(k.records.loaded.kind.name))
+            workIds.set(k.records.loaded.kind.name, new Set());
+    const windowsOf = new Map();
+    for (const e of edges) {
+        if (e.kind !== "within" || e.state !== "worked")
+            continue;
+        const w = nodes.get(e.to);
+        if (!w)
+            continue;
+        const sha = e.from.slice("commit:".length);
+        (windowsOf.get(sha) ?? windowsOf.set(sha, []).get(sha)).push({ id: `${w.recordKind}:${w.record}`, node: w.id, path: w.path });
+    }
+    const later = new Map();
+    const trace = await buildTrace({
+        top,
+        commits: all.filter((n) => n.kind === "commit").map((c) => ({ id: c.id, sha: c.sha, trailers: c.trailers, joins: c.joins })),
+        work: readsWork ? { index: { kinds: workIds }, nodes: workNodeIds } : null,
+        windows: windowsOf,
+        // The region's member's ledger; for a region in no member, every member's and the workspace's own.
+        ledgers: (regionMembers.length > 0 ? regionMembers : declaration.members.map((m) => m.name))
+            .map((name) => {
+            const dir = declaration.members.find((m) => m.name === name).dir;
+            return { member: name, cwd: memberDirOnDisk(located.rootOnDisk, dir), within: dir === "." ? null : `_members/${name}/` };
+        })
+            .concat(regionMembers.length > 0 ? [] : [{ member: null, cwd: located.rootOnDisk, within: null }]),
+        green: declaration.ci?.green ?? null,
+        contains: (sha, commit) => {
+            if (commit === sha)
+                return true;
+            if (!rev || !FULL_COMMIT_ID.test(commit))
+                return false;
+            let set = later.get(sha);
+            if (!set)
+                later.set(sha, (set = descendants(top, sha, rev)));
+            return set.has(commit);
+        },
+    });
     return {
         doc: {
             ...head,
             at: located.at,
             workspace: { name: declaration.name, root: located.root },
             region: rid,
-            history: { rev, follows: region.lines ? "line-range" : type === "file" ? "file" : "directory", shallow },
+            history: { rev, follows: region.commit ? "commit" : region.lines ? "line-range" : type === "file" ? "file" : "directory", shallow },
             kinds: kinds.map((k) => ({ file: k.display, name: k.name, records: k.records?.loaded.kind.name ?? null, joins: k.joins?.form ?? null })),
             nodes: all,
             edges,
@@ -1494,6 +1613,7 @@ async function walk(query, head) {
                 findings: findings.length,
             },
             why,
+            trace,
         },
         failed: reasons.some((r) => r.code === "intent-plugin-failed"),
     };
@@ -1618,12 +1738,12 @@ async function walk(query, head) {
         if (!explained) {
             gaps.push({
                 code: "intent-why-no-decision",
-                message: readsRecords ? `no current decision governs ${region.path}, and none is carried out by what made its lines` : `no record kind was read, so no decision can account for ${region.path}`,
+                message: readsRecords ? `no current decision governs ${regionLabel}, and none is carried out by what made its lines` : `no record kind was read, so no decision can account for ${regionLabel}`,
             });
         }
         const committed = who.filter((w) => w.sha !== null);
         if (fileLines !== null ? committed.length > 0 && committed.every((w) => w.runs.length === 0) : touched.length > 0 && runNodes.length === 0) {
-            gaps.push({ code: "intent-why-no-run", message: `no agent run is joined to the commits that made ${fileLines !== null ? "the current lines of " : ""}${region.path}` });
+            gaps.push({ code: "intent-why-no-run", message: `no agent run is joined to the commits that made ${fileLines !== null ? "the current lines of " : ""}${regionLabel}` });
         }
         const uncommitted = who.filter((w) => w.sha === null).map((w) => w.line);
         if (uncommitted.length > 0)