@intentius/chant 0.124.27 → 0.124.28

package/dist/cli/handlers/pr.js

@@ -29,6 +29,12 @@
  *
  * Every run writes `pr-plan.json` or `pr-apply.json` (`pr-report.schema.json`),
  * `change-set.json` and `pr-note.md` under `--output` (default `.chant/pr`). *
+ * `--events-json` (#4041, #4007) streams the stage's run events to stdout,
+ * one `run-event.schema.json` line each: the planning as a `plan` phase with
+ * a step per component, the gate's decision as a `gate` phase, and on
+ * pr-apply the apply's waves and components as `chant run --components`
+ * streams them.
+ *
  * `--member <name>` (#3465) runs a workspace member's loop: the member's
  * generated pipeline passes it from the member's directory. The gate is
  * recorded under `pr-<n>-<member>`, and the note and the statuses carry the
@@ -44,6 +50,8 @@ import { applyPrSet, approvalOf, approversWithoutReview, decidePrGate, planPrSet
 import { readFanOutAttempt, writeFanOutAttempt } from "../../components/fan-out-record.js";
 import { samePlanDigest } from "../../lifecycle/plan-digest.js";
 import { gitGateLedgerPort } from "../../op/gate.js";
+import { emitGateStep, gateEventsOf, GATE_PHASE } from "../../run-event-stream.js";
+import { openCliRunEvents, refusesEventsWithJson } from "../run-events.js";
 import { describePlanChanged, PR_APPLY_GATE, prApproveCommand, prNoteMarker, prOp, prStatusDescription, prStatusContext, prStatusState, renderPrNote, } from "../../pr-loop.js";
 import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf } from "../../pr-forge.js";
 import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "../../plan-summary.js";
@@ -51,7 +59,7 @@ import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
 import { formatError, formatInfo, formatSuccess, formatWarning } from "../format.js";
 import { findWorkspaceRoot } from "../../project-root.js";
 import { resolveChangedUnits } from "./fan-out.js";
-import { GATED_EXIT_CODE, recordAutoReleasesForRun } from "./run.js";
+import { GATED_EXIT_CODE, autoReleaseRun, recordAutoReleasesForRun } from "./run.js";
 /** Where the reports land unless `--output` says. */
 export const PR_REPORT_DIR = ".chant/pr";
 const fail = (message, hint) => {
@@ -179,8 +187,31 @@ async function checkMember(projectPath, names) {
     return name;
 }
 /** Plan every member the derivation selects. */
-function planAll(p) {
-    return planPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: p.env, seededOutputs: p.seededOutputs });
+function planAll(p, onRunEvent) {
+    return planPrSet({
+        components: p.components,
+        plan: p.plan,
+        registry: p.registry,
+        env: p.env,
+        seededOutputs: p.seededOutputs,
+        ...(onRunEvent ? { onRunEvent } : {}),
+    });
+}
+/**
+ * How a stage's report settles its run's events (#4041): a refusal waits on
+ * a person, as a gate does, and exits the same way.
+ */
+function settleOf(status) {
+    switch (status) {
+        case "nothing":
+        case "planned":
+        case "applied":
+            return "ok";
+        case "refused":
+            return "gated";
+        default:
+            return "failed";
+    }
 }
 /** Write the report, the change set and the note; print the note's path. */
 function writeOutputs(ctx, report, note) {
@@ -238,20 +269,44 @@ async function finish(ctx, p, report) {
     if (ctx.args.json)
         console.log(JSON.stringify(report, null, 2));
 }
-/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] */
-export async function runComponentsPrPlan(ctx) {
+/** Run a stage, and end its stream as `failed` when the stage did not settle it. */
+async function withStageEvents(stage, run) {
+    const events = {};
+    try {
+        return await run(events);
+    }
+    catch (err) {
+        events.stream?.settle("failed", err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    finally {
+        events.stream?.settle("failed", `${stage} stopped before it finished`);
+    }
+}
+/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] */
+export function runComponentsPrPlan(ctx) {
+    if (refusesEventsWithJson(ctx.args, "the stage's report"))
+        return Promise.resolve(1);
+    return withStageEvents("pr-plan", (events) => prPlan(ctx, events));
+}
+async function prPlan(ctx, stage) {
     if (ctx.args.pr === undefined) {
         return fail("pr-plan needs the pull or merge request: --pr <n>", "Its approval is recorded under op pr-<n>, so one pull request's approval never answers another's.");
     }
     const p = await prepare(ctx, "plan");
     if (typeof p === "number")
         return p;
-    const set = await planAll(p);
     const op = prOp(ctx.args.pr, p.member);
+    // `--events-json` (#4041): planning, then where the approval stands.
+    const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") });
+    stage.stream = events;
+    events?.emit({ type: "run-start", waves: p.plan.waves });
+    const set = await planAll(p, events?.emit);
     let approval = { status: "pending" };
     if (p.plan.order.length > 0) {
         try {
-            approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: set.doc.digest }));
+            const check = await emitGateStep(events?.emit, { op, gate: p.gate }, () => decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: set.doc.digest }));
+            approval = approvalOf(check);
         }
         catch (err) {
             console.error(formatWarning({ message: `could not read the gate ledger, so the approval reads as pending: ${err instanceof Error ? err.message : String(err)}` }));
@@ -274,6 +329,8 @@ export async function runComponentsPrPlan(ctx) {
         status,
     });
     await finish(ctx, p, report);
+    // The plan stage settles on its planning: an approval still to come is what it reports, not a stop.
+    events?.settle(settleOf(status), status === "plan-failed" ? "a member failed to plan" : undefined);
     console.error(formatInfo(`pr-plan: ${report.members.length} member(s), ${status}`));
     printMembers(report);
     if (status === "planned") {
@@ -282,8 +339,13 @@ export async function runComponentsPrPlan(ctx) {
     }
     return status === "plan-failed" ? 1 : 0;
 }
-/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] */
-export async function runComponentsPrApply(ctx) {
+/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] */
+export function runComponentsPrApply(ctx) {
+    if (refusesEventsWithJson(ctx.args, "the stage's report"))
+        return Promise.resolve(1);
+    return withStageEvents("pr-apply", (events) => prApply(ctx, events));
+}
+async function prApply(ctx, stage) {
     const { args } = ctx;
     if (args.requireReview && !args.forge)
         return fail("--require-review reads the pull request's reviews, so it needs --forge <kind>");
@@ -300,6 +362,12 @@ export async function runComponentsPrApply(ctx) {
         }
     }
     const op = pr === null ? "pr-unknown" : prOp(pr, p.member);
