@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/handlers/gate-resume.js

@@ -0,0 +1,275 @@
+/**
+ * `chant approve <op> <gate> --resume` and `chant run resume` (#3683): start
+ * the CI job that waits at a gate again once its approval has arrived. See
+ * `../../op/gate-resume.ts` for what each forge is asked and the token it
+ * needs. Neither approves anything.
+ *
+ * A gate that asks a decision point (#3170) waits on a question, not on an
+ * approval: its pending fact cites the question, and the gate's resolution is
+ * only written when the run asks again. So such a fact is resumable once the
+ * question has an answer that passes the gate (`pointGateResumable`, #3835),
+ * and `chant workspace points answer --resume` resumes the job right after
+ * the answer.
+ *
+ * What to resume is decided from the ledger by `planGateResumes`
+ * (`../../op/gate-resume-plan.ts`, #3858): an approval a wave already applied
+ * under is spent and resumes nothing, and an apply under an approval that
+ * stopped (an applied line with a run locator and no finished line) resumes
+ * once the forge says its run is gone.
+ */
+import { GATES_DIR, readGateLedger, } from "../../lifecycle/gate-ledger.js";
+import { appliedGatePath, parseAppliedGateFile } from "../../lifecycle/gate-applied.js";
+import { listFilesInDir, pushLifecycleStatus, readBlobFromPath, requireLifecycleLedger } from "../../lifecycle/git.js";
+import { parseGateSubject } from "../../op/gate-point.js";
+import { resolutionAnswering, resumeGateRun, resumeTokenFromEnv, } from "../../op/gate-resume.js";
+import { planGateResumes } from "../../op/gate-resume-plan.js";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format.js";
+/** Every question the workspace at `cwd` lists, by id, the lifecycle ledger's included. Empty when the workspace can't be read. */
+export async function workspaceQuestions(cwd) {
+    const { workspacePoints } = await import("../../workspace/points-cli.js");
+    const doc = await workspacePoints({ cwd }).catch(() => undefined);
+    if (!doc || !("questions" in doc))
+        return new Map();
+    return new Map(doc.questions.map((q) => [q.id, { id: q.id, state: q.state, answer: q.answer, answeredBy: q.answeredBy, answeredOn: q.answeredOn }]));
+}
+/** Resume the job behind one standing pending fact, when an approval answers it and is not spent. */
+export async function resumeStanding(standing, resolutions, opts = {}, pending = [standing]) {
+    const [candidate] = planGateResumes({
+        op: standing.op,
+        pending: [standing],
+        resolutions,
+        applied: opts.applied ?? [],
+        now: standing.timestamp,
+        ...(opts.questions ? { questions: opts.questions } : {}),
+        answering: (r, s) => resolutionAnswering(r, s, pending),
+    });
+    return resumeCandidate(candidate, opts);
+}
+/**
+ * Act on one candidate {@link planGateResumes} decided: start its job again
+ * through the forge, or under `dryRun` ask the forge whether it would. A
+ * stopped apply is resumed only once the forge says its run is gone.
+ */
+export async function resumeCandidate(c, opts = {}) {
+    const base = {
+        op: c.op,
+        gate: c.gate,
+        ...(c.environment !== undefined ? { environment: c.environment } : {}),
+        source: c.source,
+        status: "not-approved",
+        reason: c.reason,
+        resumable: c.resumable,
+        message: c.message,
+        ...(c.planDigest !== undefined ? { planDigest: c.planDigest } : {}),
+        ...(c.approvedBy !== undefined ? { approvedBy: c.approvedBy } : {}),
+        ...(c.approvedAt !== undefined ? { approvedAt: c.approvedAt } : {}),
+        ...(c.run?.url ? { url: c.run.url } : {}),
+        ...(c.run ? { run: c.run } : {}),
+        ...(c.spent ? { spent: c.spent } : {}),
+        ...(c.stopped ? { stopped: { ...c.stopped } } : {}),
+    };
+    if (c.reason === "spent")
+        return { ...base, status: "spent" };
+    if (!c.resumable)
+        return base;
+    if (!c.run) {
+        return { ...base, status: "no-job", message: "its pending fact names no CI job (it was recorded outside CI); run it again by hand" };
+    }
+    const stopped = c.source === "stopped";
+    const token = resumeTokenFromEnv(c.run.forge, opts.env ?? process.env);
+    // A waiting job needs no forge call to say it would resume; a stopped apply needs one to know its run is gone.
+    if (opts.dryRun && !stopped)
+        return { ...base, status: "would-resume", message: `would resume ${c.run.forge} run ${c.run.run}; ${c.message}` };
+    if (!token) {
+        const need = `${c.run.forge === "gitlab" ? "GITLAB_TOKEN" : "GITHUB_TOKEN"}`;
+        return {
+            ...base,
+            ...(stopped ? { resumable: false } : {}),
+            status: "no-token",
+            message: stopped
+                ? `${c.message}; whether run ${c.run.run} is gone needs a token to read ${c.run.forge} with: set CHANT_FORGE_TOKEN (or ${need})`
+                : `no token to call ${c.run.forge} with: set CHANT_FORGE_TOKEN (or ${need})`,
+        };
+    }
+    try {
+        const since = stopped ? c.stopped.appliedAt : c.approvedAt;
+        const outcome = await resumeGateRun(c.run, { token, ...(since ? { since } : {}), ...(opts.fetch ? { fetch: opts.fetch } : {}), ...(opts.dryRun ? { dryRun: true } : {}) });
+        const message = outcome.status === "skipped" ? outcome.reason : outcome.how;
+        if (!stopped)
+            return { ...base, status: outcome.status, message };
+        const gone = outcome.status !== "skipped";
+        return {
+            ...base,
+            status: outcome.status,
+            resumable: gone,
+            message: gone ? `the apply that began at ${c.stopped.appliedAt} stopped and its run is gone: ${message}` : `the apply that began at ${c.stopped.appliedAt} is left alone: ${message}`,
+            stopped: { ...c.stopped, runGone: gone },
+        };
+    }
+    catch (err) {
+        return { ...base, status: "failed", message: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** The `applied` and `finished` lines of `_gates/<op>/applied.jsonl` on `chant/lifecycle`. */
+export async function readAppliedGateFile(op) {
+    const { dir, file } = appliedGatePath(op);
+    const text = await readBlobFromPath(dir, file);
+    return text ? parseAppliedGateFile(text) : { applied: [], finished: [] };
+}
+/**
+ * Resume every job waiting on `op`'s gates (or one gate) whose approval
+ * arrived and is not spent, and every apply under an approval that stopped
+ * once its run is gone (#3858).
+ */
+export async function resumeOpGates(op, gate, opts = {}) {
+    const ledger = await readGateLedger(op);
+    const lines = opts.applied ? { applied: opts.applied, finished: opts.finished ?? [] } : await readAppliedGateFile(op);
+    const now = opts.now ?? new Date().toISOString();
+    // Read the workspace's questions once, and only when a fact waits on one (#3835).
+    const questions = opts.questions ?? (ledger.pending.some((p) => p.answer) ? await workspaceQuestions(process.cwd()) : undefined);
+    const candidates = planGateResumes({
+        op,
+        pending: ledger.pending,
+        resolutions: ledger.resolutions,
+        applied: lines.applied,
+        finished: lines.finished,
+        now,
+        ...(gate !== undefined ? { gate } : {}),
+        ...(questions ? { questions } : {}),
+        answering: resolutionAnswering,
+    });
+    const reports = [];
+    for (const c of candidates)
+        reports.push(await resumeCandidate(c, opts));
+    return reports;
+}
+function printReport(r) {
+    const where = `${r.op} / ${r.gate}${r.environment !== undefined ? ` (${r.environment})` : ""}`;
+    const by = r.approvedBy ? `, approved by ${r.approvedBy}` : "";
+    const link = r.url ? ` ${r.url}` : "";
+    if (r.status === "resumed")
+        console.error(formatSuccess(`${where}${by}: ${r.message}${link}`));
+    else if (r.status === "would-resume")
+        console.error(formatInfo(`${where}${by}: ${r.message}${link}`));
+    else if (r.status === "failed" || r.status === "no-token") {
+        console.error(formatError({
+            message: `${where}${by}: not resumed: ${r.message}`,
+            hint: "GitHub needs actions: write; GitLab a token with the api scope and the Developer role; Forgejo a token with write:repository.",
+        }));
+    }
+    else
+        console.error(formatInfo(`${where}${by}: not resumed: ${r.message}${link}`));
+}
+/**
+ * What `chant approve --resume` runs once the approval is recorded and
+ * pushed. Returns the exit code: 0 when the job was resumed or had nothing to
+ * resume, 1 when a forge call failed or no token was found.
+ */
+export async function resumeAfterApproval(op, gate, environment, pushed) {
+    if (!pushed) {
+        console.error(formatWarning({
+            message: "Not resuming: the approval did not reach the remote, so the resumed job would not see it.",
+            hint: "Push chant/lifecycle, then run `chant run resume --op " + op + "`.",
+        }));
+        return 1;
+    }
+    const reports = (await resumeOpGates(op, gate)).filter((r) => environment === undefined || r.environment === environment);
+    if (reports.length === 0) {
+        console.error(formatInfo(`No pending fact for ${op} / ${gate} is waiting, so there is nothing to resume.`));
+        return 0;
+    }
+    for (const r of reports)
+        printReport(r);
+    return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+}
+/**
+ * What `chant workspace points answer --resume` runs once the answer is
+ * written (#3835): resume the job waiting at the gate the question names in
+ * its subject (`gate:<op>/<gate>`), when the answer passes it. The answer has
+ * to be on the remote for the resumed job to see it: one held on
+ * `chant/lifecycle` is pushed again here, and one in the working tree is
+ * not resumed on, since the job reads it only once it is committed and pushed.
+ * Returns the exit code, as {@link resumeAfterApproval} does.
+ */
+export async function resumeAfterAnswer(question, cwd = process.cwd()) {
+    const named = parseGateSubject(question.subject);
+    if (!named) {
+        console.error(formatInfo(`Question ${question.id} names no gate in its subject, so there is nothing to resume.`));
+        return 0;
+    }
+    if (question.ledger === null) {
+        console.error(formatWarning({
+            message: `Not resuming: the answer to ${question.id} is in the working tree, and the resumed job would not see it.`,
+            hint: `Commit and push it, then run \`chant run resume --op ${named.op}\`.`,
+        }));
+        return 1;
+    }
+    if ((await pushLifecycleStatus({ cwd })).status !== "pushed") {
+        console.error(formatWarning({
+            message: "Not resuming: the answer did not reach the remote, so the resumed job would not see it.",
+            hint: `Push chant/lifecycle, then run \`chant run resume --op ${named.op}\`.`,
+        }));
+        return 1;
+    }
+    const reports = (await resumeOpGates(named.op, named.gate)).filter((r) => r.environment === undefined);
+    if (reports.length === 0) {
+        console.error(formatInfo(`No pending fact for ${named.op} / ${named.gate} is waiting, so there is nothing to resume.`));
+        return 0;
+    }
+    for (const r of reports)
+        printReport(r);
+    return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+}
+/**
+ * What `chant run resume` does, callable in process: read the gate ledgers
+ * (`op`'s alone, when given) and start again each CI job that waits at a
+ * gate an approval now answers. With `gate`, only that gate's job is touched,
+ * so a caller that just approved one wave resumes that wave's job and no
+ * other (#3854). The lifecycle ledger has to be readable
+ * (`requireLifecycleLedger`).
+ */
+export async function resumeWaitingGates(opts = {}) {
+    const { op, gate, ...rest } = opts;
+    const ops = op ? [op] : (await listFilesInDir(GATES_DIR)).filter((f) => f.endsWith(".jsonl")).map((f) => f.slice(0, -".jsonl".length));
+    const reports = [];
+    for (const o of ops)
+        reports.push(...(await resumeOpGates(o, gate, rest)));
+    return reports;
+}
+/**
+ * `chant run resume [--op <op>] [--gate <gate>] [--dry-run] [--json]`: the
+ * scheduled job. Reads every gate ledger on `chant/lifecycle` (or `--op`'s),
+ * and starts again each CI job that waits at a gate (or at `--gate` alone)
+ * an approval now answers, or at a gate whose decision point now has an
+ * answer that passes it (#3835), unless a wave already applied under that
+ * approval (#3858). It also starts again the run of an apply under an
+ * approval that stopped, once that run is gone. `--dry-run --json` starts
+ * nothing and says, per gate, whether it would resume and why, for a product
+ * that resumes in its own job.
+ */
+export async function runResumeCommand(ctx) {
+    try {
+        await requireLifecycleLedger();
+    }
+    catch (err) {
+        console.error(formatError({ message: `Cannot read the gate ledgers: ${err instanceof Error ? err.message : String(err)}` }));
+        return 1;
+    }
+    const dryRun = ctx.args.dryRun === true;
+    const reports = await resumeWaitingGates({
+        ...(ctx.args.op ? { op: ctx.args.op } : {}),
+        ...(ctx.args.gate ? { gate: ctx.args.gate } : {}),
+        dryRun,
+    });
+    if (ctx.args.json)
+        console.log(JSON.stringify({ dryRun, reports }, null, 2));
+    else {
+        for (const r of reports.filter((r) => r.status !== "not-approved"))
+            printReport(r);
+        const waiting = reports.filter((r) => r.status === "not-approved").length;
+        const done = dryRun ? `${reports.filter((r) => r.resumable).length} would resume` : `${reports.filter((r) => r.status === "resumed").length} resumed`;
+        console.error(formatInfo(`${done}, ${waiting} still waiting for an approval or a passing answer.`));
+    }
+    // A dry run reads; a missing token only leaves a stopped apply unchecked, which its report says.
+    return reports.some((r) => r.status === "failed" || (!dryRun && r.status === "no-token")) ? 1 : 0;
+}

package/dist/cli/handlers/generate.js

@@ -0,0 +1,84 @@
+import { relative, resolve, sep } from "node:path";
+import { findProjectConfigPastFragments, loadChantConfig } from "../../config.js";
+import { checkProjectCodegen, generateProjectCode } from "../../project-codegen.js";
+import { formatError, formatSuccess, formatWarning } from "../format.js";
+/**
+ * `chant generate [path] [--check] [--lexicon <name>]` — project-local code
+ * generation (../../project-codegen.ts). Each configured lexicon that
+ * implements the `projectCodegen` hook renders typed code from the sources
+ * the project declares (`k8s.crds`, `helm.charts`) into
+ * `<codegen.outDir>/<lexicon>/`.
+ *
+ * `--check` writes nothing and exits 1 when any lexicon's committed output no
+ * longer matches its declared sources: the same check `chant build` makes,
+ * for a CI step that wants to say so before building.
+ *
+ * Not `chant dev generate`, which regenerates a lexicon package's own types
+ * from upstream specs and is for lexicon authors.
+ */
+export async function runGenerate(ctx) {
+    const { args } = ctx;
+    const projectRoot = findProjectConfigPastFragments(resolve(args.path)).dir;
+    let config;
+    try {
+        config = (await loadChantConfig(projectRoot)).config;
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    const plugins = ctx.plugins.filter((p) => typeof p.projectCodegen === "function" && (!args.lexicon || p.name === args.lexicon));
+    if (args.lexicon && plugins.length === 0) {
+        console.error(formatError({
+            message: `lexicon "${args.lexicon}" is not configured for this project, or generates no project code`,
+        }));
+        return 1;
+    }
+    const show = (path) => {
+        const rel = relative(projectRoot, path);
+        return rel === "" ? "." : rel.split(sep).join("/");
+    };
+    if (args.check) {
+        let failed = 0;
+        for (const plugin of plugins) {
+            const check = await checkProjectCodegen(plugin, projectRoot, config).catch((err) => ({
+                status: "error",
+                message: err instanceof Error ? err.message : String(err),
+            }));
+            if (check.status === "current")
+                console.error(formatSuccess(`${plugin.name}: generated code is current`));
+            if ("message" in check) {
+                failed++;
+                console.error(formatError({ message: `${plugin.name}: ${check.message}` }));
+            }
+        }
+        return failed > 0 ? 1 : 0;
+    }
+    let written = 0;
+    for (const plugin of plugins) {
+        let result;
+        try {
+            result = await generateProjectCode(plugin, projectRoot, config);
+        }
+        catch (err) {
+            console.error(formatError({ message: `${plugin.name}: ${err instanceof Error ? err.message : String(err)}` }));
+            return 1;
+        }
+        if (!result || result.status === "none")
+            continue;
+        if (result.status === "removed") {
+            console.error(formatWarning({
+                message: `${plugin.name}: no sources declared, removed ${result.files.length} generated file(s) from ${show(result.outDir)}`,
+            }));
+            continue;
+        }
+        written++;
+        for (const line of result.summary)
+            console.log(`  ${plugin.name}: ${line}`);
+        console.error(formatSuccess(`${plugin.name}: wrote ${result.files.length} file(s) to ${show(result.outDir)}`));
+    }
+    if (written === 0) {
+        console.error("Nothing to generate: no configured lexicon declares project sources (for example k8s.crds or helm.charts in chant.config.ts).");
+    }
+    return 0;
+}