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

package/src/loaders/toml.js

@@ -0,0 +1,68 @@
+// TOML for the build descriptions the loaders take -- Cargo.toml, Cargo.lock, foundry.toml -- read
+// by @preventive/lockfile's strict TOML 1.0 parser into a tree of tables, and refused where it
+// isn't TOML, or isn't the TOML those files are written in: a bad escape, an unterminated string, a
+// key or table defined twice, a local date, U+FFFD where a lenient decoder replaced bytes ... each a
+// TomlError naming the file and line, never a guessed value.
+
+import { TomlError, parseToml } from '@preventive/lockfile/toml.js'
+
+export { TomlError }
+
+// --- Bracket helpers (for the Rust scanner) ----------------------------------------------
+
+// Index of the bracket closing the one opened at `open`, or the last index when unbalanced.
+export function matchClose(text, open) {
+  const close = { '[': ']', '(': ')', '{': '}' }[text[open]]
+  let depth = 0
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === text[open]) depth++
+    else if (text[i] === close && --depth === 0) return i
+  }
+  return text.length - 1
+}
+
+// Split on commas outside brackets/braces/parentheses/strings.
+export function splitTopLevel(text) {
+  const parts = []
+  let depth = 0
+  let start = 0
+  let inStr = false
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inStr) {
+      if (ch === '\\') i++
+      else if (ch === '"') inStr = false
+      continue
+    }
+    if (ch === '"') inStr = true
+    else if (ch === '(' || ch === '[' || ch === '{') depth++
+    else if (ch === ')' || ch === ']' || ch === '}') depth--
+    else if (ch === ',' && depth === 0) {
+      parts.push(text.slice(start, i))
+      start = i + 1
+    }
+  }
+  parts.push(text.slice(start))
+  return parts
+}
+
+// --- The reader -----------------------------------------------------------------------------
+
+// The table tree of TOML `text` (parseToml): tables are null-prototype objects, arrays arrays, and
+// values strings, booleans, numbers (an integer past 2^53 a BigInt), TomlFloat and TomlDateTime.
+// Throws a TomlError on anything else, naming `file` when given.
+export const readToml = (text, file = null) => nameErrors(file, () => parseToml(text))
+
+// `read()`, with an error of one of `classes` it throws (@preventive/lockfile's, whose message
+// leads with where it is) leading with `file` too, its fields kept; null `file` names none.
+export function nameErrors(file, read, classes = [TomlError]) {
+  try {
+    return read()
+  } catch (err) {
+    if (file === null || !classes.some((c) => err instanceof c)) throw err
+    throw Object.assign(new err.constructor(`${file}: ${err.message}`), err)
+  }
+}
+
+// Whether a TOML value is a table (a TomlFloat or TomlDateTime is an object too).
+export const isTomlTable = (value) => value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === null

package/src/metro-resolver.js

@@ -1,9 +1,10 @@
-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 { diskHost } from '@exodus/stasis-core/host'
 import { isTypeDeclaration } from '@exodus/stasis-core/util'
+import { readJson } from './resolve-typescript.js'
 
 // 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
@@ -23,29 +24,10 @@ import { isTypeDeclaration } from '@exodus/stasis-core/util'
 // 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
-  }
+  const s = diskHost.stat(p)
+  return s?.isFile() ? 'f' : s?.isDirectory() ? 'd' : null
 }
 
 // A `.d.ts` is types-only, erased at runtime, so the resolver must never land on one: report it as
