@intentius/chant 0.124.31 → 0.124.32

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>]`. */

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,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"}
+{"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

@@ -37,8 +37,8 @@ import { spawn } from "node:child_process";
 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) {

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"}

package/dist/ts-loader.js

@@ -18,12 +18,14 @@
  *
  * 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}).
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import * as nodeModule from "node:module";
 import { dirname, join, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { isJavaScriptModule, moduleSourceDir } from "./module-source.js";
 const { createRequire, registerHooks } = nodeModule;
 const STATE = Symbol.for("chant.compiledCli");
 function compiledState() {
@@ -35,11 +37,15 @@ function runsCompiled() {
 }
 /**
  * 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 function installCompiledCli() {
-    if (!runsCompiled() || compiledState())
+    if (!runsCompiled()) {
+        installSourceResolution();
+        return;
+    }
+    if (compiledState())
         return;
     globalThis[STATE] = { tsx: false };
     const distDir = dirname(fileURLToPath(import.meta.url));
@@ -49,8 +55,10 @@ export function installCompiledCli() {
     registerHooks({
         resolve(specifier, context, nextResolve) {
             const result = nextResolve(specifier, context);
-            if (!result.url.startsWith(srcUrl))
-                return result;
+            if (!result.url.startsWith(srcUrl)) {
+                const twin = lexiconCompiledTwin(result.url);
+                return twin === undefined ? result : { ...result, url: twin, format: "module" };
+            }
             const path = result.url.slice(srcUrl.length).replace(/[?#].*$/, "");
             if (!path.endsWith(".ts") || path.endsWith(".d.ts"))
                 return result;
@@ -64,6 +72,155 @@ export function installCompiledCli() {
         },
     });
 }
+/** Package directories by the directory a module sits in: a lexicon package's root, or null for any other package. */
+const lexiconRoots = new Map();
+/** The lexicon package `dir` belongs to: the nearest directory up with a package.json, when it names a chant lexicon. */
+function lexiconRootOf(dir) {
+    const seen = [];
+    let root = null;
+    for (let at = dir;;) {
+        const cached = lexiconRoots.get(at);
+        if (cached !== undefined) {
+            root = cached;
+            break;
+        }
+        seen.push(at);
+        const manifest = join(at, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                const name = JSON.parse(readFileSync(manifest, "utf-8")).name;
+                root = typeof name === "string" && name.startsWith("@intentius/chant-lexicon-") ? at : null;
+            }
+            catch {
+                root = null;
+            }
+            break;
+        }
+        const parent = dirname(at);
+        if (parent === at)
+            break;
+        at = parent;
+    }
+    for (const at of seen)
+        lexiconRoots.set(at, root);
+    return root ?? undefined;
+}
+/**
+ * #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 function lexiconCompiledTwin(url) {
+    if (!url.startsWith("file:"))
+        return undefined;
+    const path = fileURLToPath(url.replace(/[?#].*$/, ""));
+    if (!/\.[cm]?ts$/.test(path) || /\.d\.[cm]?ts$/.test(path) || !path.includes(`${sep}src${sep}`))
+        return undefined;
+    const root = lexiconRootOf(dirname(path));
+    if (root === undefined)
+        return undefined;
+    const srcDir = join(root, "src") + sep;
+    if (!path.startsWith(srcDir))
+        return undefined;
+    const js = join(root, "dist", path.slice(srcDir.length)).replace(/\.([cm]?)ts$/, ".$1js");
+    return existsSync(js) ? pathToFileURL(js).href : undefined;
+}
+const SOURCE_RESOLUTION = Symbol.for("chant.sourceResolution");
+/**
+ * #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 function chantPackageSourceTarget(specifier, parentPath) {
+    const match = /^(@intentius\/chant(?:-[a-z0-9-]+)?)(\/.*)?$/.exec(specifier);
+    if (!match)
+        return undefined;
+    const subpath = match[2] ? `.${match[2]}` : ".";
+    let dir = dirname(parentPath);
+    for (;;) {
+        const pkgDir = join(dir, "node_modules", match[1]);
+        const manifest = join(pkgDir, "package.json");
+        if (existsSync(manifest)) {
+            let exportsField;
+            try {
+                exportsField = JSON.parse(readFileSync(manifest, "utf-8")).exports;
+            }
+            catch {
+                return undefined;
+            }
+            if (!exportsField || typeof exportsField !== "object")
+                return undefined;
+            const map = exportsField;
+            let entry = map[subpath];
+            let star;
+            if (entry === undefined) {
+                let best = "";
+                for (const key of Object.keys(map)) {
+                    const at = key.indexOf("*");
+                    if (at < 0 || key.indexOf("*", at + 1) >= 0)
+                        continue;
+                    const prefix = key.slice(0, at);
+                    const suffix = key.slice(at + 1);
+                    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix) || subpath.length < key.length || prefix.length <= best.length)
+                        continue;
+                    best = prefix;
+                    entry = map[key];
+                    star = subpath.slice(prefix.length, subpath.length - suffix.length);
+                }
+            }
+            const development = entry && typeof entry === "object" ? entry.development : undefined;
+            if (typeof development !== "string")
+                return undefined;
+            const target = join(pkgDir, star === undefined ? development : development.split("*").join(star));
+            // Node keys a module by its real path, so a symlinked package must too.
+            return existsSync(target) ? realpathSync(target) : undefined;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * #3981 — from source, resolve chant's own packages through their
+ * `development` export condition, as `node --conditions=development` (which
+ * the repository's `bin/chant` passes) would. A lexicon's `default` export is
+ * its compiled `dist/*.js`, which a checkout may not have built, or built from
+ * older source; `development` is its `src/*.ts`, which vitest, a project's
+ * tsconfig `paths` and fold's own resolution (`SOURCE_EXPORT_CONDITIONS`)
+ * pick. Without this, a CLI run from source by `node --import tsx` would load
+ * a plugin from `dist/` and fold the project against `src/`: two copies of the
+ * lexicon with their own classes.
+ *
+ * The hook resolves the specifier itself and short-circuits: conditions added
+ * to the context here do not reach tsx's resolver. Nothing is installed under
+ * vitest, whose resolver already adds the condition, or on a node without
+ * `module.registerHooks`.
+ */
+function installSourceResolution() {
+    // In a vitest worker (not a CLI it spawns, which inherits its environment), vite resolves.
+    if ("__vitest_worker__" in globalThis || typeof registerHooks !== "function")
+        return;
+    const flags = globalThis;
+    if (flags[SOURCE_RESOLUTION])
+        return;
+    flags[SOURCE_RESOLUTION] = true;
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const parentURL = context?.parentURL;
+            if (specifier.startsWith("@intentius/chant") && parentURL?.startsWith("file:")) {
+                const target = chantPackageSourceTarget(specifier, fileURLToPath(parentURL));
+                if (target !== undefined)
+                    return { url: pathToFileURL(target).href, shortCircuit: true };
+            }
+            return nextResolve(specifier, context);
+        },
+    });
+}
 /**
  * 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)
@@ -83,21 +240,38 @@ export function ensureTypeScriptLoader() {
     require("tsx/esm/api").register();
     return true;
 }
+/**
+ * #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 function ensureTypeScriptLoaderFor(pathOrUrl) {
+    if (!isJavaScriptModule(pathOrUrl))
+        return ensureTypeScriptLoader();
+    return compiledState()?.tsx ?? false;
+}
+/**
+ * #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 function typeScriptLoaderPending() {
+    const state = compiledState();
+    return state !== undefined && !state.tsx;
+}
 /**
  * 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 function chantSourceDir(moduleUrl) {
-    const dir = dirname(fileURLToPath(moduleUrl));
-    if (!moduleUrl.endsWith(".js"))
-        return dir;
-    const marker = `${sep}dist${sep}`;
-    const at = (dir + sep).lastIndexOf(marker);
-    if (at < 0)
-        return dir;
-    return dir.slice(0, at) + `${sep}src` + dir.slice(at + marker.length - 1);
+    return moduleSourceDir(moduleUrl);
 }