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

package/src/loaders/toml.js

@@ -0,0 +1,68 @@
+// TOML for the build descriptions the loaders take -- Cargo.toml, Cargo.lock, foundry.toml -- read
+// by @preventive/lockfile's strict TOML 1.0 parser into a tree of tables, and refused where it
+// isn't TOML, or isn't the TOML those files are written in: a bad escape, an unterminated string, a
+// key or table defined twice, a local date, U+FFFD where a lenient decoder replaced bytes ... each a
+// TomlError naming the file and line, never a guessed value.
+
+import { TomlError, parseToml } from '@preventive/lockfile/toml.js'
+
+export { TomlError }
+
+// --- Bracket helpers (for the Rust scanner) ----------------------------------------------
+
+// Index of the bracket closing the one opened at `open`, or the last index when unbalanced.
+export function matchClose(text, open) {
+  const close = { '[': ']', '(': ')', '{': '}' }[text[open]]
+  let depth = 0
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === text[open]) depth++
+    else if (text[i] === close && --depth === 0) return i
+  }
+  return text.length - 1
+}
+
+// Split on commas outside brackets/braces/parentheses/strings.
+export function splitTopLevel(text) {
+  const parts = []
+  let depth = 0
+  let start = 0
+  let inStr = false
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inStr) {
+      if (ch === '\\') i++
+      else if (ch === '"') inStr = false
+      continue
+    }
+    if (ch === '"') inStr = true
+    else if (ch === '(' || ch === '[' || ch === '{') depth++
+    else if (ch === ')' || ch === ']' || ch === '}') depth--
+    else if (ch === ',' && depth === 0) {
+      parts.push(text.slice(start, i))
+      start = i + 1
+    }
+  }
+  parts.push(text.slice(start))
+  return parts
+}
+
+// --- The reader -----------------------------------------------------------------------------
+
+// The table tree of TOML `text` (parseToml): tables are null-prototype objects, arrays arrays, and
+// values strings, booleans, numbers (an integer past 2^53 a BigInt), TomlFloat and TomlDateTime.
+// Throws a TomlError on anything else, naming `file` when given.
+export const readToml = (text, file = null) => nameErrors(file, () => parseToml(text))
+
+// `read()`, with an error of one of `classes` it throws (@preventive/lockfile's, whose message
+// leads with where it is) leading with `file` too, its fields kept; null `file` names none.
+export function nameErrors(file, read, classes = [TomlError]) {
+  try {
+    return read()
+  } catch (err) {
+    if (file === null || !classes.some((c) => err instanceof c)) throw err
+    throw Object.assign(new err.constructor(`${file}: ${err.message}`), err)
+  }
+}
+
+// Whether a TOML value is a table (a TomlFloat or TomlDateTime is an object too).
+export const isTomlTable = (value) => value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === null

package/src/metro-resolver.js

