@exodus/stasis-plugins 1.0.0-beta.12 → 1.0.0-beta.14

package/src/metro-transformer.js

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, resolve as resolvePath } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { State } from '@exodus/stasis-core/state'
+import { servedByBundle } from '@exodus/stasis-core/state-util'
 import { transformContext } from './metro-babel-transformer.js'
 
 // Companion to the StasisMetro serializer, which withStasis() wires as Metro's `transformerPath`
@@ -11,7 +12,8 @@ import { transformContext } from './metro-babel-transformer.js'
 // wraps the project's own transformer, and does two things in each worker:
 //  - keeps each import as written for the serializer, through the Babel transformer it swaps in
 //    (./metro-babel-transformer.js): a dependency Babel rewrote (e.g. through
-//    babel-plugin-module-resolver) carries the specifiers written in the source as `stasisAsWritten`;
+//    babel-plugin-module-resolver) carries the specifiers written in the source as `stasisAsWritten`,
+//    and the output, the ones of the imports a Babel plugin consumed as `stasisConsumed`;
 //  - is the LOAD half of stasis for Metro (under load the serializer only asserts edges). Load only
 //    READS an immutable bundle and every worker reads the same bytes (no IPC), so a per-worker
 //    transformer is the natural seam: it replaces Metro's on-disk `data` with the bundle's
