@intentius/chant 0.124.27 → 0.124.29

package/dist/workspace/releases.js

@@ -0,0 +1,103 @@
+/**
+ * The `releases` read (#4026, ws-104): every release of one member with its
+ * targets, its cuts, and the environments that run it.
+ *
+ * `chant release list --json` prints this document. It reads the local
+ * `chant/lifecycle` branch and never fetches. An environment runs a release
+ * for the components whose latest deploy record there names the release in
+ * `releaseDigest`. A promote under a release writes that field; deploys made
+ * any other way do not name a release yet (#4043), so they list nowhere.
+ *
+ * Each release carries `revoked` (#4033, ws-105): the `ci/revoked/<sha>` tag
+ * on its commit, judged as `release cut` judges it, or null. It is read from
+ * local tags at read time; nothing records it. When the tags can't be judged
+ * (a `ci.green.signedSince` naming no commit here) every release reads null,
+ * and `chant workspace check` reports the declaration.
+ *
+ * Each cut carries `signatureCheck` (#4031): whether its signature verifies
+ * for its actor against the signers at base, and, when the declaration names
+ * a `release` gate with a class, whether the actor is in it.
+ *
+ * A release file that is not a release, or whose content does not hash to its
+ * digest, and a cut line that is not a cut, are left out and counted under
+ * `reason` with `ledger-malformed`; the rest are listed. A read that fails
+ * outright is the failure `ledger-unreadable`.
+ */
+import { execFileSync } from "node:child_process";
+import { latestPerComponent, listReleaseEnvironments, readReleaseLedger } from "../lifecycle/release-ledger.js";
+import { readAllReleases, readCuts } from "../lifecycle/release-store.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { readerVersion } from "./declaration.js";
+import { checkReleaseSignature } from "./identity-gate-rule.js";
+import { readRevokedCommits, revocationOf } from "../lifecycle/release-revocation.js";
+export const RELEASES_CONTRACT_VERSION = 1;
+export const RELEASES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json";
+/** Why the read stopped. Closed; each code is in `reason-codes.ts`. */
+export const RELEASES_ERROR_CODES = ["not-a-git-repository", "ledger-unreadable"];
+/** Why some entries were left out. */
+export const RELEASES_REASON_CODES = ["ledger-malformed"];
+/**
+ * The rule a cut's signature is judged by (#4031): the declaration's
+ * `identity.gates.release` and the signers and role grants, all read at base.
+ */
+export async function releaseRule(cwd) {
+    const { scopeSource } = await import("./write-scope.js");
+    const { releaseRuleFrom } = await import("./identity.js");
+    return releaseRuleFrom(scopeSource(cwd)).rule;
+}
+/** Read the releases of the member at `cwd`. */
+export async function releasesDocument(req) {
+    const head = { $schema: RELEASES_SCHEMA_ID, contract: RELEASES_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        execFileSync("git", ["rev-parse", "--git-dir"], { cwd: req.cwd, stdio: "ignore" });
+    }
+    catch {
+        return { ...head, error: { code: "not-a-git-repository", message: "releases are read from the chant/lifecycle branch, and this directory is not in a git repository" } };
+    }
+    try {
+        const ledger = await resolveMemberLedger(req.cwd);
+        const loc = { cwd: req.cwd };
+        const { releases, malformed: badReleases } = await readAllReleases(loc);
+        const { cuts, malformed: badCuts } = await readCuts(loc);
+        const running = new Map();
+        for (const env of await listReleaseEnvironments(loc)) {
+            const { records } = await readReleaseLedger(env, loc);
+            for (const record of latestPerComponent(records).values()) {
+                const digest = record.releaseDigest;
+                if (typeof digest !== "string")
+                    continue;
+                const envs = running.get(digest) ?? new Map();
+                envs.set(env, [...(envs.get(env) ?? []), record.component].sort());
+                running.set(digest, envs);
+            }
+        }
+        const rule = await releaseRule(req.cwd);
+        const revoked = await readRevokedCommits(req.cwd).catch(() => new Map());
+        const entries = releases.map(({ version: _v, ...release }) => {
+            const own = cuts.filter((c) => c.releaseDigest === release.releaseDigest);
+            return {
+                ...release,
+                label: own.find((c) => c.label !== null)?.label ?? null,
+                cuts: own.map(({ version: _cv, releaseDigest: _d, ...cut }) => ({ ...cut, signatureCheck: checkReleaseSignature(rule, { releaseDigest: release.releaseDigest, ...cut }) })),
+                environments: [...(running.get(release.releaseDigest) ?? new Map())]
+                    .map(([env, components]) => ({ env, components }))
+                    .sort((a, b) => (a.env < b.env ? -1 : 1)),
+                revoked: revocationOf(release, revoked),
+            };
+        });
+        const latest = (e) => e.cuts.map((c) => c.timestamp).sort().at(-1) ?? "";
+        entries.sort((a, b) => (latest(b) !== latest(a) ? (latest(b) < latest(a) ? -1 : 1) : a.releaseDigest < b.releaseDigest ? -1 : 1));
+        const bad = badReleases + badCuts;
+        return {
+            ...head,
+            member: ledger.members.length > 0 ? ledger.members.join("/") : null,
+            releases: entries,
+            reason: bad > 0
+                ? { code: "ledger-malformed", message: `${badReleases} release file(s) and ${badCuts} cut line(s) could not be read and are left out` }
+                : null,
+        };
+    }
+    catch (err) {
+        return { ...head, error: { code: "ledger-unreadable", message: `reading the releases failed: ${err instanceof Error ? err.message : String(err)}` } };
+    }
+}

