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

package/src/cmd/bundle.js

@@ -1,19 +1,19 @@
 import { isUtf8 } from 'node:buffer'
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
-import { extname, join, posix, relative, resolve } from 'node:path'
+import { 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 { Lockfile } from '@exodus/stasis-core/lockfile'
-import { scan } from '../scan.js'
+import { importsTypescriptByOutputName, scan } from '../scan.js'
 import { createFieldResolver, resolveConditions } from '../resolve-fields.js'
-import { discoverTsconfig, isDir, loadTsconfigPaths } from '../resolve-typescript.js'
+import { discoverTsconfig, isDir, loadTsconfigPaths, packageTsconfigPaths } from '../resolve-typescript.js'
 import { createMetroResolver } from '../metro-resolver.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, isPodspec, isSkippedNativeWalkDir, moduleFileKey, parseResourcesOption, posixPathEscapes, refineNativeCapture, relativeEscapes, splitNodeModulesPath, toPosix } from '@exodus/stasis-core/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 { diskHost } from '@exodus/stasis-core/host'
 import {
   SOLIDITY_PACKAGE_MANIFESTS,
@@ -37,7 +37,7 @@ import {
 } from '../loaders/php.js'
 import { DEFAULT_BUNDLE_FILE, bundledSummary, packagesLabel, writeBundle, writeFile } from './output.js'
 
-const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'])
+const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.jsx', '.tsx'])
 const BASH_EXTS = new Set(['.sh', '.bash'])
 const RUST_EXTS = new Set(['.rs'])
 
@@ -124,16 +124,26 @@ function makeSolidityClassifier(baseDir, ownership, host) {
   }
 }
 
+// A vendored crate's ecosystem, by where `cargo vendor` copied it from (vendoredFrom): a registry's
+// copy is `cargo`, which `stasis audit` asks OSV about as a crates.io crate's; a git checkout's is
+// `cargo-git`, and a copy with no `.cargo-checksum.json`, which could be either, `cargo-unknown`.
+// Neither is ever sent to a public advisory database: a private git dependency's name has no place
+// there, and a crates.io crate of the same name isn't it.
+const vendoredEcosystem = (from) => {
+  if (from === 'registry') return 'cargo'
+  return from === 'git' ? 'cargo-git' : 'cargo-unknown'
+}
+
 // Classify a Rust file by the nearest Cargo.toml `[package]`: a `cargo vendor`ed crate under the
 // vendor dir (`vendor/<dir>/`, or where .cargo/config.toml points) is a dependency (tagged
-// `cargo`); any other package (the crate itself, a workspace member reached through a `path`
-// dependency) is first-party, so no ecosystem. Null (no manifest above the file) defers to the
-// package.json/placeholder logic.
+// `cargo`, `cargo-git` or `cargo-unknown`: see vendoredEcosystem); any other package (the crate
+// itself, a workspace member reached through a `path` dependency) is first-party, so no
+// ecosystem. Null (no manifest above the file) defers to the package.json/placeholder logic.
 function makeRustClassifier(cargo) {
   return (path) => {
     const pkg = cargo.packageInfo(path)
     if (!pkg) return null
-    return { bucketDir: pkg.dir, name: pkg.name, version: pkg.version, ecosystem: cargo.isVendored(path) ? 'cargo' : undefined }
+    return { bucketDir: pkg.dir, name: pkg.name, version: pkg.version, ecosystem: cargo.isVendored(path) ? vendoredEcosystem(cargo.vendoredFrom(path)) : undefined }
   }
 }
 
@@ -195,19 +205,16 @@ function assembleCodeBundle({
   packageOf = packageLookup(baseDir, { host }),
 }) {
   const modules = new Map()
-  const ensureBucket = (dir, name, version, bucketEcosystem) => {
-    if (!modules.has(dir)) {
-      modules.set(dir, bucketEcosystem === undefined
-        ? { name, version, files: Object.create(null) }
-        : { name, version, ecosystem: bucketEcosystem, files: Object.create(null) })
-    }
+  // `identity`'s name, version, ecosystem and repo (moduleInfo takes those alone).
+  const ensureBucket = (dir, identity) => {
+    if (!modules.has(dir)) modules.set(dir, moduleInfo({ ...identity, files: Object.create(null) }))
     return modules.get(dir)
   }
 
   for (const [path, content] of sources) {
     const dep = classifyDep?.(path)
     if (dep) {
-      ensureBucket(dep.bucketDir, dep.name, dep.version, dep.ecosystem).files[fileInBucket(dep.bucketDir, path)] = content
+      ensureBucket(dep.bucketDir, dep).files[fileInBucket(dep.bucketDir, path)] = content
       continue
     }
     const meta = packageOf(path)
@@ -216,11 +223,10 @@ function assembleCodeBundle({
       if (inNodeModules && !hasNodeModulesSegment(meta.pkgDir)) {
         throw new Error(`No package.json with name+version found for ${path}`)
       }
-      const bucketEcosystem = hasNodeModulesSegment(meta.pkgDir) ? 'npm' : undefined
-      ensureBucket(meta.pkgDir, meta.name, meta.version, bucketEcosystem).files[fileInBucket(meta.pkgDir, path)] = content
+      ensureBucket(meta.pkgDir, meta).files[fileInBucket(meta.pkgDir, path)] = content
     } else {
       if (inNodeModules) throw new Error(`No package.json with name+version found for ${path}`)
-      ensureBucket('.', workspaceName, workspaceVersion).files[path] = content
+      ensureBucket('.', { name: workspaceName, version: workspaceVersion }).files[path] = content
     }
   }
 
@@ -586,6 +592,13 @@ function displayPath(url, baseDir) {
   return rel && !relativeEscapes(rel) ? rel : abs
 }
 
+// One unresolved scan edge for diagnostics, naming the file --typescript would resolve it to when
+// the scan found one (Scan#typescriptCandidate).
+function describeUnresolved(u, show) {
+  const typescript = u.typescriptURL ? `; resolves to ${show(u.typescriptURL)} under --typescript` : ''
+  return `${u.kind} ${u.spec ?? '<dynamic>'} from ${show(u.parentURL)} (${u.reason}${typescript})`
+}
+
 // Classify scanner unresolved edges + parse errors into fatal (broken/divergent at load)
 // vs tolerated (a catchable runtime miss). Shared so the plain and --mainFields JS paths
 // gate identically. `baseDir` relativizes the paths in the emitted messages (see displayPath).
@@ -607,7 +620,7 @@ function analyzeScanner(scanner, { baseDir }) {
   const fatalUnresolved = (u) => staticKinds.has(u.kind) && staticReachable.has(u.parentURL)
   const fatal = scanner.unresolved
     .filter((u) => fatalUnresolved(u))
-    .map((u) => `unresolved ${u.kind} ${u.spec} from ${show(u.parentURL)} (${u.reason})`)
+    .map((u) => `unresolved ${describeUnresolved(u, show)}`)
   // Fatal parse: an eagerly-linked module-family file, or any file the parser couldn't process.
   const fatalParse = (p) => staticReachable.has(p.url) && (p.format?.startsWith('module') === true || !p.recovered)
   for (const p of scanner.parseErrors) {
@@ -643,7 +656,7 @@ function reportScanIssues({ fatal, tolerated, toleratedParse }, { label = '', ba
     throw new Error(`JS bundle would be broken at load time${where}:\n${listed(fatal)}`)
   }
   if (tolerated.length > 0) {
-    const summary = listed(tolerated, (u) => `${u.kind} ${u.spec ?? '<dynamic>'} from ${show(u.parentURL)} (${u.reason})`)
+    const summary = listed(tolerated, (u) => describeUnresolved(u, show))
     console.warn(`[stasis] Bundle has ${tolerated.length} unresolved import(s)${where}; they will fall through at load time:\n${summary}`)
   }
   if (toleratedParse.length > 0) {
@@ -656,9 +669,15 @@ function reportScanIssues({ fatal, tolerated, toleratedParse }, { label = '', ba
 // token into the resolver.
 const cleanConditions = (conditions) => conditions.map((c) => (typeof c === 'string' ? c.trim() : c)).filter(Boolean)
 
-// --typescript honours tsconfig `paths` aliases: an explicit --tsconfig must exist, otherwise the
-// project root's tsconfig.json applies when present (null matcher = no aliases).
-const typescriptPathsFor = (typescript, baseDir, tsconfig, host) => (typescript ? loadTsconfigPaths(discoverTsconfig(baseDir, tsconfig, host), host) : null)
+// --typescript honours tsconfig `paths` aliases: an explicit --tsconfig's for every file (it must
+// exist), else those of the tsconfig.json beside each importing file's package.json
+// (packageTsconfigPaths, the project read as the State reads it, to `env`'s PROJECT_CWD; null
+// matcher = no aliases). Without --typescript they only hint a miss (Scan#typescriptCandidate), so a
+// config that doesn't load is none.
+function typescriptPathsFor(typescript, baseDir, tsconfig, host, env) {
+  if (typescript && tsconfig !== undefined) return loadTsconfigPaths(discoverTsconfig(baseDir, tsconfig, host), host)
+  return packageTsconfigPaths(baseDir, { host, lenient: !typescript, projectCwd: env.PROJECT_CWD })
+}
 
 // Build a JS/TS Bundle (in-memory) by statically scanning the require/import graph; no
 // user code is executed, and TS is stored verbatim (Node strips types at load). Scope comes
@@ -666,12 +685,15 @@ const typescriptPathsFor = (typescript, baseDir, tsconfig, host) => (typescript
 // extra `exports`/`imports` conditions; on their own they don't honour legacy mainFields or
 // platform suffixes (see `--mainFields` / buildResolvedJsBundle). `typescript` maps a failed
 // resolution to its on-disk TS source (tsc's rules; see resolve-typescript.js), honouring the
-// `paths` aliases of `tsconfig` (an explicit config path, default the project's tsconfig.json).
+// `paths` aliases of `tsconfig` (an explicit config path, default each package's tsconfig.json); it
+// is taken as given where the entries import TS sources by output name (importsTypescriptByOutputName).
 // Files are read through `host` (@exodus/stasis-core/host), the disk by default; EXODUS_STASIS_*
-// settings from `env`.
-export async function buildJsBundle({ cwd = process.cwd(), env = process.env, entries, scope, conditions = [], jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost } = {}) {
+// settings from `env`. With `innermostRoot`, the State is rooted at the innermost package at or
+// above cwd that holds every file the scan reaches (innermostRootOf), rather than at the project's
+// root above it, where that holds no stasis file of its own.
+export async function buildJsBundle({ cwd = process.cwd(), env = process.env, entries, scope, conditions = [], jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost, innermostRoot = false } = {}) {
   if (!Array.isArray(entries) || entries.length === 0) {
-    throw new Error('buildJsBundle: at least one entry .js/.cjs/.mjs/.ts/.cts/.mts file is required')
+    throw new Error('buildJsBundle: at least one entry .js/.cjs/.mjs/.ts/.cts/.mts/.jsx/.tsx file is required')
   }
   for (const e of entries) {
     if (!JS_EXTS.has(extname(e))) throw new Error(`buildJsBundle: not a JS/TS file: ${e}`)
@@ -684,7 +706,8 @@ export async function buildJsBundle({ cwd = process.cwd(), env = process.env, en
   // --resources: extensions/filenames carried as opaque assets instead of failing "can't carry".
   const resourceSet = parseResourcesOption('buildJsBundle', resources)
 
-  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host)
+  typescript ||= importsTypescriptByOutputName(absEntries, host)
+  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host, env)
 
   const scanner = scan(absEntries, { conditions: scanConditions, jsx, flow, typescript, typescriptPaths, resources: resourceSet, host })
 
@@ -696,7 +719,23 @@ export async function buildJsBundle({ cwd = process.cwd(), env = process.env, en
   // bundle:'replace' skips reading any on-disk stasis.code.br (bundle:'add' would leak stale
   // entries); lock:'ignore' tolerates a pre-existing lockfile without consuming it; and it is never
   // written, so it claims no write target.
-  const state = new State(baseDir, { bundle: 'replace', lock: 'ignore', ...(scope ? { scope } : {}), host, env, claim: false })
+  const stateOptions = { bundle: 'replace', lock: 'ignore', ...(scope ? { scope } : {}), host, claim: false }
+  let state = new State(baseDir, { ...stateOptions, env })
+  // A root holding a stasis file is the project's own choice, whose config the build takes.
+  if (innermostRoot && !STASIS_ROOT_FILES.some((file) => host.stat(join(state.root, file)) !== null)) {
+    const root = innermostRootOf(baseDir, [...scanner.files.keys()].map((url) => host.realpath(fileURLToPath(url))), state.root, host)
+    // The State's walk up from cwd stops at PROJECT_CWD, as it does where yarn sets it.
+    if (root !== state.root) state = new State(baseDir, { ...stateOptions, env: { ...env, PROJECT_CWD: root } })
+  }
+  // Named here rather than as the State's bare assertion: a stasis file in a directory below the
+  // project's root (a stray stasis.code.br there, say) roots the State at it, out of the files above.
+  for (const url of scanner.files.keys()) {
+    const file = fileURLToPath(url)
+    if (!relativeEscapes(relative(state.root, file))) continue
+    const markers = STASIS_ROOT_FILES.filter((name) => host.stat(join(state.root, name)) !== null)
+    const rootedBy = markers.length === 0 ? '' : ` (rooted there by its ${markers.join(' and ')}, which can be removed if stale)`
+    throw new Error(`buildJsBundle: ${relative(baseDir, file)} is outside the project root at ${relative(baseDir, state.root) || '.'}${rootedBy}`)
+  }
   for (const [url, info] of scanner.files) {
     // A resource carries bytes only: addFile derives resource vs resource:base64 from the content
     // and stores it under `resources` (a resource can't be an entry, so no isEntry).
@@ -740,14 +779,26 @@ export async function buildJsBundle({ cwd = process.cwd(), env = process.env, en
   return state
 }
 
-// Extensions probed when a resolved target names none. Limited to what a source bundle can
-// carry (scan's RESOLVABLE_EXTS) so the resolver never resolves a file the bundle would reject.
-// --jsx widens this to the JSX/TSX extensions (mirroring scan's jsx-gated RESOLVABLE_EXTS) so an
-// extensionless `import './Foo'` can land on Foo.jsx/Foo.tsx, as Metro's sourceExts do. `.js`/`.ts`
-// keep their existing precedence (base order preserved as a subsequence); collisions across the
-// added extensions are rare and, like the base list, don't track the project's real Metro order.
-const SOURCE_EXTS = ['js', 'json', 'ts']
-const SOURCE_EXTS_JSX = ['js', 'jsx', 'json', 'ts', 'tsx']
+// The files that root a State in the directory holding one (state.js's discovery).
+const STASIS_ROOT_FILES = ['stasis.config.json', 'stasis.lock.json', DEFAULT_BUNDLE_FILE]
+
+// The innermost directory at or above `baseDir`, up to `root`, holding every one of `files` (real
+// paths) and a package.json with a name, which a State can be rooted at; `root` where none below it
+// does. One without a name, such as a `{"type":"module"}` marker, is no root: the State takes such a
+// file's package to be the named one above it, which it then must hold.
+function innermostRootOf(baseDir, files, root, host) {
+  for (let dir = baseDir; dir !== root && dirname(dir) !== dir; dir = dirname(dir)) {
+    if (files.every((file) => isPathWithin(dir, file)) && readPackageJson(dir, 'package.json', { host })?.name !== undefined) return dir
+  }
+  return root
+}
+
+// Extensions probed when a resolved target names none, in Metro's default sourceExts order.
+// Limited to what a source bundle can carry (scan's RESOLVABLE_EXTS) so the resolver never
+// resolves a file the bundle would reject; an extensionless `import './Foo'` can land on
+// Foo.jsx/Foo.tsx, as it does under Metro. Like Metro's default, this doesn't track a project's
+// own sourceExts.
+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,
@@ -799,15 +850,14 @@ function nativeModuleFiles(pkgAbs, host) {
 // `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.
-export function fieldResolverFor(platform, { mainFields, metro = false, conditions = [], jsx = false, typescript = false, typescriptPaths = null, host = diskHost }) {
+export function fieldResolverFor(platform, { mainFields, metro = false, conditions = [], typescript = false, typescriptPaths = null, host = diskHost }) {
   const extras = metro ? ['react-native', ...(platform === 'web' ? ['browser'] : [])] : conditions
   const fields = metro ? METRO_MAIN_FIELDS : mainFields
   const resolver = createFieldResolver({
     mainFields: fields,
     platform,
     preferNative: platform !== null && platform !== 'web',
-    // Under --jsx the resolver probes .jsx/.tsx too, matching scan's jsx-widened carryable set.
-    sourceExts: jsx ? SOURCE_EXTS_JSX : SOURCE_EXTS,
+    sourceExts: SOURCE_EXTS,
     conditions: resolveConditions('commonjs', extras),
     // Opt into Metro's package-entry browser-field quirks only on the --metro path.
     metro,
@@ -824,7 +874,7 @@ export function fieldResolverFor(platform, { mainFields, metro = false, conditio
 // Build a JS/TS Bundle + companion Lockfile via the legacy-field resolver (`--mainFields`/
 // `--metro`). Scanned once per platform; each edge is recorded flat when the platforms that
 // have it agree, or as a `{ platform: target }` map where they diverge. Returns { bundle, lockfile }.
-async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields, platforms, conditions = [], metro = false, metroResolver = false, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost }) {
+async function buildResolvedJsBundle({ cwd = process.cwd(), env = process.env, entries, mainFields, platforms, conditions = [], metro = false, metroResolver = false, jsx = false, flow = false, typescript = false, tsconfig, resources = [], packageJSON = false, host = diskHost }) {
   const baseDir = resolve(cwd)
   const absEntries = entries.map((e) => resolve(baseDir, e))
   const normalized = normalizeEntries(entries, cwd)
@@ -839,10 +889,11 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
 
   const scanConditions = cleanConditions(conditions)
 
-  // Under --jsx the resolver probes .jsx/.tsx too, matching scan's jsx-widened carryable set.
-  const sourceExts = jsx ? SOURCE_EXTS_JSX : SOURCE_EXTS
+  // Taken as given where the entries import TS sources by output name, but under --metro-resolver,
+  // which has no tsc mapping (classifyEntries rejects --typescript there).
+  if (!metroResolver) typescript ||= importsTypescriptByOutputName(absEntries, host)
   // --typescript's tsconfig `paths` matcher, shared by every per-platform resolver below.
-  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host)
+  const typescriptPaths = typescriptPathsFor(typescript, baseDir, tsconfig, host, env)
   // --resources: extensions/filenames carried as opaque assets instead of failing "can't carry".
   const resourceSet = parseResourcesOption('buildResolvedJsBundle', resources)
 
@@ -855,16 +906,19 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
   let usesEmpty = false
 
   for (const platform of platforms) {
-    const field = fieldResolverFor(platform, { mainFields, metro, conditions: scanConditions, jsx, typescript, typescriptPaths, host })
+    const field = fieldResolverFor(platform, { mainFields, metro, conditions: scanConditions, typescript, typescriptPaths, host })
     const { extras } = field
     // --metro --metro-resolver delegates to the project's own metro-resolver for byte-for-byte Metro
     // fidelity; otherwise the built-in field/suffix resolver reproduces it. metro-resolver derives
     // default/require|import/platform conditions itself, so it takes only the extra `react-native`
     // condition (browser comes from its per-platform map, keyed on `web`).
     const resolver = metroResolver
-      ? createMetroResolver({ projectDir: baseDir, platform, sourceExts, mainFields, conditionNames: ['react-native'], host })
+      ? createMetroResolver({ projectDir: baseDir, platform, sourceExts: SOURCE_EXTS, mainFields, conditionNames: ['react-native'], host })
       : field.resolver
-    const scanner = scan(absEntries, { conditions: extras, resolve: resolver, jsx, flow, resources: resourceSet, host })
+    // Without --typescript, the field resolver --typescript would build names the file a miss would
+    // land on: a hint in the unresolved report, never an edge (see Scan#typescriptCandidate).
+    const typescriptResolve = typescript || metroResolver ? null : fieldResolverFor(platform, { mainFields, metro, conditions: scanConditions, typescript: true, typescriptPaths, host }).resolver
+    const scanner = scan(absEntries, { conditions: extras, resolve: resolver, typescriptResolve, jsx, flow, resources: resourceSet, host })
     reportScanIssues(analyzeScanner(scanner, { baseDir }), { baseDir, label: platform ?? 'mainFields' })
 
     const platformKey = platform ?? '*' // '*' is a private placeholder for the single mainFields pass; it never unflattens
@@ -1039,7 +1093,7 @@ async function buildResolvedJsBundle({ cwd = process.cwd(), entries, mainFields,
   for (const [dir, m] of bundle.modules) {
     const files = Object.create(null)
     for (const rel of Object.keys(m.files)) files[rel] = integrities.get(moduleFileKey(dir, rel))
-    lockModules.set(dir, { name: m.name, version: m.version, ...(m.ecosystem === undefined ? {} : { ecosystem: m.ecosystem }), files })
+    lockModules.set(dir, moduleInfo({ ...m, files }))
   }
   const lockfile = new Lockfile({
     config: bundle.config,
@@ -1069,7 +1123,7 @@ function classifyEntries(name, { cwd = process.cwd(), entries, mappingFile, mani
   else if (entries.every((e) => BASH_EXTS.has(extname(e)))) kind = 'bash'
   else if (entries.every((e) => RUST_EXTS.has(extname(e)))) kind = 'rust'
   else {
-    throw new Error(`${name}: entries must all be .sol, all be .php, all be .js/.cjs/.mjs/.ts/.cts/.mts, all be .sh/.bash, or all be .rs (no mixing)`)
+    throw new Error(`${name}: entries must all be .sol, all be .php, all be .js/.cjs/.mjs/.ts/.cts/.mts/.jsx/.tsx, all be .sh/.bash, or all be .rs (no mixing)`)
   }
   if (mappingFile && kind !== 'sol') {
     throw new Error(`${name}: --mapping is only valid for .sol bundles`)
@@ -1117,7 +1171,8 @@ function classifyEntries(name, { cwd = process.cwd(), entries, mappingFile, mani
   if (mainFields !== undefined && kind !== 'js') {
     throw new Error(`${name}: --mainFields is only valid for JS bundles`)
   }
-  // --jsx toggles the scanner's JSX parsing for the .js family; only JS entries are scanned.
+  // --jsx toggles the scanner's JSX parsing for the .js family (.jsx/.tsx need no flag); only JS
+  // entries are scanned.
   if (jsx && kind !== 'js') {
     throw new Error(`${name}: --jsx is only valid for JS bundles`)
   }
@@ -1168,15 +1223,17 @@ function classifyEntries(name, { cwd = process.cwd(), entries, mappingFile, mani
 
 // A JS bundle as `stasis bundle` builds it: by the legacy-field resolver with `mainFields` or
 // `metro`, whose per-platform edges and synthetic empty module a State can't hold, else through a
-// State, which detects the bundle's repo itself. -> { bundle, lockfile: () => Lockfile, stateBuilt }
-async function buildJs({ mainFields, platforms, metro, metroResolver, ...options }) {
+// State, which detects the bundle's repo itself. `root` is the directory the bundle's paths are
+// relative to: cwd for the resolver's, the State's root for the State's.
+// -> { bundle, lockfile: () => Lockfile, stateBuilt, root }
+async function buildJs({ mainFields, platforms, metro, metroResolver, innermostRoot, ...options }) {
   if (metro || mainFields !== undefined) {
     const built = await buildResolvedJsBundle({ ...options, mainFields: metro ? METRO_MAIN_FIELDS : mainFields, platforms: metro ? platforms : [null], metro: Boolean(metro), metroResolver: Boolean(metroResolver) })
-    return { bundle: built.bundle, lockfile: () => built.lockfile, stateBuilt: false }
+    return { bundle: built.bundle, lockfile: () => built.lockfile, stateBuilt: false, root: resolve(options.cwd) }
   }
-  const state = await buildJsBundle(options)
+  const state = await buildJsBundle({ ...options, innermostRoot })
   // Stamp the `bundle` consumer (the static build carries none).
-  return { bundle: state.sourceBundle.withReason('bundle'), lockfile: () => state.lockfile, stateBuilt: true }
+  return { bundle: state.sourceBundle.withReason('bundle'), lockfile: () => state.lockfile, stateBuilt: true, root: state.root }
 }
 
 // The bundle of `kind` (classifyEntries') built from buildBundle's options.
@@ -1190,11 +1247,15 @@ async function buildOfKind(kind, { cwd, env, entries, mappingFile, manifests, sc
 }
 
 // buildVfsBundle's checks of `options`, which hold before anything is fetched (`host` the
-// project's, or an empty tree's with `fetched: false`): no metro-resolver, which reads the disk.
+// project's, or an empty tree's with `fetched: false`): no metro-resolver, which reads the disk;
+// `generate` only for JS.
 // -> the kind of bundle its entries make
 export function checkVfsOptions(name, options) {
   const kind = classifyEntries(name, options)
   if (options.metroResolver) throw new Error(`${name}: metroResolver is not supported`)
+  const { generate = [] } = options
+  if (!Array.isArray(generate) || generate.some((step) => step !== 'prisma')) throw new TypeError(`${name}: generate must be an array of 'prisma'`)
+  if (generate.length > 0 && kind !== 'js') throw new Error(`${name}: --generate is only valid for JS bundles`)
   return kind
 }
 
@@ -1203,13 +1264,19 @@ export function checkVfsOptions(name, options) {
 // would install, or its Solidity options, through the dependencies folder 'soldeer' would install; with
 // nothing read from disk but tarballs and zips, nor from the environment: a Solidity bundle is
 // built with foundry.toml's default profile, whatever FOUNDRY_PROFILE or remappings one sets, and no
-// EXODUS_STASIS_* setting is read. `repo`, the informational `{ github, directory | root, commit }`,
+// EXODUS_STASIS_* setting is read. `repo`, the informational `{ github, directory, commit }`,
 // is the Bundle's, over what is detected in the Vfs as `stasis bundle` detects it on disk. `os`,
 // `cpu` and `libc` are loadNodeModules'. Without a `packageManager`, it is the one whose lockfile
-// installs cwd, where only one's does.
-// -> { bundle: Bundle, lockfile: Lockfile (of a JS bundle), stats, packageManager }
-export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageManagerVersion, os, cpu, libc, repo, ...options } = {}) {
-  const { checkKind, checkTarget, checkVfs, loadTree, packageManagerFor, packageManagerOf, vfsHost } = await import('../vfs-bundle/tree.js')
+// installs cwd, where only one's does. `innermostRoot` is buildJsBundle's, for a JS bundle built
+// through a State. `generate: ['prisma']` writes each project's Prisma Client into the laid-out
+// 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.
+// -> { 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')
   checkVfs('buildVfsBundle', vfs)
   checkTarget('buildVfsBundle', { os, cpu, libc })
   // Checked as the Bundle checks it, before anything is fetched.
@@ -1219,7 +1286,7 @@ export async function buildVfsBundle({ vfs, packageManager, cwd = '/', packageMa
   cwd = project.realpath(posix.resolve('/', cwd))
   packageManager = packageManagerFor('buildVfsBundle', project, cwd, { packageManager, packageManagerVersion, os })
   const pm = packageManagerOf('buildVfsBundle', packageManager)
-  checkKind('buildVfsBundle', checkVfsOptions('buildVfsBundle', { ...options, cwd, host: project }), [packageManager])
+  checkKind('buildVfsBundle', checkVfsOptions('buildVfsBundle', { ...options, generate, cwd, host: project }), [packageManager])
   // Checked before anything is fetched: an entry out of what the tree installs is in the project
   // already. (A Solidity entry that is no .sol file is a directory, skipped where it is missing.)
   for (const entry of options.entries) {
@@ -1227,13 +1294,19 @@ 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 { host, stats } = await loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc })
+  const tree = await loadTree({ project, packageManager, cwd, packageManagerVersion, os, cpu, libc, client })
+  let { host } = tree
+  if (generate.includes('prisma')) {
+    const { generatePrismaClients, withPrismaClients } = await import('../vfs-bundle/prisma.js')
+    const outputs = await generatePrismaClients({ host, root: tree.root, projects: tree.projects })
+    if (outputs.length > 0) host = treeHost(tree, vfsHost(withPrismaClients(vfs, outputs)))
+  }
   const args = { ...options, cwd, host, env: {} }
-  const { bundle, lockfile, stateBuilt } = pm.kind === 'sol' ? { bundle: await buildSolidityBundle(args) } : await buildJs(args)
+  const { bundle, lockfile, stateBuilt, root } = pm.kind === 'sol' ? { bundle: await buildSolidityBundle(args), root: cwd } : await buildJs({ ...args, innermostRoot })
   if (repo !== undefined) bundle.repo = repo
   // Rooted at cwd, where `stasis bundle` detects its repo.
   else if (!stateBuilt) bundle.repo ??= detectRepo(cwd, host)
-  return { bundle, lockfile: lockfile?.(), stats, packageManager }
+  return { bundle, lockfile: lockfile?.(), stats: tree.stats, packageManager, root }
 }
 
 // Programmatic equivalent of `stasis bundle`: build and return an in-memory Bundle without
@@ -1255,14 +1328,20 @@ export async function bundleCommand({ cwd = process.cwd(), env = process.env, en
   const options = { cwd, env, entries, mappingFile, manifests, scope, conditions, mainFields, platforms, metro, metroResolver, jsx, flow, typescript, tsconfig, resources, packageJSON, cargo, cargoFeatures, cargoNoDefaultFeatures, cargoAllFeatures, cargoTarget, cargoManifests }
   const kind = classifyEntries('bundleCommand', { ...options, lockfile })
 
-  const target = output ?? DEFAULT_BUNDLE_FILE
   // --add has nothing to merge into on stdout (write-only).
-  if (add && target === '-') {
+  if (add && output === '-') {
     throw new Error('bundleCommand: --add cannot be combined with --output=- (nothing to merge into on stdout)')
   }
 
   const built = await buildOfKind(kind, options)
   let { bundle } = built
+  // The directory the bundle's paths are relative to: a State-built JS bundle's root, which is the
+  // project's at or above cwd (a workspace package's is the workspace root's), else cwd.
+  const root = built.root ?? resolve(cwd)
+  // By default the bundle goes there, where `stasis run --bundle=load` discovers it. In cwd below
+  // the root it would load as rooted at cwd, and root the next `stasis bundle` there too, out of the
+  // files above it.
+  const target = output ?? relative(resolve(cwd), join(root, DEFAULT_BUNDLE_FILE))
   // Only a JS bundle has a lockfile (classifyEntries refuses one for the others).
   let lockData = lockfile ? built.lockfile().serialize() : undefined
 
@@ -1306,7 +1385,8 @@ export async function bundleCommand({ cwd = process.cwd(), env = process.env, en
 
   const dest = writeBundle(cwd, target, serialized, brotliQuality)
   if (lockData) writeFile(lockAbs, lockData)
-  const fromDir = outermostDir(files, resolve(cwd))
+  // The bundle's paths are relative to its root; shown relative to cwd, as `dest` is.
+  const fromDir = posix.join(toPosix(relative(resolve(cwd), root)), outermostDir(files, root))
   // On a merge, report newly-added files alongside the totals; a fresh write keeps the plain line.
   if (mergedFrom !== undefined) {
     const added = files.length - mergedFrom

package/src/diff.js

@@ -1,4 +1,4 @@
-import { sortPaths } from '@exodus/stasis-core/util'
+import { reposAgree, sortPaths } from '@exodus/stasis-core/util'
 
 // `@exodus/stasis/diff` — compare two parsed stasis artifacts (Bundle/Lockfile) at the module and
 // file level. Never reads disk. Comparing across kinds works by reducing every file to the same
@@ -21,7 +21,7 @@ function digestOf(kind, format, value, hash) {
 
 const projectPath = (dir, rel) => (dir === '.' ? rel : `${dir}/${rel}`)
 
-// Project an artifact onto a uniform shape: scope + Map<dir, { name, version, ecosystem,
+// Project an artifact onto a uniform shape: scope + Map<dir, { name, version, ecosystem, repo,
 // files: Map<rel, digest> }>. `input` is { artifact, kind }; `hash` re-hashes bundle bytes only.
 export function normalizeArtifact(input, { hash } = {}) {
   const { artifact, kind } = input ?? {}
@@ -30,13 +30,13 @@ export function normalizeArtifact(input, { hash } = {}) {
   }
   const formats = artifact.formats ?? new Map()
   const modules = new Map()
-  for (const [dir, { name, version, ecosystem, files }] of artifact.modules) {
+  for (const [dir, { name, version, ecosystem, repo, files }] of artifact.modules) {
     const digests = new Map()
     for (const [rel, value] of Object.entries(files)) {
       digests.set(rel, digestOf(kind, formats.get(projectPath(dir, rel)), value, hash))
     }
     // v0 bundles record no name/version; normalize undefined -> null for a single "unknown" sentinel.
-    modules.set(dir, { name: name ?? null, version: version ?? null, ecosystem: ecosystem ?? null, files: digests })
+    modules.set(dir, { name: name ?? null, version: version ?? null, ecosystem: ecosystem ?? null, repo, files: digests })
   }
   // `executable` decides which files `stasis extract` chmods +x, so a change to it changes the tree
   // an artifact produces even when every digest matches -- it has to be part of "did these differ?".
@@ -45,8 +45,8 @@ export function normalizeArtifact(input, { hash } = {}) {
 
 // Diff two `{ artifact, kind }` operands (`left` = baseline/"from", `right` = "to"). Modules are
 // compared whole-package; files only within packages present on BOTH sides (a one-sided package is
-// reported once as an added/removed module, not per-file). A version/name change is reported only
-// when both sides record a non-null value. `{ imports: true }` also diffs the resolution graphs
+// reported once as an added/removed module, not per-file). A version/name/repo change is reported
+// only when both sides record a non-null value (an artifact from before `repo` records none). `{ imports: true }` also diffs the resolution graphs
 // (opt-in; verbose). `hash` is required only when a bundle is an operand.
 export function diffArtifacts(left, right, { imports = false, hash } = {}) {
   const L = normalizeArtifact(left, { hash })
@@ -80,7 +80,11 @@ export function diffArtifacts(left, right, { imports = false, hash } = {}) {
     if (l.name !== null && r.name !== null && l.name !== r.name) {
       change.nameChange = { from: l.name, to: r.name }
     }
-    if (change.versionChange || change.nameChange) modulesChanged.push(change)
+    // A dependency's repo picks the GitHub advisories audit asks, so a change to it is one to review.
+    if (!reposAgree(l.repo, r.repo)) {
+      change.repoChange = { from: l.repo, to: r.repo }
+    }
+    if (change.versionChange || change.nameChange || change.repoChange) modulesChanged.push(change)
 
     const rels = new Set([...l.files.keys(), ...r.files.keys()])
     for (const rel of rels) {
@@ -203,10 +207,14 @@ const REMOVED = '-'
 const ADDED = '+'
 const CHANGED = '*'
 
-function describeModuleChange({ name, versionChange, nameChange }) {
+// `owner/name`, its commit and directory where recorded: `owner/name@0123abc (packages/x)`.
+const repoLabel = ({ github, commit, directory }) => `${github ?? '?'}${commit ? `@${commit.slice(0, 7)}` : ''}${directory ? ` (${directory})` : ''}`
+
+function describeModuleChange({ name, versionChange, nameChange, repoChange }) {
   const segs = []
   if (versionChange) segs.push(`${versionChange.from} -> ${versionChange.to}`)
   if (nameChange) segs.push(`name ${nameChange.from} -> ${nameChange.to}`)
+  if (repoChange) segs.push(`repo ${repoLabel(repoChange.from)} -> ${repoLabel(repoChange.to)}`)
   return `${name ? `${name} ` : ''}${segs.join(', ')}`
 }
 

package/src/loaders/cargo.js

@@ -782,6 +782,12 @@ export function createCargoContext(baseDir, { entries = [], features = [], noDef
     // sha256, as `cargo vendor` listed them, path relative to the package.
     return value === null ? null : { text, git: (value?.package ?? null) === null, files: isPlainObject(value?.files) ? value.files : {} }
   })
+  // Where `cargo vendor` copied the vendored package at `dir` from, as its `.cargo-checksum.json`
+  // tells: `registry` or `git` (a git checkout); null without that file, when it could be either.
+  const copySource = (dir) => {
+    const git = checksumOf(dir)?.git
+    return git === undefined ? null : (git ? 'git' : 'registry')
+  }
   // Throws when `fileRel`, a file of the vendored package at `dir`, isn't byte for byte (`buf`) the
   // file its `.cargo-checksum.json` lists -- edited after `cargo vendor`: cargo refuses to build
   // the package, and so the bundle does. A file the list doesn't name, or a package without one,
@@ -900,8 +906,7 @@ export function createCargoContext(baseDir, { entries = [], features = [], noDef
   const lockKeysOf = (lk, m) => {
     const keys = lk.byId.get(`${normName(m.package.name)} ${version(m)}`) ?? []
     if (!isVendoredDir(m.dir)) return keys.filter((k) => lk.lock.packages[k].source === undefined)
-    const git = checksumOf(m.dir)?.git
-    const kind = git === undefined ? null : (git ? 'git' : 'registry')
+    const kind = copySource(m.dir)
     return keys.filter((k) => lk.lock.packages[k].source !== undefined && (kind === null || sourceKind(lk.lock.packages[k].source) === kind))
   }
   // Dependency → package, memoized per (package, request): the fixed-point loop asks many times.
@@ -997,16 +1002,20 @@ export function createCargoContext(baseDir, { entries = [], features = [], noDef
 
   // --- feature resolution
 
-  // Cargo's feature resolver: v2 (edition 2021+, or `resolver = "2"`/`"3"`) leaves dev-dependencies
-  // out of a normal build's unification, resolves what is built for the host apart from what is
-  // built for the target, and ignores the tables of platforms not being built; v1 unifies them all.
-  // It is the workspace's setting: the build's workspace root's (buildWorkspaceRoot) `resolver`,
-  // else its edition -- never that of a vendored crate an entry is in, where cargo isn't run.
+  // Cargo's feature resolver: v2 (edition 2021, or `resolver = "2"`) leaves dev-dependencies out of
+  // a normal build's unification, resolves what is built for the host apart from what is built for
+  // the target, and ignores the tables of platforms not being built; v1 unifies them all. v3
+  // (edition 2024, or `resolver = "3"`) resolves features as v2 does, and picks versions by
+  // `rust-version` too, which the lockfile and the vendored copies have decided here. It is the
+  // workspace's setting: the build's workspace root's (buildWorkspaceRoot) `resolver`, else its
+  // edition's, as linkCargo gives it -- never that of a vendored crate an entry is in, where cargo
+  // isn't run.
   let resolverMemo = null
   const resolverVersion = () => {
     if (resolverMemo === null) {
       const root = buildWorkspaceRoot()
-      resolverMemo = root?.resolver ?? (Number(root?.package?.edition ?? 0) >= 2021 ? 2 : 1)
+      const edition = Number(root?.package?.edition ?? 0)
+      resolverMemo = root?.resolver ?? (edition >= 2024 ? 3 : (edition >= 2021 ? 2 : 1))
     }
     return resolverMemo
   }
@@ -1613,11 +1622,19 @@ export function createCargoContext(baseDir, { entries = [], features = [], noDef
       const m = packageFor(fileRel)
       if (m !== null && isVendoredDir(m.dir)) checkVendored(m.dir, fileRel, buf)
     },
-    // Whether `fileRel` belongs to a vendored package (a registry crate `cargo vendor` copied in).
+    // Whether `fileRel` belongs to a vendored package (a crate `cargo vendor` copied in, a registry's
+    // or a git checkout's: see vendoredFrom).
     isVendored(fileRel) {
       const m = packageFor(fileRel)
       return m !== null && isVendoredDir(m.dir)
     },
+    // Where `cargo vendor` copied the vendored package owning `fileRel` from, as its
+    // `.cargo-checksum.json` tells: `registry` (a package checksum) or `git` (a git checkout's: none);
+    // null when it has no such file, and so could be either, or isn't vendored.
+    vendoredFrom(fileRel) {
+      const m = packageFor(fileRel)
+      return m !== null && isVendoredDir(m.dir) ? copySource(m.dir) : null
+    },
     // The build script of `fileRel`'s package, project-relative, when there is one on disk:
     // `[package] build = "…"`, else `build.rs` beside the manifest; `build = false` means none. A
     // vendored package's may not name a file outside the package (a published crate never does).