@intentius/chant 0.124.34 → 0.124.36

package/src/workspace/release-candidates.schema.json

@@ -212,6 +212,7 @@
         "newFor",
         "cut",
         "changes",
+        "groups",
         "flags"
       ],
       "properties": {
@@ -245,6 +246,13 @@
           },
           "description": "The first-parent commits after the previous candidate, up to and including this one, newest first."
         },
+        "groups": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/group"
+          },
+          "description": "The same changes by work item, then pull request, then commit (#4168 4.4). Work items come first, in the order the oldest change names them, then `work: null` for changes that name none. A change with two work items is under both."
+        },
         "flags": {
           "type": "array",
           "items": {
@@ -254,6 +262,49 @@
         }
       }
     },
+    "group": {
+      "type": "object",
+      "required": [
+        "work",
+        "pullRequests"
+      ],
+      "properties": {
+        "work": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The work item id a `Chant-Record: work:<id>` trailer names, or null."
+        },
+        "pullRequests": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "pr",
+              "commits"
+            ],
+            "properties": {
+              "pr": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "description": "The pull request, or null for commits that landed without one."
+              },
+              "commits": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Newest first."
+              }
+            }
+          },
+          "description": "Pull requests in the order their oldest commit landed, then `pr: null`."
+        }
+      }
+    },
     "change": {
       "type": "object",
       "required": [

package/src/workspace/release-candidates.test.ts

@@ -11,7 +11,7 @@ import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { contract } from "./__fixtures__/contract-repo";
 import candidatesSchema from "./release-candidates.schema.json";
-import { prFromSubject, recordTrailers, releaseCandidatesDocument, RELEASE_CANDIDATES_SCHEMA_ID } from "./release-candidates";
+import { groupChanges, mergeRecordPr, prFromSubject, recordTrailers, releaseCandidatesDocument, RELEASE_CANDIDATES_SCHEMA_ID, type CandidateChange } from "./release-candidates";
 import { appendCut, makeRelease, persistRelease } from "../lifecycle/release-store";
 import { appendReleaseRecord } from "../lifecycle/release-ledger";
 import { writeLedgerFiles } from "../lifecycle/git";
@@ -46,6 +46,33 @@ describe("recordTrailers and prFromSubject", () => {
   });
 });
 
