@exodus/stasis 1.0.0-beta.1 → 1.0.0-beta.3

package/src/loaders/rust.js

@@ -1,17 +1,7 @@
-// Rust loader: produces a `{ sources, resolutions, missing }` triple from a
-// crate's source files, mirroring the Solidity/Bash loaders' interface. The
+// Rust loader: `{ sources, resolutions, missing }` from a crate's files. The
 // reachable set is discovered by following `mod foo;` declarations (the only
-// thing that pulls a new file into a crate); `use crate::path` statements
-// don't add files, they just reference already-declared modules, so they're
-// resolved against the module tree for the import graph but never widen the walk.
-//
-// `use crate::` resolution is best-effort (external crates, macro paths, and
-// item-vs-module ambiguity are simply dropped). An unconditional `mod foo;`
-// with no backing file is a genuine hole (a compile error in a real crate) and
-// is reported in `missing` so the bundle builder can reject it; a cfg-gated
-// `mod` (e.g. `#[cfg(test)] mod tests;`) may be compiled out and is tolerated.
-// Comments are stripped before extraction so a commented-out `mod`/`use` is
-// neither followed nor flagged.
+// thing that pulls a new file in); `use crate::` edges resolve against the
+// module tree for the import graph but never widen the walk.
 
 import { realpathSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -19,48 +9,33 @@ import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path
 
 import { assertRealPathWithinBase } from '@exodus/stasis-core/util'
 
-// `mod foo;` / `pub mod foo;` / `pub(crate) mod foo;` — external module
-// declarations only. Inline `mod foo { ... }` is intentionally NOT matched.
-// Applied per (trimmed) line, so it stays anchored at the line start.
+// External `mod foo;` declarations only; inline `mod foo { ... }` is intentionally not matched.
 const MOD_DECL_RE = /^(?:pub(?:\([^)]*\))?\s+)?mod\s+(\w+)\s*;/u
 
-// `crate::path::to::item` references (in `use` or expression position).
 const USE_CRATE_RE = /\bcrate(?:::\w+)+/gu
 
-// `cargo vendor` copies external crates in-tree under this directory; their
-// sources are pulled into the bundle and tagged `cargo` (see cmd/bundle.js).
+// `cargo vendor` copies external crates in-tree under this dir.
 const VENDOR_DIR = 'vendor'
 
-// `extern crate foo;` and the leading segment of any `foo::path` use/expr path.
-// The leading segment of a path that ISN'T crate/self/super or a std-family
-// root is a candidate external crate name; resolveVendoredCrate keeps only the
-// ones that actually exist under vendor/. The lead must start lowercase to skip
-// `Type::assoc` associated-item paths (crate names are snake_case by convention).
+// `extern crate foo;` and the leading segment of any `foo::path`. The lead must
+// start lowercase (`[a-z_]`) to skip `Type::assoc` associated-item paths.
 const EXTERN_CRATE_RE = /^(?:pub\s+)?extern\s+crate\s+(\w+)\s*;/u
 const PATH_LEAD_RE = /\b([a-z_]\w*)(?:::\w+)+/gu
 const NON_CRATE_LEADS = new Set(['crate', 'self', 'super', 'std', 'core', 'alloc'])
 
-// A `#[cfg(...)]` / `#[cfg_attr(...)]` attribute gates the next item on a build
-// configuration that may be off (e.g. `#[cfg(test)]`).
+// `#[cfg(...)]`/`#[cfg_attr(...)]` gates the next item on a config that may be off.
 const CFG_ATTR_RE = /^#\[\s*cfg(?:_attr)?\b/u
 
