@intentius/chant 0.124.32 → 0.124.34

package/dist/workspace/release-candidates.js

@@ -0,0 +1,233 @@
+/**
+ * The `release-candidates` read (#4168 4.2): which green commits of trunk a
+ * person can cut a release from, and what each one would ship.
+ *
+ * `chant release candidates [--env <env>] [--json]` prints this document.
+ * It walks the first-parent line of the trunk (`ci.green.branch`, else what
+ * `origin/HEAD` names, as `release cut` resolves it) from its tip back to the
+ * oldest commit an environment of the member runs, or `limit` commits when an
+ * environment runs no release yet. An environment runs the releases its
+ * latest deploy records name in `releaseDigest`, as the `releases` read
+ * (./releases.ts) says.
+ *
+ * Every green commit that is not revoked is a candidate. Its `changes` are
+ * the first-parent commits after the previous candidate up to and including
+ * it, so the candidates partition the walk. A revoked commit is listed under
+ * `skipped`, and its changes carry on into the next candidate. Commits after
+ * the newest candidate are listed under `pending`: they are not green yet, or
+ * went red.
+ *
+ * For each change it names the work items and other records its
+ * `Chant-Record` trailers name, the pull request a forge's squash subject
+ * names (`... (#123)`), and the merge record `_merges/<sha>.json` on
+ * `chant/lifecycle` when one exists (#4168 4.1). Each candidate lists the
+ * flags whose record files changed in its range, from the declared flag kinds
+ * (#4024).
+ *
+ * It reads local refs and tags only and never fetches. Git is read through a
+ * local `git` subprocess.
+ */
+import { execFileSync } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { latestPerComponent, readReleaseLedger } from "../lifecycle/release-ledger.js";
+import { readAllReleases, readCuts } from "../lifecycle/release-store.js";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+import { readBlobFromPath } from "../lifecycle/git.js";
+import { readerVersion } from "./declaration.js";
+export const RELEASE_CANDIDATES_CONTRACT_VERSION = 1;
+export const RELEASE_CANDIDATES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json";
+/** Why the read stopped. Closed; each code is in `reason-codes.ts`. */
+export const RELEASE_CANDIDATES_ERROR_CODES = ["not-a-git-repository", "ledger-unreadable"];
+/** How many first-parent commits the walk reads when no environment bounds it. */
+export const DEFAULT_CANDIDATE_LIMIT = 50;
+function git(top, args) {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 }).trim();
+}
+function tryGit(top, args) {
+    try {
+        return git(top, args);
+    }
+    catch {
+        return null;
+    }
+}
+const PR_IN_SUBJECT = /\(#(\d+)\)\s*$/;
+/** The work ids and `<kind>:<id>` records a commit's `Chant-Record` trailers name. */
+export function recordTrailers(trailers) {
+    const values = Object.entries(trailers)
+        .filter(([k]) => k.toLowerCase() === "chant-record")
+        .flatMap(([, v]) => v);
+    const records = values.map((v) => v.trim()).filter((v) => /^[^:\s]+:\S+$/.test(v));
+    const work = records.filter((r) => r.startsWith("work:")).map((r) => r.slice("work:".length));
+    return { work, records };
+}
+/** The pull request number at the end of a squash subject, or null. */
+export function prFromSubject(subject) {
+    const m = PR_IN_SUBJECT.exec(subject);
+    return m ? Number(m[1]) : null;
+}
+/** Read the release candidates of the member at `query.cwd`. */
+export async function releaseCandidatesDocument(query) {
+    const head = { $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: RELEASE_CANDIDATES_CONTRACT_VERSION, chant: readerVersion() };
+    const cwd = resolve(query.cwd);
+    const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+    if (!top)
+        return { ...head, error: { code: "not-a-git-repository", message: "candidates are read from trunk's commits and tags, and this directory is not in a git repository" } };
+    try {
+        const { scopeSource } = await import("./write-scope.js");
+        const { resolveTrunk } = await import("../lifecycle/release-workstation.js");
+        const { judgedCiTags } = await import("../lifecycle/release-revocation.js");
+        const { commitDetails } = await import("./intent.js");
+        const source = scopeSource(cwd);
+        const green = source.declaration?.ci?.green ?? null;
+        const trunk = resolveTrunk(top, green?.branch ?? null);
+        const tip = tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${trunk.remote}/${trunk.branch}^{commit}`]) ??
+            tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk.branch}^{commit}`]);
+        const ledger = await resolveMemberLedger(cwd);
+        const loc = { cwd };
+        // What each environment runs.
+        const { readMemberPromotionOrder } = await import("./promotion-order.js");
+        const order = ((await readMemberPromotionOrder(cwd)) ?? []).map((s) => s.name);
+        const envNames = query.env !== undefined ? [query.env] : order;
+        const { releases } = await readAllReleases(loc);
+        const { cuts } = await readCuts(loc);
+        const commitOf = new Map(releases.map((r) => [r.releaseDigest, r.commit]));
+        const labelOf = new Map();
+        const cutAt = new Map();
+        for (const c of cuts) {
+            if (c.label !== null && !labelOf.has(c.releaseDigest))
+                labelOf.set(c.releaseDigest, c.label);
+            if (!cutAt.has(c.releaseDigest) || c.timestamp > cutAt.get(c.releaseDigest))
+                cutAt.set(c.releaseDigest, c.timestamp);
+        }
+        const environments = [];
+        for (const env of envNames) {
+            const { records } = await readReleaseLedger(env, loc);
+            const byDigest = new Map();
+            for (const record of latestPerComponent(records).values()) {
+                const digest = record.releaseDigest;
+                if (typeof digest !== "string")
+                    continue;
+                byDigest.set(digest, [...(byDigest.get(digest) ?? []), record.component].sort());
+            }
+            const running = [...byDigest]
+                .map(([releaseDigest, components]) => ({ releaseDigest, label: labelOf.get(releaseDigest) ?? null, commit: commitOf.get(releaseDigest) ?? null, components }))
+                .sort((a, b) => ((cutAt.get(b.releaseDigest) ?? "") < (cutAt.get(a.releaseDigest) ?? "") ? -1 : 1));
+            environments.push({ env, running });
+        }
+        const empty = { ...head, member: ledger.members.length > 0 ? ledger.members.join("/") : null, branch: trunk.branch, tip, environments, since: null, candidates: [], skipped: [], pending: [] };
+        if (!tip)
+            return empty;
+        // The oldest commit any environment runs bounds the walk, when every environment runs one.
+        const limit = query.limit ?? DEFAULT_CANDIDATE_LIMIT;
+        const line = git(top, ["rev-list", "--first-parent", `--max-count=${Math.max(limit, 1) * 20}`, tip]).split("\n").filter(Boolean);
+        const position = new Map(line.map((sha, i) => [sha, i]));
+        const runningCommits = (e) => e.running.map((r) => r.commit).filter((c) => c !== null && position.has(c));
+        const bounded = environments.length > 0 && environments.every((e) => runningCommits(e).length > 0);
+        let since = null;
+        let walk = line.slice(0, limit);
+        if (bounded) {
+            const oldest = Math.max(...environments.flatMap((e) => runningCommits(e).map((c) => position.get(c))));
+            since = line[oldest];
+            walk = line.slice(0, oldest);
+        }
+        // An environment's newest running commit on the line, by position (smaller is newer).
+        const newestRun = new Map(environments.map((e) => [e.env, Math.min(...runningCommits(e).map((c) => position.get(c)), Number.POSITIVE_INFINITY)]));
+        const tags = await judgedCiTags(top, green);
+        const details = commitDetails(top, walk);
+        const merges = new Map();
+        for (const sha of walk) {
+            const text = (await readBlobFromPath("_merges", `${sha}.json`, loc)) ?? (ledger.prefix !== "" ? await readBlobFromPath("_merges", `${sha}.json`, { cwd, ledgerPrefix: "" }) : null);
+            if (text === null)
+                continue;
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    merges.set(sha, parsed);
+            }
+            catch {
+                // A merge record that is not JSON is left out.
+            }
+        }
+        const change = (sha) => {
+            const d = details.get(sha);
+            const { work, records } = recordTrailers(d?.trailers ?? {});
+            const merge = merges.get(sha) ?? null;
+            const mergePr = merge && typeof merge.pr === "number" ? merge.pr : null;
+            const subject = d?.subject ?? "";
+            return { commit: sha, subject, date: d?.date ?? "", work, records, pr: mergePr ?? prFromSubject(subject), merge };
+        };
+        const flagReader = await flagsReader(top, source.rootOnDisk);
+        const cutLabels = new Map();
+        for (const r of releases) {
+            const label = labelOf.get(r.releaseDigest);
+            if (label !== undefined)
+                cutLabels.set(r.commit, [...(cutLabels.get(r.commit) ?? []), label].sort());
+        }
+        // Oldest first, so each candidate closes the commits since the previous one.
+        const candidates = [];
+        const skipped = [];
+        let open = [];
+        for (let i = walk.length - 1; i >= 0; i--) {
+            const sha = walk[i];
+            open.push(sha);
+            if (tags.revoked.has(sha)) {
+                skipped.push({ commit: sha, subject: details.get(sha)?.subject ?? "", reason: "revoked" });
+                continue;
+            }
+            if (!tags.green.has(sha))
+                continue;
+            const own = change(sha);
+            candidates.push({
+                commit: sha,
+                subject: own.subject,
+                date: own.date,
+                newFor: environments.filter((e) => i < newestRun.get(e.env)).map((e) => e.env),
+                cut: cutLabels.get(sha) ?? [],
+                changes: open.map(change).reverse(),
+                flags: flagReader(open),
+            });
+            open = [];
+        }
+        return {
+            ...empty,
+            since,
+            candidates: candidates.reverse(),
+            skipped: skipped.reverse(),
+            pending: open.map(change).reverse(),
+        };
+    }
+    catch (err) {
+        return { ...head, error: { code: "ledger-unreadable", message: `reading the candidates failed: ${err instanceof Error ? err.message : String(err)}` } };
+    }
+}
+/** The flags whose record files the given commits change, or a reader that finds none when no flag kind can be read. */
+async function flagsReader(top, root) {
+    if (!root)
+        return () => [];
+    let flags;
+    try {
+        const { readWorkspaceFlags } = await import("./flags-read.js");
+        flags = (await readWorkspaceFlags(root)).flags;
+    }
+    catch {
+        return () => [];
+    }
+    if (flags.length === 0)
+        return () => [];
+    const fromTop = (p) => relative(top, resolve(root, p)).split(sep).join("/");
+    const byPath = new Map(flags.map((f) => [fromTop(f.path), f]));
+    return (shas) => {
+        const touched = new Set();
+        for (const sha of shas) {
+            const names = tryGit(top, ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha]) ?? "";
+            for (const n of names.split("\n"))
+                if (byPath.has(n))
+                    touched.add(n);
+        }
+        return [...touched]
+            .sort()
+            .map((p) => byPath.get(p))
+            .map((f) => ({ id: f.id, member: f.member, param: f.param, path: f.path, values: f.values }));
+    };
+}

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

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