+describe("groupChanges (#4168 4.4)", () => {
+  const change = (commit: string, work: string[], pr: number | null): CandidateChange => ({ commit, subject: commit, date: "", work, records: work.map((w) => `work:${w}`), pr, merge: null });
+
+  test("groups by work item, then pull request, then commit, with the ungrouped last", () => {
+    // Newest first, as a candidate's changes are.
+    const groups = groupChanges([
+      change("f", [], null),
+      change("e", ["w-2"], null),
+      change("d", ["w-1"], 4),
+      change("c", [], 3),
+      change("b", ["w-1", "w-2"], 2),
+      change("a", ["w-1"], 2),
+    ]);
+    expect(groups).toEqual([
+      { work: "w-1", pullRequests: [{ pr: 2, commits: ["b", "a"] }, { pr: 4, commits: ["d"] }] },
+      { work: "w-2", pullRequests: [{ pr: 2, commits: ["b"] }, { pr: null, commits: ["e"] }] },
+      { work: null, pullRequests: [{ pr: 3, commits: ["c"] }, { pr: null, commits: ["f"] }] },
+    ]);
+  });
+
+  test("a merge record names its pull request in source", () => {
+    expect(mergeRecordPr({ source: { kind: "pull-request", pr: 12 } })).toBe(12);
+    expect(mergeRecordPr({ source: { kind: "direct-push" } })).toBeNull();
+    expect(mergeRecordPr(null)).toBeNull();
+  });
+});
+
 describe("releaseCandidatesDocument", () => {
   test("partitions the walk at green commits, skips revoked ones, and says which environments each is new for", async () => {
     await withTestDir(async (dir) => {
@@ -63,7 +90,7 @@ describe("releaseCandidatesDocument", () => {
         { cwd: dir },
       );
       // A merge record for d names its pull request.
-      await writeLedgerFiles([{ path: `_merges/${d}.json`, content: JSON.stringify({ pr: 40, approvedDigest: "sha256:x" }) }], "merge record", { cwd: dir });
+      await writeLedgerFiles([{ path: `_merges/${d}.json`, content: JSON.stringify({ source: { kind: "pull-request", pr: 40 }, approvedDigest: "sha256:x" }) }], "merge record", { cwd: dir });
 
       const doc = await releaseCandidatesDocument({ cwd: dir });
       expectValid(doc);
@@ -78,7 +105,7 @@ describe("releaseCandidatesDocument", () => {
       expect(doc.candidates.map((x) => x.commit)).toEqual([d, b, init]);
       expect(doc.candidates[0]).toMatchObject({ newFor: ["staging", "prod"], cut: [] });
       expect(doc.candidates[0].changes.map((x) => x.commit)).toEqual([d, c]);
-      expect(doc.candidates[0].changes[0]).toMatchObject({ pr: 40, merge: { pr: 40, approvedDigest: "sha256:x" } });
+      expect(doc.candidates[0].changes[0]).toMatchObject({ pr: 40, merge: { source: { kind: "pull-request", pr: 40 }, approvedDigest: "sha256:x" } });
       expect(doc.candidates[1].changes.map((x) => x.commit)).toEqual([b, a]);
       expect(doc.candidates[1].changes[0].work).toEqual(["w-7"]);
       expect(doc.candidates[1].changes[1].pr).toBe(1);

package/src/workspace/release-candidates.ts

@@ -24,6 +24,11 @@
  * flags whose record files changed in its range, from the declared flag kinds
  * (#4024).
  *
+ * Each candidate also groups its changes (#4168 4.4) by work item, then by
+ * pull request, then by commit: a change lands under every work item its
+ * trailers name, or under no work item, and within that under its pull
+ * request, or under none for a commit that landed without one.
+ *
  * It reads local refs and tags only and never fetches. Git is read through a
  * local `git` subprocess.
  */
@@ -76,6 +81,20 @@ export interface CandidateChange {
   merge: Record<string, unknown> | null;
 }
 
+/** A candidate's changes under one pull request, or under none (`pr: null`) for commits that landed without one. */
+export interface CandidatePullRequestGroup {
+  pr: number | null;
+  /** Newest first. */
+  commits: string[];
+}
+
+/** A candidate's changes under one work item, or under none (`work: null`). Work items come first, in the order the oldest change names them. */
+export interface CandidateGroup {
+  work: string | null;
+  /** Pull requests in the order their oldest commit landed, then `pr: null`. */
+  pullRequests: CandidatePullRequestGroup[];
+}
+
 export interface CandidateFlag {
   id: string;
   member: string;
@@ -95,6 +114,8 @@ export interface Candidate {
   /** The labels of releases already cut from it. */
   cut: string[];
   changes: CandidateChange[];
+  /** The same changes by work item, then pull request, then commit (#4168 4.4). */
+  groups: CandidateGroup[];
   flags: CandidateFlag[];
 }
 
@@ -156,6 +177,34 @@ export function prFromSubject(subject: string): number | null {
   return m ? Number(m[1]) : null;
 }
 
+/** The pull request a merge record names in its `source`, or null. */
+export function mergeRecordPr(merge: Record<string, unknown> | null): number | null {
+  const source = merge?.source as { kind?: unknown; pr?: unknown } | undefined;
+  return source?.kind === "pull-request" && typeof source.pr === "number" ? source.pr : null;
+}
+
+/**
+ * Group changes, given newest first, by work item, then pull request, then
+ * commit. A change with work items lands in each one's group; the rest land
+ * in the `work: null` group, last. Within a group, pull requests come in the
+ * order their oldest commit landed, and commits without one last.
+ */
+export function groupChanges(changes: readonly CandidateChange[]): CandidateGroup[] {
+  const oldestFirst = [...changes].reverse();
+  const groups = new Map<string | null, Map<number | null, string[]>>();
+  const add = (work: string | null, pr: number | null, commit: string): void => {
+    const byPr = groups.get(work) ?? new Map<number | null, string[]>();
+    groups.set(work, byPr);
+    byPr.set(pr, [commit, ...(byPr.get(pr) ?? [])]);
+  };
+  for (const c of oldestFirst) for (const work of c.work.length > 0 ? c.work : [null]) add(work, c.pr, c.commit);
+  const nullLast = <K>(keys: K[]): K[] => [...keys.filter((k) => k !== null), ...keys.filter((k) => k === null)];
+  return nullLast([...groups.keys()]).map((work) => {
+    const byPr = groups.get(work)!;
+    return { work, pullRequests: nullLast([...byPr.keys()]).map((pr) => ({ pr, commits: byPr.get(pr)! })) };
+  });
+}
+
 /** Read the release candidates of the member at `query.cwd`. */
 export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery): Promise<ReleaseCandidatesDocument> {
   const head = { $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: RELEASE_CANDIDATES_CONTRACT_VERSION, chant: readerVersion() };
@@ -240,7 +289,8 @@ export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery):
       const d = details.get(sha);
       const { work, records } = recordTrailers(d?.trailers ?? {});
       const merge = merges.get(sha) ?? null;
-      const mergePr = merge && typeof merge.pr === "number" ? merge.pr : null;
+      // The merge record names its pull request in `source` (../lifecycle/merge-record.ts).
+      const mergePr = mergeRecordPr(merge);
       const subject = d?.subject ?? "";
       return { commit: sha, subject, date: d?.date ?? "", work, records, pr: mergePr ?? prFromSubject(subject), merge };
     };
@@ -265,13 +315,15 @@ export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery):
       }
       if (!tags.green.has(sha)) continue;
       const own = change(sha);
+      const changes = open.map(change).reverse();
       candidates.push({
         commit: sha,
         subject: own.subject,
         date: own.date,
         newFor: environments.filter((e) => i < newestRun.get(e.env)!).map((e) => e.env),
         cut: cutLabels.get(sha) ?? [],
-        changes: open.map(change).reverse(),
+        changes,
+        groups: groupChanges(changes),
         flags: flagReader(open),
       });
       open = [];

package/src/workspace/releases.schema.json

@@ -363,6 +363,36 @@
               "type": "string"
             }
           }
+        },
+        "composed": {
+          "type": "object",
+          "required": [
+            "branch",
+            "base",
+            "sources"
+          ],
+          "properties": {
+            "branch": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "base": {
+              "type": "string"
+            },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Added by #4168 4.3, written by chant 0.124.35 and newer. On a cut of a composed commit only: its chant/compose/<name> branch, the trunk commit it was composed on, and the trunk commits picked onto that base, oldest first."
+        },
+        "channel": {
+          "type": "string",
+          "description": "Added by #4168 4.3, written by chant 0.124.35 and newer. The tag release publish moves in place of latest (an npm dist-tag, an image tag), from release cut --channel. Absent for latest."
         }
       }
     },