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

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)

package/src/vfs-bundle/tree.js

@@ -1,7 +1,8 @@
 import { constants } from 'node:fs'
-import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path'
 
-import { NO_ENTRY, packageJSONStat, packageJSONText, readJson } from '@exodus/stasis-core/bundle-util'
+import { isValidRepoField } from '@exodus/stasis-core/bundle'
+import { NO_ENTRY, packageJSONStat, packageJSONText, parseGithubRepository, readJson } from '@exodus/stasis-core/bundle-util'
 import { byName } from '@exodus/stasis-core/host'
 import { hasNodeModulesSegment, isPlainObject } from '@exodus/stasis-core/util'
 import { buildNpmTree, findNpmWorkspaces } from '@preventive/deptree/npm.js'
@@ -114,6 +115,14 @@ export function checkTarget(name, { os, cpu, libc }) {
   if (libc !== undefined && !LIBCS.has(libc)) throw new TypeError(`${name}: libc must be one of 'glibc', 'musl', 'unknown'`)
 }
 
+// `cache`, where npm packages' tarballs and version documents are kept, as @preventive/upstream's
+// CacheOptions take it: left out, in setCacheDir's cache; a store with `read` and `write`, in place
+// of it; or false, nowhere. Checked as deptree checks it, before anything is fetched.
+export function checkCache(name, cache) {
+  if (cache === undefined || cache === false || (typeof cache?.read === 'function' && typeof cache?.write === 'function')) return
+  throw new TypeError(`${name}: cache must be false, or a store with read and write, or left out`)
+}
+
 // yarn installs a workspace from the root that declares it, whatever yarn.lock is nearer, and any
 // other package from the nearest yarn.lock.
 function yarn1Root(host, cwd) {
@@ -191,7 +200,7 @@ const PACKAGE_MANAGERS = {
     alone: async (names, above) => !(await above()).some((dir) => dir.includes('pnpm-workspace.yaml')),
     projects: (view, pnpm) => findPnpmProjects({ project: view, host: { pnpm } }),
     installs: 'node_modules',
-    build: (view, pnpm, _file, given) => buildPnpmTree({ project: view, host: { pnpm, ...target(given) } }),
+    build: (view, pnpm, _file, given) => buildPnpmTree({ project: view, host: { pnpm, ...target(given) }, cache: given?.cache }),
   },
   yarn1: {
     kind: 'js',
@@ -205,7 +214,7 @@ const PACKAGE_MANAGERS = {
     installs: 'node_modules',
     build: (view, yarn, file, given) => {
       const { libc: _, ...host } = target({ ...given, libc: 'unknown' }) // yarn 1 matches no libc
-      return naming(file, buildYarn1Tree({ project: view, host: { yarn, ...host } }))
+      return naming(file, buildYarn1Tree({ project: view, host: { yarn, ...host }, cache: given?.cache }))
     },
   },
   npm: {
@@ -218,7 +227,7 @@ const PACKAGE_MANAGERS = {
     alone: async (names, above) => !(await above()).some((dir) => dir.includes('package.json')),
     projects: (view, _npm, given) => findNpmWorkspaces({ project: view, os: target(given).os }),
     installs: 'node_modules',
-    build: (view, npm, file, given) => naming(file, buildNpmTree({ project: view, host: npmHost(npm, given) })),
+    build: (view, npm, file, given) => naming(file, buildNpmTree({ project: view, host: npmHost(npm, given), cache: given?.cache })),
   },
   soldeer: {
     kind: 'sol',
@@ -343,15 +352,17 @@ export function checkVfs(name, vfs) {
   }
 }
 
-// -> { root, vfs, projects, stats, packageManager, packageManagerVersion }, of the project `project`
-// holds that `cwd` is in, as `packageManager` installs it: the directory it installs from, as a real
-// path; a new Vfs holding the tree, rooted there; the directories of the projects it finds, from
-// there; deptree's counts; and the version reproduced, `packageManagerVersion` if given, else the one
-// the root package.json's packageManager pins, else the default. deptree reads the project through a
-// view of `project`, which nothing is written through. `client`, a @preventive/upstream/github.js
-// client, is what a Soldeer git dependency is fetched through (deptree's `github`); without one, a
-// lockfile holding one is refused before anything is fetched.
-async function layOutTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client }) {
+// -> { root, vfs, projects, stats, installed, packageManager, packageManagerVersion }, of the project
+// `project` holds that `cwd` is in, as `packageManager` installs it: the directory it installs from,
+// as a real path; a new Vfs holding the tree, rooted there; the directories of the projects it finds,
+// from there; deptree's counts, and what it installs, each by its `path` from there; and the version
+// reproduced, `packageManagerVersion` if given, else the one the root package.json's packageManager
+// pins, else the default. deptree reads the project through a view of `project`, which nothing is
+// written through. `client`, a @preventive/upstream/github.js client, is what a Soldeer git
+// dependency is fetched through (deptree's `github`); without one, a lockfile holding one is refused
+// before anything is fetched. `cache` (checkCache) is where npm packages' tarballs and version
+// documents are kept, which deptree fetches for pnpm, yarn1 and npm.
+async function layOutTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client, cache }) {
   const pm = PACKAGE_MANAGERS[packageManager]
   const found = pm.root(project, cwd, os)
   if (found === null) throw new Error(`no ${pm.lockfile} found in ${cwd} or any parent directory`)
@@ -364,17 +375,40 @@ async function layOutTree({ project, packageManager, cwd, packageManagerVersion,
   const projects = new Set(pm.projects(view, version, { os, cpu, libc }))
   const other = pm.kind === 'js' ? outsider(project, found, cwd, projects) : null
   if (other !== null) throw new Error(`${file} does not install ${other}: it is none of the lockfile's projects`)
-  const { vfs, stats } = await pm.build(view, version, file, { os, cpu, libc, client })
+  const { vfs, stats, installed } = await pm.build(view, version, file, { os, cpu, libc, client, cache })
   return {
     root: project.realpath(found),
     vfs,
     projects,
     stats,
+    installed,
     packageManager,
     packageManagerVersion: version ?? (String(pinned).startsWith(`${pm.pin}@`) ? /^[^@]+@([^+]+)/u.exec(pinned)[1] : undefined),
   }
 }
 
+// The root of the GitHub repository a git URL names, or undefined for another host's.
+const githubRoot = (url) => {
+  const github = parseGithubRepository(url)
+  return github === null ? undefined : { github, directory: '' }
+}
+
+// Each dependency of `bundle`, its paths from `root`, at the commit the tree (layOutTree's) installs
+// it from, where deptree names a full one: an npm package at its gitHead, which the registry's
+// version document names, a commit of the repository its own package.json names, so taken only
+// where the bundle records that one; a Soldeer git dependency at its lockfile's `rev`, the root of
+// the repository it is fetched from, where that is a GitHub one. Metadata, as `repo` is: the
+// publisher's word, held to no repository.
+export function pinCommits(bundle, root, { root: from, installed }) {
+  const byDir = new Map(installed.map((pkg) => [posix.relative(root, posix.join(from, pkg.path)), pkg]))
+  for (const [dir, info] of bundle.modules) {
+    const pkg = byDir.get(dir)
+    if (!isValidRepoField('commit', pkg?.commit)) continue
+    const repo = info.repo ?? githubRoot(pkg.git)
+    if (repo !== undefined) bundle.modules.set(dir, { ...info, repo: { ...repo, commit: pkg.commit } })
+  }
+}
+
 // fs.Stats#mode carries the file type above the permission bits a Vfs stat holds.
 const TYPE_BITS = { file: constants.S_IFREG, directory: constants.S_IFDIR, symlink: constants.S_IFLNK }
 

package/src/vfs-bundle.js

@@ -3,7 +3,7 @@ import { posix } from 'node:path'
 import { Vfs } from '@preventive/vfs'
 import { KINDS, checkAhead } from './vfs-bundle/entries.js'
 import { suggestedRepoEntries } from './vfs-bundle/github.js'
-import { NODE_MODULES_MANAGERS, checkTarget, checkVfs, detectPackageManager, loadTree, packageManagerFor, vfsHost } from './vfs-bundle/tree.js'
+import { NODE_MODULES_MANAGERS, checkCache, checkTarget, checkVfs, detectPackageManager, loadTree, packageManagerFor, vfsHost } from './vfs-bundle/tree.js'
 
 // @exodus/stasis/vfs-bundle: static bundles from a project's lockfile alone, through the
 // dependencies its package manager would install (`packageManager`: 'pnpm', pnpm 9, 10, 11 or 12;
@@ -30,10 +30,12 @@ export function createVfsHost(vfs) {
   return vfsHost(vfs, { cache: false })
 }
 
-// -> { root, vfs, projects, host, stats, packageManager, packageManagerVersion }, as 'pnpm',
-// 'yarn1' or 'npm' installs node_modules: the directory in the project's Vfs it installs cwd from,
-// which holds the lockfile; the Vfs the tree is laid out into, rooted there; the projects'
-// directories from there; the host reading the project through the tree; deptree's counts; and the
+// -> { root, vfs, projects, host, stats, installed, packageManager, packageManagerVersion }, as
+// 'pnpm', 'yarn1' or 'npm' installs node_modules: the directory in the project's Vfs it installs cwd
+// from, which holds the lockfile; the Vfs the tree is laid out into, rooted there; the projects'
+// directories from there; the host reading the project through the tree; deptree's counts, and the
+// packages it installs (each by its `path` from there, with the `commit` its version document
+// names, where it names a full one); and the
 // package manager reproduced, at `packageManagerVersion` if given, else the one the root
 // package.json's packageManager pins, else pnpm 10.33.4, yarn 1.22.22 or npm 11.21.0 (which nothing
 // pins: npm reads no packageManager). The host caches what it reads, of the project's Vfs too, so
@@ -41,15 +43,18 @@ export function createVfsHost(vfs) {
 // `os`, `cpu` and `libc` ('glibc', 'musl' or 'unknown', pnpm's and npm's, which takes 'unknown' for
 // none) are the machine packages are matched against: this one's but for what is given (for another
 // os, libc defaults to 'unknown'). Without a `packageManager`, it is the one of the three whose
-// lockfile installs cwd, where only one's does.
-export async function loadNodeModules({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc } = {}) {
+// lockfile installs cwd, where only one's does. `cache` is where the packages' tarballs and version
+// documents are kept, as @preventive/upstream's CacheOptions take it: left out, in setCacheDir's
+// cache; a store with `read` and `write`, in place of it; or false, nowhere.
+export async function loadNodeModules({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc, cache } = {}) {
   checkVfs('loadNodeModules', vfs)
   checkTarget('loadNodeModules', { os, cpu, libc })
+  checkCache('loadNodeModules', cache)
   const project = vfsHost(vfs)
   // A real path, as detection and the layout take it.
   cwd = project.realpath(posix.resolve('/', cwd))
   packageManager = packageManagerFor('loadNodeModules', project, cwd, { packageManager, packageManagerVersion, os }, NODE_MODULES_MANAGERS)
-  return loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc })
+  return loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, cache })
 }
 
 // -> the entries buildGitHubBundle takes where none are given, as paths from the project's