@intentius/chant 0.124.27 → 0.124.29

package/dist/lifecycle/__fixtures__/publish-fakes.js

@@ -0,0 +1,304 @@
+/**
+ * Test stand-ins for the publish targets (#4047): an OCI registry fake that
+ * listens on 127.0.0.1 inside the test process and answers with a Bearer
+ * challenge as GHCR and Docker Hub do, an OCI image layout writer, a fake
+ * `npm` that records each call and keeps a registry with dist-tags in a file,
+ * and a forge fake with draft releases (#4048). Nothing here reaches a network or a real
+ * registry, and every server a test starts is closed by it.
+ */
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+const sha = (b) => `sha256:${createHash("sha256").update(b).digest("hex")}`;
+/** A registry fake with a Bearer token service that accepts `username` and `password`. */
+export async function startFakeRegistry(creds) {
+    const blobs = new Map();
+    const manifests = new Map();
+    const requests = [];
+    const state = { uploads: 0, port: 0 };
+    const read = (req) => new Promise((res) => {
+        const parts = [];
+        req.on("data", (c) => parts.push(c));
+        req.on("end", () => res(Buffer.concat(parts)));
+    });
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://127.0.0.1:${state.port}`);
+        const body = await read(req);
+        requests.push({ method: req.method ?? "", path: url.pathname, authorization: req.headers.authorization ?? null });
+        const send = (status, headers = {}, text = "") => {
+            res.writeHead(status, headers);
+            res.end(text);
+        };
+        if (url.pathname === "/token") {
+            const basic = `Basic ${Buffer.from(`${creds.username}:${creds.password}`).toString("base64")}`;
+            if (req.headers.authorization !== basic)
+                return send(401, {}, "bad credentials");
+            return send(200, { "content-type": "application/json" }, JSON.stringify({ token: creds.token }));
+        }
+        if (req.headers.authorization !== `Bearer ${creds.token}`) {
+            return send(401, { "www-authenticate": `Bearer realm="http://127.0.0.1:${state.port}/token",service="fake-registry"` }, "unauthorized");
+        }
+        let m = url.pathname.match(/^\/v2\/(.+)\/blobs\/uploads\/(.*)$/);
+        if (m) {
+            if (req.method === "POST")
+                return send(202, { location: `/v2/${m[1]}/blobs/uploads/u${requests.length}?_state=s` });
+            const digest = url.searchParams.get("digest") ?? "";
+            if (req.method === "PUT" && sha(body) === digest && url.searchParams.get("_state") === "s") {
+                blobs.set(digest, body);
+                state.uploads++;
+                return send(201, { "docker-content-digest": digest });
+            }
+            return send(400, {}, "digest invalid");
+        }
+        m = url.pathname.match(/^\/v2\/(.+)\/blobs\/(sha256:[0-9a-f]+)$/);
+        if (m && req.method === "HEAD")
+            return send(blobs.has(m[2]) ? 200 : 404);
+        m = url.pathname.match(/^\/v2\/(.+)\/manifests\/(.+)$/);
+        if (m && (req.method === "HEAD" || req.method === "GET")) {
+            const found = manifests.get(m[2]);
+            return found ? send(200, { "content-type": found.type, "docker-content-digest": sha(found.bytes) }, req.method === "GET" ? found.bytes.toString("utf-8") : "") : send(404);
+        }
+        if (m && req.method === "PUT") {
+            const ref = m[2];
+            if (ref.startsWith("sha256:") && sha(body) !== ref)
+                return send(400, {}, "manifest digest invalid");
+            const parsed = JSON.parse(body.toString("utf-8"));
+            for (const d of [parsed.config, ...(parsed.layers ?? [])])
+                if (d && !blobs.has(d.digest))
+                    return send(400, {}, `blob unknown ${d.digest}`);
+            manifests.set(ref, { name: m[1], type: String(req.headers["content-type"]), bytes: body });
+            return send(201, { "docker-content-digest": sha(body) });
+        }
+        return send(404, {}, "not found");
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", () => r()));
+    state.port = server.address().port;
+    return {
+        host: `127.0.0.1:${state.port}`,
+        blobs,
+        manifests,
+        requests,
+        get uploads() {
+            return state.uploads;
+        },
+        close: () => new Promise((r) => server.close(() => r())),
+    };
+}
+/** Write a one-image OCI layout at `dir`, returning the manifest's and the config's digests. */
+export function writeOciLayout(dir, content = "layer bytes") {
+    const blobsDir = join(dir, "blobs", "sha256");
+    mkdirSync(blobsDir, { recursive: true });
+    const put = (bytes) => {
+        const d = sha(bytes);
+        writeFileSync(join(blobsDir, d.slice(7)), bytes);
+        return { digest: d, size: Buffer.byteLength(bytes) };
+    };
+    const layer = put(content);
+    const config = put(JSON.stringify({ architecture: "amd64", os: "linux", rootfs: { type: "layers", diff_ids: [layer.digest] } }));
+    const manifest = put(JSON.stringify({
+        schemaVersion: 2,
+        mediaType: "application/vnd.oci.image.manifest.v1+json",
+        config: { mediaType: "application/vnd.oci.image.config.v1+json", ...config },
+        layers: [{ mediaType: "application/vnd.oci.image.layer.v1.tar", ...layer }],
+    }));
+    writeFileSync(join(dir, "oci-layout"), JSON.stringify({ imageLayoutVersion: "1.0.0" }));
+    writeFileSync(join(dir, "index.json"), JSON.stringify({ schemaVersion: 2, manifests: [{ mediaType: "application/vnd.oci.image.manifest.v1+json", ...manifest }] }));
+    return { digest: manifest.digest, configDigest: config.digest };
+}
+/** The registry file a fake npm writing calls to `log` keeps its state in. */
+export const fakeNpmRegistryFile = (log) => `${log}.registry.json`;
+/** Read the fake npm's registry. */
+export function readFakeNpmRegistry(log) {
+    const file = fakeNpmRegistryFile(log);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf-8")) : { packages: {} };
+}
+/** Seed the fake npm's registry, such as with an earlier version as `latest`. */
+export function seedFakeNpmRegistry(log, registry) {
+    writeFileSync(fakeNpmRegistryFile(log), JSON.stringify(registry));
+}
+/**
+ * Write a fake `npm` at `<binDir>/npm` that appends `{ args, tokenSet }` to
+ * `log` for each call and prints the token it was given (so a test can show
+ * it is masked). It keeps a registry in `<log>.registry.json`, as npm's does:
+ *
+ * - `publish <dir|tgz> [--tag <t>]` adds the version under `<t>` (default
+ *   `latest`), and refuses a version already there with a 403. As npm's
+ *   registry does, a package's first version is also `latest`. It exits 1
+ *   when the package path contains `$FAKE_NPM_FAIL`.
+ * - `view <name>@<version> version` prints the version when it is there.
+ * - `dist-tag add <name>@<version> <tag>` points the tag at a version that is
+ *   there. It exits 1 when the name contains `$FAKE_NPM_FAIL_TAG`.
+ * - `install` (#4049) checks that every dependency in `./package.json` is in
+ *   its registry at that version, and installs nothing.
+ * - `audit signatures` (#4049) prints what npm prints for verified
+ *   signatures and attestations, and exits 1 when `$FAKE_NPM_AUDIT_FAIL` is set.
+ */
+export function writeFakeNpm(binDir, log) {
+    mkdirSync(binDir, { recursive: true });
+    const file = join(binDir, "npm");
+    writeFileSync(file, `#!${process.execPath}
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const args = process.argv.slice(2);
+const token = process.env.NODE_AUTH_TOKEN || "";
+const regFile = ${JSON.stringify(log)} + ".registry.json";
+fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({ args, tokenSet: token !== "" }) + "\\n");
+console.log("npm notice using //registry.example/:_authToken=" + token);
+console.error("npm notice token " + token);
+const reg = fs.existsSync(regFile) ? JSON.parse(fs.readFileSync(regFile, "utf-8")) : { packages: {} };
+const save = () => fs.writeFileSync(regFile, JSON.stringify(reg));
+const flag = (name) => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+const split = (spec) => { const at = spec.lastIndexOf("@"); return [spec.slice(0, at), spec.slice(at + 1)]; };
+if (args[0] === "publish") {
+  if (process.env.FAKE_NPM_FAIL && args[1] && args[1].includes(process.env.FAKE_NPM_FAIL)) { console.error("npm error 403 Forbidden"); process.exit(1); }
+  const text = fs.statSync(args[1]).isDirectory() ? fs.readFileSync(path.join(args[1], "package.json"), "utf-8") : execFileSync("tar", ["-xzOf", args[1], "package/package.json"], { encoding: "utf-8" });
+  const { name, version } = JSON.parse(text);
+  const p = reg.packages[name] || (reg.packages[name] = { versions: [], distTags: {} });
+  if (p.versions.includes(version)) { console.error("npm error 403 You cannot publish over the previously published versions: " + version); process.exit(1); }
+  p.versions.push(version);
+  p.distTags[flag("--tag") || "latest"] = version;
+  if (!p.distTags.latest) p.distTags.latest = version;
+  save();
+  console.log("+ " + name + "@" + version);
+} else if (args[0] === "view") {
+  const [name, version] = split(args[1]);
+  const p = reg.packages[name];
+  if (!p) { console.error("npm error 404 Not Found - " + name); process.exit(1); }
+  if (p.versions.includes(version)) console.log(version);
+} else if (args[0] === "dist-tag" && args[1] === "add") {
+  const [name, version] = split(args[2]);
+  if (process.env.FAKE_NPM_FAIL_TAG && name.includes(process.env.FAKE_NPM_FAIL_TAG)) { console.error("npm error 403 Forbidden - no permission to change dist-tags"); process.exit(1); }
+  const p = reg.packages[name];
+  if (!p || !p.versions.includes(version)) { console.error("npm error 404 " + args[2] + " is not in the npm registry"); process.exit(1); }
+  p.distTags[args[3]] = version;
+  save();
+  console.log("+" + args[3] + ": " + args[2]);
+} else if (args[0] === "install") {
+  const deps = JSON.parse(fs.readFileSync("package.json", "utf-8")).dependencies || {};
+  for (const [name, version] of Object.entries(deps)) {
+    const p = reg.packages[name];
+    if (!p || !p.versions.includes(version)) { console.error("npm error 404 " + name + "@" + version + " is not in this registry"); process.exit(1); }
+  }
+  console.log("added " + Object.keys(deps).length + " packages");
+} else if (args[0] === "audit" && args[1] === "signatures") {
+  const n = Object.keys(JSON.parse(fs.readFileSync("package.json", "utf-8")).dependencies || {}).length;
+  if (process.env.FAKE_NPM_AUDIT_FAIL) { console.error(n + " packages have invalid attestations"); process.exit(1); }
+  console.log("audited " + n + " packages");
+  console.log(n + " packages have verified registry signatures");
+  console.log(n + " packages have verified attestations");
+} else {
+  console.error("fake npm: unknown command " + args.join(" ")); process.exit(2);
+}
+`);
+    chmodSync(file, 0o755);
+    return file;
+}
+/** A forge fake at `api` for `repo`, which holds `releases` to begin with. */
+export function startFakeForge(forge, api, repo, releases = []) {
+    const calls = [];
+    const packages = new Map();
+    const failures = [];
+    let nextId = 100 + releases.length;
+    const root = forge === "gitlab" ? `${api}/projects/${encodeURIComponent(repo)}` : `${api}/repos/${repo}`;
+    const uploads = forge === "github" ? "https://uploads.forge.test" : api;
+    const json = (status, body) => ({ ok: status < 300, status, headers: { get: () => null }, text: async () => (body === undefined ? "" : JSON.stringify(body)) });
+    const view = (r) => forge === "gitlab"
+        ? { tag_name: r.tag_name, assets: { links: r.assets.map((a) => ({ name: a.name })) } }
+        : { id: r.id, tag_name: r.tag_name, draft: r.draft, upload_url: `${uploads}/repos/${repo}/releases/${r.id}/assets{?name,label}`, assets: r.assets.map((a) => ({ name: a.name, ...(forge === "github" ? { digest: a.digest } : {}) })) };
+    const text = (b) => (b === undefined ? "" : typeof b === "string" ? b : Buffer.from(b).toString("utf-8"));
+    const fetch = async (url, init) => {
+        calls.push({ method: init.method, url, headers: init.headers, ...(init.body !== undefined ? { body: init.body } : {}) });
+        const key = `${init.method} ${url}`;
+        const f = failures.findIndex((p) => key.startsWith(p));
+        if (f >= 0) {
+            failures.splice(f, 1);
+            return json(500, { message: "Internal Server Error" });
+        }
+        const u = new URL(url);
+        const path = url.split("?")[0];
+        if (forge === "gitlab") {
+            if (init.method === "PUT" && path.startsWith(`${root}/packages/generic/`)) {
+                packages.set(path, text(init.body));
+                return json(201, { message: "201 Created" });
+            }
+            const byTag = path.startsWith(`${root}/releases/`) ? decodeURIComponent(path.slice(`${root}/releases/`.length)) : null;
+            if (init.method === "GET" && byTag !== null) {
+                const r = releases.find((x) => x.tag_name === byTag);
+                return r ? json(200, view(r)) : json(404, { message: "404 Not Found" });
+            }
+            if (init.method === "POST" && path === `${root}/releases`) {
+                const b = JSON.parse(text(init.body));
+                if (releases.some((x) => x.tag_name === b.tag_name))
+                    return json(409, { message: "Release already exists" });
+                const r = { id: nextId++, tag_name: b.tag_name, draft: false, target: b.ref, assets: (b.assets?.links ?? []).map((l) => ({ name: l.name, digest: null, bytes: packages.get(l.url) ?? "" })) };
+                releases.push(r);
+                return json(201, view(r));
+            }
+            return json(404, { message: "404 Not Found" });
+        }
+        if (init.method === "GET" && path.startsWith(`${root}/releases/tags/`)) {
+            const tag = decodeURIComponent(path.slice(`${root}/releases/tags/`.length));
+            const r = releases.find((x) => x.tag_name === tag && !x.draft);
+            return r ? json(200, view(r)) : json(404, { message: "Not Found" });
+        }
+        if (init.method === "GET" && path === `${root}/releases`)
+            return json(200, releases.map(view));
+        if (init.method === "POST" && path === `${root}/releases`) {
+            const b = JSON.parse(text(init.body));
+            const r = { id: nextId++, tag_name: b.tag_name, draft: b.draft === true, target: b.target_commitish, assets: [] };
+            releases.push(r);
+            return json(201, view(r));
+        }
+        const asset = path.match(/\/releases\/(\d+)\/assets$/);
+        if (init.method === "POST" && asset && (path.startsWith(uploads) || path.startsWith(root))) {
+            const r = releases.find((x) => x.id === Number(asset[1]));
+            const name = u.searchParams.get("name") ?? "";
+            if (!r)
+                return json(404, { message: "Not Found" });
+            if (r.assets.some((a) => a.name === name))
+                return json(422, { message: "already_exists" });
+            let bytes = text(init.body);
+            if (forge === "forgejo")
+                bytes = bytes.split("\r\n\r\n")[1]?.split("\r\n--")[0] ?? "";
+            r.assets.push({ name, digest: sha(bytes), bytes });
+            return json(201, { name, browser_download_url: `https://forge.test/${repo}/releases/download/${r.tag_name}/${name}` });
+        }
+        const edit = path.match(/\/releases\/(\d+)$/);
+        if (init.method === "PATCH" && edit) {
+            const r = releases.find((x) => x.id === Number(edit[1]));
+            if (!r)
+                return json(404, { message: "Not Found" });
+            const b = JSON.parse(text(init.body));
+            if (b.draft === false)
+                r.draft = false;
+            return json(200, view(r));
+        }
+        return json(404, { message: "Not Found" });
+    };
+    return {
+        fetch,
+        calls,
+        releases,
+        packages,
+        visible: () => releases.filter((r) => !r.draft).map((r) => ({ tag: r.tag_name, assets: r.assets.map((a) => a.name) })),
+        failOnce: (prefix) => void failures.push(prefix),
+    };
+}
+/** A small SPDX document, as `npm sbom --sbom-format spdx` writes one. */
+export function spdxDocument(name) {
+    return `${JSON.stringify({ spdxVersion: "SPDX-2.3", dataLicense: "CC0-1.0", SPDXID: "SPDXRef-DOCUMENT", name, documentNamespace: `https://example.test/${name}`, creationInfo: { created: "2026-10-17T00:00:00Z", creators: ["Tool: npm"] }, packages: [] }, null, 2)}\n`;
+}
+/** Write an npm package directory, with an `sbom.spdx.json` at its root unless `sbom` is false (#4049). */
+export function writePackage(dir, name, version, sbom = true) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name, version }, null, 2));
+    if (sbom)
+        writeFileSync(join(dir, "sbom.spdx.json"), spdxDocument(name));
+}
+/** Write a `package-lock.json` at `dir`, which the OCI and forge targets write their SBOM from (#4049). */
+export function writeLockfile(dir) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package-lock.json"), JSON.stringify({ name: "acme", lockfileVersion: 3, packages: { "": { name: "acme" }, "node_modules/left-pad": { version: "1.3.0" } } }, null, 2));
+}

