@exodus/stasis 1.0.0-alpha.2 → 1.0.0-beta.0

package/src/loaders/rust.js

@@ -0,0 +1,336 @@
+// Rust loader: produces a `{ sources, resolutions, missing }` triple from a
+// crate's source files, mirroring the Solidity/Bash loaders' interface. 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.
+
+import { realpathSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+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.
+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).
+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).
+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)]`).
+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.
+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.
+export function extractModDecls(content) {
+  const decls = []
+  let cfgPending = false
+  for (const raw of stripRustComments(content).split('\n')) {
+    const line = raw.trim()
+    if (line === '') continue // blank lines don't break a contiguous attribute group
+    const m = MOD_DECL_RE.exec(line)
+    if (m) {
+      decls.push({ name: m[1], conditional: cfgPending })
+      cfgPending = false
+    } else if (CFG_ATTR_RE.test(line)) {
+      cfgPending = true
+    } else if (!line.startsWith('#[')) {
+      cfgPending = false // a non-attribute line ends the attribute group
+    }
+  }
+  return decls
+}
+
+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.
+export function extractExternalCrates(content) {
+  const stripped = stripRustComments(content)
+  const names = new Set()
+  for (const raw of stripped.split('\n')) {
+    const m = EXTERN_CRATE_RE.exec(raw.trim())
+    if (m) names.add(m[1])
+  }
+  for (const m of stripped.matchAll(PATH_LEAD_RE)) {
+    if (!NON_CRATE_LEADS.has(m[1])) names.add(m[1])
+  }
+  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).
+export function resolveVendoredCrate(crateName, { knownSources, baseDir, vendorDir = VENDOR_DIR } = {}) {
+  const dirs = crateName.includes('_') ? [crateName, crateName.replaceAll('_', '-')] : [crateName]
+  for (const dir of dirs) {
+    const lib = `${vendorDir}/${dir}/src/lib.rs`
+    if (knownSources) {
+      if (knownSources.has(lib)) return lib
+    } else if (baseDir) {
+      try {
+        if (statSync(join(baseDir, lib)).isFile()) return lib
+      } catch { /* not this spelling — try the next */ }
+    }
+  }
+  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
+export function getModuleDir(filePath) {
+  const lastSlash = filePath.lastIndexOf('/')
+  const dir = lastSlash === -1 ? '' : filePath.slice(0, lastSlash)
+  const name = lastSlash === -1 ? filePath : filePath.slice(lastSlash + 1)
+  if (name === 'main.rs' || name === 'lib.rs' || name === 'mod.rs') return dir
+  const stem = name.replace(/\.rs$/u, '')
+  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.
+export function resolveModPath(modName, fromFile, { knownSources, baseDir } = {}) {
+  const modDir = getModuleDir(fromFile)
+  const base = modDir ? `${modDir}/${modName}` : modName
+  const candidates = [`${base}.rs`, `${base}/mod.rs`]
+
+  if (knownSources) return candidates.find((c) => knownSources.has(c)) ?? null
+  if (baseDir) {
+    for (const c of candidates) {
+      try {
+        if (statSync(join(baseDir, c)).isFile()) return c
+      } catch { /* missing — try the next candidate */ }
+    }
+  }
+  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).
+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).
+    if (vendorDir && filePath.startsWith(`${vendorDir}/`)) continue
+    const name = filePath.includes('/') ? filePath.slice(filePath.lastIndexOf('/') + 1) : filePath
+    if (name !== 'main.rs' && name !== 'lib.rs') continue
+    const seen = new Set()
+    const stack = [[filePath, 'crate', 0]]
+    while (stack.length > 0) {
+      const [path, modulePath, depth] = stack.pop()
+      tree.set(modulePath, path)
+      if (seen.has(path) || depth >= MAX_MODULE_DEPTH) continue
+      seen.add(path)
+      const specMap = resolutions.get(path)
+      if (!specMap) continue
+      for (const [spec, resolved] of specMap) {
+        if (!spec.startsWith('mod ')) continue
+        stack.push([resolved, `${modulePath}::${spec.slice(4)}`, depth + 1])
+      }
+    }
+  }
+  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.
+export function resolveUsePath(usePath, moduleTree) {
+  const parts = usePath.split('::')
+  for (let i = parts.length; i >= 1; i--) {
+    const modulePath = parts.slice(0, i).join('::')
+    if (moduleTree.has(modulePath)) return moduleTree.get(modulePath)
+  }
+  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.
+export function buildRustTree(sources) {
+  const resolutions = new Map()
+  const missing = []
+  for (const [path, content] of sources) {
+    const specMap = new Map()
+    for (const { name, conditional } of extractModDecls(content)) {
+      const resolved = resolveModPath(name, path, { knownSources: sources })
+      if (resolved) {
+        specMap.set(`mod ${name}`, resolved)
+      } else if (!conditional) {
+        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.
+    }
+    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.
+    if (path.startsWith(`${VENDOR_DIR}/`)) continue
+    const specMap = resolutions.get(path)
+    for (const usePath of extractCrateUses(content)) {
+      const resolved = resolveUsePath(usePath, moduleTree)
+      if (resolved && resolved !== path && !specMap.has(usePath)) {
+        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}`
+      if (lib && lib !== path && !specMap.has(spec)) specMap.set(spec, lib)
+    }
+  }
+  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.
+export async function collectRustFilesFromDisk(baseDir, entries) {
+  const sources = new Map()
+  const realBase = realpathSync(baseDir)
+
+  const processWave = async (wave) => {
+    const toLoad = [...new Set(wave)].filter((p) => !sources.has(p))
+    if (toLoad.length === 0) return
+    const reads = await Promise.all(
+      toLoad.map(async (relPath) => {
+        try {
+          assertRealPathWithinBase(realBase, baseDir, relPath)
+          return [relPath, await readFile(join(baseDir, relPath), 'utf8')]
+        } catch (err) {
+          if (err.code === 'ENOENT') {
+            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).
+          if (err.code === 'EISDIR') {
+            console.warn(`[loader.rust] Skipping directory reference: ${relPath}`)
+            return null
+          }
+          throw err
+        }
+      })
+    )
+    const next = []
+    for (const entry of reads) {
+      if (!entry) continue
+      const [relPath, content] = entry
+      sources.set(relPath, content)
+      for (const { name } of extractModDecls(content)) {
+        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.
+      for (const crate of extractExternalCrates(content)) {
+        const lib = resolveVendoredCrate(crate, { baseDir })
+        if (lib && !sources.has(lib)) next.push(lib)
+      }
+    }
+    await processWave(next)
+  }
+
+  await processWave(entries)
+  return sources
+}
+
+// Reject absolute paths and `..`-escaping paths in a `.rs.txt` listing so a
+// malicious or sloppy listing can't read files outside the listing's own dir.
+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('/')
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`${label} escapes baseDir: ${candidate}`)
+  }
+}
+
+// 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 }.
+export async function loadRust(rsTxtFile) {
+  const baseDir = dirname(resolve(rsTxtFile))
+  const listing = await readFile(rsTxtFile, 'utf8')
+  const lines = listing.split('\n').map((l) => l.trim()).filter(Boolean)
+    .map((l) => l.replace(/^\.\//u, ''))
+  if (lines.length === 0) throw new Error(`Empty Rust listing: ${rsTxtFile}`)
+
+  if (!lines.every((line) => extname(line) === '.rs')) {
+    throw new Error(`Rust listing must only contain .rs files: ${rsTxtFile}`)
+  }
+  for (const line of lines) assertWithinBase(baseDir, line, 'Entry path')
+
+  const sources = await collectRustFilesFromDisk(baseDir, lines)
+  return buildRustTree(sources)
+}

package/src/loaders/solidity.js

@@ -5,9 +5,13 @@
 // file (foundry.toml or remappings.txt) is read to extract `remappings`,
 // but is itself not included in `sources`.
 
+import { realpathSync, statSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 
+import { assertRealPathWithinBase } from '@exodus/stasis-core/util'
+
 const SOL_IMPORT_RE = /import\s[^"']*["']([^"']+)["']/gu
 
 export function extractSolImports(content) {
@@ -28,16 +32,21 @@ export function parseRemappings(content) {
   }).filter(Boolean)
 }
 
-// Returns a candidate resolved path, or null if the specifier doesn't match
-// any remapping and isn't a relative import. The caller is responsible for
-// checking whether the resolved path actually exists in `sources` (the
-// etherscan bundle's cnames are exact-match keys — `@openzeppelin/…` lives
-// alongside `contracts/Foo.sol` — so a non-relative, non-remapped specifier
-// may still be a hit when matched verbatim against the bundle). Logging
-// "Missing import" also lives at the callsite because only the callsite
-// knows whether that verbatim fallback matched.
-export function resolveSolImport(specifier, fromFile, remappings) {
-  // Try remappings (longest prefix match)
+// 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.
+export function resolveSolImport(specifier, fromFile, { remappings = [], baseDir } = {}) {
   let best = null
   for (const { prefix, target } of remappings) {
     if (specifier.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) {
@@ -47,13 +56,9 @@ export function resolveSolImport(specifier, fromFile, remappings) {
   if (best) {
     const target = best.target.replace(/\/$/u, '')
     const remaining = specifier.slice(best.prefix.length).replace(/^\//u, '')
-    const result = remaining ? `${target}/${remaining}` : target
-    return result.replace(/^\.\//u, '')
+    return (remaining ? `${target}/${remaining}` : target).replace(/^\.\//u, '')
   }
 
-  // Relative import. `..` segments that would traverse above the project
-  // root return null instead of silently clamping to root — clamping would
-  // change the import target into something the source never asked for.
   if (specifier.startsWith('.')) {
     const fromDir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : ''
     const parts = [...(fromDir ? fromDir.split('/') : []), ...specifier.split('/')]
@@ -70,30 +75,56 @@ export function resolveSolImport(specifier, fromFile, remappings) {
     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.
+  if (baseDir && specifier.startsWith('@')) {
+    const parts = specifier.split('/')
+    if (parts.length < 3) return null
+    if (parts.slice(2).includes('..')) return null
+    try {
+      const abs = createRequire(resolve(baseDir, fromFile)).resolve(specifier)
+      const rel = relative(baseDir, abs).split(/[\\/]/u).join('/')
+      if (!rel.startsWith('..') && !isAbsolute(rel)) return rel
+    } 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.
+  if (baseDir && !isAbsolute(specifier)) {
+    const rel = relative(baseDir, resolve(baseDir, specifier)).split(/[\\/]/u).join('/')
+    if (rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)) {
+      try {
+        if (statSync(join(baseDir, rel)).isFile()) return rel
+      } catch { /* missing or not statable */ }
+    }
+  }
+
   return null
 }
 
 // Build the { sources, resolutions, missing } triple from a Map of
-// already-loaded Solidity sources (any key format — relative paths for
-// disk-loaded projects, `${address}/${cname}` for etherscan, etc.) plus
-// optional remappings. Imports that resolve via remappings/relative paths
-// win; as a fallback we also accept an import specifier that matches a
-// stored key verbatim (etherscan bundles imports like
-// `@openzeppelin/contracts/.../IERC20.sol` which is itself a stored
-// cname). `missing` lists every (spec, from) pair that could not be
-// resolved or that resolved to a file that wasn't loaded into `sources`.
-export function buildSolidityTree(sources, { remappings = [] } = {}) {
+// 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`.
+export function buildSolidityTree(sources, { remappings = [], baseDir } = {}) {
   const resolutions = new Map()
   const missing = []
   for (const [path, content] of sources) {
     const specMap = new Map()
     for (const spec of extractSolImports(content)) {
-      let resolved = resolveSolImport(spec, path, remappings)
+      let resolved = resolveSolImport(spec, path, { remappings, baseDir })
       if (resolved && !sources.has(resolved)) resolved = null
-      // Verbatim fallback: many Solidity ecosystems (etherscan bundles,
-      // hardhat flat layouts) ship `@openzeppelin/...` imports as literal
-      // keys in the source map. If the remap/relative resolution didn't
-      // hit but the bundle has the specifier itself as a key, use it.
       if (!resolved && sources.has(spec)) resolved = spec
       if (resolved) {
         specMap.set(spec, resolved)
@@ -107,34 +138,24 @@ export function buildSolidityTree(sources, { remappings = [] } = {}) {
   return { sources, resolutions, missing }
 }
 
-// Walk the filesystem starting from `entries`, following relative/remapped
-// imports and reading each file exactly once. Returns a Map<relPath, content>
-// suitable for passing into buildSolidityTree. Files in the same wave are
-// read in parallel; subsequent waves depend on the imports discovered in
-// the previous one.
-//
-// Specifiers that exactly match one of the explicit entries (the file
-// list passed by the caller) are accepted as-is, even when they don't
-// match any remapping. Solidity projects routinely write
-// `import "src/A.sol"` and rely on solc's include-path / Foundry's
-// remap-from-root behavior; here we don't have a true include path,
-// but if the caller listed `src/A.sol` themselves we know the path is
-// intentional and resolves to that file. Mirrors the `sources.has(spec)`
-// fallback in `buildSolidityTree`, but applied during the walk so the
-// file actually gets loaded into `sources`.
+// 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"`).
 export async function collectSolidityFilesFromDisk(baseDir, entries, remappings) {
   const sources = new Map()
   const knownEntries = new Set(entries)
+  const realBase = realpathSync(baseDir)
 
   const processWave = async (wave) => {
     const toLoad = [...new Set(wave)].filter((p) => !sources.has(p))
     if (toLoad.length === 0) return
-    // A resolved path that doesn't exist on disk is treated like an
-    // unresolved import: warn and skip rather than aborting the entire
-    // walk. Other read errors (EACCES, EIO, …) still propagate.
     const reads = await Promise.all(
       toLoad.map(async (relPath) => {
         try {
+          assertRealPathWithinBase(realBase, baseDir, relPath)
           return [relPath, await readFile(join(baseDir, relPath), 'utf8')]
         } catch (err) {
           if (err.code === 'ENOENT') {
@@ -151,7 +172,7 @@ export async function collectSolidityFilesFromDisk(baseDir, entries, remappings)
       const [relPath, content] = entry
       sources.set(relPath, content)
       for (const spec of extractSolImports(content)) {
-        let resolved = resolveSolImport(spec, relPath, remappings)
+        let resolved = resolveSolImport(spec, relPath, { remappings, baseDir })
         if (!resolved && knownEntries.has(spec)) resolved = spec
         if (resolved) {
           if (!sources.has(resolved)) next.push(resolved)
@@ -210,5 +231,5 @@ export async function loadSolidity(solTxtFile) {
   const entries = lines.map((l) => l.replace(/^\.\//u, ''))
   for (const e of entries) assertWithinBase(baseDir, e, 'Entry path')
   const sources = await collectSolidityFilesFromDisk(baseDir, entries, remappings)
-  return buildSolidityTree(sources, { remappings })
+  return buildSolidityTree(sources, { remappings, baseDir })
 }

package/src/lockfile.js

@@ -1,80 +1,4 @@
-import { assert, fileSetToObject, fromEntries, sortPaths } from './util.js'
-
-const VERSION = 0
-
-const normalize = ({ name, version, files }) =>
-  ({ name, version, files: fromEntries(Object.entries(files)) })
-
-export class Lockfile {
-  static VERSION = VERSION
-
-  version = VERSION
-  config
-  entries
-  modules
-
-  constructor({ config = { scope: 'full' }, entries, modules } = {}) {
-    assert(['node_modules', 'full'].includes(config.scope))
-    this.config = config
-    this.entries = entries ?? new Set()
-    this.modules = modules ?? new Map()
-  }
-
-  static parse(text) {
-    const json = JSON.parse(text)
-    assert(json.version === VERSION)
-    assert(['node_modules', 'full'].includes(json.config?.scope))
-
-    const full = json.config.scope === 'full'
-    assert(!!json.entries === full)
-    assert(!!json.sources === full)
-    assert(json.modules)
-
-    const modules = new Map()
-    for (const [dir, info] of Object.entries(json.modules)) {
-      assert(dir.includes('node_modules'))
-      assert(info?.name && info.version && info.files)
-      modules.set(dir, normalize(info))
-    }
-
-    let entries = new Set()
-    if (full) {
-      assert(Array.isArray(json.entries))
-      entries = new Set(json.entries)
-      for (const [dir, info] of Object.entries(json.sources)) {
-        assert(!dir.includes('node_modules'))
-        modules.set(dir, normalize(info))
-      }
-    }
-
-    for (const [dir, { files }] of modules) {
-      assert(!dir.startsWith('..'))
-      assert(files)
-      for (const name of Object.keys(files)) {
-        assert(!name.startsWith('..'))
-      }
-    }
-
-    return new Lockfile({ config: json.config, entries, modules })
-  }
-
-  serialize() {
-    const entries = fileSetToObject(this.entries)
-    const modules = []
-    const sources = []
-    for (const [dir, { name, version, files }] of this.modules) {
-      const inNodeModules = dir.includes('node_modules')
-      if (inNodeModules) assert(name && version && files)
-      const type = inNodeModules ? modules : sources
-      const sorted = fromEntries(Object.entries(files).toSorted((a, b) => sortPaths(a[0], b[0])))
-      type.push([dir, { name, version, files: sorted }])
-    }
-    modules.sort((a, b) => sortPaths(a[0], b[0]))
-    sources.sort((a, b) => sortPaths(a[0], b[0]))
-
-    const store = { version: this.version, config: this.config }
-    if (this.config.scope === 'full') Object.assign(store, { entries, sources: fromEntries(sources) })
-    Object.assign(store, { modules: fromEntries(modules) })
-    return JSON.stringify(store, undefined, 2) + '\n'
-  }
-}
+// Public-export adapter: backs `@exodus/stasis/lockfile`. The implementation lives in
+// @exodus/stasis-core; internal tooling and tests import `@exodus/stasis-core/lockfile`
+// directly, so this file exists only to back the package's `exports` map.
+export * from '@exodus/stasis-core/lockfile'

package/src/metro-transformer.js

@@ -0,0 +1,6 @@
+// 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
+// without cross-worker state sync.
+export * from '@exodus/stasis-plugins/metro-transformer'

package/src/metro.js

@@ -0,0 +1,5 @@
+// Public-export adapter: backs `@exodus/stasis/metro`. The plugin lives in
+// @exodus/stasis-plugins (which depends on @exodus/stasis-core for State /
+// resolvePluginState). Internal code uses `@exodus/stasis-plugins/metro` directly;
+// this file exists only to back the package's `exports` map.
+export * from '@exodus/stasis-plugins/metro'