@intentius/chant 0.124.28 → 0.124.30

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

@@ -21,7 +21,8 @@
  * component gate in a plain `run --components` binds a lifecycle-plan digest
  * and stores nothing here.
  *
- * How long a stored change set is kept is #4036's retention policy.
+ * `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";

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

@@ -1 +1 @@
-{"version":3,"file":"change-set-store.d.ts","sourceRoot":"","sources":["../../src/lifecycle/change-set-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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"}
+{"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

@@ -21,7 +21,8 @@
  * component gate in a plain `run --components` binds a lifecycle-plan digest
  * and stores nothing here.
  *
- * How long a stored change set is kept is #4036's retention policy.
+ * `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";

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-metrics.d.ts","sourceRoot":"","sources":["../../src/lifecycle/delivery-metrics.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/delivery-metrics.js

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+/** The failure window when the declaration's `metrics.failureWindowDays` is not set. */
+export const DEFAULT_FAILURE_WINDOW_DAYS = 7;
+const DAY_MS = 86400000;
+/**
+ * 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 function rollbackOf(record) {
+    return record.restores ?? 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 function isRedeploy(record) {
+    return record.redeploys !== undefined;
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const s = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(s.length / 2);
+    return Math.round(s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2);
+}
+const at = (iso) => Date.parse(iso);
+const ref = (r) => ({ runId: r.runId, timestamp: r.timestamp });
+/**
+ * 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 function environmentMetrics(env, records, lookups, window, failureWindowDays = DEFAULT_FAILURE_WINDOW_DAYS) {
+    // Ledger order breaks timestamp ties, as `latestPerComponent` does.
+    const sorted = records.map((r, i) => ({ r, i })).sort((a, b) => at(a.r.timestamp) - at(b.r.timestamp) || a.i - b.i).map((x) => x.r);
+    const since = at(window.since);
+    const until = at(window.until);
+    const failureMs = failureWindowDays * DAY_MS;
+    const inWindow = (r) => at(r.timestamp) >= since && at(r.timestamp) <= until;
+    const facts = sorted.map((r) => {
+        const releaseDigest = lookups.releaseOf(r) ?? null;
+        const commit = (releaseDigest !== null ? lookups.commitOfRelease(releaseDigest) : null) ?? r.gitSha;
+        return { r, releaseDigest, commit, revocation: lookups.revocationOf(commit) };
+    });
+    // A redeploy puts the running release back: it is counted apart, and
+    // neither fails nor restores on its own.
+    const deployments = facts.filter((f) => inWindow(f.r) && !isRedeploy(f.r));
+    const failures = [];
+    for (const [i, f] of facts.entries()) {
+        if (!inWindow(f.r) || isRedeploy(f.r))
+            continue;
+        const t = at(f.r.timestamp);
+        const later = facts.slice(i + 1).filter((g) => g.r.component === f.r.component);
+        // Revoked within the window after the deploy. A tag with no time, or one
+        // made before the deploy, revokes what was deployed all the same.
+        const revoked = f.revocation !== null && (f.revocation.tagged === null || at(f.revocation.tagged) - t <= failureMs) ? f.revocation : null;
+        // Rolled back from it: the next deploy of the component that is not a
+        // redeploy is a rollback, within the window.
+        const next = later.find((g) => !isRedeploy(g.r));
+        const rolledBack = next !== undefined && rollbackOf(next.r) !== null && at(next.r.timestamp) - t <= failureMs ? next.r : null;
+        if (!revoked && !rolledBack)
+            continue;
+        const restore = later.find((g) => !isRedeploy(g.r) && g.revocation === null);
+        failures.push({
+            component: f.r.component,
+            timestamp: f.r.timestamp,
+            runId: f.r.runId,
+            releaseDigest: f.releaseDigest,
+            label: f.releaseDigest !== null ? lookups.labelOf(f.releaseDigest) : null,
+            commit: f.commit,
+            causes: [...(revoked ? ["revoked"] : []), ...(rolledBack ? ["rolled-back"] : [])],
+            revoked,
+            rolledBackBy: rolledBack ? ref(rolledBack) : null,
+            restoredBy: restore ? ref(restore.r) : null,
+            restoreSeconds: restore ? Math.round((at(restore.r.timestamp) - t) / 1000) : null,
+        });
+    }
+    // Lead time: one change per release, or per commit deployed from no
+    // release, timed at its first deploy in this environment.
+    const firstDeploy = new Map();
+    for (const f of facts) {
+        const key = f.releaseDigest !== null ? `release:${f.releaseDigest}` : `commit:${f.r.gitSha}`;
+        if (!firstDeploy.has(key))
+            firstDeploy.set(key, f);
+    }
+    const leads = [];
+    let fromRelease = 0;
+    let unknown = 0;
+    for (const f of firstDeploy.values()) {
+        if (!inWindow(f.r))
+            continue;
+        const committed = lookups.commitTime(f.commit);
+        if (committed === null) {
+            unknown++;
+            continue;
+        }
+        leads.push(Math.max(0, (at(f.r.timestamp) - committed) / 1000));
+        if (f.releaseDigest !== null)
+            fromRelease++;
+    }
+    const weeks = Math.max(until - since, DAY_MS) / (7 * DAY_MS);
+    const restored = failures.filter((x) => x.restoreSeconds !== null);
+    return {
+        env,
+        deployments: {
+            count: deployments.length,
+            redeploys: facts.filter((f) => inWindow(f.r) && isRedeploy(f.r)).length,
+            runs: new Set(deployments.map((f) => f.r.runId)).size,
+            fromRelease: deployments.filter((f) => f.releaseDigest !== null).length,
+            perWeek: Math.round((deployments.length / weeks) * 100) / 100,
+        },
+        leadTime: { changes: leads.length, fromRelease, fromCommit: leads.length - fromRelease, unknown, medianSeconds: median(leads) },
+        changeFailure: {
+            deployments: deployments.length,
+            failed: failures.length,
+            revoked: failures.filter((x) => x.revoked !== null).length,
+            rolledBack: failures.filter((x) => x.rolledBackBy !== null).length,
+            rate: deployments.length === 0 ? null : Math.round((failures.length / deployments.length) * 10000) / 10000,
+        },
+        restore: { restored: restored.length, open: failures.length - restored.length, medianSeconds: median(restored.map((x) => x.restoreSeconds)) },
+        failures,
+    };
+}