@intentius/chant 0.124.13 → 0.124.14

package/src/lint/policy-import.ts

@@ -17,12 +17,14 @@
  * the *decision* and documents the reasoning, and re-exports these three
  * functions as its public surface) for one structural reason: `./policy.ts`
  * needs to consult it, `./policy-sandbox.ts` needs to call `./policy.ts`, and a
- * flag on a leaf module with no imports of its own breaks what would otherwise
+ * flag on a leaf module (its one import, `../ts-loader`, is a leaf too) breaks what would otherwise
  * be an import cycle. It also puts the check on the narrowest possible thing —
  * the function that actually executes project code — rather than on a caller
  * that might forget to ask.
  */
 
+import { ensureTypeScriptLoader } from "../ts-loader";
+
 /** Whether this process must run project policy modules inside the sandbox boundary instead of here. */
 let armed = false;
 
@@ -66,5 +68,6 @@ export async function importPolicyModule(policyPath: string): Promise<PolicyModu
       `Refusing to import the policy module ${policyPath} into the chant process under --sandbox: it is project-authored code and must be imported inside the sandbox boundary (packages/core/src/lint/policy-sandbox.ts's runProjectPolicies).`,
     );
   }
+  ensureTypeScriptLoader();
   return (await import(policyPath)) as PolicyModuleNamespace;
 }

package/src/lint/rule-loader.ts

