@intentius/chant 0.124.32 → 0.124.34

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

@@ -0,0 +1,353 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json",
+  "title": "chant release candidates output",
+  "description": "What `chant release candidates --json` prints (#4168 4.2): the green commits of trunk a release can be cut from, newest first, each with the commits, work items, pull requests, merge records and flags it would ship since the previous candidate, and what each environment of the member runs. It reads local refs and tags and never fetches. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.33 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "branch",
+        "tip",
+        "environments",
+        "since",
+        "candidates",
+        "skipped",
+        "pending"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The workspace member read, or null for a project outside a workspace."
+        },
+        "branch": {
+          "type": "string",
+          "description": "The trunk walked: ci.green.branch, else what origin/HEAD names."
+        },
+        "tip": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The branch's tip as this clone knows it, or null when it knows none."
+        },
+        "environments": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/environment"
+          },
+          "description": "The member's environments in promotion order, or the one --env names."
+        },
+        "since": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The oldest commit an environment runs, where the walk stopped, or null when it read its limit of commits."
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/candidate"
+          },
+          "description": "Green commits that are not revoked, newest first."
+        },
+        "skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "commit",
+              "subject",
+              "reason"
+            ],
+            "properties": {
+              "commit": {
+                "type": "string"
+              },
+              "subject": {
+                "type": "string"
+              },
+              "reason": {
+                "enum": [
+                  "revoked"
+                ]
+              }
+            }
+          },
+          "description": "Revoked green commits, newest first. Their changes are in the next candidate."
+        },
+        "pending": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/change"
+          },
+          "description": "Commits after the newest candidate, newest first: not green yet, or red."
+        }
+      },
+      "description": "Exit code 0, with or without candidates."
+    },
+    "failure": {
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "not-a-git-repository",
+                "ledger-unreadable"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Exit code 1."
+    },
+    "environment": {
+      "type": "object",
+      "required": [
+        "env",
+        "running"
+      ],
+      "properties": {
+        "env": {
+          "type": "string"
+        },
+        "running": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/running"
+          },
+          "description": "The releases the environment's latest deploys name, newest cut first."
+        }
+      }
+    },
+    "running": {
+      "type": "object",
+      "required": [
+        "releaseDigest",
+        "label",
+        "commit",
+        "components"
+      ],
+      "properties": {
+        "releaseDigest": {
+          "type": "string"
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "commit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The commit it was cut from, or null when its release file is not on this clone's branch."
+        },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "required": [
+        "commit",
+        "subject",
+        "date",
+        "newFor",
+        "cut",
+        "changes",
+        "flags"
+      ],
+      "properties": {
+        "commit": {
+          "type": "string"
+        },
+        "subject": {
+          "type": "string"
+        },
+        "date": {
+          "type": "string"
+        },
+        "newFor": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The environments that run neither this commit nor a later one."
+        },
+        "cut": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The labels of releases already cut from it."
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/change"
+          },
+          "description": "The first-parent commits after the previous candidate, up to and including this one, newest first."
+        },
+        "flags": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/flag"
+          },
+          "description": "The flags of the declared flag kinds whose record files those commits change."
+        }
+      }
+    },
+    "change": {
+      "type": "object",
+      "required": [
+        "commit",
+        "subject",
+        "date",
+        "work",
+        "records",
+        "pr",
+        "merge"
+      ],
+      "properties": {
+        "commit": {
+          "type": "string"
+        },
+        "subject": {
+          "type": "string"
+        },
+        "date": {
+          "type": "string",
+          "description": "Author date, ISO 8601."
+        },
+        "work": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The ids its `Chant-Record: work:<id>` trailers name."
+        },
+        "records": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Every `Chant-Record` trailer, as `<kind>:<id>`."
+        },
+        "pr": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "The pull request the merge record or the squash subject (`(#123)` at its end) names, or null."
+        },
+        "merge": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "The merge record `_merges/<sha>.json` on chant/lifecycle (#4168 4.1), as stored, or null when there is none."
+        }
+      },
+      "description": "One first-parent commit."
+    },
+    "flag": {
+      "type": "object",
+      "required": [
+        "id",
+        "member",
+        "param",
+        "path",
+        "values"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "member": {
+          "type": "string"
+        },
+        "param": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file from the workspace root."
+        },
+        "values": {
+          "type": "object",
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              }
+            ]
+          },
+          "description": "The value per environment, as the working tree's record writes it."
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,106 @@
+/**
+ * The `release-candidates` read (#4168 4.2): green commits of trunk, each
+ * with the commits since the previous one, held to
+ * `release-candidates.schema.json`.
+ */
+
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+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 { appendCut, makeRelease, persistRelease } from "../lifecycle/release-store";
+import { appendReleaseRecord } from "../lifecycle/release-ledger";
+import { writeLedgerFiles } from "../lifecycle/git";
+
+const { expectValid } = contract(candidatesSchema);
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/** A repo on main with chant.config.ts declaring staging and prod, and one commit per subject. */
+function repo(dir: string, subjects: string[]): string[] {
+  for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@chant.dev"], ["config", "user.name", "T"]]) git(dir, ...args);
+  writeFileSync(join(dir, "chant.config.ts"), `export default { environments: ["staging", "prod"] };\n`);
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  const shas = [git(dir, "rev-parse", "HEAD")];
+  for (const s of subjects) {
+    git(dir, "commit", "-q", "--allow-empty", "-m", s);
+    shas.push(git(dir, "rev-parse", "HEAD"));
+  }
+  return shas;
+}
+
+describe("recordTrailers and prFromSubject", () => {
+  test("read work ids, every record, and a squash subject's pull request", () => {
+    expect(recordTrailers({ "Chant-Record": ["work:w-1", "decision:d-2", "nonsense"] })).toEqual({ work: ["w-1"], records: ["work:w-1", "decision:d-2"] });
+    expect(prFromSubject("ci: a thing (#4168) (#4174)")).toBe(4174);
+    expect(prFromSubject("no number here")).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) => {
+      const [init, a, b, c, d, e] = repo(dir, ["a (#1)", "b\n\nChant-Record: work:w-7", "c", "d (#4)", "e"]);
+      for (const sha of [init, b, d]) git(dir, "tag", `ci/green/${sha}`);
+      git(dir, "tag", `ci/green/${c}`);
+      git(dir, "tag", `ci/revoked/${c}`);
+
+      // staging runs a release of init; prod runs nothing.
+      const r = makeRelease({ member: null, commit: init, artifactDigests: [], targets: [{ env: "staging", templates: [], params: [] }] });
+      await persistRelease(r, [], { cwd: dir });
+      await appendCut({ releaseDigest: r.releaseDigest, label: "v0", actor: "alice", timestamp: "2026-10-20T10:00:00.000Z", runOrigin: null }, { cwd: dir });
+      await appendReleaseRecord(
+        { component: "api", env: "staging", digest: `sha256:${"a".repeat(64)}`, gitSha: init, runId: "r", timestamp: "2026-10-20T11:00:00.000Z", actor: "ci", releaseDigest: r.releaseDigest },
+        { 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 });
+
+      const doc = await releaseCandidatesDocument({ cwd: dir });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc).toMatchObject({ $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: 1, branch: "main", tip: e, member: null });
+      expect(doc.environments).toEqual([
+        { env: "staging", running: [{ releaseDigest: r.releaseDigest, label: "v0", commit: init, components: ["api"] }] },
+        { env: "prod", running: [] },
+      ]);
+      // prod runs nothing, so the walk is not bounded and reaches init.
+      expect(doc.since).toBeNull();
+      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[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);
+      expect(doc.candidates[2]).toMatchObject({ commit: init, newFor: ["prod"], cut: ["v0"] });
+      expect(doc.skipped).toEqual([{ commit: c, subject: "c", reason: "revoked" }]);
+      expect(doc.pending.map((x) => x.commit)).toEqual([e]);
+
+      // --env staging stops at what staging runs.
+      const staging = await releaseCandidatesDocument({ cwd: dir, env: "staging" });
+      if ("error" in staging) throw new Error(staging.error.message);
+      expectValid(staging);
+      expect(staging.since).toBe(init);
+      expect(staging.candidates.map((x) => x.commit)).toEqual([d, b]);
+      expect(staging.candidates.every((x) => x.newFor.join() === "staging")).toBe(true);
+    });
+  });
+
+  test("outside git it is the failure not-a-git-repository", async () => {
+    await withTestDir(async (dir) => {
+      const doc = await releaseCandidatesDocument({ cwd: dir });
+      expectValid(doc);
+      expect(doc).toMatchObject({ error: { code: "not-a-git-repository" } });
+    });
+  });
+});