@exodus/stasis 1.0.0-beta.3 → 1.0.0-beta.5

package/src/scan.js

@@ -1,10 +1,11 @@
-import { readFileSync, existsSync } from 'node:fs'
 import { extname, resolve as resolvePath, relative } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { createRequire, isBuiltin } from 'node:module'
 import assert from 'node:assert/strict'
 import { packageType } from '@exodus/stasis-core/bundle-util'
-import { classifyExtension, classifyFormat } from '@exodus/stasis-core/util'
+import { classifyExtension, classifyFormat, relativeEscapes } from '@exodus/stasis-core/util'
+import { resolveTypescriptFallback } from './resolve-typescript.js'
+import { diskHost } from '@exodus/stasis-core/host'
 
 // Static require/import graph walker: parses source, never loads or executes user code.
 // Dynamic specifiers (`require(name)`, `import('./'+x)`) are recorded as unresolved.
@@ -54,10 +55,10 @@ function getFlowRemoveTypes() {
 // classifyFormat is the shared name->format authority (static and runtime bundles must agree); it
 // returns null for the .js/.ts family whose module system comes from package.json `type` (null =
 // detect from syntax, signaled up as null).
-function formatForFile(file) {
+function formatForFile(file, host) {
   const format = classifyFormat(file)
   if (format != null) return format
-  const type = packageType(file)
+  const type = packageType(file, host)
   if (type === null) return null
   return `${type}${extname(file) === '.ts' ? '-typescript' : ''}`
 }
@@ -127,15 +128,22 @@ export class Scan {
   // `jsx` opts the .js/.cjs/.mjs family into JSX syntax (React Native's JSX-in-.js convention);
   // off by default because oxc, like tsc, only auto-enables JSX for .jsx/.tsx by extension.
   // `flow`: strip Flow type syntax from JS-family sources before parsing (see #scanFile).
+  // `typescript`: retry a failed resolution with tsc's mapping (see #typescriptResolve), with
+  // `typescriptPaths` (a loadTsconfigPaths matcher) adding tsconfig alias support; only consulted
+  // on the built-in (Node) resolver -- a custom `resolve` owns its own TS handling.
   // `resources` (a `parseResourcesOption` Set of extensions/filenames): reached files matching it
   // are carried as opaque resources (bytes only) rather than rejected as un-carryable -- for graphs
   // that aren't fully loadable in JS (e.g. Metro consuming .png/.svg assets).
-  constructor({ conditions = [], resolve = null, jsx = false, flow = false, resources = new Set() } = {}) {
+  // `host`: the filesystem the walk reads and resolves through (@exodus/stasis-core/host).
+  constructor({ conditions = [], resolve = null, jsx = false, flow = false, typescript = false, typescriptPaths = null, resources = new Set(), host = diskHost } = {}) {
     this.extraConditions = [...conditions]
     this.customResolve = resolve
     this.jsx = jsx
     this.flow = flow
+    this.typescript = typescript
+    this.typescriptPaths = typescriptPaths
     this.resources = resources
+    this.host = host
     // --jsx widens the script/resolvable extension sets to include .jsx/.tsx, so those files are
     // parsed (not left as opaque leaves) and queued when reached. Off by default the base sets apply.
     this.scriptExts = jsx ? new Set([...SCRIPT_EXTS, ...JSX_FILE_EXTS]) : SCRIPT_EXTS
@@ -154,7 +162,7 @@ export class Scan {
     const queue = []
     for (const entry of entries) {
       const abs = resolvePath(entry)
-      assert.ok(existsSync(abs), `entry not found: ${abs}`)
+      assert.ok(this.host.stat(abs) !== null, `entry not found: ${abs}`)
       const url = pathToFileURL(abs).toString()
       this.entries.add(url)
       queue.push(url)
@@ -183,6 +191,28 @@ export class Scan {
     this.parseErrors.push({ url, format, message, recovered })
   }
 
+  // --typescript: resolve `spec` the way tsc maps TS sources, invoked only AFTER Node's own
+  // resolution missed -- so an on-disk `.js` (or any Node-resolvable target) always wins, and the
+  // mapping only completes a failed resolution, never rewrites a successful one. The rules
+  // (extension substitution, extensionless/index completion, manifest-target and tsconfig-paths
+  // mapping) live in the shared dispatcher (resolve-typescript.js), so this resolver and the
+  // legacy-field one cannot drift. The hit is realpathed to match req.resolve's canonical output
+  // (every other recorded edge is a realpath).
+  #typescriptResolve(parentFile, spec, conditions) {
+    const hit = resolveTypescriptFallback(parentFile, spec, {
+      conditions,
+      tsx: this.jsx,
+      paths: this.typescriptPaths,
+      host: this.host,
+    })
+    if (hit == null) return null
+    try {
+      return this.host.realpath(hit)
+    } catch {
+      return null
+    }
+  }
+
   // Strip Flow type syntax to plain JS via the optional flow-remove-types dep (resolved lazily; a
   // missing dep is an env error and propagates). Only invoked as a parse fallback (see #scanFile),
   // so plain-JS files never reach it. Returns the rewritten source, or null when the transform
@@ -219,8 +249,8 @@ export class Scan {
     }
 
     // declared === null: typeless package; Node decides .js/.ts by syntax, resolved after parse.
-    const declared = formatForFile(file)
-    const src = readFileSync(file, 'utf8')
+    const declared = formatForFile(file, this.host)
+    const src = this.host.readFile(file).toString('utf8')
 
     // Resolve the parser outside the try: a missing oxc-parser is an env error, not this
     // file's — it must not be swallowed into a silent zero-edge leaf.
@@ -244,8 +274,9 @@ export class Scan {
     // `-typescript` suffix; .jsx/.tsx deliberately land on plain module/commonjs (like a JSX-in-.js
     // file) — they're bundler-transformed, keyed by extension in `stasis build`, not Node-strippable,
     // so the "needs a JSX/TS transform" signal rides the .jsx/.tsx extension, not the format tag.
-    let format = declared
-      ?? `${parsed.module.hasModuleSyntax ? 'module' : 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
+    const tsSuffix = ext === '.ts' ? '-typescript' : ''
+    const detectedFormat = (p) => `${p.module.hasModuleSyntax ? 'module' : 'commonjs'}${tsSuffix}`
+    let format = declared ?? detectedFormat(parsed)
 
     // oxc recovers from syntax errors (reports them in parsed.errors) rather than throwing;
     // Warning/Advice severities aren't real parse errors.
@@ -259,7 +290,7 @@ export class Scan {
         const asModule = parser.parseSync(file, src, parseOptions('module'))
         if (nonWarning(asModule).length === 0) {
           parsed = asModule
-          format = `module${ext === '.ts' ? '-typescript' : ''}`
+          format = `module${tsSuffix}`
           errors = []
         }
       } catch { /* keep the script parse and its recorded errors */ }
@@ -278,7 +309,7 @@ export class Scan {
           const asFlow = parser.parseSync(file, flowSrc, parseOptions(baseSourceType))
           if (nonWarning(asFlow).length === 0) {
             parsed = asFlow
-            format = declared ?? `${parsed.module.hasModuleSyntax ? 'module' : 'commonjs'}${ext === '.ts' ? '-typescript' : ''}`
+            format = declared ?? detectedFormat(parsed)
             errors = []
           }
         } catch { /* keep the original parse + its errors */ }
@@ -298,19 +329,21 @@ export class Scan {
     }
 
     const specs = []
-    // Type-only edges (`import type`, `export type`) are erased before runtime — skip them so the
-    // bundle matches Node's load graph. Mixed (`{ type A, B }`) and bare side-effect imports are kept.
-    if (parsed.module?.staticImports) {
-      for (const imp of parsed.module.staticImports) {
-        if (imp.entries.length > 0 && imp.entries.every((e) => e.isType)) continue
-        specs.push({ kind: 'import', spec: imp.moduleRequest.value })
-      }
-    }
-    if (parsed.module?.staticExports) {
-      for (const exp of parsed.module.staticExports) {
-        for (const entry of exp.entries) {
-          if (entry.moduleRequest && !entry.isType) specs.push({ kind: 'export-from', spec: entry.moduleRequest.value })
-        }
+    // STATEMENT-level type-ness decides an edge, matching what survives type erasure at runtime
+    // (verbatimModuleSyntax / Node's own type stripping): an `import type` / `export type`
+    // statement is erased whole, so no edge; a statement that merely lists inline `type`
+    // specifiers (`import { type A }`, `export { type B } from`) -- or none at all (`import {}`,
+    // `export {} from`) -- still loads its module, so its edge is real. oxc's module records
+    // can't draw that line (`import type { A }` and `import { type A }` yield identical
+    // all-isType entries, and `export {} from` yields no entry at all), so the statements are
+    // read off the AST, where importKind/exportKind carry it.
+    for (const node of parsed.program.body) {
+      if (node.type === 'ImportDeclaration') {
+        if (node.importKind !== 'type') specs.push({ kind: 'import', spec: node.source.value })
+      } else if (node.type === 'ExportNamedDeclaration') {
+        if (node.source != null && node.exportKind !== 'type') specs.push({ kind: 'export-from', spec: node.source.value })
+      } else if (node.type === 'ExportAllDeclaration') {
+        if (node.exportKind !== 'type') specs.push({ kind: 'export-from', spec: node.source.value })
       }
     }
     findCallSpecifiers(parsed.program, (s) => specs.push(s))
@@ -320,12 +353,17 @@ export class Scan {
     // IMPORT conditions -- the parent-format set baked the wrong `exports` branch into the bundle.
     // The custom (legacy-field) resolver keeps the format set: bundlers don't split per edge.
     const formatContext = ['module', 'module-typescript'].includes(format) ? 'import' : 'require'
-    const req = createRequire(file)
     const edges = []
     const specMaps = new Map() // condition key -> specifier -> child URL
-    const record = (key, spec, childURL) => {
+    const addChild = (s, key, childURL, childPath) => {
+      edges.push({ ...s, child: childURL })
       if (!specMaps.has(key)) specMaps.set(key, new Map())
-      specMaps.get(key).set(spec, childURL)
+      specMaps.get(key).set(s.spec, childURL)
+      if (this.resolvableExts.has(extname(childPath)) || this.#isResource(childPath)) queue.push(childURL)
+    }
+    const addUnresolved = (s, reason) => {
+      edges.push({ ...s, error: reason })
+      this.unresolved.push({ parentURL: url, kind: s.kind, spec: s.spec, reason })
     }
 
     for (const s of specs) {
@@ -346,13 +384,9 @@ export class Scan {
         } else if (r?.empty) {
           edges.push({ ...s, empty: true })
         } else if (r?.url) {
-          edges.push({ ...s, child: r.url })
-          record(key, s.spec, r.url)
-          const childPath = fileURLToPath(r.url)
-          if (this.resolvableExts.has(extname(childPath)) || this.#isResource(childPath)) queue.push(r.url)
+          addChild(s, key, r.url, fileURLToPath(r.url))
         } else {
-          edges.push({ ...s, error: 'MODULE_NOT_FOUND' })
-          this.unresolved.push({ parentURL: url, kind: s.kind, spec: s.spec, reason: 'MODULE_NOT_FOUND' })
+          addUnresolved(s, 'MODULE_NOT_FOUND')
         }
         continue
       }
@@ -360,17 +394,19 @@ export class Scan {
         edges.push({ ...s, builtin: true })
         continue
       }
+      let childPath
       try {
-        const childPath = req.resolve(s.spec, { conditions })
-        const childURL = pathToFileURL(childPath).toString()
-        edges.push({ ...s, child: childURL })
-        record(key, s.spec, childURL)
-        const childExt = extname(childPath)
-        if (this.resolvableExts.has(childExt) || this.#isResource(childPath)) queue.push(childURL)
+        childPath = this.host.resolve(file, s.spec, conditions)
       } catch (cause) {
-        edges.push({ ...s, error: cause.code ?? cause.message })
-        this.unresolved.push({ parentURL: url, kind: s.kind, spec: s.spec, reason: cause.code ?? cause.message })
+        // --typescript: complete the miss with tsc's mapping (see #typescriptResolve); the edge
+        // stays keyed by the ORIGINAL specifier -- only the target is the mapped file.
+        if (this.typescript) childPath = this.#typescriptResolve(file, s.spec, conditions)
+        if (childPath == null) {
+          addUnresolved(s, cause.code ?? cause.message)
+          continue
+        }
       }
+      addChild(s, key, pathToFileURL(childPath).toString(), childPath)
     }
 
     for (const [key, specMap] of specMaps) {
@@ -384,7 +420,7 @@ export class Scan {
     const rel = (url) => {
       const abs = fileURLToPath(url)
       const r = relative(root, abs)
-      if (r.startsWith('..')) throw new Error(`Path outside root: ${abs}`)
+      if (relativeEscapes(r)) throw new Error(`Path outside root: ${abs}`)
       return r
     }
     const relEdge = (e) => (e.child ? { ...e, child: rel(e.child) } : e)

package/src/vfs-bundle/entries.js

@@ -0,0 +1,140 @@
+import { join, normalize, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { readJson } from '@exodus/stasis-core/bundle-util'
+import { isAutoExcludedDir, isPlainObject, posixPathEscapes, relativeEscapes } from '@exodus/stasis-core/util'
+import { Vfs } from '@preventive/vfs'
+import { checkVfsOptions, fieldResolverFor } from '../cmd/bundle.js'
+import { foundrySourceDir } from '../loaders/foundry.js'
+import { resolveTypescriptFallback, typescriptExportsTarget } from '../resolve-typescript.js'
+import { checkKind, checkVersion, packageManagerOf, vfsHost } from './tree.js'
+
+const JS = /\.[cm]?[jt]s$/u
+// Node's own conditions for require() and for import, which the build's are added to.
+const NODE_CONDITIONS = [['require', 'node', 'node-addons', 'module-sync'], ['import', 'node', 'node-addons', 'module-sync']]
+
+// 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
+// `metro` through the build's field resolver, once per platform of `platforms` under `metro`; what
+// 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.
+function packageEntries(host, dir, { conditions = [], mainFields, metro = false, platforms = [], jsx = false, typescript = false } = {}) {
+  const real = host.realpath(dir)
+  const manifest = join(real, 'package.json')
+  const pkg = readJson(manifest, host)
+  if (!isPlainObject(pkg)) return []
+  const found = new Set()
+  const add = (file) => {
+    const rel = file === undefined ? '' : relative(real, file)
+    if (rel !== '' && !relativeEscapes(rel) && JS.test(rel)) found.add(rel)
+  }
+  const passes = metro || mainFields !== undefined
+    ? (metro ? platforms : [null]).map((platform) => fieldResolverFor(platform, { mainFields, metro, conditions, jsx, typescript, host }))
+    : [{ extras: conditions, mainFields: ['main'] }]
+  // Node's resolution of `specifier`, else under `typescript` the miss `mapped` as tsc maps it; a
+  // real path either way, or undefined.
+  const viaNode = (specifier, names, extras, mapped) => {
+    const set = new Set([...names, ...extras])
+    try {
+      return host.resolve(manifest, specifier, set)
+    } catch {
+      const hit = typescript ? mapped(set) : null
+      return hit === null ? undefined : host.realpath(hit)
+    }
+  }
+  for (const { extras, mainFields: fields, resolver } of passes) {
+    const entry = fields.map((name) => pkg[name]).find((value) => typeof value === 'string' && value !== '')
+    if (entry !== undefined && posixPathEscapes(entry)) continue
+    if (resolver === undefined) {
+      add(viaNode('./', NODE_CONDITIONS[0], extras, (set) => resolveTypescriptFallback(manifest, './', { conditions: set, tsx: jsx, host })))
+    } else {
+      // A real path, as Node's resolution gives and the scan takes.
+      const hit = resolver(manifest, './')
+      if (hit?.url !== undefined) add(host.realpath(fileURLToPath(hit.url)))
+    }
+  }
+  const { exports, name } = pkg
+  const keyed = isPlainObject(exports) && Object.keys(exports).some((key) => key.startsWith('.'))
+  const subpaths = keyed ? Object.keys(exports) : exports === undefined || exports === null ? [] : ['.']
+  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, tsx: jsx, host })))
+    }
+  }
+  const bins = typeof pkg.bin === 'string' ? [pkg.bin] : pkg.bin !== null && typeof pkg.bin === 'object' ? Object.values(pkg.bin) : []
+  for (const bin of bins) {
+    if (typeof bin === 'string' && !posixPathEscapes(bin) && host.stat(join(real, bin))?.isFile()) add(host.realpath(join(real, bin)))
+  }
+  return [...found]
+}
+
+// Directories whose .sol files are none of a project's entry points: its tests, scripts and mocks,
+// what it depends on or builds, and what no walk descends into.
+const SKIPPED_DIRS = new Set(['test', 'tests', 'script', 'scripts', 'mock', 'mocks', 'lib', 'node_modules', 'dependencies', 'out', 'cache', 'artifacts', 'build'])
+const isSkippedDir = (name) => SKIPPED_DIRS.has(name.toLowerCase()) || isAutoExcludedDir(name)
+// A .sol file but a test or script by its name.
+const isEntrySol = (entry) => entry.isFile() && entry.name.endsWith('.sol') && !/\.(?:t|s|test|spec)\.sol$/u.test(entry.name)
+
+// The .sol files under the directory `rel` of `real` that are entry points by name, but those in a
+// skipped directory; sorted. Links are not followed.
+function solidityFiles(host, real, rel) {
+  const out = []
+  const walk = (sub) => {
+    for (const entry of host.readdir(join(real, sub))) {
+      const path = sub === '.' ? entry.name : `${sub}/${entry.name}`
+      if (entry.isDirectory()) {
+        if (!isSkippedDir(entry.name)) walk(path)
+      } else if (isEntrySol(entry)) {
+        out.push(path)
+      }
+    }
+  }
+  walk(rel)
+  return out.toSorted()
+}
+
+// The entry points of the Soldeer project in `dir`, by name and layout, as paths from `dir`: its
+// .sol files directly in it, then those under contracts/, then those under its source directory
+// (its foundry.toml's default profile's `src`, else `src`); none of its tests, scripts or mocks,
+// nor any in what it depends on or builds. A link to a directory is none.
+function solidityEntries(host, dir) {
+  const real = host.realpath(dir)
+  const isDirectory = (rel) => !posixPathEscapes(rel) && host.stat(join(real, rel))?.isDirectory() && host.readlink(join(real, rel)) === null
+  const under = (rel) => (isDirectory(rel) ? solidityFiles(host, real, rel) : [])
+  const src = normalize(foundrySourceDir(real, { host })).replace(/\/+$/u, '')
+  const own = host.readdir(real).filter(isEntrySol).map((entry) => entry.name).toSorted()
+  return [...new Set([...own, ...under('contracts'), ...(src === 'contracts' ? [] : under(src))])]
+}
+
+// By the kind of bundle a package manager builds: an entry its options are checked over before
+// there are any, the entries the build takes where none are given, and what having none says.
+export const KINDS = {
+  js: { standIn: 'index.js', entries: packageEntries, none: 'has no package.json naming a JS entry point there' },
+  sol: { standIn: 'index.sol', entries: solidityEntries, none: 'has no .sol entry point directly in it, under contracts/, or under its source directory' },
+}
+
+const EMPTY = vfsHost(new Vfs())
+
+// The build's checks of `options` before anything is fetched, over an empty tree, which never
+// decides them: for the package manager given, else for any; over the entries given, else over one
+// of the kind the default ones are. -> the PACKAGE_MANAGERS entry of the one given
+export function checkAhead(name, packageManager, options) {
+  checkVersion(name, { packageManager, ...options })
+  const pm = packageManager === undefined ? undefined : packageManagerOf(name, packageManager)
+  const refusal = (entries) => {
+    try {
+      checkKind(name, checkVfsOptions(name, { ...options, entries, cwd: '/', host: EMPTY, fetched: false }), packageManager === undefined ? undefined : [packageManager])
+      return null
+    } catch (error) {
+      return error
+    }
+  }
+  const refusals = options.entries === undefined ? (pm === undefined ? Object.values(KINDS) : [KINDS[pm.kind]]).map(({ standIn }) => refusal([standIn])) : [refusal(options.entries)]
+  if (!refusals.includes(null)) throw refusals[0]
+  return pm
+}

package/src/vfs-bundle/github.js

@@ -0,0 +1,193 @@
+import { posix } from 'node:path'
+
+import { isValidRepoField } from '@exodus/stasis-core/bundle'
+import { posixPathEscapes } from '@exodus/stasis-core/util'
+import { decompress } from '@preventive/archive/compression.js'
+import { ArchiveError, unpack } from '@preventive/archive/tar.js'
+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, lockfileRoot, lockfilesListed, noLockfile, packageManagerOf, vfsHost } from './tree.js'
+
+// As upstream's tree verification bounds a tarball's unpacked size.
+const MAX_TAR_BYTES = 2 ** 30
+// What a git tree holds (upstream's verification refuses anything else from GitHub).
+const TREE_TYPES = new Set(['file', 'directory', 'symlink'])
+// Lockfile references to a path above the lockfile's directory (conservatively: any importer's):
+// pnpm's and yarn's specs, and package-lock.json's package keys and `resolved` paths, `..` itself
+// (`link:..`, npm's `".."`) or under it.
+const LOCKFILE_ESCAPE = /(?:link:|file:|directory: |["'])\.\.(?![^/"'\s])/u
+const TSCONFIG = /(?:^|\/)[jt]sconfig[^/]*\.json$/u
+
+// Whether `target`, a path relative to the file `from`, resolves outside the tree.
+const resolvesOutside = (from, target) => target.startsWith('/') || posixPathEscapes(posix.join(posix.dirname(from), target))
+
+// The mode a checkout gives an entry under the usual umask 022. Git keeps only a file's executable
+// bit (upstream verifies that much), and GitHub's tarballs are written with git archive's tar.umask
+// 0002, which makes them 664 and 775 besides.
+const checkoutMode = ({ type, mode }) => (type === 'symlink' ? mode : type === 'directory' || mode & 0o100 ? 0o755 : 0o644)
+
+// A GitHub tarball's entries, its one top directory dropped, with the modes a checkout has.
+async function treeEntries(tarball, where) {
+  const entries = []
+  for (const entry of unpack(await decompress(tarball, 'gzip', { limit: MAX_TAR_BYTES }))) {
+    const name = entry.name.slice(entry.name.indexOf('/') + 1)
+    if (!TREE_TYPES.has(entry.type)) throw new Error(`${where}: unexpected ${entry.type} ${JSON.stringify(name)} in the tarball`)
+    if (entry.name.includes('/')) entries.push({ ...entry, name, mode: checkoutMode(entry) })
+  }
+  return entries
+}
+
+// The first symlink pointing outside the tree, which would otherwise resolve within it.
+const escapingLink = (entries) => entries.find((entry) => entry.type === 'symlink' && resolvesOutside(entry.name, entry.linkname))
+
+// Whether a subtree's files refer to a path above it: a lockfile link or a [jt]sconfig path.
+function refersAbove(entries, lockfile) {
+  const text = (entry) => new TextDecoder().decode(entry.data)
+  return entries.some((entry) => entry.type === 'file' && (entry.name === lockfile
+    ? LOCKFILE_ESCAPE.test(text(entry))
+    : TSCONFIG.test(entry.name) && [...text(entry).matchAll(/"(\.\.?\/[^"]*)"/gu)].some(([, path]) => resolvesOutside(entry.name, path))))
+}
+
+// The directories above `directory`, the repo's root (undefined) last.
+function ancestorsOf(directory) {
+  const out = []
+  for (let dir = posix.dirname(directory); dir !== '.'; dir = posix.dirname(dir)) out.push(dir)
+  return [...out, undefined]
+}
+
+// The files of the subtree `tree`, or null where one is a symlink out of it.
+async function treeFiles(client, { github, tree, where }) {
+  let files
+  try {
+    files = await treeEntries(await client.getRepoTreeTarball({ repo: github, tree }), where)
+  } catch (error) {
+    if (error instanceof ArchiveError) return null // e.g. a symlink out of the subtree
+    throw error
+  }
+  return escapingLink(files) ? null : files
+}
+
+// The whole repo's files at `sha`.
+async function repoFiles(client, { github, sha, where }) {
+  const files = await treeEntries(await client.getRepoTarball({ repo: github, sha }), where)
+  const link = escapingLink(files)
+  if (link) throw new Error(`${where}: symlink ${JSON.stringify(link.name)} points outside the repo`)
+  return files
+}
+
+// Checked as the Bundle checks them, before anything is fetched; a tag's name is upstream's to check.
+function checkRepo(name, { github, sha, tag, directory }) {
+  if (github === undefined) throw new Error(`${name}: github is required`)
+  if (tag !== undefined && (typeof tag !== 'string' || tag === '')) throw new TypeError(`${name}: tag must be a non-empty string`)
+  if (sha !== undefined && tag !== undefined) throw new Error(`${name}: sha and tag both name the commit: give one`)
+  for (const [key, value] of Object.entries({ github, commit: sha, directory: directory || undefined })) {
+    if (value !== undefined && !isValidRepoField(key, value)) throw new Error(`${name}: invalid ${key}: ${JSON.stringify(value)}`)
+  }
+}
+
+// listRepoDir's listing of a directory of the repo at `sha`, each listed once.
+function lister(client, { github, sha }) {
+  const listings = new Map()
+  return (directory) => {
+    if (!listings.has(directory)) listings.set(directory, client.listRepoDir({ repo: github, sha, directory }))
+    return listings.get(directory)
+  }
+}
+
+// Of no package manager given, the one whose lockfile alone `directory` (or the repo's root) and
+// the directories above it list, which is then the only one that may install it; refused where
+// none does; undefined where more than one does, or the listings can't tell, for the tree to tell.
+async function listedPackageManager(list, { directory, where }) {
+  let listings
+  try {
+    listings = await Promise.all((directory ? [directory, ...ancestorsOf(directory)] : [undefined]).map(list))
+  } catch {
+    // No plain directory in git (a symlink, or under one); the root's failure is GitHub's.
+    await list(undefined)
+    return undefined
+  }
+  const listed = lockfilesListed(listings)
+  if (listed.length === 0) throw noLockfile(where, posix.resolve('/', directory || '.'))
+  return listed.length === 1 ? listed[0] : undefined
+}
+
+// The files of `directory` alone, when it holds the lockfile, is installed from itself and stands
+// alone; else null.
+async function subtreeEntries(client, list, { github, directory, packageManager, where }) {
+  const names = async (path) => (await list(path)).map((entry) => entry.path)
+  let listing
+  try {
+    listing = await list(directory)
+  } catch {
+    return null // no plain directory in git (a symlink, or under one): the whole repo resolves it
+  }
+  if (!lockfilesListed([listing]).includes(packageManager)) return null
+  const above = ancestorsOf(directory)
+  // Installed from a root above it (a workspace's), it is built from there.
+  if (!(await installedAlone(packageManager, listing.map((entry) => entry.path), () => Promise.all(above.map(names))))) return null
+  // Its tree id, as the listing above it holds it, held to that directory's own.
+  const tree = (await list(above[0])).find((entry) => entry.path === posix.basename(directory) && entry.type === 'tree')?.sha
+  const files = tree === undefined ? null : await treeFiles(client, { github, tree, where })
+  return files === null || refersAbove(files, lockfileOf(packageManager)) ? null : files
+}
+
+// The repo as buildGitHubBundle downloads it, for `name`: at `sha`, else the commit `tag` names (an
+// annotated tag followed to it), else the default branch's head; `directory` alone where it stands
+// alone for the package manager installing it, else the whole repo. That package manager is
+// `packageManager` if given, else the one the listings tell, before the tree is fetched, else the
+// tree; `options` are checked for it once it is known.
+// -> { vfs, host, cwd, subtree, sha, where, packageManager, kind }
+async function repoTree(name, { github, sha, tag, directory, client, packageManager }, options) {
+  checkAhead(name, packageManager, options)
+  checkRepo(name, { github, sha, tag, directory })
+  client ??= createClient({ token: null })
+  sha ??= tag === undefined ? (await client.getRepoHead({ repo: github })).oid : (await client.getRepoTag({ repo: github, tag })).oid
+  const where = `${name}: ${github}@${sha}`
+  const list = lister(client, { github, sha })
+  let found = packageManager
+  if (found === undefined) {
+    found = await listedPackageManager(list, { directory, where })
+    if (found !== undefined) checkAhead(name, found, options)
+  }
+  const subtree = directory && found !== undefined ? await subtreeEntries(client, list, { github, directory, packageManager: found, where }) : null
+  const vfs = vfsFromEntries(subtree ?? await repoFiles(client, { github, sha, where }))
+  const host = vfsHost(vfs)
+  const cwd = posix.resolve('/', subtree ? '.' : directory ?? '.')
+  if (packageManager === undefined) {
+    const detected = detectPackageManager(where, host, cwd, { os: options.os })
+    if (detected !== found) checkAhead(name, detected, options)
+    found = detected
+  }
+  return { vfs, host, cwd, subtree, sha, where, packageManager: found, kind: KINDS[packageManagerOf(name, found).kind] }
+}
+
+// A GitHub repo at a full commit, or the one `tag` names, the default branch's head without either,
+// as buildVfsBundle builds it: `directory` downloaded alone where it stands alone, else the whole
+// repo, and without a `packageManager`, the one whose lockfile installs it, where only one's does
+// (repoTree). Without `entries`, they are the ones suggestedEntries suggests. `repo` names the
+// commit and where the lockfile is, which the bundle's paths are relative to. 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.
+export async function buildGitHubBundle({ github, sha, tag, directory, client, packageManager, ...options } = {}) {
+  checkTarget('buildGitHubBundle', options)
+  const tree = await repoTree('buildGitHubBundle', { github, sha, tag, directory, client, packageManager }, options)
+  const root = lockfileRoot(tree.host, tree.packageManager, tree.cwd, options.os)
+  const at = tree.subtree ? posix.join(directory, (root ?? '/').slice(1)) : (root ?? '/').slice(1)
+  const location = at === '' ? { root: true } : isValidRepoField('directory', at) ? { directory: at } : {}
+  let { entries } = options
+  if (entries === undefined) {
+    // As suggestedEntries suggests them, from the tree at hand.
+    entries = tree.kind.entries(tree.host, tree.cwd, options)
+    if (entries.length === 0) throw new Error(`${tree.where}: no entries given, and ${directory || 'the repo root'} ${tree.kind.none}`)
+  }
+  return buildVfsBundle({ ...options, entries, packageManager: tree.packageManager, vfs: tree.vfs, cwd: tree.cwd, repo: { github, commit: tree.sha, ...location } })
+}
+
+// suggestedEntries of a GitHub repo, `{ github, sha, tag, directory, client, packageManager }`, as
+// buildGitHubBundle downloads it.
+export async function suggestedRepoEntries(repo, resolution) {
+  const tree = await repoTree('suggestedEntries', repo, resolution)
+  return tree.kind.entries(tree.host, tree.cwd, resolution)
+}