@ttsc/unplugin 0.30.4 → 0.31.0

package/src/core/discovery/findNearestProjectTsconfig.ts

@@ -0,0 +1,45 @@
+import { HOST_PROJECT_DISCOVERY_FILESYSTEM } from "./HOST_PROJECT_DISCOVERY_FILESYSTEM";
+import type { TtscProjectDiscoveryFilesystem } from "./TtscProjectDiscoveryFilesystem";
+import { findNearestProjectTsconfigImpl } from "./findNearestProjectTsconfigImpl";
+
+/**
+ * Find the nearest ancestor `tsconfig.json` that is proven to be a file.
+ *
+ * A directory, broken link, permission failure, or any other unprovable
+ * candidate cannot terminate the walk. `stat` deliberately follows links, so a
+ * link to a regular file retains its lexical config spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The delegated walk chooses the first ancestor candidate whose stat proves
+ *   a regular file; non-file candidates cannot become the implicit project.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This entry point exposes selection without observations while sharing the
+ *   same implementation with the evidence-retaining discovery entry point.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The shared walk uses the observed platform's path API and link-following
+ *   stat. This entry adds no host-OS case or separator inference.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   An injected filesystem is an explicit observation boundary; selection
+ *   does not patch global stat or branch on fixture identity.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native documentation distinguishes file-kind proof, link following and
+ *   lexical result spelling in separate purpose and boundary paragraphs.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   The delegated parent walk visits D candidate levels, paying native stat
+ *   plus path resolution/join/dirname text work at each reached prefix. It
+ *   retains no candidate history in this selection-only entry point.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function findNearestProjectTsconfig(
+  startDirectory: string,
+  filesystem: TtscProjectDiscoveryFilesystem = HOST_PROJECT_DISCOVERY_FILESYSTEM,
+): string | undefined {
+  return findNearestProjectTsconfigImpl(startDirectory, filesystem);
+}

package/src/core/discovery/findNearestProjectTsconfigImpl.ts

@@ -0,0 +1,72 @@
+import path from "node:path";
+
+import type { TtscProjectDiscoveryFilesystem } from "./TtscProjectDiscoveryFilesystem";
+import type { TtscProjectTsconfigCandidate } from "./TtscProjectTsconfigCandidate";
+
+/**
+ * Walk ancestor directories, optionally retaining every consulted predicate.
+ *
+ * Failed stat observations cannot select a config. Reaching the volume root
+ * without a regular candidate returns undefined.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Every iteration probes one ancestor's tsconfig.json; dirname moves toward
+ *   a fixed root, and the first proven regular file wins.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One loop owns candidate choice and optional recording, so both discovery
+ *   entry points share absence and ordering semantics.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Explicit platform selects win32 or posix path syntax; otherwise Node uses
+ *   host-native paths. The observed stat capability decides regular-file kind;
+ *   dirname terminates at that native root without shell invocation.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Failed observations remain false predicates, not fabricated config paths;
+ *   the filesystem parameter supplies native observations without patching.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   JSDoc explains optional recording, failure handling and root termination;
+ *   separate paragraphs give the purpose and the nonobvious boundary.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Walks D parent levels with one stat each and stops at the native root;
+ *   resolution/join/dirname cost follows each reached prefix's text. Optional
+ *   recording allocates D candidate pairs/path strings, not a constant-size
+ *   result; no directory enumeration or content read occurs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function findNearestProjectTsconfigImpl(
+  startDirectory: string,
+  filesystem: TtscProjectDiscoveryFilesystem,
+  candidates?: TtscProjectTsconfigCandidate[],
+): string | undefined {
+  const paths =
+    filesystem.platform === undefined
+      ? path
+      : filesystem.platform === "win32"
+        ? path.win32
+        : path.posix;
+  let current = paths.resolve(startDirectory);
+  while (true) {
+    const candidate = paths.join(current, "tsconfig.json");
+    let fileExists = false;
+    try {
+      fileExists = filesystem.stat(candidate).isFile();
+    } catch {
+      // An implicit candidate is selectable only when its file kind is proven.
+    }
+    candidates?.push({ file: candidate, fileExists });
+    if (fileExists) {
+      return candidate;
+    }
+    const parent = paths.dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}

package/src/core/discovery/findProjectTsconfigs.ts

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { TtscProjectTreeDiscoveryFilesystem } from "./TtscProjectTreeDiscoveryFilesystem";
+import { canonicalProjectPath } from "./canonicalProjectPath";
+import { isIgnoredProjectDirectory } from "./isIgnoredProjectDirectory";
+import { projectDirectoryIdentity } from "./projectDirectoryIdentity";
+
+const HOST_PROJECT_TREE_DISCOVERY_FILESYSTEM: TtscProjectTreeDiscoveryFilesystem =
+  Object.freeze({
+    readdir: (location: string) =>
+      fs.readdirSync(location, { withFileTypes: true }),
+    realpath: fs.realpathSync.native,
+    stat: fs.statSync,
+  });
+
+/**
+ * Find every regular `tsconfig.json` below one project root.
+ *
+ * The traversal retains lexical project spellings while following child
+ * directory links and junctions. A physical ancestor set cuts cycles without
+ * collapsing two independent aliases of the same project. An incomplete
+ * traversal is reported rather than returned as a complete project map, so a
+ * cache-key caller can refuse reuse.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Each lexical directory contributes its config predicate. Physical ancestor
+ *   identities cut cycles within a branch while independent link aliases keep
+ *   their lexical projects. Unproven linked ancestry marks traversal incomplete.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Entry and exit frames on one stack maintain active physical ancestry.
+ *   Identity and ignored-directory helpers own their policies; traversal owns
+ *   completeness and lexical output.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The filesystem view supplies native stat, directory entries and realpath.
+ *   Links and junctions use observed target kinds and physical spelling;
+ *   unresolved link identity marks incompleteness instead of guessing OS case.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Only package, VCS and host-cache directories are intentionally omitted;
+ *   unreadable state cannot masquerade as a complete empty project map.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Documentation explains lexical aliases, physical cycle guards and the
+ *   incomplete result, with reasons separated from the callback contract.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned map transfers to the caller. Pending frames and active
+ *   ancestry are temporary computation state, with no retained native handle.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Each reached lexical directory is enumerated once; a shared ancestor Set
+ *   gives constant-time cycle checks without copying ancestry at every child.
+ *   Entry/exit frames keep only active ancestry, and final sorting costs
+ *   O(c log c) text comparisons for c candidates and a separate file sort.
+ *   Native directory listings, entry-name joins, candidate stat and optional
+ *   realpath/link-target stat contribute their entry/path/native costs. Pending
+ *   sibling frames and returned arrays grow with reached lexical populations;
+ *   aliases may enumerate one physical subtree at multiple lexical addresses.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This traversal observes one current project tree; cross-call reuse and
+ *   proof of continued validity belong to its cache-key caller.
+ */
+export function findProjectTsconfigs(
+  root: string,
+  filesystem: TtscProjectTreeDiscoveryFilesystem = HOST_PROJECT_TREE_DISCOVERY_FILESYSTEM,
+): { candidates: string[]; complete: boolean; files: string[] } {
+  const paths =
+    filesystem.platform === undefined
+      ? path
+      : filesystem.platform === "win32"
+        ? path.win32
+        : path.posix;
+  type PendingDirectory = {
+    directory: string;
+    exiting?: boolean;
+    identity: string;
+    physicalAncestorsComplete: boolean;
+  };
+  const rootDirectory = paths.resolve(root);
+  const rootIdentity = projectDirectoryIdentity(
+    rootDirectory,
+    filesystem,
+    paths,
+  );
+  const pending: PendingDirectory[] = [
+    {
+      directory: rootDirectory,
+      identity:
+        rootIdentity ??
+        canonicalProjectPath(rootDirectory, filesystem.platform),
+      physicalAncestorsComplete:
+        filesystem.realpath === undefined || rootIdentity !== undefined,
+    },
+  ];
+  const candidates: string[] = [];
+  const files: string[] = [];
+  const ancestors = new Set<string>();
+  let complete =
+    filesystem.realpath === undefined || rootIdentity !== undefined;
+  while (pending.length !== 0) {
+    const current = pending.pop()!;
+    if (current.exiting) {
+      ancestors.delete(current.identity);
+      continue;
+    }
+    if (ancestors.has(current.identity)) continue;
+    ancestors.add(current.identity);
+    pending.push({ ...current, exiting: true });
+    const directory = current.directory;
+    let entries: readonly (Pick<fs.Dirent, "isDirectory" | "name"> &
+      Partial<Pick<fs.Dirent, "isSymbolicLink">>)[];
+    try {
+      entries = filesystem.readdir(directory);
+    } catch {
+      complete = false;
+      continue;
+    }
+    for (const entry of entries) {
+      if (isIgnoredProjectDirectory(entry.name)) continue;
+      const child = paths.join(directory, entry.name);
+      const linked = entry.isSymbolicLink?.() === true;
+      let directoryEntry = entry.isDirectory();
+      if (!directoryEntry && linked) {
+        try {
+          directoryEntry = filesystem.stat(child).isDirectory?.() === true;
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException).code;
+          if (code !== "ENOENT" && code !== "ENOTDIR") complete = false;
+          continue;
+        }
+      }
+      if (!directoryEntry) continue;
+      const identity = projectDirectoryIdentity(child, filesystem, paths);
+      const physicalAncestorsComplete =
+        current.physicalAncestorsComplete &&
+        (filesystem.realpath === undefined || identity !== undefined);
+      if (filesystem.realpath !== undefined && identity === undefined) {
+        complete = false;
+      }
+      if (linked && (identity === undefined || !physicalAncestorsComplete)) {
+        complete = false;
+        continue;
+      }
+      const stableIdentity =
+        identity ?? canonicalProjectPath(child, filesystem.platform);
+      if (ancestors.has(stableIdentity)) continue;
+      pending.push({
+        directory: child,
+        identity: stableIdentity,
+        physicalAncestorsComplete,
+      });
+    }
+    const candidate = paths.join(directory, "tsconfig.json");
+    candidates.push(candidate);
+    try {
+      if (filesystem.stat(candidate).isFile()) {
+        files.push(candidate);
+      }
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") {
+        complete = false;
+      }
+    }
+  }
+  candidates.sort();
+  files.sort();
+  return { candidates, complete, files };
+}

