@intentius/chant 0.124.28 → 0.124.30

package/dist/cli/handlers/pr.js

@@ -33,7 +33,15 @@
  * 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.
+ * streams them. A component the apply does not start settles too, `blocked`
+ * behind a failed dependency or `already-applied` on a resumed apply.
+ * With or without it, pr-apply prints a line on stderr as each wave starts
+ * and as each component settles, so a job log shows the waves in order.
+ *
+ * `--report-url <s3 or file URL>` (#4007) copies `pr-<stage>.json`,
+ * `change-set.json` and, with `--events-json`, the events to
+ * `<url>/<pr>/<commit>/`, the events again as each wave and component
+ * settles (`../../pr-report-url.ts`).
  *
  * `--member <name>` (#3465) runs a workspace member's loop: the member's
  * generated pipeline passes it from the member's directory. The gate is
@@ -48,10 +56,12 @@ import { resolveCommit, resolveMergeBase } from "../../components/changed-files.
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support.js";
 import { applyPrSet, approvalOf, approversWithoutReview, decidePrGate, planPrSet, prReport, readOnlyLedger, resumePrSet, } from "../../components/pr-run.js";
 import { readFanOutAttempt, writeFanOutAttempt } from "../../components/fan-out-record.js";
+import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs.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 { openPrReportUpload, parseReportUrl, reportKey } from "../../pr-report-url.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";
@@ -213,12 +223,18 @@ function settleOf(status) {
             return "failed";
     }
 }
-/** Write the report, the change set and the note; print the note's path. */
-function writeOutputs(ctx, report, note) {
+/** Write the report, the change set and the note, and hand the first two to `--report-url`'s upload. */
+function writeOutputs(ctx, report, note, upload) {
     const dir = resolve(ctx.args.output ?? PR_REPORT_DIR);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, `pr-${report.stage}.json`), JSON.stringify(report, null, 2) + "\n");
-    writeFileSync(join(dir, "change-set.json"), JSON.stringify(report.changeSet, null, 2) + "\n");
+    const files = [
+        [`pr-${report.stage}.json`, JSON.stringify(report, null, 2) + "\n"],
+        ["change-set.json", JSON.stringify(report.changeSet, null, 2) + "\n"],
+    ];
+    for (const [name, body] of files) {
+        writeFileSync(join(dir, name), body);
+        upload?.file(name, body);
+    }
     writeFileSync(join(dir, "pr-note.md"), note);
 }
 /** Post the note and the stage's status. A forge that refuses is a warning: the stage's outcome stands. */
@@ -262,16 +278,22 @@ function printMembers(report) {
         console.error(`  ${m.member.padEnd(20)} ${m.status.padEnd(12)} create ${c.create} update ${c.update} replace ${c.replace} delete ${c.delete}${m.error ? `  ${m.error}` : ""}`);
     }
 }
