@nubjs/nub-linux-x64 0.0.12 → 0.0.14

package/runtime/preload.mjs

@@ -1,317 +1,101 @@
-// Nub fast-path preload — Node 22.15+ (sync `module.registerHooks`).
+// Nub compat-tier preload — Node 18.19–22.14, injected via `--import` (ESM).
 //
-// This file is the main-thread `--import` preload for ALL tiers. It owns only
-// the tier-specific wiring; every resolution + transpile primitive lives in
-// runtime/transform-core.mjs (shared verbatim with the compat-tier loader
-// worker, so the two can never drift). What stays here:
-//   - watch-mode dependency IPC (main-thread only),
-//   - the thin resolve/load hooks that delegate to the core,
-//   - the main-thread CommonJS `require()` shim (Module._resolveFilename +
-//     require.extensions), installed on BOTH tiers — `module.register` hooks ESM
-//     but not require, and `module.registerHooks`' require coverage is incomplete
-//     before ~Node 24 (e.g. require-from-`.cts` on 22.15),
-//   - clobbered-polyfill preloading + the Temporal lazy global,
-//   - tier dispatch (registerHooks vs register).
-
+// The FAST tier (Node 22.15+) is loaded separately, as a `--require` CommonJS
+// preload (runtime/preload.cjs), so Node keeps its synchronous `Module.runMain`
+// CJS entry path (top-level `executionAsyncId()===1`, sync exception origin,
+// `require.main.id` `'.'`, `module.parent` `null`). The mere presence of an
+// `--import` ESM preload forces eager ESM-loader init that routes even a CJS entry
+// through the async ESM module-job (R1) — so the fast tier must NOT use `--import`.
+//
+// THIS file stays the compat path: on 18.19–22.14, `module.registerHooks` does not
+// exist and `require(esm)` is unreliable, so hooks run async in a dedicated loader
+// worker via `module.register`, and the parser is preloaded via dynamic `import()`
+// while we can still `await`. That async machinery is exactly why the compat tier
+// keeps `--import` — its top-level `await` is accepted here (an `--import` ESM
+// module may be async), and the < 22.15 floor has no equivalent sync surface.
+//
+// Resolution + transpile primitives come from runtime/transform-core.mjs; the
+// non-tier-specific wiring (watch IPC, the CJS require() shim, clobbered-polyfill
+// preloading, the Temporal lazy global) is shared verbatim with the fast tier via
+// runtime/preload-common.cjs, so the two tiers can never drift.
+
+// MUST be first: restores NODE_COMPILE_CACHE into process.env (R8) before
+// transform-core.mjs's body evaluates, since transform-core reads it as the
+// transpile-cache disable signal. ESM imports evaluate in source order, so this
+// side-effecting import has to precede the transform-core import. See
+// compile-cache-restore.mjs.
+import "./compile-cache-restore.mjs";
 import module from "node:module";
-import { readdirSync } from "node:fs";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { join, dirname, resolve as pathResolve, extname as pathExtname } from "node:path";
-import {
-  TRANSPILE_EXTS, DATA_EXTS, TS_PARENT_EXTS,
-  extname, isNodeModules, getTsconfigForDir, getPackageType,
-  resolveSpec, resolveCjsPath, requireTargetIsEsm, loadTranspile, loadData,
-  maybeSweepCache, setWatchHooks, ensureParser,
-} from "./transform-core.mjs";
+import * as core from "./transform-core.mjs";
 
 const __require = createRequire(import.meta.url);