+    // The run id the release records carry, chosen before the run so that
+    // `--events-json` (#4041, #4007) names the run by it too.
+    const release = autoReleaseRun(`${op}-${Date.now()}`);
+    const events = await openCliRunEvents(args, { kind: "component", name: `pr-apply ${op}`, runId: release.runId, cwd: resolve(".") });
+    stage.stream = events;
+    events?.emit({ type: "run-start", waves: p.plan.waves });
     // `--resume` (#3464): an earlier attempt at this change on this commit
     // applied part of an approved set. When the members left are covered by
     // it and its approval still stands, finish it under that approval.
@@ -314,9 +382,12 @@ export async function runComponentsPrApply(ctx) {
         }
     }
     const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume, op) : undefined;
-    const set = resumed?.set ?? (await planAll(p));
+    if (resumed)
+        emitResumedGate(events, op, p.gate, resumed.check);
+    const set = resumed?.set ?? (await planAll(p, events?.emit));
     const base = { stage: "apply", pr, env: p.env, ...(p.member ? { member: p.member } : {}), base: p.base, head: p.head, op, gate: p.gate, plan: p.plan, signal: p.signal, set };
-    const stop = async (report, code) => {
+    const stop = async (report, code, settle) => {
+        events?.settle(settle ?? settleOf(report.status), report.status === "plan-failed" || report.status === "failed" ? report.message ?? `pr-apply ${report.status}` : undefined);
         await finish(ctx, p, report);
         console.error((code === 0 ? formatInfo : (m) => formatWarning({ message: m }))(`pr-apply: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
         if (report.message)
@@ -344,16 +415,25 @@ export async function runComponentsPrApply(ctx) {
             message: "A member failed to plan, so there is no plan to compare with the approved one. Nothing was applied.",
         }), 1);
     }
+    // #4022: keep the change set the gate binds on chant/lifecycle under its
+    // digest before deciding the gate, so the plan an approval bound, or the
+    // one a pending fact waits on, can be read once this job is gone.
+    await storeChangeSetForGate(ctx, p, set.doc);
     let approval;
     if (resumed) {
         approval = resumed.approval;
     }
     else {
-        const check = await decidePrGate(gitGateLedgerPort(), {
+        const check = await emitGateStep(events?.emit, { op, gate: p.gate }, () => decidePrGate(gitGateLedgerPort(), {
             op,
             gate: p.gate,
             digest: set.doc.digest,
             description: `pull request #${pr}: ${p.plan.order.join(", ")}`,
+        }), (unapproved) => {
+            const a = approvalOf(unapproved);
+            return a.status === "changed"
+                ? describePlanChanged({ op, gate: p.gate, digest: set.doc.digest, approval: a })
+                : `No approval stands for this plan. Approve it: ${prApproveCommand({ op, gate: p.gate, digest: set.doc.digest })}`;
         });
         approval = approvalOf(check);
         if (!check.satisfied) {
@@ -378,15 +458,11 @@ export async function runComponentsPrApply(ctx) {
         }
         const strangers = approversWithoutReview(approval.approvedBy ?? [], reviewers);
         if (strangers.length > 0) {
-            return stop(prReport({
-                ...base,
-                approval,
-                status: "refused",
-                refusal: "not-a-reviewer",
-                message: `The plan is approved by ${strangers.join(", ")}, who ${strangers.length === 1 ? "has" : "have"} no approving review on #${pr}` +
-                    ` (approving reviews: ${reviewers.join(", ") || "none"}). Nothing was applied. ` +
-                    `An approval counts when it names the reviewer the way the forge does: ${p.forge.principalOf("<login>")}.`,
-            }), GATED_EXIT_CODE);
+            const message = `The plan is approved by ${strangers.join(", ")}, who ${strangers.length === 1 ? "has" : "have"} no approving review on #${pr}` +
+                ` (approving reviews: ${reviewers.join(", ") || "none"}). Nothing was applied. ` +
+                `An approval counts when it names the reviewer the way the forge does: ${p.forge.principalOf("<login>")}.`;
+            emitReviewStop(events, message);
+            return stop(prReport({ ...base, approval, status: "refused", refusal: "not-a-reviewer", message }), GATED_EXIT_CODE);
         }
     }
     // The record is written before the first component runs and again as each
@@ -424,6 +500,8 @@ export async function runComponentsPrApply(ctx) {
         env: p.env,
         set,
         ...(resumed ? { resumed: prior } : {}),
+        // The apply is this run's waves, so the fan-out's own run framing is dropped.
+        ...(events ? { onRunEvent: events.nested } : {}),
         ...(resumePath
             ? {
                 onComponentSettled: (settled, outputs) => {
@@ -441,7 +519,7 @@ export async function runComponentsPrApply(ctx) {
             : {}),
     });
     recordAttempt();
-    await recordAutoReleasesForRun(applied.run.results, p.env, `${op}-${Date.now()}`, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord));
+    await recordAutoReleasesForRun(applied.run.results, p.env, release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), release.runOrigin);
     const report = prReport({
         ...base,
         approval,
@@ -449,11 +527,57 @@ export async function runComponentsPrApply(ctx) {
         members: applied.members,
         ...(resumed ? { resumed: resumed.completed } : {}),
     });
-    const code = await stop(report, applied.status === "applied" ? 0 : 1);
+    // A component that stopped at a gate of its own leaves the apply waiting on a person.
+    const code = await stop(report, applied.status === "applied" ? 0 : 1, applied.run.status === "gated" ? "gated" : undefined);
     if (applied.status === "applied")
         console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
     return code;
 }
+/** A resumed apply's gate (#3464), decided against the approved digest, as the run's `gate` phase. */
+function emitResumedGate(events, op, gate, check) {
+    if (!events)
+        return;
+    const where = { component: null, phase: GATE_PHASE, step: `gate:${gate}` };
+    events.emit({ type: "phase-start", component: null, phase: GATE_PHASE });
+    events.emit({ type: "step-start", ...where });
+    for (const body of gateEventsOf(check, { ...where, op, gate }, { durationMs: null }))
+        events.emit(body);
+    events.emit({ type: "phase-settle", component: null, phase: GATE_PHASE, status: check.satisfied ? "ok" : "gated" });
+}
+/** An approval by someone with no approving review (#3183) stops the apply: a `review` phase that settles `gated`. */
+function emitReviewStop(events, message) {
+    if (!events)
+        return;
+    events.emit({ type: "phase-start", component: null, phase: "review" });
+    events.emit({ type: "step-start", component: null, phase: "review", step: "review" });
+    events.emit({ type: "step-settle", component: null, phase: "review", step: "review", status: "gated", durationMs: null, message });
+    events.emit({ type: "phase-settle", component: null, phase: "review", status: "gated" });
+}
+/**
+ * Store `doc` under its digest with its entries mapped onto the member's
+ * graph (`storeGateChangeSet`), and push. A failure is a warning: the gate
+ * decides the same either way.
+ */
+async function storeChangeSetForGate(ctx, p, doc) {
+    const { storeGateChangeSet, gateGraphReader } = await import("../../lifecycle/gate-change-set.js");
+    const { pushLifecycleReport } = await import("../../lifecycle/git.js");
+    const graphArgs = [
+        ...(ctx.args.param ?? []).flatMap((kv) => ["--param", kv]),
+        ...(ctx.args.paramsFile ? ["--params-file", ctx.args.paramsFile] : []),
+    ];
+    try {
+        const stored = await storeGateChangeSet({ doc, cwd: resolve("."), at: p.head, readGraph: gateGraphReader(graphArgs) });
+        if (stored.warning)
+            console.error(formatWarning({ message: stored.warning }));
+        // The push's own outcome is said by the gate's pending fact, or by the
+        // release records the apply writes, which push the same branch.
+        if (stored.written)
+            await pushLifecycleReport();
+    }
+    catch (err) {
+        console.error(formatWarning({ message: `could not store the change set ${doc.digest}: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+}
 /**
  * Whether `attempt` finishes here (#3464). It carries only when it was made
  * by an apply of this pull request's gate, on this commit, for this
@@ -499,5 +623,5 @@ async function tryResume(p, attempt, file, op) {
     if (!resumed.ok)
         return skip(`what is left is not what was approved. ${resumed.reasons.join("; ")}`);
     console.error(formatInfo(`resume  : ${attempt.completed.join(", ")} applied in an earlier attempt; applying ${resumed.plan.order.join(", ") || "nothing more"} under the approval of ${record.digest}`));
-    return { plan: resumed.plan, set: resumed.set, approval: approvalOf(check), completed: attempt.completed, outputs };
+    return { plan: resumed.plan, set: resumed.set, check, approval: approvalOf(check), completed: attempt.completed, outputs };
 }

package/dist/cli/handlers/promote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAuCH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAmPlD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C/E;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BhF;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BhF"}
+{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA8CH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgclD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6F/E;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BhF;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BhF"}