package/dist/workspace/release-workflow.d.ts

@@ -0,0 +1,31 @@
+import type { SecurityGroup } from "./security.js";
+export declare const RELEASE_WORKFLOW_FORGES: readonly ["github", "forgejo", "gitlab"];
+export type ReleaseWorkflowForge = (typeof RELEASE_WORKFLOW_FORGES)[number];
+/** Where each forge's publish workflow is written, relative to the repository root. */
+export declare const RELEASE_WORKFLOW_FILES: Record<ReleaseWorkflowForge, string>;
+export interface ReleaseWorkflowInput {
+    forge: ReleaseWorkflowForge;
+    /** The security groups the workspace opts into at its root. */
+    groups: ReadonlySet<SecurityGroup>;
+    /** The command that installs what the build needs. Default `npm ci`. */
+    install?: string;
+    /** The command that builds what the targets upload, or none. Default `npm run build`. */
+    build?: string | null;
+    /** What runs chant. Default `npx chant`. */
+    chant?: string;
+    /** The workspace root relative to the repository root, `.` at the top. */
+    workspaceRoot?: string;
+}
+/** The flags `chant release publish` gets under the groups. */
+export declare function publishFlags(groups: ReadonlySet<SecurityGroup>): string[];
+/** The workflow file's text, without the generated-by header. */
+export declare function renderReleaseWorkflow(input: ReleaseWorkflowInput): string;
+/** The header that marks the file generated, naming the command that regenerates it. */
+export declare function releaseWorkflowHeader(command: string): string;
+/**
+ * `chant release workflow [--forge github|gitlab|forgejo] [--install <command>]
+ * [--build <command>|--no-build] [--chant <command>] [--output <file>]`: write
+ * the publish workflow for the workspace's forge, under its security groups.
+ */
+export declare function runReleaseWorkflow(ctx: import("../cli/registry.js").CommandContext): Promise<number>;
+//# sourceMappingURL=release-workflow.d.ts.map

package/dist/workspace/release-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-workflow.d.ts","sourceRoot":"","sources":["../../src/workspace/release-workflow.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,uBAAuB,YAAI,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,uFAAuF;AACvF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAKvE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,+DAA+D;IAC/D,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,GAAG,MAAM,EAAE,CAEzE;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAwDzE;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,OAAO,iBAAiB,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CvG"}