package/dist/workspace/releases.schema.json

@@ -0,0 +1,513 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json",
+  "title": "chant release list output",
+  "description": "What `chant release list --json` prints (#4026, ws-104): every release of one member, each the compiled output of one green commit, with its artifact digests, one target per environment, its cuts and the environments that run it. It reads the local chant/lifecycle branch 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.28 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0, with or without releases.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "releases",
+        "reason"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The workspace member read, its path of names joined with / when nested, or null for a project outside a workspace (the flat ledger layout)."
+        },
+        "releases": {
+          "type": "array",
+          "description": "Newest cut first. A release stored with no cut comes last.",
+          "items": {
+            "$ref": "#/$defs/release"
+          }
+        },
+        "reason": {
+          "description": "Null when everything was read. ledger-malformed when some release files or cut lines could not be read; the rest are listed.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code",
+                "message"
+              ],
+              "properties": {
+                "code": {
+                  "enum": [
+                    "ledger-malformed"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "releaseDigest",
+        "label",
+        "member",
+        "commit",
+        "artifactDigests",
+        "targets",
+        "cuts",
+        "environments"
+      ],
+      "properties": {
+        "releaseDigest": {
+          "type": "string",
+          "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$",
+          "description": "computePlanDigest(\"release\", subject) over member, commit, artifactDigests, and each target's env, templates and the name and value of each param. The file is _releases/<releaseDigest>.json on chant/lifecycle, with : written as _."
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The release's label, from its cuts, or null. A label names one release in a member and a release takes at most one label."
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "The full sha of the green commit the release was cut from."
+        },
+        "artifactDigests": {
+          "type": "array",
+          "description": "Each image and asset built once from the commit, sorted by component, then path. A config-only release carries the previous release's entries.",
+          "items": {
+            "type": "object",
+            "required": [
+              "component",
+              "kind",
+              "path",
+              "digest"
+            ],
+            "properties": {
+              "component": {
+                "type": "string"
+              },
+              "kind": {
+                "enum": [
+                  "image",
+                  "asset"
+                ]
+              },
+              "path": {
+                "type": "string"
+              },
+              "digest": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "targets": {
+          "type": "array",
+          "description": "One per environment the member declares, sorted by env.",
+          "items": {
+            "$ref": "#/$defs/target"
+          }
+        },
+        "cuts": {
+          "type": "array",
+          "description": "Each cut of the release, oldest first.",
+          "items": {
+            "$ref": "#/$defs/cut"
+          }
+        },
+        "environments": {
+          "type": "array",
+          "description": "The environments that run the release, sorted by env: in each, the components whose latest deploy record names this release in releaseDigest. A promote with --release writes that field. An environment can run components of several releases.",
+          "items": {
+            "type": "object",
+            "required": [
+              "env",
+              "components"
+            ],
+            "properties": {
+              "env": {
+                "type": "string"
+              },
+              "components": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "revoked": {
+          "description": "Added within contract version 1 by #4033, written by chant 0.124.29 and newer. The ci/revoked/<sha> tag on the release's commit, or null when the commit is not revoked. A revoked release is never promoted (chant components promote --release refuses it) and its pending release gates refuse approval. Null too when the ci tags can't be judged, as when ci.green.signedSince names no commit here, which chant workspace check reports.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/revocation"
+            }
+          ]
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "required": [
+        "env",
+        "templates",
+        "params"
+      ],
+      "properties": {
+        "env": {
+          "type": "string"
+        },
+        "templates": {
+          "type": "array",
+          "description": "The files the environment's deploys read, compiled for it, sorted by component, then path.",
+          "items": {
+            "type": "object",
+            "required": [
+              "component",
+              "path",
+              "digest"
+            ],
+            "properties": {
+              "component": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The component whose deploy reads it, or null for a project with no components."
+              },
+              "path": {
+                "type": "string",
+                "description": "The path the deploy step names, relative to the member's directory."
+              },
+              "digest": {
+                "type": "string",
+                "pattern": "^(jcs1-)?sha256:[0-9a-f]{64}$",
+                "description": "sha256 of the file's bytes."
+              }
+            }
+          }
+        },
+        "params": {
+          "type": "array",
+          "description": "The resolved build parameters the environment was compiled with, sorted by name. source is outside the release digest.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "value",
+              "source"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "value": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "source": {
+                "type": "string",
+                "description": "cli, params-file, env or default."
+              }
+            }
+          }
+        }
+      }
+    },
+    "cut": {
+      "type": "object",
+      "required": [
+        "label",
+        "actor",
+        "timestamp",
+        "runOrigin",
+        "signature"
+      ],
+      "properties": {
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "actor": {
+          "type": "string"
+        },
+        "timestamp": {
+          "type": "string",
+          "description": "ISO 8601."
+        },
+        "runId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added by #4027, written by chant 0.124.29 and newer. The run the cut ran in: the CI run's id in CI (GITHUB_RUN_ID, CI_PIPELINE_ID), or outside CI an id minted on the machine that cut, local-<epoch ms>. Null on a cut written before 0.124.29."
+        },
+        "runOrigin": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge"
+              ],
+              "properties": {
+                "forge": {
+                  "enum": [
+                    "github",
+                    "gitlab",
+                    "op",
+                    "local"
+                  ]
+                },
+                "repo": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The run the cut ran in: the forge (github for GitHub and Forgejo, gitlab, or local for an id minted outside CI), the repo or project, and a link to the run. From chant 0.124.29 a cut outside CI writes { forge: local } (#4027); a cut written before reads null outside CI."
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added by #4031, written by chant 0.124.28 and newer. The cut's armored ssh signature (ssh-keygen -Y sign, namespace chant-release) by the actor's key, over the release digest, the label (empty for none), the actor and the timestamp, joined by LF with no final newline. Null for an unsigned cut. A reader checks it against .chant/allowed_signers at base; signatureCheck is chant's own check."
+        },
+        "signatureCheck": {
+          "type": "object",
+          "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. Whether signature verifies for actor against the signers file at base and, when the declaration at base names a release gate in identity.gates with a class, whether the role grants in .chant/trust.json at base put actor in it. Judged on every read.",
+          "required": [
+            "status",
+            "key",
+            "reason"
+          ],
+          "properties": {
+            "status": {
+              "enum": [
+                "verified",
+                "unsigned",
+                "unverified"
+              ],
+              "description": "verified: the signature verifies, and the actor is in the release gate's class when it names one. unsigned: the cut has no signature. unverified: it has one that does not count, and reason says why."
+            },
+            "key": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The fingerprint (SHA256:...) of the key in the signature, or null for an unsigned cut or a signature that can't be read. Reported, never trusted."
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/releases/v1/releases.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"
+            }
+          }
+        }
+      }
+    },
+    "revocation": {
+      "type": "object",
+      "description": "A revoked tag on a release's commit (#4033, ws-105), as chant ci list --json shows a commit's revoked tag, with the commit. Read from local tags at read time and judged as release cut judges them: with ci.green.signedSince, a revoked tag without a valid runner statement is ignored and revokes nothing.",
+      "required": [
+        "commit",
+        "tag",
+        "tagged",
+        "phase",
+        "run",
+        "signer"
+      ],
+      "properties": {
+        "commit": {
+          "type": "string",
+          "description": "The release's commit, which the tag names."
+        },
+        "tag": {
+          "type": "string",
+          "description": "ci/revoked/<sha>."
+        },
+        "tagged": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "When the tag was made, ISO 8601, or null for a lightweight tag."
+        },
+        "phase": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The phase the annotation names as failed, or null when the annotation can't be read."
+        },
+        "run": {
+          "description": "The run the annotation names as failed, or null.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name",
+                "id",
+                "conclusion",
+                "url"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "id": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ],
+                  "description": "The check run's id, or null for a chant Op run."
+                },
+                "conclusion": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "url": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "opRun": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "env",
+                    "signer"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "env": {
+                      "type": "string"
+                    },
+                    "signer": {
+                      "type": "string"
+                    }
+                  },
+                  "description": "Present only when the run is a chant Op run (ci.green.source runs, #4044): its id, the env it is recorded under and the runner whose statement it carries. id above is then null."
+                }
+              }
+            }
+          ]
+        },
+        "signer": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The runner principal whose statement the tag carries, or null when it counts unsigned."
+        }
+      }
+    }
+  }
+}