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

package/src/cmd/bundle.js

@@ -1,20 +1,22 @@
 import { isUtf8 } from 'node:buffer'
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
-import { dirname, extname, join, posix, relative, resolve } from 'node:path'
+import { basename, dirname, extname, join, posix, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { brotliDecompressSync } from 'node:zlib'
 
-import { Bundle } from '@exodus/stasis-core/bundle'
+import { Bundle, isValidRepoField } from '@exodus/stasis-core/bundle'
 import { Lockfile } from '@exodus/stasis-core/lockfile'
 import { importsTypescriptByOutputName, scan } from '../scan.js'
 import { createFieldResolver, resolveConditions } from '../resolve-fields.js'
 import { discoverTsconfig, isDir, loadTsconfigPaths, packageTsconfigPaths } from '../resolve-typescript.js'
 import { createMetroResolver } from '../metro-resolver.js'
+import { pinInstalledCommits } from '../installed-commits.js'
 import { State } from '@exodus/stasis-core/state'
 import { sha512integrity } from '@exodus/stasis-core/state-util'
-import { detectRepo, findPackageMetadata, normalizeEntries, packageType, readJson, readModuleManifest, readPackageJson, readRegularFileOrNull } from '@exodus/stasis-core/bundle-util'
-import { RN_CORE_INCLUDE_FILES, assertRealPathWithinBase, classifyNativeCapture, hasNodeModulesSegment, isDotEnvFile, isExcludedNativeDir, isExecutableFile, isNativeArtifact, isNativeManifest, isPathWithin, isPodspec, isSkippedNativeWalkDir, moduleFileKey, moduleInfo, parseResourcesOption, posixPathEscapes, refineNativeCapture, relativeEscapes, splitNodeModulesPath, toPosix } from '@exodus/stasis-core/util'
+import { checkoutCommit, detectRepo, findPackageMetadata, normalizeEntries, packageType, parseGithubRepository, readJson, readModuleManifest, readPackageJson, readRegularFileOrNull } from '@exodus/stasis-core/bundle-util'
+import { EMPTY_MODULE_PATH, RN_CORE_INCLUDE_FILES, assertRealPathWithinBase, classifyNativeCapture, hasNodeModulesSegment, isDotEnvFile, isExcludedNativeDir, isExecutableFile, isNativeArtifact, isNativeManifest, isPathWithin, isPodspec, isSkippedNativeWalkDir, moduleFileKey, moduleInfo, parseResourcesOption, posixPathEscapes, refineNativeCapture, relativeEscapes, splitNodeModulesPath, toPosix } from '@exodus/stasis-core/util'
 import { diskHost } from '@exodus/stasis-core/host'
+import { parseSoldeerLockfile } from '@preventive/lockfile/soldeer.js'
 import {
   SOLIDITY_PACKAGE_MANIFESTS,
   SOLIDITY_ROOT_MANIFESTS,
@@ -82,42 +84,105 @@ function parseSoldeerDir(seg) {
   return m ? { name: m[1], version: m[2] } : { name: seg, version: '0.0.0' }
 }
 
-// Extract `owner/repo` from a github.com remote (https/ssh/scp); null for non-github hosts.
-function githubSlug(url) {
-  const m = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/iu.exec(url)
-  return m ? `${m[1]}/${m[2]}` : null
-}
-
-// The github.com ones of `submodules` (readGitmodules), as Map<submodulePath, { name, branch }>.
+// A url as git fetches from a host: scp's `[user@]host:path`, with no scheme and a colon before its
+// first slash, or a URL of a transport git has itself (`http`, `https`, `git`, `ssh` and its
+// `git+ssh`/`ssh+git` aliases, lowercase, as git spells them), its authority, `[userinfo@]host[:port]`,
+// ending at the first slash after it. Not, then, what a package.json spells GitHub's that git reads
+// another way or not at all: `ssh://git@github.com:owner/name`, whose host is `github.com:owner` to
+// git; `git+https://` or `HTTPS://`, transports git doesn't have; nor `owner/name`, a path, as is any
+// url with no colon before its first slash.
+const GIT_URL = /^(?:[^/]*:(?!\/\/)|(?:https?|git|ssh|git\+ssh|ssh\+git):\/\/(?:[^/@]*@)?[^/:@]*(?::\d*)?\/)/u
+
+// The GitHub repository, `owner/name`, a .gitmodules `url` names (parseGithubRepository), else null:
+// none for a host merely holding `github.com` (`https://notgithub.com/o/n`), nor for a url git
+// doesn't fetch as one (GIT_URL), nor for npm's `github:owner/name`, the host `github`'s path to git,
+// whatever an ssh alias or `insteadOf` makes of it, nor one with a `#`, which git keeps in the path
+// it asks for (`owner/name.git#v1`) where npm takes a committish. git's `ssh+git://`, which a
+// package.json doesn't spell, is its `ssh://`.
+const submoduleGithub = (url) => (GIT_URL.test(url) && !/^github:/iu.test(url) && !url.includes('#') ? parseGithubRepository(url.replace(/^ssh\+git:/u, 'ssh:')) : null)
+
+// The GitHub ones of `submodules` (readGitmodules), as Map<submodulePath, { name, branch }>.
 function githubSubmodules(submodules) {
   const byPath = new Map()
   for (const { path, url, branch } of submodules) {
-    const name = url && githubSlug(url)
+    const name = url && submoduleGithub(url)
     if (name) byPath.set(path, { name, branch })
   }
   return byPath
 }
 
+// The root of the GitHub repository `github` at `commit`, where both are valid; else undefined.
+const repoRootAt = (github, commit) => (isValidRepoField('github', github) && isValidRepoField('commit', commit) ? { github, directory: '', commit } : undefined)
+
+// The text of `rel`, a file of the project root, read as `ownership` vouches for it; null where it
+// refuses it, nothing is there, or it isn't UTF-8.
+function ownedText(baseDir, rel, ownership, host) {
+  const { reason, real, outside } = ownership.of(rel)
+  if (reason || real === null || outside) return null
+  try {
+    const buf = readRegularFileOrNull(join(host.realpath(baseDir), real), rel, host)
+    return buf === null ? null : decodeUtf8(buf, rel)
+  } catch {
+    return null
+  }
+}
+
+// Each git dependency the root's soldeer.lock installs from GitHub, by its folder under
+// `dependencies/` (`<name>-<version>`, as Soldeer names it): the repository's root at the lockfile's
+// `rev`, which Soldeer checks out there. None where the lockfile can't be read or parsed: it is
+// metadata, which never stops a build.
+function soldeerGitRepos(baseDir, ownership, host) {
+  const text = ownedText(baseDir, 'soldeer.lock', ownership, host)
+  let lock = null
+  try {
+    lock = text === null ? null : parseSoldeerLockfile(text)
+  } catch {
+    // Not one Soldeer writes: nothing is recorded from it.
+  }
+  const repos = new Map()
+  for (const dep of Object.values(lock?.dependencies ?? {})) {
+    const repo = dep.type === 'git' ? repoRootAt(parseGithubRepository(dep.git), dep.rev) : undefined
+    if (repo !== undefined) repos.set(`${dep.name}-${dep.version}`, repo)
+  }
+  return repos
+}
+
 // Classify a Solidity file's dep bucket: Soldeer (`dependencies/<name>-<version>/`) or a
 // github submodule (`lib/`, via the `.gitmodules` `ownership` read), else null to defer to the
 // node_modules/workspace logic. `ownership.assert` vets a package.json path before it is read
-// through `host`.
+// through `host`. A bucket's `repo` is the GitHub repository it is checked out from, at its root, at
+// the commit its checkout's HEAD is at, as the bundle's own `repo` reads one: a submodule's, from
+// the GitHub repository its .gitmodules url names; a Soldeer git dependency's, where it is its
+// soldeer.lock `rev` (soldeerGitRepos), as Soldeer holds a checkout to the lockfile before taking it
+// for installed: a folder left at another commit since the lockfile changed, or no checkout, records
+// none.
 function makeSolidityClassifier(baseDir, ownership, host) {
   const submodules = githubSubmodules(ownership.submodules)
   const check = ownership.assert
   const versions = new Map() // a submodule's package.json version, read once
+  const commits = new Map() // a bucket's checkout's commit, read once
+  const commitOf = (dir) => {
+    if (!commits.has(dir)) commits.set(dir, checkoutCommit(join(baseDir, dir), host))
+    return commits.get(dir)
+  }
+  let soldeer // soldeerGitRepos, read at the first Soldeer file
   return (path) => {
     if (path.startsWith('dependencies/')) {
       const seg = path.slice('dependencies/'.length).split('/')[0]
       if (seg) {
         const { name, version } = parseSoldeerDir(seg)
-        return { bucketDir: `dependencies/${seg}`, name, version, ecosystem: 'soldeer' }
+        const bucketDir = `dependencies/${seg}`
+        soldeer ??= soldeerGitRepos(baseDir, ownership, host)
+        const locked = soldeer.get(seg)
+        const repo = locked !== undefined && commitOf(bucketDir) === locked.commit ? locked : undefined
+        return { bucketDir, name, version, ecosystem: 'soldeer', ...(repo === undefined ? {} : { repo }) }
       }
     }
     for (const [sub, { name, branch }] of submodules) {
       if (path === sub || path.startsWith(`${sub}/`)) {
         if (!versions.has(sub)) versions.set(sub, readPackageJson(baseDir, moduleFileKey(sub, 'package.json'), { strict: true, check, host })?.version)
-        return { bucketDir: sub, name, version: versions.get(sub) ?? branch ?? '0.0.0', ecosystem: 'github' }
+        const repo = repoRootAt(name, commitOf(sub))
+        return { bucketDir: sub, name, version: versions.get(sub) ?? branch ?? '0.0.0', ecosystem: 'github', ...(repo === undefined ? {} : { repo }) }
       }
     }
     return null
@@ -801,9 +866,11 @@ function innermostRootOf(baseDir, files, root, host) {
 const SOURCE_EXTS = ['js', 'jsx', 'json', 'ts', 'tsx']
 // React Native preset mainFields for `--metro` (which also sets the RN conditions + platform suffixes).
 const METRO_MAIN_FIELDS = ['react-native', 'browser', 'main']
-// Synthetic path for the empty module a browser/react-native `false` redirect resolves to,
-// carried as a real empty CJS file so the edge points at attestable bytes.
-const EMPTY_MODULE_PATH = '.stasis/empty-module.js'
+// What esbuild and webpack 5 both assert on every platform besides `import`/`require` and
+// `default`, and so `--mainFields` too: `module`, the bundler-only condition a package's ESM build
+// sits under, from an import and a require alike. (esbuild drops it when given conditions of its
+// own; webpack keeps it, as `--conditions` adds to it here.) Node and Metro never assert it.
+const BUNDLER_CONDITIONS = ['module']
 
 // Recursively collect the files under `dirAbs` whose name `keep` takes, skipping build output,
 // symlinks (cycle/escape hazard) and, directly in `dirAbs`, the dirs `skipAtRoot` names. Absolute
@@ -848,10 +915,11 @@ function nativeModuleFiles(pkgAbs, host) {
 
 // The built-in field/suffix resolver (resolve-fields.js) the legacy-field build resolves with on
 // `platform` (null for --mainFields), its `mainFields` (Metro's under --metro), and the conditions
-// it adds to Node's: --metro asserts the RN conditions (+ browser on web); --mainFields carries the
-// user's --conditions.
+// it adds to the bundler base (`import`/`require` + `default`, never Node's `node`; see
+// resolveConditions): --metro asserts the RN conditions (+ browser on web), Metro's own set;
+// --mainFields asserts esbuild's and webpack's `module` (BUNDLER_CONDITIONS) and the user's --conditions.
 export function fieldResolverFor(platform, { mainFields, metro = false, conditions = [], typescript = false, typescriptPaths = null, host = diskHost }) {
-  const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : conditions
+  const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : [...new Set([...BUNDLER_CONDITIONS, ...conditions])]
   const fields = metro ? METRO_MAIN_FIELDS : mainFields
   const resolver = createFieldResolver({
     mainFields: fields,
@@ -879,8 +947,17 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), env = process.env, e
   const absEntries = entries.map((e) => resolve(baseDir, e))
   const normalized = normalizeEntries(entries, cwd)
 
+  // A resolved file arrives by its real path, an entry as spelled: under a cwd named through a link,
+  // the files the scan reaches lie below the root's real path, not below `baseDir` as spelled. Either
+  // is the root; a file below neither is outside it. (Realpathed only when needed, so a missing cwd
+  // is still the scan's missing entry.)
+  let realRoot
   const toRel = (abs) => {
-    const rel = toPosix(relative(baseDir, abs))
+    let rel = toPosix(relative(baseDir, abs))
+    if (relativeEscapes(rel)) {
+      realRoot ??= host.realpath(baseDir)
+      rel = toPosix(relative(realRoot, abs))
+    }
     if (relativeEscapes(rel)) {
       throw new Error(`Bundle would reach a file outside the project root: ${abs}`)
     }
@@ -958,8 +1035,10 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), env = process.env, e
   const realBase = host.realpath(baseDir)
   for (const abs of reached) {
     const rel = toRel(abs)
-    // Security: the field resolver returns the lexical path, so an in-tree-named symlink
-    // escaping the root would slip past toRel's textual check -- realpath and fail closed.
+    // Security: a resolved file arrives by its real path, which toRel already holds to the root,
+    // but an entry is taken as spelled (and --metro-resolver keeps a path it can't realpath), so an
+    // in-tree-named symlink escaping the root would slip past toRel's textual check -- realpath and
+    // fail closed.
     assertRealPathWithinBase(realBase, baseDir, rel, host)
     const buf = host.readFile(abs)
     if (resourceRels.has(rel)) {
@@ -978,25 +1057,89 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), env = process.env, e
     put(EMPTY_MODULE_PATH, '', 'commonjs', Buffer.alloc(0))
   }
 
+  // The package a bundled file is in (findPackageMetadata: its pkgDir and identity, null where no
+  // manifest names one), memoized per directory so a package's many files don't each re-walk to it.
+  const packageOf = packageLookup(baseDir, { host })
+
   // --metro also carries each bundled dependency's native build-input surface (ios/android
-  // sources + podspecs), scoped to the node_modules packages actually in the bundle. Native
-  // source is stored as code under a language tag; other assets as 'resource'/'resource:base64'.
+  // sources + podspecs), scoped to the packages in the bundle installed or linked into
+  // node_modules. Native source is stored as code under a language tag; other assets as
+  // 'resource'/'resource:base64'.
   if (metro) {
-    const pkgDirs = new Set()
+    const pkgDirs = new Map() // package dir -> its package's name
+    // Follow the CODE/module graph only: a package reached solely for an asset (--resources) is
+    // not a linked native dependency, so it must not drag in its ios/android surface.
+    const isCode = (rel) => !resourceRels.has(rel)
     for (const abs of reached) {
-      // Follow the CODE/module graph only: a package reached solely for an asset (--resources) is
-      // not a linked native dependency, so it must not drag in its ios/android surface.
       const rel = toRel(abs)
-      if (resourceRels.has(rel)) continue
-      const nm = splitNodeModulesPath(rel)
-      if (nm) pkgDirs.add(nm.dir)
+      const nm = isCode(rel) && splitNodeModulesPath(rel)
+      if (nm) pkgDirs.set(nm.dir, nm.name)
+    }
+    // A package linked into node_modules from out of it (a workspace package) is reached by its real
+    // path, out of node_modules, but is a dependency all the same, however an import reaches it (by
+    // name or alias, through a browser/react-native map, by a relative path): one linked, under any
+    // name, into a node_modules its importer finds packages in (the directories the resolver looks
+    // in). One linked nowhere there is the project's own source.
+    const linksIn = new Map() // directory -> Set of the real package dirs linked into a node_modules it finds packages in
+    const linkedFrom = (dir) => {
+      let links = linksIn.get(dir)
+      if (links !== undefined) return links
+      const parent = dirname(dir)
+      links = new Set(parent === dir ? [] : linkedFrom(parent))
+      const link = (abs) => {
+        try {
+          const rel = toRel(host.realpath(abs))
+          if (!splitNodeModulesPath(rel)) links.add(rel)
+        } catch { /* a dangling link, or one out of the root, whose files the scan pass refused already */ }
+      }
+      const listing = (abs) => {
+        try {
+          return host.readdir(abs)
+        } catch {
+          return []
+        }
+      }
+      // As locatePackage: a directory named node_modules holds no node_modules of its own to look in.
+      if (basename(dir) !== 'node_modules') {
+        const nodeModules = join(dir, 'node_modules')
+        for (const ent of listing(nodeModules)) {
+          const abs = join(nodeModules, ent.name)
+          if (ent.name.startsWith('@')) {
+            // A scope holds packages, a directory or a link to one (a whole scope linked, where
+            // every package in it is reached through the link).
+            for (const scoped of listing(abs)) {
+              if (ent.isSymbolicLink() || scoped.isSymbolicLink()) link(join(abs, scoped.name))
+            }
+          } else if (ent.isSymbolicLink()) {
+            link(abs)
+          }
+        }
+      }
+      linksIn.set(dir, links)
+      return links
     }
-    for (const pkgDir of [...pkgDirs].toSorted()) {
+    for (const [parent, bySpec] of edges) {
+      for (const byPlatform of bySpec.values()) {
+        for (const target of byPlatform.values()) {
+          if (!isCode(target) || splitNodeModulesPath(target)) continue
+          const links = linkedFrom(dirname(join(baseDir, parent)))
+          // The linked root holding the target, nearest first: its entry may lie below a manifest of
+          // its own (a named dist/package.json), as a node_modules path names the package it's in.
+          let root = posix.dirname(target)
+          while (root !== '.' && !links.has(root)) root = posix.dirname(root)
+          // The project's own source isn't a dependency, nor is an import within the package itself.
+          if (root === '.' || parent.startsWith(`${root}/`) || pkgDirs.has(root)) continue
+          // Named by its own manifest, whatever name it's linked under.
+          pkgDirs.set(root, readPackageJson(baseDir, `${root}/package.json`, { host })?.name)
+        }
+      }
+    }
+    for (const [pkgDir, name] of [...pkgDirs].toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
       const pkgAbs = join(baseDir, pkgDir)
       // react-native core isn't a Pod (config reports it via reactNativePath, not `dependencies`),
       // so walk its whole tree for native source (React/, ReactCommon/, ReactAndroid/, ...) the same
       // way a native dep's ios/android surface is walked; every other dep gets its ios/android + podspecs.
-      const isRnCore = pkgDir.slice(pkgDir.lastIndexOf('node_modules/') + 'node_modules/'.length) === 'react-native'
+      const isRnCore = name === 'react-native'
       const files = isRnCore ? [] : nativeModuleFiles(pkgAbs, host)
       if (isRnCore) walkNative(pkgAbs, files, host, isNativeSource)
       for (const abs of files) {
@@ -1036,12 +1179,9 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), env = process.env, e
 
   // --package-json: fold each bundled module's package.json into `sources` (and its integrity into
   // the companion lockfile) even when the scan never reached it. Buckets are the ones
-  // assembleCodeBundle derives, from the same `packageOf` (findPackageMetadata -> pkgDir, else the
-  // '.' workspace bucket; packageLookup memoizes it per directory so a package's many files don't
-  // each re-walk to the same manifest). readModuleManifest applies the read/validate rules shared
-  // with the State path (containment, UTF-8-aborts); no identity check here -- these buckets are
-  // all fresh from disk.
-  const packageOf = packageLookup(baseDir, { host })
+  // assembleCodeBundle derives, from the same `packageOf` (its pkgDir, else the '.' workspace
+  // bucket). readModuleManifest applies the read/validate rules shared with the State path
+  // (containment, UTF-8-aborts); no identity check here -- these buckets are all fresh from disk.
   if (packageJSON) {
     const pkgDirs = new Set()
     for (const abs of reached) {
@@ -1236,14 +1376,17 @@ async function buildJs({ mainFields, platforms, metro, metroResolver, innermostR
   return { bundle: state.sourceBundle.withReason('bundle'), lockfile: () => state.lockfile, stateBuilt: true, root: state.root }
 }
 
-// The bundle of `kind` (classifyEntries') built from buildBundle's options.
+// The bundle of `kind` (classifyEntries') built from buildBundle's options, from disk: a JS bundle's
+// git dependencies at the commits their package managers' records name (pinInstalledCommits).
 // -> { bundle, lockfile: () => Lockfile, stateBuilt } (the last two of a JS bundle alone)
 async function buildOfKind(kind, { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }) {
   if (kind === 'sol') return { bundle: await buildSolidityBundle({ cwd, env, entries, mappingFile, manifests }) }
   if (kind === 'php') return { bundle: await buildPhpBundle({ cwd, entries }) }
   if (kind === 'bash') return { bundle: await buildBashBundle({ cwd, entries }) }
   if (kind === 'rust') return { bundle: await buildRustBundle({ cwd, entries, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }) }
-  return buildJs({ cwd, env, entries, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON })
+  const built = await buildJs({ cwd, env, entries, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON })
+  pinInstalledCommits(built.bundle, built.root)
+  return built
 }
 
 // buildVfsBundle's checks of `options`, which hold before anything is fetched (`host` the
@@ -1272,13 +1415,16 @@ export function checkVfsOptions(name, options) {
 // tree before the scan, leaving `vfs` as it is (vfs-bundle/prisma.js). `client`, a
 // @preventive/upstream/github.js client, is what a Soldeer git dependency is fetched through; without
 // one, a soldeer.lock holding one is refused, naming deptree's `github`, before anything is fetched.
-// `root` is the directory in the Vfs the bundle's paths are relative to: cwd, or for a JS bundle
-// built through a State, the State's root, which is at or above it.
+// `cache` is where npm packages' tarballs and version documents are kept (checkCache). Each
+// dependency is recorded at the commit the tree installs it from, where deptree names one
+// (pinCommits). `root` is the directory in the Vfs the bundle's paths are relative to: cwd, or for a
+// JS bundle built through a State, the State's root, which is at or above it.
 // -> { bundle: Bundle, lockfile: Lockfile (of a JS bundle), stats, packageManager, root }
-export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc, repo, innermostRoot = false, generate = [], client, ...options } = {}) {
-  const { checkKind, checkTarget, checkVfs, loadTree, packageManagerFor, packageManagerOf, treeHost, vfsHost } = await import('../vfs-bundle/tree.js')
+export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc, repo, innermostRoot = false, generate = [], client, cache, ...options } = {}) {
+  const { checkCache, checkKind, checkTarget, checkVfs, loadTree, packageManagerFor, packageManagerOf, pinCommits, treeHost, vfsHost } = await import('../vfs-bundle/tree.js')
   checkVfs('buildVfsBundle', vfs)
   checkTarget('buildVfsBundle', { os, cpu, libc })
+  checkCache('buildVfsBundle', cache)
   // Checked as the Bundle checks it, before anything is fetched.
   if (repo !== undefined) repo = new Bundle({ repo }).repo
   const project = vfsHost(vfs)
@@ -1294,7 +1440,7 @@ export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageMa
     if (pm.kind === 'sol' && !abs.endsWith('.sol')) continue
     if (!posix.relative(cwd, abs).split('/').includes(pm.installs) && project.stat(abs) === null) throw new Error(`entry not found: ${abs}`)
   }
-  const tree = await loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client })
+  const tree = await loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client, cache })
   let { host } = tree
   if (generate.includes('prisma')) {
     const { generatePrismaClients, withPrismaClients } = await import('../vfs-bundle/prisma.js')
@@ -1306,6 +1452,7 @@ export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageMa
   if (repo !== undefined) bundle.repo = repo
   // Rooted at cwd, where `stasis bundle` detects its repo.
   else if (!stateBuilt) bundle.repo ??= detectRepo(cwd, host)
+  pinCommits(bundle, root, tree)
   return { bundle, lockfile: lockfile?.(), stats: tree.stats, packageManager, root }
 }
 

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 })
+  }
+}