package/src/core/discovery/isIgnoredProjectDirectory.ts

@@ -0,0 +1,33 @@
+/**
+ * Keep the dependency, VCS and ttsc plugin stores outside project discovery.
+ *
+ * All other names are governed by the selected project rather than guessed
+ * directory conventions.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Exact equality identifies the three stores outside this source-discovery
+ *   contract; ordinary output and hidden directories remain policy-owned.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One predicate owns the traversal's unconditional directory omissions.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   These store names express traversal ownership, not expected fixture answers
+ *   or an expanding list of guessed consumer output directories.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The comment names the omitted stores and explains why other directory names
+ *   remain configuration decisions instead of repeating a boolean expression.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Compares a bare directory name with three literals; it reads no filesystem and parses no path.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   Three exact fixed-length literals define the product-owned omission set;
+ *   no input collection/traversal or growing matching strategy is chosen.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function isIgnoredProjectDirectory(name: string): boolean {
+  // These are discovery-owned stores. Other names remain project-policy choices.
+  return name === ".git" || name === ".ttsc" || name === "node_modules";
+}

package/src/core/discovery/projectDirectoryIdentity.ts

@@ -0,0 +1,59 @@
+import type path from "node:path";
+
+import type { TtscProjectTreeDiscoveryFilesystem } from "./TtscProjectTreeDiscoveryFilesystem";
+import { canonicalProjectPath } from "./canonicalProjectPath";
+
+/**
+ * Resolve the physical identity of one directory reached by project-tree
+ * discovery, or `undefined` when the filesystem view cannot resolve it.
+ *
+ * The identity is what makes linked traversal cycle-safe: a junction or symlink
+ * back to an ancestor has the same physical identity as that ancestor. An
+ * unresolvable identity is reported as absent rather than guessed, so the
+ * caller can mark the traversal incomplete instead of claiming a full project
+ * map.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The filesystem's realpath supplies physical spelling for the branch cycle
+ *   guard; unresolvable identity returns undefined instead of a guessed target.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This operation separates physical observation from lexical traversal and
+ *   delegates volume-root key formatting to canonicalProjectPath.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The supplied realpath operation observes actual directory identity under
+ *   its filesystem view. The selected path API normalizes native root syntax
+ *   without folding child names by OS default.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No native name case is inferred from the OS and missing identity does not
+ *   authorize traversal through an unproven link cycle.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose explains the cycle guard and absence consequence, giving the
+ *   reason for the undefined result without claiming successful enumeration.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Available identity pays supplied realpath component/link resolution, native
+ *   selected-grammar path resolution and volume-root formatting/string work.
+ *   Absent capability returns immediately; no subtree or content is enumerated.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function projectDirectoryIdentity(
+  directory: string,
+  filesystem: TtscProjectTreeDiscoveryFilesystem,
+  paths: typeof path.posix | typeof path.win32,
+): string | undefined {
+  if (filesystem.realpath === undefined) return undefined;
+  try {
+    return canonicalProjectPath(
+      paths.resolve(filesystem.realpath(directory)),
+      filesystem.platform,
+    );
+  } catch {
+    return undefined;
+  }
+}

package/src/core/esbuild/createEsbuildBuildLifecycle.ts

@@ -0,0 +1,60 @@
+import type { TtscTransformCache } from "../transform/cache/TtscTransformCache";
+import { beginTtscTransformBuild } from "../transform/cache/beginTtscTransformBuild";
+import { resetTtscTransformCache } from "../transform/cache/resetTtscTransformCache";
+
+/**
+ * Own the started esbuild contexts sharing one transform cache.
+ *
+ * Every start opens a delivery pass, including repeated starts of one context.
+ * Only a started identity can release ownership; the last disposal resets the
+ * cache before returning true to let the caller clear and close its bridge.
+ * Bridge acquisition, sequence tokens and asynchronous close remain
+ * caller-owned.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Weak owner identities count each started context once. Unknown disposal
+ *   cannot reset another context's cache; the last known owner resets it.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One weak set and count own registration and final release. The returned
+ *   boolean separates cache release from the adapter's bridge cleanup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Uses the actual cache pass and reset operations without changing its entries,
+ *   substituting a compiler, or manufacturing notification authority.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose distinguishes repeated pass starts, counted ownership and
+ *   caller-owned bridge effects, following the documentation guidance.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Context identities and the borrowed cache are opaque; this operation
+ *   chooses no native path, case policy or watch backend.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Weak-set membership avoids scanning contexts. Every start delegates a cache
+ *   pass and final disposal delegates reset; their work follows retained cache
+ *   entries and resource owners, rather than being constant at this wrapper.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Overlapping started contexts retain the same cache while each start still
+ *   opens its own pass. Input validity remains the cache consumer's responsibility.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   The controller borrows the cache and weakly retains context identities.
+ *   Final known disposal resets cache resources; bridge close and cancellation
+ *   of ongoing compilation are not guaranteed by this ownership counter.
+ */
+export function createEsbuildBuildLifecycle(cache: TtscTransformCache) {
+  const owners = new WeakSet<object>();
+  let lifecycles = 0;
+  return {
+    start(owner: object): void {
+      if (!owners.has(owner)) {
+        owners.add(owner);
+        lifecycles += 1;
+      }
+      beginTtscTransformBuild(cache);
+    },
+    dispose(owner: object): boolean {
+      if (!owners.delete(owner)) return false;
+      lifecycles -= 1;
+      if (lifecycles !== 0) return false;
+      resetTtscTransformCache(cache);
+      return true;
+    },
+  };
+}

