@ttsc/unplugin 0.20.0 → 0.21.0

package/src/bun.ts

@@ -1,10 +1,22 @@
 import fs from "node:fs/promises";
-import type { UnpluginContextMeta } from "unplugin";
 
-import { unplugin } from "./api";
-import { sourceFilePattern } from "./core/index";
+import {
+  beginTtscTransformBuild,
+  createTtscTransformCache,
+  isTransformTarget,
+  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?$/;
+
 /**
  * Minimal subset of the Bun plugin API consumed by this adapter.
  *
@@ -38,7 +50,7 @@ export type TtscBunOptions =
   | (() => TtscUnpluginOptions | undefined);
 
 /**
- * Transform context handed to the raw unplugin transform under Bun.
+ * Transform hooks handed to the shared transform under Bun.
  *
  * The shared transform calls `addWatchFile` once per plugin-reported dependency
  * so type-only inputs can enter a bundler's watch graph. Bun's bundler and
@@ -49,7 +61,7 @@ export type TtscBunOptions =
  * `this.addWatchFile` `undefined`, so any plugin reporting dependencies threw
  * `TypeError: this.addWatchFile is not a function`.
  */
-const bunTransformContext = {
+const bunTransformHooks = {
   addWatchFile(): void {},
 };
 
@@ -63,91 +75,159 @@ function resolveBunOptions(
 /**
  * Minimal subset of the Bun `BuildConfig` plugin build object.
  *
- * Only the `onLoad` hook is used; other hooks are not needed for a
- * source-to-source transform.
+ * `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.
  */
 export interface BunLikeBuild {
+  /**
+   * Build configuration exposed unchanged by Bun's bundler plugin builder.
+   *
+   * Runtime plugin builders do not supply `files`. Bun's bundler accepts an
+   * in-memory file map whose values deliberately remain `unknown` here because
+   * this adapter only needs to preserve ownership, not consume their contents.
+   */
+  config?: {
+    files?: Readonly<Record<string, unknown>>;
+  };
+  /**
+   * Register a callback for the start of a bundler build.
+   *
+   * Optional because `Bun.plugin()` runtime builders do not expose this hook.
+   */
+  onStart?(callback: () => void | Promise<void>): void;
   /**
    * Register a loader callback for files matching `filter`.
    *
-   * The callback receives the absolute file path and must return the
-   * transformed file contents plus the `loader` Bun should apply next. The
-   * `loader` matters most for the runtime path (`Bun.plugin`), where Bun must
-   * be told the returned contents are still TypeScript so it keeps transpiling
-   * them before execution.
+   * The callback receives the file path and must return the transformed file
+   * contents plus the `loader` Bun should apply next. Configured in-memory
+   * files retain relative key spellings; ordinary disk files are normally
+   * absolute. The `loader` matters most for the runtime path (`Bun.plugin`),
+   * where Bun must be told the returned contents are still TypeScript so it
+   * keeps transpiling them before execution.
    */
   onLoad(
     options: { filter: RegExp },
     loader: (args: {
       path: string;
-    }) => Promise<{ contents: string; loader: BunLoader }>,
+    }) => Promise<{ contents: string; loader: BunLoader } | undefined>,
   ): void;
 }
 
 /**
  * Create a ttsc plugin for Bun's bundler AND runtime.
  *
- * Bun does not implement the unplugin protocol, so this adapter instantiates
- * the raw unplugin transform and wires it to Bun's `onLoad` hook manually. The
- * adapter reads each matching file from disk and forwards the content to the
- * ttsc transform; if the transform returns no changes the original source is
- * passed through unchanged.
+ * Bun does not implement the unplugin protocol, so this adapter wires the
+ * shared ttsc transform core to Bun's `onLoad` hook directly. It reads each
+ * included file from disk and forwards the content to the transform. Under
+ * `Bun.build`, excluded files and no-op transforms return `undefined` so the
+ * next loader retains ownership. Entries supplied through `BuildConfig.files`
+ * also stay with Bun's in-memory loader: they are not filesystem project inputs
+ * and reading the same path from disk would either fail or silently replace the
+ * configured contents. The runtime `Bun.plugin()` API rejects an undefined
+ * `onLoad` result, so that path explicitly returns the original source and
+ * loader instead.
  *
  * The same object works for `Bun.build({ plugins: [ttsc()] })` (bundler) and
  * for `Bun.plugin(ttsc())` / a `bunfig.toml` preload (runtime) — see
  * `bun-register`. Every result carries an explicit `loader` so Bun keeps
- * transpiling the emitted TypeScript at runtime; `sourceFilePattern` only
- * matches TypeScript, so the loader is always `ts`/`tsx`.
+ * transpiling the emitted TypeScript at runtime; `bunSourceFilePattern` only
+ * matches TypeScript, so the loader is always `ts`/`tsx`. A runtime plugin
+ * instance is one immutable load session, like Bun's own module cache; restart
+ * the process after changing compiler inputs.
  */
 export default function bun(options?: TtscBunOptions): BunLikePlugin {
   return {
     name: "ttsc-unplugin",
     setup(build) {
-      // Build the raw transform lazily on first load rather than in `setup`.
-      // Bun runs `setup` synchronously when the plugin is registered, so a
-      // runtime registration (bun-register) that resolves its effective options
-      // through a provider must defer that resolution until after any explicit
-      // `register(options)` call in the same tick. Deferring also keeps a single
-      // transform (and its project cache) shared across every loaded module.
-      let raw: ReturnType<typeof unplugin.raw> | undefined;
-      build.onLoad({ filter: sourceFilePattern }, async (args) => {
-        raw ??= unplugin.raw(
-          resolveBunOptions(options),
-          {} as UnpluginContextMeta,
-        );
+      // 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.
+      let resolved: ReturnType<typeof resolveOptions> | undefined;
+      const getOptions = () =>
+        (resolved ??= resolveOptions(resolveBunOptions(options)));
+      const cache = createTtscTransformCache();
+      const runtime = build.onStart === undefined;
+      const ownsInMemoryFile = createBunInMemoryFileMatcher(build);
+      // Bun.plugin() has no onStart callback, but one setup invocation belongs
+      // to exactly one runtime process and module-loading session. Mark that
+      // session up front so first delivery of every emitted project module is
+      // constant-time instead of re-reading the whole project. Bun.build()
+      // immediately starts the same initial scope again through onStart and
+      // 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 =
-          typeof raw.transform === "function"
-            ? await raw.transform.call(
-                bunTransformContext as never,
-                source,
-                args.path,
-              )
-            : undefined;
-        // Unpack both shorthand string and object result shapes.
-        if (typeof result === "string") {
-          return { contents: result, loader };
-        }
-        if (
-          typeof result === "object" &&
-          result !== null &&
-          "code" in result &&
-          typeof result.code === "string"
-        ) {
+        const result = await transformTtsc(
+          args.path,
+          source,
+          getOptions(),
+          undefined,
+          cache,
+          bunTransformHooks,
+        );
+        if (result !== undefined) {
           return { contents: result.code, loader };
         }
-        return { contents: source, loader };
+        return runtime ? { contents: source, loader } : undefined;
       });
     },
   };
 }
 
 /**
- * Pick the Bun loader for a matched file. `sourceFilePattern` is
+ * 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.
  */
 function bunLoaderFor(filePath: string): BunLoader {
   return /x$/i.test(filePath) ? "tsx" : "ts";
 }
+
+/**
+ * Create a stable ownership matcher for Bun's `BuildConfig.files` map.
+ *
+ * Bun preserves relative `files` keys in the corresponding `onLoad` path.
+ * Preserve relative versus absolute spelling and dot segments exactly. Windows
+ * normalizes separators and drive-letter case, but not component case. No path
+ * is resolved against cwd, so `process.chdir()` cannot change ownership.
+ */
+function createBunInMemoryFileMatcher(
+  build: BunLikeBuild,
+): (file: string) => boolean {
+  const files = build.config?.files;
+  if (files === undefined) return () => false;
+  const identities = new Set(Object.keys(files).map(bunPathIdentityKey));
+  return (file) => identities.has(bunPathIdentityKey(file));
+}
+
+/**
+ * Normalize the path forms Bun equates for its in-memory file map.
+ *
+ * Bun normalizes Windows separators and drive-letter case, but preserves path
+ * component case, relative versus absolute spelling, and dot segments. A
+ * filesystem identity key is broader and would suppress real disk transforms.
+ */
+function bunPathIdentityKey(file: string): string {
+  if (process.platform !== "win32") return file;
+  return file
+    .replace(/\\/g, "/")
+    .replace(
+      /^([a-z]):/i,
+      (_match, drive: string) => `${drive.toLowerCase()}:`,
+    );
+}

package/src/core/index.ts

@@ -1,17 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
 import type { UnpluginFactory, UnpluginInstance } from "unplugin";
 import { createUnplugin } from "unplugin";
 
 import type { TtscUnpluginOptions } from "./options";
 import { resolveOptions } from "./options";
 import {
+  beginTtscTransformBuild,
   collectExternalInputHashes,
   collectProjectInputHashes,
   createTtscTransformCache,
   isDeclarationFile,
   isProjectWalkPath,
+  resetTtscTransformCache,
   stripQuery,
   transformTtsc,
 } from "./transform";
+import { createViteServeMissingInputWatch } from "./viteServe";
 
 const name = "ttsc-unplugin";
 /**
@@ -34,9 +39,9 @@ const virtualModulePattern = /\0/;
  *
  * The factory resolves raw options once, creates a per-build transform cache,
  * and captures Vite alias configuration via the `vite.configResolved` hook so
- * that path aliases are forwarded to the generated tsconfig overlay. The cache
- * is cleared on every `buildStart` to avoid stale results across watch-mode
- * rebuilds.
+ * that path aliases are forwarded to the generated tsconfig overlay. Real build
+ * lifecycles use a per-build cache; Vite's development server keeps persistent
+ * validation because its one `buildStart` spans later HMR edits.
  */
 const unpluginFactory: UnpluginFactory<
   TtscUnpluginOptions | undefined,
@@ -44,7 +49,9 @@ const unpluginFactory: UnpluginFactory<
 > = (rawOptions = {}) => {
   const options = resolveOptions(rawOptions);
   const transformCache = createTtscTransformCache();
+  const missingInputs = createViteServeMissingInputWatch();
   let aliases: unknown;
+  let viteCommand: string | undefined;
 
   return {
     name,
@@ -53,11 +60,34 @@ const unpluginFactory: UnpluginFactory<
     vite: {
       configResolved(config) {
         aliases = config.resolve.alias;
+        // Re-read per config resolution: a plugin instance reused across a
+        // serve and a later build must stop routing missing inputs to the
+        // serve-time poll, even though the closed server stays attached
+        // (see the dispose note in viteServe.ts).
+        viteCommand = config.command;
+      },
+      // Vite serve funnels every transform-context `addWatchFile()` into the
+      // module's added-import graph (`_addedImports`), which import-analysis
+      // resolves like real imports. Capture the dev server so the transform
+      // hook can route watch inputs that do not exist yet — superseding
+      // resolution candidates above all — around that graph and still
+      // invalidate their importers when the path is created.
+      configureServer(server) {
+        missingInputs.attach(server);
+      },
+      // Vite calls buildEnd when the dev server (or build) closes; drop every
+      // poller so a stopped server leaks no watch state.
+      buildEnd() {
+        missingInputs.dispose();
       },
     },
 
     buildStart() {
-      transformCache.clear();
+      if (viteCommand === "serve") {
+        resetTtscTransformCache(transformCache);
+      } else {
+        beginTtscTransformBuild(transformCache);
+      }
     },
 
     transformInclude(id) {
@@ -75,8 +105,23 @@ const unpluginFactory: UnpluginFactory<
         // unioned with the host-owned reference graph) so type-only inputs
         // 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.
-        addWatchFile: (watched) => this.addWatchFile(watched),
+        // 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.
+        addWatchFile: (watched) => {
+          if (
+            viteCommand === "serve" &&
+            missingInputs.serving() &&
+            !fs.existsSync(watched)
+          ) {
+            missingInputs.watch(watched, path.resolve(file));
+            return;
+          }
+          this.addWatchFile(watched);
+        },
         // A module the plugin declared volatile depends on non-file inputs,
         // which no file-dependency snapshot can represent; mark it
         // uncacheable where the bundler exposes that control.
@@ -103,10 +148,12 @@ export type {
 } from "./options";
 export type { TtscTransformHooks } from "./transform";
 export {
+  beginTtscTransformBuild,
   collectExternalInputHashes,
   collectProjectInputHashes,
   createTtscTransformCache,
   isProjectWalkPath,
+  resetTtscTransformCache,
   resolveOptions,
   transformTtsc,
   unplugin,
@@ -121,7 +168,7 @@ export default unplugin;
  * Excluded ids: virtual modules (NUL prefix), `.d.ts` declaration files, and
  * anything inside `node_modules`.
  */
-function isTransformTarget(id: string): boolean {
+export function isTransformTarget(id: string): boolean {
   return (
     sourceFilePattern.test(id) &&
     !virtualModulePattern.test(id) &&