-
-// ── Watch-mode dependency reporting ─────────────────────────────────
-// Under `nub watch`, Node's FilesWatcher only watches files in the import graph;
-// config files (tsconfig.json, package.json) and `.env*` are NOT in any graph,
-// so an edit to them otherwise goes stale. Node accepts incremental
-// `process.send({'watch:require': [...]})` over its WATCH_REPORT_DEPENDENCIES
-// IPC at ANY point in the child's life (it adds each path to the watch set), so
-// we report config paths AS the core loader discovers them. The reporters are
-// injected into the core via setWatchHooks (below) so getTsconfigForDir /
-// getPackageType self-report. The flush is coalesced via setImmediate.
-const WATCH_REPORTING = process.env.WATCH_REPORT_DEPENDENCIES === "1" && typeof process.send === "function";
-const watchReported = new Set();
-const watchPending = [];
-let watchFlushScheduled = false;
-function flushWatchDeps() {
-  watchFlushScheduled = false;
-  if (watchPending.length === 0) return;
-  const batch = watchPending.splice(0, watchPending.length);
-  try { process.send({ "watch:require": batch }); } catch {}
-}
-function reportWatchDep(path) {
-  if (!WATCH_REPORTING || !path || watchReported.has(path)) return;
-  watchReported.add(path);
-  watchPending.push(path);
-  if (!watchFlushScheduled) {
-    watchFlushScheduled = true;
-    // A scheduled immediate is drained before the loop would exit, so even a
-    // script that finishes synchronously flushes its deps. (Don't unref: an
-    // unref'd immediate is skipped on a synchronous exit, dropping the report.)
-    setImmediate(flushWatchDeps);
-  }
-}
-// Report a directory's `.env*` files (the natural watch targets). Scanned once
-// per directory, lazily.
-const watchEnvScannedDirs = new Set();
-function reportEnvFilesIn(dir) {
-  if (!WATCH_REPORTING || watchEnvScannedDirs.has(dir)) return;
-  watchEnvScannedDirs.add(dir);
-  let entries;
-  try { entries = readdirSync(dir); } catch { return; }
-  for (const name of entries) {
-    if (name === ".env" || name.startsWith(".env.")) reportWatchDep(join(dir, name));
-  }
-}
-setWatchHooks({ reportDep: reportWatchDep, reportEnvDir: reportEnvFilesIn });
-
-// Best-effort bounded-cache eviction (main thread only; the core guards on it).
-maybeSweepCache();
-
-// ── Resolve hook ────────────────────────────────────────────────────
-function resolve(specifier, context, nextResolve) {
-  const r = resolveSpec(specifier, context.parentURL);
-  return r ?? nextResolve(specifier, context);
-}
-
-// ── Load hook ───────────────────────────────────────────────────────
-function load(url, context, nextLoad) {
-  const ext = extname(url);
-
-  // Watch mode: surface this file's nearest config files (tsconfig.json,
-  // package.json) + sibling `.env*` so edits to them restart the run. Done for
-  // every user file (not just transpiled ones) — getTsconfigForDir/getPackageType
-  // self-report via the injected watch hooks.
-  if (WATCH_REPORTING && url.startsWith("file:") && !isNodeModules(url)) {
-    try {
-      const dir = dirname(fileURLToPath(url));
-      getTsconfigForDir(dir);
-      getPackageType(dir);
-    } catch {}
-  }
-
-  if (TRANSPILE_EXTS.has(ext)) return loadTranspile(url, ext);
-  if (ext in DATA_EXTS) return loadData(url, ext);
-
-  return nextLoad(url, context);
-}
-
-// ── CommonJS require() augmentation (BOTH tiers) ────────────────────
-// `module.registerHooks`' CJS-`require()` coverage is INCOMPLETE before ~Node 24:
-// on Node 22.15 a `require()` from a `.cts` parent (which Node loads via the ESM
-// translator's special-require) hits native Module._resolveFilename with no
-// tsconfig/extensionless handling — a `require('@alias')` or `require('./x')` of a
-// `.ts` target throws MODULE_NOT_FOUND, while the same code works on Node 26 (where
-// registerHooks does cover it) and on the fast `import` path. On the compat tier
-// (18.19–22.14) the only hook surface is `module.register`, which intercepts the
-// ESM loader ONLY — so `require()` is entirely unaugmented there. Both gaps have
-// the same closure: install this main-thread CJS shim, reusing the core's canonical
-// resolveCjsPath / loadTranspile (no drift). It tries nub's resolution first and
-// FALLS THROUGH to native on a miss, so it is a safe no-op on the versions where
-// registerHooks already covers require (Node 24+/26). Mechanism stays within the
-// augmenter rules: exactly what `--require`-installing the ts-node / tsx CJS shim
-// has always done. So it runs on the fast tier too — registerHooks is necessary
-// but, below ~Node 24, not sufficient for require().
-// This error is surfaced ONLY on Node versions without native require(esm)
-// (< 20.19 / 22.0–22.11), where require() of an ES module genuinely cannot work.
-// On every require(esm)-capable Node, Node loads the ES module itself and this is
-// never reached. The message is user-facing: no internal mechanism names.
-function requireEsmError(filename) {
-  const err = new Error(
-    `Cannot require() this file — it is an ES module.\n` +
-    `  ${filename}\n` +
-    `It uses \`import\`/\`export\`, so it loads as an ES module, and this version of ` +
-    `Node can't require() an ES module. Load it with \`import(...)\` instead, rename ` +
-    `it to .cts for a CommonJS module, or upgrade Node.`,
-  );
-  err.code = "ERR_REQUIRE_ESM";
-  return err;
-}
-
-// `withClassicTranspile` — also install the `require.extensions` (classic CommonJS
-// loader) transpile hook. This is needed ONLY on Node WITHOUT native require(esm)
-// (< 20.19 / 22.0–22.11): there, `module.register`'s ESM-loader hooks can't reach a
-// `require()`, AND an ES module simply can't be require()d, so we transpile CJS
-// content classically and surface a clean error for ESM content. On require(esm)-
-// capable Node we DON'T install it — registering `require.extensions['.ts']` would
-// shadow Node's own native require(esm) of ES-module `.ts` files (breaking
-// `require("./esm.ts")`), and the resolve shim below plus the tier's load hook
-// already cover resolution + transpile.
-function installCjsRequireHooks(withClassicTranspile) {
-  // Module._resolveFilename: try nub's resolution first (tsconfig paths,
-  // extensionless .ts, .js→.ts). If the target is an ES-module TS file AND this
-  // Node can't require(esm), throw a clean error HERE — before Node's special-
-  // require (used for require() from a CJS module loaded via the ESM translator)
-  // crashes with an opaque `cjsCache.get(...)` TypeError. On require(esm)-capable
-  // Node, return the path and let Node load the ES module itself. On miss/own
-  // error, fall through to Node (augmentation never masks Node's diagnostics).
-  const origResolveFilename = module._resolveFilename;
-  module._resolveFilename = function (request, parent, isMain, options) {
-    let resolved = null;
-    try {
-      const parentPath = parent && typeof parent.filename === "string" ? parent.filename : null;
-      resolved = resolveCjsPath(request, parentPath);
-    } catch { /* fall through to Node */ }
-    if (resolved) {
-      if (withClassicTranspile && requireTargetIsEsm(resolved, pathExtname(resolved))) {
-        throw requireEsmError(resolved);
-      }
-      return resolved;
-    }
-    return origResolveFilename.call(this, request, parent, isMain, options);
-  };
-
-  if (!withClassicTranspile) return;
-
-  // require.extensions: transpile via the SAME loadTranspile the load hook uses —
-  // target:'es2022' lowering (`using`), tsconfig, source maps, the Stage-3
-  // decorator guard, and module-format detection are all identical to the fast
-  // tier. The path is already a real TS file (Module._resolveFilename ran first).
-  // A module-format source can't be _compile'd as CJS — same clean error as above.
-  const transpileExtension = (mod, filename) => {
-    const { source, format } = loadTranspile(pathToFileURL(filename).href, pathExtname(filename));
-    if (format === "module") throw requireEsmError(filename);
-    mod._compile(source, filename);
-  };
-  for (const ext of [".ts", ".cts", ".mts", ".tsx", ".jsx"]) {
-    module._extensions[ext] = transpileExtension;
-  }
-}
-
-// ── Pre-load clobbered polyfill packages BEFORE hooks register ──────
-// Packages in the core's CLOBBER_MAP can't be imported after hooks register
-// because the resolve hook returns a synthetic module instead of the real
-// package. Load them here via CJS require (not yet hooked) and stash them.
-// Temporal is the exception (A37): the polyfill is ~18ms to load and most scripts
-// never touch it, so we only RESOLVE its path now (cheap) and defer the load to a
-// lazy global getter (below). Requiring it later by absolute path bypasses the
-// CLOBBER_MAP resolve-hook entry, which keys on the "@js-temporal/polyfill"
-// specifier — not the resolved path.
-const __preloadedPolyfills = {};
-// Feature-detect before requiring (A39): URLPattern is native on Node 24+, so
-// skip loading the polyfill there. On 22.x it's absent → load it.
-if (typeof globalThis.URLPattern === "undefined") {
-  try { __preloadedPolyfills.urlpattern = __require("urlpattern-polyfill"); } catch {}
-}
-// Float16Array: native on Node 24+, absent on the 22.x floor.
-if (typeof globalThis.Float16Array === "undefined") {
-  try { __preloadedPolyfills.float16 = __require("@petamoriken/float16"); } catch {}
-}
-let __temporalPath;
-try { __temporalPath = __require.resolve("@js-temporal/polyfill"); } catch {}
-
-// ── Tier dispatch ───────────────────────────────────────────────────
-// Three tiers per wiki/research/supported-node-versions.md:
-//   - >= 22.15.0:         sync module.registerHooks (fast path, in-thread)
-//   - >= 18.19.0 < 22.15: async module.register (loader worker) + main-thread
-//                         CJS require() shim (module.register is ESM-only)
-//   - <  18.19.0:         unsupported (Rust spawn path hard-errors; defensive log)
-//
-// No user-visible distinction between the two augmentation tiers — both deliver
-// the identical feature surface, silently. The compat-mode notice was dropped
-// 2026-05-29 (it labeled a purely internal mechanism choice).
-const __nodeVersionParts = process.versions.node.split(".").map((n) => parseInt(n, 10));
-const __nodeMajor = __nodeVersionParts[0] || 0;
-const __nodeMinor = __nodeVersionParts[1] || 0;
-const __isAugmentedTier = __nodeMajor > 22 || (__nodeMajor === 22 && __nodeMinor >= 15);
-const __isCompatTier = !__isAugmentedTier && (__nodeMajor > 18 || (__nodeMajor === 18 && __nodeMinor >= 19));
-// Native TypeScript support (`process.features.typescript` is "strip"/"transform"
-// — Node 22.18+/24+). Where present, Node loads `.ts` from require() itself,
-// INCLUDING ES-module `.ts` via native require(esm); registering the classic
-// `require.extensions['.ts']` shim there would shadow that and break
-// `require("./esm.ts")`. Where absent (≤ 22.17 / the whole compat tier), Node can't
-// load a required `.ts` on its own, so the shim is required — it transpiles CJS
-// content and surfaces a clean error for ES-module content (which require() can't
-// load there anyway). Feature-detected, not version-gated.
+const common = __require("./preload-common.cjs");
+const { installSyncPolyfills } = __require("./polyfills.cjs");
+
+// ── Tier detection ──────────────────────────────────────────────────
+// This `.mjs` preload should only ever be `--import`ed for the compat tier (the
+// Rust spawn path chooses `--require preload.cjs` for 22.15+). But guard anyway: if
+// someone `--import`s it directly on an unsupported Node, emit a clear message and
+// skip hook registration rather than throw (throwing breaks user-invoked --import
+// flows). The fast-tier branch is intentionally absent here — 22.15+ goes through
+// preload.cjs.
+const [__major = 0, __minor = 0] = process.versions.node.split(".").map((n) => parseInt(n, 10));
+const __isCompatTier = __major > 18 || (__major === 18 && __minor >= 19);
+const __isFastTier = __major > 22 || (__major === 22 && __minor >= 15);
+
+// Native TypeScript support (`process.features.typescript`). Where absent (the
+// whole compat tier ≤ 22.17), Node can't load a required `.ts` on its own, so the
+// classic require.extensions transpile shim is installed; where present it's
+// skipped so Node's native require() of `.ts` isn't shadowed.
 const __hasNativeTs = !!process.features?.typescript;
 