package/dist/lifecycle/change-set-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Stored change sets (#4022): each change-set document a gate binds, kept on
+ * `chant/lifecycle` under its digest so the plan an approval bound can be read
+ * once the run that planned it is gone.
+ *
+ * A pull-request gate, a release gate and an `empty` resolution (ws-104
+ * question 2 and 6) bind the change-set document's `digest`
+ * (`../change-set.ts`) in `planDigest`. Only that value reaches the gate
+ * ledger, so this store keeps the document beside it:
+ *
+ *   _change-sets/<digest>.json    the document, written once and never rewritten
+ *
+ * `:` is written as `_` in the file name, as `_plans/`, `_builds/` and
+ * `_releases/` do. A workspace member's copy sits under
+ * `_members/<member>/_change-sets/` through the same `ledgerDir` prefix the
+ * gate ledger uses, so a gate and its change set are read from one member.
+ *
+ * The stored document is the one the gate bound, with each entry's graph
+ * `node` (`../change-set-graph.ts`) and the `graph` it came from. Neither is
+ * hashed, so the stored document still verifies against its digest. A
+ * component gate in a plain `run --components` binds a lifecycle-plan digest
+ * and stores nothing here.
+ *
+ * `chant lifecycle gc` removes a stored change set from the branch's tree
+ * once #4036's retention policy lets it go (./retention.ts); history keeps it.
+ */
+import { type ChangeSetDocument } from "../change-set.js";
+import { type LedgerLocation } from "./git.js";
+/** The directory on `chant/lifecycle` that holds stored change sets. */
+export declare const CHANGE_SETS_DIR = "_change-sets";
+/** The file a change set with `digest` is stored in, inside {@link CHANGE_SETS_DIR}. */
+export declare function changeSetFile(digest: string): string;
+/** Thrown when a document can't be stored: it is not a change-set document, or its content does not hash to its digest. */
+export declare class ChangeSetStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Store a change-set document under its digest. A document already stored
+ * under the digest is never rewritten. Refuses a document whose content does
+ * not hash to its own `digest`. Does not push: call `pushLifecycleReport`
+ * (./git.ts) after, or let the gate's own pending fact push it.
+ */
+export declare function persistChangeSet(doc: ChangeSetDocument, opts?: {
+    cwd?: string;
+}): Promise<{
+    commit: string | null;
+    written: boolean;
+}>;
+/** What reading one stored change set found. */
+export type StoredChangeSetRead = {
+    status: "found";
+    document: ChangeSetDocument;
+} | {
+    status: "missing";
+}
+/** A file is stored under the digest, and it is not a change-set document whose content hashes to that digest. */
+ | {
+    status: "malformed";
+    message: string;
+};
+/** Parse a stored file, checking it is the document `digest` names. */
+export declare function parseStoredChangeSet(text: string, digest: string): StoredChangeSetRead;
+/**
+ * Read the change set stored under `digest`. Reads the local `chant/lifecycle`
+ * branch and never fetches. Throws only when git itself fails.
+ */
+export declare function readStoredChangeSet(digest: string, opts?: LedgerLocation): Promise<StoredChangeSetRead>;
+//# sourceMappingURL=change-set-store.d.ts.map

package/dist/lifecycle/change-set-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-set-store.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAoE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACzH,OAAO,EAAmF,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAE7H,wEAAwE;AACxE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2HAA2H;AAC3H,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,iBAAiB,EACtB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAsBtD;AAED,gDAAgD;AAChD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,kHAAkH;GAChH;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,CActF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAI7G"}

package/dist/lifecycle/change-set-store.js

@@ -0,0 +1,97 @@
+/**
+ * Stored change sets (#4022): each change-set document a gate binds, kept on
+ * `chant/lifecycle` under its digest so the plan an approval bound can be read
+ * once the run that planned it is gone.
+ *
+ * A pull-request gate, a release gate and an `empty` resolution (ws-104
+ * question 2 and 6) bind the change-set document's `digest`
+ * (`../change-set.ts`) in `planDigest`. Only that value reaches the gate
+ * ledger, so this store keeps the document beside it:
+ *
+ *   _change-sets/<digest>.json    the document, written once and never rewritten
+ *
+ * `:` is written as `_` in the file name, as `_plans/`, `_builds/` and
+ * `_releases/` do. A workspace member's copy sits under
+ * `_members/<member>/_change-sets/` through the same `ledgerDir` prefix the
+ * gate ledger uses, so a gate and its change set are read from one member.
+ *
+ * The stored document is the one the gate bound, with each entry's graph
+ * `node` (`../change-set-graph.ts`) and the `graph` it came from. Neither is
+ * hashed, so the stored document still verifies against its digest. A
+ * component gate in a plain `run --components` binds a lifecycle-plan digest
+ * and stores nothing here.
+ *
+ * `chant lifecycle gc` removes a stored change set from the branch's tree
+ * once #4036's retention policy lets it go (./retention.ts); history keeps it.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, verifyChangeSetDigest } from "../change-set.js";
+import { ledgerDir, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles } from "./git.js";
+/** The directory on `chant/lifecycle` that holds stored change sets. */
+export const CHANGE_SETS_DIR = "_change-sets";
+/** The file a change set with `digest` is stored in, inside {@link CHANGE_SETS_DIR}. */
+export function changeSetFile(digest) {
+    return `${digest.replace(/:/g, "_")}.json`;
+}
+/** Thrown when a document can't be stored: it is not a change-set document, or its content does not hash to its digest. */
+export class ChangeSetStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ChangeSetStoreError";
+    }
+}
+/**
+ * Store a change-set document under its digest. A document already stored
+ * under the digest is never rewritten. Refuses a document whose content does
+ * not hash to its own `digest`. Does not push: call `pushLifecycleReport`
+ * (./git.ts) after, or let the gate's own pending fact push it.
+ */
+export async function persistChangeSet(doc, opts) {
+    if (doc?.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT) {
+        throw new ChangeSetStoreError(`not a change-set document: its $schema is not ${CHANGE_SET_SCHEMA_ID} with contract ${CHANGE_SET_CONTRACT}`);
+    }
+    if (!verifyChangeSetDigest(doc)) {
+        throw new ChangeSetStoreError(`change set ${doc.digest} does not hash to its own digest; refusing to store it`);
+    }
+    const file = changeSetFile(doc.digest);
+    if ((await readPathSha(CHANGE_SETS_DIR, file, opts)) !== null)
+        return { commit: null, written: false };
+    const dir = await ledgerDir(CHANGE_SETS_DIR, opts);
+    try {
+        const commit = await writeLedgerFiles([{ path: `${dir}/${file}`, content: `${JSON.stringify(doc, sortedJsonReplacer)}\n`, expectPriorSha: null }], `Change set ${doc.digest}`, opts);
+        return { commit, written: true };
+    }
+    catch (err) {
+        // Another writer stored the same digest first; what is there is the same document.
+        if (err instanceof RefCASConflictError)
+            return { commit: null, written: false };
+        throw err;
+    }
+}
+/** Parse a stored file, checking it is the document `digest` names. */
+export function parseStoredChangeSet(text, digest) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (err) {
+        return { status: "malformed", message: `the file stored under ${digest} is not JSON: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!doc || typeof doc !== "object" || doc.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT || !Array.isArray(doc.entries) || !Array.isArray(doc.members)) {
+        return { status: "malformed", message: `the file stored under ${digest} is not a change-set document` };
+    }
+    if (doc.digest !== digest || !verifyChangeSetDigest(doc)) {
+        return { status: "malformed", message: `the change set stored under ${digest} does not hash to that digest` };
+    }
+    return { status: "found", document: doc };
+}
+/**
+ * Read the change set stored under `digest`. Reads the local `chant/lifecycle`
+ * branch and never fetches. Throws only when git itself fails.
+ */
+export async function readStoredChangeSet(digest, opts) {
+    const text = await readBlobFromPath(CHANGE_SETS_DIR, changeSetFile(digest), opts);
+    if (text === null)
+        return { status: "missing" };
+    return parseStoredChangeSet(text, digest);
+}

package/dist/lifecycle/commit-sha.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The commit a run, a gate or a deploy is for (#4020), as one answer for every
+ * record that carries it. The checkout's `HEAD` is what the process builds
+ * from, so it comes first; a CI job whose checkout has no git (a bare
+ * artifact job) falls back to the commit the forge says it started for.
+ * Undefined when neither is known, so a record leaves the field out rather
+ * than guessing.
+ */
+export declare function resolveCommitSha(opts?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}): Promise<string | undefined>;
+//# sourceMappingURL=commit-sha.d.ts.map

package/dist/lifecycle/commit-sha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-sha.d.ts","sourceRoot":"","sources":["../../src/lifecycle/commit-sha.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,wBAAsB,gBAAgB,CACpC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAO,GACpE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/lifecycle/commit-sha.js

@@ -0,0 +1,21 @@
+/**
+ * The commit a run, a gate or a deploy is for (#4020), as one answer for every
+ * record that carries it. The checkout's `HEAD` is what the process builds
+ * from, so it comes first; a CI job whose checkout has no git (a bare
+ * artifact job) falls back to the commit the forge says it started for.
+ * Undefined when neither is known, so a record leaves the field out rather
+ * than guessing.
+ */
+import { ciCommitFromEnv } from "../op/gate-run-locator.js";
+import { getHeadCommit } from "./git.js";
+export async function resolveCommitSha(opts = {}) {
+    try {
+        const head = await getHeadCommit(opts.cwd ? { cwd: opts.cwd } : undefined);
+        if (/^[0-9a-f]{40,64}$/.test(head))
+            return head;
+    }
+    catch {
+        // Not a checkout, or no git on the path: the environment may still say.
+    }
+    return ciCommitFromEnv(opts.env);
+}

package/dist/lifecycle/delivery-metrics.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The four DORA metrics of one environment's deploy records (#4039): how
+ * often it deploys, the lead time from commit to running release, the change
+ * failure rate and the time to restore.
+ *
+ * Everything here is pure. The caller reads the ledgers, the release files
+ * and the ci tags, and hands this module one environment's records with
+ * lookups for the rest; `workspace/delivery-metrics.ts` does that for
+ * `chant workspace metrics`.
+ *
+ * A deploy is one record in `<env>/releases.jsonl`: one component deployed
+ * once. A redeploy, which puts the running release back, is counted apart and
+ * is not a deploy for the metrics. A deploy fails when, within the failure window after it, the commit
+ * it deployed is revoked (a counted `ci/revoked/<sha>` tag, #4033) or the
+ * environment is rolled back from it. Which records are rollbacks, and which
+ * put the current release back, is decided in {@link rollbackOf} and
+ * {@link isRedeploy} and nowhere else, so a new kind of rollback record
+ * (#4035) changes those two functions only.
+ */
+import type { ReleaseRecord, ReleaseRef } from "./release-ledger.js";
+/** The failure window when the declaration's `metrics.failureWindowDays` is not set. */
+export declare const DEFAULT_FAILURE_WINDOW_DAYS = 7;
+/**
+ * The earlier deploy a rollback record restores, or null when the record is
+ * not a rollback. Today a rollback is a record `chant components rollback`
+ * wrote, which names what it restores in `restores` (#2531). Every rule below
+ * that asks whether a record rolled an environment back asks this function.
+ */
+export declare function rollbackOf(record: Pick<ReleaseRecord, "restores">): ReleaseRef | null;
+/**
+ * Whether the record put the current release back (`chant components
+ * redeploy`, #2604). A redeploy deploys the same release again, so it neither
+ * restores a failed deploy nor stands between a deploy and its rollback.
+ */
+export declare function isRedeploy(record: Pick<ReleaseRecord, "redeploys">): boolean;
+/** A counted revoked tag on a commit, with the time it was made, or null for a lightweight tag. */
+export interface CommitRevocation {
+    tag: string;
+    tagged: string | null;
+}
+/** What the caller knows beyond the records, as lookups. */
+export interface MetricsLookups {
+    /** The release a deploy record names: its `releaseDigest`, else the one its release-gate admission names. Undefined when it names none. */
+    releaseOf: (record: ReleaseRecord) => string | undefined;
+    /** The commit a release was cut from, or null when its file can't be read here. */
+    commitOfRelease: (releaseDigest: string) => string | null;
+    /** The release's label, or null. */
+    labelOf: (releaseDigest: string) => string | null;
+    /** The counted revoked tag on a commit, or null when the commit is not revoked. */
+    revocationOf: (commit: string) => CommitRevocation | null;
+    /** The commit's committer time in milliseconds, or null when the commit is not in this repository. */
+    commitTime: (commit: string) => number | null;
+}
+/** The span of time the metrics count deploys in. */
+export interface MetricsWindow {
+    /** ISO-8601, inclusive. */
+    since: string;
+    /** ISO-8601, inclusive. */
+    until: string;
+}
+/** A record named the way `restores` names one. */
+export interface DeployRef {
+    runId: string;
+    timestamp: string;
+}
+/** One failed deploy, and how it was restored. */
+export interface DeployFailure {
+    component: string;
+    timestamp: string;
+    runId: string;
+    /** The release the deploy came from, or null for a deploy made from no release. */
+    releaseDigest: string | null;
+    label: string | null;
+    /** The commit it deployed: the release's commit, or the record's `gitSha` for a deploy made from no release. */
+    commit: string;
+    /** Why it counts as failed: `revoked`, `rolled-back`, or both. */
+    causes: Array<"revoked" | "rolled-back">;
+    /** The revoked tag on the commit, when that is a cause. */
+    revoked: CommitRevocation | null;
+    /** The rollback record that rolled the environment back from it, when that is a cause. */
+    rolledBackBy: DeployRef | null;
+    /** The next deploy of the component in the environment whose commit is not revoked, or null while there is none. */
+    restoredBy: DeployRef | null;
+    /** Seconds from the failed deploy to `restoredBy`, or null while it is not restored. */
+    restoreSeconds: number | null;
+}
+/** The four metrics of one environment. */
+export interface EnvironmentMetrics {
+    env: string;
+    deployments: {
+        /** Deploy records in the window, one per component deployed, leaving out redeploys. Rollbacks count. */
+        count: number;
+        /** Redeploys in the window: records that put the running release back, counted apart from `count`. */
+        redeploys: number;
+        /** Distinct `runId` values among them, so a run that deploys several components counts once. */
+        runs: number;
+        /** Of `count`, the deploys made from a release. */
+        fromRelease: number;
+        /** `count` over the window in weeks, to two decimals. */
+        perWeek: number;
+    };
+    leadTime: {
+        /** Changes whose first deploy here falls in the window and whose commit time is known. */
+        changes: number;
+        /** Of `changes`, releases (the first deploy naming the release). */
+        fromRelease: number;
+        /** Of `changes`, commits deployed from no release (the first deploy with that `gitSha`). */
+        fromCommit: number;
+        /** Changes left out because their commit is not in this repository. */
+        unknown: number;
+        /** The median, in seconds, or null when `changes` is 0. */
+        medianSeconds: number | null;
+    };
+    changeFailure: {
+        deployments: number;
+        failed: number;
+        /** Failed deploys whose commit was revoked within the window after them. */
+        revoked: number;
+        /** Failed deploys the environment was rolled back from within the window after them. */
+        rolledBack: number;
+        /** `failed` over `deployments`, to four decimals, or null with no deployments. */
+        rate: number | null;
+    };
+    restore: {
+        restored: number;
+        open: number;
+        medianSeconds: number | null;
+    };
+    /** The failed deploys in the window, oldest first. */
+    failures: DeployFailure[];
+}
+/**
+ * The metrics of one environment's records. `records` is the whole ledger of
+ * the environment, every component, in ledger order: deploys before the
+ * window still decide lead times, and deploys after a failure decide its
+ * restore. Only deploys whose `timestamp` falls in `window` are counted.
+ */
+export declare function environmentMetrics(env: string, records: readonly ReleaseRecord[], lookups: MetricsLookups, window: MetricsWindow, failureWindowDays?: number): EnvironmentMetrics;
+//# sourceMappingURL=delivery-metrics.d.ts.map