@@ -48,35 +50,18 @@ function baseConfig({ stasisBaseTransformerPath: _, ...config } = {}) {
 // -> transparent pass-through, so wiring it permanently is safe. A construction failure is cached
 // and rethrown on every call -- never throw-once-then-silently-pass-through. It never writes, so it
 // claims no write path: a capturing worker's own preload State already holds them.
-let stateInited = false
-let loadState = null
-let stateError = null
+let loaded
 function getLoadState() {
-  if (!stateInited) {
+  if (loaded === undefined) {
     try {
       const state = new State(process.cwd(), { claim: false })
-      loadState = state.config.loadBundle ? state : null
-    } catch (err) {
-      stateError = err
-      throw err
-    } finally {
-      stateInited = true
+      loaded = { state: state.config.loadBundle ? state : null }
+    } catch (error) {
+      loaded = { error }
     }
   }
-  if (stateError) throw stateError
-  return loadState
-}
-
-// True iff `absolute` is in scope for load mode. state.relative throws outside the project root
-// (out-of-scope: system files, scratch) -> defer to disk. Mirrors the webpack plugin's inScope.
-function inScope(state, absolute) {
-  try {
-    state.relative(absolute)
-  } catch {
-    return false
-  }
-  if (state.config.full) return true
-  return state.inNodeModules(pathToFileURL(absolute).toString())
+  if ('error' in loaded) throw loaded.error
+  return loaded.state
 }
 
 // The Babel transformer swapped in for the project's, by path as metro-transform-worker requires it.
@@ -88,17 +73,25 @@ function resolveBabelTransformer(base, path) {
   return isAbsolute(path) ? path : createRequire(base.file).resolve(path)
 }
 
-// Each dependency named by a specifier Babel rewrote, with the ones written in the source. One
-// Metro dependency can stand for several, written apart and rewritten alike (`#local/abc` and
-// `./src/abc`); a dependency written as Metro names it is left as is.
-function withAsWritten(result, asWritten) {
-  if (asWritten.size === 0 || !Array.isArray(result?.dependencies)) return result
+// Each dependency as the source wrote it. One named by a specifier Babel rewrote carries the ones
+// written in the source: one Metro dependency can stand for several, written apart and rewritten
+// alike (`#local/abc` and `./src/abc`). One no specifier in the source names carries
+// `stasisInserted`: Babel added it (a helper from @babel/runtime, the JSX runtime), or Metro did (its
+// asyncRequire for an `import()`, an asset's registry). A dependency written as Metro names it is
+// left as is. The imports a Babel plugin consumed, read and inlined in their stead
+// (`require('./messages.po')`, @exodus/i18n's plugin-inline-po), no dependency of Metro's, ride on
+// the output Metro keeps for the module, its first entry's data, as `stasisConsumed`.
+function withAsWritten(result, { asWritten, consumed }) {
+  if (!Array.isArray(result?.dependencies)) return result
   const dependencies = result.dependencies.map((dep) => {
     const written = asWritten.get(dep.name)
-    if (written === undefined || (written.size === 1 && written.has(dep.name))) return dep
+    if (written === undefined) return { ...dep, stasisInserted: true }
+    if (written.size === 1 && written.has(dep.name)) return dep
     return { ...dep, stasisAsWritten: [...written] }
   })
-  return { ...result, dependencies }
+  if (consumed.size === 0 || !Array.isArray(result.output) || result.output.length === 0) return { ...result, dependencies }
+  const [first, ...rest] = result.output
+  return { ...result, dependencies, output: [{ ...first, data: { ...first.data, stasisConsumed: [...consumed] } }, ...rest] }
 }
 
 export async function transform(config, projectRoot, filename, data, options) {
@@ -108,7 +101,7 @@ export async function transform(config, projectRoot, filename, data, options) {
   if (state) {
     // `filename` is project-relative in Metro's contract; resolve against projectRoot.
     const absolute = resolvePath(projectRoot, filename)
-    if (inScope(state, absolute)) {
+    if (servedByBundle(state, absolute)) {
       // getFile re-verifies the hash and throws on a file the bundle doesn't carry (fail-closed,
       // no disk fallback). Code sources come back as strings; resources as Buffers.
       const { source } = state.getFile(pathToFileURL(absolute).toString())
@@ -116,10 +109,10 @@ export async function transform(config, projectRoot, filename, data, options) {
     }
   }
   if (typeof config.babelTransformerPath !== 'string') return base.transformer.transform(config, projectRoot, filename, data, options)
-  const context = { babelTransformerPath: resolveBabelTransformer(base, config.babelTransformerPath), asWritten: new Map() }
+  const context = { babelTransformerPath: resolveBabelTransformer(base, config.babelTransformerPath), asWritten: new Map(), consumed: new Set() }
   const result = await transformContext.run(context, () =>
     base.transformer.transform({ ...config, babelTransformerPath: BABEL_TRANSFORMER }, projectRoot, filename, data, options))
-  return withAsWritten(result, context.asWritten)
+  return withAsWritten(result, context)
 }
 
 export function getCacheKey(config, opts) {

package/src/metro.js

@@ -1,17 +1,17 @@
 import assert from 'node:assert/strict'
-import { isUtf8 } from 'node:buffer'
+import { Buffer, isUtf8 } from 'node:buffer'
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
-import { isAbsolute, join } from 'node:path'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
-import { resolvePluginState } from './plugins.js'
-import { looksNative, nativeInputs } from './metro-native.js'
+import { resolvePluginState, unsupportedExtension } from './plugins.js'
+import { AUTO_INCLUDES, FILE_STAT, RN_CORE_INCLUDE_FILES, bundleDirHost, looksNative, metroAssetFiles, nativeInputs } from './metro-native.js'
 import { diskHost } from '@exodus/stasis-core/host'
 import { State } from '@exodus/stasis-core/state'
-import { realReadFileSync } from '@exodus/stasis-core/state-util'
-import { RN_CORE_INCLUDE_FILES, classifyExtension, classifyFormat, splitNodeModulesPath } from '@exodus/stasis-core/util'
+import { inScope, realReadFileSync } from '@exodus/stasis-core/state-util'
+import { classifyExtension, classifyFormat, isPathWithin, nodeExtFormat, splitNodeModulesPath } from '@exodus/stasis-core/util'
 
 const require = createRequire(import.meta.url)
 
@@ -33,12 +33,22 @@ function entrySet(graph) {
   return new Set()
 }
 
-// Files a React Native build requires that Metro's module graph never carries; attested (tagged by
-// the shared classifier, see #captureAutoIncludes) when they resolve from the project.
-const AUTO_INCLUDES = [
-  'metro-runtime/src/modules/asyncRequire.js',
-  '@react-native-community/cli/setup_env.sh',
-]
+// Metro's own transform plugins, as its transform worker names them for its cache key: the file
+// `metro-transform-plugins` resolves to from the project, else through metro and its transform
+// worker, which depend on it (a pnpm install links it only beside them). -> [] where none resolves
+function metroTransformPluginFiles(projectDir) {
+  for (const chain of [['metro-transform-plugins'], ['metro', 'metro-transform-worker', 'metro-transform-plugins']]) {
+    let file
+    try {
+      for (const name of chain) file = require.resolve(name, { paths: [file === undefined ? projectDir : dirname(file)] })
+    } catch {
+      continue
+    }
+    const { getTransformPluginCacheKeyFiles } = require(file)
+    return typeof getTransformPluginCacheKeyFiles === 'function' ? getTransformPluginCacheKeyFiles() : []
+  }
+  return []
+}
 
 // The worker-side toolchain that only Metro's transform workers load, named in both the
 // --child-process assert and the transform-cache warning so the two can't describe different sets.
@@ -135,6 +145,10 @@ function metroDefaultSerializer() {
 // transformerPath -- out of stasis's hands (see withStasis).
 export class StasisMetro {
   #seen = new Set()
+  // The project root's real path, once a consumed resource needs it (#consumedResources).
+  #realRoot
+  // Under load, the bundle's files as a directory listing, once an asset needs them (#bundleDirHost).
+  #bundleDirs
   #state
   #resources
 
@@ -245,28 +259,29 @@ export class StasisMetro {
 
   #capture(graph, preModules) {
     const entries = entrySet(graph)
+    const platform = graph.transformOptions?.platform ?? null
     // preModules first (Metro's prepended polyfills/runtime; synthetic ones like __prelude__ are
     // skipped by the existsSync guard below), then the app graph.
-    if (preModules) this.#captureModules(preModules, entries)
-    this.#captureModules(graph.dependencies.values(), entries)
-    // AFTER the graph so #seen already holds graph modules -- an auto-include that landed in the
-    // graph (asyncRequire, when the app uses dynamic import()) is deduped, not re-recorded.
+    if (preModules) this.#captureModules(preModules, entries, platform)
+    this.#captureModules(graph.dependencies.values(), entries, platform)
     this.#captureAutoIncludes()
+    this.#captureTransformPlugins()
     // AFTER the graph + auto-includes (same dedupe reason): the native pass only adds the native
     // build-input surface (podspec/gradle/sources) that no module graph carries.
     this.#captureNativeModules()
   }
 
-  // Shared epilogue for the classify-driven capture paths: record under the given format/resource.
-  // `format` null/undefined lets addFile pick (loader format for JS unless `inferFormat` is false,
-  // byte-derived for a resource); addFile already asserts UTF-8 for a non-resource (code) source, so
-  // no guard is needed here.
-  #recordCapture(full, source, { format, resource, inferFormat = true }) {
-    this.#state.addFile(pathToFileURL(full).toString(), { source, format: format ?? undefined, resource, inferFormat, reason: 'metro' })
+  // Shared epilogue for the classify-driven capture paths: record under the given format/resource,
+  // attributed to `reason`. `format` null/undefined lets addFile pick (loader format for JS unless
+  // `inferFormat` is false, byte-derived for a resource); addFile already asserts UTF-8 for a
+  // non-resource (code) source, so no guard is needed here.
+  #recordCapture(full, source, { format, resource, inferFormat = true, reason = 'metro' }) {
+    this.#state.addFile(pathToFileURL(full).toString(), { source, format: format ?? undefined, resource, inferFormat, reason })
   }
 
-  // Attest the AUTO_INCLUDES list. Per entry, skip: unresolvable, already-seen, or resolving
-  // outside the project root (keys are root-relative). Attested entries ride the normal addFile path.
+  // Attest the AUTO_INCLUDES list (./metro-native.js, shared with `stasis bundle --metro`). Per entry,
+  // skip: unresolvable, already-seen, or resolving outside the project root (keys are root-relative).
+  // Attested entries ride the normal addFile path.
   #captureAutoIncludes() {
     for (const specifier of AUTO_INCLUDES) {
       let modPath
@@ -275,21 +290,35 @@ export class StasisMetro {
       } catch {
         continue
       }
-      if (this.#seen.has(modPath)) continue
-      try {
-        this.#state.relative(modPath)
-      } catch {
-        continue
-      }
+      if (this.#seen.has(modPath) || !this.#within(modPath)) continue
       this.#seen.add(modPath)
       // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
       const source = realReadFileSync(modPath)
       // Tag from the ONE shared classifier so an auto-include agrees with any other path meeting
       // the same file (native walk, --fs): setup_env.sh -> 'shell', not a forced 'resource' that
       // would collide at the format noupsert. Unrecognized -> resource (vetted list, so no allowlist).
-      // JS (asyncRequire.js) is code Metro builds, so it takes no format, as the graph's doesn't.
       const format = classifyFormat(modPath, { content: source })
-      this.#recordCapture(modPath, source, { format, resource: format === undefined, inferFormat: false })
+      this.#recordCapture(modPath, source, { format, resource: format === undefined, inferFormat: false, reason: 'run' })
+    }
+  }
+
+  // Attest each of Metro's own transform plugins (metroTransformPluginFiles). Its transform worker
+  // hashes every one into its cache key, but loads one only as the build's options call for it
+  // (import-export-plugin under `experimentalImportSupport`, inline-requires-plugin under
+  // `inlineRequires`, constant-folding-plugin outside dev, normalizePseudoGlobals when minifying), so
+  // a capture loads them all, as Metro would: under `stasis run` the loader then records each with
+  // what it imports, so a bundle builds under any of those options. Each is recorded besides, as the
+  // Node module it is, where no loader records it, attributed to `run` as one Metro loads is: the
+  // build's toolchain, none of it the app's. One outside the project root is passed over.
+  #captureTransformPlugins() {
+    for (const file of metroTransformPluginFiles(this.#projectDir)) {
+      if (this.#seen.has(file) || !this.#within(file)) continue
+      this.#seen.add(file)
+      try {
+        require(file)
+      } catch { /* one that can't load can't run under Metro either: its bytes are still recorded */ }
+      // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
+      this.#recordCapture(file, realReadFileSync(file), { reason: 'run' })
     }
   }
 
@@ -310,23 +339,12 @@ export class StasisMetro {
     // RN CORE isn't a `dependencies` entry (config reports only reactNativePath) and autolinking
     // never lists it, but its native source (React/, ReactCommon/, ReactAndroid/, sdks/, ...) is a
     // build input like any other dep's -- walk it in full, the same way.
-    const rnPath = config.reactNativePath
-    if (typeof rnPath === 'string' && isAbsolute(rnPath)) roots.add(rnPath)
-    for (const root of roots) {
-      try {
-        this.#state.relative(root) // asserts the package lives inside the project root
-      } catch {
-        continue
-      }
-      this.#captureNativeTree(root)
-    }
+    const rnPath = typeof config.reactNativePath === 'string' && isAbsolute(config.reactNativePath) ? config.reactNativePath : null
+    if (rnPath !== null) roots.add(rnPath)
+    // One outside the project root is unattestable.
+    for (const root of roots) if (this.#within(root)) this.#captureNativeTree(root)
     // RN core's `.js` build scripts the walk skips (Metro-owned by extension, but never in the graph).
-    if (typeof rnPath === 'string' && isAbsolute(rnPath)) {
-      try {
-        this.#state.relative(rnPath)
-        for (const file of RN_CORE_INCLUDE_FILES) this.#captureNativeFile(join(rnPath, file))
-      } catch { /* react-native resolved outside the project root -- unattestable */ }
-    }
+    if (rnPath !== null && this.#within(rnPath)) for (const file of RN_CORE_INCLUDE_FILES) this.#captureNativeFile(join(rnPath, file))
   }
 
   // Attest a single vetted file (RN_CORE_INCLUDE_FILES) the tree walk skips; absent -> skipped.
@@ -358,12 +376,13 @@ export class StasisMetro {
   }
 
   // Attest the native build inputs of the package at `root` (nativeInputs, shared with `stasis bundle
-  // --metro`), but what is already captured as a graph module or auto-include. Real readers: plugin
-  // bookkeeping, not re-recorded by --fs.
+  // --metro`), but what is already captured as a graph module or auto-include, each in the format it
+  // gives (none for a codegen source, as Metro's code has none, so none is inferred). Real readers:
+  // plugin bookkeeping, not re-recorded by --fs.
   #captureNativeTree(root) {
     for (const { file, source, action, format } of nativeInputs(root, diskHost, { resources: this.#resources, skip: (f) => this.#seen.has(f) })) {
       this.#seen.add(file)
-      this.#recordCapture(file, source, { format, resource: action === 'resource' })
+      this.#recordCapture(file, source, { format, resource: action === 'resource', inferFormat: false })
     }
   }
 
@@ -379,6 +398,8 @@ export class StasisMetro {
       if (modPath === undefined) continue
       const url = pathToFileURL(modPath).toString()
       for (const [specifier, target] of this.#edges(module)) this.#state.assertImport(url, specifier, target, { platform })
+      this.#assertConsumed(module, modPath)
+      this.#assertAssetFiles(module, modPath, platform ?? null)
     }
   }
 
@@ -386,9 +407,13 @@ export class StasisMetro {
   // (`dep.data.name`) by the specifier Babel left; where a plugin rewrote it, the stasis transformer
   // (./metro-transformer.js) carries the ones written in the source. Code and resource targets alike,
   // as `stasis bundle --metro` and the esbuild plugin record them: an asset is resolved as code is.
+  // One the source doesn't write (`stasisInserted`: a Babel helper, the JSX runtime, Metro's
+  // asyncRequire) is no edge, as `stasis bundle --metro` has none: its file is carried, as every
+  // module of the graph is, and under load Metro resolves it unasserted.
   #edges(module) {
     const edges = []
     for (const dep of module.dependencies?.values?.() ?? []) {
+      if (dep?.data?.stasisInserted === true) continue
       const target = dep?.absolutePath
       if (typeof target !== 'string' || !isAbsolute(target) || !existsSync(target)) continue
       if (classifyExtension(target, this.#resources) === 'unknown') continue
@@ -399,17 +424,14 @@ export class StasisMetro {
     return edges
   }
 
-  #captureModules(modules, entries) {
+  #captureModules(modules, entries, platform) {
     for (const module of modules) {
       const modPath = diskPath(module)
       if (modPath === undefined) continue
 
       const kind = classifyExtension(modPath, this.#resources)
       if (kind === 'unknown') {
-        throw new Error(
-          `StasisMetro: unsupported extension for '${modPath}' -- ` +
-          `add its extension or filename to the plugin's resources option or stop importing it`
-        )
+        throw new Error(unsupportedExtension('StasisMetro', `'${modPath}'`))
       }
       const url = pathToFileURL(modPath).toString()
       for (const [specifier, target] of this.#edges(module)) this.#state.addImport(url, specifier, target)
@@ -425,9 +447,152 @@ export class StasisMetro {
         assert.ok(isUtf8(source), `StasisMetro: code-classified file has non-UTF-8 bytes: ${modPath}`)
       }
       // No format for a code file: Metro transforms it from source, so Node's module/commonjs isn't
-      // what runs (a resource still takes its byte-derived one).
-      this.#state.addFile(url, { source, isEntry: entries.has(modPath), resource: kind === 'resource', inferFormat: false, reason: 'metro' })
+      // what runs. But the one its name alone gives it (.json, .mjs, .cjs: nodeExtFormat), as Node
+      // loads it too, which a --fs read of it records besides (a resource still takes its
+      // byte-derived format).
+      const format = kind === 'code' ? nodeExtFormat(modPath) : undefined
+      this.#state.addFile(url, { source, format, isEntry: entries.has(modPath), resource: kind === 'resource', inferFormat: false, reason: 'metro' })
+      this.#captureConsumed(module, modPath)
+      this.#captureAssetFiles(module, modPath, platform)
+    }
+  }
+
+  // Whether `path` lies within the project root, as the State's root-relative keys need.
+  #within(path) {
+    return isPathWithin(this.#state.root, path)
+  }
+
+  // `path`'s real path, where it lies within the project root (not linked out of it), else null.
+  #realWithin(path) {
+    let real
+    try {
+      real = diskHost.realpath(path)
+      this.#realRoot ??= diskHost.realpath(this.#state.root)
+    } catch {
+      return null
     }
+    return this.#within(real) && isPathWithin(this.#realRoot, real) ? real : null
+  }
+
+  // The resources a Babel plugin consumed in transforming `module`, read and inlined in their imports'
+  // stead (`require('./messages.po')`, @exodus/i18n's plugin-inline-po), as the stasis transformer
+  // carries them (`stasisConsumed`): no module of Metro's, so no edge, but the build's input all the
+  // same. One named by path, as such a plugin reads it, from the module's dir, by its real path, as
+  // Metro names its modules. One naming code (an import a plugin split into others, as
+  // babel-plugin-lodash does), no file, or one outside the project root is passed over; one the
+  // resources don't carry is refused. -> each as { file: its real path, read: the path read }
+  * #consumedResources(module, modPath) {
+    for (const specifier of module.output?.[0]?.data?.stasisConsumed ?? []) {
+      if (typeof specifier !== 'string' || !(isAbsolute(specifier) || /^\.\.?\//u.test(specifier))) continue
+      const read = resolve(dirname(modPath), specifier)
+      const file = diskHost.stat(read)?.isFile() ? this.#realWithin(read) : null
+      if (file === null) continue
+      const kind = classifyExtension(file, this.#resources)
+      if (kind === 'code') continue
+      if (kind === 'unknown') {
+        throw new Error(unsupportedExtension('StasisMetro', `'${file}', which a Babel plugin inlines into '${modPath}'`))
+      }
+      yield { file, read }
+    }
+  }
+
+  // Capture: each, attributed to `metro`, as `stasis bundle --metro` records them under `bundle:metro`.
+  #captureConsumed(module, modPath) {
+    for (const { file } of this.#consumedResources(module, modPath)) this.#captureRead(file, 'resource')
+  }
+
+  // Capture `path`, a file Metro's build reads that its graph doesn't carry, once, attributed to
+  // `metro`, as the `kind` classifyExtension gives it.
+  #captureRead(path, kind) {
+    if (this.#seen.has(path)) return
+    this.#seen.add(path)
+    // Real reader: plugin bookkeeping, not a program fs read -- must not be re-recorded by --fs.
+    this.#recordCapture(path, realReadFileSync(path), { format: kind === 'code' ? nodeExtFormat(path) : undefined, resource: kind === 'resource', inferFormat: false })
+  }
+
+  // Load: the Babel plugin reads each from disk, past the stasis transformer (#assertOnDisk).
+  #assertConsumed(module, modPath) {
+    for (const files of this.#consumedResources(module, modPath)) {
+      this.#assertOnDisk(files, { what: `which a Babel plugin inlines into '${modPath}'`, servedBy: ['sync', 'async'] })
+    }
+  }
+
+  // The files of the asset module `module` Metro builds, by the names it reads them by (#assetDirHost):
+  // as Metro reads them to build it (its `scales` and `hash`) and copies them out with it, it and its
+  // other scales (`logo@2x.png`, `logo@3x.png`; metroAssetFiles, Metro's own rule for `platform`). No
+  // import names one, so no edge. -> their paths, none for a module no asset
+  #assetFiles(module, modPath, platform) {
+    return module.output?.[0]?.type === 'js/module/asset' ? metroAssetFiles(modPath, platform, this.#assetDirHost()) : []
+  }
+
+  // The directory listing Metro finds an asset's files in (fs.promises.readdir): the disk's, but under
+  // load with --fs=async, which serves it, the bundle's where it has one (a file added on disk since
+  // is no file of the asset Metro builds), each name in it a file where it is one on disk or the bundle
+  // serves one (gone from disk, it holds no drift).
+  #assetDirHost() {
+    const state = this.#state
+    if (!state.config.loadBundle || state.config.fs !== 'async') return diskHost
+    return {
+      readdir: (dir) => state.getFsDirFamily(pathToFileURL(dir).toString())?.map((name) => ({ name })) ?? diskHost.readdir(dir),
+      stat: (path) => diskHost.stat(path) ?? (state.getFsStatFamily(pathToFileURL(path).toString()) === 'file' ? FILE_STAT : null),
+    }
+  }
+
+  // The files the bundle carries, as a directory listing of them (`metroAssetFiles`' host): an asset's
+  // files as captured.
+  #bundleDirHost() {
+    this.#bundleDirs ??= bundleDirHost(this.#state)
+    return this.#bundleDirs
+  }
+
+  // Capture: each but the module itself, attributed to `metro`, as `stasis bundle --metro` records them:
+  // by the name Metro reads it by, with the bytes it reads there (one linked in, its target's), so a
+  // load holds that name to them. One linked from outside the project is passed over.
+  #captureAssetFiles(module, modPath, platform) {
+    for (const read of this.#assetFiles(module, modPath, platform)) {
+      const kind = classifyExtension(read, this.#resources)
+      // One of a kind unknown, as the module itself, which the graph capture refused.
+      if (kind !== 'unknown' && this.#realWithin(read) !== null) this.#captureRead(read, kind)
+    }
+  }
+
+  // Load: Metro's asset transformer reads each of an asset's files from disk (fs.promises), the module's
+  // own too, past the stasis transformer, which serves the module's `data` that it never reads. Each it
+  // reads on disk must be the bundle's under the name it reads it by (#assertOnDisk: a scale added since
+  // the capture, or one a symlink redirects, reads bytes the bundle doesn't carry there); and each the
+  // bundle carries must be among those it reads (one gone builds another asset, its `scales` and `hash`,
+  // from what remains) -- unless --fs=async serves them.
+  #assertAssetFiles(module, modPath, platform) {
+    const read = this.#assetFiles(module, modPath, platform)
+    if (read.length === 0) return
+    const what = `a file of the asset '${modPath}' Metro builds`
+    for (const path of read) {
+      if (diskHost.stat(path)?.isFile()) this.#assertOnDisk({ file: path, read: path }, { what, servedBy: ['async'] })
+    }
+    if (!inScope(this.#state, pathToFileURL(modPath).toString())) return
+    for (const file of metroAssetFiles(modPath, platform, this.#bundleDirHost())) {
+      if (read.includes(file)) continue
+      throw new Error(`StasisMetro: '${file}', ${what} as the bundle carries it, is gone -- Metro would build the asset without it under load; restore it`)
+    }
+  }
+
+  // Load: a file Metro's build reads from disk by `read`, past the stasis transformer, which serves only
+  // the module it transforms. One in scope (as the transformer's: any under scope=full, else one in
+  // node_modules) is held to the bundle's bytes for `file` (getFile throws on one it doesn't carry),
+  // fail closed on drift -- unless --fs, in a mode of `servedBy` (async patches fs.promises too), serves
+  // the read from the bundle itself, which it does by the path read (not a symlink to the file the
+  // bundle carries).
+  #assertOnDisk({ file, read }, { what, servedBy }) {
+    const state = this.#state
+    const url = pathToFileURL(file).toString()
+    if (!inScope(state, url)) return
+    if (servedBy.includes(state.config.fs) && state.getFsFileFamily(pathToFileURL(read).toString()) !== undefined) return
+    const { source } = state.getFile(url)
+    if (realReadFileSync(file).equals(Buffer.isBuffer(source) ? source : Buffer.from(source))) return
+    throw new Error(
+      `StasisMetro: '${file}', ${what}, differs on disk from the bundle -- ` +
+      'Metro\'s build reads it from disk under load; restore it, or run with --fs to serve it from the bundle'
+    )
   }
 }
 

package/src/plugins.js

@@ -22,7 +22,7 @@ import { extSetsEqual, parseResourcesOption } from '@exodus/stasis-core/util'
 //  7. lock='none' AND bundle='none' with no preload is a no-op (env-controlled-off framework plugins).
 export function resolvePluginState(label, options, cwd) {
   validatePluginOptions(label, options)
-  const { scope, lock, bundle, bundleFile, resourcesBundleFile, debug, childProcess, packageJSON, resources } = options
+  const { lock, bundle, bundleFile, resourcesBundleFile, resources } = options
   // Same-instance fast path: loader installed but lazy initState hasn't fired (webpack builds plugins
   // before user code). Force-init so the plugin lands in the ambient branch. NOT for a separate
   // stasis-core copy -- that would mint a phantom State.preload racing the real loader's write.
@@ -69,21 +69,13 @@ export function resolvePluginState(label, options, cwd) {
 
   // Preload active: the lockfile is necessarily the ambient's. Enforce field coordination, then reuse or sidecar.
   const pc = ambient.config
-  if (lock !== undefined && lock !== pc.lock) {
-    throw new Error(`${label}: lock='${lock}' conflicts with active preload lock='${pc.lock}'`)
-  }
-  // scope/debug/childProcess must agree with the preload (reuse adopts it, sidecar copies it).
-  if (scope !== undefined && scope !== pc.scope) {
-    throw new Error(`${label}: scope='${scope}' conflicts with active preload scope='${pc.scope}'`)
-  }
-  if (debug !== undefined && debug !== pc.debug) {
-    throw new Error(`${label}: debug=${debug} conflicts with active preload debug=${pc.debug}`)
-  }
-  if (childProcess !== undefined && childProcess !== pc.childProcess) {
-    throw new Error(`${label}: childProcess=${childProcess} conflicts with active preload childProcess=${pc.childProcess}`)
-  }
-  if (packageJSON !== undefined && packageJSON !== pc.packageJSON) {
-    throw new Error(`${label}: packageJSON=${packageJSON} conflicts with active preload packageJSON=${pc.packageJSON}`)
+  // lock/scope/debug/childProcess/packageJSON must agree with the preload (reuse adopts it, sidecar
+  // copies it). The string modes are quoted, the boolean toggles not (validatePluginOptions typed them).
+  const shown = (value) => (typeof value === 'string' ? `'${value}'` : value)
+  for (const key of ['lock', 'scope', 'debug', 'childProcess', 'packageJSON']) {
+    if (options[key] !== undefined && options[key] !== pc[key]) {
+      throw new Error(`${label}: ${key}=${shown(options[key])} conflicts with active preload ${key}=${shown(pc[key])}`)
+    }
   }
   // resources is process-wide, so a plugin's allowlist must agree with the preload's -- compare
   // parsed sets (order/dupes/case-insensitive) to prevent one plugin silently widening the asset set.
@@ -100,13 +92,27 @@ export function resolvePluginState(label, options, cwd) {
   // fs-READ during the build from genuine run dependencies recorded before any plugin existed.
   ambient.markPluginAttached()
 
+  // A State of its own bundle (`mode`, at bundleFile) beside the preload, whose lockfile it shares
+  // and whose other settings it carries over (sidecars skip stasis.config.json discovery).
+  const sidecar = (mode) => ({
+    state: new State(cwd, {
+      parent: ambient,
+      scope: pc.scope,
+      lock: pc.lock,
+      bundle: mode,
+      bundleFile,
+      resourcesBundleFile,
+      debug: pc.debug,
+      childProcess: pc.childProcess,
+      packageJSON: pc.packageJSON,
+      resources: [...pc.resources],
+      brotliQuality: pc.brotliQuality,
+    }),
+    isNoop: false,
+  })
+
   if (pc.bundle) {
-    // Preload has bundle on -- plugin can't disable, must match mode.
-    if (bundle === 'none' || bundle === 'ignore') {
-      throw new Error(
-        `${label}: bundle='${bundle}' conflicts with active preload bundle='${pc.bundleMode}'`
-      )
-    }
+    // Preload has bundle on -- plugin can't disable (pc.bundleMode is neither 'none' nor 'ignore'), must match mode.
     if (bundle !== undefined && bundle !== pc.bundleMode) {
       throw new Error(
         `${label}: bundle='${bundle}' conflicts with active preload bundle='${pc.bundleMode}'`
@@ -118,21 +124,7 @@ export function resolvePluginState(label, options, cwd) {
       return { state: ambient, isNoop: false }
     }
     // Rule 6: different path -- sidecar inherits preload's modes, overrides bundleFile.
-    const sidecar = new State(cwd, {
-      parent: ambient,
-      scope: pc.scope,
-      lock: pc.lock,
-      bundle: pc.bundleMode,
-      bundleFile,
-      resourcesBundleFile,
-      debug: pc.debug,
-      childProcess: pc.childProcess,
-      packageJSON: pc.packageJSON,
-      resources: [...pc.resources],
-      // carried over: sidecars skip stasis.config.json discovery
-      brotliQuality: pc.brotliQuality,
-    })
-    return { state: sidecar, isNoop: false }
+    return sidecar(pc.bundleMode)
   }
 
   // Preload exists but has no bundle.
@@ -152,18 +144,23 @@ export function resolvePluginState(label, options, cwd) {
       `${label}: bundle='${bundle}' alongside a preload without bundle requires an explicit bundleFile`
     )
   }
-  const sidecar = new State(cwd, {
-    parent: ambient,
-    scope: pc.scope,
-    lock: pc.lock,
-    bundle,
-    bundleFile,
-    resourcesBundleFile,
-    debug: pc.debug,
-    childProcess: pc.childProcess,
-    packageJSON: pc.packageJSON,
-    resources: [...pc.resources],
-    brotliQuality: pc.brotliQuality, // carried over, like the Rule 6 sidecar above
-  })
-  return { state: sidecar, isNoop: false }
+  return sidecar(bundle)
+}
+
+// What a plugin (`label`) says of a file it is given (`what`, as it names it) whose extension it
+// neither bundles as code nor is allowed as a resource.
+export const unsupportedExtension = (label, what) =>
+  `${label}: unsupported extension for ${what} -- add its extension or filename to the plugin's resources option or stop importing it`
+
+// `state.getImport(parentURL, specifier, options)`, or undefined where the bundle attests no such edge:
+// at a successful capture that's an EXTERNAL (never recorded as an edge), the bundler's to resolve as
+// without us. File BYTES still fail closed where the plugin loads them; any other error is a real
+// fault, thrown.
+export function attestedImport(state, parentURL, specifier, options) {
+  try {
+    return state.getImport(parentURL, specifier, options)
+  } catch (err) {
+    if (err?.code === 'ERR_MODULE_NOT_FOUND') return undefined
+    throw err
+  }
 }