@exodus/stasis 1.0.0-beta.7 → 1.0.0-beta.9

package/src/installed-commits.js

@@ -0,0 +1,182 @@
+import { hash } from 'node:crypto'
+import { dirname, join, relative, resolve } from 'node:path'
+
+import { toBase32 } from '@exodus/bytes/base32.js'
+import { isValidRepoField } from '@exodus/stasis-core/bundle'
+import { parseGithubRepository, readJson, readText } from '@exodus/stasis-core/bundle-util'
+import { diskHost } from '@exodus/stasis-core/host'
+import { isPlainObject, relativeEscapes, toPosix } from '@exodus/stasis-core/util'
+import { parsePnpmLockfile } from '@preventive/lockfile/pnpm.js'
+import { parseYarn1Lockfile } from '@preventive/lockfile/yarn1.js'
+
+// The commit each git dependency in a node_modules on disk is installed at, as the package manager
+// that laid it out recorded it there: npm in its hidden lockfile, pnpm in its copy of the lockfile,
+// yarn 1 in yarn.lock, as its .yarn-integrity has it installed. Nothing on disk names a registry
+// package's. A record missing, unreadable, or naming no full commit of a GitHub repository records
+// nothing, and fails nothing.
+
+// `{ github, commit }` of `repo`, a git URL, at `commit`, where that is a GitHub repository and a full
+// commit id; else undefined.
+function githubCommit(repo, commit) {
+  const github = parseGithubRepository(repo)
+  return github !== null && isValidRepoField('commit', commit) ? { github, commit } : undefined
+}
+
+// GitHub's tarball of a commit, as yarn 1 and pnpm fetch a GitHub dependency.
+const CODELOAD = /^https:\/\/codeload\.github\.com\/([^/]+\/[^/]+)\/tar\.gz\/([^/]+)$/u
+const githubTarball = (url) => {
+  const [, github, commit] = CODELOAD.exec(url) ?? []
+  return isValidRepoField('github', github) ? githubCommit(github, commit) : undefined
+}
+
+// githubCommit of a git or tarball resolution @preventive/lockfile reads.
+const resolutionCommit = (resolution) => {
+  if (resolution?.type === 'git') return githubCommit(resolution.repo, resolution.commit)
+  return resolution?.type === 'tarball' ? githubTarball(resolution.tarball ?? '') : undefined
+}
+
+// The lookup of a record that finds nothing: one unreadable, or none.
+const NONE = () => undefined
+
+// npm's, from npm 7: the hidden lockfile it writes into `dir`'s node_modules as it lays it out, by
+// each package's location from `dir`, where it records the version installed there. A git
+// dependency's `resolved` is the URL npm clones, `#` and the commit.
+function npmRecord(dir, host) {
+  const packages = readJson(join(dir, 'node_modules', '.package-lock.json'), host)?.packages
+  if (!isPlainObject(packages)) return NONE
+  return (location, version) => {
+    const entry = Object.hasOwn(packages, location) ? packages[location] : undefined
+    if (!isPlainObject(entry) || entry.version !== version || typeof entry.resolved !== 'string') return undefined
+    const { resolved } = entry
+    if (!/^git(?:\+[\w.-]+)?:/u.test(resolved)) return githubTarball(resolved)
+    const at = resolved.lastIndexOf('#')
+    return at === -1 ? undefined : githubCommit(resolved.slice(0, at), resolved.slice(at + 1))
+  }
+}
+
+// yarn 1's: yarn.lock in `dir`, by the name a package is installed as, the last of its location, and
+// its version, where one entry alone has both. The .yarn-integrity yarn writes into the node_modules
+// it lays out has to hold the entry's resolution for each of its patterns, as yarn.lock's `resolved`
+// spells it: a yarn.lock changed since often moves a git dependency to another commit of one version.
+function yarnRecord(dir, host) {
+  const installed = readJson(join(dir, 'node_modules', '.yarn-integrity'), host)?.lockfileEntries
+  const text = readText(host, join(dir, 'yarn.lock'))
+  if (!isPlainObject(installed) || text === null) return NONE
+  let packages
+  try {
+    packages = parseYarn1Lockfile(text, { checkVersions: false }).packages
+  } catch {
+    return NONE // whatever the reader refuses
+  }
+  const byVersion = new Map()
+  for (const { patterns, name, version, resolution } of new Set(Object.values(packages))) {
+    let commit = resolutionCommit(resolution)
+    const resolved = resolution?.type === 'git' ? `${resolution.repo}#${resolution.commit}` : resolution?.sha1 === undefined ? resolution?.tarball : `${resolution.tarball}#${resolution.sha1}`
+    if (!patterns.every((pattern) => Object.hasOwn(installed, pattern) && installed[pattern] === resolved)) commit = undefined
+    // Of two entries of one name and version, either may be the one installed.
+    const id = `${name}@${version}`
+    byVersion.set(id, byVersion.has(id) ? undefined : commit)
+  }
+  return (location, version) => byVersion.get(`${location.slice(location.lastIndexOf('node_modules/') + 'node_modules/'.length)}@${version}`)
+}
+
+// What npm and yarn leave in a node_modules they lay out, and the reader of each one's record.
+const LAYOUTS = [['.package-lock.json', npmRecord], ['.yarn-integrity', yarnRecord]]
+
+// The names pnpm 9 to 12 may give snapshot `key`'s directory in node_modules/.pnpm, as its
+// depPathToFilename (@pnpm/dependency-path) spells them: each character a path can't hold made `+`,
+// `#` too from pnpm 10, and a peer's parentheses `_`; where that is too long or has a capital, cut
+// short before `_` and a hash of it, 26 base32 of an MD5 for pnpm 9, 32 hex of a SHA-256 from pnpm 10,
+// of which the hash alone is kept, as where it is cut depends on the install's
+// virtualStoreDirMaxLength.
+const STORE_NAMES = [
+  [/[\\/:*?"<>|]/gu, (name) => toBase32(hash('md5', name, 'buffer'), { padding: false }).toLowerCase()],
+  [/[\\/:*?"<>|#]/gu, (name) => hash('sha256', name).slice(0, 32)],
+]
+const storeNames = (key) => STORE_NAMES.flatMap(([unsafe, digest]) => {
+  let name = key.replace(unsafe, '+')
+  if (name.includes('(')) name = name.replace(/\)$/u, '').replace(/\)\(|\(|\)/gu, '_')
+  return [name, `_${digest(name)}`]
+})
+const STORE_HASH = /_(?:[\da-f]{32}|[a-z2-7]{26})$/u
+
+// pnpm's: lock.yaml in `store`, a node_modules/.pnpm, the lockfile of what pnpm 9 to 12 installed
+// there, by the directory there each snapshot is in. A git dependency's resolution is the repository
+// and commit, or GitHub's tarball of the commit, and the package's `path` in it (`#path:`) where it is
+// not at the root.
+function pnpmRecord(store, host) {
+  const text = readText(host, join(store, 'lock.yaml'))
+  let packages
+  try {
+    packages = text === null ? undefined : parsePnpmLockfile(text).lockfile?.packages
+  } catch {
+    return NONE // whatever the reader refuses
+  }
+  const byName = new Map()
+  for (const [key, { resolution }] of Object.entries(packages ?? {})) {
+    const commit = resolutionCommit(resolution)
+    if (commit === undefined) continue
+    const directory = (resolution.path ?? '').replace(/^\/+|\/+$/gu, '')
+    const repo = { github: commit.github, ...(isValidRepoField('directory', directory) && { directory }), commit: commit.commit }
+    for (const name of storeNames(key)) byName.set(name, repo)
+  }
+  return (name) => byName.get(name) ?? byName.get(STORE_HASH.exec(name)?.[0])
+}
+
+// A pnpm package's real path, <store>/<dir>/node_modules/<name>, its store a node_modules/.pnpm.
+const PNPM_PACKAGE = /^(.*\/node_modules\/\.pnpm)\/([^/]+)\/node_modules\/(?:@[^/]+\/)?[^/]+$/u
+
+// Each npm dependency of `bundle`, its buckets' paths from `root`, that is a git dependency of a GitHub
+// repository, recorded as its package manager's record has it installed: that repository, over the
+// one its package.json names (a fork's, where that names the one forked), at its root (`''`) or the
+// subdirectory pnpm records, at that commit. A dependency is found by its real path, through the link
+// pnpm installs it by: in a node_modules/.pnpm, by its directory there; else by its location from the
+// nearest directory whose node_modules npm or yarn laid out, from the one its outermost node_modules
+// below the bundle root is in up to that root, whatever a directory above the root is named: a
+// record outside the root is another project's. Metadata, as `repo` is: never checked against the
+// files installed.
+export function pinInstalledCommits(bundle, root, host = diskHost) {
+  const stores = new Map()
+  const layouts = new Map()
+  let top // the bundle root's real path, as each package's is compared with it
+  // The record of `dir`'s node_modules, or null where neither npm nor yarn laid it out; where both
+  // left theirs, neither's, as which was last is not known.
+  const layoutAt = (dir) => {
+    if (!layouts.has(dir)) {
+      const found = LAYOUTS.filter(([file]) => host.stat(join(dir, 'node_modules', file)) !== null)
+      layouts.set(dir, found.length === 0 ? null : found.length === 1 ? found[0][1](dir, host) : NONE)
+    }
+    return layouts.get(dir)
+  }
+  for (const [dir, info] of bundle.modules) {
+    if (info.ecosystem !== 'npm') continue
+    let real
+    try {
+      real = toPosix(host.realpath(resolve(root, dir)))
+    } catch {
+      continue
+    }
+    let repo
+    const pnpm = PNPM_PACKAGE.exec(real)
+    if (pnpm !== null) {
+      const [, store, name] = pnpm
+      if (!stores.has(store)) stores.set(store, pnpmRecord(store, host))
+      repo = stores.get(store)(name)
+    } else {
+      try {
+        top ??= resolve(host.realpath(resolve(root)))
+      } catch {
+        return
+      }
+      const rel = relative(top, real)
+      const parts = toPosix(rel).split('/')
+      const at = parts.indexOf('node_modules')
+      if (relativeEscapes(rel) || at === -1) continue
+      let from = resolve(top, ...parts.slice(0, at))
+      while (layoutAt(from) === null && from !== top) from = dirname(from)
+      const commit = (layoutAt(from) ?? NONE)(toPosix(relative(from, real)), info.version)
+      if (commit !== undefined) repo = { github: commit.github, directory: '', commit: commit.commit }
+    }
+    if (repo !== undefined) bundle.modules.set(dir, { ...info, repo })
+  }
+}

package/src/loaders/php.js

@@ -9,6 +9,8 @@ import { readFile } from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { isDeepStrictEqual } from 'node:util'
 
+import { isValidRepoField } from '@exodus/stasis-core/bundle'
+import { checkoutCommit, parseGithubRepository } from '@exodus/stasis-core/bundle-util'
 import { assertRealPathWithinBase, isPlainObject, relativeEscapes, toPosix } from '@exodus/stasis-core/util'
 import { LockfileError, parseComposerLock } from '@preventive/lockfile/composer.js'
 import { isDir, isFile } from '../resolve-typescript.js'
@@ -532,20 +534,40 @@ function assertInstalledAsLocked(lockText, installedText, { installedFile, vendo
   return installed
 }
 
-// The Composer packages of the project at `baseDir`, `[{ name, version, dir, extra }]`, `dir` where
+// The GitHub repository a Composer package `p` (composer.lock's, or installed.json's) is cloned
+// from, at the commit it is installed at: its git `source` on GitHub, at its `reference` where that
+// is a full commit and what is installed at `at` (its directory, or null for none) is at it.
+// Installed from its source -- as installed.json's `installation-source`, `from`, says, or as it
+// must be with no dist, or as a git checkout there shows -- it is a clone Composer checked out at
+// the reference, which may have been moved since: so only where that checkout's HEAD is it. Else
+// from its dist, which Composer installs by default: only one at the same reference, as one with
+// none, or another, is an archive no commit is known of. Packagist takes a package from the root
+// of its repository, so `directory` is ''. Undefined otherwise.
+function composerRepo({ source, dist }, from, at) {
+  if (source?.type !== 'git') return undefined
+  const fromSource = from === 'source' || dist == null || (at !== null && existsSync(join(at, '.git')))
+  if (fromSource ? at === null || checkoutCommit(at) !== source.reference : dist.reference !== source.reference) return undefined
+  const github = parseGithubRepository(source.url)
+  return github !== null && isValidRepoField('commit', source.reference) ? { github, directory: '', commit: source.reference } : undefined
+}
+
+// The Composer packages of the project at `baseDir`, `[{ name, version, dir, extra, repo }]`, `dir` where
 // the package is installed, baseDir-relative (null for nowhere in baseDir, as a metapackage). Of
 // its composer.lock where there is one, read by @preventive/lockfile beside composer.json as
 // `composer install` reads them -- one it refuses stops the build -- each package where Composer
 // installs it (lockedDir), so no install is needed; else of vendor/composer/installed.json, as
 // it is. Where both are, installed.json must be the lockfile's install (assertInstalledAsLocked):
-// its packages, each where installed.json says.
+// its packages, each where installed.json says. `repo` is composerRepo's.
 export function loadComposerPackages(baseDir) {
   const { vendorDir } = readComposerJson(baseDir)
   const lockText = readUtf8OrNull(join(baseDir, 'composer.lock'), 'composer.lock')
   if (lockText === null) {
     return readInstalledPackages(baseDir, vendorDir)
       .filter((p) => p?.name && p.version)
-      .map((p) => ({ name: p.name, version: p.version, dir: installedDir(baseDir, vendorDir, p), extra: p.extra }))
+      .map((p) => {
+        const dir = installedDir(baseDir, vendorDir, p)
+        return { name: p.name, version: p.version, dir, extra: p.extra, repo: composerRepo(p, p['installation-source'], dir == null ? null : join(baseDir, dir)) }
+      })
   }
 
   const composerJson = readUtf8OrNull(join(baseDir, 'composer.json'), 'composer.json')
@@ -554,9 +576,13 @@ export function loadComposerPackages(baseDir) {
   const installedText = readUtf8OrNull(join(baseDir, installedFile), installedFile)
   const installed = installedText === null ? null : assertInstalledAsLocked(lockText, installedText, { installedFile, vendorDir })
   const dirs = installed === null ? null : new Map(installed.packages.map((p) => [p.name, installedDir(baseDir, vendorDir, p)]))
+  const from = new Map(installed?.packages.map((p) => [p.name, p['installation-source']]))
   return Object.values(lock.packages)
     .filter((p) => dirs === null || dirs.has(p.name))
-    .map((p) => ({ name: p.name, version: p.version, dir: dirs === null ? lockedDir(baseDir, vendorDir, p) : dirs.get(p.name), extra: p.extra }))
+    .map((p) => {
+      const dir = dirs === null ? lockedDir(baseDir, vendorDir, p) : dirs.get(p.name)
+      return { name: p.name, version: p.version, dir, extra: p.extra, repo: composerRepo(p, from.get(p.name), dir == null ? null : join(baseDir, dir)) }
+    })
 }
 
 // Build the autoload config for `baseDir`, merging the root composer.json
@@ -667,28 +693,28 @@ function matchingPrefixes(map, name) {
   return [...map].filter(([prefix]) => name.startsWith(prefix)).toSorted((a, b) => b[0].length - a[0].length)
 }
 
-// The versions of the Composer `packages` (loadComposerPackages: the authoritative source; a
-// package's own composer.json usually omits `version`), by where each is installed and by name.
+// The versions and repos of the Composer `packages` (loadComposerPackages: the authoritative source;
+// a package's own composer.json usually omits `version`), by where each is installed and by name.
 function packageVersions(packages) {
   const byDir = new Map()
   const byName = new Map()
-  for (const { name, version, dir } of packages) {
-    byName.set(name, version)
-    if (dir) byDir.set(dir, version)
+  for (const { name, version, dir, repo } of packages) {
+    byName.set(name, { version, repo })
+    if (dir) byDir.set(dir, { version, repo })
   }
   return { byDir, byName }
 }
 
 // Walk up from a bundled file to the nearest named composer.json, returning
-// { pkgDir, name, version } (pkgDir "." for the root; version from composer.lock or
+// { pkgDir, name, version, repo } (pkgDir "." for the root; version and repo from composer.lock or
 // installed.json by dir/name, else composer.json `version`, else `fallbackVersion`). Null if none.
 function findComposerPackage(baseDir, fileRelPath, installed, fallbackVersion) {
   let dir = dirname(fileRelPath)
   for (;;) {
     const cj = readJsonIfExists(join(baseDir, dir, 'composer.json'))
     if (cj?.name) {
-      const version = installed.byDir.get(dir) ?? installed.byName.get(cj.name) ?? cj.version ?? fallbackVersion
-      return { pkgDir: dir, name: cj.name, version }
+      const known = installed.byDir.get(dir) ?? installed.byName.get(cj.name)
+      return { pkgDir: dir, name: cj.name, version: known?.version ?? cj.version ?? fallbackVersion, repo: known?.repo }
     }
     if (dir === '.' || dir === '/' || dir === '') return null
     const parent = dirname(dir)
@@ -700,16 +726,17 @@ function findComposerPackage(baseDir, fileRelPath, installed, fallbackVersion) {
 // Group bundled PHP sources into per-package buckets keyed by the nearest
 // composer.json's directory (vendor deps get their own; workspace files and
 // orphans -> the root "." bucket with the placeholder identity). Returns a
-// Map<dir, { name, version, files }>. `packages`: loadComposerPackages(baseDir).
+// Map<dir, { name, version, ecosystem?, repo?, files }>, a dependency's `repo` where composerRepo
+// gives one. `packages`: loadComposerPackages(baseDir).
 export function bucketizePhpSources(baseDir, sources, fallbackName, fallbackVersion, packages = loadComposerPackages(baseDir)) {
   const installed = packageVersions(packages)
 
   const modules = new Map()
-  const ensureBucket = (dir, name, version, ecosystem) => {
+  const ensureBucket = (dir, name, version, ecosystem, repo) => {
     if (!modules.has(dir)) {
       modules.set(dir, ecosystem === undefined
         ? { name, version, files: Object.create(null) }
-        : { name, version, ecosystem, files: Object.create(null) })
+        : { name, version, ecosystem, ...(repo === undefined ? {} : { repo }), files: Object.create(null) })
     }
     return modules.get(dir)
   }
@@ -721,7 +748,7 @@ export function bucketizePhpSources(baseDir, sources, fallbackName, fallbackVers
       // Below the root package = an installed Composer dependency, tagged
       // `composer`; the root "." bucket is workspace code and stays ecosystem-less.
       const ecosystem = pkg.pkgDir === '.' ? undefined : 'composer'
-      ensureBucket(pkg.pkgDir, pkg.name, pkg.version, ecosystem).files[rel] = content
+      ensureBucket(pkg.pkgDir, pkg.name, pkg.version, ecosystem, pkg.repo).files[rel] = content
     } else {
       ensureBucket('.', fallbackName, fallbackVersion).files[path] = content
     }

package/src/resolve-fields.js

@@ -14,17 +14,25 @@ import {
   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. No user code is executed (only package.json is stat/read).
+// 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 real file (file: URL string)
+//   { 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
+//   { 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"),
@@ -106,7 +114,21 @@ function resolveEntryThroughMap(map, main, opts) {
   return { entry: main }
 }
 
-const fileResolution = (path) => ({ url: pathToFileURL(path).toString() })
+// 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) {
@@ -199,7 +221,7 @@ function resolveSourceFile(base, opts) {
 // 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 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)) {
@@ -219,8 +241,9 @@ function resolveFileOrDir(base, opts) {
   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.
+// 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
@@ -244,6 +267,9 @@ export function createFieldResolver({
   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) {
@@ -251,11 +277,28 @@ export function createFieldResolver({
     const conds = new Set(callConditions ?? conditions)
     const viaNode = (spec) => {
       try {
-        return fileResolution(host.resolve(parentFile, spec, conds))
+        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)
 
@@ -283,26 +326,15 @@ export function createFieldResolver({
       }
     }
 
-    // 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, fileOpts)
     }
 
-    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)
+    // 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
@@ -319,7 +351,7 @@ export function createFieldResolver({
       paths: typescriptPaths,
       host,
     })
-    return hit == null ? null : fileResolution(hit)
+    return hit == null ? null : fileResolution(hit, host)
   }
 }
 
@@ -328,11 +360,11 @@ 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).
+// 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 = []) {
-  const base = isModuleFormat(format)
-    ? ['node', 'import', 'module-sync', 'node-addons']
-    : ['node', 'require', 'module-sync', 'node-addons']
-  return [...new Set([...base, ...extras])]
+  return [...new Set([isModuleFormat(format) ? 'import' : 'require', 'default', ...extras])]
 }

package/src/resolve-node.js

@@ -385,9 +385,10 @@ export function createNodeResolver(host) {
 
   const notFound = (request, parentFile) => Object.assign(codedError('MODULE_NOT_FOUND', `Cannot find module '${request}'\nRequire stack:\n- ${parentFile}`), { requireStack: [parentFile] })
 
-  // Module._resolveFilename: -> the file's real path, or a builtin's id.
-  const resolveFilename = (parentFile, request, conditions) => {
-    if (isBuiltin(request)) return request
+  // Module._resolveFilename: -> the file's real path, or a builtin's id. Without `builtins`, a
+  // request naming a builtin is looked up like any bare name (see resolve).
+  const resolveFilename = (parentFile, request, conditions, builtins) => {
+    if (builtins && isBuiltin(request)) return request
     if (request === '') throw notFound(request, parentFile)
     if (request[0] === '#') {
       const pkg = readPackageScope(parentFile)
@@ -404,12 +405,14 @@ export function createNodeResolver(host) {
 
   return {
     // `conditions`: `require.resolve`'s own by default. A builtin returns its id, as it does.
-    resolve(parentFile, request, conditions = REQUIRE_CONDITIONS) {
+    // `builtins: false` resolves for a target with no Node builtins: a bare builtin name (`buffer`)
+    // is the installed package of that name, through its `exports` like any other.
+    resolve(parentFile, request, conditions = REQUIRE_CONDITIONS, { builtins = true } = {}) {
       parentFile = resolve(parentFile)
       if (!(conditions instanceof Set)) conditions = new Set(conditions)
-      const key = `${dirname(parentFile)}\0${request}\0${[...conditions].join(',')}`
+      const key = `${dirname(parentFile)}\0${request}\0${[...conditions].join(',')}${builtins ? '' : '\0nobuiltins'}`
       let hit = memo.get(key)
-      if (hit === undefined) memo.set(key, hit = resolveFilename(parentFile, request, conditions))
+      if (hit === undefined) memo.set(key, hit = resolveFilename(parentFile, request, conditions, builtins))
       return hit
     },
   }

package/src/scan.js

@@ -237,10 +237,15 @@ export class Scan {
     return this
   }
 
-  // Must match the runtime resolver's condition set (omitting one resolves `exports`-gated
-  // packages to a different file) AND its order: the recorded key must equal the runtime
-  // hooks' string for exact lookups. Extras go where Node puts user conditions in each set.
+  // Node's resolver: must match the runtime resolver's condition set (omitting one resolves
+  // `exports`-gated packages to a different file) AND its order: the recorded key must equal the
+  // runtime hooks' string for exact lookups. Extras go where Node puts user conditions in each set.
+  // A custom resolver (--mainFields/--metro) resolves for a bundler instead, so it gets what
+  // esbuild, webpack and Metro all assert: `import`/`require`, `default` (which Node's resolver
+  // matches anyway) and the extras, never `node`, `node-addons` or `module-sync`; the same set as
+  // resolve-fields.js's resolveConditions.
   #conditionSet(context) {
+    if (this.customResolve) return new Set([context, 'default', ...this.extraConditions])
     return context === 'import'
       ? new Set(['node', 'import', 'module-sync', 'node-addons', ...this.extraConditions])
       : new Set(['require', 'node', 'node-addons', ...this.extraConditions, 'module-sync'])

package/src/vfs-bundle/entries.js

@@ -6,12 +6,15 @@ import { isAutoExcludedDir, isPlainObject, posixPathEscapes, relativeEscapes } f
 import { Vfs } from '@preventive/vfs'
 import { checkVfsOptions, fieldResolverFor } from '../cmd/bundle.js'
 import { foundrySourceDir } from '../loaders/foundry.js'
+import { resolveConditions } from '../resolve-fields.js'
 import { resolveTypescriptFallback, typescriptExportsTarget } from '../resolve-typescript.js'
 import { checkKind, checkVersion, packageManagerOf, vfsHost } from './tree.js'
 
 const JS = /\.(?:[cm]?[jt]s|[jt]sx)$/u
-// Node's own conditions for require() and for import, which the build's are added to.
+// Node's own conditions for require() and for import, which the build's are added to; with
+// `mainFields` or `metro`, the field resolver's bundler ones instead (no `node`).
 const NODE_CONDITIONS = [['require', 'node', 'node-addons', 'module-sync'], ['import', 'node', 'node-addons', 'module-sync']]
+const FIELD_CONDITIONS = ['commonjs', 'module'].map((format) => resolveConditions(format))
 
 // The entry points the package.json in `dir` names, as paths from `dir`, resolved as the JS build
 // with the given options resolves: as Node does, `conditions` added, or with `mainFields` or
@@ -19,8 +22,9 @@ const NODE_CONDITIONS = [['require', 'node', 'node-addons', 'module-sync'], ['im
 // that misses mapped as tsc maps it under `typescript`, as the build's fallback maps it. In
 // that order: its own entry, as the build resolves `./` there (`main`, or the first of the main
 // fields, else index); each subpath `exports` holds (but a pattern), as the package's name resolves
-// for require() and for import, with the conditions the build adds (the RN ones under `metro`); and
-// each `bin`. Only JS files in `dir` that are there, named from within it; none without a package.json.
+// for require() and for import, with the conditions the build adds (the RN ones under `metro`) to
+// Node's, or with `mainFields` or `metro` to the field resolver's; and each `bin`. Only JS files in
+// `dir` that are there, named from within it; none without a package.json.
 function packageEntries(host, dir, { conditions = [], mainFields, metro = false, platforms = [], typescript = false } = {}) {
   const real = host.realpath(dir)
   const manifest = join(real, 'package.json')
@@ -62,8 +66,8 @@ function packageEntries(host, dir, { conditions = [], mainFields, metro = false,
   for (const subpath of typeof name === 'string' ? subpaths : []) {
     if (!subpath.startsWith('.') || subpath.includes('*') || subpath.endsWith('/')) continue
     const specifier = subpath === '.' ? name : `${name}${subpath.slice(1)}`
-    for (const { extras } of passes) {
-      for (const names of NODE_CONDITIONS) add(viaNode(specifier, names, extras, (set) => typescriptExportsTarget(real, exports, subpath, { conditions: set, host })))
+    for (const { extras, resolver } of passes) {
+      for (const names of resolver === undefined ? NODE_CONDITIONS : FIELD_CONDITIONS) add(viaNode(specifier, names, extras, (set) => typescriptExportsTarget(real, exports, subpath, { conditions: set, host })))
     }
   }
   const bins = typeof pkg.bin === 'string' ? [pkg.bin] : pkg.bin !== null && typeof pkg.bin === 'object' ? Object.values(pkg.bin) : []

package/src/vfs-bundle/github.js

@@ -8,7 +8,7 @@ import { createClient } from '@preventive/upstream/github.js'
 import { vfsFromEntries } from '@preventive/vfs'
 import { buildVfsBundle } from '../cmd/bundle.js'
 import { KINDS, checkAhead } from './entries.js'
-import { checkTarget, detectPackageManager, installedAlone, lockfileOf, lockfilesListed, noLockfile, packageManagerOf, vfsHost } from './tree.js'
+import { checkCache, checkTarget, detectPackageManager, installedAlone, lockfileOf, lockfilesListed, noLockfile, packageManagerOf, vfsHost } from './tree.js'
 
 // As upstream's tree verification bounds a tarball's unpacked size.
 const MAX_TAR_BYTES = 2 ** 30
@@ -172,8 +172,11 @@ async function repoTree(name, { github, sha, tag, directory, client, packageMana
 // one is outside the others; `repo` names that directory and the commit. Nothing is read from disk:
 // the tree's bytes come from GitHub, or from the cache setCacheDir names, held to the git tree id
 // either way (@preventive/upstream), and are unpacked into a Vfs that buildVfsBundle reads alone.
+// `cache` is buildVfsBundle's, for the npm packages the tree installs: the repo's tree is cached
+// where setCacheDir says, whatever it is.
 export async function buildGitHubBundle({ github, sha, tag, directory, client, packageManager, ...options } = {}) {
   checkTarget('buildGitHubBundle', options)
+  checkCache('buildGitHubBundle', options.cache)
   // Its own, for a Soldeer git dependency too.
   client ??= createClient({ token: null })
   const tree = await repoTree('buildGitHubBundle', { github, sha, tag, directory, client, packageManager }, options)