@exodus/stasis 1.0.0-beta.0 → 1.0.0-beta.10

package/src/resolve-fields.js

@@ -0,0 +1,370 @@
+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 {
+  inNodeModules,
+  isDir,
+  isFile,
+  locatePackage,
+  nearestPackage,
+  readJson,
+  resolveTypescriptFallback,
+  typescriptSiblings,
+} from './resolve-typescript.js'
+import { diskHost } from '@exodus/stasis-core/host'
+import { createNodeResolver } from './resolve-node.js'
+
+// 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's algorithm, under a bundler's conditions rather than Node's (see
+// resolveConditions). No user code is executed (only package.json is stat/read).
+//
+// Returns, for each specifier:
+//   { url }      resolved to a file, by its real path (file: URL string; see fileResolution)
+//   { empty }    a browser/react-native field mapped it to `false` (empty module)
+//   { builtin }  a Node builtin: a `node:` specifier, or a builtin name no installed package resolves
+//   null         unresolved
+//
+// Browser and React Native targets have no Node builtins, so a bare builtin name (`buffer`,
+// `events`, `util`, `process`, ...) resolves to the installed npm package of that name, as esbuild
+// (platform browser), webpack 5 (target web) and Metro bundle it. Where nothing is installed it
+// stays a builtin, as the --metro-resolver adapter reports Metro's miss on one (metro-resolver.js),
+// rather than an unresolved edge: Metro and webpack fail the build there.
+
+// 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 }
+}
+
+// A resolved file by its REAL path (through `host`, so a Vfs host's links are followed too), as Node,
+// Metro and esbuild record one: under pnpm's isolated layout `node_modules/debug` links into
+// `node_modules/.pnpm/debug@x/node_modules/debug`, whose own imports (a sibling `ms`) resolve only
+// from where it really lies. Probing stays on the path as reached, so a candidate and the package
+// scope read from it (resolveSourceFile's metro redirect) are one spelling; only the hit is
+// realpathed. null where the file has no real path (gone since it was probed).
+function fileResolution(path, host) {
+  let real
+  try {
+    real = host.realpath(path)
+  } catch {
+    return null
+  }
+  return { url: pathToFileURL(real).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). Placed before that loop so `x.js` -> `x.ts` beats a pathological
+  // `x.js.<ext>`, matching tsc's candidate order. Never into node_modules: where tsc's pick, the
+  // first sibling on disk, lies there by its real path, nothing maps (inNodeModules), as the shared
+  // fallback refuses its own -- never a later sibling tsc wouldn't pick. The resolver drops
+  // `typescript` for an importer there.
+  if (opts.typescript) {
+    for (const cand of typescriptSiblings(base)) {
+      const hit = probePath(cand, true)
+      if (hit === null) continue
+      return typeof hit === 'string' && inNodeModules(hit, opts.host) ? null : 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, opts.host) : 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` (a resolveConditions set) gates `exports`
+// packages (delegated to Node's algorithm), `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 tsconfig paths matcher; see resolveTypescriptFallback) 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', 'jsx', 'json', 'ts', 'tsx'],
+  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 }
+  // An importer in node_modules gets no --typescript mapping (inNodeModules), wherever its import lands.
+  const fromNodeModules = { ...opts, typescript: false }
+  // Node answers a builtin name with the builtin itself, so an `exports`-bearing package named like
+  // one (see the header) resolves through this instead, with builtins off; built on first use.
+  let packageResolver
+  // `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 fileOpts = typescript && inNodeModules(parentFile, host) ? fromNodeModules : opts
+    const conds = new Set(callConditions ?? conditions)
+    const viaNode = (spec) => {
+      try {
+        if (!isBuiltin(spec)) return fileResolution(host.resolve(parentFile, spec, conds), host)
+        packageResolver ??= createNodeResolver(host)
+        return fileResolution(packageResolver.resolve(parentFile, spec, conds, { builtins: false }), host)
+      } catch {
+        return null
+      }
+    }
+    // A bare specifier (`mod`, `mod/sub`) through node_modules.
+    const viaPackage = (spec) => {
+      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, fileOpts)
+      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), fileOpts)
+    }
+    // `#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), fileOpts)
+        }
+        spec = r
+      }
+    }
+
+    if (spec.startsWith('.') || isAbsolute(spec)) {
+      const base = isAbsolute(spec) ? spec : resolvePath(dirname(parentFile), spec)
+      return resolveFileOrDir(base, fileOpts)
+    }
+
+    // A builtin the browser map did not remap: its `node:` form names the builtin itself; a bare
+    // name is the installed package of that name (see the header), the builtin where none resolves.
+    if (isBuiltin(spec)) return spec.startsWith('node:') ? { builtin: true } : (viaPackage(spec) ?? { builtin: true })
+    return viaPackage(spec)
+  }
+  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),
+      paths: typescriptPaths,
+      host,
+    })
+    return hit == null ? null : fileResolution(hit, host)
+  }
+}
+
+// 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, as scan's #conditionSet gives a custom resolver:
+// `import` or `require` by format, `default` (which Node's resolver matches anyway), plus extras.
+// A bundler's base, not Node's: esbuild, webpack and Metro assert `import`/`require` and
+// `default`, never `node`, so an `exports` map listing `node` first can't win over the extras.
+// Order is irrelevant (Node membership-tests against exports key order).
+export function resolveConditions(format, extras = []) {
+  return [...new Set([isModuleFormat(format) ? 'import' : 'require', 'default', ...extras])]
+}