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

package/src/audit-corrections.js

@@ -6,38 +6,62 @@ import { satisfies, valid } from '@preventive/upstream/semver.js'
 // package pulled in only through corrected files is skipped by the audit (see
 // collectPackagesFromFile) -- none of its real code ships, so no advisory applies.
 //
-// Each entry names a package, the audit-irrelevant files (relative to the module
-// dir), and `range` -- the semver range VERIFIED to match the rationale. The
-// correction never applies outside it: a release could change the file, so the
-// range is widened only after re-checking the file in the new versions.
-const CORRECTIONS = [
+// Exported as `@exodus/stasis/audit-corrections`, as plain data, so a tool that
+// lays out or reads packages without stasis -- a tree @preventive/deptree builds,
+// a server reading bundles -- can apply the same corrections without its own copy.
+// Each entry names a package of `ecosystem`, one audit-irrelevant `file` (relative
+// to the module dir), `range` -- the semver range VERIFIED to match the rationale --
+// and `integrity`, the sha512 of every distinct copy of `file` the versions in
+// `range` publish, as a stasis lockfile records a file: a holder of the file's bytes
+// can tell they are one of the copies verified. The correction never applies outside
+// the range: a release could change the file, so the range is widened only after
+// re-checking the file in the new versions, adding any new copy's integrity. Frozen,
+// as the audit reads these very objects.
+export const CORRECTIONS = Object.freeze([
   {
     // ws's browser build is a noop stub -- `module.exports = function () { throw
     // new Error('ws does not work in the browser...') }` -- with none of the
-    // WebSocket implementation in it. Verified against the ws 8.21.1 tarball
-    // (latest at the time of writing); re-check browser.js before widening.
+    // WebSocket implementation in it. browser.js ships from 6.0.0 on; every copy
+    // through 8.22.0 (latest at the time of writing) is one of these two, which
+    // differ only in a space; re-check browser.js before widening.
+    ecosystem: 'npm',
     name: 'ws',
-    files: new Set(['browser.js']),
-    range: '<=8.21.1',
+    file: 'browser.js',
+    range: '<=8.22.0',
+    integrity: [
+      'sha512-98uEc4/THUpHCA7AQwBKLHHmxV6leyGmPkDAYZsoBiigxjKL8//TIb/oUKDUJLc+s/pwdGA9LR0F9e7nZHfXUQ==', // `function ()`: 6.0.0 - 6.1.1, 7.3.1 - 8.22.0
+      'sha512-F7vx6oiX9vsFoxNPTudk20Hjp7IzJePAJCYaSoX9FMJ2JaGVcFx4Bkw5W7+I3a1DsonitnosbpuG1qAMsUwH7w==', // `function()`: 6.1.2 - 7.3.0
+    ],
   },
   {
     // node-fetch's browser build re-exports the environment's native fetch
     // (`module.exports = globalObject.fetch`, plus Headers/Request/Response) --
     // none of the node-fetch implementation, where its advisories live, is in it.
-    // browser.js ships only through 2.7.0 (3.x dropped it); verified 2.6.13/2.7.0.
+    // browser.js ships only from 2.0.0 through 2.7.0 (3.x dropped it); every copy
+    // in the range is one of these, which differ in how they find the global.
+    ecosystem: 'npm',
     name: 'node-fetch',
-    files: new Set(['browser.js']),
+    file: 'browser.js',
     range: '<=2.7.0',
+    integrity: [
+      'sha512-uCZB0X6rUVIf5lZU2NN9/Z1Fd6cPCLg4M9eduYxOgSP3QZNwi0/xSa/s6AUFtvLz4y4MK02SJihOIhDoFIzdiA==', // 2.0.0 - 2.1.1
+      'sha512-toQ4RDdyjsAxTaxnaLs2AE56rXws+jMZV896U8pP0MSuKRiq8ZGKkOTMsvyCJoAJTbrgoQpr89H2n8+Z1ALcYA==', // 2.1.2
+      'sha512-LOd+I1R3xYSCHFN9oj3xeN3wa7fYYx5XQKTiKkvWn4dSYVgHI2jsXZp0mJt5KlQg3ECXXh5UtpEW7kGu1dG/aQ==', // 2.2.0 - 2.2.1
+      'sha512-2yo4Ysl+g09ocycwEBcN7IkSvM/KPpO9CW+1FI+0QfzvWJfaQepo+WEqn1/o5Og1weM14flcdv23hqZtxFXFUw==', // 2.3.0 - 2.6.0
+      'sha512-WgHaZJVwFovVrKVySaKzxzXssn5kY8y3x8NJThodDRL9nwUxV7Q1z/RRzuLZ2lNkxabHLpG/l+vu7KQ2tGbP8g==', // 2.6.1 - 2.6.7
+      'sha512-84sQFcu3uzgEsJOjIhz6tE8vInV1STCA4sX5EI9NK3Tt8n/Kb1serbKMz+YkdOAuCspHRiSUW2qV01z0wOgIXg==', // 2.6.8
+      'sha512-SkBfLO20d2Ngr6nhxgh/Pt6Yqe6oW8EB99KSPq0lrW0se8jIiRF3YpOe7hHbfNWxuNCsKoZZT98uCJI9OJAa/Q==', // 2.6.9 - 2.7.0
+    ],
   },
-]
+].map((correction) => Object.freeze({ ...correction, integrity: Object.freeze(correction.integrity) })))
 
 // Is `rel` (a file path relative to the module dir) audit-irrelevant for
-// `name@version`? Unknown or unparsable versions are never corrected (fail
-// closed: the package stays audited).
-function isCorrectedFile(name, version, rel) {
-  for (const { name: pkg, files, range } of CORRECTIONS) {
-    if (pkg !== name || !files.has(rel)) continue
-    if (valid(version) && satisfies(version, range)) return true
+// `name@version` of `ecosystem`? Unknown or unparsable versions are never
+// corrected (fail closed: the package stays audited).
+function isCorrectedFile(name, version, rel, ecosystem) {
+  for (const correction of CORRECTIONS) {
+    if (correction.ecosystem !== ecosystem || correction.name !== name || correction.file !== rel) continue
+    if (valid(version) && satisfies(version, correction.range)) return true
   }
   return false
 }
@@ -65,8 +89,8 @@ const isManifest = (rel, ecosystem) => MANIFESTS[ecosystem]?.has(rel.slice(rel.l
 // Is `rel` evidence that `name@version`'s REAL code is present, of a dependency of
 // `ecosystem` (npm by default)? This is the one rule every audit surface shares --
 // package presence, the reason column, and the --why chain graph all count a file
-// (or an edge targeting it) only when it passes. Manifests never do; corrected
-// files (npm's) don't within their verified range.
+// (or an edge targeting it) only when it passes. Manifests never do; CORRECTIONS'
+// files don't within their verified range.
 export function isEvidenceFile(name, version, rel, ecosystem = 'npm') {
-  return !isManifest(rel, ecosystem) && (ecosystem !== 'npm' || !isCorrectedFile(name, version, rel))
+  return !isManifest(rel, ecosystem) && !isCorrectedFile(name, version, rel, ecosystem)
 }

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