@exodus/stasis-plugins 1.0.0-beta.15 → 1.0.0-beta.17

package/src/metro-native.js

@@ -3,22 +3,16 @@ import { basename, dirname, join, posix, relative, sep } from 'node:path'
 
 import { readJson } from '@exodus/stasis-core/bundle-util'
 import { diskHost } from '@exodus/stasis-core/host'
-import { CODE_EXTENSIONS, classifyFormat, isAutoExcludedDir, isBinaryPlist, isDotEnvFile, isExcludedNativeFile, isNativeArtifact, nameFormat, pathExt, toPosix } from '@exodus/stasis-core/util'
-
-// The native build inputs of a React Native app's packages, shared by the Metro plugin's capture and
-// `stasis bundle --metro` so the two carry the same files. Both read through `fs`:
-//   readdir(dir) -> Dirent[] (throws where `dir` isn't one), readFile(file) -> Buffer,
-//   stat(path) -> Stats, or null where nothing is there.
-
-// Files a React Native build requires that neither Metro's module graph nor a run's loader carries,
-// each as a require() of it from the project root resolves it (one that doesn't, or lies outside the
-// root, is passed over), tagged by the shared classifier: setup_env.sh, which the React Native CLI runs
-// (`execFileSync`) as every command of it starts, `react-native config` the Metro plugin runs included.
-// The run's toolchain, none of it the app's: the Metro plugin records each under `run`, `stasis bundle
-// --metro` as its own (`bundle`).
+import { CODE_EXTENSIONS, classifyFormat, isAutoExcludedDir, isBinaryPlist, isDotEnvFile, isExcludedNativeFile, isNativeArtifact, nameFormat, pathExt, toPosix, upsert } from '@exodus/stasis-core/util'
+
+// The native build inputs of a React Native app's packages, shared by the Metro plugin's capture and `stasis bundle
+// --metro` so the two carry the same files. `fs` is a host: readdir(dir) -> Dirent[] (throws where `dir` isn't one),
+// readFile(file) -> Buffer, stat(path) -> Stats, or null where nothing is there.
+
+// Files a React Native build requires that neither Metro's graph nor a run's loader carries, resolved from the project
+// root: setup_env.sh, which the React Native CLI runs as every command starts (`react-native config` included).
 export const AUTO_INCLUDES = ['@react-native-community/cli/setup_env.sh']
 