-// Strip `//` line comments and `/* */` block comments so a commented-out
-// `mod`/`use` isn't mistaken for a real one — a commented `mod foo;` with no
-// backing file would otherwise be reported as a fatal "missing module".
-// Newlines inside block comments are preserved so the per-line matching below
-// stays aligned. Not string-literal aware (a `//` or `/* */` inside a string
-// can't masquerade as a line-anchored `mod` decl, so it doesn't matter for
-// extraction), and nested block comments aren't handled — both are acceptable
-// for best-effort extraction and match the Solidity loader's fidelity.
+// Strip comments so a commented-out `mod`/`use` isn't taken for a real one (a
+// commented `mod foo;` with no file would be a false "missing module").
+// Newlines in block comments are preserved to keep the per-line matching aligned.
 function stripRustComments(content) {
   const noBlock = content.replace(/\/\*[\s\S]*?\*\//gu, (m) => m.replace(/[^\n]/gu, ' '))
   return noBlock.replace(/\/\/[^\n]*/gu, '')
 }
 
-// Extract external `mod <name>;` declarations as { name, conditional } records.
-// `conditional` is true when a `#[cfg(...)]` attribute gates the declaration:
-// such a module may be compiled out (e.g. `#[cfg(test)] mod tests;`), so the
-// bundle builder treats its absence as tolerable rather than fatal.
+// Extract external `mod <name>;` as { name, conditional } records; `conditional`
+// (a `#[cfg(...)]`-gated decl) may be compiled out, so its absence is tolerable.
 export function extractModDecls(content) {
   const decls = []
   let cfgPending = false
@@ -84,10 +59,8 @@ export function extractCrateUses(content) {
   return [...stripRustComments(content).matchAll(USE_CRATE_RE)].map((m) => m[0])
 }
 
-// Candidate external-crate names referenced by a file: `extern crate <name>;`
-// plus the leading segment of every `<name>::...` path (minus crate/self/super
-// and the std family). Best-effort and deliberately over-inclusive — a lead
-// that doesn't name a real vendored crate is dropped by resolveVendoredCrate.
+// Candidate external-crate names (best-effort, over-inclusive — bad leads are
+// dropped later by resolveVendoredCrate).
 export function extractExternalCrates(content) {
   const stripped = stripRustComments(content)
   const names = new Set()
@@ -101,12 +74,8 @@ export function extractExternalCrates(content) {
   return [...names]
 }
 
-// Resolve an external crate name to its vendored crate-root file
-// (`vendor/<dir>/src/lib.rs`), or null when no such crate is vendored. A Rust
-// `use` name is the crate's lib name (underscores); the on-disk vendor dir uses
-// the package name, which may hyphenate — so try the name as-is and with
-// underscores swapped for hyphens. Existence is checked against `knownSources`
-// (tree mode) or the filesystem under `baseDir` (walk mode).
+// Resolve a crate name to its vendored root (`vendor/<dir>/src/lib.rs`), or null.
+// `use` names underscore but the vendor dir may hyphenate, so try both spellings.
 export function resolveVendoredCrate(crateName, { knownSources, baseDir, vendorDir = VENDOR_DIR } = {}) {
   const dirs = crateName.includes('_') ? [crateName, crateName.replaceAll('_', '-')] : [crateName]
   for (const dir of dirs) {
@@ -122,9 +91,8 @@ export function resolveVendoredCrate(crateName, { knownSources, baseDir, vendorD
   return null
 }
 
-// The directory where this file's submodules live, per Rust's path rules:
-//   - crate roots (main.rs/lib.rs) and mod.rs hold submodules as siblings
-//   - any other foo.rs holds them under a foo/ subdirectory
+// Directory holding this file's submodules, per Rust's path rules: siblings for
+// crate roots (main.rs/lib.rs) and mod.rs, else under a `<stem>/` subdir.
 export function getModuleDir(filePath) {
   const lastSlash = filePath.lastIndexOf('/')
   const dir = lastSlash === -1 ? '' : filePath.slice(0, lastSlash)
@@ -134,10 +102,7 @@ export function getModuleDir(filePath) {
   return dir ? `${dir}/${stem}` : stem
 }
 
-// Resolve a `mod <name>;` declaration to the baseDir-relative file that
-// defines it, trying `<dir>/<name>.rs` then `<dir>/<name>/mod.rs`. Existence
-// is checked against `knownSources` (tree mode) or the filesystem under
-// `baseDir` (walk mode); returns null when neither finds a file.
+// Resolve `mod <name>;` to its file, trying `<dir>/<name>.rs` then `<dir>/<name>/mod.rs`.
 export function resolveModPath(modName, fromFile, { knownSources, baseDir } = {}) {
   const modDir = getModuleDir(fromFile)
   const base = modDir ? `${modDir}/${modName}` : modName
@@ -154,22 +119,14 @@ export function resolveModPath(modName, fromFile, { knownSources, baseDir } = {}
   return null
 }
 
-// Build a `module path -> file` map (e.g. "crate::foo::bar" -> "src/foo/bar.rs")
-// by walking `mod` edges out from every crate root (main.rs / lib.rs). The walk
-// is iterative (a deep `mod` chain would overflow a recursive descent) and
-// depth-bounded: a `seen` set stops mod cycles, and MAX_MODULE_DEPTH caps a
-// pathologically deep chain — both the descent and the O(depth²) growth of the
-// joined module-path strings. Real crates nest a handful deep; the cap only
-// ever trims best-effort `use crate::` resolution for absurd input (file
-// collection happens in collectRustFilesFromDisk, which is unaffected).
+// Cap on `mod`-chain depth when building the module tree: with the `seen` set it
+// bounds cycles and the O(depth²) growth of joined module-path strings on absurd input.
 const MAX_MODULE_DEPTH = 1000
 
 export function buildModuleTree(sources, resolutions, { vendorDir = null } = {}) {
   const tree = new Map()
   for (const filePath of sources.keys()) {
-    // A vendored crate is its own crate, not part of the project crate rooted
-    // at `crate::` — skip its root so its tree doesn't collide on the `crate`
-    // key (its internal `crate::` edges are left best-effort/unresolved).
+    // Skip vendored crate roots: they're separate crates and would collide on the `crate` key.
     if (vendorDir && filePath.startsWith(`${vendorDir}/`)) continue
     const name = filePath.includes('/') ? filePath.slice(filePath.lastIndexOf('/') + 1) : filePath
     if (name !== 'main.rs' && name !== 'lib.rs') continue
@@ -191,9 +148,8 @@ export function buildModuleTree(sources, resolutions, { vendorDir = null } = {})
   return tree
 }
 
-// Resolve a `crate::a::b::Item` path to the file of the deepest module along
-// it (the trailing item names aren't modules), e.g. `crate::foo::Bar` ->
-// the file for `crate::foo`. Returns null when no prefix names a module.
+// Resolve `crate::a::b::Item` to the deepest module prefix that names a file
+// (trailing item names aren't modules); null when none does.
 export function resolveUsePath(usePath, moduleTree) {
   const parts = usePath.split('::')
   for (let i = parts.length; i >= 1; i--) {
@@ -203,12 +159,9 @@ export function resolveUsePath(usePath, moduleTree) {
   return null
 }
 
-// Build the { sources, resolutions, missing } triple from a Map of
-// already-loaded Rust sources. Two-phase: resolve `mod` edges (which also
-// defines the module tree), then resolve `crate::` references against it.
-// An unconditional `mod foo;` with no file is recorded in `missing` (the
-// bundle builder treats it as fatal); a cfg-gated `mod`, unresolved `crate::`
-// references, and self/duplicate references are omitted.
+// Build the triple from already-loaded sources. Two-phase: resolve `mod` edges
+// (defining the module tree), then `crate::` refs against it. Unconditional
+// `mod` with no file → `missing` (fatal); cfg-gated/unresolved/self refs omitted.
 export function buildRustTree(sources) {
   const resolutions = new Map()
   const missing = []
@@ -222,17 +175,15 @@ export function buildRustTree(sources) {
         console.warn(`[loader.rust] Missing module: ${name} from ${path}`)
         missing.push({ spec: `mod ${name}`, from: path })
       }
-      // conditional && unresolved: a cfg-gated module that may be compiled out
-      // (e.g. #[cfg(test)] mod tests;) — tolerated, not a fatal hole.
+      // conditional && unresolved: cfg-gated module, may be compiled out — tolerated.
     }
     resolutions.set(path, specMap)
   }
 
   const moduleTree = buildModuleTree(sources, resolutions, { vendorDir: VENDOR_DIR })
   for (const [path, content] of sources) {
-    // Vendored crates keep their (file-relative) `mod` edges from above, but
-    // their `crate::`/external `use` edges are dropped rather than mis-resolved
-    // against the project crate's module tree.
+    // Vendored crates keep their `mod` edges but skip `crate::`/`use` resolution
+    // (their edges would mis-resolve against the project crate's tree).
     if (path.startsWith(`${VENDOR_DIR}/`)) continue
     const specMap = resolutions.get(path)
     for (const usePath of extractCrateUses(content)) {
@@ -241,8 +192,6 @@ export function buildRustTree(sources) {
         specMap.set(usePath, resolved)
       }
     }
-    // A `use <crate>::…` of a vendored crate becomes a `use <crate>` edge to
-    // that crate's root, recording the cross-crate dependency in the graph.
     for (const crate of extractExternalCrates(content)) {
       const lib = resolveVendoredCrate(crate, { knownSources: sources })
       const spec = `use ${crate}`
@@ -252,9 +201,8 @@ export function buildRustTree(sources) {
   return { sources, resolutions, missing }
 }
 
-// Walk the filesystem from `entries`, following `mod` declarations and reading
-// each reachable file once. A `mod` whose file is missing on disk warns and is
-// skipped; the walk continues. Files in a wave are read in parallel.
+// Walk from `entries` following `mod` decls, reading each reachable file once;
+// a missing file warns and is skipped without aborting the walk.
 export async function collectRustFilesFromDisk(baseDir, entries) {
   const sources = new Map()
   const realBase = realpathSync(baseDir)
@@ -272,8 +220,7 @@ export async function collectRustFilesFromDisk(baseDir, entries) {
             console.warn(`[loader.rust] Missing file: ${relPath}`)
             return null
           }
-          // resolveModPath gates candidates with isFile so a directory is
-          // normally never queued; guard EISDIR anyway (symmetry with bash).
+          // resolveModPath gates on isFile so a dir is normally never queued; guard EISDIR anyway.
           if (err.code === 'EISDIR') {
             console.warn(`[loader.rust] Skipping directory reference: ${relPath}`)
             return null
@@ -291,8 +238,7 @@ export async function collectRustFilesFromDisk(baseDir, entries) {
         const resolved = resolveModPath(name, relPath, { baseDir })
         if (resolved && !sources.has(resolved)) next.push(resolved)
       }
-      // Follow `use <crate>::…` into a vendored crate's root; its own `mod`
-      // edges (read on the next wave) then pull in the rest of the crate.
+      // Follow `use <crate>::…` to the vendored root; its `mod` edges pull in the rest next wave.
       for (const crate of extractExternalCrates(content)) {
         const lib = resolveVendoredCrate(crate, { baseDir })
         if (lib && !sources.has(lib)) next.push(lib)
@@ -315,10 +261,8 @@ function assertWithinBase(baseDir, candidate, label) {
   }
 }
 
-// High-level: takes a `.rs.txt` listing whose lines are crate entry points
-// (typically src/main.rs or src/lib.rs), resolved relative to the listing.
-// Walks `mod` declarations from there, then resolves `crate::` references.
-// Returns { sources, resolutions, missing }.
+// High-level entry: reads a `.rs.txt` listing of crate entry points (relative to
+// the listing), then walks `mod`/`crate::` from there.
 export async function loadRust(rsTxtFile) {
   const baseDir = dirname(resolve(rsTxtFile))
   const listing = await readFile(rsTxtFile, 'utf8')

package/src/loaders/solidity.js

@@ -1,9 +1,7 @@
 // Based on DeepView's Solidity loader.
 // https://github.com/PreventiveMeasures/deepview/blob/main/src/loaders/solidity.js
-//
-// Adapted to produce a `{ sources, resolutions }` pair only. The mapping
-// file (foundry.toml or remappings.txt) is read to extract `remappings`,
-// but is itself not included in `sources`.
+// Produces a `{ sources, resolutions }` pair; the mapping file (foundry.toml /
+// remappings.txt) is read for `remappings` but not included in `sources`.
 
 import { realpathSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -32,20 +30,11 @@ export function parseRemappings(content) {
   }).filter(Boolean)
 }
 
-// Resolve a Solidity import specifier to a baseDir-relative POSIX path,
-// trying four strategies in order:
-//   1. user remappings (longest prefix wins)
-//   2. relative path (`./...` or `../...`); traversal above the project
-//      root returns null instead of clamping
-//   3. Node's CJS resolver via createRequire, anchored at the importing
-//      source — only when `baseDir` is provided and the specifier looks
-//      like a scoped npm package (`@scope/pkg/sub/path`)
-//   4. project-relative fallback: when `baseDir` is provided and a file
-//      exists at `<baseDir>/<specifier>`, accept the specifier as-is.
-//      Equivalent to an implicit `<top>/=<top>/` remapping for any
-//      top-level directory in the project. Lets Foundry-style
-//      `import "src/Foo.sol"` work without an explicit remapping.
-// Returns null when no strategy resolves the import.
+// Resolve a Solidity import to a baseDir-relative POSIX path, trying in order:
+// (1) remappings (longest prefix wins); (2) relative `./`/`../` (root-escape ->
+// null, not clamped); (3) Node CJS resolver for scoped npm packages
+// (`@scope/pkg/...`); (4) project-relative fallback if the file exists. Returns
+// null when nothing resolves.
 export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir } = {}) {
   let best = null
   for (const { prefix, target } of remappings) {
@@ -75,12 +64,9 @@ export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir
     return resolved.join('/')
   }
 
-  // Node-style `@scope/pkg/sub/path`. createRequire is anchored at the
-  // importing source so nested node_modules resolve like Node would
-  // (a file under `node_modules/foo/` finds its deps in
-  // `foo/node_modules/` before walking up). `..` segments in the
-  // subpath are rejected so a crafted specifier can't escape the
-  // resolved package via require.resolve's own path normalization.
+  // Node-style `@scope/pkg/sub/path`. createRequire is anchored at the importing
+  // source so nested node_modules resolve like Node. `..` segments in the subpath
+  // are rejected so a crafted specifier can't escape the resolved package.
   if (baseDir && specifier.startsWith('@')) {
     const parts = specifier.split('/')
     if (parts.length < 3) return null
@@ -92,12 +78,9 @@ export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir
     } catch { /* package missing, exports map blocks the subpath, … */ }
   }
 
-  // Project-relative fallback: when nothing else resolved, accept the
-  // spec as-is if a real file sits at `<baseDir>/<spec>`. statSync's
-  // isFile() guard keeps directories and other non-files from being
-  // queued for readFile (which would surface as EISDIR mid-walk). `./`
-  // and `../` specs are already routed through the relative branch
-  // above, so we only see bare specs here.
+  // Project-relative fallback: accept the spec as-is if a real file sits at
+  // `<baseDir>/<spec>`. The isFile() guard keeps directories out of the read
+  // queue (they'd surface as EISDIR mid-walk). Only bare specs reach here.
   if (baseDir && !isAbsolute(specifier)) {
     const rel = relative(baseDir, resolve(baseDir, specifier)).split(/[\\/]/u).join('/')
     if (rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)) {
@@ -110,13 +93,10 @@ export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir
   return null
 }
 
-// Build the { sources, resolutions, missing } triple from a Map of
-// already-loaded Solidity sources plus optional remappings. Imports that
-// resolve via remappings/relative/Node win; as a final fallback an
-// import specifier that matches a stored key verbatim (etherscan
-// bundles, hardhat flat layouts) is accepted. `missing` lists every
-// (spec, from) pair that could not be resolved or that resolved to a
-// file not loaded into `sources`.
+// Build `{ sources, resolutions, missing }` from already-loaded Solidity sources
+// plus optional remappings. Imports resolve via remappings/relative/Node; as a
+// final fallback a specifier matching a stored key verbatim is accepted. `missing`
+// lists every (spec, from) pair that didn't resolve or resolved outside `sources`.
 export function buildSolidityTree(sources, { remappings = [], baseDir } = {}) {
   const resolutions = new Map()
   const missing = []
@@ -138,12 +118,9 @@ export function buildSolidityTree(sources, { remappings = [], baseDir } = {}) {
   return { sources, resolutions, missing }
 }
 
-// Walk the filesystem starting from `entries`, following resolved
-// imports and reading each file exactly once. Files in the same wave
-// are read in parallel; the next wave depends on the imports
-// discovered in the previous one. Caller-listed entries are also
-// accepted as verbatim non-relative import targets (Foundry-style
-// `import "src/A.sol"`).
+// Walk the filesystem from `entries`, following resolved imports and reading each
+// file once (same-wave reads run in parallel). Caller-listed entries are also
+// accepted as verbatim non-relative import targets (Foundry-style `import "src/A.sol"`).
 export async function collectSolidityFilesFromDisk(baseDir, entries, remappings) {
   const sources = new Map()
   const knownEntries = new Set(entries)
@@ -188,17 +165,16 @@ export async function collectSolidityFilesFromDisk(baseDir, entries, remappings)
   return sources
 }
 
-// Read a foundry.toml or remappings.txt mapping file and return its parsed
-// remappings. The mapping file itself is NOT included in the loaded sources.
+// Read a foundry.toml/remappings.txt mapping file -> parsed remappings (the file
+// itself is not added to sources).
 export async function readRemappingsFile(mappingFile) {
   const content = await readFile(mappingFile, 'utf8')
   if (mappingFile.endsWith('.toml')) return parseRemappingsFromToml(content)
   return parseRemappings(content)
 }
 
-// Reject absolute paths and `..`-escaping paths in a `.sol.txt` listing so
-// a malicious or sloppy listing can't trick the loader into reading
-// arbitrary files outside the listing's own directory.
+// Reject absolute and `..`-escaping paths in a `.sol.txt` listing so it can't
+// trick the loader into reading files outside the listing's directory.
 function assertWithinBase(baseDir, candidate, label) {
   if (isAbsolute(candidate)) throw new Error(`${label} must not be absolute: ${candidate}`)
   const rel = relative(baseDir, resolve(baseDir, candidate)).split(/[\\/]/u).join('/')
@@ -207,10 +183,9 @@ function assertWithinBase(baseDir, candidate, label) {
   }
 }
 
-// High-level: takes an optional .sol.txt listing file. The first line may
-// be a `*.toml` or `remappings.txt` mapping file (resolved relative to the
-// listing); the remaining lines are `*.sol` files. Mirrors the DeepView
-// loader's interface.
+// High-level entry: a `.sol.txt` listing whose optional first line is a
+// `*.toml`/`remappings.txt` mapping file (resolved relative to the listing); the
+// remaining lines are `*.sol` files.
 export async function loadSolidity(solTxtFile) {
   const baseDir = dirname(resolve(solTxtFile))
   const listing = await readFile(solTxtFile, 'utf8')

package/src/metro-resolver.js

@@ -0,0 +1,165 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs'
+import { createRequire, isBuiltin } from 'node:module'
+import { dirname, isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { isTypeDeclaration } from '@exodus/stasis-core/util'
+
+// Adapter that drives the PROJECT's own `metro-resolver` from stasis's static scanner, so
+// `stasis bundle --metro --metro-resolver` resolves modules EXACTLY the way that project's
+// installed Metro does -- rather than the hand-rolled Metro/RN approximation in
+// resolve-fields.js. `metro-resolver` is a leaf of the Metro toolchain (it takes a context of
+// filesystem callbacks and does no I/O of its own), so we load whichever copy the project
+// already ships and feed it a synchronous, disk-backed ResolutionContext.
+//
+// Returns, for each specifier, the same shape scan.js expects from a custom resolver:
+//   { url }      resolved to a real file (file: URL string)
+//   { empty }    a browser/react-native field mapped it to `false` (empty module)
+//   { builtin }  a Node builtin (Metro itself has none; we classify a bare-name miss)
+//   null         unresolved
+//
+// It is deliberately version-agnostic: it never imports metro-resolver internals (the
+// `./private/*` subpath), only the public `resolve`. `resolve` applies the browser-field
+// redirect via its own bundled helper, so the `redirectModulePath` we place on the context is
+// an inert placeholder that satisfies the type but is never consulted for base resolution.
+
+function readJson(file) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return null // absent / unreadable -- no package manifest here
+  }
+  // A manifest that EXISTS but is malformed must fail closed (Metro would throw, not resolve past it).
+  try {
+    return JSON.parse(text)
+  } catch (cause) {
+    throw new Error(`Invalid package.json: ${file}`, { cause })
+  }
+}
+
+// 'f' | 'd' | null for a path, without throwing.
+function pathType(p) {
+  try {
+    const s = statSync(p)
+    return s.isFile() ? 'f' : s.isDirectory() ? 'd' : null
+  } catch {
+    return null
+  }
+}
+
+// A `.d.ts` is types-only, erased at runtime, so the resolver must never land on one: report it as
+// non-existent to Metro's filesystem hooks and a package whose entry points at a declaration falls
+// through to its real `.js`. Only the RESOLUTION hooks use this -- getPackageForModule's own
+// dir-vs-file probe stays on raw pathType (it locates package scopes, never a module target).
+const resolvableType = (p) => (isTypeDeclaration(p) ? null : pathType(p))
+
+// Metro's `getPackageForModule`: the closest package scope for an absolute candidate path
+// (which need not exist). The candidate can be a package DIRECTORY (a bare import lands on
+// `<node_modules>/<pkg>`), so probing starts at the path itself, then walks up. `packageRelativePath`
+// is '' when the candidate IS the package root -- Metro's exports resolver maps '' to the '.' subpath,
+// and a stray '.' there would mismatch the exports key.
+function getPackageForModule(absModulePath) {
+  let dir = pathType(absModulePath) === 'd' ? absModulePath : dirname(absModulePath)
+  while (true) {
+    const pkg = readJson(join(dir, 'package.json'))
+    if (pkg) {
+      const rel = dir === absModulePath ? '' : absModulePath.slice(dir.length + 1)
+      return { rootPath: dir, packageJson: pkg, packageRelativePath: rel }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+// Build a resolver bound to a platform. `metro-resolver` is required from `projectDir` so we
+// honour the version the project's Metro uses; a missing package throws with actionable guidance.
+// `sourceExts` are the extensions Metro probes (kept to what a source bundle can carry, so the
+// resolver never lands on a file the bundle would reject). `mainFields` drives the browser-field
+// spec; `conditionNames` are the extra `exports`/`imports` conditions on top of the ones Metro
+// derives itself (default + require|import + platform).
+export function createMetroResolver({
+  projectDir,
+  platform,
+  sourceExts = ['js', 'json', 'ts'],
+  mainFields = ['react-native', 'browser', 'main'],
+  conditionNames = ['react-native'],
+  conditionsByPlatform = { web: ['browser'] },
+  enablePackageExports = true,
+} = {}) {
+  const require = createRequire(join(projectDir, 'noop.js'))
+  let resolve
+  try {
+    ;({ resolve } = require('metro-resolver'))
+  } catch (cause) {
+    throw new Error(
+      `StasisMetroResolver: couldn't load 'metro-resolver' from ${projectDir}. --metro-resolver ` +
+      'resolves through the project\'s own Metro; install it (it ships with react-native/metro) ' +
+      'or drop --metro-resolver to use the built-in resolver.',
+      { cause }
+    )
+  }
+
+  // A React Native app has no Node builtins by default; Metro only prefers native suffixes off web.
+  const base = {
+    allowHaste: false,
+    assetExts: new Set(),
+    customResolverOptions: {},
+    disableHierarchicalLookup: false,
+    doesFileExist: (p) => resolvableType(p) === 'f',
+    extraNodeModules: null,
+    dev: false,
+    getPackage: (packageJsonPath) => readJson(packageJsonPath),
+    getPackageForModule,
+    fileSystemLookup: (p) => {
+      const abs = isAbsolute(p) ? p : join(projectDir, p)
+      const type = resolvableType(abs)
+      if (!type) return { exists: false }
+      let realPath = abs
+      try {
+        realPath = realpathSync(abs)
+      } catch { /* keep the lexical path when realpath fails (e.g. a broken symlink) */ }
+      return { exists: true, type, realPath }
+    },
+    mainFields,
+    nodeModulesPaths: [],
+    preferNativePlatform: platform !== 'web',
+    resolveAsset: (dirPath, assetName, ext) => {
+      const f = join(dirPath, `${assetName}${ext}`)
+      return pathType(f) === 'f' ? [f] : null
+    },
+    resolveHasteModule: () => null,
+    resolveHastePackage: () => null,
+    // Inert placeholder: `resolve` redirects via its own bundled helper, never this (see header).
+    redirectModulePath: (modulePath) => modulePath,
+    sourceExts,
+    unstable_conditionNames: conditionNames,
+    unstable_conditionsByPlatform: conditionsByPlatform,
+    unstable_enablePackageExports: enablePackageExports,
+    unstable_incrementalResolution: false,
+    unstable_logWarning: () => {}, // a static build must not spam on exports fallbacks
+  }
+
+  return function resolveOne(parentFile, specifier, callConditions) {
+    // Metro splits `exports` on whether the edge was an ESM import vs a CJS require. scan.js hands
+    // us the parent's format-derived condition set, so 'import' membership is that signal.
+    const isESMImport = callConditions instanceof Set ? callConditions.has('import') : false
+    const context = { ...base, originModulePath: parentFile, isESMImport }
+    let res
+    try {
+      res = resolve(context, specifier, platform)
+    } catch {
+      // Metro carries no Node builtins: an unmapped builtin fails to resolve here. The browser-field
+      // remap of a builtin (`{"crypto": false}` / a shim) is handled inside resolve() before this.
+      if (isBuiltin(specifier)) return { builtin: true }
+      return null
+    }
+    if (!res) return null
+    if (res.type === 'empty') return { empty: true }
+    if (res.type === 'sourceFile') return { url: pathToFileURL(res.filePath).toString() }
+    // Assets are off (assetExts empty) for a code bundle, but map defensively to the first variant.
+    if (res.type === 'assetFiles' && res.filePaths?.length) return { url: pathToFileURL(res.filePaths[0]).toString() }
+    return null
+  }
+}

package/src/metro-transformer.js

@@ -1,6 +1,7 @@
 // Public-export adapter: backs `@exodus/stasis/metro-transformer`. The transformer
 // lives in @exodus/stasis-plugins (which depends on @exodus/stasis-core for State; it
-// drives load-mode getFile directly). Wire it as Metro's `transformer.transformerPath`
-// in load mode; see the source for the load asymmetry that lets this run per-worker
+// drives load-mode getFile directly). Wire it permanently as Metro's top-level
+// `transformerPath`; it only acts under bundle=load (transparent pass-through
+// otherwise). See the source for the load asymmetry that lets this run per-worker
 // without cross-worker state sync.
 export * from '@exodus/stasis-plugins/metro-transformer'