-if (__isAugmentedTier) {
-  // Fast path: sync, in-thread hooks. Same realm as user code; covers `import` and
-  // (Node 24+) `require`. registerHooks' require RESOLUTION is incomplete on
-  // 22.15–24, so also install the main-thread resolve shim. Install the classic
-  // require.extensions transpile shim only on 22.15–22.17 (no native `.ts`); on
-  // 22.18+/24+ skip it so Node's native require() of `.ts` — incl. ES modules —
-  // isn't shadowed (see installCjsRequireHooks).
+// Watch reporting + the Temporal lazy global are tier-independent.
+common.installWatchReporting(core);
+
+if (__isFastTier) {
+  // Defensive only — the Rust path uses preload.cjs for 22.15+. If reached, the
+  // sync registerHooks API is available; register synchronously to stay correct.
+  const { resolve, load } = common.makeHooks(core, process.env.WATCH_REPORT_DEPENDENCIES === "1");
   module.registerHooks({ resolve, load });
-  installCjsRequireHooks(!__hasNativeTs);
+  common.installCjsRequireHooks(core, !__hasNativeTs);
 } else if (__isCompatTier) {
   // Compat path: ESM `import` hooks run in a dedicated loader worker thread.
   module.register("./preload-async-hooks.mjs", import.meta.url);
   // The main-thread CommonJS require() shim's format detection is synchronous and
-  // reaches down to Node 18.19, where `require("oxc-parser")` (ESM-only) fails —
-  // so preload the parser via dynamic import now, while we can still await.
-  await ensureParser();
+  // reaches down to Node 18.19, where `require("oxc-parser")` (ESM-only) fails — so
+  // preload the parser via dynamic import now, while we can still await.
+  await core.ensureParser();
   // module.register() is ESM-loader-only; augment CommonJS require() on the main
   // thread too. The compat tier never has native `.ts`, so it always installs the
   // classic transpile shim (CJS transpile + clean error for ES-module require()).
-  installCjsRequireHooks(!__hasNativeTs);
+  common.installCjsRequireHooks(core, !__hasNativeTs);
 } else {
-  // Defensive: Rust spawn path hard-errors on < 18.19 before reaching here. If
-  // invoked directly via `node --import`, emit a clear message and skip hook
-  // registration rather than throw (throwing breaks user-invoked --import flows).
   process.stderr.write(
     `Nub requires Node 18.19 or newer for runtime augmentation; got ${process.versions.node}. Preload is inactive.\n`,
   );
 }
 
-// ── Polyfill preloads (tier-independent) ────────────────────────────
-// Polyfills install identically on both augmented and compat paths.
-globalThis.__nubPreloaded = __preloadedPolyfills;
-await import("./polyfills.mjs");
-delete globalThis.__nubPreloaded;
-
-// ── Temporal: lazy global (A37) ─────────────────────────────────────
-// Temporal ships in no supported Node, so nub always provides it — but the
-// polyfill is ~18ms to load and rarely used, so install a lazy getter that loads
-// it (by resolved path, bypassing the clobber) on first access. The CLOBBER
-// re-export of `import "@js-temporal/polyfill"` reads globalThis.Temporal, so a
-// user importing the package triggers this same one-time load. A plain assignment
-// (`globalThis.Temporal = …`) replaces the accessor with the value.
-if (typeof globalThis.Temporal === "undefined" && __temporalPath) {
-  const defineTemporal = (value) =>
-    Object.defineProperty(globalThis, "Temporal", {
-      value,
-      configurable: true,
-      writable: true,
-      enumerable: false,
-    });
-  Object.defineProperty(globalThis, "Temporal", {
-    configurable: true,
-    enumerable: false,
-    get() {
-      const polyfill = __require(__temporalPath);
-      // @js-temporal/polyfill exports `toTemporalInstant` as a function but does
-      // NOT auto-install it on Date.prototype (you assign it yourself). Install it
-      // here so that on the floor (no native Temporal) `date.toTemporalInstant()`
-      // AND the package clobber's re-export of `Date.prototype.toTemporalInstant`
-      // both work — matching native Node. Guarded so we never replace a native
-      // implementation on a runtime that ships Temporal.
-      if (
-        typeof Date.prototype.toTemporalInstant !== "function" &&
-        typeof polyfill.toTemporalInstant === "function"
-      ) {
-        Object.defineProperty(Date.prototype, "toTemporalInstant", {
-          value: polyfill.toTemporalInstant,
-          configurable: true,
-          writable: true,
-          enumerable: false,
-        });
-      }
-      const T = polyfill.Temporal;
-      defineTemporal(T);
-      return T;
-    },
-    set: defineTemporal,
-  });
+// ── Clobbered-polyfill preloading + polyfills ───────────────────────
+// Require the clobbered polyfill packages before the resolve hook would intercept
+// them, then install the sync globals (shared with the fast tier) and the two ESM
+// side-effect modules. On the compat tier `require(esm)` of the worker/navigator
+// modules is unreliable, so they load via dynamic `import()` here.
+const __preloadedPolyfills = common.preloadPolyfillPackages(__require);
+installSyncPolyfills(__preloadedPolyfills);
+if (typeof globalThis.navigator?.locks === "undefined") {
+  await import("./navigator-locks.mjs");
 }
+await import("./worker-polyfill.mjs");
 
-// Watch-mode dependency reporting is incremental — see reportWatchDep + the
-// injected core hooks. Config deps are reported as the loader discovers each user
-// file, plus their `.env*` siblings.
+// ── Temporal: lazy global (A37) ─────────────────────────────────────
+common.installTemporalLazyGlobal(__require);
+
+// ── Compile-cache: re-enable for the USER's modules (R8) ────────────
+// spawn.rs strips NODE_COMPILE_CACHE for every augmented spawn (both tiers), so
+// nub's preload chain is never cached into the user's dir. Re-point the cache at
+// the user's original dir (via the PID-keyed sentinel) so their own modules still
+// cache. `module.enableCompileCache` only exists on Node 22.8+, so on most of the
+// compat tier (< 22.8) this is a safe no-op; it benefits 22.8–22.14 users who set
+// NODE_COMPILE_CACHE. See reenableUserCompileCache for the full rationale.
+common.reenableUserCompileCache();