@ttsc/metro 0.28.5 → 0.29.0

package/README.md

@@ -41,11 +41,11 @@ module.exports = withTtsc(getDefaultConfig(__dirname));
 
 `withTtsc` sets `transformer.babelTransformerPath` and leaves the rest of your config untouched. It auto-detects the upstream transformer to delegate to (`@expo/metro-config/babel-transformer` for Expo, then `@react-native/metro-babel-transformer`, then the legacy `metro-react-native-babel-transformer`).
 
-If your config already set `transformer.babelTransformerPath`, that transformer is **chained rather than replaced**: the `ttsc` pass runs first and then delegates to it, so wrapping a working config keeps what it configured. This is what makes `react-native-svg-transformer` — whose entire installation is that one assignment — keep working after you adopt `@ttsc/metro`. Pass `upstreamTransformer` explicitly to override both that and auto-detection.
+If your config already set `transformer.babelTransformerPath`, that transformer is **chained rather than replaced**: the `ttsc` pass runs first and then delegates to it, so wrapping a working config keeps what it configured. This is what makes `react-native-svg-transformer`, whose entire installation is that one assignment, keep working after you adopt `@ttsc/metro`. Pass `upstreamTransformer` explicitly to override both that and auto-detection.
 
-The value is resolved from your `projectRoot`, exactly as Metro resolves it, so a relative `"./metro-svg.cjs"` and a bare `"react-native-svg-transformer"` both mean what they mean in your project rather than inside this package. A path that names `@ttsc/metro`'s own transformer is never chained — in any spelling, including a second copy installed elsewhere in your tree — because delegating this transformer into itself would recurse on every file.
+The value is resolved from your `projectRoot`, exactly as Metro resolves it, so a relative `"./metro-svg.cjs"` and a bare `"react-native-svg-transformer"` both mean what they mean in your project rather than inside this package. A path that names `@ttsc/metro`'s own transformer is never chained in any spelling, including a second copy installed elsewhere in your tree, because delegating this transformer into itself would recurse on every file.
 
-Auto-detection only skips a candidate whose entry point is genuinely **not available** — the package is not installed, or it is installed but the requested subpath is not exported (Expo/React Native version skew). A candidate that _does_ resolve but fails while loading — a top-level throw, an incompatible runtime ABI, or a missing peer/transitive dependency — surfaces its original error (as the `cause` of a `@ttsc/metro` wrapper) instead of being treated as absent. This stops a broken Expo/React Native install from silently falling through to the wrong transformer, and stops an explicit `upstreamTransformer` failure from being reported as if the module did not exist.
+Auto-detection only skips a candidate whose entry point is genuinely **not available**: the package is not installed, or it is installed but the requested subpath is not exported (Expo/React Native version skew). A candidate that _does_ resolve but fails while loading, whether from a top-level throw, an incompatible runtime ABI, or a missing peer or transitive dependency, surfaces its original error (as the `cause` of a `@ttsc/metro` wrapper) instead of being treated as absent. This stops a broken Expo/React Native install from silently falling through to the wrong transformer, and stops an explicit `upstreamTransformer` failure from being reported as if the module did not exist.
 
 ## Configuration
 
@@ -80,7 +80,7 @@ The plugin contract and `tsconfig` discovery match the Unplugin integrations. Me
 
 ### Files outside the program
 
-Metro resolves its own module graph, and that graph is not the set of files your `tsconfig` describes. A file Metro delivers that the compiled program does not contain is passed to the upstream transformer untransformed, and reported naming the file and the `tsconfig` it is missing from — once per file per compile in each Metro worker, since a Metro worker has no build boundary to reset the report at:
+Metro resolves its own module graph, and that graph is not the set of files your `tsconfig` describes. A file Metro delivers that the compiled program does not contain is passed to the upstream transformer untransformed, and reported naming the file and the `tsconfig` it is missing from, once per file per compile in each Metro worker, since a Metro worker has no build boundary to reset the report at:
 
 ```
 ttsc: /app/scripts/tool.ts is not part of the program described by /app/tsconfig.json,
@@ -88,7 +88,7 @@ so it was left untransformed. Add it to that project's "include" if ttsc plugins
 should apply to it.
 ```
 
-This is not a build error. The file is simply not this project's to transform, and the usual cause is a Metro graph reaching past the `tsconfig`'s `include` — a source beside `src` rather than inside it, or one in a sibling workspace folder. Add it to that project's `include` if `ttsc` plugins should apply to it.
+This is not a build error. The file is simply not this project's to transform, and the usual cause is a Metro graph reaching past the `tsconfig`'s `include`, such as a source beside `src` rather than inside it or one in a sibling workspace folder. Add it to that project's `include` if `ttsc` plugins should apply to it.
 
 The report matters because passing through is not the same as leaving alone: a file that skips the `ttsc` pass keeps whatever plugin-driven syntax it carries, which fails at runtime rather than at build time. Declaration and JavaScript files never reach the pass at all, so they are not reported; they are filtered before it, as `include` / `exclude` above describes.
 