package/src/core/esbuild/createEsbuildOptions.ts

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { UnpluginOptions } from "unplugin";
+
+import type { HostWatchBridge } from "../bridge/HostWatchBridge";
+import { fallbackToolDirectory } from "../bridge/fallbackToolDirectory";
+import { hostToolDirectory } from "../bridge/hostToolDirectory";
+import { openHostWatchBridge } from "../bridge/openHostWatchBridge";
+import { registerProjectRecord } from "../bridge/registerProjectRecord";
+import type { ResolvedTtscUnpluginOptions } from "../options/ResolvedTtscUnpluginOptions";
+import { typescriptTransformSourcePattern } from "../source/typescriptTransformSourcePattern";
+import { createTtscTransformCache } from "../transform/cache/createTtscTransformCache";
+import { transformTtsc } from "../transform/transformTtsc";
+import { inlineSourceMap } from "../transform/utils/inlineSourceMap";
+import type { TtscProjectRegistration } from "../transform/watch/TtscProjectRegistration";
+import { createEsbuildBuildLifecycle } from "./createEsbuildBuildLifecycle";
+
+/**
+ * The esbuild adapter: its native loader owns the transform and the
+ * registration of the project's record, independent of unplugin's hook order.
+ *
+ * Esbuild watches each module and the project's record, which the bridge moves
+ * when an input changes. Esbuild keeps one watch state per path for a whole
+ * build, taken from the last loader result that named the path (evanw/esbuild
+ * internal/fs), which is why the compiler's inputs themselves were never a
+ * channel it could take: an edit landing after one module's loader returned and
+ * before another's did was the second module's baseline, and the first module's
+ * edit was masked, with no rebuild ever (samchon/ttsc#1463). The record is
+ * named by every module's result with one content, the generation's state, so
+ * no result masks another.
+ *
+ * Esbuild tells a plugin nothing about whether its context watches, so the
+ * bridge opens for a one-shot `build()` as well, and closes when the last
+ * context of this plugin is disposed, which `build()` reports at its end.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The native file loader returns source, parser/map and available project
+ *   record dependencies together; record-write failure follows the shared
+ *   reporting boundary rather than guaranteeing a record channel. Start opens
+ *   a delivery pass and the bridge's change
+ *   sequence, and each delivery writes the record of the generation it read;
+ *   error responses retain prior dependencies so failed builds can observe their
+ *   repair.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Setup owns lifecycle registration and loader responses; shared transform and
+ *   record helpers retain compilation, validation and observation responsibility.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The adapter uses esbuild's onLoad/watchFiles/onDispose API. Previous dependency
+ *   retention covers real failed loads rather than inventing a successful result.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain esbuild's baseline behavior and absent watch-mode
+ *   capability; lifecycle/error comments and tag separation follow documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Native resolution anchors absWorkingDir/cwd; Node reads delivered disk files.
+ *   Host-local or accepted user fallback records avoid temporary-path assumptions,
+ *   while the shared observer owns native watch and filesystem identity differences.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   A delivery reads S source bytes and indexes/copies its dependency set.
+ *   Delegated work includes current generation identity/validation/native compile
+ *   misses, record serialization/writes, watch registration and map encoding.
+ *   Previous maps follow M loaded file keys and their dependency populations;
+ *   path/error/message text and input proof bytes are not bounded by M alone.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Concurrent contexts of one plugin share its cache; build start opens a new
+ *   delivery pass that re-proves the retained generation, and transform validity
+ *   uses generation inputs. The shared pass token can advance when another
+ *   started context opens a pass; each loader captures its token before awaiting
+ *   disk/compile work. Owner identity prevents
+ *   a setup that never started from releasing another context's cache.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Active started contexts own cache/bridge retention. The last onDispose resets
+ *   the cache and initiates bridge close with rejection suppressed; the hook
+ *   does not await native cleanup or promise cancellation of running compiles.
+ *   Previous lists remain with host-owned setup closures, without a fixed entry
+ *   or byte cap. A setup that never started acquires no counted ownership and
+ *   its dispose cannot release another context's cache.
+ */
+export function createEsbuildOptions(
+  options: ResolvedTtscUnpluginOptions,
+  includes: (file: string) => boolean,
+): UnpluginOptions {
+  const cache = createTtscTransformCache();
+  const lifecycle = createEsbuildBuildLifecycle(cache);
+  let bridge: HostWatchBridge | undefined;
+  // The bridge's change sequence when the current pass opened, which every
+  // delivery of the pass is registered against (samchon/ttsc#1460).
+  let passStartedAt: number | undefined;
+  return {
+    name: "ttsc-unplugin",
+    esbuild: {
+      setup(build) {
+        const root = path.resolve(
+          build.initialOptions.absWorkingDir ?? process.cwd(),
+        );
+        // Setup can fail validation without receiving onDispose. Acquire only
+        // at onStart, and retain a generation while another owner is active.
+        build.onStart(() => {
+          lifecycle.start(build);
+          // No record is proven here: esbuild keeps no cache of a loader's
+          // result, so every build runs every module through the loader,
+          // and each delivery writes the record of the generation it read.
+          passStartedAt = bridge?.begin();
+        });
+        build.onDispose(() => {
+          if (!lifecycle.dispose(build)) return;
+          const open = bridge;
+          bridge = undefined;
+          passStartedAt = undefined;
+          open?.close().catch(() => undefined);
+        });
+        // The record each module's last result named, kept through a failed
+        // load so the repair is observed by the same context.
+        const previous = new Map<string, string[]>();
+        build.onLoad(
+          { filter: typescriptTransformSourcePattern, namespace: "file" },
+          async ({ path: file }) => {
+            if (!includes(file)) return;
+            const watchFiles = new Set<string>([file]);
+            const startedAt = (passStartedAt ??= (bridge ??=
+              openHostWatchBridge(root)).begin());
+            const register = (registration: TtscProjectRegistration) =>
+              registerProjectRecord({
+                addWatchFile: (input) => watchFiles.add(input),
+                bridge: { instance: bridge!, startedAt },
+                registration,
+              });
+            let contents: string;
+            let errors;
+            try {
+              const source = await fs.promises.readFile(file, "utf8");
+              const result = await transformTtsc(
+                file,
+                source,
+                options,
+                undefined,
+                cache,
+                {
+                  // esbuild's `path` is the file's own, its query held apart.
+                  exactPath: true,
+                  project: {
+                    register,
+                    toolDirectory: hostToolDirectory(root),
+                    // esbuild takes a record anywhere, and cannot say whether
+                    // it watches (samchon/ttsc#1480).
+                    ...fallbackRecordDirectory(root),
+                  },
+                },
+              );
+              contents =
+                result === undefined ? source : inlineSourceMap(result);
+            } catch (error) {
+              for (const input of previous.get(file) ?? [])
+                watchFiles.add(input);
+              // Returning errors with dependencies lets an initially failing
+              // build observe its repair; throwing discards those channels.
+              errors = [
+                {
+                  text: error instanceof Error ? error.message : String(error),
+                  detail: error,
+                },
+              ];
+              contents = "";
+            }
+            const dependencies = [...watchFiles];
+            previous.set(file, dependencies);
+            return {
+              contents,
+              errors,
+              loader: file.endsWith(".tsx") ? "tsx" : "ts",
+              resolveDir: path.dirname(file),
+              watchFiles: dependencies,
+            };
+          },
+        );
+      },
+    },
+  };
+}
+
+/** The fallback record directory of a root, spread into a project hook. */
+function fallbackRecordDirectory(root: string): {
+  fallbackToolDirectory?: string;
+} {
+  const fallback = fallbackToolDirectory(root);
+  return fallback === undefined ? {} : { fallbackToolDirectory: fallback };
+}