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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
@@ -25,12 +25,13 @@
     "src/apis/npm/index.js",
     "src/apis/npm/semver.cjs",
     "src/audit.js",
+    "src/babel.js",
+    "src/babel-worker.cjs",
     "src/bundle.js",
     "src/bundle-from-lockfile.js",
     "src/cmd/bundle.js",
     "src/cmd/build.js",
     "src/cmd/diff.js",
-    "src/cmd/extract.js",
     "src/cmd/sbom.js",
     "src/diff.js",
     "src/esbuild.js",
@@ -42,6 +43,7 @@
     "src/loaders/php.js",
     "src/lockfile.js",
     "src/metro.js",
+    "src/metro-resolver.js",
     "src/metro-transformer.js",
     "src/mock.js",
     "src/parse.js",
@@ -68,16 +70,20 @@
   },
   "homepage": "https://github.com/ExodusOSS/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.1",
-    "@exodus/stasis-plugins": "1.0.0-beta.1",
+    "@exodus/stasis-core": "1.0.0-beta.3",
+    "@exodus/stasis-plugins": "1.0.0-beta.3",
     "oxc-parser": "^0.94.0"
   },
   "peerDependencies": {
-    "esbuild": "*"
+    "esbuild": "*",
+    "flow-remove-types": "*"
   },
   "peerDependenciesMeta": {
     "esbuild": {
       "optional": true
+    },
+    "flow-remove-types": {
+      "optional": true
     }
   }
 }

package/src/apis/npm/semver.cjs

