@ttsc/metro 0.30.3 → 0.31.0

package/lib/index.mjs

@@ -1,9 +1,12 @@
-import { readFileSync, realpathSync } from 'node:fs';
+import { openTtscTransformSession } from '@ttsc/unplugin/api';
+import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createFilesystemPathIdentityContext } from 'ttsc/path-identity';
 import { prepareSnapshot } from './core/fingerprint.mjs';
 import { ENV_KEY, serializeOptions } from './core/options.mjs';
+import { locateProjectUpstreamTransformer } from './core/upstream.mjs';
 
 /**
  * `@ttsc/metro`: Metro (React Native / Expo) adapter for ttsc plugins.
@@ -54,14 +57,65 @@ import { ENV_KEY, serializeOptions } from './core/options.mjs';
  * `.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.
  */
 function withTtsc(config, options = {}) {
     // 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);
     process.env[ENV_KEY] = serializeOptions(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: {
@@ -84,11 +138,24 @@ function withTtsc(config, options = {}) {
  * and delegate into itself.
  */
 function inheritConfiguredTransformer(config, options) {
+    // 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 &&
+        options.upstreamTransformer.length !== 0) {
+        return {
+            ...options,
+            upstreamTransformer: resolveFromProject(options.upstreamTransformer, config),
+        };
+    }
     const declared = config.transformer?.babelTransformerPath;
-    if (options.upstreamTransformer !== undefined ||
-        typeof declared !== "string" ||
-        declared.length === 0) {
-        return options;
+    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
@@ -126,16 +193,20 @@ function inheritConfiguredTransformer(config, options) {
  * somewhere less legible.
  */
 function resolveFromProject(declared, config) {
-    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) {
+    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.
@@ -173,22 +244,15 @@ function isOwnTransformer(declared) {
 /**
  * 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, right) {
-    const identity = (file) => {
-        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;
 }
 /**
  * Absolute path to the built transformer module Metro will `require`.

package/lib/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;AA4BH;;;;;;;;;;;;;;;;;;;;AAoBG;SACa,QAAQ,CACtB,MAAS,EACT,UAA4B,EAAE,EAAA;;;;;IAM9B,MAAM,aAAa,GAAG,eAAe,CACnC,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,GAAG,MAAM,CAAC,WAAW,GAAG,SAAS,CACxE;AACD,IAAA,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,gBAAgB,CACrC,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7C,aAAa,CACd;IACD,OAAO;AACL,QAAA,GAAG,MAAM;AACT,QAAA,WAAW,EAAE;YACX,GAAG,MAAM,CAAC,WAAW;YACrB,oBAAoB,EAAE,qBAAqB,EAAE;AAC9C,SAAA;KACG;AACR;AAEA;;;;;;;;;;;;AAYG;AACH,SAAS,4BAA4B,CACnC,MAAuB,EACvB,OAAyB,EAAA;AAEzB,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,oBAAoB;AACzD,IAAA,IACE,OAAO,CAAC,mBAAmB,KAAK,SAAS;QACzC,OAAO,QAAQ,KAAK,QAAQ;AAC5B,QAAA,QAAQ,CAAC,MAAM,KAAK,CAAC,EACrB;AACA,QAAA,OAAO,OAAO;IAChB;;;;IAIA,MAAM,QAAQ,GAAG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC;AACrD,IAAA,IAAI,gBAAgB,CAAC,QAAQ,CAAC,EAAE;AAC9B,QAAA,OAAO,OAAO;IAChB;IACA,OAAO,EAAE,GAAG,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE;AACtD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AACH,SAAS,kBAAkB,CAAC,QAAgB,EAAE,MAAuB,EAAA;AACnE,IAAA,MAAM,IAAI,GACR,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,KAAK;UACpE,MAAM,CAAC;AACT,UAAE,OAAO,CAAC,GAAG,EAAE;AACnB,IAAA,IAAI;AACF,QAAA,OAAO,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC7E;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,QAAQ;IACjB;AACF;AAEA;;;;;;;;;;;;;;;;AAgBG;AACH,SAAS,gBAAgB,CAAC,QAAgB,EAAA;AACxC,IAAA,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,IAAI,YAAY,CAAC,SAAS,EAAE,qBAAqB,EAAE,CAAC,EAAE;AACpD,QAAA,OAAO,IAAI;IACb;IACA,IAAI,CAAC,gCAAgC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE;AAC/D,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI;AACF,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC;AAClE,QAAA,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa;IAC1E;AAAE,IAAA,MAAM;;AAEN,QAAA,OAAO,KAAK;IACd;AACF;AAEA;;;;;;AAMG;AACH,SAAS,YAAY,CAAC,IAAY,EAAE,KAAa,EAAA;AAC/C,IAAA,MAAM,QAAQ,GAAG,CAAC,IAAY,KAAY;AACxC,QAAA,IAAI,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;AAC5B,QAAA,IAAI;AACF,YAAA,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC1C;AAAE,QAAA,MAAM;;QAER;AACA,QAAA,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,GAAG,QAAQ,CAAC,WAAW,EAAE,GAAG,QAAQ;AACzE,IAAA,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,KAAK,CAAC;AAC3C;AAEA;;;;;;;;AAQG;AACH,SAAS,qBAAqB,GAAA;AAC5B,IAAA,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,gBAAgB,CAAC;AACxE;;;;"}
+{"version":3,"file":"index.mjs","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/lib/transformer.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedTtscMetroOptions } from "./core/options";
+import type { ResolvedTtscMetroOptions } from "./core/TtscMetroOptions";
 /**
  * Resolve Metro's per-file `filename` to an absolute path.
  *
@@ -10,6 +10,39 @@ import type { ResolvedTtscMetroOptions } from "./core/options";
  * 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 declare function resolveAbsoluteFilename(filename: string, options?: Record<string, unknown>): string;
 /**
@@ -19,7 +52,60 @@ export declare function resolveAbsoluteFilename(filename: string, options?: Reco
  * 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 declare function transform(params: {
     src: string;
@@ -48,14 +134,105 @@ export declare 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 declare function getCacheKey(...args: unknown[]): string;
 /**
  * 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 declare function shouldTransform(filename: string, opts: ResolvedTtscMetroOptions): boolean;