@@ -1,6 +1,7 @@
 import { readdirSync, existsSync } from "fs";
 import { dirname, join, resolve } from "path";
 import type { LintRule } from "./rule";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -82,6 +83,7 @@ export async function loadLocalRules(projectDir: string): Promise<LintRule[]> {
     const filePath = resolve(rulesDir, file);
     let mod: Record<string, unknown>;
     try {
+      ensureTypeScriptLoader();
       mod = await import(filePath);
     } catch (err) {
       throw new Error(

package/src/op/discover.ts

@@ -6,6 +6,7 @@ import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
 import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
 import { isStewardDeclaration, type StewardDeclaration } from "./steward";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -150,6 +151,7 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   for (const filePath of files) {
     try {
+      ensureTypeScriptLoader();
       const mod = (await import(filePath)) as Record<string, unknown>;
       const exported = opsExportedBy(mod);
 
@@ -220,6 +222,7 @@ export async function discoverStewards(opts?: { cwd?: string }): Promise<Steward
   for (const filePath of files) {
     let mod: Record<string, unknown>;
     try {
+      ensureTypeScriptLoader();
       mod = (await import(filePath)) as Record<string, unknown>;
     } catch (err) {
       errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);

package/src/ts-loader.test.ts

@@ -0,0 +1,23 @@
+import { join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { chantSourceDir, ensureTypeScriptLoader } from "./ts-loader";
+
+describe("ts-loader (#3878)", () => {
+  const pkg = join(sep, "x", "node_modules", "@intentius", "chant");
+
+  test("chantSourceDir maps a compiled module's directory to its source directory", () => {
+    const url = pathToFileURL(join(pkg, "dist", "discovery", "sandbox", "driver.js")).href;
+    expect(chantSourceDir(url)).toBe(join(pkg, "src", "discovery", "sandbox"));
+    expect(chantSourceDir(pathToFileURL(join(pkg, "dist", "params.js")).href)).toBe(join(pkg, "src"));
+  });
+
+  test("chantSourceDir leaves a source module's directory alone", () => {
+    const url = pathToFileURL(join(pkg, "src", "discovery", "sandbox", "driver.ts")).href;
+    expect(chantSourceDir(url)).toBe(join(pkg, "src", "discovery", "sandbox"));
+  });
+
+  test("from source, the TypeScript loader is already there and nothing is registered", () => {
+    expect(ensureTypeScriptLoader()).toBe(false);
+  });
+});

package/src/ts-loader.ts

@@ -0,0 +1,122 @@
+/**
+ * #3878 — TypeScript loading for the compiled CLI.
+ *
+ * An installed chant runs `dist/cli/main.js` with plain `node`, so chant's own
+ * modules need no loader. Everything else chant imports at run time still can
+ * be TypeScript: a project's `chant.config.ts` and source files, `*.op.ts`,
+ * policies and lint rules, and the lexicon packages, which ship `src/*.ts`.
+ * {@link ensureTypeScriptLoader} registers tsx for those, the first time one of
+ * them is about to be imported, so a command that imports none (`--version`,
+ * `run wave` on a project with no `chant.config.ts`) never loads tsx at all.
+ *
+ * {@link installCompiledCli} also points every resolution of chant's own
+ * source at the compiled file next to it. A lexicon or project file imports
+ * `@intentius/chant`, and the package exports resolve that to `src/*.ts`;
+ * without the redirect that import would load a second copy of core,
+ * transpiled, beside the one the CLI runs, with its own registries and
+ * classes.
+ *
+ * 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.
+ */
+
+import { existsSync } from "node:fs";
+import * as nodeModule from "node:module";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// `module.registerHooks` (Node 22.15+, 24) is newer than the @types/node the
+// repository pins, so its shape is declared here.
+interface ResolveResult {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+type NextResolve = (specifier: string, context?: unknown) => ResolveResult;
+const { createRequire, registerHooks } = nodeModule as unknown as {
+  createRequire: typeof nodeModule.createRequire;
+  registerHooks: (hooks: { resolve: (specifier: string, context: unknown, nextResolve: NextResolve) => ResolveResult }) => unknown;
+};
+
+interface CompiledCliState {
+  /** Whether tsx has been registered in this process. */
+  tsx: boolean;
+}
+
+const STATE = Symbol.for("chant.compiledCli");
+
+function compiledState(): CompiledCliState | undefined {
+  return (globalThis as { [STATE]?: CompiledCliState })[STATE];
+}
+
+/** True when this module runs as compiled JavaScript, from `<package>/dist`. */
+function runsCompiled(): boolean {
+  return import.meta.url.endsWith(".js");
+}
+
+/**
+ * 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.
+ */
+export function installCompiledCli(): void {
+  if (!runsCompiled() || compiledState()) return;
+  (globalThis as { [STATE]?: CompiledCliState })[STATE] = { tsx: false };
+
+  const distDir = dirname(fileURLToPath(import.meta.url));
+  const srcUrl = pathToFileURL(join(dirname(distDir), "src") + sep).href;
+  const distUrl = pathToFileURL(distDir + sep).href;
+  const compiled = new Map<string, string | null>();
+
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const result = nextResolve(specifier, context);
+      if (!result.url.startsWith(srcUrl)) return result;
+      const path = result.url.slice(srcUrl.length).replace(/[?#].*$/, "");
+      if (!path.endsWith(".ts") || path.endsWith(".d.ts")) return result;
+      let target = compiled.get(path);
+      if (target === undefined) {
+        const js = distUrl + path.slice(0, -3) + ".js";
+        target = existsSync(fileURLToPath(js)) ? js : null;
+        compiled.set(path, target);
+      }
+      return target === null ? result : { ...result, url: target, format: "module" };
+    },
+  });
+}
+
+/**
+ * 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)
+ * is already loading chant itself. Returns whether the compiled CLI's tsx
+ * registration covers this process, so a caller that registers its own
+ * CommonJS hook from source knows not to add a second one.
+ */
+export function ensureTypeScriptLoader(): boolean {
+  const state = compiledState();
+  if (!state) return false;
+  if (state.tsx) return true;
+  state.tsx = true;
+  const require = createRequire(import.meta.url);
+  (require("tsx/cjs/api") as { register: () => unknown }).register();
+  (require("tsx/esm/api") as { register: () => unknown }).register();
+  return true;
+}
+
+/**
+ * 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.
+ */
+export function chantSourceDir(moduleUrl: string): string {
+  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);
+}

package/src/workspace/chant-migrations/chud-lexicon-exit.ts

@@ -47,7 +47,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, posix } from "node:path";
 import yaml from "js-yaml";
-import answerSchema from "../point-answer.schema.json";
+import answerSchema from "../point-answer.schema.json" with { type: "json" };
 import { fileHash } from "../lineage-lock";
 import { DECISION_POINTS_SCHEMA_ID, POINT_INPUT_OUTPUT_NAMES, parsePoints, PointsError } from "../points";
 import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, NotMoved, PlanConflict, PlannedChange } from "../chant-migrations";

package/src/workspace/declaration.ts

@@ -19,7 +19,7 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import schema from "./declaration.schema.json";
+import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";

package/src/workspace/kinds.ts

@@ -20,7 +20,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import schema from "./workspace-kinds.schema.json";
+import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";

package/src/workspace/lineage-migrations.ts

@@ -25,6 +25,7 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 import { LockError, type Lineage } from "./lineage-lock";
 import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError, type Version } from "./lineage-version";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 /** Where a template keeps its migrations, relative to the template's directory. */
 export const MIGRATIONS_DIR = ".chant/migrations";
@@ -281,6 +282,7 @@ export async function runMigration(m: LoadedMigration, opts: RunMigrationOptions
       mkdirSync(dirname(abs), { recursive: true });
       writeFileSync(abs, data);
     }
+    ensureTypeScriptLoader();
     const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
     if (typeof mod.default !== "function") throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
     await (mod.default as (ctx: { dir: string }) => unknown)({ dir: opts.dir });

package/src/workspace/points.ts

@@ -35,7 +35,7 @@
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { dirname, posix, relative, resolve, sep } from "node:path";
-import schema from "./decision-points.schema.json";
+import schema from "./decision-points.schema.json" with { type: "json" };
 import type { ReasonCode } from "./reason-codes";
 import type { RecordSource } from "./record-source";
 import type { LoadedRecordKind, ReadRecordsOptions, RecordEntry } from "./records";

package/src/workspace/principal-classes.ts

@@ -26,7 +26,7 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, posix } from "node:path";
 import { kindsExportTarget, pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
-import schema from "./workspace-principals.schema.json";
+import schema from "./workspace-principals.schema.json" with { type: "json" };
 import type { TrustPolicy } from "./trust/policy";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, grantedClasses, type PrincipalClass } from "./identity-gate-rule";