@@ -96,13 +96,15 @@ This is the shared core's answer rather than Metro's own, so every `@ttsc/unplug
 
 ## Cache invalidation
 
-Metro keys its transform cache on each file's own content plus one static transformer key, and its babel-transformer contract has no per-file dependency registration. A `ttsc` transform can depend on a _type_ in another file, so `@ttsc/metro` folds a project fingerprint into that static key: every regular file reached by the non-following project walk, plus reference-graph inputs outside that walk (`node_modules` declarations, monorepo sibling sources, files reached through symlinks or Windows junctions, and out-of-root tsconfig `extends` ancestry) recorded under `node_modules/.cache/ttsc-metro`. Editing any of them re-keys the next run, so `metro bundle` and dev-server starts pick up cross-file type changes without `--reset-cache`.
+Metro keys its transform cache on each file's own content plus one static transformer key, and its babel-transformer contract has no per-file dependency registration. A `ttsc` transform can depend on a _type_ in another file, so `@ttsc/metro` folds a project fingerprint into that static key: every regular file reached by the project walk, every effective config source, and transform inputs recorded under `node_modules/.cache/ttsc-metro`. In a workspace with nested or directory-linked `tsconfig.json` projects, each lexical subtree is walked under the nearest config that transformed files use; the project-map traversal follows symlinks and Windows junctions while a physical ancestor set cuts cycles without collapsing independent aliases. The project map itself is hashed so adding or removing a nested or linked project config also changes the key. Worker discovery retains the exact candidate predicates that selected its project instead of reconstructing them after selection. A module passed through because its Program has no output still records those candidates and the universal config inputs that can later admit it. `withTtsc` gives each run a private identity, `getCacheKey` records the exact file state and static coverage that identity hashed, and workers compare every derived input's compiler-generation hash, realpath, or resolution predicate with that baseline. Inputs outside proven static coverage stay in one batched worker snapshot. A missing input, an out-of-root `watchFolders` project, a symlink or Windows junction transition, an `extends` change, or any A-to-B-to-A change between static keying and transformation taints the observation and rotates the next snapshot epoch, so it cannot collide with the earlier A key. Editing any fingerprinted input re-keys the next run, so `metro bundle` and dev-server starts pick up cross-file type changes without `--reset-cache`.
+
+Snapshot compaction is serialized across Metro config processes. If two builds prepare the same project cache at once, one compacts the shared worker documents and the contender uses a private non-reusable key for that run instead of racing the main snapshot rewrite.
 
 The granularity is project-level by necessity: Metro evaluates the transformer key once per run, so any fingerprinted change re-transforms every file on the next run. What remains outside the mechanism's reach:
 
 - **Within a running dev server**, Metro re-transforms only files its watcher reports changed. Editing a type in file B updates a dependent file A on A's next transform: save A, or restart the dev server (no `--reset-cache` needed).
 - **Files a plugin declares `volatile`** depend on non-file inputs that no fingerprint can represent; while a volatile declaration is recorded, cross-run cache reuse is disabled entirely.
-- **If snapshot persistence fails**, a recovery document beside `node_modules/.cache/ttsc-metro` makes every later key non-reusable until the pending observations are compacted under a fresh epoch; if an older readable snapshot exists and neither the snapshot nor recovery location is writable, the transform fails instead of authorizing stale reuse.
+- **If snapshot persistence fails**, a recovery document beside `node_modules/.cache/ttsc-metro` makes every later key non-reusable until the pending observations are compacted under a fresh epoch. If preparation cannot persist even that document, its run token forces a nonce across bundle and process boundaries. A worker whose run token authorized a reusable key fails the transform if neither location accepts its observation, even when the old main snapshot is temporarily unreadable.
 
 ## Caveats (v1)
 

package/lib/core/fingerprint.d.ts

@@ -14,20 +14,20 @@
  *   `projectRoot` plus the resolved tsconfig's directory when it lies outside),
  *   hashed with the exact walk universe the `@ttsc/unplugin` transform core
  *   validates its own cache against.
- * - **Recorded out-of-walk inputs.** The transform core cannot walk files outside
- *   the roots or under ignored directories, but the host-owned reference graph
- *   (samchon/ttsc#718) reports them per transform. Workers record them into a
- *   snapshot under `node_modules/.cache/ttsc-metro`; the next run's
- *   `getCacheKey` re-hashes the recorded set.
+ * - **Recorded transform inputs.** The host-owned reference graph
+ *   (samchon/ttsc#718) reports each transform's derived inputs. Workers retain
+ *   them under `node_modules/.cache/ttsc-metro`, compare their generation state
+ *   with the exact main-process key baseline, and batch one durable write per
+ *   delivered module.
  *
  * Snapshot layout: one main file carrying a random epoch id plus per-worker
  * files with unique names, so concurrent workers never race a shared write.
- * `withTtsc` (the single config process, before workers exist) compacts worker
- * files into the main file. Readers take the union of every file, reading the
- * worker files strictly before the main file: the compactor renames the merged
- * main into place strictly before deleting a worker file, so a worker file that
- * disappears mid-read is always already merged into the main the reader loads
- * afterwards.
+ * `withTtsc` compacts worker files into the main file before its workers exist,
+ * under a process-shared lock for builds using the same project cache. Readers
+ * take the union of every file, reading the worker files strictly before the
+ * main file: the compactor renames the merged main into place strictly before
+ * deleting a worker file, so a worker file that disappears mid-read is always
+ * already merged into the main the reader loads afterwards.
  *
  * Sound degradations, by design:
  *
@@ -43,16 +43,22 @@
  *   until a later run records the volatile declaration gone.
  * - A recorded input that disappears hashes as a stable `missing` marker, so
  *   deletion and reappearance both move the key.
+ * - A worker state that differs from the static key's run baseline taints the
+ *   observation; compaction rotates the epoch so even A -> B -> A cannot reuse
+ *   output stored under the earlier A key.
  */
 import { readProjectMembershipPolicy } from "@ttsc/unplugin/api";
+import type { TtscProjectDiscoveryFilesystem, TtscProjectTreeDiscoveryFilesystem, TtscWatchInput } from "@ttsc/unplugin/api";
 /** Union of the snapshot state readable on disk. */
 interface SnapshotState {
     /** Random epoch id minted when the main snapshot was created. */
     id: string;
-    /** Absolute paths of every recorded out-of-walk input. */
+    /** Absolute paths of every recorded derived transform input. */
     files: string[];
     /** Whether any recorded transform declared volatile output. */
     volatile: boolean;
+    /** Whether a transform observed state different from its run's static key. */
+    tainted: boolean;
 }
 /**
  * Resolve the base directory both fingerprint sides agree on: Metro's
@@ -68,8 +74,8 @@ export declare function resolveFingerprintBase(projectRoot: string | undefined):
  * already inside the base walk (an explicit out-of-root `project`, or a
  * monorepo-root tsconfig discovered above the app). Matching the transform
  * core's own validation universe keeps the invariant simple: everything the
- * core treats as an input is fingerprinted, either by a walk here or by the
- * recorded out-of-walk snapshot.
+ * core treats as an input is fingerprinted by the walk, the recorded snapshot,
+ * or both.
  */
 export declare function fingerprintRoots(base: string, explicitProject: string | undefined): string[];
 /**
@@ -87,10 +93,18 @@ export declare function fingerprintRoots(base: string, explicitProject: string |
 export interface TtscMetroProjectView {
     /** The base directory both fingerprint sides agree on. */
     readonly base: string;
+    /** Config candidates observed while selecting this transform's project. */
+    readonly discoveryInputs: readonly TtscWatchInput[];
     /** The caller's explicit `project`, if any. */
     readonly explicitProject: string | undefined;
     /** The membership policy resolved for that project. */
     readonly policy: ReturnType<typeof readProjectMembershipPolicy>;
+    /** The policy used by the routed static walk. */
+    readonly walkPolicy: ReturnType<typeof readProjectMembershipPolicy>;
+    /** Lexical roots whose fingerprint uses this project's policy. */
+    readonly roots: readonly string[];
+    /** The exact config selected for this project. */
+    readonly tsconfig: string;
 }
 /**
  * Resolve one transform's project view, once, for every watch input it reports.
@@ -102,6 +116,8 @@ export interface TtscMetroProjectView {
 export declare function resolveProjectView(props: {
     compilerOptions?: Record<string, unknown>;
     explicitProject?: string;
+    filename?: string;
+    projectDiscoveryFilesystem?: TtscProjectDiscoveryFilesystem;
     projectRoot?: string;
 }): TtscMetroProjectView;
 /**
@@ -112,22 +128,28 @@ export declare function resolveProjectView(props: {
 export declare function computeProjectFingerprint(props: {
     compilerOptions?: Record<string, unknown>;
     explicitProject?: string;
+    /** Test seam for proving that incomplete implicit enumeration fails closed. */
+    projectDiscoveryFilesystem?: TtscProjectTreeDiscoveryFilesystem;
     projectRoot?: string;
+    /** Private identity transported from `withTtsc` to this Metro run. */
+    runId?: string;
 }): string;
 /**
- * Prepare the snapshot for a new run. Called from `withTtsc` in the single
- * Metro config process, before any worker exists: creates the main snapshot
- * (fresh epoch id) when missing or corrupt, compacts leftover worker files into
- * it, and sweeps unparseable worker files plus crash-leftover temp files. An
- * unparseable worker file's recordings are unrecoverable, so its removal mints
- * a fresh epoch id — every key that might have depended on the lost recordings
- * is soundly orphaned, and later runs stabilize instead of degrading to a nonce
- * forever. A failed rewrite leaves a recovery document outside the snapshot
- * directory so `getCacheKey` degrades to a nonce until a later compaction
- * succeeds. If an older readable main exists and neither location is writable,
- * preparation throws instead of authorizing stale reuse.
+ * Prepare the snapshot for a new run. Called from `withTtsc` before any worker
+ * exists: creates the main snapshot (fresh epoch id) when missing or corrupt,
+ * compacts leftover worker files into it, and sweeps unparseable worker files
+ * plus crash-leftover temp files. Concurrent config processes are serialized; a
+ * contender takes a non-reusable run token instead of racing the mutable main
+ * rewrite. An unparseable worker file's recordings are unrecoverable, so its
+ * removal mints a fresh epoch id — every key that might have depended on the
+ * lost recordings is soundly orphaned, and later runs stabilize instead of
+ * degrading to a nonce forever. A failed rewrite leaves a recovery document
+ * outside the snapshot directory and returns a non-reusable run token. The
+ * token crosses bundle and process boundaries, so `getCacheKey` degrades to a
+ * nonce even when neither snapshot location can persist the failure and an old
+ * main later reappears.
  */
-export declare function prepareSnapshot(projectRoot: string | undefined): void;
+export declare function prepareSnapshot(projectRoot: string | undefined): string;
 /**
  * Read the unioned snapshot state, or `undefined` when the main snapshot is
  * missing or any snapshot file is corrupt (a torn or foreign write means the
@@ -135,16 +157,15 @@ export declare function prepareSnapshot(projectRoot: string | undefined): void;
  */
 export declare function readSnapshotState(base: string): SnapshotState | undefined;
 /**
- * Recorder held by each Metro worker. It persists out-of-walk watch inputs and
- * missing in-walk paths delivered through the transform core's `addWatchFile`
- * hook, plus any volatile declaration. Existing in-walk files stay covered by
- * the project walk; a missing path must be retained because its creation is a
- * state change that the initial walk could not hash. A clean in-walk transform
- * also writes a document so it can clear a volatile declaration from an earlier
- * run. The unique name makes worker writes race-free; `withTtsc` compacts the
- * files on the next run.
+ * Recorder held by each Metro worker. It persists every derived watch input and
+ * any volatile declaration, compares compiler-generation evidence with the
+ * matching main-process run baseline, and marks any temporal mismatch tainted.
+ * A clean transform also writes a document so it can clear a volatile
+ * declaration from an earlier run. One cumulative document is flushed per
+ * delivered module; the unique name makes worker writes race-free, and
+ * `withTtsc` compacts the files on the next run.
  */
-export declare function createSnapshotRecorder(): {
+export declare function createSnapshotRecorder(runId?: string): {
     record: (props: {
         input: string;
         /**
@@ -159,15 +180,15 @@ export declare function createSnapshotRecorder(): {
          * compiler-options overlay reached one half and not the other, and the
          * input was then covered by neither (samchon/ttsc#1316).
          *
-         * Resolving it once per transform is also what makes it affordable.
-         * `record` runs once per watch input rather than once per file, and
-         * validating the memo means stat-ing the whole `extends` chain, measured at
-         * 12 microseconds per stat — a few thousand modules times fifteen inputs
-         * each cost over half a second per run for an answer that cannot change
-         * between two inputs of one file.
+         * Resolving it once per transform also keeps every entry in the module's
+         * batch attached to the exact same config graph and policy.
          */
         project: TtscMetroProjectView;
     }) => void;
+    recordMany: (props: {
+        inputs: readonly TtscWatchInput[];
+        project: TtscMetroProjectView;
+    }) => void;
     recordVolatile: (props: {
         project: TtscMetroProjectView;
     }) => void;