@intentius/chant 0.124.31 → 0.124.33

package/src/workspace/reason-codes.ts

@@ -229,11 +229,29 @@ export const REASONS = {
   "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
   "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
   "diagram-render-drift": "A declared diagram records a sourceHash, and the source's bytes now hash to something else: the render is stale for its source.",
+  // The security group checklists (check, #4168 step 7). Each is also a WSP finding.
+  "security-signers-missing": "The workspace opts into verified-releases, and there is no .chant/allowed_signers to verify a release's signature against.",
+  "security-release-gate-missing": "Under verified-releases, identity.gates has no release entry, or it names no class, so a cut is not held to a class of signers.",
+  "security-publish-allows-unsigned": "Under verified-releases, a pipeline file runs release publish with --allow-unsigned.",
+  "security-sbom-disabled": "Under supply-chain, a member's chant.config.ts sets sbom: false on a publish target.",
+  "security-sbom-unsourced": "Under supply-chain, a member publishes, names no sbom file and has no package-lock.json, pom.xml or Cargo.lock to write one from.",
+  "security-publish-no-provenance": "Under supply-chain, a pipeline file runs release publish without --require-provenance.",
+  "security-component-no-sbom": "Under supply-chain, a member's components have no generate-sbom step.",
+  "security-component-no-verify": "Under supply-chain, a member's components have no verify step.",
+  "security-signed-since-unset": "Under who-ran-it, ci.green sets no signedSince, or there is no ci.green block.",
+  "security-runner-untrusted": "Under who-ran-it, .chant/trust.json lists no runner key.",
+  "security-tick-no-key": "Under who-ran-it, a pipeline file runs ci tick with no runner key.",
+  "security-review-not-required": "Under review-rules, an apply job passes --no-require-review, which the group overrides.",
+  "security-attribution-any": "Under review-rules, identity.attribution is not identified.",
+  "security-gate-unsigned": "Under review-rules, an apply job names a gate identity.gates does not list, or identity.gates lists none.",
+  "security-runner-start-no-key": "Under isolated-runners, .chant/trust.json lists no key under runners for a provisioner to sign runner-start statements with.",
+  "security-runner-start-no-role": "Under isolated-runners, no principal under runners in .chant/trust.json holds the runner role.",
+  "security-trust-unreadable": "Under isolated-runners, .chant/trust.json can't be read, so no runner-start statement can be checked.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
-  // The credential fountain itself hands a persistent box (check, #2780). Also a WSP finding.
-  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose persistent sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
+  // The credential fountain itself hands a box (check, #2780). Also a WSP finding.
+  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
   // A box's intent, the decision record its box block names (check, #2850). Each is also a WSP finding.
   "box-intent-unknown": "A box block names an intent, and no record of a declared kind named decision has that id.",
   "box-intent-unconstrained": "The decision record a box names as its intent constrains no member or path of this workspace: no member: entry for a declared member and no path: entry at, above or inside one's directory.",

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" } });
+    });
+  });
+});