@@ -10,11 +10,9 @@ const argv0 = process.argv[0] // not process.argv0 which lacks path
 function getSemver() {
   if (semver) return semver
 
-  // Coherence check that we got Node.js path there
   assert(['node', 'node.exe'].includes(basename(argv0)))
   assert.equal(basename(argv0), basename(process.argv0))
 
-  // Load semver from npm bundled with Node.js
   const semverDir = resolve(dirname(argv0), '../lib/node_modules/npm/node_modules/semver')
   semver = require(semverDir)
   return semver

package/src/audit.js

@@ -1,15 +1,30 @@
+import { moduleFileKey } from '@exodus/stasis-core/util'
 import { advisories } from './apis/npm/index.js'
+import { isEvidenceFile } from './audit-corrections.js'
 import semver from './apis/npm/semver.cjs'
 import { parseFile } from './parse.js'
+import { collectWhy } from './why.js'
 
-// Only audit installed dependencies; workspace/first-party packages live under
-// non-`node_modules` keys in .modules (Lockfile/Bundle merge sources in) and
-// shouldn't be sent to the public registry — they leak names and produce noise.
+// Only audit installed dependencies; first-party packages live under non-`node_modules` keys and
+// must not be sent to the public registry (leaks names, adds noise).
+//
+// A package counts as present only when its REAL code is, and recorded = present:
+// an artifact records exactly the files it ships or attested -- imported, entry,
+// or `add`-ed (the last two have no in-edge in the resolution graph, so presence
+// must NOT be derived from edges). The package is audited only if some recorded
+// file is code evidence (see audit-corrections.js) -- not a corrected file (ws's
+// noop browser.js stub), not a package.json manifest (recorded for resolver /
+// metadata reads). So a ws shipped only as browser.js (+ manifest) is skipped,
+// while one whose real code was bundled stays. Which consumers and import EDGES
+// reach that code is the reason column's concern -- collectReasons and why.js
+// apply the same evidence rule per file/edge there.
 export function collectPackagesFromFile(file) {
   const out = []
-  for (const [dir, { name, version }] of parseFile(file).modules) {
+  for (const [dir, { name, version, files }] of parseFile(file).modules) {
     if (!dir.includes('node_modules')) continue
-    if (name && version) out.push({ name, version })
+    if (!name || !version) continue
+    if (!Object.keys(files).some((rel) => isEvidenceFile(name, version, rel))) continue
+    out.push({ name, version })
   }
   return out
 }
@@ -28,9 +43,80 @@ export function collectPackages(files) {
   return out.toSorted((a, b) => a.name.localeCompare(b.name) || semver.compare(a.version, b.version))
 }
 
+// Map each audited node_modules package (`name@version`) to the bundle consumers ("reasons") that
+// recorded its files. Only bundles carry a reason map ({ consumer: [file, ...] }); lockfiles omit
+// it. Each file is resolved back to its owning package via the module file listing. Only evidence
+// files attribute (see audit-corrections.js): a consumer that recorded nothing of a package but a
+// corrected file or its package.json manifest carries none of its real code and is NOT a reason --
+// e.g. webpack shipping only ws's noop browser.js stub, while `run` bundles the real ws.
+export function collectReasons(files) {
+  const byPkg = new Map()
+  for (const file of files) {
+    const artifact = parseFile(file)
+    const reason = artifact.reason
+    if (!reason) continue
+    const fileToPkg = new Map()
+    for (const [dir, { name, version, files: modFiles }] of artifact.modules) {
+      if (!dir.includes('node_modules') || !name || !version) continue
+      for (const rel of Object.keys(modFiles)) {
+        if (!isEvidenceFile(name, version, rel)) continue
+        fileToPkg.set(moduleFileKey(dir, rel), `${name}@${version}`)
+      }
+    }
+    for (const [consumer, list] of Object.entries(reason)) {
+      if (!Array.isArray(list)) continue
+      for (const f of list) {
+        const key = fileToPkg.get(f)
+        if (key === undefined) continue
+        let set = byPkg.get(key)
+        if (set === undefined) byPkg.set(key, (set = new Set()))
+        set.add(consumer)
+      }
+    }
+  }
+  return byPkg
+}
+
 const SEVERITY_ORDER = { critical: 0, high: 1, moderate: 2, low: 3, info: 4, none: 5 }
 
-export function flattenAdvisories(result, packages = []) {
+// Consumer display order: bundler plugins (metro, webpack, esbuild, ...) first,
+// then `run`, then `add`. Ties broken alphabetically.
+const CONSUMER_RANK = { run: 1, add: 2 }
+const consumerRank = (c) => CONSUMER_RANK[c] ?? 0
+const byConsumerOrder = (a, b) => consumerRank(a) - consumerRank(b) || a.localeCompare(b)
+
+// Build a row's `reason` cell by unioning over exactly the affected versions it
+// covers. Without `--why` that's the `, `-joined set of bundle consumers; with
+// `--why` it's the newline-joined `consumer: a -> b -> c` import-path lines
+// (which REPLACE the consumer list). Consumers are ordered plugins -> run -> add.
+// `reasonFilter`, when set, narrows the cell to a single consumer: the `--why`
+// chains are already filtered upstream (see collectWhy), so only the consumer
+// list needs pruning here.
+function reasonCell(pkg, affected, reasonsByPkg, whyByPkg, reasonFilter) {
+  const parts = new Set()
+  const source = whyByPkg ?? reasonsByPkg
+  for (const v of affected) {
+    for (const p of source.get(`${pkg}@${v}`) ?? []) parts.add(p)
+  }
+  // --why: group `consumer: path` lines by consumer and order the groups
+  // plugins -> run -> add (this also re-unites a consumer's lines when they were
+  // split across affected versions); within a group collectWhy's compressed order
+  // is preserved. Otherwise: the `, `-joined consumer set in the same order.
+  if (whyByPkg) {
+    const byConsumer = new Map()
+    for (const line of parts) {
+      const i = line.indexOf(': ')
+      const consumer = i === -1 ? '' : line.slice(0, i)
+      if (!byConsumer.has(consumer)) byConsumer.set(consumer, [])
+      byConsumer.get(consumer).push(line)
+    }
+    return [...byConsumer.keys()].toSorted(byConsumerOrder).flatMap((c) => byConsumer.get(c)).join('\n')
+  }
+  const consumers = reasonFilter ? [...parts].filter((c) => c === reasonFilter) : [...parts]
+  return consumers.toSorted(byConsumerOrder).join(', ')
+}
+
+export function flattenAdvisories(result, packages = [], reasonsByPkg = new Map(), whyByPkg = null, reasonFilter = null) {
   const installed = new Map()
   for (const { name, version } of packages) {
     if (!installed.has(name)) installed.set(name, [])
@@ -45,10 +131,13 @@ export function flattenAdvisories(result, packages = []) {
       const affected = range
         ? installedVersions.filter((v) => semver.satisfies(v, range))
         : installedVersions
-      // npm occasionally returns advisories whose vulnerable range matches none
-      // of the versions we submitted; drop them so the table (and the CLI exit
-      // code) reflect only real hits.
+      // npm sometimes returns advisories whose range matches none of the versions we submitted; drop
+      // them so the table and exit code reflect only real hits.
       if (installedVersions.length > 0 && affected.length === 0) continue
+      const reason = reasonCell(pkg, affected, reasonsByPkg, whyByPkg, reasonFilter)
+      // --reason keeps only advisories tied to that consumer: once the cell is
+      // narrowed to it, an empty cell means this package isn't related to it.
+      if (reasonFilter && reason === '') continue
       rows.push({
         package: pkg,
         installed: affected.join(', '),
@@ -56,6 +145,7 @@ export function flattenAdvisories(result, packages = []) {
         severity: adv.severity ?? '',
         title: adv.title ?? '',
         url: adv.url ?? '',
+        reason,
       })
     }
   }
@@ -69,36 +159,77 @@ export function flattenAdvisories(result, packages = []) {
   return rows
 }
 
-// Line breaks in npm advisory titles would otherwise break the box layout.
-// Covers LF, bare CR (and CRLF), and U+2028 / U+2029 line/paragraph separators.
+// Strip line breaks (LF/CR/CRLF, U+2028/U+2029) from advisory titles so they can't break the box layout.
 const cell = (v) => String(v ?? '').replace(/[\r\n\u2028\u2029]+/gu, ' ')
 
-export function formatTable(rows, columns) {
+// Split a value into the physical lines a cell occupies. Non-multiline columns
+// collapse every line break to a space via `cell` (one line). A column named in
+// `multiline` (the `--why` reason column) keeps intentional `\n` breaks -- one
+// physical line per entry -- while still flattening stray CR/separators in each.
+const cellLines = (v, multiline) =>
+  multiline ? String(v ?? '').split('\n').map((s) => cell(s)) : [cell(v)]
+
+export function formatTable(rows, columns, { multiline = [] } = {}) {
   if (rows.length === 0) return ''
-  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length)))
+  const ml = new Set(multiline)
+  const linesOf = (obj) => columns.map((c) => cellLines(obj[c], ml.has(c)))
+  const header = columns.map((c) => [c])
+  const body = rows.map((r) => linesOf(r))
+  const widths = columns.map((c, i) =>
+    Math.max(c.length, ...body.map((cells) => Math.max(0, ...cells[i].map((l) => l.length))))
+  )
   const pad = (s, w) => s.padEnd(w)
   const line = (l, m, r, fill) => l + widths.map((w) => fill.repeat(w + 2)).join(m) + r
-  const row = (vals) => '│ ' + vals.map((v, i) => pad(cell(v), widths[i])).join(' │ ') + ' │'
+  // A row spans as many physical lines as its tallest cell; shorter cells pad
+  // out with blanks so the borders stay aligned.
+  const render = (cells) => {
+    const height = Math.max(...cells.map((c) => c.length))
+    const out = []
+    for (let i = 0; i < height; i++) {
+      out.push('│ ' + cells.map((c, j) => pad(c[i] ?? '', widths[j])).join(' │ ') + ' │')
+    }
+    return out.join('\n')
+  }
   return [
     line('┌', '┬', '┐', '─'),
-    row(columns),
+    render(header),
     line('├', '┼', '┤', '─'),
-    ...rows.map((r) => row(columns.map((c) => r[c]))),
+    ...body.map(render),
     line('└', '┴', '┘', '─'),
   ].join('\n')
 }
 
-export async function audit(files) {
+export async function audit(files, { why = false, whyDeep = false, whyFull = false, reason = null } = {}) {
+  // --why-deep and --why-full imply --why. Deep keeps every chain instead of the
+  // default pruning of chains whose full suffix is already a chain (see
+  // collectWhy/dropSuffixed); full spells chains out with no `...` collapse.
+  why = why || whyDeep || whyFull
   const packages = collectPackages(files)
   if (packages.length === 0) {
-    return { packages, advisories: {}, rows: [] }
+    return { packages, advisories: {}, rows: [], why }
   }
   const result = await advisories(packages)
-  const rows = flattenAdvisories(result, packages)
-  return { packages, advisories: result, rows }
+  // `--why` REPLACES the consumer list with per-consumer import paths, so only
+  // one of the two is computed. Restrict the (potentially expensive) path search
+  // to the packages that actually carry an advisory. `reason` (--reason) narrows
+  // both the paths (in collectWhy) and the consumer list (in flattenAdvisories)
+  // to a single consumer, dropping advisories unrelated to it.
+  let rows
+  if (why) {
+    const vulnerable = new Set(
+      Object.entries(result).filter(([, v]) => Array.isArray(v) && v.length > 0).map(([name]) => name)
+    )
+    const targetKeys = new Set(
+      packages.filter((p) => vulnerable.has(p.name)).map((p) => `${p.name}@${p.version}`)
+    )
+    rows = flattenAdvisories(result, packages, undefined, collectWhy(files, targetKeys, reason, { deep: whyDeep, full: whyFull }), reason)
+  } else {
+    rows = flattenAdvisories(result, packages, collectReasons(files), null, reason)
+  }
+  return { packages, advisories: result, rows, why, whyDeep, whyFull, reason }
 }
 
-export function printAuditReport({ packages, rows }, { out = process.stdout, err = process.stderr } = {}) {
+export function printAuditReport({ packages, rows, why = false, reason = null }, { out = process.stdout, err = process.stderr } = {}) {
   err.write(`Scanned ${packages.length} package${packages.length === 1 ? '' : 's'}\n`)
   if (packages.length === 0) {
     err.write('No node_modules entries found in the input files\n')
@@ -108,5 +239,13 @@ export function printAuditReport({ packages, rows }, { out = process.stdout, err
     err.write('No advisories found\n')
     return
   }
-  out.write(formatTable(rows, ['severity', 'package', 'installed', 'vulnerable', 'title', 'url']) + '\n')
+  const columns = ['severity', 'package', 'installed', 'vulnerable', 'title', 'url']
+  // Surface the reason column only when some advisory has provenance -- bundle
+  // consumers, or (with --why) import paths. Under --reason WITHOUT --why every
+  // cell is just the filter value repeated, so drop the column then; --why still
+  // earns it (the import chains differ per row).
+  if (rows.some((r) => r.reason) && !(reason && !why)) columns.splice(3, 0, 'reason')
+  // Under --why the reason cell is a list of `consumer: path` lines; let it span
+  // multiple physical rows instead of collapsing to one.
+  out.write(formatTable(rows, columns, { multiline: why ? ['reason'] : [] }) + '\n')
 }

package/src/babel-worker.cjs

@@ -0,0 +1,65 @@
+'use strict'
+
+const { Worker, MessageChannel, isMainThread, parentPort, workerData } = require('node:worker_threads')
+const { once } = require('node:events')
+const { availableParallelism } = require('node:os')
+
+// Babel transforms are CPU-bound and `stasis build` fires many concurrently (esbuild loads
+// files in parallel), so they run on a small worker-thread pool off the main thread. Workers
+// are unref()ed: a pending transform keeps the process alive through its open MessagePort,
+// but an idle pool never holds the process open after the build finishes.
+//
+// Babel is the project's dependency, not stasis's, so each pool is keyed by the resolved
+// @babel/core entry path and the worker loads that exact copy (passed via workerData).
+if (isMainThread) {
+  const maxWorkers = availableParallelism() >= 4 ? 2 : 1
+  const pools = new Map() // resolved @babel/core path -> [{ worker, busy }]
+
+  const getWorker = (babelPath) => {
+    if (!pools.has(babelPath)) pools.set(babelPath, [])
+    const workers = pools.get(babelPath)
+
+    const idle = workers.find((info) => info.busy === 0)
+    if (idle) return idle
+
+    if (workers.length < maxWorkers) {
+      const worker = new Worker(__filename, { workerData: { babelPath } })
+      worker.unref()
+      // unhandled top-level errors crash the process automatically, which is the desired
+      // behavior -- no need to listen to 'error'
+      workers.unshift({ worker, busy: 0 })
+    } else if (workers.length > 1) {
+      workers.sort((a, b) => a.busy - b.busy)
+    }
+
+    return workers[0]
+  }
+
+  const transformAsync = async (babelPath, code, options) => {
+    const info = getWorker(babelPath)
+    info.busy++
+    const channel = new MessageChannel()
+    info.worker.postMessage({ port: channel.port1, code, options }, [channel.port1])
+    const [{ result, error }] = await once(channel.port2, 'message')
+    info.busy--
+    if (error) throw error
+    return result
+  }
+
+  module.exports = { transformAsync }
+} else {
+  const babel = require(workerData.babelPath)
+
+  parentPort.on('message', ({ port, code: input, options }) => {
+    try {
+      // transformSync: the worker is already off the main thread, async only adds overhead
+      const { code, map } = babel.transformSync(input, options)
+      // only plain data crosses the port -- a full Babel result carries non-cloneable state
+      port.postMessage({ result: { code, map } })
+    } catch (error) {
+      port.postMessage({ error })
+    }
+
+    port.close()
+  })
+}

package/src/babel.js

@@ -0,0 +1,131 @@
+// Per-file Babel pre-transforms for `stasis build`, serving two flags:
+//
+// --platform=hermes downlevels every code file to the dialect Hermes (React Native's
+// engine) executes -- no classes, class fields, let/const, arrows, async generators or
+// for-await. Two steps per file, then a constrained final bundle:
+//   1. esbuild.transform lowers class fields / private members / static blocks / `using`
+//      into plain class syntax (stripping TS types and compiling JSX on the way), the
+//      shape Babel's class transform can consume.
+//   2. A Babel worker pool applies transform-block-scoping + transform-classes -- the two
+//      lowerings esbuild refuses to do itself.
+//   3. The final esbuild bundle runs with HERMES_UNSUPPORTED (arrow/async-generator/
+//      for-await lowered by esbuild; class and const-and-let declared unsupported both so
+//      esbuild's own helpers stay Hermes-safe and as a fail-closed check that none
+//      survived Babel).
+//
+// --babel instead runs each code file through the project's own babel.config.* verbatim --
+// no esbuild pre-transform, Babel sees the original source exactly as the project's own
+// toolchain (e.g. Metro) would hand it over.
+//
+// Babel is the PROJECT's dev dependency, not stasis's: @babel/core (and, for hermes, the
+// two transform plugins) resolve from the project directory, so the project pins its own
+// Babel toolchain and config semantics.
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+// esbuild `supported` map for the FINAL hermes bundle (spread into esbuild.build options).
+export const HERMES_UNSUPPORTED = {
+  arrow: false,
+  class: false, // already lowered by Babel; unsupporting it doubles as a safeguard check
+  'async-generator': false,
+  'const-and-let': false, // ditto, and keeps esbuild-emitted helpers off let/const
+  'for-await': false,
+}
+
+// Class-syntax extensions the hermes pre-transform lowers into plain classes for Babel,
+// which handles none of them without extra plugins (and Hermes supports none of them either).
+const PRE_TRANSFORM_UNSUPPORTED = {
+  'class-field': false,
+  'class-private-accessor': false,
+  'class-private-brand-check': false,
+  'class-private-field': false,
+  'class-private-method': false,
+  'class-private-static-accessor': false,
+  'class-private-static-field': false,
+  'class-private-static-method': false,
+  'class-static-blocks': false,
+  'class-static-field': false,
+  'import-attributes': false,
+  using: false,
+}
+
+const HERMES_BABEL_PLUGINS = ['@babel/plugin-transform-block-scoping', '@babel/plugin-transform-classes']
+
+// Only real JS-family sources are transformed; anything else the plugin serves (json, or a
+// --loader override like .svg:text) passes through untouched.
+const TRANSFORMABLE_LOADERS = new Set(['js', 'ts', 'jsx', 'tsx'])
+
+// Resolved up front on the main thread so a missing install fails with instructions, not a
+// worker crash mid-build. Returns absolute paths: the worker loads @babel/core by path, and
+// plugin paths bypass Babel's own name resolution (which would look in the wrong dir).
+function resolveFromProject(projectDir, deps, flag) {
+  const projectRequire = createRequire(join(projectDir, 'noop.js'))
+  try {
+    return deps.map((dep) => projectRequire.resolve(dep))
+  } catch (cause) {
+    throw new Error(
+      `stasis build: ${flag} needs ${deps.join(', ')} installed in the project ` +
+      `(e.g. \`npm i -D ${deps.join(' ')}\`); resolution failed from ${projectDir}`,
+      { cause }
+    )
+  }
+}
+
+// The hermes per-file pre-transform, in StasisEsbuild's load-mode `transform` hook shape:
+// (source, { path, loader }) => { contents, loader } | undefined.
+export function createHermesTransform({ projectDir, esbuild }) {
+  const [babelPath, ...plugins] = resolveFromProject(
+    projectDir, ['@babel/core', ...HERMES_BABEL_PLUGINS], '--platform=hermes'
+  )
+  const { transformAsync } = require('./babel-worker.cjs')
+  return async (source, { path, loader }) => {
+    if (!TRANSFORMABLE_LOADERS.has(loader)) return undefined
+    const { code, warnings } = await esbuild.transform(source, {
+      sourcemap: 'inline',
+      sourcefile: path,
+      loader,
+      supported: PRE_TRANSFORM_UNSUPPORTED,
+    })
+    if (warnings.length > 0) {
+      const formatted = await esbuild.formatMessages(warnings, { kind: 'warning', color: false })
+      for (const line of formatted) process.stderr.write(line)
+    }
+    const result = await transformAsync(babelPath, code, {
+      compact: false,
+      babelrc: false,
+      configFile: false,
+      plugins,
+    })
+    // TS is stripped and JSX compiled by the pre-transform, so the result is always plain js.
+    return { contents: result.code, loader: 'js' }
+  }
+}
+
+// The --babel per-file transform (same hook shape): the project's own babel.config.* over
+// the original source. Its output must be esbuild-parseable js -- a config that leaves TS/JSX
+// in place fails the build in Babel or esbuild, which is the project's config to fix.
+export function createBabelConfigTransform({ projectDir }) {
+  const configFile = ['babel.config.js', 'babel.config.cjs', 'babel.config.mjs', 'babel.config.json']
+    .map((name) => join(projectDir, name))
+    .find((file) => existsSync(file))
+  if (!configFile) {
+    throw new Error(`stasis build: --babel found no babel.config.(js|cjs|mjs|json) in ${projectDir}`)
+  }
+  const [babelPath] = resolveFromProject(projectDir, ['@babel/core'], '--babel')
+  const { transformAsync } = require('./babel-worker.cjs')
+  return async (source, { path, loader }) => {
+    if (!TRANSFORMABLE_LOADERS.has(loader)) return undefined
+    // filename makes per-file config (overrides, .babelrc lookup) behave as in a real run.
+    const result = await transformAsync(babelPath, source, {
+      cwd: projectDir,
+      root: projectDir,
+      configFile,
+      filename: path,
+      compact: false,
+    })
+    return { contents: result.code, loader: 'js' }
+  }
+}

package/src/bundle-from-lockfile.js

@@ -4,17 +4,12 @@ import { resolve } from 'node:path'
 
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { sha512integrity } from '@exodus/stasis-core/state-util'
-import { moduleFileKey } from '@exodus/stasis-core/util'
+import { moduleFileKey, narrowExecutable } from '@exodus/stasis-core/util'
 
-// Reconstruct an in-memory Bundle from a lockfile by reading every file it attests
-// from disk and verifying each against the lockfile's SRI digest -- the exact inverse
-// of `extract`'s lockfileFromBundle. A changed or tampered file fails closed here (the
-// digest won't match), so building from a lockfile is as trustworthy as a
-// `stasis run --lock=frozen` replay: the build only ever sees bytes the lockfile
-// vouches for. `root` is the project root the lockfile's paths are relative to.
-//
-// Directory captures (`stasis run --fs` readdir listings, format 'directory') are
-// skipped: they key a listing at a directory's own path, not a file esbuild could load.
+// Reconstruct an in-memory Bundle from a lockfile, reading every attested file from disk and
+// verifying each against the lockfile's SRI digest -- fail closed on mismatch, so this is as
+// trustworthy as a `stasis run --lock=frozen` replay. `root` is what the lockfile's paths are
+// relative to. Directory captures (format 'directory') are skipped -- not files esbuild can load.
 export function bundleFromLockfile(lockfile, { root }) {
   if (!lockfile.imports) throw new Error('stasis: lockfile has no recorded import graph')
   const formats = lockfile.formats ?? new Map()
@@ -32,18 +27,14 @@ export function bundleFromLockfile(lockfile, { root }) {
       } catch (cause) {
         throw new Error(`stasis: file attested by the lockfile is missing on disk: ${file}`, { cause })
       }
-      // The lockfile digests raw on-disk bytes; verify against them before trusting
-      // the file. (Code and 'resource' files hash identically whether viewed as a
-      // string or bytes, since Node hashes a string as its UTF-8 bytes.)
+      // The lockfile digests raw on-disk bytes; verify before trusting the file.
       const actual = sha512integrity(bytes)
       if (actual !== integrity) {
         throw new Error(`stasis: ${file} does not match the lockfile (expected ${integrity}, got ${actual})`)
       }
-      // Store content the way a Bundle does: 'resource:base64' as base64 text,
-      // everything else (code, 'resource') as a raw UTF-8 string. A non-base64 entry is
-      // digested AND served as UTF-8 text, so a non-UTF-8 byte would transcode lossily
-      // (U+FFFD), diverging the served content from the verified bytes -- mirror the
-      // capture side's isUtf8 guard and fail closed instead.
+      // Store content as a Bundle does: 'resource:base64' as base64, everything else as a UTF-8 string.
+      // A non-UTF-8 byte in a non-base64 entry would transcode lossily (U+FFFD), diverging served
+      // content from the verified bytes -- mirror the capture side's isUtf8 guard and fail closed.
       if (format === 'resource:base64') {
         out[rel] = bytes.toString('base64')
       } else {
@@ -61,5 +52,8 @@ export function bundleFromLockfile(lockfile, { root }) {
     modules,
     imports: lockfile.imports,
     formats,
+    // Narrowed to the files this bundle ended up carrying (a skipped `directory` capture drops out),
+    // keeping Bundle.parse's rules true for a hand-built lockfile too.
+    executable: narrowExecutable(lockfile.executable, { modules, formats, scope: lockfile.config.scope }),
   })
 }