@@ -0,0 +1,150 @@
+import { createRequire, isBuiltin } from 'node:module'
+import { dirname, isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { diskHost } from '@exodus/stasis-core/host'
+import { isTypeDeclaration } from '@exodus/stasis-core/util'
+import { readJson } from './resolve-typescript.js'
+
+// Adapter that drives the PROJECT's own `metro-resolver` from stasis's static scanner, so
+// `stasis bundle --metro --metro-resolver` resolves modules EXACTLY the way that project's
+// installed Metro does -- rather than the hand-rolled Metro/RN approximation in
+// resolve-fields.js. `metro-resolver` is a leaf of the Metro toolchain (it takes a context of
+// filesystem callbacks and does no I/O of its own), so we load whichever copy the project
+// already ships and feed it a synchronous, disk-backed ResolutionContext.
+//
+// Returns, for each specifier, the same shape scan.js expects from a custom resolver:
+//   { url }      resolved to a real file (file: URL string)
+//   { empty }    a browser/react-native field mapped it to `false` (empty module)
+//   { builtin }  a Node builtin (Metro itself has none; we classify a bare-name miss)
+//   null         unresolved
+//
+// It is deliberately version-agnostic: it never imports metro-resolver internals (the
+// `./private/*` subpath), only the public `resolve`. `resolve` applies the browser-field
+// redirect via its own bundled helper, so the `redirectModulePath` we place on the context is
+// an inert placeholder that satisfies the type but is never consulted for base resolution.
+
+// 'f' | 'd' | null for a path, without throwing.
+function pathType(p) {
+  const s = diskHost.stat(p)
+  return s?.isFile() ? 'f' : s?.isDirectory() ? 'd' : null
+}
+
+// A `.d.ts` is types-only, erased at runtime, so the resolver must never land on one: report it as
+// non-existent to Metro's filesystem hooks and a package whose entry points at a declaration falls
+// through to its real `.js`. Only the RESOLUTION hooks use this -- getPackageForModule's own
+// dir-vs-file probe stays on raw pathType (it locates package scopes, never a module target).
+const resolvableType = (p) => (isTypeDeclaration(p) ? null : pathType(p))
+
+// Metro's `getPackageForModule`: the closest package scope for an absolute candidate path
+// (which need not exist). The candidate can be a package DIRECTORY (a bare import lands on
+// `<node_modules>/<pkg>`), so probing starts at the path itself, then walks up. `packageRelativePath`
+// is '' when the candidate IS the package root -- Metro's exports resolver maps '' to the '.' subpath,
+// and a stray '.' there would mismatch the exports key.
+function getPackageForModule(absModulePath) {
+  let dir = pathType(absModulePath) === 'd' ? absModulePath : dirname(absModulePath)
+  while (true) {
+    const pkg = readJson(join(dir, 'package.json'))
+    if (pkg) {
+      const rel = dir === absModulePath ? '' : absModulePath.slice(dir.length + 1)
+      return { rootPath: dir, packageJson: pkg, packageRelativePath: rel }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+// Build a resolver bound to a platform. `metro-resolver` is required from `projectDir` so we
+// honour the version the project's Metro uses; a missing package throws with actionable guidance.
+// `sourceExts` are the extensions Metro probes (kept to what a source bundle can carry, so the
+// resolver never lands on a file the bundle would reject). `mainFields` drives the browser-field
+// spec; `conditionNames` are the extra `exports`/`imports` conditions on top of the ones Metro
+// derives itself (default + require|import + platform).
+export function createMetroResolver({
+  projectDir,
+  platform,
+  sourceExts = ['js', 'json', 'ts'],
+  mainFields = ['react-native', 'browser', 'main'],
+  conditionNames = ['react-native'],
+  conditionsByPlatform = { web: ['browser'] },
+  enablePackageExports = true,
+  host = diskHost,
+} = {}) {
+  // It loads the project's metro-resolver, which reads the disk: never off it.
+  if (host !== diskHost) throw new Error('createMetroResolver: metro-resolver reads the disk, so it is not supported off disk')
+  const require = createRequire(join(projectDir, 'noop.js'))
+  let resolve
+  try {
+    ;({ resolve } = require('metro-resolver'))
+  } catch (cause) {
+    throw new Error(
+      `StasisMetroResolver: couldn't load 'metro-resolver' from ${projectDir}. --metro-resolver ` +
+      'resolves through the project\'s own Metro; install it (it ships with react-native/metro) ' +
+      'or drop --metro-resolver to use the built-in resolver.',
+      { cause }
+    )
+  }
+
+  // A React Native app has no Node builtins by default; Metro only prefers native suffixes off web.
+  const base = {
+    allowHaste: false,
+    assetExts: new Set(),
+    customResolverOptions: {},
+    disableHierarchicalLookup: false,
+    doesFileExist: (p) => resolvableType(p) === 'f',
+    extraNodeModules: null,
+    dev: false,
+    getPackage: (packageJsonPath) => readJson(packageJsonPath),
+    getPackageForModule,
+    fileSystemLookup: (p) => {
+      const abs = isAbsolute(p) ? p : join(projectDir, p)
+      const type = resolvableType(abs)
+      if (!type) return { exists: false }
+      let realPath = abs
+      try {
+        realPath = diskHost.realpath(abs)
+      } catch { /* keep the lexical path when realpath fails (e.g. a broken symlink) */ }
+      return { exists: true, type, realPath }
+    },
+    mainFields,
+    nodeModulesPaths: [],
+    preferNativePlatform: platform !== 'web',
+    resolveAsset: (dirPath, assetName, ext) => {
+      const f = join(dirPath, `${assetName}${ext}`)
+      return pathType(f) === 'f' ? [f] : null
+    },
+    resolveHasteModule: () => null,
+    resolveHastePackage: () => null,
+    // Inert placeholder: `resolve` redirects via its own bundled helper, never this (see header).
+    redirectModulePath: (modulePath) => modulePath,
+    sourceExts,
+    unstable_conditionNames: conditionNames,
+    unstable_conditionsByPlatform: conditionsByPlatform,
+    unstable_enablePackageExports: enablePackageExports,
+    unstable_incrementalResolution: false,
+    unstable_logWarning: () => {}, // a static build must not spam on exports fallbacks
+  }
+
+  return function resolveOne(parentFile, specifier, callConditions) {
+    // Metro splits `exports` on whether the edge was an ESM import vs a CJS require. scan.js hands
+    // us the parent's format-derived condition set, so 'import' membership is that signal.
+    const isESMImport = callConditions instanceof Set ? callConditions.has('import') : false
+    const context = { ...base, originModulePath: parentFile, isESMImport }
+    let res
+    try {
+      res = resolve(context, specifier, platform)
+    } catch {
+      // Metro carries no Node builtins: an unmapped builtin fails to resolve here. The browser-field
+      // remap of a builtin (`{"crypto": false}` / a shim) is handled inside resolve() before this.
+      if (isBuiltin(specifier)) return { builtin: true }
+      return null
+    }
+    if (!res) return null
+    if (res.type === 'empty') return { empty: true }
+    if (res.type === 'sourceFile') return { url: pathToFileURL(res.filePath).toString() }
+    // Assets are off (assetExts empty) for a code bundle, but map defensively to the first variant.
+    if (res.type === 'assetFiles' && res.filePaths?.length) return { url: pathToFileURL(res.filePaths[0]).toString() }
+    return null
+  }
+}

package/src/mock.js

@@ -1,52 +1,33 @@
-// Imported by src/loader-mock.js (the `stasis run --mock` entry) after the
-// @exodus/stasis-core hooks lib is evaluated but before its hooks are installed.
-// The goal is to capture the import graph for a bundle by actually running user
-// code, but with outbound side-effects denied. Pair with Node's `--permission`
-// flag (see bin/stasis.js when run with `--mock`), which fail-closed-denies fs
-// writes, child processes, worker threads, native addons, and the inspector at
-// the runtime boundary. This file covers what `--permission` cannot: there is no
-// `--allow-net`, so the network builtins are neutralized here in JS.
+// Imported by src/loader-mock.js (the `stasis run --mock` entry) after the core hooks lib is
+// evaluated but before its hooks are installed. Captures the import graph by running user code
+// with side-effects denied. Pairs with Node's `--permission` (see bin/stasis.js), which denies fs
+// writes/child procs/workers/addons/inspector at the runtime boundary; this file covers what
+// `--permission` can't -- there is no `--allow-net`, so the network builtins are neutralized in JS.
 //
-// Design: FAIL CLOSED, WHOLE MODULE.
-//  - We replace *every* callable on each network builtin with a thrower, not a
-//    curated method list. There is no "I forgot net.Socket#connect" gap: if
-//    it's a function on a denied module (factory, constructor, or helper),
-//    invoking it is denied. This also closes higher-level HTTP clients
-//    (axios/got/node-fetch/undici/ws) for free -- they all bottom out at
-//    node:net / node:tls / node:dns.
-//  - Anything we don't explicitly model still fails closed, because the call
-//    throws rather than silently succeeding.
+// FAIL CLOSED, WHOLE MODULE: replace *every* callable on a denied builtin with a thrower, not a
+// curated method list -- higher-level clients (axios/undici/ws) fall closed too since they bottom
+// out at node:net/tls/dns, and anything unmodelled still throws rather than silently succeeding.
 //
-// Mechanism: node:test's MockTracker can only redefine *configurable*
-// properties. ESM namespace objects (`import * as net from 'node:net'`) freeze
-// their bindings, so mocking the ESM namespace throws "Cannot redefine
-// property". The CommonJS exports object for the same builtin is mutable, and
-// ESM live-bindings track CJS mutation for builtins -- so we go through
-// `createRequire` to grab the mutable object and let live bindings propagate to
-// any importer that loads *after* us. Modules linked before this file runs keep
-// their original bindings -- which is exactly why the loader's own state.js
-// (node:fs/path/url/module/zlib/buffer, none of them network) keeps working.
+// Mechanism: go through `createRequire` to grab the *mutable* CJS exports object -- ESM namespace
+// objects freeze their bindings, so mocking them throws "Cannot redefine property". ESM live-bindings
+// track CJS mutation for builtins, so importers loading *after* us see the mocks; modules linked
+// before (the loader's own state.js) keep their real bindings.
 
 import { mock } from 'node:test'
 import { createRequire, syncBuiltinESMExports } from 'node:module'
 
 const require = createRequire(import.meta.url)
 
-// Force lazy initialization of process.stdin/stdout/stderr *before* we mock
-// the net/tls constructors. Node's process.std{in,out,err} are lazy getters
-// that construct an underlying net.Socket (or tty.WriteStream) on first read;
-// syncBuiltinESMExports() below would otherwise trigger those getters as it
-// materializes node:process's ESM wrapper, and the constructor would hit our
-// mock and throw mid-setup. Reading the property once here caches the real
-// Socket/TTY in Node's closure, so the later sync just reads the cached value.
+// Force lazy init of process.std{in,out,err} before mocking net/tls: they're lazy getters that
+// build a net.Socket/tty.WriteStream on first read, which syncBuiltinESMExports() below would
+// otherwise trigger through our mock mid-setup. Reading once here caches the real Socket/TTY.
 void process.stdin
 void process.stdout
 void process.stderr
 
 const MARKER = '[stasis --mock]'
 
-// Tagged so the unhandledRejection trap below can tell our denials apart from
-// genuine application bugs.
+// Tagged (__stasisMock) so the unhandledRejection trap below can tell our denials from real bugs.
 const blocked = (label) => {
   const err = new Error(`${MARKER} ${label} is blocked while capturing imports`)
   err.code = 'ERR_STASIS_MOCK_BLOCKED'
@@ -54,29 +35,18 @@ const blocked = (label) => {
   return err
 }
 
-// A *regular* (constructable) function, so that both `mod.factory()` and
-// `new mod.Constructor()` throw our attributable error -- an arrow function
-// would make `new` fail with a confusing "is not a constructor" TypeError.
+// A *regular* (constructable) function so both `mod.factory()` and `new mod.Constructor()` throw
+// our error; an arrow would make `new` fail with a confusing "is not a constructor".
 const denyFn = (label) => function () { throw blocked(label) }
 
-// Promise-shaped version: returns a rejected promise instead of sync-throwing.
-// Used for node:fs/promises, node:dns/promises, and similar. Fire-and-forget
-// `void fsPromises.writeFile(...)` then surfaces as an unhandledRejection
-// (caught by the trap below) rather than crashing the script synchronously.
+// Promise-shaped version: rejects instead of sync-throwing, so fire-and-forget callers surface via
+// the unhandledRejection trap below rather than crashing the script synchronously.
 const denyFnAsync = (label) => function () { return Promise.reject(blocked(label)) }
 
-// Replace every own function on `mod` (and, one level down, on `mod.promises`)
-// with a thrower. The factory picks denyFnAsync for promise-shaped surfaces
-// (/promises submodules) so fire-and-forget callers reject quietly through
-// the unhandledRejection trap below rather than crashing the script with a
-// synchronous throw -- *except* for class-shaped exports (PascalCase),
-// because `new Class()` on a function that returns a Promise yields the
-// Promise as the constructed value (per the `new` semantics), and the caller
-// then sees a confused `r.resolve is not a function` instead of our
-// attributable error. Sync-throw classes give the clean error in both
-// `new dnsp.Resolver()` and `dns.lookup()` cases. Functions are configurable
-// on the builtins we target; fall back to direct assignment on the off
-// chance one isn't.
+// Replace every own function on `mod` (and one level down on `mod.promises`) with a thrower.
+// Promise-shaped surfaces use denyFnAsync so fire-and-forget callers reject quietly -- except
+// class-shaped exports (PascalCase): `new Class()` returning a Promise yields the Promise as the
+// constructed value, so classes sync-throw to give a clean error in both `new` and call form.
 const isClassName = (key) => /^[A-Z]/.test(key)
 const denyModuleSurface = (specifier, mod, opts = {}) => {
   const { prefix = specifier, async: isAsync = specifier.endsWith('/promises') } = opts
@@ -96,29 +66,14 @@ const denyModuleSurface = (specifier, mod, opts = {}) => {
   }
 }
 
-// Every callable on these builtins is replaced with a thrower. The list
-// covers two categories:
-//
-//   1) Network surface (http/https/http2/net/dgram/tls/dns) -- the permission
-//      system has no --allow-net counterpart, so JS-mock is the *only* layer.
-//
-//   2) Process / worker surface (child_process/worker_threads/cluster/
-//      inspector) -- already denied at the kernel level by --permission (no
-//      --allow-child-process / --allow-worker / --allow-inspector and no
-//      --allow-addons). We duplicate the deny here on purpose: a JS-level
-//      thrower surfaces a clean, attributable ERR_STASIS_MOCK_BLOCKED instead
-//      of the kernel's ERR_ACCESS_DENIED, and it's defense in depth against
-//      anything that might quietly slip the permission rule (a future
-//      bypass, a misconfigured --allow flag, code that grabs primitives via
-//      process.binding before --permission's check fires, ...).
+// Every callable on these builtins is replaced with a thrower.
 const DENY_ALL = [
   // Network surface (no --allow-net counterpart -- JS-mock is the only layer).
   'node:http', 'node:https', 'node:http2',
   'node:net', 'node:dgram', 'node:tls',
   'node:dns', 'node:dns/promises',
-  // Process / worker / debug. Already kernel-denied by --permission; we
-  // duplicate the deny here for attributable errors and defense in depth
-  // against a future --allow-* slip-up or a process.binding bypass.
+  // Process/worker/debug: already --permission-denied; duplicated for attributable errors and
+  // defense in depth against a future --allow-* slip-up or a process.binding bypass.
   'node:child_process',
   'node:worker_threads',
   'node:cluster',
@@ -128,15 +83,9 @@ const DENY_ALL = [
   'node:repl',         // repl.start() opens an interactive stdin loop
   'node:sqlite',       // DatabaseSync can open/create SQLite files (Node 22+)
   'node:trace_events', // createTracing() can write trace files
-  'node:v8',           // writeHeapSnapshot bypasses node:fs (goes through V8);
-                       // setFlagsFromString mutates global V8 state. Serialize/
-                       // deserialize are blocked too -- if a package needs them
-                       // it can't run under --mock, which is consistent with
-                       // the "deny whole module" stance.
-  // node:wasi is *not* in this list: just require('node:wasi') emits an
-  // ExperimentalWarning to stderr on every --mock run, and --permission
-  // without --allow-wasi already denies WASI construction at the kernel
-  // level. The duplicate-deny isn't worth the warning noise.
+  'node:v8',           // writeHeapSnapshot bypasses node:fs; setFlagsFromString mutates global V8 state
+  // node:wasi is deliberately omitted: require('node:wasi') emits an ExperimentalWarning, and
+  // --permission already denies WASI construction at the kernel level.
 ]
 
 for (const specifier of DENY_ALL) {
@@ -149,24 +98,10 @@ for (const specifier of DENY_ALL) {
   denyModuleSurface(specifier, mod)
 }
 
-// process method denials. process.exit / process.abort are deliberately left
-// alone -- if user code wants to terminate early, let it; that's not a side
-// effect we should hide. The rest mutate global process state, do real I/O,
-// or talk to a parent over IPC:
-//   - chdir affects fs resolution for everything that runs after
-//   - kill signals other processes
-//   - umask affects every future file create
-//   - dlopen loads a native addon (--permission also denies)
-//   - binding returns Node's internal C++ bindings (--permission also denies);
-//     we duplicate to match the "process.binding bypass" claim in the header
-//   - setUid/setGid/setEuid/setEgid/setgroups/initgroups change privileges
-//     (--permission also denies these). Duplicated for attributable errors
-//   - send / disconnect talk to the parent over IPC (when the process was
-//     forked with stdio:'ipc'); not blocked by --permission
-//   - setSourceMapsEnabled / loadEnvFile mutate global Node state and (in
-//     loadEnvFile's case) read+mutate process.env from a file
-//   - setUncaughtExceptionCaptureCallback replaces Node's exception
-//     handling, which would also disable our exitCode=13 cleanup
+// process method denials. process.exit / process.abort are deliberately left alone -- early
+// termination isn't a side effect we should hide. The rest mutate global process state, do real
+// I/O, or talk to a parent over IPC; note setUncaughtExceptionCaptureCallback would also disable
+// our exitCode=13 cleanup below.
 const PROCESS_DENY = [
   'chdir', 'kill', 'umask', 'dlopen', 'binding',
   'setUid', 'setGid', 'setEuid', 'setEgid', 'setgroups', 'initgroups',
@@ -180,24 +115,14 @@ for (const name of PROCESS_DENY) {
   }
 }
 
-// process.report.writeReport(filename) writes a diagnostic JSON file to disk
-// (under --report-dir or cwd by default). Deny it so user code can't drop
-// reports into the project tree. process.report is an object, present on all
-// Node 12+ builds; the methods inside it are configurable.
+// process.report.writeReport writes a diagnostic JSON file to disk; deny it too.
 if (process.report && typeof process.report.writeReport === 'function') {
   mock.method(process.report, 'writeReport', denyFn('process.report.writeReport()'))
 }
 
-// fs writers: --permission blocks them at the kernel level too, but we mock
-// at the JS layer for cleaner attributable errors and so that user code can't
-// even *try* to mutate files inside the project's cwd (which is on the
-// --allow-fs-write list so stasis can emit its bundle/lockfile). Reads stay
-// real so node_modules resolution and config discovery keep working. This
-// works because loader-mock.js evaluates the core hooks lib *before* importing
-// us, so stasis's own destructured `import { writeFileSync } from 'node:fs'`
-// snapshots are already taken and it keeps real fs; the syncBuiltinESMExports()
-// call below then refreshes the node:fs ESM wrapper so the user's subsequent
-// ESM imports see the mocked names.
+// fs writers: --permission blocks these at the kernel level too, but JS-mocking gives cleaner
+// errors and stops user code mutating even cwd files (cwd is on --allow-fs-write for the bundle).
+// Reads stay real so node_modules resolution keeps working.
 const fs = require('node:fs')
 const fsPromises = require('node:fs/promises')
 const FS_WRITERS = [
@@ -221,25 +146,14 @@ for (const name of FS_WRITERS) {
   }
 }
 
-// Refresh the node:fs / node:fs/promises ESM wrappers so destructured/
-// namespace ESM imports made *after* this point see the mocked names.
-// Bindings already captured by stasis's own modules (linked before this file
-// ran) keep their snapshot of the real functions.
+// Refresh the node:fs ESM wrappers so ESM imports after this point see the mocked names;
+// bindings stasis already captured (linked before this file ran) keep their real snapshot.
 syncBuiltinESMExports()
 
-// Global fetch / WebSocket / EventSource come from undici, not node:http, so
-// they need separate handling. (Their transport bottoms out at node:net, which
-// is already blocked above -- but intercepting here yields a clean, attributable
-// error instead of a confusing low-level socket failure.) These globals are
-// writable + configurable, so assign directly.
-//
-// fetch returns a *forever-pending* promise rather than rejecting -- same
-// "silently ignored" semantics as the promise-style timers. An awaiter hangs,
-// fire-and-forget `void fetch(url)` quietly sits as a pending promise, and we
-// don't need an unhandledRejection trap (no rejection is produced). The event
-// loop is unaffected by a pending promise on its own, so the capture still
-// drains and the bundle gets written on beforeExit. WebSocket/EventSource
-// throw from their constructors so the synchronous shape is preserved.
+// Global fetch / WebSocket / EventSource come from undici, not node:http, so handle separately.
+// fetch returns a *forever-pending* promise (not a rejection) so an awaiter hangs and the capture
+// still drains to write the bundle on beforeExit; WebSocket/EventSource throw from their
+// constructors to preserve the synchronous shape.
 if (typeof globalThis.fetch === 'function') {
   globalThis.fetch = () => new Promise(() => {})
 }
@@ -251,58 +165,36 @@ for (const name of ['WebSocket', 'EventSource']) {
   }
 }
 
-// Our promise-shaped mocks (fs/promises, dns/promises, ...) sync-throw, which
-// `await` converts into a rejection. A fire-and-forget caller (no .catch / no
-// try-catch) would otherwise surface as unhandledRejection and tear the
-// process down before the loader writes the bundle on beforeExit. Swallow
-// *only* our own denials; rethrow everything else so real bugs still crash.
+// Our denials become unhandledRejections for fire-and-forget callers, which would tear the process
+// down before the loader writes the bundle. Swallow *only* our own denials; rethrow everything else.
 process.on('unhandledRejection', (reason) => {
   if (reason?.__stasisMock) return
   throw reason
 })
 
-// User code that awaits a denied promise (a forever-pending timer, an
-// undelivered fetch) leaves the top-level await unsettled, which Node 24+
-// flags by setting exitCode=13 at exit time. The bundle has already been
-// written by then (state.write() ran at beforeExit, before this), so the
-// capture itself succeeded -- override the 13 back to 0 so the CLI doesn't
-// report failure. Anything other than 13 (real assertion failure, syntax
-// error, ...) is preserved.
+// Node 24+ sets exitCode=13 when a top-level await stays unsettled (e.g. an awaited denied
+// promise). The bundle already wrote at beforeExit, so reset 13 -> 0; any other code is preserved.
 process.on('exit', () => {
   if (process.exitCode === 13) process.exitCode = 0
 })
 
-// Timers: silently ignored. Callback-style timers (setTimeout/setInterval/
-// setImmediate) become no-ops -- the callback never runs and the scheduling
-// call returns normally so user code keeps going. Promise-style timers
-// (node:timers/promises) return *forever-pending* promises: `await
-// setTimeout(...)` suspends forever and any code past the await never runs.
-// That's the "silently ignored" semantics for promise timers -- the awaiter
-// is dropped, not given a synthetic value. The process still exits cleanly
-// because a pending promise on its own doesn't keep the event loop alive, so
-// once everything else drains, Node tears down (logging an unsettled-
-// top-level-await warning) and the loader's beforeExit hook writes the
-// bundle.
-//
-// Stasis itself does not import node:timers anywhere, so unlike node:fs the
-// ESM wrapper for node:timers/timers-promises is not pre-materialized; the
-// CJS exports mutation below propagates to the user's first ESM import.
+// Timers: silently ignored. Callback timers (setTimeout/setInterval/setImmediate) become no-ops;
+// promise timers (node:timers/promises) return *forever-pending* promises so `await setTimeout()`
+// suspends forever. A pending promise doesn't keep the event loop alive, so the process still
+// exits cleanly and the loader's beforeExit hook writes the bundle.
 const noop = () => undefined
 const pending = () => new Promise(() => {})
-for (const name of ['setTimeout', 'setInterval', 'setImmediate']) globalThis[name] = noop
-for (const name of ['clearTimeout', 'clearInterval', 'clearImmediate']) globalThis[name] = noop
+const TIMERS = ['setTimeout', 'setInterval', 'setImmediate', 'clearTimeout', 'clearInterval', 'clearImmediate']
+for (const name of TIMERS) globalThis[name] = noop
 
 const timers = require('node:timers')
-for (const name of ['setTimeout', 'setInterval', 'setImmediate', 'clearTimeout', 'clearInterval', 'clearImmediate']) {
-  mock.method(timers, name, noop)
-}
+for (const name of TIMERS) mock.method(timers, name, noop)
 
 const timersPromises = require('node:timers/promises')
 mock.method(timersPromises, 'setTimeout', pending)
 mock.method(timersPromises, 'setImmediate', pending)
-// setInterval returns an async iterable; each `await iter.next()` is also a
-// forever-pending promise, so `for await (const _ of setInterval(...))` hangs
-// at the first iteration -- the loop body never runs.
+// setInterval returns an async iterable; each `await iter.next()` is forever-pending, so
+// `for await (const _ of setInterval(...))` hangs at the first iteration.
 mock.method(timersPromises, 'setInterval', () => ({
   [Symbol.asyncIterator]() {
     return { next: pending }

package/src/parse.js

@@ -4,18 +4,9 @@ import { brotliDecompressSync } from 'node:zlib'
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { Lockfile } from '@exodus/stasis-core/lockfile'
 
-// Read a stasis artifact from disk and parse it into a Lockfile or Bundle,
-// reporting which kind it turned out to be. `kind` is one of:
-//   'lockfile' -- a `stasis.lock.json` (files recorded as SRI digests)
-//   'bundle'   -- a `stasis.code.br` (one unified format holding both code and
-//                 resources; per-file encoding is read from its `formats` map)
-// The bundle is one format: code files hash as UTF-8 text and 'resource:base64'
-// files hash as their decoded bytes, decided per-file by `stasis diff` from the
-// bundle's formats rather than from a whole-bundle kind.
-//
-// Lockfiles are JSON text starting with `{`; bundles are brotli-compressed JSON.
-// Sniff the leading byte to route to the right parser so its diagnostic surfaces
-// on failure.
+// Read a stasis artifact and parse it into a Lockfile or Bundle, reporting its `kind`
+// ('lockfile' | 'bundle'). Lockfiles are JSON starting with `{`; bundles are brotli-compressed
+// JSON — sniff the leading byte to route to the right parser so its diagnostic surfaces on failure.
 export function parseFileWithKind(file) {
   let buf
   try {
@@ -44,10 +35,7 @@ export function parseFileWithKind(file) {
   }
 }
 
-// Read a stasis artifact from disk and parse it into a Lockfile or Bundle.
-// Shared by `stasis audit` and `stasis sbom`, which both inventory the packages
-// a lockfile/bundle records and don't care which kind it is. Thin wrapper over
-// `parseFileWithKind` that drops the `kind`.
+// Thin wrapper over parseFileWithKind that drops the `kind` (for callers like audit/sbom).
 export function parseFile(file) {
   return parseFileWithKind(file).artifact
 }