@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/ci-green-workflow.js

@@ -0,0 +1,199 @@
+/**
+ * The root CI file that runs `chant ci tick` (#3573, ws-103; ws-042 for its
+ * place at the repository root, #2524 D14 for its header and record).
+ *
+ * `chant ci workflow` writes `.github/workflows/chant-ci-green.yml`. It runs
+ * the tick when a workflow that holds a required check run completes on the
+ * branch, so a result or a re-run is acted on within seconds, and every 15
+ * minutes as a backstop for a dropped or late event. One concurrency group
+ * that never cancels keeps ticks one at a time.
+ *
+ * GitHub's `workflow_run` names workflows, and `ci.green` names check runs,
+ * so the generator reads the repository's other workflow files and keeps
+ * each workflow with a job whose check-run name meets one of a required
+ * phase's patterns. A job's check run is its `name`, or its id, with
+ * ` (<matrix values>)` after it for a matrix job and ` / <job>` after it for
+ * a job that calls a reusable workflow; a `${{ }}` expression stands for
+ * anything. `--workflow <name>` adds a workflow the scan can't see.
+ *
+ * The tick runs the published chant that wrote the file, through npx.
+ * `--chant <command>` runs another one instead, and `--install <command>`
+ * adds a step that installs it, with setup-node caching npm's downloads when
+ * the workspace root has a `package-lock.json`. chant's own repository uses
+ * both to run its source at the commit it checks out.
+ *
+ * The tick pushes its tags with the credentials actions/checkout leaves in
+ * the clone, the Actions token by default. GitHub treats a new ref to a
+ * commit whose workflow files differ from the default branch's as an update
+ * to those workflows, and the Actions token can never hold the `workflows`
+ * permission, so it is refused there. `--token-secret <NAME>` checks out
+ * with `secrets.<NAME>` instead, and `--app-id-var <VAR> --app-key-secret
+ * <NAME>` mints a GitHub App token first and checks out with that. The
+ * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
+ * a fine-grained personal access token can't call the Checks API.
+ *
+ * Like a member's pipelines (./member-pipeline.ts), the file starts with the
+ * generated-file header naming the command, and the member whose directory
+ * the command runs in records it in its generated-file record, so `WSP081`
+ * allows one declarer.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { GENERATED_MARKER } from "../discovery/files.js";
+import { parseYAMLDocument } from "../yaml.js";
+import { matchesCheckRun } from "./ci-green.js";
+/** Where the workflow goes, relative to the repository root. */
+export const CI_GREEN_WORKFLOW_FILE = ".github/workflows/chant-ci-green.yml";
+export const CI_GREEN_WORKFLOW_NAME = "chant-ci-green";
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const EXPRESSION = /\$\{\{[^}]*\}\}/g;
+/** The check-run names a workflow's jobs report, as patterns: `*` stands for what an expression or a matrix fills in. */
+export function jobCheckRuns(doc) {
+    if (!isObject(doc) || !isObject(doc.jobs))
+        return [];
+    const out = [];
+    for (const [id, job] of Object.entries(doc.jobs)) {
+        if (!isObject(job))
+            continue;
+        const named = typeof job.name === "string" ? job.name : id;
+        const base = named.replace(EXPRESSION, "*");
+        out.push(base);
+        if (isObject(job.strategy) && job.strategy.matrix !== undefined && base === named)
+            out.push(`${base} (*)`);
+        if (typeof job.uses === "string")
+            out.push(`${base} / *`);
+    }
+    return out;
+}
+/** Whether two patterns can name the same check run: either matches the other with its `*` filled in. */
+function meet(a, b) {
+    return matchesCheckRun(a, b.replace(/\*/g, "x")) || matchesCheckRun(b, a.replace(/\*/g, "x"));
+}
+/** The name `workflow_run` knows a workflow by: its `name`, or its path when it has none or the name is an expression. */
+function workflowName(doc, path) {
+    return isObject(doc) && typeof doc.name === "string" && !doc.name.includes("${{") ? doc.name : path;
+}
+/** Find the workflows that hold the required phases' check runs. */
+export function workflowsHolding(green, sources) {
+    const patterns = green.require.flatMap((name) => green.phases.find((p) => p.name === name).runs.map((pattern) => ({ phase: name, pattern })));
+    const workflows = new Set();
+    const met = new Set();
+    const unreadable = [];
+    for (const s of sources) {
+        let doc;
+        try {
+            doc = parseYAMLDocument(s.text);
+        }
+        catch {
+            unreadable.push(s.path);
+            continue;
+        }
+        const runs = jobCheckRuns(doc);
+        for (const p of patterns) {
+            if (!runs.some((r) => meet(p.pattern, r)))
+                continue;
+            workflows.add(workflowName(doc, s.path));
+            met.add(`${p.phase}\0${p.pattern}`);
+        }
+    }
+    return {
+        workflows: [...workflows].sort(),
+        unmatched: patterns.filter((p) => !met.has(`${p.phase}\0${p.pattern}`)),
+        unreadable,
+    };
+}
+/** The repository's GitHub workflow files, other than `skip`. */
+export function readWorkflowSources(repoRoot, skip) {
+    const dir = join(repoRoot, ".github", "workflows");
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => /\.ya?ml$/.test(f))
+        .sort()
+        .map((f) => `.github/workflows/${f}`)
+        .filter((p) => p !== skip)
+        .map((path) => ({ path, text: readFileSync(join(repoRoot, path), "utf-8") }));
+}
+const q = (s) => JSON.stringify(s);
+/** A secret or variable name GitHub accepts: letters, digits and underscores, not starting with a digit. */
+export const ACTIONS_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The workflow's YAML, without the generated-file header. Deterministic: the same input writes the same bytes. */
+export function renderCiGreenWorkflow(input) {
+    const { green } = input;
+    const where = input.workspaceRoot === "." ? [] : [`        working-directory: ${q(input.workspaceRoot)}`];
+    const cache = input.install && input.npmLock ? ["          cache: npm", ...(input.npmLock === "package-lock.json" ? [] : [`          cache-dependency-path: ${q(input.npmLock)}`])] : [];
+    const tick = input.chant ? q(`${input.chant} ci tick`) : `npx --yes @intentius/chant@${input.chantVersion} ci tick`;
+    const push = input.push;
+    const mint = push && "appIdVar" in push
+        ? [
+            "      - name: Mint a GitHub App token that may push tags to commits that change workflows",
+            "        id: app-token",
+            "        uses: actions/create-github-app-token@v2",
+            "        with:",
+            `          app-id: \${{ vars.${push.appIdVar} }}`,
+            `          private-key: \${{ secrets.${push.appKeySecret} }}`,
+        ]
+        : [];
+    const token = !push ? [] : ["secret" in push ? `          token: \${{ secrets.${push.secret} }}` : "          token: ${{ steps.app-token.outputs.token }}"];
+    const lines = [
+        `name: ${CI_GREEN_WORKFLOW_NAME}`,
+        "",
+        "# Tags each commit on the branch that passed its required phases ci/green/<sha>,",
+        "# and a green commit that later fails one ci/revoked/<sha>.",
+        "on:",
+        "  workflow_run:",
+        "    workflows:",
+        ...input.workflows.map((w) => `      - ${q(w)}`),
+        "    types:",
+        "      - completed",
+        "    branches:",
+        `      - ${q(green.branch)}`,
+        "  schedule:",
+        "    - cron: \"*/15 * * * *\"",
+        "  workflow_dispatch: {}",
+        "",
+        "# One tick at a time, and a tick in progress is never cancelled.",
+        "concurrency:",
+        `  group: ${CI_GREEN_WORKFLOW_NAME}`,
+        "  cancel-in-progress: false",
+        "",
+        "permissions:",
+        "  contents: write",
+        "  checks: read",
+        "",
+        "jobs:",
+        "  tick:",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: 15",
+        "    steps:",
+        ...mint,
+        "      - uses: actions/checkout@v6",
+        "        with:",
+        `          ref: ${q(green.branch)}`,
+        "          fetch-depth: 0",
+        ...token,
+        "      - uses: actions/setup-node@v6",
+        "        with:",
+        "          node-version: \"24\"",
+        ...cache,
+        ...(input.install ? ["      - name: Install what the tick runs", ...where, `        run: ${q(input.install)}`] : []),
+        "      - name: Tag the commits that turned green, revoke the ones that turned red",
+        ...where,
+        "        env:",
+        "          GITHUB_TOKEN: ${{ github.token }}",
+        "          GIT_COMMITTER_NAME: github-actions[bot]",
+        "          GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com",
+        `        run: ${tick}`,
+    ];
+    return lines.join("\n") + "\n";
+}
+/** The header line naming the command that regenerates the file, and where to run it. */
+export function ciGreenHeader(command, where) {
+    return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the ${where === "member" ? "member's directory" : "workspace root"})\n`;
+}
+/** Write the file, creating its directory. Returns the path relative to the current directory. */
+export function writeWorkflowFile(target, text) {
+    mkdirSync(dirname(resolve(target)), { recursive: true });
+    writeFileSync(target, text);
+    return relative(process.cwd(), target).split(sep).join("/") || target;
+}

package/dist/workspace/ci-green.js

@@ -0,0 +1,325 @@
+/**
+ * Which commits passed CI (#3573, ws-103).
+ *
+ * The declaration's `ci.green` names a branch, a window and phases, each
+ * phase a list of check-run name patterns. A phase passes when every check
+ * run its patterns match finished with success, judged by each run's latest
+ * attempt. A run that finished as skipped passes only in a phase declared
+ * `skipped: pass`. A run still going, or a pattern no run matches yet, leaves
+ * the phase undecided. A commit passes when every phase in `require` passes,
+ * and fails when one of them fails.
+ *
+ * What chant concluded is kept in git as two kinds of annotated tag, each
+ * made once and never moved or deleted by chant:
+ *
+ *   ci/green/<sha>     every required phase passed; the annotation gives the
+ *                      time and each phase's runs
+ *   ci/revoked/<sha>   a green commit later failed a required phase (a re-run
+ *                      that went red); the annotation gives the phase, the
+ *                      run and the time
+ *
+ * {@link ciTick} walks the branch's first-parent commits within the window,
+ * tags the ones that turned green and revokes the green ones that turned red.
+ * It is idempotent: a second tick over the same check runs changes nothing.
+ * A revoked commit is never looked at again, so it goes green again only
+ * when someone deletes its revoked tag by hand, which leaves its green tag
+ * standing. {@link lastGreen} reads the tags alone, with no forge.
+ *
+ * The forge is asked only for check runs (`./ci-green-forge.ts`). The tags
+ * are fetched from and pushed to the remote with git.
+ */
+import { execFileSync } from "node:child_process";
+import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError } from "./declaration.js";
+import { gitTop } from "./tree.js";
+import { locateWorkspace } from "./which-chant.js";
+export const CI_GREEN_TAG_PREFIX = "ci/green/";
+export const CI_REVOKED_TAG_PREFIX = "ci/revoked/";
+export const CI_LAST_GREEN_CONTRACT_VERSION = 1;
+export const CI_LAST_GREEN_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-last-green/v1/ci-last-green.schema.json";
+/** Why `ci last-green` or `ci tick` could not start. Closed. */
+export const CI_GREEN_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "ci-green-undeclared", "ci-branch-unknown"];
+export class CiGreenError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CiGreenError";
+    }
+}
+/** Whether a check run's name matches a pattern: the whole name, `*` standing for any run of characters. */
+export function matchesCheckRun(pattern, name) {
+    const re = new RegExp(`^${pattern.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`, "s");
+    return re.test(name);
+}
+/** Each check run's latest attempt, by name: the run with the largest id. */
+export function latestAttempts(runs) {
+    const byName = new Map();
+    for (const r of runs) {
+        const seen = byName.get(r.name);
+        if (!seen || r.id > seen.id)
+            byName.set(r.name, r);
+    }
+    return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+function runVerdict(phase, r) {
+    if (r.status !== "completed")
+        return "pending";
+    if (r.conclusion === "success")
+        return "pass";
+    if (r.conclusion === "skipped")
+        return phase.skipped === "pass" ? "pass" : "fail";
+    return "fail";
+}
+/** Judge one phase against a commit's latest attempts. */
+export function evaluatePhase(phase, latest) {
+    const runs = [];
+    const unmatched = [];
+    for (const pattern of phase.runs) {
+        const matched = latest.filter((r) => matchesCheckRun(pattern, r.name));
+        if (matched.length === 0)
+            unmatched.push(pattern);
+        for (const r of matched) {
+            if (runs.some((x) => x.name === r.name))
+                continue;
+            runs.push({ name: r.name, id: r.id, status: r.status, conclusion: r.conclusion, url: r.url, verdict: runVerdict(phase, r) });
+        }
+    }
+    const verdict = runs.some((r) => r.verdict === "fail")
+        ? "fail"
+        : runs.some((r) => r.verdict === "pending") || unmatched.length > 0
+            ? "pending"
+            : "pass";
+    return { phase: phase.name, verdict, runs, unmatched };
+}
+/** Judge a commit: it fails when a required phase fails, and passes when every one passes. */
+export function evaluateCommit(green, runs) {
+    const latest = latestAttempts(runs);
+    const phases = green.require.map((name) => evaluatePhase(green.phases.find((p) => p.name === name), latest));
+    const failed = phases.find((p) => p.verdict === "fail");
+    if (failed)
+        return { verdict: "fail", phases, failure: { phase: failed.phase, run: failed.runs.find((r) => r.verdict === "fail") } };
+    return { verdict: phases.some((p) => p.verdict === "pending") ? "pending" : "pass", phases, failure: null };
+}
+/** A time as an annotation and a tick report write it: UTC, to the second. */
+const iso = (d) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
+/** `window` (`90m`, `24h`, `7d`) in milliseconds. */
+export function windowMs(window) {
+    const m = /^([1-9][0-9]*)(m|h|d)$/.exec(window);
+    if (!m)
+        throw new Error(`ci.green.window must be a number of minutes, hours or days, such as 24h, not ${JSON.stringify(window)}`);
+    return Number(m[1]) * { m: 60000, h: 3600000, d: 86400000 }[m[2]];
+}
+const runRecord = (r) => ({ name: r.name, id: r.id, conclusion: r.conclusion, url: r.url });
+/** The annotation of a green tag: a subject line, then the record as JSON. */
+export function greenAnnotation(green, sha, verdict, at) {
+    const record = {
+        schema: 1,
+        tag: "green",
+        commit: sha,
+        branch: green.branch,
+        at: iso(at),
+        phases: Object.fromEntries(verdict.phases.map((p) => [p.phase, p.runs.map(runRecord)])),
+    };
+    return `ci: every required phase passed (${green.require.join(", ")})\n\n${JSON.stringify(record, null, 2)}\n`;
+}
+/** The annotation of a revoked tag: the phase and the run that failed, and the time. */
+export function revokedAnnotation(green, sha, failure, at) {
+    const record = { schema: 1, tag: "revoked", commit: sha, branch: green.branch, at: iso(at), phase: failure.phase, run: runRecord(failure.run) };
+    return `ci: phase ${failure.phase} failed in ${failure.run.name} (${failure.run.conclusion ?? failure.run.status})\n\n${JSON.stringify(record, null, 2)}\n`;
+}
+/**
+ * Decide what a tick does, without touching git: a commit with no green tag
+ * whose required phases all passed gets one, and a green commit with no
+ * revoked tag that now fails a required phase gets revoked. A revoked commit
+ * is skipped without asking the forge.
+ */
+export async function planTick(input) {
+    const out = [];
+    for (const c of input.commits) {
+        const before = input.revokedTags.has(c.sha) ? "revoked" : input.greenTags.has(c.sha) ? "green" : "none";
+        if (before === "revoked") {
+            out.push({ ...c, before, made: null });
+            continue;
+        }
+        const verdict = evaluateCommit(input.green, await input.checkRuns(c.sha));
+        let made = null;
+        if (before === "none" && verdict.verdict === "pass") {
+            made = { tag: `${CI_GREEN_TAG_PREFIX}${c.sha}`, message: greenAnnotation(input.green, c.sha, verdict, input.now) };
+        }
+        else if (before === "green" && verdict.verdict === "fail") {
+            made = { tag: `${CI_REVOKED_TAG_PREFIX}${c.sha}`, message: revokedAnnotation(input.green, c.sha, verdict.failure, input.now) };
+        }
+        out.push({ ...c, before, verdict, made });
+    }
+    return out;
+}
+function git(top, args) {
+    return execFileSync("git", args, {
+        cwd: top,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        maxBuffer: 256 * 1024 * 1024,
+    }).trimEnd();
+}
+function tryGit(top, args) {
+    try {
+        return git(top, args);
+    }
+    catch {
+        return null;
+    }
+}
+/** The ci tags in the repository: the commits with a green tag, and those with a revoked one. */
+export function readCiTags(top) {
+    const green = new Map();
+    const revoked = new Set();
+    const lines = git(top, ["for-each-ref", "--format=%(refname:lstrip=2)%09%(taggerdate:iso-strict)", `refs/tags/${CI_GREEN_TAG_PREFIX}`, `refs/tags/${CI_REVOKED_TAG_PREFIX}`]);
+    for (const line of lines.split("\n").filter(Boolean)) {
+        const [tag, date] = line.split("\t");
+        if (tag.startsWith(CI_GREEN_TAG_PREFIX))
+            green.set(tag.slice(CI_GREEN_TAG_PREFIX.length), date ?? "");
+        else
+            revoked.add(tag.slice(CI_REVOKED_TAG_PREFIX.length));
+    }
+    return { green, revoked };
+}
+/** The declaration's `ci.green`, read where `cwd` is, and the git top. */
+function readGreen(cwd) {
+    const located = locateWorkspace(cwd);
+    const declaration = readDeclaration(located.tree);
+    const green = declaration.ci?.green ?? null;
+    if (!green)
+        throw new CiGreenError("ci-green-undeclared", `${declaration.file} declares no ci.green, so chant does not know which check runs make a commit green`);
+    const top = located.top ?? gitTop(cwd);
+    if (!top)
+        throw new WorkspaceReadError("not-a-git-repository", "the ci tags are git tags, and this directory is not in a git repository");
+    return { green, top, workspace: { name: declaration.name, root: located.root, file: declaration.file } };
+}
+/**
+ * One tick: fetch the branch and the ci tags from the remote (pruning a ci
+ * tag deleted there by hand), judge the first-parent commits within the
+ * window, make the tags that are due and push them, never forced.
+ */
+export async function ciTick(req) {
+    const { green, top } = readGreen(req.cwd);
+    const remote = req.remote ?? "origin";
+    const now = req.now ?? new Date();
+    const tracking = `refs/remotes/${remote}/${green.branch}`;
+    try {
+        git(top, ["fetch", "--quiet", "--no-tags", "--prune", remote, `+refs/heads/${green.branch}:${tracking}`, "+refs/tags/ci/*:refs/tags/ci/*"]);
+    }
+    catch (err) {
+        throw new Error(`could not fetch ${green.branch} and the ci tags from ${remote}: ${stderrOf(err)}`);
+    }
+    if (tryGit(top, ["rev-parse", "--verify", "--quiet", `${tracking}^{commit}`]) === null) {
+        throw new CiGreenError("ci-branch-unknown", `${remote} has no branch ${green.branch}`);
+    }
+    const cutoff = Math.floor((now.getTime() - windowMs(green.window)) / 1000);
+    const commits = git(top, ["log", "--first-parent", `--max-age=${cutoff}`, "--format=%H %ct", tracking])
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => line.split(" "))
+        .filter(([, ct]) => Number(ct) >= cutoff)
+        .map(([sha, ct]) => ({ sha, committed: iso(new Date(Number(ct) * 1000)) }));
+    const tags = readCiTags(top);
+    const planned = await planTick({
+        green,
+        commits,
+        greenTags: new Set(tags.green.keys()),
+        revokedTags: tags.revoked,
+        checkRuns: (sha) => req.forge.checkRuns(sha),
+        now,
+    });
+    const due = planned.filter((c) => c.made !== null);
+    if (!req.dryRun && due.length > 0) {
+        const ident = taggerConfig(top);
+        for (const c of due)
+            git(top, [...ident, "tag", "-a", "-m", c.made.message, c.made.tag, c.sha]);
+        try {
+            git(top, ["push", "--quiet", remote, ...due.map((c) => `refs/tags/${c.made.tag}`)]);
+        }
+        catch (err) {
+            // The local tags stay until the next tick's fetch prunes the ones the remote lacks.
+            const stderr = stderrOf(err);
+            const cause = pushRefusalCause(stderr);
+            throw new Error(`could not push ${due.map((c) => c.made.tag).join(", ")} to ${remote}: ${cause ? `${cause}\n` : ""}${stderr}`);
+        }
+    }
+    return { branch: green.branch, window: green.window, ref: tracking, commits: planned, made: due.map((c) => c.made.tag) };
+}
+/**
+ * Why the remote refused a tag push, when chant can tell. GitHub refuses a
+ * new ref to a commit whose workflow files differ from the default branch's
+ * unless the token may update workflows, and the Actions token never may.
+ */
+export function pushRefusalCause(stderr) {
+    if (!/without [`']?workflows?[`']? (permission|scope)/i.test(stderr))
+        return null;
+    return ("GitHub refused the tag push because the tagged commit changes workflow files, and GITHUB_TOKEN can't update workflows: " +
+        "regenerate the workflow with --token-secret <NAME>, naming a secret that holds a fine-grained token with Contents and Workflows read and write, " +
+        "or with --app-id-var <VAR> --app-key-secret <NAME> for a GitHub App's token");
+}
+/** A tagger for an annotated tag when git has none configured, as on a fresh CI runner. The environment's GIT_COMMITTER_* still win. */
+function taggerConfig(top) {
+    const out = [];
+    if (tryGit(top, ["config", "user.name"]) === null)
+        out.push("-c", "user.name=chant");
+    if (tryGit(top, ["config", "user.email"]) === null)
+        out.push("-c", "user.email=chant@localhost");
+    return out;
+}
+function stderrOf(err) {
+    const e = err;
+    return String(e.stderr ?? e.message ?? err).trim();
+}
+/** The text `chant ci tick` prints. */
+export function formatTick(r, dryRun = false) {
+    const lines = [`${r.branch}, commits within ${r.window}: ${r.commits.length}`];
+    for (const c of r.commits) {
+        const short = c.sha.slice(0, 12);
+        if (c.made) {
+            lines.push(`  ${short}  ${dryRun ? "would make" : "made"} ${c.made.tag.slice(0, c.made.tag.lastIndexOf("/"))}${c.verdict?.failure ? `: phase ${c.verdict.failure.phase}, ${c.verdict.failure.run.name} ${c.verdict.failure.run.conclusion}` : ""}`);
+        }
+        else if (c.before === "revoked") {
+            lines.push(`  ${short}  revoked`);
+        }
+        else {
+            const v = c.verdict;
+            const waiting = v.phases.filter((p) => p.verdict === "pending").map((p) => p.phase);
+            const what = c.before === "green" ? "green" : v.verdict === "fail" ? `failed: phase ${v.failure.phase}, ${v.failure.run.name} ${v.failure.run.conclusion}` : `undecided: ${waiting.join(", ")}`;
+            lines.push(`  ${short}  ${what}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * `chant ci last-green`: the newest first-parent commit of the branch with a
+ * green tag and no revoked tag. It reads local refs and tags and never
+ * fetches, so a reader fetches first (`git fetch origin --tags`).
+ */
+export function lastGreen(req) {
+    const head = { $schema: CI_LAST_GREEN_SCHEMA_ID, contract: CI_LAST_GREEN_CONTRACT_VERSION, chant: readerVersion() };
+    try {
+        const { green, top, workspace } = readGreen(req.cwd);
+        const candidates = [`refs/remotes/${req.remote ?? "origin"}/${green.branch}`, `refs/heads/${green.branch}`];
+        const ref = candidates.find((r) => tryGit(top, ["rev-parse", "--verify", "--quiet", `${r}^{commit}`]) !== null);
+        if (!ref)
+            throw new CiGreenError("ci-branch-unknown", `this repository has neither ${candidates.join(" nor ")}`);
+        const tags = readCiTags(top);
+        let commit = null;
+        if (tags.green.size > 0) {
+            for (const sha of git(top, ["rev-list", "--first-parent", ref]).split("\n")) {
+                if (!tags.green.has(sha) || tags.revoked.has(sha))
+                    continue;
+                commit = { sha, tag: `${CI_GREEN_TAG_PREFIX}${sha}`, tagged: tags.green.get(sha) || null, committed: git(top, ["show", "-s", "--format=%cI", sha]) };
+                break;
+            }
+        }
+        return { ...head, workspace, branch: green.branch, ref, commit };
+    }
+    catch (err) {
+        if (err instanceof CiGreenError || err instanceof WorkspaceReadError)
+            return { ...head, error: { code: err.code, message: err instanceof WorkspaceReadError ? err.describe() : err.message } };
+        throw err;
+    }
+}

package/dist/workspace/ci-last-green.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ci-last-green/v1/ci-last-green.schema.json",
+  "title": "chant ci last-green output",
+  "description": "What `chant ci last-green --json` prints (#3573, ws-103): the newest first-parent commit of the branch ci.green names that has a ci/green/<sha> tag and no ci/revoked/<sha> tag. 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.108.0 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0, with or without a green commit.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "workspace",
+        "branch",
+        "ref",
+        "commit"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ci-last-green/v1/ci-last-green.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "workspace": {
+          "type": "object",
+          "required": [
+            "name",
+            "root",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "root": {
+              "type": "string",
+              "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself."
+            },
+            "file": {
+              "enum": [
+                "chant.workspace.json",
+                "chant.workspace.jsonc"
+              ]
+            }
+          }
+        },
+        "branch": {
+          "type": "string",
+          "description": "ci.green.branch."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The ref whose first-parent commits were walked: refs/remotes/origin/<branch> when the checkout has it, else refs/heads/<branch>."
+        },
+        "commit": {
+          "description": "The newest green commit that is not revoked, or null when there is none.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "sha",
+                "tag",
+                "tagged",
+                "committed"
+              ],
+              "properties": {
+                "sha": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{40,64}$"
+                },
+                "tag": {
+                  "type": "string",
+                  "description": "ci/green/<sha>."
+                },
+                "tagged": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "When the green tag was made, ISO 8601, or null for a lightweight tag."
+                },
+                "committed": {
+                  "type": "string",
+                  "description": "The commit's committer time, ISO 8601."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ci-last-green/v1/ci-last-green.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "ci-green-undeclared",
+                "ci-branch-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}