-async function finish(ctx, p, report) {
+async function finish(ctx, p, report, upload) {
     const note = noteFor(report, p.forge);
-    writeOutputs(ctx, report, note);
+    writeOutputs(ctx, report, note, upload);
     await publish(p.forge, report, note);
     if (ctx.args.json)
         console.log(JSON.stringify(report, null, 2));
 }
-/** Run a stage, and end its stream as `failed` when the stage did not settle it. */
-async function withStageEvents(stage, run) {
+/** Run a stage, end its stream as `failed` when the stage did not settle it, and finish its upload. */
+async function withStageEvents(stage, ctx, run) {
     const events = {};
+    if (ctx.args.reportUrl !== undefined) {
+        const target = parseReportUrl(ctx.args.reportUrl);
+        if ("error" in target)
+            return fail(target.error);
+        events.target = target;
+    }
     try {
         return await run(events);
     }
@@ -281,13 +303,32 @@ async function withStageEvents(stage, run) {
     }
     finally {
         events.stream?.settle("failed", `${stage} stopped before it finished`);
+        if (events.upload) {
+            await events.upload.close();
+            console.error(formatInfo(`report  : ${events.upload.where}/`));
+        }
     }
 }
-/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] */
+/**
+ * Open the stage's `--report-url` upload under its pull request and commit,
+ * when the flag was given. Its events are the lines `openCliRunEvents` writes.
+ */
+function openUpload(events, stage, pr, p) {
+    if (!events.target)
+        return undefined;
+    events.upload = openPrReportUpload({
+        target: events.target,
+        key: reportKey(pr, p.head, p.member),
+        stage,
+        warn: (message) => console.error(formatWarning({ message })),
+    });
+    return events.upload;
+}
+/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrPlan(ctx) {
     if (refusesEventsWithJson(ctx.args, "the stage's report"))
         return Promise.resolve(1);
-    return withStageEvents("pr-plan", (events) => prPlan(ctx, events));
+    return withStageEvents("pr-plan", ctx, (events) => prPlan(ctx, events));
 }
 async function prPlan(ctx, stage) {
     if (ctx.args.pr === undefined) {
@@ -297,8 +338,9 @@ async function prPlan(ctx, stage) {
     if (typeof p === "number")
         return p;
     const op = prOp(ctx.args.pr, p.member);
+    const upload = openUpload(stage, "plan", ctx.args.pr, p);
     // `--events-json` (#4041): planning, then where the approval stands.
-    const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") });
+    const events = await openCliRunEvents(ctx.args, { kind: "component", name: `pr-plan ${op}`, cwd: resolve(".") }, upload?.line);
     stage.stream = events;
     events?.emit({ type: "run-start", waves: p.plan.waves });
     const set = await planAll(p, events?.emit);
@@ -328,7 +370,7 @@ async function prPlan(ctx, stage) {
         approval,
         status,
     });
-    await finish(ctx, p, report);
+    await finish(ctx, p, report, upload);
     // 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}`));
@@ -339,11 +381,11 @@ async function prPlan(ctx, stage) {
     }
     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] [--events-json] */
+/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
 export function runComponentsPrApply(ctx) {
     if (refusesEventsWithJson(ctx.args, "the stage's report"))
         return Promise.resolve(1);
-    return withStageEvents("pr-apply", (events) => prApply(ctx, events));
+    return withStageEvents("pr-apply", ctx, (events) => prApply(ctx, events));
 }
 async function prApply(ctx, stage) {
     const { args } = ctx;
@@ -365,7 +407,8 @@ async function prApply(ctx, stage) {
     // 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(".") });
+    const upload = openUpload(stage, "apply", pr, p);
+    const events = await openCliRunEvents(args, { kind: "component", name: `pr-apply ${op}`, runId: release.runId, cwd: resolve(".") }, upload?.line);
     stage.stream = events;
     events?.emit({ type: "run-start", waves: p.plan.waves });
     // `--resume` (#3464): an earlier attempt at this change on this commit
@@ -381,14 +424,26 @@ async function prApply(ctx, stage) {
             return fail(`--resume: could not read "${args.resume}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume, op) : undefined;
-    if (resumed)
+    // What each component would apply now (#4081): progress carries only where it is unchanged.
+    const inputsNow = resumePath ? componentInputDigests(p.components, { projectRoot: resolve("."), env: p.env }) : {};
+    const resumed = pr !== null && p.plan.order.length > 0 && attempt ? await tryResume(p, attempt, args.resume, op, inputsNow) : undefined;
+    // The components an earlier attempt applied settle first (#4007), each in
+    // the wave the derivation gave it, which is the run-start's.
+    const log = applyLog();
+    if (resumed) {
+        const waveOf = new Map(p.plan.waves.flatMap((wave, i) => wave.map((name) => [name, i + 1])));
+        for (const component of p.plan.order.filter((name) => resumed.completed.includes(name))) {
+            const body = { type: "component-settle", wave: waveOf.get(component), component, status: "already-applied" };
+            events?.emit(body);
+            log(body);
+        }
         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, 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);
+        await finish(ctx, p, report, upload);
         console.error((code === 0 ? formatInfo : (m) => formatWarning({ message: m }))(`pr-apply: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
         if (report.message)
             console.error(report.message);
@@ -469,6 +524,7 @@ async function prApply(ctx, stage) {
     // one settles, so a run killed partway still knows what applied.
     const prior = resumed ? { completed: resumed.completed, outputs: resumed.outputs } : { completed: [], outputs: {} };
     const completedSoFar = new Set(prior.completed);
+    const inputsSoFar = Object.fromEntries(prior.completed.filter((name) => inputsNow[name] !== undefined).map((name) => [name, inputsNow[name]]));
     const failedSoFar = [];
     const outputsSoFar = { ...prior.outputs };
     const record = {
@@ -489,6 +545,7 @@ async function prApply(ctx, stage) {
             completed: [...completedSoFar].sort(),
             failed: [...failedSoFar].sort(),
             outputs: outputsSoFar,
+            inputs: Object.fromEntries(Object.entries(inputsSoFar).sort(([a], [b]) => a.localeCompare(b))),
             prApply: record,
         });
     };
@@ -500,13 +557,19 @@ async function prApply(ctx, stage) {
         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 } : {}),
+        // The apply is this run's waves, so the fan-out's own run framing is
+        // dropped. The log's lines go to stderr with or without --events-json.
+        onRunEvent: (body) => {
+            events?.nested(body);
+            log(body);
+        },
         ...(resumePath
             ? {
                 onComponentSettled: (settled, outputs) => {
                     if (settled.status === "ok") {
                         completedSoFar.add(settled.component);
+                        if (inputsNow[settled.component] !== undefined)
+                            inputsSoFar[settled.component] = inputsNow[settled.component];
                         if (outputs)
                             outputsSoFar[settled.component] = outputs;
                     }
@@ -533,6 +596,38 @@ async function prApply(ctx, stage) {
         console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
     return code;
 }
+/** What a component's settle says in the job log. */
+function settleWords(body) {
+    switch (body.status) {
+        case "ok":
+            return "applied";
+        case "failed":
+            return "failed";
+        case "gated":
+            return "stopped at its own gate";
+        case "waiting":
+            return "waiting on a decision";
+        case "blocked":
+            return `blocked by ${body.blockedBy ?? "a dependency"}, not run`;
+        case "already-applied":
+            return "already applied in an earlier attempt";
+    }
+}
+/**
+ * pr-apply's job log (#4007): a line on stderr as each wave starts and as
+ * each component settles, so the log shows the waves in order while they run.
+ */
+function applyLog() {
+    let waves = 0;
+    return (body) => {
+        if (body.type === "run-start")
+            waves = body.waves?.length ?? 0;
+        else if (body.type === "wave-start")
+            console.error(formatInfo(`wave ${body.wave}${waves ? `/${waves}` : ""}: ${body.components.join(", ")}`));
+        else if (body.type === "component-settle")
+            console.error(formatInfo(`  ${body.component}: ${settleWords(body)}`));
+    };
+}
 /** 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)
@@ -584,8 +679,13 @@ async function storeChangeSetForGate(ctx, p, doc) {
  * derivation; when its approval still stands; and when every member left is
  * covered by the approved set. Otherwise it says why on stderr and the apply
  * runs as it would with no record.
+ *
+ * Of the components it applied, only those whose input digest is the same
+ * now carry (#4081), as in `components fan-out --resume`. One that changed
+ * runs again, under the same approval when the approved set covers its new
+ * plan. A record without input digests carries nothing.
  */
-async function tryResume(p, attempt, file, op) {
+async function tryResume(p, attempt, file, op, inputsNow) {
     const skip = (why) => {
         console.error(formatWarning({ message: `--resume: "${file}" does not carry: ${why}`, hint: "Every member is planned again, and the plan needs an approval of its own." }));
         return undefined;
@@ -601,6 +701,14 @@ async function tryResume(p, attempt, file, op) {
         return skip("the change selects other components than it did");
     if (attempt.completed.length === 0)
         return undefined;
+    const split = progressThatCarries(attempt, inputsNow);
+    if (split.unrecorded)
+        return skip("it does not record what each component applied, since it was written before chant recorded component inputs");
+    for (const name of split.changed)
+        console.error(formatInfo(`${name}: changed since the earlier attempt, so it runs again`));
+    if (split.carried.length === 0)
+        return undefined;
+    const completed = split.carried;
     let check;
     try {
         check = await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: record.digest });
@@ -610,7 +718,7 @@ async function tryResume(p, attempt, file, op) {
     }
     if (!check.satisfied)
         return skip(`no approval stands for the plan it applied (${record.digest}) any more`);
-    const outputs = Object.fromEntries(Object.entries(attempt.outputs).filter(([name]) => attempt.completed.includes(name)));
+    const outputs = Object.fromEntries(Object.entries(attempt.outputs).filter(([name]) => completed.includes(name)));
     const resumed = await resumePrSet({
         components: p.components,
         plan: p.plan,
@@ -618,10 +726,10 @@ async function tryResume(p, attempt, file, op) {
         env: p.env,
         seededOutputs: p.seededOutputs,
         record,
-        completed: attempt.completed,
+        completed,
     });
     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, check, approval: approvalOf(check), completed: attempt.completed, outputs };
+    console.error(formatInfo(`resume  : ${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, check, approval: approvalOf(check), completed, outputs };
 }

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

@@ -12,6 +12,13 @@
  * failed or stopped at a gate, so the ledger never misses a deploy that
  * happened. Unlike an auto-recorded release, the record is what these
  * commands are for, so a failed write is an error rather than a warning.
+ * A run that applied partly, or failed, also appends a deploy outcome
+ * (#4035, ../../lifecycle/deploy-outcome.ts) naming what it did to each
+ * component, so `workspace status` reads the environment as mixed.
+ *
+ * `rollback --release` (#4035) is a promote of an earlier release into the
+ * environment: every component of the release at the digest the environment
+ * ran from it, through the release gate `promote --release` binds (#4045).
  */
 import type { CommandContext } from "../registry.js";
 export declare function runComponentsPromote(ctx: CommandContext): Promise<number>;

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;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"}
+{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA+CH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAukBlD,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2E/E;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAsChF;AAsCD,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BhF"}