@intentius/chant 0.124.30 → 0.124.32

package/dist/pr-loop.d.ts

@@ -28,6 +28,16 @@
  * and decides the gate against the new digest. The same plan applies; a moved
  * plan stops with both digests named and nothing applied.
  *
+ * ## A gate per wave on merge
+ *
+ * With `--wave-gate <gate>` (#4003) the apply runs a wave at a time, and
+ * plans each wave after the one before it applied. Wave 1 applies under the
+ * pull request's approval. A later wave whose new plan the approved change
+ * set covers (`planCoveredBy`) applies under that approval too; one whose
+ * plan moved waits at `<gate>-wave-<k>`, under the same op, for an approval
+ * of its new plan. The report's `waves` says which wave applied under which
+ * approval.
+ *
  * ## Inside a workspace member
  *
  * Each workspace member that generates the pipeline (#3465) runs its own
@@ -43,6 +53,14 @@ export declare const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/w
 export declare const PR_REPORT_CONTRACT = 1;
 /** The first chant whose report can carry `deployedOutputs` (#4104). */
 export declare const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
+/** The first chant whose report can carry `waveGate` and `waves` (#4003). */
+export declare const PR_REPORT_WAVES_FLOOR = "0.124.32";
+/**
+ * The first chant whose report can carry `plannedOutputs`, `rounds`, a
+ * member's `unknownInputs`, `buildInputs`, `round` and `held`, and the `waiting` statuses
+ * (#3999).
+ */
+export declare const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export declare const PR_APPLY_GATE = "pr-apply";
 /**
@@ -50,6 +68,13 @@ export declare const PR_APPLY_GATE = "pr-apply";
  * `pr-<number>-<member>` for a workspace member's pipeline (#3465).
  */
 export declare function prOp(pr: number, member?: string): string;
+/**
+ * The gate a round of an apply waits on (#3999): the pull request's own
+ * gate for the first, and `<gate>-round-<n>` for each one planned after an
+ * upstream applied. A workspace's `identity.gates` entry for `gate` covers
+ * every round.
+ */
+export declare function prRoundGate(gate: string, round: number): string;
 /** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
 export declare const PR_GATE_OP: RegExp;
 /** The hidden line that marks the pull request's note, one per environment and, in a workspace, per member. */
@@ -79,7 +104,13 @@ export type PrMemberStatus =
 /** The apply failed. */
  | "failed"
 /** Not applied because a member it depends on failed. */
- | "blocked";
+ | "blocked"
+/**
+ * Apply stage (#3999): held back because its plan read an upstream output
+ * that applied as another value, or was known only after apply. It waits
+ * on an approval of the plan the apply made for it afterwards (`rounds`).
+ */
+ | "waiting";
 export interface PrMember {
     /** The member's name in the change set: a root, for a terraform-family step. */
     member: string;
@@ -93,9 +124,47 @@ export interface PrMember {
     /**
      * Components this one depends on whose outputs changed when they applied
      * (apply stage). Its applied plan read the values from before, so the next
-     * run plans it again.
+     * run plans it again. Not written since #3999, which holds such a member
+     * back and plans it again in the same apply (`held`, `round`).
      */
     inputsMoved?: string[];
+    /**
+     * The upstream outputs its plan read that the change's plans could not
+     * say (#3999), as `<component>.<output>`, sorted: known only after that
+     * upstream applies. The approval does not cover what this member does
+     * with them; the apply plans it again once they are known.
+     */
+    unknownInputs?: string[];
+    /**
+     * The published artifact identities its plan read from a build in the
+     * same change (#3999), as `<component>.publish.<field>`, sorted: an image
+     * digest, say. Known only after the build runs, but never approved again:
+     * the build's provenance and attestation bind the digest, so the member
+     * applies without a later round.
+     */
+    buildInputs?: string[];
+    /** Apply stage (#3999): the round whose plan it applied or waits on, when not the first. */
+    round?: number;
+    /** Apply stage (#3999): why the first round's plan did not apply. */
+    held?: string;
+}
+/** A round of plans an apply made after an upstream applied (#3999), the report's `rounds`. */
+export interface PrRound {
+    /** 2 for the first plan made after an upstream applied, and on. */
+    round: number;
+    /** The gate it waits on: {@link prRoundGate}. */
+    gate: string;
+    /** The change-set digest of what the round planned. What its gate binds. */
+    digest: string;
+    /** The components planned again, in apply order. */
+    components: string[];
+    approval: PrApproval;
+    /** `waiting`: no approval stands for `digest`. `plan-failed`: a member failed to plan, so the round did not apply. */
+    status: "applied" | "failed" | "waiting" | "plan-failed";
+    /** With `waiting`: why an approval that stands does not count (`--require-review`). */
+    message?: string;
+    /** The change-set document the round planned. */
+    changeSet: ChangeSetDocument;
 }
 /** Where the approval stands for the planned digest. */
 export interface PrApproval {
@@ -122,8 +191,19 @@ export type PrStatus =
  | "applied"
 /** Apply stage: a member failed to apply. Its dependents did not run. */
  | "failed"
+/**
+ * Apply stage with `--wave-gate` and `--wave` (#4003): this wave applied,
+ * and a later wave of the change is still to run.
+ */
+ | "wave-applied"
 /** Apply stage: nothing applied, see `refusal`. */
- | "refused";
+ | "refused"
+/**
+ * Apply stage (#3999): the approved plans applied, except members held
+ * back after an upstream applied. They wait on the approval of the plan
+ * the last of `rounds` made.
+ */
+ | "waiting";
 /** Why an apply refused. */
 export type PrRefusal = 
 /** No approval stands for any plan of this pull request. */
@@ -132,8 +212,44 @@ export type PrRefusal =
  | "plan-changed"
 /** The approval names someone who has not approved the pull request on the forge. */
  | "not-a-reviewer"
+/** The approval names the pull request's author, or an author or committer of one of its commits (#4000). */
+ | "author-approved"
 /** No pull request merged this commit, so there is no approval to read. */
- | "no-pull-request";
+ | "no-pull-request"
+/** `--wave-gate` (#4003): the wave's new plan is not one the pull request approved, and no approval stands for it. */
+ | "wave-not-approved"
+/** `--wave-gate`: an approval of the wave's gate stands for another digest, so its plan moved since. */
+ | "wave-plan-changed"
+/** `--wave-gate` with `--wave <k>`: an earlier wave has work left, or no record says it applied. */
+ | "earlier-wave";
+/**
+ * One wave of an apply with `--wave-gate` (#4003): what it planned, where it
+ * got to, and which approval it applied or waits under.
+ */
+export interface PrWave {
+    /** 1-based, from the derivation (`selection.waves`). */
+    wave: number;
+    /** The components planned in it on the run that reached it. */
+    components: string[];
+    /** `applied`; `failed` or `plan-failed`; or `waiting` at its gate. */
+    status: "applied" | "failed" | "plan-failed" | "waiting";
+    /**
+     * `pull-request`: the approved change set covers the wave's plan, so it
+     * applies under the pull request's approval. `wave`: its plan moved, so it
+     * needs an approval of its own gate.
+     */
+    approval: "pull-request" | "wave";
+    /** The gate it applied or waits under: the pull request's, or `<wave gate>-wave-<k>`. */
+    gate: string;
+    /** The digest that gate binds: the pull request's change set, or the wave's new plan. */
+    digest: string;
+    /** Who approved that digest. */
+    approvedBy?: string[];
+    /** Waiting: an approval of the wave's gate stands for this other digest. */
+    approved?: string;
+    /** Why the approved change set does not cover the wave's plan, one line per member. */
+    moved?: string[];
+}
 /**
  * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
  * The terragucci plan report (#3349) reads it; fields are only ever added.
@@ -175,7 +291,28 @@ export interface PrReport {
      * {@link PR_REPORT_DEPLOYED_OUTPUTS_FLOOR}.
      */
     deployedOutputs?: Record<string, string[]>;
+    /**
+     * Per dependency in the change that a member was planned against (#3999),
+     * the names of the outputs its plan knows, sorted. An output it reads that
+     * is not here is known only after apply (a member's `unknownInputs`).
+     * Absent when no member read one. Added within contract 1 by chant
+     * {@link PR_REPORT_PLANNED_OUTPUTS_FLOOR}.
+     */
+    plannedOutputs?: Record<string, string[]>;
+    /**
+     * Apply stage (#3999): the rounds planned after an upstream applied, in
+     * order, each with its own gate and digest. Absent when nothing was held.
+     */
+    rounds?: PrRound[];
     approval: PrApproval;
+    /**
+     * The wave gate's base name with `--wave-gate` (#4003): wave k waits on
+     * `<waveGate>-wave-<k>` when its plan moved. Added within contract 1 by
+     * chant {@link PR_REPORT_WAVES_FLOOR}.
+     */
+    waveGate?: string;
+    /** With `waveGate`: each wave reached so far, in order. */
+    waves?: PrWave[];
     /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
     selection: {
         changed: string[];

package/dist/pr-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-loop.d.ts","sourceRoot":"","sources":["../src/pr-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pr-loop.d.ts","sourceRoot":"","sources":["../src/pr-loop.ts"],"names":[],"mappings":"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"}

package/dist/pr-loop.js

@@ -28,6 +28,16 @@
  * and decides the gate against the new digest. The same plan applies; a moved
  * plan stops with both digests named and nothing applied.
  *
+ * ## A gate per wave on merge
+ *
+ * With `--wave-gate <gate>` (#4003) the apply runs a wave at a time, and
+ * plans each wave after the one before it applied. Wave 1 applies under the
+ * pull request's approval. A later wave whose new plan the approved change
+ * set covers (`planCoveredBy`) applies under that approval too; one whose
+ * plan moved waits at `<gate>-wave-<k>`, under the same op, for an approval
+ * of its new plan. The report's `waves` says which wave applied under which
+ * approval.
+ *
  * ## Inside a workspace member
  *
  * Each workspace member that generates the pipeline (#3465) runs its own
@@ -43,6 +53,14 @@ export const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace
 export const PR_REPORT_CONTRACT = 1;
 /** The first chant whose report can carry `deployedOutputs` (#4104). */
 export const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
+/** The first chant whose report can carry `waveGate` and `waves` (#4003). */
+export const PR_REPORT_WAVES_FLOOR = "0.124.32";
+/**
+ * The first chant whose report can carry `plannedOutputs`, `rounds`, a
+ * member's `unknownInputs`, `buildInputs`, `round` and `held`, and the `waiting` statuses
+ * (#3999).
+ */
+export const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 /**
@@ -52,6 +70,15 @@ export const PR_APPLY_GATE = "pr-apply";
 export function prOp(pr, member) {
     return member ? `pr-${pr}-${member}` : `pr-${pr}`;
 }
+/**
+ * The gate a round of an apply waits on (#3999): the pull request's own
+ * gate for the first, and `<gate>-round-<n>` for each one planned after an
+ * upstream applied. A workspace's `identity.gates` entry for `gate` covers
+ * every round.
+ */
+export function prRoundGate(gate, round) {
+    return round <= 1 ? gate : `${gate}-round-${round}`;
+}
 /** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
 export const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
 /** The hidden line that marks the pull request's note, one per environment and, in a workspace, per member. */
@@ -101,6 +128,7 @@ const STATUS_WORDS = {
     applied: "applied",
     failed: "apply failed",
     blocked: "blocked",
+    waiting: "waiting on its new plan",
 };
 function headline(report) {
     const n = report.members.length;
@@ -116,10 +144,47 @@ function headline(report) {
             return `Applied ${members}.`;
         case "failed":
             return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
-        case "refused":
-            return "The apply refused.";
+        case "wave-applied": {
+            const applied = (report.waves ?? []).filter((w) => w.status === "applied").map((w) => w.wave);
+            const total = report.selection.waves.length;
+            return `Applied wave ${applied.at(-1) ?? "?"} of ${total}. The next wave runs in its own job.`;
+        }
+        case "refused": {
+            const waiting = report.waves?.find((w) => w.status === "waiting");
+            return waiting ? `Wave ${waiting.wave} waits at its gate ${code(waiting.gate)}; nothing in it applied.` : "The apply refused.";
+        }
+        case "waiting":
+            return `Applied ${report.members.filter((m) => m.status === "applied").length} of ${members}; ${report.members.filter((m) => m.status === "waiting").length} wait on an approval of the plan made after their upstream applied.`;
     }
 }
+/** Who a wave applied or waits under, as a table cell. */
+function waveApproval(w) {
+    const whose = w.approval === "pull-request" ? "the pull request's" : "its own";
+    const by = w.approvedBy?.length ? ` by ${w.approvedBy.map(code).join(", ")}` : w.status === "waiting" ? ", not approved yet" : "";
+    return `${whose} ${code(w.gate)}${by}`;
+}
+/**
+ * The waves of an apply with `--wave-gate` (#4003): a row per wave reached,
+ * saying which approval it applied under, then for a wave that waits the
+ * reason its plan moved and the approve command for its new plan.
+ */
+function waveLines(report, approver) {
+    const waves = report.waves ?? [];
+    if (waves.length === 0)
+        return [];
+    const out = ["", "| Wave | Components | Status | Approval |", "|---:|---|---|---|"];
+    for (const w of waves)
+        out.push(`| ${w.wave} | ${w.components.map(code).join(", ")} | ${w.status} | ${waveApproval(w)} |`);
+    for (const w of waves.filter((x) => x.status === "waiting")) {
+        out.push("", `Wave ${w.wave} was planned after the waves before it applied, and the approved plan does not cover it:`, "");
+        for (const why of w.moved ?? [])
+            out.push(`- ${why}`);
+        if (w.approved)
+            out.push("", `An approval of ${code(w.gate)} stands for ${code(w.approved)}, not for the plan now.`);
+        out.push("", `Read wave ${w.wave}'s plan, ${code(w.digest)}, and approve it with:`, "", "```", prApproveCommand({ op: report.op, gate: w.gate, digest: w.digest }, approver), "```", "", "Then run the wave's apply job again.");
+    }
+    return out;
+}
 function approvalLines(report, approver) {
     const a = report.approval;
     if (report.status === "nothing")
@@ -170,6 +235,7 @@ export function renderPrNote(report, options = {}) {
             out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
         }
     }
+    out.push(...waveLines(report, options.approver ?? "<you>"));
     if (report.selection.unclaimed.length > 0) {
         out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
     }
@@ -178,9 +244,39 @@ export function renderPrNote(report, options = {}) {
         const each = deployed.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none yet"})`);
         out.push("", `Planned against outputs read from the deployed estate: ${each.join("; ")}.`);
     }
+    const planned = Object.entries(report.plannedOutputs ?? {});
+    if (planned.length > 0) {
+        const each = planned.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none known"})`);
+        out.push("", `Planned against the outputs this change's plans say its upstreams will have: ${each.join("; ")}.`);
+    }
+    const unknown = [...new Set(report.members.flatMap((m) => (m.unknownInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+    if (unknown.length > 0) {
+        out.push("", `Known only after apply: ${unknown.join("; ")}. This approval does not cover what those members do with them. ` +
+            "The apply plans them again once their upstream applied and asks for an approval of that plan.");
+    }
+    const fromBuild = [...new Set(report.members.flatMap((m) => (m.buildInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+    if (fromBuild.length > 0) {
+        out.push("", `From this pull request's build: ${fromBuild.join("; ")}. The image digest comes from this pull request's build, whose provenance binds it, ` +
+            "so those members apply with it once the build ran, without a second approval.");
+    }
+    for (const r of report.rounds ?? []) {
+        const what = `Round ${r.round} planned ${r.components.map(code).join(", ")} again after their upstream applied, digest ${code(r.digest)}`;
+        if (r.status === "waiting") {
+            if (r.message)
+                out.push("", `> ${r.message}`);
+            out.push("", `${what}. Not approved yet. Approve it, then run the apply again with the same \`--resume\` record:`, "", "```", prApproveCommand({ op: report.op, gate: r.gate, digest: r.digest }, options.approver ?? "<you>"), "```");
+        }
+        else {
+            out.push("", `${what}: ${r.status === "applied" ? `applied, approved by ${(r.approval.approvedBy ?? []).map(code).join(", ")}` : r.status === "plan-failed" ? "a member failed to plan" : "the apply failed"}.`);
+        }
+    }
     if (report.status !== "nothing") {
         out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
     }
+    // #4003: with a gate per wave, a later wave's plan on merge may differ from this one.
+    if (report.stage === "plan" && report.status === "planned" && report.waveGate) {
+        out.push("", `On merge each wave after the first is planned again once the waves before it apply, and a wave whose plan moved stops at its own gate, ${code(`${report.waveGate}-wave-<k>`)}, for approval.`);
+    }
     const head = out.join("\n") + "\n";
     if (report.status === "nothing" || report.changeSet.members.length === 0)
         return head;
@@ -210,20 +306,40 @@ export function prStatusDescription(report) {
         case "applied":
             text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
             break;
+        case "wave-applied": {
+            const last = (report.waves ?? []).filter((w) => w.status === "applied").at(-1);
+            text = `applied wave ${last?.wave ?? "?"} of ${report.selection.waves.length}${last ? ` under ${last.approval === "pull-request" ? "the pull request's approval" : `${last.gate}`}` : ""}`;
+            break;
+        }
         case "failed":
             text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
             break;
-        case "refused":
-            text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+        case "waiting":
+            text = `waiting: ${report.members.filter((m) => m.status === "waiting").map((m) => m.member).join(", ")} planned again after an upstream applied, not approved yet`;
             break;
+        case "refused": {
+            const waiting = report.waves?.find((w) => w.status === "waiting");
+            if (waiting && (report.refusal === "wave-not-approved" || report.refusal === "wave-plan-changed")) {
+                text = `wave ${waiting.wave} waits at ${waiting.gate}: ${report.refusal === "wave-plan-changed" ? "its plan changed after its approval" : "its plan moved, approve it"}`;
+                break;
+            }
+            if (report.refusal === "earlier-wave") {
+                text = "refused: an earlier wave has not applied";
+                break;
+            }
+            text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+            break;
+        }
     }
     return text.length > 140 ? text.slice(0, 137) + "..." : text;
 }
 /** The commit status state for a report: success, failure, or pending while it waits on approval. */
 export function prStatusState(report) {
-    if (report.status === "planned" || report.status === "applied" || report.status === "nothing")
+    if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing")
         return "success";
-    if (report.status === "refused" && report.refusal === "not-approved")
+    if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved"))
+        return "pending";
+    if (report.status === "waiting")
         return "pending";
     return "failure";
 }

package/dist/pr-report-url.d.ts

@@ -44,8 +44,8 @@ export type ReportTarget = {
     bucket: string;
     prefix: string;
 };
-/** `--report-url` read, or why it can't be. */
-export declare function parseReportUrl(raw: string): ReportTarget | {
+/** `--report-url` read, or why it can't be. `name` is what the error calls the value: the flag, or `ci.reportUrl` (#4160). */
+export declare function parseReportUrl(raw: string, name?: string): ReportTarget | {
     error: string;
 };
 /** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */
@@ -60,6 +60,14 @@ export type AwsCli = (args: string[], stdin: string) => Promise<void>;
 export declare const realAwsCli: AwsCli;
 /** A put for `target`. `aws` replaces the AWS CLI in a test. */
 export declare function reportPut(target: ReportTarget, aws?: AwsCli): ReportPut;
+/** Reads one object: `key` below the URL. Resolves null for an object that is not there, and rejects with a line a person can read for any other failure. */
+export type ReportGet = (key: string) => Promise<string | null>;
+/** Runs the AWS CLI with `args` and resolves its stdout, rejecting with its error line on a non-zero exit. */
+export type AwsRead = (args: string[]) => Promise<string>;
+/** The AWS CLI on PATH, read for the body `aws s3 cp <s3 url> -` prints. */
+export declare const realAwsRead: AwsRead;
+/** A get for `target`. `aws` replaces the AWS CLI in a test. */
+export declare function reportGet(target: ReportTarget, aws?: AwsRead): ReportGet;
 /** A stage's upload: its events as they are written, and its files at the end. */
 export interface PrReportUpload {
     /** The folder the stage's files go to: `<url>/<key>`. */

package/dist/pr-report-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-report-url.d.ts","sourceRoot":"","sources":["../src/pr-report-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,mCAAmC;AACnC,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkB5E;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,kCAAkC;AAClC,eAAO,MAAM,gBAAgB,UAAW,MAAM,GAAG,OAAO,KAAG,MAAoC,CAAC;AAEhG,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1F,kGAAkG;AAClG,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAItE,2BAA2B;AAC3B,eAAO,MAAM,UAAU,EAAE,MAmBrB,CAAC;AAEL,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,MAAmB,GAAG,SAAS,CAcnF;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oGAAoG;IACpG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,+FAA+F;IAC/F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAQD,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB,GAAG,cAAc,CA6DjB"}
+{"version":3,"file":"pr-report-url.d.ts","sourceRoot":"","sources":["../src/pr-report-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAOH,mCAAmC;AACnC,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,8HAA8H;AAC9H,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAiB,GAAG,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkBnG;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED,kCAAkC;AAClC,eAAO,MAAM,gBAAgB,UAAW,MAAM,GAAG,OAAO,KAAG,MAAoC,CAAC;AAEhG,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1F,kGAAkG;AAClG,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAItE,2BAA2B;AAC3B,eAAO,MAAM,UAAU,EAAE,MAmBrB,CAAC;AAEL,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,MAAmB,GAAG,SAAS,CAcnF;AAED,6JAA6J;AAC7J,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEhE,8GAA8G;AAC9G,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE1D,4EAA4E;AAC5E,eAAO,MAAM,WAAW,EAAE,OAiBtB,CAAC;AAKL,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,GAAE,OAAqB,GAAG,SAAS,CAoBrF;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oGAAoG;IACpG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,+FAA+F;IAC/F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAQD,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB,GAAG,cAAc,CA6DjB"}

package/dist/pr-report-url.js

@@ -34,11 +34,11 @@
  * CLI's own error line.
  */
 import { spawn } from "node:child_process";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
-/** `--report-url` read, or why it can't be. */
-export function parseReportUrl(raw) {
+/** `--report-url` read, or why it can't be. `name` is what the error calls the value: the flag, or `ci.reportUrl` (#4160). */
+export function parseReportUrl(raw, name = "--report-url") {
     const url = raw.trim();
     if (url.startsWith("file://")) {
         let dir;
@@ -46,10 +46,10 @@ export function parseReportUrl(raw) {
             dir = fileURLToPath(url);
         }
         catch (err) {
-            return { error: `--report-url ${url}: ${err instanceof Error ? err.message : String(err)}` };
+            return { error: `${name} ${url}: ${err instanceof Error ? err.message : String(err)}` };
         }
         if (!isAbsolute(dir))
-            return { error: `--report-url ${url}: a file URL names an absolute directory` };
+            return { error: `${name} ${url}: a file URL names an absolute directory` };
         return { scheme: "file", url: url.replace(/\/+$/, ""), dir };
     }
     const s3 = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
@@ -57,7 +57,7 @@ export function parseReportUrl(raw) {
         const prefix = s3[2].replace(/\/+$/, "");
         return { scheme: "s3", url: `s3://${s3[1]}${prefix ? `/${prefix}` : ""}`, bucket: s3[1], prefix };
     }
-    return { error: `--report-url ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
+    return { error: `${name} ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
 }
 /** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */
 export function reportKey(pr, commit, member) {
@@ -102,6 +102,52 @@ export function reportPut(target, aws = realAwsCli) {
         return aws(["s3", "cp", "-", object, "--content-type", contentType, "--only-show-errors"], body);
     };
 }
+/** The AWS CLI on PATH, read for the body `aws s3 cp <s3 url> -` prints. */
+export const realAwsRead = (args) => new Promise((resolveRead, reject) => {
+    const child = spawn(AWS_BINARY, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const out = [];
+    let stderr = "";
+    child.stdout.on("data", (chunk) => out.push(chunk));
+    child.stderr.on("data", (chunk) => {
+        if (stderr.length < 4096)
+            stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err) => reject(new Error(err.code === "ENOENT" ? "the AWS CLI (aws) is not on PATH; an s3 report URL is read with it" : err.message)));
+    child.on("close", (code) => {
+        if (code === 0)
+            return resolveRead(Buffer.concat(out).toString("utf8"));
+        const line = stderr.trim().split("\n").filter(Boolean).at(-1) ?? "";
+        reject(new Error(`aws s3 cp exited ${code}${line ? `: ${line.slice(0, 300)}` : ""}`));
+    });
+});
+/** What the AWS CLI says about an object that does not exist. */
+const S3_ABSENT = /\(404\)|Not Found|NoSuchKey|does not exist/i;
+/** A get for `target`. `aws` replaces the AWS CLI in a test. */
+export function reportGet(target, aws = realAwsRead) {
+    if (target.scheme === "file") {
+        return async (key) => {
+            try {
+                return readFileSync(join(target.dir, ...key.split("/")), "utf-8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return null;
+                throw err;
+            }
+        };
+    }
+    return async (key) => {
+        const object = `s3://${target.bucket}/${target.prefix ? `${target.prefix}/` : ""}${key}`;
+        try {
+            return await aws(["s3", "cp", object, "-", "--only-show-errors"]);
+        }
+        catch (err) {
+            if (S3_ABSENT.test(messageOf(err)))
+                return null;
+            throw err;
+        }
+    };
+}
 const UPLOAD_ON = new Set(["wave-settle", "component-settle", "run-settle"]);
 const NDJSON = "application/x-ndjson";
 const JSON_TYPE = "application/json";

package/dist/ts-loader.d.ts

@@ -18,14 +18,31 @@
  *
  * Run from source (the repository's `bin/chant` through tsx, vitest), this
  * module is itself TypeScript, the TypeScript loader is already there, and
- * both functions do nothing.
+ * both functions do nothing, except that {@link installCompiledCli} resolves
+ * chant's packages to their source (#3981, {@link installSourceResolution}).
  */
 /**
  * Called once by the CLI's `main()`. Compiled, it records that TypeScript
- * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
- * source it does nothing.
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect. From
+ * source it installs {@link installSourceResolution}.
  */
 export declare function installCompiledCli(): void;
+/**
+ * #3981 — the compiled module for a lexicon's `src/*.ts`: `<lexicon>/dist/*.js`
+ * when it exists, as a URL, else `undefined`. A lexicon ships both, and its
+ * exports name the compiled one; fold reads a composite from the source, and
+ * an import that source makes must land on the module the plugin and the
+ * project already loaded, with no TypeScript loader.
+ */
+export declare function lexiconCompiledTwin(url: string): string | undefined;
+/**
+ * #3981 — the `development` target a chant package's `exports` give
+ * `specifier`, found from `parentPath`'s directory up through each
+ * `node_modules`, or `undefined` when there is none or its file does not
+ * exist. Reads exact keys and single-`*` patterns, the shapes chant's
+ * packages use; anything else is left to Node.
+ */
+export declare function chantPackageSourceTarget(specifier: string, parentPath: string): string | undefined;
 /**
  * Register tsx for the ESM and CommonJS loaders, once, before importing
  * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
@@ -34,13 +51,30 @@ export declare function installCompiledCli(): void;
  * CommonJS hook from source knows not to add a second one.
  */
 export declare function ensureTypeScriptLoader(): boolean;
+/**
+ * #3981 — register tsx only when the module about to be imported is not
+ * JavaScript. `pathOrUrl` is the resolved module, a path or a file URL. A
+ * compiled lexicon (`dist/*.js`) imports with plain node, so a command that
+ * loads only compiled modules never pays for tsx's hooks thread. A `.ts`
+ * module, or one with no extension, registers tsx as before. Returns what
+ * {@link ensureTypeScriptLoader} does, or whether tsx is already registered
+ * when the module is JavaScript.
+ */
+export declare function ensureTypeScriptLoaderFor(pathOrUrl: string): boolean;
+/**
+ * #3981 — whether a caller about to import a module of unknown kind should
+ * resolve it first: true only in the compiled CLI before tsx is registered.
+ * From source, and once tsx is in, every module loads either way.
+ */
+export declare function typeScriptLoaderPending(): boolean;
 /**
  * The source directory for a module of chant's own: `dirname` of `moduleUrl`
  * from source, and the matching directory under `<package>/src` when the
  * module runs from `<package>/dist`. The sandbox drivers hand chant's own
  * modules to esbuild by path, and must name the TypeScript source the
  * project's own `@intentius/chant/*` imports resolve to. String arithmetic
- * only: no filesystem access, so it is safe inside a sandboxed child.
+ * only: no filesystem access, so it is safe inside a sandboxed child. The
+ * same mapping as {@link moduleSourceDir}, which lexicons use.
  */
 export declare function chantSourceDir(moduleUrl: string): string;
 //# sourceMappingURL=ts-loader.d.ts.map

package/dist/ts-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-loader.d.ts","sourceRoot":"","sources":["../src/ts-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAoCH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAwBzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAShD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOxD"}
+{"version":3,"file":"ts-loader.d.ts","sourceRoot":"","sources":["../src/ts-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAqCH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CA+BzC;AAkCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnE;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA0ClG;AAoCD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAShD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAGpE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAGjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD"}