@@ -87,7 +69,10 @@ export function createMetroResolver({
   conditionNames = ['react-native'],
   conditionsByPlatform = { web: ['browser'] },
   enablePackageExports = true,
+  host = diskHost,
 } = {}) {
+  // It loads the project's metro-resolver, which reads the disk: never off it.
+  if (host !== diskHost) throw new Error('createMetroResolver: metro-resolver reads the disk, so it is not supported off disk')
   const require = createRequire(join(projectDir, 'noop.js'))
   let resolve
   try {
@@ -118,7 +103,7 @@ export function createMetroResolver({
       if (!type) return { exists: false }
       let realPath = abs
       try {
-        realPath = realpathSync(abs)
+        realPath = diskHost.realpath(abs)
       } catch { /* keep the lexical path when realpath fails (e.g. a broken symlink) */ }
       return { exists: true, type, realPath }
     },

package/src/mock.js

@@ -184,13 +184,11 @@ process.on('exit', () => {
 // exits cleanly and the loader's beforeExit hook writes the bundle.
 const noop = () => undefined
 const pending = () => new Promise(() => {})
-for (const name of ['setTimeout', 'setInterval', 'setImmediate']) globalThis[name] = noop
-for (const name of ['clearTimeout', 'clearInterval', 'clearImmediate']) globalThis[name] = noop
+const TIMERS = ['setTimeout', 'setInterval', 'setImmediate', 'clearTimeout', 'clearInterval', 'clearImmediate']
+for (const name of TIMERS) globalThis[name] = noop
 
 const timers = require('node:timers')
-for (const name of ['setTimeout', 'setInterval', 'setImmediate', 'clearTimeout', 'clearInterval', 'clearImmediate']) {
-  mock.method(timers, name, noop)
-}
+for (const name of TIMERS) mock.method(timers, name, noop)
 
 const timersPromises = require('node:timers/promises')
 mock.method(timersPromises, 'setTimeout', pending)

package/src/resolve-fields.js

@@ -0,0 +1,331 @@
+import { isBuiltin } from 'node:module'
+import { dirname, isAbsolute, join, relative, resolve as resolvePath } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { isTypeDeclaration, stripTypeDeclaration, toPosix } from '@exodus/stasis-core/util'
+import {
+  isDir,
+  isFile,
+  locatePackage,
+  nearestPackage,
+  readJson,
+  resolveTypescriptFallback,
+  typescriptSiblings,
+} from './resolve-typescript.js'
+import { diskHost } from '@exodus/stasis-core/host'
+
+// Static module resolver for legacy package fields (`react-native`/`browser`/`main` + browser-spec
+// redirect maps) and platform suffixes (`.ios`/`.android`/`.native`), reproducing Metro/React-Native
+// resolution that Node's own resolver (used by scan.js) can't. `exports`-bearing packages are
+// delegated to Node. No user code is executed (only package.json is stat/read).
+//
+// Returns, for each specifier:
+//   { 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
+//   null         unresolved
+
+// Metro divergence toggle. When a package's browser map maps its OWN entry to `false` (under
+// Metro's matching rules, which include bare keys like {"buf": false} for main "./buf.js"),
+// Metro's `getPackageEntryPoint` ignores the non-string replacement and keeps `main`. The
+// `--metro` resolver matches that by default; flip this to `false` to fail closed instead:
+// a `false` match on the entry then yields an EMPTY module. Note the off state is deliberately
+// stricter than both tools -- for a bare-key `false`, Metro keeps `main` and esbuild would not
+// match the entry at all -- it exists as an escape hatch, not an esbuild-parity mode. This only
+// affects the `--metro` path; the `--mainFields` path always empties (matching esbuild).
+// Tests can override per-resolver via createFieldResolver's `metroKeepEntryOnBrowserFalse`.
+const METRO_KEEP_ENTRY_ON_BROWSER_FALSE = true
+
+// First mainFields entry that's a non-empty string, else `index` (object-valued fields are redirect maps).
+function packageEntry(pkg, mainFields) {
+  for (const name of mainFields) {
+    if (typeof pkg?.[name] === 'string' && pkg[name].length > 0) return pkg[name]
+  }
+  return 'index'
+}
+
+// Merge object-valued mainFields (browser-spec maps) into one redirect map. Iterate in REVERSE
+// so earlier mainFields win on conflict. Keys are verbatim: `./x` relative vs bare `x` (kept bare).
+function mergeRedirectMap(pkg, mainFields) {
+  const map = new Map()
+  for (let i = mainFields.length - 1; i >= 0; i--) {
+    const field = pkg?.[mainFields[i]]
+    if (!field || typeof field !== 'object') continue
+    for (const [key, value] of Object.entries(field)) {
+      if (typeof value !== 'string' && value !== false) continue
+      map.set(key, value)
+    }
+  }
+  return map
+}
+
+// Metro's entry-variant list for `main` (getPackageEntryPoint, metro-resolver
+// PackageResolve.js): the main spelling and its ./-toggled twin, each expanded to
+// [self, +'.js', +'.json', ext-stripped]. ORDER MATTERS -- the first variant with ANY mapping
+// (string or false) decides, so this must reproduce Metro's list exactly, duplicates included.
+function metroEntryVariants(main) {
+  const toggled = main.startsWith('./') ? main.slice(2) : `./${main}`
+  return [main, toggled].flatMap((v) => [v, `${v}.js`, `${v}.json`, v.replace(/\.(?:js|json)$/u, '')])
+}
+
+// Resolve the package ENTRY (from mainFields) through the package's own redirect map.
+// Returns { entry } (the redirected or original entry to resolve) or { empty: true }.
+// Both halves of the entry semantics -- WHICH keys match, and what `false` means -- live here
+// so no caller can get one without the other:
+// - metro: Metro's getPackageEntryPoint. First matching variant (Metro's order) wins; a string
+//   redirects; `false` (any non-string) keeps `main`, unless the keep-on-false toggle is off,
+//   in which case it fails closed to an empty module (see METRO_KEEP_ENTRY_ON_BROWSER_FALSE).
+// - default (--mainFields): esbuild-shaped candidates; `false` empties the entry, matching
+//   esbuild. The extension-STRIPPED bare spelling is not probed: for an extensioned main,
+//   esbuild treats it as a bare module name, not the entry. (For an extensionless main the
+//   `bare` candidate covers it -- esbuild does match that spelling; verified empirically.)
+function resolveEntryThroughMap(map, main, opts) {
+  if (map.size === 0) return { entry: main }
+  let cands
+  if (opts.metro) {
+    cands = metroEntryVariants(main)
+  } else {
+    const bare = main.replace(/^\.\//u, '')
+    const stripped = bare.replace(/\.(?:js|json)$/u, '')
+    cands = [
+      `./${bare}`, bare,
+      `./${stripped}`,
+      `./${stripped}.js`, `${stripped}.js`,
+      `./${stripped}.json`, `${stripped}.json`,
+    ]
+  }
+  for (const cand of cands) {
+    const v = map.get(cand)
+    if (typeof v === 'string') return { entry: v }
+    if (v === false) {
+      if (opts.metro && opts.metroKeepEntryOnBrowserFalse) return { entry: main }
+      return { empty: true }
+    }
+  }
+  return { entry: main }
+}
+
+const fileResolution = (path) => ({ url: pathToFileURL(path).toString() })
+
+// Match a package-relative path (`./x`) against the redirect map, trying `.js`/`.json` appended.
+function matchRedirect(map, relPath) {
+  if (map.size === 0) return undefined
+  for (const cand of [relPath, `${relPath}.js`, `${relPath}.json`]) {
+    if (map.has(cand)) return map.get(cand)
+  }
+  return undefined
+}
+
+// Probe `base` for a source file in platform order: bare name first, then per ext
+// `base.<platform>.<ext>`, `base.native.<ext>` (native only), `base.<ext>`. `platform: null`
+// disables suffixes. Under metro, every SUFFIXED candidate first passes through the candidate's
+// own package redirect map -- mirroring Metro's resolveSourceFileForExt, which runs
+// redirectModulePath on each non-bare candidate: `false` short-circuits the whole probe to an
+// empty module (e.g. browser { "./index.ios.js": false }), and a string redirect re-lands the
+// candidate package-root-relative. Returns a path, { empty: true } (metro only), or null.
+function resolveSourceFile(base, opts) {
+  // A path that literally names a `.d.ts` names no runtime module (types are erased). Probe its
+  // declaration-free stem instead, so an entry field pointing at `dist/index.d.ts` lands on the real
+  // `dist/index.js` beside it rather than bundling the declaration -- or failing the package
+  // outright by falling back to a different index. The probe below still refuses a literal hit.
+  base = stripTypeDeclaration(base)
+  // Candidates share base's directory, hence its package scope; resolve it lazily, once.
+  let scope
+  const redirectCandidate = (p) => {
+    if (scope === undefined) {
+      const pkg = nearestPackage(base, opts.host)
+      scope = pkg ? { pkgDir: pkg.pkgDir, map: mergeRedirectMap(pkg.pkg, opts.mainFields) } : null
+    }
+    if (!scope || scope.map.size === 0) return p
+    const rel = `./${toPosix(relative(scope.pkgDir, p))}`
+    const r = matchRedirect(scope.map, rel)
+    if (r === false) return false
+    if (typeof r === 'string') return isAbsolute(r) ? r : resolvePath(scope.pkgDir, r)
+    return p
+  }
+  // `derived` marks a candidate that is not the literal base; Metro redirect-checks those only.
+  const probePath = (p, derived) => {
+    if (opts.metro && derived) {
+      const r = redirectCandidate(p)
+      if (r === false) return { empty: true }
+      p = r
+    }
+    // A `.d.ts` is types-only, erased at runtime: never a resolution target, so a package whose
+    // entry field points at one falls through to its real `.js` instead of bundling the declaration.
+    if (isTypeDeclaration(p)) return null
+    return isFile(p, opts.host) ? p : null
+  }
+  // `suffix` is everything appended to `base`.
+  const probe = (suffix) => probePath(`${base}${suffix}`, suffix !== '')
+  const tryExt = (sourceExt) => {
+    if (opts.platform) {
+      const hit = probe(`.${opts.platform}${sourceExt}`)
+      if (hit) return hit
+    }
+    if (opts.preferNative && sourceExt !== '') {
+      const hit = probe(`.native${sourceExt}`)
+      if (hit) return hit
+    }
+    return probe(sourceExt)
+  }
+  const bare = tryExt('')
+  if (bare) return bare
+  // --typescript: tsc's extension substitution. A base naming a JS output extension probes its TS
+  // source siblings once the literal file (the bare probe above) is absent, so the on-disk `.js`
+  // always wins over its `.ts` twin. Literal siblings only -- no platform suffixes (tsc has none);
+  // extensionless bases keep going through the appended-extension loop below (sourceExts carries
+  // ts, and tsx under --jsx). Placed before that loop so `x.js` -> `x.ts` beats a pathological
+  // `x.js.<ext>`, matching tsc's candidate order.
+  if (opts.typescript) {
+    for (const cand of typescriptSiblings(base, { tsx: opts.sourceExts.includes('tsx') })) {
+      const hit = probePath(cand, true)
+      if (hit) return hit
+    }
+  }
+  for (const ext of opts.sourceExts) {
+    const hit = tryExt(`.${ext}`)
+    if (hit) return hit
+  }
+  return null
+}
+
+// Resolve absolute `base` as a file (ext probing) else as a directory (package.json `main` via
+// mainFields + entry redirect, else `index`). `exports` is NOT consulted — Node applies it only to
+// bare package-name imports, not to a path landing on a directory.
+function resolveFileOrDir(base, opts) {
+  // resolveSourceFile yields a path, { empty: true } (a metro candidate-redirect hit), or null.
+  const asResolution = (hit) => (hit == null ? null : typeof hit === 'string' ? fileResolution(hit) : hit)
+  const file = asResolution(resolveSourceFile(base, opts))
+  if (file) return file
+  if (isDir(base, opts.host)) {
+    const dpkg = readJson(join(base, 'package.json'), opts.host)
+    if (dpkg) {
+      const r = resolveEntryThroughMap(mergeRedirectMap(dpkg, opts.mainFields), packageEntry(dpkg, opts.mainFields), opts)
+      if (r.empty) return { empty: true }
+      // Node's LOAD_AS_DIRECTORY resolves `main` as a file, else as a directory index
+      // (`main: "./lib/"` -> lib/index.js); a broken `main` falls back to the package index below.
+      const entryBase = join(base, r.entry)
+      const inner = asResolution(resolveSourceFile(entryBase, opts) ?? resolveSourceFile(join(entryBase, 'index'), opts))
+      if (inner) return inner
+    }
+    const index = asResolution(resolveSourceFile(join(base, 'index'), opts))
+    if (index) return index
+  }
+  return null
+}
+
+// Build a resolver bound to options: `conditions` gates `exports` packages (delegated to Node),
+// `mainFields`/`platform`/`preferNative`/`sourceExts` drive the legacy-field + suffix probing.
+// `metro` opts into Metro's package-entry + candidate-redirect semantics (see
+// resolveEntryThroughMap and resolveSourceFile); leave it off for the esbuild-parity
+// `--mainFields` path. `typescript` adds tsc's extension substitution (a missing `x.js` probes
+// its `x.ts` sibling; see resolveSourceFile) plus the shared miss fallback (see below), and
+// `typescriptPaths` (a loadTsconfigPaths matcher) its tsconfig alias mapping.
+// `metroKeepEntryOnBrowserFalse` overrides the module-level toggle
+// (METRO_KEEP_ENTRY_ON_BROWSER_FALSE) per resolver -- primarily so tests can cover both branches.
+// `host` is the filesystem view (@exodus/stasis-core/host), the real disk by default.
+export function createFieldResolver({
+  conditions = [],
+  mainFields = ['main'],
+  platform = null,
+  preferNative = false,
+  sourceExts = ['js', 'json', 'ts'],
+  metro = false,
+  typescript = false,
+  typescriptPaths = null,
+  metroKeepEntryOnBrowserFalse = METRO_KEEP_ENTRY_ON_BROWSER_FALSE,
+  host = diskHost,
+} = {}) {
+  const opts = { platform, preferNative, sourceExts, mainFields, metro, typescript, metroKeepEntryOnBrowserFalse, host }
+  // `callConditions` (from scan) is the parent's format-driven condition set, so `exports`
+  // delegation matches Node resolving from THAT file; falls back to configured `conditions`.
+  const resolve = function resolve(parentFile, specifier, callConditions) {
+    const conds = new Set(callConditions ?? conditions)
+    const viaNode = (spec) => {
+      try {
+        return fileResolution(host.resolve(parentFile, spec, conds))
+      } catch {
+        return null
+      }
+    }
+    // `#name` subpath imports use the `imports` field + conditions; Node's algorithm handles them.
+    if (specifier.startsWith('#')) return viaNode(specifier)
+
+    let spec = specifier
+    // Redirect via the IMPORTER's browser/react-native map, BEFORE the builtin check on purpose:
+    // a map entry can disable or shim a builtin (`{"crypto": false}` / `"crypto-browserify"`).
+    const imp = nearestPackage(parentFile, host)
+    if (imp) {
+      const map = mergeRedirectMap(imp.pkg, mainFields)
+      let r
+      if (spec.startsWith('.') || isAbsolute(spec)) {
+        const abs = isAbsolute(spec) ? spec : resolvePath(dirname(parentFile), spec)
+        r = matchRedirect(map, `./${toPosix(relative(imp.pkgDir, abs))}`)
+      } else {
+        r = map.get(spec) // a bare specifier (`mod`, `mod/sub`) matches the map's bare keys
+      }
+      if (r === false) return { empty: true }
+      if (typeof r === 'string') {
+        // Browser-map targets are relative to the PACKAGE ROOT, not the importing file; a
+        // bare-module target re-enters resolution below.
+        if (r.startsWith('.') || isAbsolute(r)) {
+          return resolveFileOrDir(isAbsolute(r) ? r : resolvePath(imp.pkgDir, r), opts)
+        }
+        spec = r
+      }
+    }
+
+    // A builtin the browser map did not remap resolves to the builtin itself.
+    if (isBuiltin(spec)) return { builtin: true }
+
+    if (spec.startsWith('.') || isAbsolute(spec)) {
+      const base = isAbsolute(spec) ? spec : resolvePath(dirname(parentFile), spec)
+      return resolveFileOrDir(base, opts)
+    }
+
+    const loc = locatePackage(dirname(parentFile), spec, host)
+    if (!loc) return null
+    const pkg = readJson(join(loc.pkgDir, 'package.json'), host) ?? {}
+    // `exports` wins over mainFields; Node's algorithm resolves it (with conditions) correctly.
+    if (pkg.exports != null) return viaNode(spec)
+    // A bare package import resolves its directory via the same dir algorithm as any other.
+    if (loc.subpath === '') return resolveFileOrDir(loc.pkgDir, opts)
+    const sub = `./${loc.subpath}`
+    const r = matchRedirect(mergeRedirectMap(pkg, mainFields), sub)
+    if (r === false) return { empty: true }
+    const target = typeof r === 'string' ? r : sub
+    return resolveFileOrDir(join(loc.pkgDir, target), opts)
+  }
+  if (!typescript) return resolve
+  // --typescript: when the whole field flow leaves the specifier unresolved, give tsc's mapping
+  // the same shot the scanner's fallback gets, via the shared dispatcher. On this path it covers
+  // the layers the field resolver delegates to Node -- `exports`-bearing packages and `#` subpath
+  // imports, whose targets may name compiled files existing only as TS source -- plus tsconfig
+  // `paths` aliases; misses only, so no field/redirect/suffix resolution is ever overridden.
+  // (Relative paths re-probe tsc-style too -- redundant after resolveSourceFile, but harmless.)
+  return function resolveWithTypescriptFallback(parentFile, specifier, callConditions) {
+    const resolved = resolve(parentFile, specifier, callConditions)
+    if (resolved) return resolved
+    const hit = resolveTypescriptFallback(parentFile, specifier, {
+      conditions: new Set(callConditions ?? conditions),
+      tsx: sourceExts.includes('tsx'),
+      paths: typescriptPaths,
+      host,
+    })
+    return hit == null ? null : fileResolution(hit)
+  }
+}
+
+// True when `format` is an ESM family (drives the base condition set, mirroring scan).
+function isModuleFormat(format) {
+  return format === 'module' || format === 'module-typescript'
+}
+
+// Condition set for a parent of the given format: Node's format-driven base (matching scan's
+// #conditionsFor) plus extras. Order is irrelevant (Node membership-tests against exports key order).
+export function resolveConditions(format, extras = []) {
+  const base = isModuleFormat(format)
+    ? ['node', 'import', 'module-sync', 'node-addons']
+    : ['node', 'require', 'module-sync', 'node-addons']
+  return [...new Set([...base, ...extras])]
+}