@ttsc/metro 0.16.3

package/src/core/options.ts

@@ -0,0 +1,130 @@
+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[];
+}
+
+/**
+ * Environment variable that carries the resolved options from the Metro config
+ * process to the worker processes.
+ *
+ * Metro forks its transform workers (jest-worker) from the process that loaded
+ * `metro.config.js`, so a variable set on `process.env` before Metro boots is
+ * inherited by every worker. This is the only channel `withTtsc`'s arguments
+ * can reach the transformer through: the worker never sees the `withTtsc`
+ * call.
+ */
+export const ENV_KEY = "TTSC_METRO_OPTIONS";
+
+/**
+ * Serialise user options for transport to the worker processes via
+ * {@link ENV_KEY}.
+ */
+export function serializeOptions(options: TtscMetroOptions): string {
+  return JSON.stringify(options ?? {});
+}
+
+/**
+ * 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.
+ */
+export function resolveOptionsFromEnv(): ResolvedTtscMetroOptions {
+  const raw = process.env[ENV_KEY];
+  const parsed = parse(raw);
+  return {
+    ttsc: {
+      project: parsed.project,
+      compilerOptions: parsed.compilerOptions,
+      ...("plugins" in parsed ? { plugins: parsed.plugins } : {}),
+    },
+    upstreamTransformer:
+      typeof parsed.upstreamTransformer === "string"
+        ? parsed.upstreamTransformer
+        : undefined,
+    include: toStringArray(parsed.include),
+    exclude: toStringArray(parsed.exclude),
+  };
+}
+
+function parse(raw: string | undefined): TtscMetroOptions {
+  if (raw === undefined || raw.length === 0) {
+    return {};
+  }
+  try {
+    const value: unknown = JSON.parse(raw);
+    // Only a plain object is a valid payload; arrays, `null`, numbers, strings,
+    // and booleans (all valid JSON) degrade to defaults rather than leaking a
+    // wrong-shaped value downstream.
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? (value as TtscMetroOptions)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Coerce an untrusted env value into a `string[]`. A non-array (e.g. the common
+ * mistake of passing a bare string for `include`/`exclude`) becomes `[]` so the
+ * worker never calls `.some` on a non-array and crashes.
+ */
+function toStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string")
+    : [];
+}

package/src/core/upstream.ts

@@ -0,0 +1,87 @@
+import { createRequire } from "node:module";
+
+const nodeRequire = createRequire(import.meta.url);
+
+/**
+ * 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;
+}
+
+/**
+ * Upstream transformer module specifiers tried (in order) when no explicit
+ * `upstreamTransformer` is configured: Expo first, then modern bare React
+ * Native, then the legacy package.
+ */
+export const UPSTREAM_CANDIDATES = [
+  "@expo/metro-config/babel-transformer",
+  "@react-native/metro-babel-transformer",
+  "metro-react-native-babel-transformer",
+] as const;
+
+/**
+ * Resolve the upstream Metro Babel transformer to delegate to.
+ *
+ * Detection order, most specific first:
+ *
+ * 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.
+ *
+ * `load` is injectable purely so the resolution order and the not-found path
+ * can be tested deterministically; production always uses the real `require`.
+ */
+export function resolveUpstreamTransformer(
+  customPath?: string,
+  load: (modulePath: string) => UpstreamTransformer | undefined = tryRequire,
+): UpstreamTransformer {
+  if (customPath !== undefined && customPath.length !== 0) {
+    const upstream = load(customPath);
+    if (upstream === undefined) {
+      throw new Error(
+        `[@ttsc/metro] Could not load the configured upstream transformer: ${customPath}`,
+      );
+    }
+    return upstream;
+  }
+
+  for (const candidate of UPSTREAM_CANDIDATES) {
+    const upstream = load(candidate);
+    if (upstream !== undefined) {
+      return upstream;
+    }
+  }
+
+  throw new Error(
+    "[@ttsc/metro] Could not find an upstream Metro transformer. Install " +
+      "@expo/metro-config (Expo) or @react-native/metro-babel-transformer " +
+      "(React Native), or set the `upstreamTransformer` option to an explicit " +
+      "module path.",
+  );
+}
+
+function tryRequire(modulePath: string): UpstreamTransformer | undefined {
+  try {
+    return nodeRequire(modulePath) as UpstreamTransformer;
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * `@ttsc/metro`: Metro (React Native / Expo) adapter for ttsc plugins.
+ *
+ * Metro bundles with Babel, which strips TypeScript types and never runs ttsc
+ * plugins, so neither the `ttsc` CLI nor `@ttsc/unplugin` can reach an RN/Expo
+ * build. {@link withTtsc} wires a Metro custom transformer that runs the ttsc
+ * plugin pass on each TypeScript file before handing the result to the
+ * project's existing Expo/React-Native Babel transformer.
+ *
+ * @example
+ *   Expo project
+ *   ```js
+ *   // metro.config.js
+ *   const { getDefaultConfig } = require("expo/metro-config");
+ *   const { withTtsc } = require("@ttsc/metro");
+ *
+ *   module.exports = withTtsc(getDefaultConfig(__dirname));
+ *   ```
+ *
+ * @example
+ *   Bare React Native
+ *   ```js
+ *   // metro.config.js
+ *   const { getDefaultConfig } = require("@react-native/metro-config");
+ *   const { withTtsc } = require("@ttsc/metro");
+ *
+ *   module.exports = withTtsc(getDefaultConfig(__dirname));
+ *   ```
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { TtscMetroOptions } from "./core/options";
+import { ENV_KEY, serializeOptions } from "./core/options";
+
+export type {
+  ResolvedTtscMetroOptions,
+  TtscMetroOptions,
+} from "./core/options";
+
+/**
+ * Minimal structural type for a Metro config object, avoids a hard dependency
+ * on Metro's types while letting {@link withTtsc} preserve the caller's exact
+ * config type.
+ */
+interface MetroConfigLike {
+  transformer?: {
+    babelTransformerPath?: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Wrap a Metro config so ttsc plugins run on every TypeScript file.
+ *
+ * Sets `transformer.babelTransformerPath` to this package's transformer and
+ * publishes the resolved options to Metro's worker processes via the
+ * {@link ENV_KEY} environment variable (the workers never see this call, so env
+ * is the transport, see `core/options.ts`). Compatible with Expo's
+ * `getDefaultConfig()` and bare React Native alike.
+ *
+ * With no `options`, the transformer auto-discovers `tsconfig.json` and runs
+ * the plugins configured there: the standard ttsc model. Pass `options` only to
+ * override the project path, plugin list, or include/exclude filters.
+ */
+export function withTtsc<T extends MetroConfigLike>(
+  config: T,
+  options: TtscMetroOptions = {},
+): T {
+  process.env[ENV_KEY] = serializeOptions(options);
+  return {
+    ...config,
+    transformer: {
+      ...config.transformer,
+      babelTransformerPath: transformerModulePath(),
+    },
+  } as T;
+}
+
+/**
+ * Absolute path to the built transformer module Metro will `require`.
+ *
+ * Always the CommonJS build (`transformer.js`) next to this module: Metro
+ * resolves `babelTransformerPath` with `require`, and `metro.config.js` is a
+ * CommonJS module. Rollup rewrites `import.meta.url` for both the CJS and ESM
+ * builds, so this resolves correctly regardless of how the config loaded this
+ * entry.
+ */
+function transformerModulePath(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "transformer.js");
+}

package/src/transformer.ts

@@ -0,0 +1,249 @@
+/**
+ * Metro custom transformer for ttsc.
+ *
+ * Metro loads this module via `transformer.babelTransformerPath` (wired by
+ * {@link withTtsc}) and calls {@link transform} once per file. The flow is:
+ *
+ * TypeScript source -> ttsc plugin pass (typia, nestia, …) via @ttsc/unplugin's
+ * core -> transformed TypeScript source -> upstream Expo/RN Babel transformer
+ * (strips types, RN transforms) -> Babel AST (what Metro consumes)
+ *
+ * The ttsc pass reuses `@ttsc/unplugin`'s `transformTtsc`, so the plugin
+ * contract, tsconfig discovery, and per-build cache are identical to every
+ * other bundler integration. See the package README for the v1 cost model and
+ * the cross-file cache-invalidation caveat.
+ */
+import {
+  createTtscTransformCache,
+  resolveOptions,
+  transformTtsc,
+} from "@ttsc/unplugin/api";
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import type { ResolvedTtscMetroOptions } from "./core/options";
+import { resolveOptionsFromEnv } from "./core/options";
+import { resolveUpstreamTransformer } from "./core/upstream";
+
+const nodeRequire = createRequire(import.meta.url);
+
+/**
+ * Matches the TypeScript source extensions the ttsc pass handles (`.ts`,
+ * `.tsx`, `.cts`, `.mts`). JavaScript and declaration files are passed straight
+ * through to the upstream transformer.
+ */
+const TS_EXTENSION = /\.[cm]?tsx?$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+
+/**
+ * Per-worker singletons. Metro loads this module once per worker process and
+ * reuses it across every file that worker handles, so the resolved options, the
+ * transform cache, and the memoised `@ttsc/unplugin` options are all scoped to
+ * the worker.
+ */
+let resolved: ResolvedTtscMetroOptions | undefined;
+let unpluginOptions: ReturnType<typeof resolveOptions> | undefined;
+const cache = createTtscTransformCache();
+
+/** Lazily resolve the worker-side options (from {@link resolveOptionsFromEnv}). */
+function options(): ResolvedTtscMetroOptions {
+  return (resolved ??= resolveOptionsFromEnv());
+}
+
+/**
+ * Resolve Metro's per-file `filename` to an absolute path.
+ *
+ * Metro hands the babel transformer a path **relative to `projectRoot`** (it
+ * reads the file via `fs.readFileSync(path.resolve(projectRoot, filename))`)
+ * and passes `projectRoot` inside `options`. The ttsc pass needs an absolute
+ * path that matches a key in the compiled program, so resolve against
+ * `projectRoot`, never `process.cwd()`, which differs from `projectRoot` in
+ * 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.
+ */
+export function resolveAbsoluteFilename(
+  filename: string,
+  options?: Record<string, unknown>,
+): string {
+  if (path.isAbsolute(filename)) {
+    return filename;
+  }
+  const projectRoot =
+    options !== undefined && typeof options.projectRoot === "string"
+      ? options.projectRoot
+      : process.cwd();
+  return path.resolve(projectRoot, filename);
+}
+
+/**
+ * Metro transform entry point.
+ *
+ * Runs the ttsc plugin pass on TypeScript files, then delegates to the upstream
+ * 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.
+ */
+export async function transform(params: {
+  src: string;
+  filename: string;
+  options: Record<string, unknown>;
+  [key: string]: unknown;
+}): Promise<{ ast: object }> {
+  const opts = options();
+  const upstream = resolveUpstreamTransformer(opts.upstreamTransformer);
+
+  // Gate on the project-relative path Metro supplies, so include/exclude
+  // substrings match what the user writes (e.g. "src/generated") and never
+  // collide with an absolute ancestor directory name. The absolute path is used
+  // only to address the file inside the compiled program.
+  if (!shouldTransform(params.filename, opts)) {
+    return upstream.transform(params);
+  }
+
+  let transformedSrc = params.src;
+  try {
+    unpluginOptions ??= resolveOptions(opts.ttsc);
+    const result = await transformTtsc(
+      resolveAbsoluteFilename(params.filename, params.options),
+      params.src,
+      unpluginOptions,
+      undefined,
+      cache,
+    );
+    if (result !== undefined && typeof result.code === "string") {
+      transformedSrc = result.code;
+    }
+  } catch (error) {
+    // A file that is not part of the tsconfig program is not a build error,
+    // pass it through untransformed. Genuine compile/type failures propagate so
+    // Metro surfaces them, matching the other ttsc bundler integrations.
+    if (!isFileOutsideProject(error)) {
+      throw error;
+    }
+  }
+
+  return upstream.transform({ ...params, src: transformedSrc });
+}
+
+/**
+ * Metro transform-cache key.
+ *
+ * Metro already content-hashes each file, so this only has to invalidate when
+ * the transformer itself changes: package version + resolved options + the
+ * upstream transformer's own key (forwarded Metro's args, e.g. `projectRoot`,
+ * so a `babel.config.js` change still busts the cache). Resolving the upstream
+ * is deliberately non-fatal here: a missing peer must not crash cache-key
+ * computation. NOTE: this does not encode the tsconfig / plugin configuration
+ * or cross-file type dependencies, so after editing those (or a depended-upon
+ * type) run Metro with `--reset-cache`. See the README "Caveats" and
+ * samchon/ttsc#255.
+ */
+export function getCacheKey(...args: unknown[]): string {
+  const opts = options();
+  const hash = createHash("sha256");
+  hash.update(`@ttsc/metro:${packageVersion()}`);
+  hash.update(
+    stableStringify({
+      ttsc: 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);
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * 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.
+ */
+function upstreamCacheKey(
+  upstreamTransformer: string | undefined,
+  args: unknown[],
+): string {
+  let upstream;
+  try {
+    upstream = resolveUpstreamTransformer(upstreamTransformer);
+  } catch {
+    return "";
+  }
+  if (upstream.getCacheKey === undefined) {
+    return "";
+  }
+  try {
+    return String(upstream.getCacheKey(...args) ?? "");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Decide whether a file should run through the ttsc pass. Only TypeScript
+ * sources (`.ts`/`.tsx`/`.cts`/`.mts`, excluding `.d.ts`) qualify; `exclude`
+ * substrings win over `include`, and an empty `include` means "all TypeScript".
+ * Exported for unit testing.
+ */
+export function shouldTransform(
+  filename: string,
+  opts: ResolvedTtscMetroOptions,
+): boolean {
+  if (!TS_EXTENSION.test(filename) || DECLARATION.test(filename)) {
+    return false;
+  }
+  if (opts.exclude.some((pattern) => filename.includes(pattern))) {
+    return false;
+  }
+  if (
+    opts.include.length !== 0 &&
+    !opts.include.some((pattern) => filename.includes(pattern))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * `transformTtsc` throws `"ttsc transform did not return output for <file>"`
+ * when the requested file is not part of the compiled program (e.g. excluded
+ * from the tsconfig). That case is non-fatal: the file should pass through.
+ */
+function isFileOutsideProject(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("did not return output");
+}
+
+function packageVersion(): string {
+  try {
+    const pkg = nodeRequire("@ttsc/metro/package.json") as { version?: string };
+    return pkg.version ?? "0";
+  } catch {
+    return "0";
+  }
+}
+
+/**
+ * JSON-serialise with object keys sorted recursively, so two semantically equal
+ * option sets always hash to the same cache key regardless of property order.
+ */
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}