-// The entries of the directory `dir`, none where it's missing or no directory.
 export function listing(dir, fs) {
   try {
     return fs.readdir(dir)
@@ -27,39 +21,31 @@ export function listing(dir, fs) {
   }
 }
 
-// RN core build scripts the native walk would defer to Metro as `.js`, but Metro never sees them (RN's
-// podspecs invoke them at pod-install). Project-relative, so react-native's `exports` can't hide them.
+// RN core build scripts the native walk would defer to Metro as `.js`, but Metro never sees them (RN's podspecs
+// invoke them at pod-install). Project-relative, so react-native's `exports` can't hide them.
 export const RN_CORE_INCLUDE_FILES = ['sdks/hermes-engine/utils/replace_hermes_version.js']
 
-// Discovered by name: RN scatters podspecs in subdirs `react-native config` misses.
-function isPodspec(name) {
-  return name.endsWith('.podspec') || name.endsWith('.podspec.json')
-}
+// By name: RN scatters podspecs in subdirs `react-native config` misses.
+const isPodspec = (name) => name.endsWith('.podspec') || name.endsWith('.podspec.json')
 
 // The off-platform top-level dir of a native package, which no build on this host compiles.
 export function isExcludedNativeDir(name, { win32 = process.platform === 'win32' } = {}) {
   return !win32 && name === 'windows'
 }
 
-// Dirs the NATIVE walks (Metro plugin + the static --metro bundler) skip, on top of the shared set:
-// nested packages (attested separately) and regenerated build output -- none is a build input.
+// Nested packages (attested separately) and regenerated build output, on top of the shared set.
 const NATIVE_BUILD_OUTPUT_DIRS = new Set(['node_modules', 'build', '.gradle', '.cxx', 'Pods', 'DerivedData'])
-function isSkippedNativeWalkDir(name) {
-  return NATIVE_BUILD_OUTPUT_DIRS.has(name) || isAutoExcludedDir(name) || isNativeArtifact(name)
-}
+const isSkippedNativeWalkDir = (name) => NATIVE_BUILD_OUTPUT_DIRS.has(name) || isAutoExcludedDir(name) || isNativeArtifact(name)
 
-// An extensionless non-UTF-8 file is a compiled tool (Hermes' `hermesc`), never source -- skipped.
-function isExtensionlessBinary(name, content) {
-  return pathExt(name) === '' && Buffer.isBuffer(content) && !isUtf8(content)
-}
+// A compiled tool (Hermes' `hermesc`), never source.
+const isExtensionlessBinary = (name, content) => pathExt(name) === '' && Buffer.isBuffer(content) && !isUtf8(content)
 
-// The Metro native capture's policy view. Returns { action, format }: 'code' (a native build input),
-// 'skip' (excluded noise, or a JS-family file matched BY EXTENSION -- Metro owns those), else 'resource'.
+// A native capture's view of a file by name: { action: 'code', format } for a native build input, 'skip' for noise
+// or a JS-family file by extension (Metro owns those), else 'resource'.
 export function classifyNativeCapture(name, { win32 = process.platform === 'win32', content } = {}) {
   // `.env` files carry secrets: an automated capture must never sweep them in.
   if (isExcludedNativeFile(name, { win32 }) || isDotEnvFile(name)) return { action: 'skip' }
-  // Name-matched code is always a native build input, even when its tag is a Node format the JS
-  // graph would otherwise own.
+  // Name-matched code is a native build input even where its tag is a Node format the JS graph would own.
   const byName = nameFormat(name)
   if (byName !== undefined) return { action: 'code', format: byName }
   if (CODE_EXTENSIONS.has(pathExt(name))) return { action: 'skip' }
@@ -67,18 +53,16 @@ export function classifyNativeCapture(name, { win32 = process.platform === 'win3
   return format === undefined ? { action: 'resource' } : { action: 'code', format }
 }
 
-// The byte-level half of the native classification, refining what classifyNativeCapture derived from the
-// NAME. Both rules only ever demote. A 'resource' carries no format: storage derives base64 from bytes.
+// classifyNativeCapture refined by the bytes, which only ever demote; a 'resource' gets its format from its bytes.
 export function refineNativeCapture(classified, name, content, resources = new Set()) {
   if (isExtensionlessBinary(name, content)) return { action: 'skip' }
   if (isBinaryPlist(name, content)) return { action: resources.has('plist') ? 'resource' : 'skip' }
   return classified
 }
 
-// A file name as Metro's AssetPaths reads it (parsePlatformFilePath, then parseBaseName): its asset,
-// `${name}.${type}` less any scale (`a@2x.png` is `a.png`'s), its scale (`resolution`, 1 where it
-// names none), and its platform where it names `platform` (`a.ios.png`; another's, `a.android.png`,
-// is an asset of its own). -> { asset, name, type, resolution, platform }, or null for a name with no type
+// A file name as Metro's AssetPaths reads it (parsePlatformFilePath, then parseBaseName): its asset, `${name}.${type}`
+// less any scale (`a@2x.png` is `a.png`'s), its scale (`resolution`, 1 where it names none), and its platform where it
+// names `platform` (`a.ios.png`; `a.android.png` is an asset of its own). -> null for a name with no type
 const METRO_PLATFORM_FILE = /^(.+?)(?:\.([^.]+))?\.([^.]+)$/u
 const METRO_ASSET_SCALE = /^(.+?)(?:@([\d.]+)x)?$/u
 export function parseMetroAssetName(name, platform) {
@@ -91,11 +75,10 @@ export function parseMetroAssetName(name, platform) {
   return { asset: `${root}.${type}`, name: root, type, resolution: Number.isNaN(resolution) ? 1 : resolution, platform: ofPlatform ? platform : null }
 }
 
-// What a file's stat answers to metroAssetFiles, for a file a listing names but the disk lacks.
+// A file's stat for metroAssetFiles, where a listing names one the disk lacks.
 export const FILE_STAT = { isFile: () => true }
 
-// The files `state` (a loaded State) carries, as a directory listing of them (metroAssetFiles' host):
-// an asset's files as captured.
+// The files `state` (a loaded State) carries, as a directory listing of them (metroAssetFiles' host).
 export function bundleDirHost(state) {
   const dirs = Map.groupBy([...state.sources.keys(), ...state.resources.keys()], (rel) => posix.dirname(rel))
   return {
@@ -104,10 +87,9 @@ export function bundleDirHost(state) {
   }
 }
 
-// Metro's record of the asset module `path` (its Assets' getAbsoluteAssetRecord): the files it reads
-// to build the module (its `scales` and `hash`) and copies out with it. In `path`'s directory, each of
-// the asset's name and type at any scale (`a.png`, `a@2x.png`, `a@3x.png`): those for `platform`
-// (`a.ios.png`, `a@3x.ios.png`) where it has any, else those for none. -> absolute paths
+// Metro's record of the asset module `path` (getAbsoluteAssetRecord): the files it reads to build it and copies out
+// with it, each of the asset's name and type at any scale in its directory, those for `platform` where it has any,
+// else those for none. -> absolute paths
 export function metroAssetFiles(path, platform = null, host = diskHost) {
   const own = parseMetroAssetName(basename(path), platform)
   if (own === null) return []
@@ -116,45 +98,34 @@ export function metroAssetFiles(path, platform = null, host = diskHost) {
   for (const { name } of host.readdir(dir)) {
     const parsed = parseMetroAssetName(name, platform)
     if (parsed?.asset !== own.asset || host.stat(join(dir, name))?.isFile() !== true) continue
-    if (!byPlatform.has(parsed.platform)) byPlatform.set(parsed.platform, [])
-    byPlatform.get(parsed.platform).push(join(dir, name))
+    upsert(byPlatform, parsed.platform, () => []).push(join(dir, name))
   }
   return (platform === null ? undefined : byPlatform.get(platform)) ?? byPlatform.get(null) ?? []
 }
 
-// True if the package at `root` ships native code: an ios/ or android/ dir, or a podspec under it.
+// Whether the package at `root` ships native code: an ios/ or android/ dir, or a podspec under it.
 export function looksNative(root, fs) {
   return fs.stat(join(root, 'ios')) !== null || fs.stat(join(root, 'android')) !== null || hasPodspec(root, fs)
 }
 
-// True if any *.podspec exists under `dir`, pruning the same subtrees the native walk skips.
 function hasPodspec(dir, fs) {
   return listing(dir, fs).some((ent) => !ent.isSymbolicLink() &&
     (ent.isFile() ? isPodspec(ent.name) : ent.isDirectory() && !isSkippedNativeWalkDir(ent.name) && hasPodspec(join(dir, ent.name), fs)))
 }
 
-// The specs React Native's codegen parses in a package's codegen sources (codegenSources), as its own
-// filter takes them (filterJSFile): a JS or TS module named `Native…` or `…NativeComponent` (a platform's
-// `.ios`/`.android` one too), but a type declaration.
+// A spec React Native's codegen parses (its filterJSFile): a JS or TS module named `Native…` or `…NativeComponent`,
+// but a type declaration.
 const isCodegenSpec = (name) => /^(?:Native.+|.+NativeComponent)/u.test(name) && /\.(?:jsx?|tsx?)$/u.test(name) && !name.endsWith('.d.ts')
 
-// Each native build input in the package at `root`, walked whole, a native build reading sources
-// from anywhere in it (a podspec compiling `cpp/` beside `ios/`): every file but build output and
-// prebuilt binaries (isSkippedNativeWalkDir, isNativeArtifact), an off-platform top-level dir
-// (isExcludedNativeDir), what the shared classifier skips (the JS and TS Metro's graph owns, docs,
-// secrets) and symlinks (a cycle or escape hazard). And the specs of its codegen sources
-// (codegenSources, isCodegenSpec), as code with no format, as Metro's code has none: none of the
-// other JS there (a react-native.config.js, the package's build, where `jsSrcsDir` is its root), which
-// codegen never reads. A file `skip(file)` holds is passed over unread. `resources` is the allowlist
-// the byte-level rules consult.
-// -> yields { file, source, action, format }, `action` 'code' (under the source-language `format`,
-// none for JS and TS) or 'resource'
+// Each native build input of the package at `root`, walked whole (a podspec may compile `cpp/` beside `ios/`) but
+// build output, prebuilt binaries, an off-platform top-level dir, symlinks and what the shared classifier skips; and
+// its codegen specs, as code with no format. -> yields { file, source, action: 'code' | 'resource', format }
 export function* nativeInputs(root, fs, { resources = new Set(), skip = () => false } = {}) {
   yield* walk(root, true)
   for (const dir of codegenSources(root, fs)) yield* sources(dir)
   function* sources(dir) {
     for (const ent of listing(dir, fs)) {
-      // None in a dot, node_modules or tests directory, as codegen skips one.
+      // As codegen skips a dot, node_modules or tests directory.
       if (ent.isSymbolicLink() || ent.name.startsWith('.') || ent.name === 'node_modules' || ent.name.startsWith('__tests')) continue
       const file = join(dir, ent.name)
       if (ent.isDirectory()) yield* sources(file)
@@ -173,27 +144,22 @@ export function* nativeInputs(root, fs, { resources = new Set(), skip = () => fa
       const byName = classifyNativeCapture(ent.name)
       if (byName.action === 'skip') continue
       const source = fs.readFile(file)
-      // Byte-level rules (prebuilt binaries, binary plists) -- see refineNativeCapture.
       const { action, format } = refineNativeCapture(byName, ent.name, source, resources)
       if (action !== 'skip') yield { file, source, action, format }
     }
   }
 }
 
-// The directories of the package at `root` its package.json's `codegenConfig` names as its JS sources
-// (`jsSrcsDir`, or each of its `libraries`', as React Native's own names `src`), each reached within it
-// through no symlink, as the walk follows none: React Native's codegen parses the specs there to
-// generate the native code a build compiles (a missing one fails it), and `react-native config` reads
-// them for the components they declare (`codegenNativeComponent`, in a `…NativeComponent` spec).
-// -> the absolute dirs
+// The dirs the package's `codegenConfig` names as its JS sources (`jsSrcsDir`, or each of its `libraries`'), each
+// reached through no symlink, as the walk follows none: codegen parses the specs there for the native code a build
+// compiles, and `react-native config` reads them for the components they declare. -> the absolute dirs
 function codegenSources(root, fs) {
   const config = readJson(join(root, 'package.json'), fs)?.codegenConfig
   const named = [config?.jsSrcsDir, ...(Array.isArray(config?.libraries) ? config.libraries.map((library) => library?.jsSrcsDir) : [])]
   return named.filter((dir) => typeof dir === 'string' && dir !== '').map((dir) => packageDir(root, dir, fs)).filter((dir) => dir !== null)
 }
 
-// The directory `rel` names in the package at `root`, each step of it one (a link's entry is none, and
-// none is `..`). -> its absolute path, or null
+// The directory `rel` names in the package at `root`, each step a directory entry (not a link, not `..`), else null.
 function packageDir(root, rel, fs) {
   let dir = root
   for (const name of relative(root, join(root, rel)).split(sep)) {
@@ -207,10 +173,9 @@ function packageDir(root, rel, fs) {
 // A package name as npm takes one (`name` or `@scope/name`), which a path can't climb out with.
 const PACKAGE_NAME = /^(?:@[^/\\@.][^/\\]*\/)?[^/\\@.][^/\\]*$/u
 
-// The app's packages `react-native config` reads, read as data rather than by running the CLI: each
-// name the app's package.json lists under dependencies, peerDependencies or devDependencies (the
-// CLI's list), in the nearest node_modules up from `projectDir` that holds it (as the CLI looks). What
-// a react-native.config.js changes, being code, isn't seen. -> the package dirs, as found
+// The app's packages `react-native config` reads, as data rather than by running the CLI: each name its package.json
+// lists under dependencies, peerDependencies or devDependencies, in the nearest node_modules up from `projectDir` that
+// holds it. What a react-native.config.js changes, being code, isn't seen. -> the package dirs
 export function linkedPackages(projectDir, fs) {
   const manifest = readJson(join(projectDir, 'package.json'), fs)
   const listed = (field) => (manifest?.[field] && typeof manifest[field] === 'object' ? Object.keys(manifest[field]) : [])
@@ -230,8 +195,7 @@ export function linkedPackages(projectDir, fs) {
   return dirs
 }
 
-// Of those, the ones `react-native config` links, as a native build would: those that ship native
-// code (looksNative). -> the package dirs, as found
+// Those of linkedPackages a native build links: those that ship native code.
 export function linkedNativePackages(projectDir, fs) {
   return linkedPackages(projectDir, fs).filter((dir) => looksNative(dir, fs))
 }

package/src/metro-transformer.js

@@ -7,27 +7,16 @@ 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`
-// whenever stasis attests the build (wire it yourself only alongside a hand-wired serializer). It
-// 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`,
-//    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
-//    hash-verified bytes (fail-closed; out-of-scope files pass their disk bytes through).
-//    KNOWN LIMITATION: does NOT build with sources absent from disk -- Metro reads + hashes each
-//    file before this runs, so the guarantee is "build attested bytes, fail closed on disk drift."
+// The worker half of StasisMetro, wired by withStasis() as `transformerPath` around the project's transformer. It
+// keeps each import as written for the serializer (./metro-babel-transformer.js), and is the LOAD half: a per-worker
+// seam, as load only reads an immutable bundle, replacing Metro's `data` with the bundle's hash-verified bytes. Metro
+// reads and hashes each file before this runs, so sources must stay on disk: attested bytes, fail closed on drift.
 
 const require = createRequire(import.meta.url)
 
-// The project's own transformer, which this one runs: the `transformerPath` withStasis() replaced,
-// handed over in Metro's transformer config, else EXODUS_STASIS_METRO_BASE_TRANSFORMER, else
-// Metro's default. Metro requires a name from its own dir, which only the project's node_modules
-// is sure to reach, so a name resolves from the project root, then from here. A base that is this
-// transformer itself (wired by hand as well) is passed over for Metro's default.
+// The project's transformer: the `transformerPath` withStasis() replaced, else EXODUS_STASIS_METRO_BASE_TRANSFORMER,
+// else Metro's default, a name resolved from the project root first, as Metro requires it from its own dir. This
+// transformer itself (wired by hand as well) means Metro's default.
 const bases = new Map()
 function baseOf(config, projectRoot = process.cwd()) {
   const path = config?.stasisBaseTransformerPath ?? (process.env.EXODUS_STASIS_METRO_BASE_TRANSFORMER || 'metro-transform-worker')
@@ -41,15 +30,10 @@ function baseOf(config, projectRoot = process.cwd()) {
   return bases.get(key)
 }
 
-// The config the project's transformer sees: its own, without what withStasis() handed over.
-function baseConfig({ stasisBaseTransformerPath: _, ...config } = {}) {
-  return config
-}
+const baseConfig = ({ stasisBaseTransformerPath: _, ...config } = {}) => config
 
-// Per-worker load State, built once from the usual env + stasis.config.json. Non-load mode -> null
-// -> 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.
+// The worker's load State, null outside load (a pass-through, so wiring this permanently is safe). A failure is
+// cached and rethrown on every call, never passed through after the first. It never writes, so claims no write path.
 let loaded
 function getLoadState() {
   if (loaded === undefined) {
@@ -64,23 +48,14 @@ function getLoadState() {
   return loaded.state
 }
 
-// The Babel transformer swapped in for the project's, by path as metro-transform-worker requires it.
 const BABEL_TRANSFORMER = fileURLToPath(new URL('./metro-babel-transformer.js', import.meta.url))
 
-// The project's Babel transformer, absolute. Metro resolves a configured one; its default
-// ('metro-babel-transformer') stays a name, which the base transformer requires from its own dir.
-function resolveBabelTransformer(base, path) {
-  return isAbsolute(path) ? path : createRequire(base.file).resolve(path)
-}
+// Metro resolves a configured Babel transformer; its default stays a name, which the base requires from its own dir.
+const resolveBabelTransformer = (base, path) => (isAbsolute(path) ? path : createRequire(base.file).resolve(path))
 
-// 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`.
+// Each dependency as the source wrote it: `stasisAsWritten` where Babel rewrote its specifier (several written apart
+// may be rewritten alike), `stasisInserted` where no specifier in the source names it (a Babel helper, Metro's
+// asyncRequire). The imports a Babel plugin consumed ride on the module's first output's data, as `stasisConsumed`.
 function withAsWritten(result, { asWritten, consumed }) {
   if (!Array.isArray(result?.dependencies)) return result
   const dependencies = result.dependencies.map((dep) => {
@@ -99,11 +74,10 @@ export async function transform(config, projectRoot, filename, data, options) {
   config = baseConfig(config)
   const state = getLoadState()
   if (state) {
-    // `filename` is project-relative in Metro's contract; resolve against projectRoot.
+    // `filename` is project-relative in Metro's contract.
     const absolute = resolvePath(projectRoot, filename)
+    // getFile re-verifies the hash and throws on a file the bundle doesn't carry: no disk fallback.
     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())
       data = Buffer.isBuffer(source) ? source : Buffer.from(source)
     }
@@ -115,10 +89,8 @@ export async function transform(config, projectRoot, filename, data, options) {
   return withAsWritten(result, context)
 }
 
+// The base's key, marked by the load State transform() goes by, so a load result never shares a disk build's entry.
 export function getCacheKey(config, opts) {
-  // Fold in the base transformer's cache key, then add a stasis-load discriminator so load results
-  // (which can differ from a disk build even when disk == bundle) don't cross-pollinate the cache.
-  // Derive the marker from the resolved load State, which transform() goes by.
   const { transformer } = baseOf(config, opts?.projectRoot)
   const baseKey = typeof transformer.getCacheKey === 'function' ? transformer.getCacheKey(baseConfig(config), opts) : ''
   const state = getLoadState()