@ttsc/metro 0.30.4 → 0.31.1

package/src/index.ts

@@ -27,19 +27,22 @@
  *   module.exports = withTtsc(getDefaultConfig(__dirname));
  *   ```
  */
-import { readFileSync, realpathSync } from "node:fs";
+import { openTtscTransformSession } from "@ttsc/unplugin/api";
+import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createFilesystemPathIdentityContext } from "ttsc/path-identity";
 
+import type { TtscMetroOptions } from "./core/TtscMetroOptions";
 import { prepareSnapshot } from "./core/fingerprint";
-import type { TtscMetroOptions } from "./core/options";
 import { ENV_KEY, serializeOptions } from "./core/options";
+import { locateProjectUpstreamTransformer } from "./core/upstream";
 
 export type {
   ResolvedTtscMetroOptions,
   TtscMetroOptions,
-} from "./core/options";
+} from "./core/TtscMetroOptions";
 
 /**
  * Minimal structural type for a Metro config object, avoids a hard dependency
@@ -74,6 +77,54 @@ interface MetroConfigLike {
  * `.svg` to the auto-detected Expo default instead, with the build still
  * succeeding (samchon/ttsc#1321). An explicit `upstreamTransformer` option
  * still wins, since that is the caller saying it outright.
+ *
+ * The call also has side effects beyond the returned config, all before Metro
+ * forks its workers. It prepares the cache-key snapshot under
+ * `<projectRoot>/node_modules/.cache/ttsc-metro` (creating it, merging the
+ * previous workers' records into it under a lock, and sweeping stale files),
+ * and it opens the shared compile session whose path the workers inherit
+ * through the environment. A snapshot that cannot be prepared never fails the
+ * call: the run takes a private token that makes its cache key non-reusable.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Metro's supported babelTransformerPath boundary installs this adapter by
+ *   cloning the config. Node project resolution preserves an existing upstream
+ *   unless explicitly overridden, and realpath/package ownership filters
+ *   inherited self-selection; explicit upstream choices remain caller-owned.
+ *   Only the owned option/session environment channels are published before
+ *   workers start; foreign loaders and methods are not patched.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The entry point prepares run ownership and worker transport, then clones
+ *   the config's transformer field. Separate helpers own upstream inheritance
+ *   and module identity instead of repeating those policies in workers.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Decision values come from the documented inputs and product protocol
+ *   rather than expected test answers. No compensating path is introduced to
+ *   make a known example pass.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node paths, createRequire and fileURLToPath resolve native paths and module
+ *   URLs. The shared filesystem-identity resolver handles links and actual
+ *   directory case capabilities in the recursion guard, instead of folding
+ *   all names by OS. Worker options use JSON environment inheritance.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains config preservation, upstream precedence, JSON
+ *   worker transport and preparation side effects. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The compaction lock it takes is released in prepareSnapshot's finally block and the session store is owned by its opener; withTtsc retains no handle itself.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   Constant work per call besides the snapshot preparation that prepareSnapshot owns.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Runs once per Metro config load; the snapshot and compile session it opens are what the workers share.
  */
 export function withTtsc<T extends MetroConfigLike>(
   config: T,
@@ -81,8 +132,8 @@ export function withTtsc<T extends MetroConfigLike>(
 ): T {
   // Prepare the reference-graph snapshot backing the transformer's cache-key
   // fingerprint (see `core/fingerprint.ts`). This runs in the single Metro
-  // config process before any worker exists, so it is the race-free moment to
-  // mint the snapshot epoch and compact the previous run's worker files.
+  // config process before its workers exist. The snapshot owner serializes
+  // concurrent config processes while compacting the previous worker records.
   const snapshotRunId = prepareSnapshot(
     typeof config.projectRoot === "string" ? config.projectRoot : undefined,
   );
@@ -90,6 +141,9 @@ export function withTtsc<T extends MetroConfigLike>(
     inheritConfiguredTransformer(config, options),
     snapshotRunId,
   );
+  // The workers Metro forks next inherit the session, so the pool compiles
+  // each generation once between them (samchon/ttsc#1390).
+  openTtscTransformSession();
   return {
     ...config,
     transformer: {
@@ -116,13 +170,31 @@ function inheritConfiguredTransformer(
   config: MetroConfigLike,
   options: TtscMetroOptions,
 ): TtscMetroOptions {
-  const declared = config.transformer?.babelTransformerPath;
+  // An explicit option is the caller's module, so it resolves from the project
+  // as a declared `babelTransformerPath` does; an empty one asks for detection.
   if (
-    options.upstreamTransformer !== undefined ||
-    typeof declared !== "string" ||
-    declared.length === 0
+    options.upstreamTransformer !== undefined &&
+    options.upstreamTransformer.length !== 0
   ) {
-    return options;
+    return {
+      ...options,
+      upstreamTransformer: resolveFromProject(
+        options.upstreamTransformer,
+        config,
+      ),
+    };
+  }
+  const declared = config.transformer?.babelTransformerPath;
+  if (typeof declared !== "string" || declared.length === 0) {
+    // Automatic detection belongs here too: the candidates are the app's
+    // packages, and only this process knows the project to look in. Nothing
+    // found leaves the worker's own probe to report it.
+    const located = locateProjectUpstreamTransformer((specifier) =>
+      projectRequire(config).resolve(specifier),
+    );
+    return located === undefined
+      ? options
+      : { ...options, upstreamTransformer: located };
   }
   // Resolve before judging. Ownership is a property of the module, not of the
   // string, and every spelling has to become one absolute path before either
@@ -161,17 +233,22 @@ function inheritConfiguredTransformer(
  * somewhere less legible.
  */
 function resolveFromProject(declared: string, config: MetroConfigLike): string {
-  const base =
-    typeof config.projectRoot === "string" && config.projectRoot.length !== 0
-      ? config.projectRoot
-      : process.cwd();
   try {
-    return createRequire(join(resolve(base), "package.json")).resolve(declared);
+    return projectRequire(config).resolve(declared);
   } catch {
     return declared;
   }
 }
 
+/** A `require` rooted in the Metro project, the owner of its transformers. */
+function projectRequire(config: MetroConfigLike): NodeJS.Require {
+  const base =
+    typeof config.projectRoot === "string" && config.projectRoot.length !== 0
+      ? config.projectRoot
+      : process.cwd();
+  return createRequire(join(resolve(base), "package.json"));
+}
+
 /**
  * Whether a `babelTransformerPath` already points at a `@ttsc/metro`
  * transformer — this copy or any other.
@@ -209,21 +286,15 @@ function isOwnTransformer(declared: string): boolean {
 /**
  * Whether two paths name the same file on disk.
  *
- * Resolved through `realpath` so a symlinked install and its target compare
- * equal, and case-folded on Windows, where `D:\` and `d:\` and a differently
- * cased base name all address one file.
+ * The shared resolver observes physical spelling and directory capabilities
+ * within this comparison. Symlinks can identify the same installed file while
+ * case-sensitive native names remain distinct.
  */
 function sameRealPath(left: string, right: string): boolean {
-  const identity = (file: string): string => {
-    let resolved = resolve(file);
-    try {
-      resolved = realpathSync.native(resolved);
-    } catch {
-      // Not on disk: the resolved spelling is the best identity available.
-    }
-    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
-  };
-  return identity(left) === identity(right);
+  const identities = createFilesystemPathIdentityContext({
+    throwOnRealpathError: false,
+  });
+  return identities.resolve(left).key === identities.resolve(right).key;
 }
 
 /**

package/src/transformer.ts

@@ -14,25 +14,33 @@
  * generation hit. Cross-file invalidation also rides the project fingerprint
  * {@link getCacheKey} folds into Metro's static transformer key (see
  * `core/fingerprint.ts`).
+ *
+ * The adapter passes no `watching` declaration in its hooks, so a project whose
+ * plugin observations are unavailable (a generation the core can only serve
+ * fresh) fails the transform with an explicit error instead of caching it: the
+ * core refuses fresh-only output unless the host states it is not watching.
  */
 import {
   createTtscTransformCache,
   isTransformTarget,
+  readTtscTransformSession,
   resolveOptions,
+  shareTtscTransformCache,
   transformTtsc,
 } from "@ttsc/unplugin/api";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+import type { ResolvedTtscMetroOptions } from "./core/TtscMetroOptions";
 import {
   computeProjectFingerprint,
   createSnapshotRecorder,
   resolveProjectView,
   stableStringify,
 } from "./core/fingerprint";
-import type { ResolvedTtscMetroOptions } from "./core/options";
 import { resolveOptionsFromEnv } from "./core/options";
+import { remapAstLocations } from "./core/remapAstLocations";
 import { resolveUpstreamTransformer } from "./core/upstream";
 
 const nodeRequire = createRequire(import.meta.url);
@@ -46,6 +54,9 @@ const nodeRequire = createRequire(import.meta.url);
 let resolved: ResolvedTtscMetroOptions | undefined;
 let unpluginOptions: ReturnType<typeof resolveOptions> | undefined;
 const cache = createTtscTransformCache();
+// Metro's workers share each compile through the session `withTtsc` opened
+// (samchon/ttsc#1390).
+shareTtscTransformCache(cache, readTtscTransformSession());
 let snapshotRecorder: ReturnType<typeof createSnapshotRecorder> | undefined;
 
 /** Lazily resolve the worker-side options (from {@link resolveOptionsFromEnv}). */
@@ -70,6 +81,39 @@ function recorder(): ReturnType<typeof createSnapshotRecorder> {
  * monorepos and when Metro is launched from a parent directory. Getting this
  * wrong makes every file look "outside the project" and silently skips the
  * plugin pass.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node path.isAbsolute/path.resolve implement Metro's filename contract.
+ *   Absolute input is retained; relative input is anchored at supplied
+ *   projectRoot, with cwd only for callers lacking that option.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper owns the single relative-to-absolute boundary, keeping Metro's
+ *   original filename separate from the compiler address.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   This operation chooses a base and delegates native path resolution;
+ *   it owns no input collection or processing strategy.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   It maps one filename and supplied options without shared computation.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The returned path transfers to its caller; no resource is retained.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   This correct owning anchor avoids monorepo misrouting without matching
+ *   error text or special-casing fixture names.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node path handles native separators, roots and drive letters. No URLs or
+ *   shell commands are mixed with filenames and no filesystem is changed.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains the project-relative input, absolute result and
+ *   cwd fallback reason. Checked against the documentation skill: separate
+ *   paragraphs state the contract and why its nonobvious boundary matters;
+ *   field comments retain their own useful facts.
  */
 export function resolveAbsoluteFilename(
   filename: string,
@@ -92,7 +136,60 @@ export function resolveAbsoluteFilename(
  * Expo/React-Native Babel transformer to produce the AST Metro expects. The
  * upstream call receives Metro's original params (notably the project-relative
  * `filename`, which Babel expects); only `src` is replaced with the
- * ttsc-transformed source.
+ * ttsc-transformed source. When the adapter returns a source map for that
+ * source, the upstream AST's locations are moved back through it to the
+ * author's lines, because Metro maps the AST against the file it read
+ * (samchon/ttsc#1392).
+ *
+ * An explicit `project` option selects its tsconfig. Otherwise the adapter
+ * discovers the nearest tsconfig and follows its references to the project
+ * admitting the file, using Metro's `projectRoot` or the current working
+ * directory to resolve a relative file.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Metro's transformer callback composes the shared Unplugin transform core
+ *   with the selected Babel transformer. One resolved project view is frozen
+ *   into compilation and recorder inputs. Noneligible or out-of-program files
+ *   follow the shared core contract; genuine compiler/load failures propagate.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The entry point gates delivery, freezes one project view for compilation
+ *   and recording, then delegates to Babel. Shared core helpers own checking
+ *   and caching; the adapter owns only Metro transport and AST remapping.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Filtering runs before compilation. Eligible deliveries resolve one view
+ *   and record their inputs in a single batch; compiler and AST traversal
+ *   costs belong to their delegated owners rather than repeated per input.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The worker's shared transform cache validates project state on each hit,
+ *   while the inherited session shares compilation across workers. The same
+ *   project view and options feed compilation and generation recording; Babel
+ *   is invoked for the actual delivery and is not memoized by this adapter.
+ *
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   Worker singletons own resolved options, the transform cache and recorder
+ *   until process termination. The shared core owns cached generations and
+ *   session storage; the recorder owns its cumulative paths. This entry point
+ *   exposes no disposal signal from Metro and does not claim a fixed byte bound.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Only the returned AST's owned locations are updated, with no patched
+ *   loader or test-specific production behavior.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Metro-relative filenames drive substring filters; Node path.resolve
+ *   produces absolute compiler addresses. The shared core owns native
+ *   compiler/session access, while Babel retains the original filename.
+ *   Worker transport is JSON and no shell command is constructed here.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains pass order, original parameter preservation,
+ *   project selection and AST location mutation. Checked against the
+ *   documentation skill: separate paragraphs state the contract and why its
+ *   nonobvious boundary matters; field comments retain their own useful
+ *   facts.
  */
 export async function transform(params: {
   src: string;
@@ -112,6 +209,8 @@ export async function transform(params: {
   }
 
   let transformedSrc = params.src;
+  let transformedMap: { mappings: string; sources: string[] } | undefined;
+  let absoluteFilename = params.filename;
   {
     unpluginOptions ??= resolveOptions(opts.ttsc);
     const projectRoot =
@@ -121,6 +220,7 @@ export async function transform(params: {
     const explicitProject =
       typeof opts.ttsc.project === "string" ? opts.ttsc.project : undefined;
     const filename = resolveAbsoluteFilename(params.filename, params.options);
+    absoluteFilename = filename;
     const project = resolveProjectView({
       compilerOptions: opts.ttsc.compilerOptions,
       explicitProject,
@@ -174,10 +274,17 @@ export async function transform(params: {
     // Genuine compile and type failures still propagate so Metro surfaces them.
     if (result !== undefined && typeof result.code === "string") {
       transformedSrc = result.code;
+      transformedMap = result.map;
     }
   }
 
-  return upstream.transform({ ...params, src: transformedSrc });
+  const output = await upstream.transform({ ...params, src: transformedSrc });
+  // Metro maps the returned AST against the file it read, so the upstream's
+  // positions in the transformed text are moved back to the author's lines.
+  if (transformedMap !== undefined) {
+    remapAstLocations(output.ast, transformedMap, absoluteFilename);
+  }
+  return output;
 }
 
 /**
@@ -199,8 +306,57 @@ export async function transform(params: {
  * A change to any fingerprinted input re-keys every transformed file at
  * project-level granularity, forced by Metro's single static key, replacing the
  * former manual `--reset-cache` step. Resolving the upstream is deliberately
- * non-fatal here: a missing peer must not crash cache-key computation. See the
- * README "Caveats" and samchon/ttsc#721.
+ * non-fatal here: a missing peer must not crash cache-key computation, but a
+ * failed upstream key withdraws reuse with a nonce. See the README "Caveats"
+ * and samchon/ttsc#721.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node sha256 combines package identity, stable resolved options, forwarded
+ *   upstream key and the project fingerprint required by Metro's
+ *   one-static-key contract. Failed upstream loads or callbacks contribute a
+ *   nonce; an absent optional callback contributes no additional key.
+ *   Forwarded compiler and plugin records retain their JSON property order
+ *   because the compiler or a plugin can give that order semantic meaning.
+ *   Fingerprint failure disables reuse through a nonce rather
+ *   than fabricating a proven generation.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One hash assembly combines options, upstream contribution and the project
+ *   fingerprint. The fingerprint owner handles persistence and validity;
+ *   cacheKeyProjectRoot extracts Metro's argument without duplicating discovery.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One static key per Metro run hashes encoded options, the upstream key
+ *   and one project fingerprint. Key assembly is linear in their string bytes;
+ *   the fingerprint owner accounts for project scans and config traversal.
+ *
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   Options, adapter version, upstream key and exact project state contribute
+ *   to the shared key. Project observation failures withdraw reuse through a
+ *   nonce. A failing upstream load or key uses a nonce too, preserving the
+ *   nonfatal keying boundary without pretending its external state is known.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The hash is local to this call. Worker singletons are owned by transform
+ *   and persisted baseline files by prepareSnapshot, not the hash assembler.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Decision values come from the documented inputs and product protocol
+ *   rather than expected test answers. No compensating path is introduced to
+ *   make a known example pass.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Native project roots are interpreted by the fingerprint owner and Node
+ *   module loading reads package identity. Hash input has deterministic
+ *   string representation across OSes; filesystem content and identity remain
+ *   deliberately host-specific.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains one key per run, all contributions,
+ *   project-wide invalidation and nonfatal upstream key policy. Checked
+ *   against the documentation skill: separate paragraphs state the contract
+ *   and why its nonobvious boundary matters; field comments retain their own
+ *   useful facts.
  */
 export function getCacheKey(...args: unknown[]): string {
   const opts = options();
@@ -208,16 +364,14 @@ export function getCacheKey(...args: unknown[]): string {
   hash.update(`@ttsc/metro:${packageVersion()}`);
   hash.update(
     stableStringify({
-      ttsc: opts.ttsc,
+      ttsc: JSON.stringify(opts.ttsc),
       include: opts.include,
       exclude: opts.exclude,
       upstreamTransformer: opts.upstreamTransformer ?? null,
     }),
   );
   const upstreamKey = upstreamCacheKey(opts.upstreamTransformer, args);
-  if (upstreamKey.length !== 0) {
-    hash.update(upstreamKey);
-  }
+  hash.update(upstreamKey ?? `nonce:${randomBytes(32).toString("hex")}`);
   hash.update(
     computeProjectFingerprint({
       // The same overlay `transform` hands the recorder. Both read these
@@ -255,18 +409,19 @@ function cacheKeyProjectRoot(args: unknown[]): string | undefined {
  * Fold the upstream transformer's cache key in, defensively. Forwards Metro's
  * own `getCacheKey` arguments so the upstream's babelrc-derived key is
  * preserved, and never throws: a missing peer or a throwing upstream
- * `getCacheKey` yields an empty contribution rather than failing the whole
- * build's cache keying.
+ * `getCacheKey` yields `undefined`, withdrawing cross-run reuse without failing
+ * the whole build's cache keying. An absent optional callback still contributes
+ * the empty string.
  */
 function upstreamCacheKey(
   upstreamTransformer: string | undefined,
   args: unknown[],
-): string {
+): string | undefined {
   let upstream;
   try {
     upstream = resolveUpstreamTransformer(upstreamTransformer);
   } catch {
-    return "";
+    return undefined;
   }
   if (upstream.getCacheKey === undefined) {
     return "";
@@ -274,15 +429,57 @@ function upstreamCacheKey(
   try {
     return String(upstream.getCacheKey(...args) ?? "");
   } catch {
-    return "";
+    return undefined;
   }
 }
 
 /**
  * Decide whether a file should run through the ttsc pass. Only TypeScript
  * sources (`.ts`/`.tsx`/`.mts`/`.cts`, excluding every declaration form)
- * qualify; `exclude` substrings win over `include`, and an empty `include`
- * means "all TypeScript". Exported for unit testing.
+ * qualify, and a file below a `node_modules` directory never does, whatever
+ * `include` says, because the shared `isTransformTarget` predicate rejects it
+ * first. `exclude` substrings win over `include`, and an empty `include` means
+ * "all eligible TypeScript". Patterns use the supplied project-relative
+ * filename literally; this operation does not normalize separators or
+ * filesystem case.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The shared isTransformTarget predicate owns supported TypeScript
+ *   extensions, declaration exclusions, virtual-module and node_modules
+ *   exclusions. Literal substring filters apply to Metro's project-relative
+ *   filename, with exclusion taking precedence.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This predicate orders extension eligibility, exclusion and inclusion as
+ *   early returns. Compiler execution remains outside the filtering policy.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Extension matching precedes substring scans; exclusion returns early and
+ *   inclusion stops at its first match. Cost follows pattern count and supplied
+ *   filename length without allocating a normalized copy for literal matching.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This inexpensive predicate coordinates no shared computation and accepts
+ *   caller-owned, potentially mutable option arrays.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Filtering retains no caller data and opens no native resource.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   This pure decision neither invokes compilation nor mutates options, and
+ *   has no fixture or test-mode branch.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   This predicate matches TypeScript extensions and caller-supplied literal
+ *   substrings. It defines no filesystem identity or native path
+ *   normalization contract.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains eligible extensions, declaration and
+ *   node_modules exclusion, empty include and exclusion precedence. Checked
+ *   against the documentation skill: separate paragraphs state the contract
+ *   and why its nonobvious boundary matters; field comments retain their own
+ *   useful facts.
  */
 export function shouldTransform(
   filename: string,