@ttsc/metro 0.30.3 → 0.31.0

package/src/core/options.ts

@@ -1,61 +1,7 @@
-import type { TtscUnpluginOptions } from "@ttsc/unplugin/api";
-
-/**
- * Options accepted by {@link withTtsc} and the Metro transformer.
- *
- * The `project` / `compilerOptions` / `plugins` fields are inherited from
- * `@ttsc/unplugin` so the Metro adapter speaks the exact same configuration
- * language as every other bundler integration. The remaining fields are
- * Metro-specific.
- *
- * Every field is JSON-serialisable on purpose: `withTtsc` runs in the Metro
- * **config** process, but the transformer runs in Metro's **worker** processes,
- * so the resolved options have to survive a structured-clone / env round-trip
- * to reach them (see {@link serializeOptions}). That is why `include`/`exclude`
- * are plain substring patterns rather than `RegExp`.
- */
-export interface TtscMetroOptions extends TtscUnpluginOptions {
-  /**
-   * Explicit module path of the upstream Metro Babel transformer to delegate to
-   * after the ttsc pass.
-   *
-   * When omitted it is auto-detected: `@expo/metro-config/babel-transformer`
-   * first (Expo), then `@react-native/metro-babel-transformer`, then the legacy
-   * `metro-react-native-babel-transformer`.
-   */
-  upstreamTransformer?: string;
-
-  /**
-   * Substring patterns; when non-empty only files whose path contains one of
-   * them are run through the ttsc pass. Non-matching files are passed straight
-   * to the upstream transformer.
-   */
-  include?: string[];
-
-  /**
-   * Substring patterns; files whose path contains one of them skip the ttsc
-   * pass and go straight to the upstream transformer. Applied after
-   * {@link include}.
-   */
-  exclude?: string[];
-}
-
-/**
- * Fully-resolved options, split into the ttsc-side overlay and Metro-side
- * knobs.
- */
-export interface ResolvedTtscMetroOptions {
-  /** Options forwarded verbatim to the `@ttsc/unplugin` transform core. */
-  ttsc: TtscUnpluginOptions;
-  /** Explicit upstream transformer module path, or `undefined` to auto-detect. */
-  upstreamTransformer?: string;
-  /** Resolved include patterns (never `undefined`). */
-  include: string[];
-  /** Resolved exclude patterns (never `undefined`). */
-  exclude: string[];
-  /** Private run identity shared by `getCacheKey` and Metro workers. */
-  snapshotRunId?: string;
-}
+import type {
+  ResolvedTtscMetroOptions,
+  TtscMetroOptions,
+} from "./TtscMetroOptions";
 
 /**
  * Environment variable that carries the resolved options from the Metro config
@@ -72,6 +18,42 @@ export const ENV_KEY = "TTSC_METRO_OPTIONS";
 /**
  * Serialise user options for transport to the worker processes via
  * {@link ENV_KEY}.
+ *
+ * A supplied private run identity is written into the payload. This function
+ * returns JSON without publishing the environment variable or mutating options.
+ * Values must be JSON-serialisable; serialization errors propagate.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   JSON.stringify and object spread encode the declared worker transport.
+ *   JSON failures propagate rather than inventing a successful payload.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   A single serializer owns the config-to-worker payload. Publication stays
+ *   with withTtsc, so encoding has no environment side effect.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   A supplied private run identity overrides that transport field; this
+ *   operation returns bytes and does not replace process methods, loader
+ *   internals or caller options.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains the JSON payload, supplied run identity and
+ *   serialization failure boundary. 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
+ *   Returns a string and keeps no state or handle.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   One JSON.stringify of the user's small options record per config load.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Runs once per Metro config load; there is no repeated work to share.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   JSON.stringify escapes backslashes, so a Windows path in the options
+ *   round-trips; no path is interpreted.
  */
 export function serializeOptions(
   options: TtscMetroOptions,
@@ -86,10 +68,50 @@ export function serializeOptions(
 /**
  * Reconstruct the resolved options inside a worker process.
  *
- * Reads {@link ENV_KEY}; when it is unset or malformed the adapter falls back to
- * defaults, which means "auto-discover `tsconfig.json` and read its configured
- * plugins", the standard ttsc behaviour, and the right thing for a project that
- * called `withTtsc(config)` with no explicit options.
+ * Reads {@link ENV_KEY}; when it is unset or contains invalid JSON or a
+ * non-object payload, the adapter falls back to defaults: auto-discover
+ * `tsconfig.json` and read its configured plugins. This is the standard ttsc
+ * behaviour for a project that called `withTtsc(config)` with no explicit
+ * options.
+ *
+ * All common compiler options, including the output-addressing `projectRoot`,
+ * survive this transport without interpreting their paths in the config host.
+ * A present `plugins` property is forwarded even when its value is `false`;
+ * omission leaves plugin selection to the project. The `include` and `exclude`
+ * arrays retain only string entries, while invalid array values become empty
+ * filters. Only a non-empty string is accepted as the private run identity.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   JSON.parse reads the adapter-owned environment channel. The parser accepts
+ *   only object payloads, filters include/exclude to strings and preserves
+ *   plugins field presence so false differs from omission.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One reconstruction function separates transport parsing and string-array
+ *   normalization from the resolved object workers consume.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Invalid JSON and non-object payloads use documented defaults, not a failed
+ *   compiler fallback; this parser patches no global APIs.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains absent, invalid-JSON and non-object defaults,
+ *   plugin-presence semantics and filter normalization. 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
+ *   Returns a fresh object and keeps no state or handle.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   One JSON.parse and a filter over the short include and exclude arrays.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   The transformer calls it once per worker and memoises the result in options().
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Reads one environment variable as JSON and resolves no path.
  */
 export function resolveOptionsFromEnv(): ResolvedTtscMetroOptions {
   const raw = process.env[ENV_KEY];
@@ -97,6 +119,7 @@ export function resolveOptionsFromEnv(): ResolvedTtscMetroOptions {
   return {
     ttsc: {
       project: parsed.project,
+      projectRoot: parsed.projectRoot,
       compilerOptions: parsed.compilerOptions,
       ...("plugins" in parsed ? { plugins: parsed.plugins } : {}),
     },

package/src/core/remapAstLocations.ts

@@ -0,0 +1,219 @@
+import { createFilesystemPathIdentityContext } from "ttsc/path-identity";
+
+/**
+ * Move every source location in an upstream transformer's AST from the ttsc
+ * transformed text back to the text the module's author wrote
+ * (samchon/ttsc#1392).
+ *
+ * Metro's Babel transformer contract returns an AST, never a map, and Metro
+ * builds the module's source map from that AST's `loc` positions against the
+ * file it read. The upstream transformer parsed the ttsc transformed text, so
+ * without this pass every position after the first change points at the
+ * reprinted lines: breakpoints, stack traces, and the error overlay would all
+ * be off. Each node's `loc` start and end are looked up in `map` with the usual
+ * greatest-lower-bound rule. A node whose start has no mapping into `file`,
+ * such as generated code, loses its `loc`, which Babel treats as a synthesized
+ * node, so it takes the mapping of the code around it.
+ *
+ * Babel locations have one-based lines and zero-based UTF-16 columns; source
+ * map segments have zero-based lines and columns. The map points from generated
+ * text to the authored file. Missing or reversed mapped ends clamp to the
+ * mapped start. Traversal tracks visited objects and mutates only AST
+ * locations. Absolute sources are compared by filesystem identity within this
+ * call, so links and actual directory case capabilities determine the owning
+ * source.
+ *
+ * @param ast The upstream transformer's AST, rewritten in place.
+ * @param map The adapter's map from the transformed text to `file`, with
+ *   absolute `sources`.
+ * @param file Absolute path of the module.
+ * @evidence contracts/common.md#principled-implementation
+ *   The adapter consumes its own source-map VLQ segments using
+ *   greatest-lower-bound lookup, then updates the upstream-owned AST through
+ *   Metro's returned-AST extension boundary. Iterative traversal tracks
+ *   visited objects to handle shared/cyclic AST references. Unmapped starts
+ *   lose loc and invalid ends clamp to the mapped start rather than
+ *   manufacturing authored positions.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Mapping decoding, position lookup and object traversal remain distinct
+ *   steps; the traversal owns AST mutation and the local lookup owns coordinate
+ *   conversion without adding a second Babel parser.
+ *
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Mapping decoding is linear in encoded bytes. A visited Set walks each
+ *   AST object once; each endpoint uses binary search on its generated line's
+ *   segments. Temporary storage follows decoded segments and reachable AST
+ *   objects, and the iterative stack avoids call-depth dependence on the AST.
+ *   Source identity resolution is shared within this call; missing sources can
+ *   additionally require ancestor and directory-capability observations.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   This call mutates one returned AST using that delivery's map; it owns no
+ *   shared cache and repeated calls would remap already moved coordinates.
+ *
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   The caller owns the AST. Local decoded lines and traversal state end with
+ *   the call; no handle or cross-delivery state is retained.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   No Babel methods or compiler internals are patched.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The shared filesystem-identity context compares absolute map sources with
+ *   the delivered file using physical spelling and actual directory case
+ *   capabilities. Source coordinates remain line/column values independent
+ *   of native newline spelling; OS names do not fold distinct filenames.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains map direction, in-place mutation, coordinate
+ *   indexing and generated/unmapped locations. 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 remapAstLocations(
+  ast: unknown,
+  map: { mappings: string; sources: readonly string[] },
+  file: string,
+): void {
+  const identities = createFilesystemPathIdentityContext({
+    throwOnRealpathError: false,
+  });
+  const fileKey = identities.resolve(file).key;
+  const own = map.sources.findIndex(
+    (source) => identities.resolve(source).key === fileKey,
+  );
+  if (own < 0) {
+    return;
+  }
+  const lines = decodeSegments(map.mappings);
+  const locate = (
+    position: unknown,
+  ): { column: number; line: number } | undefined => {
+    if (typeof position !== "object" || position === null) return undefined;
+    const { column, line } = position as { column?: unknown; line?: unknown };
+    if (typeof line !== "number" || typeof column !== "number") {
+      return undefined;
+    }
+    const segments = lines[line - 1];
+    if (segments === undefined) return undefined;
+    let low = 0;
+    let high = segments.length - 1;
+    let found: Segment | undefined;
+    while (low <= high) {
+      const middle = (low + high) >> 1;
+      const segment = segments[middle]!;
+      if (segment.generatedColumn <= column) {
+        found = segment;
+        low = middle + 1;
+      } else {
+        high = middle - 1;
+      }
+    }
+    return found === undefined || found.source !== own
+      ? undefined
+      : { column: found.column, line: found.line + 1 };
+  };
+
+  const visited = new Set<object>();
+  const pending: unknown[] = [ast];
+  while (pending.length !== 0) {
+    const value = pending.pop();
+    if (typeof value !== "object" || value === null || visited.has(value)) {
+      continue;
+    }
+    visited.add(value);
+    if (Array.isArray(value)) {
+      for (const entryToAppend of value) pending.push(entryToAppend);
+      continue;
+    }
+    const node = value as Record<string, unknown>;
+    for (const [key, child] of Object.entries(node)) {
+      if (key !== "loc") pending.push(child);
+    }
+    const loc = node.loc;
+    if (typeof loc !== "object" || loc === null) continue;
+    const { end, start } = loc as { end?: unknown; start?: unknown };
+    const mappedStart = locate(start);
+    if (mappedStart === undefined) {
+      node.loc = null;
+      continue;
+    }
+    const mappedEnd = locate(end);
+    node.loc = {
+      ...loc,
+      end:
+        mappedEnd === undefined ||
+        mappedEnd.line < mappedStart.line ||
+        (mappedEnd.line === mappedStart.line &&
+          mappedEnd.column < mappedStart.column)
+          ? mappedStart
+          : mappedEnd,
+      start: mappedStart,
+    };
+  }
+}
+
+/** One decoded mapping on a generated line. */
+interface Segment {
+  /** Zero-based generated column. */
+  generatedColumn: number;
+
+  /** Index into the map's `sources`, or `-1` for an unmapped segment. */
+  source: number;
+
+  /** Zero-based source line. */
+  line: number;
+
+  /** Zero-based source column. */
+  column: number;
+}
+
+/**
+ * Decode `mappings` into its segments per generated line, in column order.
+ * Segments of every source are kept, and a segment with no source position is
+ * kept with source `-1`, so a lookup that lands on either reports no position
+ * instead of reaching past it to an earlier mapping.
+ */
+function decodeSegments(mappings: string): Segment[][] {
+  const alphabet =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  const lines: Segment[][] = [];
+  let source = 0;
+  let line = 0;
+  let column = 0;
+  for (const text of mappings.split(";")) {
+    const segments: Segment[] = [];
+    let generatedColumn = 0;
+    for (const encoded of text.split(",")) {
+      if (encoded === "") continue;
+      const fields: number[] = [];
+      let value = 0;
+      let shift = 0;
+      for (const char of encoded) {
+        const digit = alphabet.indexOf(char);
+        if (digit < 0) return lines;
+        value += (digit & 31) << shift;
+        if ((digit & 32) !== 0) {
+          shift += 5;
+          continue;
+        }
+        fields.push((value & 1) !== 0 ? -(value >>> 1) : value >>> 1);
+        value = 0;
+        shift = 0;
+      }
+      generatedColumn += fields[0] ?? 0;
+      if (fields.length < 4) {
+        segments.push({ column: 0, generatedColumn, line: 0, source: -1 });
+        continue;
+      }
+      source += fields[1]!;
+      line += fields[2]!;
+      column += fields[3]!;
+      segments.push({ column, generatedColumn, line, source });
+    }
+    lines.push(segments);
+  }
+  return lines;
+}

package/src/core/upstream.ts

@@ -1,25 +1,8 @@
 import { createRequire } from "node:module";
 
-const nodeRequire = createRequire(import.meta.url);
+import type { UpstreamTransformer } from "./UpstreamTransformer";
 
-/**
- * The subset of the Metro Babel-transformer contract this adapter relies on.
- *
- * Metro loads the module named by `transformer.babelTransformerPath` and calls
- * its `transform` once per file, expecting a Babel AST back. `getCacheKey` is
- * an optional export Metro folds into its transform-cache key; Metro invokes it
- * with arguments (e.g. `{ projectRoot, enableBabelRCLookup }`), so it is typed
- * variadic.
- */
-export interface UpstreamTransformer {
-  transform(params: {
-    src: string;
-    filename: string;
-    options: Record<string, unknown>;
-    [key: string]: unknown;
-  }): Promise<{ ast: object }>;
-  getCacheKey?: (...args: unknown[]) => string;
-}
+const nodeRequire = createRequire(import.meta.url);
 
 /**
  * Upstream transformer module specifiers tried (in order) when no explicit
@@ -40,14 +23,55 @@ export const UPSTREAM_CANDIDATES = [
  * 1. An explicit `customPath` (the `upstreamTransformer` option);
  * 2. Each of {@link UPSTREAM_CANDIDATES} in turn.
  *
- * These are declared as optional peers and resolved at runtime against the
- * consumer project, so the adapter carries no Metro/Expo dependency itself.
- * Resolution is not memoised: Node's own module cache already makes the
- * repeated `require` a cheap lookup, and keeping no module-level state lets a
- * changed `upstreamTransformer` always take effect.
+ * `withTtsc` resolves an explicit specifier and the automatic candidates from
+ * the consuming project in the Metro config process, and publishes the absolute
+ * path it found (see {@link locateProjectUpstreamTransformer}). This worker-side
+ * lookup, rooted in the adapter's own location, is what remains for a specifier
+ * the project could not resolve, so the adapter carries no Metro/Expo
+ * dependency itself. Resolution is not memoised: Node's own module cache
+ * already makes the repeated `require` a cheap lookup, and keeping no
+ * module-level state lets a changed `upstreamTransformer` always take effect.
+ *
+ * `load` is the explicit module-loading boundary. Its default uses Node's real
+ * `require`; an injected loader must preserve absence versus failure
+ * semantics.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node createRequire loads the configured module or documented
+ *   Expo/React-Native candidates. Resolution is separated from execution: only
+ *   known entry-absence codes permit another automatic candidate;
+ *   installed-module initialization failures preserve their cause.
  *
- * `load` is injectable purely so the resolution order and the not-found path
- * can be tested deterministically; production always uses the real `require`.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Explicit selection and ordered detection share the loading boundary.
+ *   tryRequire owns absence classification, leaving this function to choose
+ *   the transformer and attach contextual errors.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The loader argument is an explicit dependency-injection boundary, not a
+ *   test-only runtime branch or a patched require.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   Node resolution accepts project-resolved absolute paths on Windows and
+ *   POSIX. createRequire is rooted at this module via import.meta.url; no
+ *   path is turned into a shell command. Runtime errors propagate through the
+ *   same policy on every OS.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains candidate order, project versus worker
+ *   resolution and absence versus initialization failures. 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
+ *   Keeps no state between calls; loaded modules belong to Node's module cache.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   At most three candidate probes per call, each a require.resolve followed by one require.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Deliberately unmemoised: Node's module cache makes a repeated require cheap and a changed option must take effect.
  */
 export function resolveUpstreamTransformer(
   customPath?: string,
@@ -101,6 +125,66 @@ export function resolveUpstreamTransformer(
   );
 }
 
+/**
+ * Locate the automatic upstream transformer the consuming project installed,
+ * without executing it.
+ *
+ * The candidates belong to the app, not to this adapter: under pnpm or a linked
+ * workspace the adapter sits outside the app's `node_modules` ancestry, so a
+ * lookup rooted in the adapter cannot see a transformer only the app installed.
+ * `resolve` is rooted in the project; each candidate is tried in
+ * {@link UPSTREAM_CANDIDATES} order and an absent one is skipped, exactly as the
+ * worker's probe skips it. Only resolution runs here, so a broken installation
+ * still fails where the worker loads it, with its own error.
+ *
+ * @param resolve Resolves a module specifier from the project.
+ * @returns The absolute path of the first installed candidate, or `undefined`.
+ * @evidence contracts/common.md#principled-implementation
+ *   The supplied project resolver uses Node module resolution without
+ *   executing candidate code. Only recognized entry-absence errors continue
+ *   probing; other resolver failures propagate.
+ *
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   Project discovery resolves only the shared candidate list; execution is
+ *   deferred to the worker loader that owns initialization failures.
+ *
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The documented optional-peer order is a product default, not a
+ *   fixture-specific answer. No module methods are replaced.
+ *
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The injected resolver owns project filesystem resolution on the host OS.
+ *   This operation compares module specifiers and returns its absolute result
+ *   without inventing separators or quoting a command.
+ *
+ * @evidence contracts/common.md#meaningful-documentation
+ *   The native JSDoc explains project ownership, ordered probing,
+ *   nonexecution and the absent result. 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
+ *   Resolves paths without executing a candidate and retains nothing.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms
+ *   At most three resolutions, stopping at the first one that succeeds.
+ *
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Runs once per withTtsc call, in the config process only.
+ */
+export function locateProjectUpstreamTransformer(
+  resolve: (specifier: string) => string,
+): string | undefined {
+  for (const candidate of UPSTREAM_CANDIDATES) {
+    try {
+      return resolve(candidate);
+    } catch (error) {
+      if (!isCandidateAbsent(error)) throw error;
+    }
+  }
+  return undefined;
+}
+
 /**
  * Load an upstream transformer module, separating genuine absence from a broken
  * installation.