@ttsc/unplugin 0.28.5 → 0.29.0

package/src/bun-register.ts

@@ -1,3 +1,5 @@
+import { isDeepStrictEqual } from "node:util";
+
 import bun, { type BunLikePlugin } from "./bun";
 import type { TtscUnpluginOptions } from "./core/options";
 
@@ -12,20 +14,29 @@ interface BunRuntimeGlobal {
   plugin(plugin: BunLikePlugin): void;
 }
 
+interface BunRegistrationState {
+  activeOptions: TtscUnpluginOptions | undefined;
+  lockedOptions: TtscUnpluginOptions | undefined;
+  optionsLocked: boolean;
+  registered: boolean;
+}
+
 /**
- * Effective options for the single runtime loader.
+ * Pending and locked options for the single runtime loader.
  *
  * Bun uses the first matching `onLoad` hook and does not fall through to a
  * later overlapping plugin (oven-sh/bun#20583). Registering twice — once
  * implicitly on import, once explicitly — would let the default loader shadow
- * the configured one. Instead exactly one Bun plugin is registered; it resolves
- * these options lazily on first load (see {@link bun}'s provider form), so an
- * explicit `register(options)` made right after importing this module overrides
- * the preload defaults without a second shadowing registration.
+ * the configured one. Instead exactly one Bun plugin is registered. Calls made
+ * before its first load replace this detached snapshot; entering the first
+ * transformable load locks that value synchronously for the process's immutable
+ * module-loading session. State is keyed by the Bun runtime in a global weak
+ * map so loading both emitted module conditions cannot install two overlapping
+ * loaders.
  */
-let activeOptions: TtscUnpluginOptions | undefined;
-/** Whether the single runtime loader has already been registered with Bun. */
-let registered = false;
+const BUN_REGISTRATION_STATES = Symbol.for(
+  "@ttsc/unplugin/bun-register/states/v1",
+);
 
 /**
  * Register the ttsc transform as a Bun **runtime** plugin.
@@ -39,14 +50,17 @@ let registered = false;
  * "@ttsc/unplugin/bun-register"`. Options are read from the nearest
  * `tsconfig.json`, identical to the bundler adapters.
  *
- * Registration is idempotent: the first call (implicit on import, or explicit)
- * registers the one loader with Bun; later calls only update the effective
- * options, so accessing the explicit API cannot install a second default loader
- * that shadows the caller's configuration. Repeated explicit calls are
- * last-write-wins for the effective options.
+ * The first call registers one loader. Calls before its first transformable
+ * TypeScript load use last-call-wins and capture options by value, so an
+ * explicit call right after importing this module replaces the preload defaults
+ * without installing a shadowing loader. Entering the first such load locks
+ * that snapshot synchronously. Later calls with a structurally identical value
+ * are idempotent; a different value throws rather than pretending a resolved
+ * loader changed configuration.
  *
- * @throws When called explicitly off the Bun runtime (`globalThis.Bun.plugin`
- *   is unavailable). The auto-registration below stays silent off Bun so the
+ * @throws When called explicitly off the Bun runtime, when options are not
+ *   structured-cloneable, or when a different option value is supplied after
+ *   the first load. The auto-registration below stays silent off Bun so the
  *   module is harmless to import from Node (tests, tooling).
  */
 export function register(options?: TtscUnpluginOptions): void {
@@ -58,15 +72,61 @@ export function register(options?: TtscUnpluginOptions): void {
         "@ttsc/unplugin/vite for non-Bun toolchains.",
     );
   }
-  activeOptions = options;
-  if (registered) {
-    return;
+  const state = registrationState(runtime);
+  const snapshot = snapshotOptions(options);
+  if (state.optionsLocked) {
+    if (isDeepStrictEqual(snapshot, state.lockedOptions)) {
+      return;
+    }
+    throw new Error(
+      "@ttsc/unplugin/bun-register options are locked because the runtime " +
+        "loader has started handling a TypeScript module. Restart the Bun " +
+        "process to use different compiler or plugin options.",
+    );
+  }
+  state.activeOptions = snapshot;
+  ensureRegistered(runtime, state);
+}
+
+/** Install the runtime's one loader without changing its pending options. */
+function ensureRegistered(
+  runtime: BunRuntimeGlobal,
+  state: BunRegistrationState,
+): void {
+  if (state.registered) return;
+  state.registered = true;
+  try {
+    runtime.plugin(bun(() => lockOptions(state)));
+  } catch (error) {
+    state.registered = false;
+    throw error;
+  }
+}
+
+/** Lock and return the detached option snapshot at first load-handler entry. */
+function lockOptions(
+  state: BunRegistrationState,
+): TtscUnpluginOptions | undefined {
+  if (!state.optionsLocked) {
+    state.lockedOptions = state.activeOptions;
+    state.optionsLocked = true;
+  }
+  return state.lockedOptions;
+}
+
+/** Detach JSON-shaped options from mutations made after `register` returns. */
+function snapshotOptions(
+  options: TtscUnpluginOptions | undefined,
+): TtscUnpluginOptions | undefined {
+  if (options === undefined) return undefined;
+  try {
+    return structuredClone(options);
+  } catch (cause) {
+    throw new TypeError(
+      "@ttsc/unplugin/bun-register options must contain structured-cloneable values.",
+      { cause },
+    );
   }
-  registered = true;
-  // Register a single loader whose options are read from `activeOptions` on
-  // first load, so an explicit call made after the import-time auto-register
-  // still wins.
-  runtime.plugin(bun(() => activeOptions));
 }
 
 function bunRuntime(): BunRuntimeGlobal | undefined {
@@ -76,11 +136,38 @@ function bunRuntime(): BunRuntimeGlobal | undefined {
     : undefined;
 }
 
+/** Resolve the shared state owned by one concrete Bun runtime object. */
+function registrationState(runtime: BunRuntimeGlobal): BunRegistrationState {
+  const holder = globalThis as unknown as Record<PropertyKey, unknown>;
+  let states = holder[BUN_REGISTRATION_STATES];
+  if (!(states instanceof WeakMap)) {
+    states = new WeakMap<object, BunRegistrationState>();
+    Object.defineProperty(holder, BUN_REGISTRATION_STATES, {
+      configurable: false,
+      enumerable: false,
+      value: states,
+      writable: false,
+    });
+  }
+  const registrations = states as WeakMap<object, BunRegistrationState>;
+  const existing = registrations.get(runtime);
+  if (existing !== undefined) return existing;
+  const created: BunRegistrationState = {
+    activeOptions: undefined,
+    lockedOptions: undefined,
+    optionsLocked: false,
+    registered: false,
+  };
+  registrations.set(runtime, created);
+  return created;
+}
+
 // Auto-register on import so a `bunfig.toml` `preload` entry — which only
 // imports the module — takes effect. Guarded so importing from Node (a stray
 // import, or a unit test) is a harmless no-op rather than a throw.
-if (bunRuntime() !== undefined) {
-  register();
+const runtime = bunRuntime();
+if (runtime !== undefined) {
+  ensureRegistered(runtime, registrationState(runtime));
 }
 
 export default register;

package/src/bun.ts

@@ -4,18 +4,15 @@ import {
   beginTtscTransformBuild,
   createTtscTransformCache,
   isTransformTarget,
+  resetTtscTransformCache,
   resolveOptions,
   transformTtsc,
 } from "./core/index";
 import type { TtscUnpluginOptions } from "./core/options";
-
-/**
- * Bun normally reports filesystem source paths, while plugin-created virtual
- * ids may contain a NUL sentinel. A virtual id must stay with the plugin that
- * created it: claiming it here and trying to read it from disk prevents that
- * plugin's later loader from running.
- */
-const bunSourceFilePattern = /^[^\x00]*\.[cm]?tsx?$/;
+import {
+  bunTypeScriptTransformSourcePattern,
+  typescriptTransformBunLoader,
+} from "./core/sourceExtensions";
 
 /**
  * Minimal subset of the Bun plugin API consumed by this adapter.
@@ -40,10 +37,10 @@ export type BunLoader = "ts" | "tsx";
  *
  * The provider form exists for the runtime registration path (`bun-register`),
  * where a single Bun plugin is registered on import but its effective options
- * may be overridden by an explicit `register(options)` call made in the same
- * synchronous tick. Resolving through the provider on first load, rather than
- * at registration, lets that later call win without Bun ever seeing a second
- * shadowing loader.
+ * may be overridden by explicit `register(options)` calls made before the first
+ * transformable TypeScript load. Resolving through the provider on that first
+ * load, rather than at registration, lets the last pending call win without Bun
+ * ever seeing a second shadowing loader.
  */
 export type TtscBunOptions =
   | TtscUnpluginOptions
@@ -75,10 +72,10 @@ function resolveBunOptions(
 /**
  * Minimal subset of the Bun `BuildConfig` plugin build object.
  *
- * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`,
- * which is used when available to forward the shared plugin's build lifecycle
- * and clear its per-build cache. The runtime plugin API omits that hook, so
- * plugin setup itself starts its one process-scoped module-loading session.
+ * `onLoad` drives the source transform. Bun's bundler also exposes `onStart`
+ * and `onEnd`, which bracket the shared plugin's build lifecycle. The runtime
+ * plugin API omits those hooks, so plugin setup itself starts its one
+ * process-scoped module-loading session.
  */
 export interface BunLikeBuild {
   /**
@@ -97,6 +94,8 @@ export interface BunLikeBuild {
    * Optional because `Bun.plugin()` runtime builders do not expose this hook.
    */
   onStart?(callback: () => void | Promise<void>): void;
+  /** Register a callback for deterministic bundler-session teardown. */
+  onEnd?(callback: () => void | Promise<void>): void;
   /**
    * Register a loader callback for files matching `filter`.
    *
@@ -141,10 +140,10 @@ export default function bun(options?: TtscBunOptions): BunLikePlugin {
   return {
     name: "ttsc-unplugin",
     setup(build) {
-      // Resolve options lazily on first load. Runtime registration may call
-      // register(options) immediately after the import-time default
-      // registration; the provider form must observe that last synchronous
-      // update without installing a second shadowing loader.
+      // Resolve options lazily on the first transformable TypeScript load.
+      // Runtime registration may replace its pending configuration at any time
+      // before then; the provider form must observe that last update without
+      // installing a second shadowing loader.
       let resolved: ReturnType<typeof resolveOptions> | undefined;
       const getOptions = () =>
         (resolved ??= resolveOptions(resolveBunOptions(options)));
@@ -159,43 +158,54 @@ export default function bun(options?: TtscBunOptions): BunLikePlugin {
       // repeats it for subsequent builds.
       beginTtscTransformBuild(cache);
       build.onStart?.(() => beginTtscTransformBuild(cache));
-      build.onLoad({ filter: bunSourceFilePattern }, async (args) => {
-        if (!runtime && ownsInMemoryFile(args.path)) {
-          return undefined;
-        }
-        if (!isTransformTarget(args.path)) {
-          if (!runtime) return undefined;
-          return {
-            contents: await fs.readFile(args.path, "utf8"),
-            loader: bunLoaderFor(args.path),
-          };
-        }
-        const loader = bunLoaderFor(args.path);
-        const source = await fs.readFile(args.path, "utf8");
-        const result = await transformTtsc(
-          args.path,
-          source,
-          getOptions(),
-          undefined,
-          cache,
-          bunTransformHooks,
-        );
-        if (result !== undefined) {
-          return { contents: result.code, loader };
-        }
-        return runtime ? { contents: source, loader } : undefined;
-      });
+      if (!runtime) {
+        build.onEnd?.(() => resetTtscTransformCache(cache));
+      }
+      build.onLoad(
+        { filter: bunTypeScriptTransformSourcePattern },
+        async (args) => {
+          if (!runtime && ownsInMemoryFile(args.path)) {
+            return undefined;
+          }
+          if (!isTransformTarget(args.path)) {
+            if (!runtime) return undefined;
+            return {
+              contents: await fs.readFile(args.path, "utf8"),
+              loader: bunLoaderFor(args.path),
+            };
+          }
+          const loader = bunLoaderFor(args.path);
+          const transformOptions = getOptions();
+          const source = await fs.readFile(args.path, "utf8");
+          const result = await transformTtsc(
+            args.path,
+            source,
+            transformOptions,
+            undefined,
+            cache,
+            bunTransformHooks,
+          );
+          if (result !== undefined) {
+            return { contents: result.code, loader };
+          }
+          return runtime ? { contents: source, loader } : undefined;
+        },
+      );
     },
   };
 }
 
 /**
- * Pick the Bun loader for a matched file. `bunSourceFilePattern` is
- * `/\.[cm]?tsx?$/`, so a trailing `x` (`.tsx`/`.ctsx`/`.mtsx`) is JSX-flavored
- * TypeScript and everything else (`.ts`/`.cts`/`.mts`) is plain TypeScript.
+ * Pick the Bun loader recorded beside the matched extension in the shared
+ * source table. Reaching this function without a table entry would mean Bun
+ * invoked a callback whose registration filter did not match.
  */
 function bunLoaderFor(filePath: string): BunLoader {
-  return /x$/i.test(filePath) ? "tsx" : "ts";
+  const loader = typescriptTransformBunLoader(filePath);
+  if (loader === undefined) {
+    throw new Error(`Bun delivered an unsupported source path: ${filePath}`);
+  }
+  return loader;
 }
 
 /**

package/src/core/index.ts

@@ -5,30 +5,36 @@ import { createUnplugin } from "unplugin";
 
 import type { TtscUnpluginOptions } from "./options";
 import { resolveOptions } from "./options";
+import { typescriptTransformSourcePattern } from "./sourceExtensions";
 import {
   beginTtscTransformBuild,
+  captureWatchInputBaseline,
+  captureWatchInputFileBaseline,
   collectExternalInputHashes,
+  collectProjectInputHashSnapshot,
   collectProjectInputHashes,
   createTtscTransformCache,
   isDeclarationFile,
   isProjectWalkPath,
+  isWatchInputKeyBaseline,
   resetTtscTransformCache,
   stripQuery,
   transformTtsc,
+  watchInputEvidenceMatchesBaseline,
 } from "./transform";
 import { createViteServeMissingInputWatch } from "./viteServe";
 
 const name = "ttsc-unplugin";
 /**
- * Matches the TypeScript source extensions the ttsc transform handles: `.ts`,
- * `.tsx`, `.mts`, `.cts` and their `x` forms. JavaScript is deliberately not
- * among them, so a `.js` module reaches no adapter's transform.
+ * Matches the exact TypeScript source extensions the ttsc transform handles:
+ * `.ts`, `.tsx`, `.mts`, and `.cts`. JavaScript and invented extension forms
+ * such as `.mtsx` are deliberately excluded.
  *
  * Shared with the Bun adapter (`bun.ts`) and the standalone Turbopack loader
  * (`turbopack.ts`) through {@link isTransformTarget}, so the filter is defined
  * once and every adapter answers the same way.
  */
-export const sourceFilePattern = /\.[cm]?tsx?$/;
+export const sourceFilePattern = typescriptTransformSourcePattern;
 /** Matches any path segment that is a `node_modules` directory (cross-platform). */
 const nodeModulesPattern = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
 /**
@@ -72,6 +78,13 @@ const unpluginFactory: UnpluginFactory<
   // old containers cannot dispose a replacement's freshly initialized cache.
   let viteBuildOwners = new WeakSet<object>();
   let viteBuildLifecycles = 0;
+  // esbuild schedules one-shot onDispose callbacks after it settles the build
+  // Promise. Acquire ownership only at onStart: plugin setup runs before build
+  // option validation, and a validation failure has no onDispose callback with
+  // which to release a setup-time owner. Once a build has actually started, the
+  // count keeps an older delayed callback from disposing its active generation.
+  const esbuildOwners = new WeakSet<object>();
+  let esbuildLifecycles = 0;
 
   return {
     name,
@@ -128,15 +141,14 @@ const unpluginFactory: UnpluginFactory<
       // project per edit (samchon/ttsc#1301). The watching build hands its
       // teardown to `closeWatcher` below instead.
       buildEnd() {
-        missingInputs.dispose();
         if (viteBuildOwners.delete(this)) {
           viteBuildLifecycles -= 1;
         }
-        if (
-          viteBuildLifecycles === 0 &&
-          (viteCommand === "serve" || !viteBuildWatching)
-        ) {
-          resetTtscTransformCache(transformCache);
+        if (viteBuildLifecycles === 0) {
+          missingInputs.dispose();
+          if (viteCommand === "serve" || !viteBuildWatching) {
+            resetTtscTransformCache(transformCache);
+          }
         }
       },
       // The watching build's real teardown, and the only hook in a
@@ -156,6 +168,7 @@ const unpluginFactory: UnpluginFactory<
       closeWatcher() {
         viteBuildOwners = new WeakSet<object>();
         viteBuildLifecycles = 0;
+        missingInputs.dispose();
         resetTtscTransformCache(transformCache);
       },
     },
@@ -195,6 +208,39 @@ const unpluginFactory: UnpluginFactory<
       },
     },
 
+    // These hosts map a top-level buildEnd to a per-compilation hook, so use
+    // their true compiler or context teardown instead. The custom callbacks
+    // are installed by unplugin alongside its ordinary transform wiring.
+    webpack(compiler) {
+      compiler.hooks.shutdown.tap(name, () => {
+        resetTtscTransformCache(transformCache);
+      });
+    },
+    rspack(compiler) {
+      compiler.hooks.shutdown.tap(name, () => {
+        resetTtscTransformCache(transformCache);
+      });
+    },
+    esbuild: {
+      setup(build) {
+        build.onStart(() => {
+          if (!esbuildOwners.has(build)) {
+            esbuildOwners.add(build);
+            esbuildLifecycles += 1;
+          }
+        });
+        build.onDispose(() => {
+          if (!esbuildOwners.delete(build)) {
+            return;
+          }
+          esbuildLifecycles -= 1;
+          if (esbuildLifecycles === 0) {
+            resetTtscTransformCache(transformCache);
+          }
+        });
+      },
+    },
+
     buildStart() {
       if (viteCommand !== undefined && !viteBuildOwners.has(this as object)) {
         viteBuildOwners.add(this as object);
@@ -242,22 +288,45 @@ const unpluginFactory: UnpluginFactory<
         // invalidate this module in watch mode and persistent caches;
         // bundlers erase type-only imports from their own module graph and
         // would otherwise serve stale generated code. Under Vite serve a
-        // missing input must not enter `addWatchFile`: import-analysis
-        // resolves added imports and 500s on a path that is absent by design
-        // (a superseding resolution candidate, a not-yet-generated
-        // dependency), so those are watched on the filesystem instead and
-        // invalidate this module when created.
+        // resolver input that is not proven to be a file must not enter
+        // `addWatchFile`: import-analysis resolves added imports and 500s on
+        // missing paths and directories, so those are watched against their
+        // compiler predicates instead and invalidate this module when the
+        // observation changes.
         addWatchFile: (watched, evidence) => {
           if (viteCommand === "serve" && missingInputs.serving()) {
+            const observation =
+              evidence?.state?.codec === "predicates"
+                ? evidence.state.observation
+                : undefined;
+            const unsafePredicate =
+              observation !== undefined &&
+              observation.fileExists !== true &&
+              observation.stat !== "file" &&
+              observation.readFile?.ok !== true
+                ? observation
+                : undefined;
+            if (unsafePredicate !== undefined) {
+              missingInputs.watch(watched, path.resolve(file), unsafePredicate);
+              return;
+            }
             // Trust the generation's recorded existence when it supplied one:
             // every cache hit revalidates it, and probing each input again
             // costs one `existsSync` per input per delivered module.
-            const missing = evidence?.missing ?? !fs.existsSync(watched);
-            if (missing) {
+            const unavailable =
+              evidence?.unavailable ??
+              (evidence === undefined
+                ? !fs.existsSync(watched)
+                  ? "missing"
+                  : undefined
+                : evidence.missing
+                  ? "missing"
+                  : undefined);
+            if (unavailable !== undefined) {
               missingInputs.watch(
                 watched,
                 path.resolve(file),
-                evidence?.identity,
+                unavailable === "not-file" ? "file" : "exists",
               );
               return;
             }
@@ -298,26 +367,52 @@ export type {
   TtscUnpluginOptions,
 } from "./options";
 export type {
+  TtscProjectDiscoveryFilesystem,
+  TtscProjectTreeDiscoveryFilesystem,
+  TtscProjectTsconfigCandidate,
+  TtscProjectTsconfigDiscovery,
+} from "./projectDiscovery";
+export type {
+  TtscProjectInputHashSnapshot,
   TtscTransformFilesystemOperations,
   TtscTransformHooks,
+  TtscWatchInput,
+  TtscWatchInputBaseline,
   TtscWatchInputEvidence,
+  TtscWatchInputFileBaseline,
+  TtscWatchInputKeyBaseline,
+  TtscWatchInputState,
 } from "./transform";
-export type { ITtscProjectMembershipPolicy } from "./tsconfigPaths";
+export type {
+  ITsconfigSourceSnapshotEntry,
+  ITtscProjectMembershipPolicy,
+} from "./tsconfigPaths";
 export {
   mergeMembershipPolicyOverlay,
   readProjectMembershipPolicy,
+  readTsconfigSourceSnapshot,
 } from "./tsconfigPaths";
 export {
   beginTtscTransformBuild,
+  captureWatchInputBaseline,
+  captureWatchInputFileBaseline,
   collectExternalInputHashes,
+  collectProjectInputHashSnapshot,
   collectProjectInputHashes,
   createTtscTransformCache,
   isProjectWalkPath,
+  isWatchInputKeyBaseline,
   resetTtscTransformCache,
   resolveOptions,
   transformTtsc,
   unplugin,
+  watchInputEvidenceMatchesBaseline,
 };
+export {
+  discoverNearestProjectTsconfig,
+  findNearestProjectTsconfig,
+  findProjectTsconfigs,
+} from "./projectDiscovery";
 
 export default unplugin;