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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.15",
+  "version": "1.0.0-beta.16",
   "description": "Bundler plugins (webpack, esbuild, Rollup, Metro) for @exodus/stasis-core",
   "type": "module",
   "exports": {
@@ -36,6 +36,6 @@
   },
   "homepage": "https://github.com/PreventiveMeasures/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.15"
+    "@exodus/stasis-core": "1.0.0-beta.16"
   }
 }

package/src/esbuild.js

@@ -1,44 +1,31 @@
-import { isUtf8 } from 'node:buffer'
 import { dirname, extname, isAbsolute, join, relative, resolve as resolvePath } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import assert from 'node:assert/strict'
 
 import { Bundle } from '@exodus/stasis-core/bundle'
-import { attestedImport, resolvePluginState, unsupportedExtension } from './plugins.js'
+import { assertCodeUtf8, assertPersistableAttributes, attestedImport, ownOrResolvedState, rebuildRefused, unsupportedExtension } from './plugins.js'
 import { State } from '@exodus/stasis-core/state'
 // Pre-patch snapshot, not `import { readFile }`: under --fs=async that builtin is patched, and
 // this plugin loads after, so a direct import would route esbuild's reads through the capture hook.
 import { realReadFile } from '@exodus/stasis-core/state-util'
-import { EMPTY_MODULE_PATH, classifyExtension } from '@exodus/stasis-core/util'
+import { EMPTY_MODULE_PATH, classifyExtension, upsert } from '@exodus/stasis-core/util'
 
-// The build options esbuild's resolver reads, replayed into the disabled-import probe so it
-// resolves exactly as the build does.
+// The build options esbuild's resolver reads, replayed into the disabled-import probe.
 const RESOLVE_OPTIONS = ['absWorkingDir', 'alias', 'conditions', 'external', 'mainFields', 'nodePaths',
   'packages', 'platform', 'preserveSymlinks', 'resolveExtensions', 'tsconfig', 'tsconfigRaw']
 
 // One import of `specifier` as `kind` would issue it, as the probe's stdin.
 function probeSource(specifier, kind) {
   const quoted = JSON.stringify(specifier)
-  switch (kind) {
-    case 'require-call':
-    case 'require-resolve':
-      return { contents: `require(${quoted})`, loader: 'js' }
-    case 'dynamic-import':
-      return { contents: `import(${quoted})`, loader: 'js' }
-    case 'import-rule':
-    case 'composes-from':
-      return { contents: `@import ${quoted};`, loader: 'css' }
-    case 'url-token':
-      return { contents: `a { b: url(${quoted}) }`, loader: 'css' }
-    default:
-      return { contents: `import ${quoted}`, loader: 'js' }
-  }
+  if (kind === 'require-call' || kind === 'require-resolve') return { contents: `require(${quoted})`, loader: 'js' }
+  if (kind === 'dynamic-import') return { contents: `import(${quoted})`, loader: 'js' }
+  if (kind === 'import-rule' || kind === 'composes-from') return { contents: `@import ${quoted};`, loader: 'css' }
+  if (kind === 'url-token') return { contents: `a { b: url(${quoted}) }`, loader: 'css' }
+  return { contents: `import ${quoted}`, loader: 'js' }
 }
 
-// A `browser` map key or a path to test against one, loosened past esbuild's matching (it tries a
-// path bare, plus each resolve extension, plus `/index`, with or without './'): no './' or `.`
-// segments, every extension stripped, trailing index segments dropped. Equal loose keys are a
-// SUPERSET of esbuild's matches -- only a probe decides.
+// A `browser` map key or a path, loosened past esbuild's matching (bare, plus each resolve extension, plus `/index`,
+// with or without './'): equal loose keys are a SUPERSET of esbuild's matches -- only a probe decides.
 function looseBrowserKey(path) {
   const parts = path.replaceAll('\\', '/').split('/').filter((part) => part !== '' && part !== '.')
   while (parts.length > 0) {
@@ -58,7 +45,7 @@ async function browserFalseKeys(dir) {
   try {
     pkg = JSON.parse(await realReadFile(join(dir, 'package.json'), 'utf8'))
   } catch {
-    return new Set() // no (readable) package.json: no map
+    return new Set()
   }
   const browser = pkg?.browser
   if (browser === null || typeof browser !== 'object' || Array.isArray(browser)) return new Set()
@@ -73,40 +60,25 @@ export class StasisEsbuild {
   #transform
   #resource
   #platform
-  #emptyModule  // URL of the empty module disabled imports point at, once capture recorded it
-  #browserScopes = new Map()  // dir -> Promise<[{ dir, keys }]>: `false` keys of it and its ancestors
-  #probes = new Map()  // [kind, resolveDir, specifier] -> Promise<disabled path | null>
-
-  // Build starts observed by this instance (across rebuilds and separate build()/context() calls);
-  // the second is refused in onStart.
+  #emptyModule // URL of the empty module disabled imports point at, once capture recorded it
+  #browserScopes = new Map() // dir -> Promise<[{ dir, keys }]>: `false` keys of it and its ancestors
+  #probes = new Map() // [kind, resolveDir, specifier] -> Promise<disabled path | null>
   #captureBuildCount = 0
 
+  // Only for load mode: `loaders` per-extension overrides (RN's '.js' -> 'jsx'), `transform(source, { path, loader })`
+  // a code rewrite (`stasis build --platform=hermes`), `resource(source, { path })` a module for a resource no loader
+  // names (`stasis build --metro`'s asset module), `platform` the one a --metro per-platform edge resolves for.
   constructor(options = {}, { loaders, transform, resource, platform } = {}) {
-    // A caller that owns a State (e.g. `stasis build`) can pass it directly; a foreign-copy State
-    // fails closed via the instanceof miss.
-    const state = options instanceof State
-      ? options
-      : resolvePluginState('StasisEsbuild', options, process.cwd()).state
-    this.#state = state  // null when plugin should be inert
-    // Cache the resolved resources Set for the per-file classify hot path.
+    const state = ownOrResolvedState('StasisEsbuild', options)
+    this.#state = state
     this.#resources = state?.config.resources ?? new Set()
-    // Per-extension esbuild loader overrides (e.g. { '.js' -> 'jsx' } for RN's JSX-in-.js),
-    // keyed by extname with the dot; falls back to #loaderFor.
     this.#loaders = loaders ?? new Map()
-    // Load-mode-only code rewrite hook (e.g. `stasis build --platform=hermes` downleveling):
-    // (source, { path, loader }) => { contents, loader } | undefined, may be async. Never
-    // runs at capture -- capture attests the file's raw bytes.
     this.#transform = transform
-    // Load-mode-only module builder for a resource no loader override names (e.g. `stasis build
-    // --metro`'s asset module): (source, { path }) => { contents, loader } | undefined, may be async.
     this.#resource = resource
-    // Load mode: the platform whose target a --metro per-platform edge resolves to (none fails
-    // closed on one, as plain bundle=load does).
     this.#platform = platform
   }
 
-  // esbuild loader for a served file: configured override, else derived from extension
-  // (.cjs/.mjs/.cts/.mts strip their module letter to js/ts).
+  // A configured override, else from the extension (.cjs/.mjs/.cts/.mts drop their module letter).
   #loaderFor(path) {
     const ext = extname(path)
     return this.#loaders.get(ext) ?? ext.replace(/^\.[cm]?/u, '')
@@ -116,22 +88,19 @@ export class StasisEsbuild {
     return 'stasis'
   }
 
-  // Every directory from `dir` up whose package.json `browser` map disables something, nearest first.
-  // esbuild consults only the nearest `browser` map, so this is a superset.
+  // Every directory from `dir` up whose `browser` map disables something, nearest first: a superset, as esbuild
+  // consults only the nearest map.
   #browserFalseScopes(dir) {
-    let scopes = this.#browserScopes.get(dir)
-    if (scopes === undefined) {
+    return upsert(this.#browserScopes, dir, () => {
       const parent = dirname(dir)
-      scopes = Promise.all([browserFalseKeys(dir), parent === dir ? [] : this.#browserFalseScopes(parent)])
+      return Promise.all([browserFalseKeys(dir), parent === dir ? [] : this.#browserFalseScopes(parent)])
         .then(([keys, above]) => (keys.size > 0 ? [{ dir, keys }, ...above] : above))
-      this.#browserScopes.set(dir, scopes)
-    }
-    return scopes
+    })
   }
 
-  // Whether some `browser` map `false` entry could match this resolution: the resolved path (and, for
-  // a relative specifier, the path it names) under each map's dir, or a bare specifier as is or as
-  // './<importer dir>/<specifier>' (a Browserify quirk esbuild keeps).
+  // Whether some `browser` map `false` entry could match this resolution: the resolved path (and, for a relative
+  // specifier, the path it names) under each map's dir, or a bare specifier as is or as './<importer dir>/<specifier>'
+  // (a Browserify quirk esbuild keeps).
   async #mayBeDisabled(path, specifier, resolveDir) {
     const isPackagePath = !isAbsolute(specifier) && !/^\.\.?(?:\/|$)/u.test(specifier) && !specifier.startsWith('/')
     const paths = isPackagePath ? [path] : [path, resolvePath(resolveDir, specifier)]
@@ -144,16 +113,13 @@ export class StasisEsbuild {
     })
   }
 
-  // esbuild's own verdict: a one-import build from the importer's dir with the build's resolve options
-  // and every load stubbed empty, whose metafile still names a disabled module `(disabled):<path>`.
-  // -> that path (absolute), or null when esbuild doesn't disable the import.
+  // esbuild's own verdict: a one-import build with the build's resolve options and every load stubbed empty, whose
+  // metafile still names a disabled module `(disabled):<path>`. -> that path (absolute), or null
   #probeDisabled(specifier, kind, resolveDir, { esbuild, initialOptions }) {
-    const key = JSON.stringify([kind, resolveDir, specifier])
-    let probe = this.#probes.get(key)
-    if (probe === undefined) {
+    return upsert(this.#probes, JSON.stringify([kind, resolveDir, specifier]), () => {
       const options = Object.fromEntries(RESOLVE_OPTIONS.filter((k) => initialOptions[k] !== undefined).map((k) => [k, initialOptions[k]]))
       const cwd = initialOptions.absWorkingDir ?? process.cwd()
-      probe = esbuild.build({
+      return esbuild.build({
         ...options,
         stdin: { ...probeSource(specifier, kind), resolveDir },
         bundle: true,
@@ -166,94 +132,71 @@ export class StasisEsbuild {
         if (!found?.startsWith('(disabled):')) return null
         return resolvePath(cwd, found.slice('(disabled):'.length))
       }, () => null)
-      this.#probes.set(key, probe)
-    }
-    return probe
+    })
   }
 
-  // A `browser` field mapping this import to `false` makes esbuild resolve it to an empty "disabled"
-  // module, but its resolve API drops that flag: a bare name comes back as a namespace-less path, a
-  // file as its plain path. The file case is confirmed by a probe, and only where a `false` entry
-  // could match (browser platform, see #mayBeDisabled).
+  // A `browser` field `false` makes esbuild resolve an import to an empty "disabled" module, but its resolve API
+  // drops that flag: a bare name comes back namespace-less, a file as its plain path, which a probe confirms where a
+  // `false` entry could match.
   async #isDisabled(res, specifier, { kind, resolveDir }, build) {
     if (res.external) return false
-    if (res.namespace === '') return true // only a disabled bare name resolves to no namespace
+    if (res.namespace === '') return true
     if (res.namespace !== 'file' || (build.initialOptions.platform ?? 'browser') !== 'browser') return false
     if (!(await this.#mayBeDisabled(res.path, specifier, resolveDir))) return false
-    // Compare the paths: a sibling plugin may have resolved the import to something else entirely.
+    // A sibling plugin may have resolved the import to something else entirely.
     return (await this.#probeDisabled(specifier, kind, resolveDir, build)) === res.path
   }
 
   setup = ({ onResolve, onLoad, onStart, onEnd, resolve, initialOptions, esbuild }) => {
-    if (!this.#state) return  // noop plugin
+    if (!this.#state) return
+    const emptyModuleURL = pathToFileURL(resolvePath(this.#state.root, EMPTY_MODULE_PATH)).toString()
 
-    // Watch/rebuild capture is unsupported: dedupe is keyed by PATH not content, so a rebuild with
-    // changed bytes would emit new bytes while the bundle/lockfile keep the OLD ones. Rebuilds re-fire
-    // onStart against the same registrations, so an instance counter catches the second and errors.
+    // Rebuilds re-fire onStart against the same registrations.
     if (!this.#state.config.loadBundle) {
       onStart(() => {
         this.#captureBuildCount += 1
-        if (this.#captureBuildCount === 1) return undefined
-        return {
-          errors: [{
-            text: 'StasisEsbuild: watch/rebuild is not supported for capture -- run a one-shot build (rebuilds would silently attest stale content)',
-          }],
-        }
+        return this.#captureBuildCount === 1 ? undefined : { errors: [{ text: rebuildRefused('StasisEsbuild') }] }
       })
     }
 
-    // The preload writes itself (hooks.js); standalone/sidecar States are written on build finish --
-    // only on a clean build (a partial one would overwrite the user's good file).
+    // The preload writes itself; a failed build mustn't overwrite the user's good file.
     if (this.#state !== State.preload) {
       onEnd((result) => {
-        if (result.errors.length > 0) return
-        this.#state.write()
+        if (result.errors.length === 0) this.#state.write()
       })
     }
 
-    // Load mode: resolution comes from the bundle's import map, not esbuild's resolver -- the file
-    // may not be on disk. Keep namespace:'file' with the original absolute path (esbuild doesn't stat
-    // plugin-returned paths) so output bytes -- banners, asset names, source maps -- match a capture build.
+    // Load mode resolves through the bundle's import map: the file may not be on disk. namespace 'file' with the
+    // original path (esbuild doesn't stat a plugin's) keeps the output (banners, asset names, maps) a capture's.
     onResolve({ filter: /$/ }, ({ path: specifier, importer, kind: resolveKind, with: attrs }) => {
       if (!this.#state.config.loadBundle) return undefined
       const isEntry = resolveKind === 'entry-point'
       let url
       if (isEntry) {
-        // Bare/relative entries are anchored to cwd (like the run loader), so the file needn't be on disk.
-        url = specifier.startsWith('file:')
-          ? specifier
-          : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
+        // Anchored to cwd, as the run loader does, so the file needn't be on disk.
+        url = specifier.startsWith('file:') ? specifier : pathToFileURL(resolvePath(process.cwd(), specifier)).toString()
         if (this.#state.config.full) this.#state.assertEntry(url)
       } else {
+        // Looked up even for a built-in's name: a browser build records `fs` where a `browser` field disables it or a
+        // package by that name serves it. KNOWN GAP: a Node-loader-captured bundle keys an attributed edge under
+        // specific conditions, which this `*` lookup won't match.
         const parentURL = pathToFileURL(importer).toString()
-        // Forward import attributes (`with { type: 'json' }`) so plugin-capture round-trips to
-        // plugin-load, both keyed under `* (with: ...)`. KNOWN GAP: a Node-loader-captured bundle
-        // keys attributed edges under specific conditions the plugin's `*` lookup won't match.
-        // The edge is looked up even for a built-in's name: a browser build records `fs` when a
-        // `browser` field disables it (an edge to the empty module) or a package by that name serves it.
-        // No attested edge (a built-in, or another external): esbuild's, which externalizes it as
-        // without us (built-ins under platform:'node'). File BYTES still fail closed at onLoad.
         const attested = attestedImport(this.#state, parentURL, specifier, { importAttributes: attrs, platform: this.#platform })
         if (attested === undefined) return undefined
         ;({ url } = attested)
       }
       const format = this.#state.getFormat(url)
-      const isEmpty = url === pathToFileURL(resolvePath(this.#state.root, EMPTY_MODULE_PATH)).toString()
-      const kind = isEmpty ? 'empty' : Bundle.isResourceFormat(format) ? 'resource' : 'code'
+      const kind = url === emptyModuleURL ? 'empty' : Bundle.isResourceFormat(format) ? 'resource' : 'code'
       return { path: fileURLToPath(url), namespace: 'file', pluginData: { isEntry, kind } }
     })
 
     onResolve({ filter: /$/, namespace: 'file' }, async ({ path: specifier, with: attrs, ...args }) => {
       const isEntry = !args.importer
-
-      // Recurse with a synthetic namespace so esbuild's default resolver runs without re-entering us
+      // A synthetic namespace runs esbuild's own resolver without re-entering this hook.
       const res = await resolve(specifier, { ...args, with: attrs, namespace: 'stasis' })
-      // A miss is esbuild's to report -- or to tolerate, as it does a require() in a try/catch (debug's
-      // optional supports-color). Decline so it re-resolves exactly as without us; no edge.
+      // A miss is esbuild's to report, or tolerate (a require() in a try/catch): decline, recording no edge.
       if (res.errors.length > 0) return undefined
-      // A disabled import (`browser` field `false`): returning `res` would bundle the real file or fail
-      // on a bare name, so decline and let esbuild re-resolve it into its own empty module. Capture
-      // points the edge at the attested empty module, which is what bundle=load serves.
+      // Declined, esbuild re-resolves a disabled import into its own empty module, the attested one bundle=load serves.
       if (!isEntry && await this.#isDisabled(res, specifier, args, { esbuild, initialOptions })) {
         if (!this.#state.config.loadBundle) {
           this.#emptyModule ??= this.#state.addEmptyModule({ reason: 'esbuild' })
@@ -261,8 +204,6 @@ export class StasisEsbuild {
         }
         return undefined
       }
-      // A non-empty `suffix` (some CSS-modules plugins set one) can't be persisted to the bundle,
-      // so refuse it rather than silently dropping it at capture.
       assert.equal(res.suffix, '',
         `StasisEsbuild: a sibling plugin set res.suffix='${res.suffix}' on '${specifier}'; ` +
         `stasis can't persist suffixes to the bundle. Disable that plugin or drop suffix from its resolve result.`)
@@ -270,77 +211,46 @@ export class StasisEsbuild {
       let kind = 'skip'
       if (res.namespace === 'file' && !res.external) {
         kind = classifyExtension(res.path, this.#resources)
-        if (kind === 'unknown') {
-          return { errors: [{ text: unsupportedExtension('StasisEsbuild', `'${res.path}'`) }] }
-        }
-        // Record the edge for BOTH code and resource targets (never entries): load mode resolves
-        // every specifier through this map, so a resource with no edge would miss at bundle=load and
-        // fall through to esbuild's disk resolver -- serving the asset UNATTESTED. kind is code|resource here.
-        if (!isEntry) {
-          const parentURL = pathToFileURL(args.importer).toString()
-          const url = pathToFileURL(res.path).toString()
-          // Forward import attributes symmetrically with load: addImport keys by attributes so
-          // getImport finds the same edge.
-          this.#state.addImport(parentURL, specifier, url, { importAttributes: attrs })
-        }
+        if (kind === 'unknown') return { errors: [{ text: unsupportedExtension('StasisEsbuild', `'${res.path}'`) }] }
+        // Resources too: load mode resolves every specifier through this map, so one with no edge would fall through
+        // to esbuild's disk resolver, unattested.
+        const url = pathToFileURL(res.path).toString()
+        if (!isEntry) this.#state.addImport(pathToFileURL(args.importer).toString(), specifier, url, { importAttributes: attrs })
       }
-
       return { ...res, pluginData: { ...res.pluginData, isEntry, kind } }
     })
 
     onLoad({ filter: /$/, namespace: 'file' }, async ({ path, pluginData, with: attrs }) => {
       const kind = pluginData?.kind ?? 'skip'
       if (kind === 'skip') return undefined
-      // Accept only the `type` import attribute; other attributes aren't persistable to the lockfile yet.
-      for (const k of Object.keys(attrs)) {
-        assert.equal(k, 'type', `unsupported import attribute: ${k}`)
-      }
+      assertPersistableAttributes(attrs)
 
-      // Load mode: serve bytes the bundle attested. getFile verifies the hash and throws on a file
-      // the bundle doesn't carry -- a missing in-scope file is a hard error, not a disk fallback.
+      // getFile verifies the hash and throws on a file the bundle doesn't carry: no disk fallback.
       if (this.#state.config.loadBundle) {
         const { source } = this.#state.getFile(pathToFileURL(path).toString())
-        // A disabled import's stand-in gets esbuild's own loader for disabled modules: `empty` is the
-        // one a CSS @import, `composes` or url() accepts, so one empty module serves JS and CSS importers.
+        // esbuild's own loader for disabled modules, which a CSS @import, `composes` or url() accepts too.
         if (kind === 'empty') return { contents: source, loader: 'empty' }
         if (kind === 'resource') {
-          // A loader override for its extension (`stasis build --loader=.png:dataurl`) wins; else the
-          // resource hook's module, where it builds one.
           const override = this.#loaders.get(extname(path))
           if (override) return { contents: source, loader: override }
           const built = await this.#resource?.(source, { path })
           if (built) return built
-          // Else the loader esbuild's own load path takes (the build's `loader` option, else its default
-          // for the extension), so a resource none loads fails as at capture, not parsed as js.
+          // The build's own loader for it, so a resource none loads fails as at capture, not parsed as js.
           return { contents: source, loader: 'default' }
         }
         const loader = this.#loaderFor(path)
-        // A transform that declines (undefined) serves the attested bytes unchanged.
-        const transformed = await this.#transform?.(source, { path, loader })
-        return transformed ?? { contents: source, loader }
+        return (await this.#transform?.(source, { path, loader })) ?? { contents: source, loader }
       }
 
       const source = await realReadFile(path)
-
-      if (kind === 'resource') {
-        // Mark as a resource (State picks 'resource' vs 'resource:base64' from bytes). Return no
-        // contents/loader: emission is esbuild's job via the build's own `loader` config.
-        if (!this.#seen.has(path)) {
-          this.#seen.add(path)
-          this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, resource: true, reason: 'esbuild' })
-        }
-        return undefined
-      }
-
-      // Code-classified files must be UTF-8; refuse non-UTF-8 rather than silently encode as a resource.
-      assert.ok(isUtf8(source), `StasisEsbuild: code-classified file has non-UTF-8 bytes: ${path}`)
-
+      const resource = kind === 'resource'
+      if (!resource) assertCodeUtf8('StasisEsbuild', path, source)
       if (!this.#seen.has(path)) {
         this.#seen.add(path)
-        this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, reason: 'esbuild' })
+        this.#state.addFile(pathToFileURL(path).toString(), { source, isEntry: pluginData?.isEntry, resource, reason: 'esbuild' })
       }
-
-      return { contents: source, loader: this.#loaderFor(path) }
+      // A resource is emitted by esbuild, through the build's own `loader` config.
+      return resource ? undefined : { contents: source, loader: this.#loaderFor(path) }
     })
   }
 }

package/src/metro-babel-transformer.js

@@ -2,30 +2,21 @@ import assert from 'node:assert/strict'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { createRequire } from 'node:module'
 
-// Stands in for the project's Babel transformer (`babelTransformerPath`) under ./metro-transformer.js,
-// which swaps it in for each worker transform, to keep each import as WRITTEN in the source. Metro
-// names a dependency by the specifier Babel leaves in its output, so a plugin rewriting it (e.g.
-// babel-plugin-module-resolver mapping `#local/abc` to `./src/abc`) leaves the serializer only the
-// rewrite. This adds one plugin that records every specifier in its `pre` -- Babel runs every
-// plugin's `pre` before any plugin's visitor, so nothing has rewritten one yet -- and reads each
-// again once Babel is done, before Metro's own passes replace them in the AST, but one importing
-// types alone that Babel erased. One a plugin consumed, gone from Babel's output with nothing left
-// naming its module (`require('./messages.po')`, which @exodus/i18n's plugin-inline-po reads and
-// inlines), it keeps apart. The real transformer runs as it would; its output is untouched.
+// Stands in for the project's Babel transformer under ./metro-transformer.js, to keep each import as WRITTEN: Metro
+// names a dependency by the specifier Babel leaves, so a rewrite (babel-plugin-module-resolver's) would leave it only
+// that. An added plugin records each specifier in its `pre` (Babel runs every `pre` before any visitor) and reads it
+// again once Babel is done; one a plugin consumed, with nothing left naming its module, is kept apart.
 
 const require = createRequire(import.meta.url)
 
-// One per worker transform, run by ./metro-transformer.js: `babelTransformerPath` is the project's
-// (absolute), `asWritten` maps each specifier Babel left to the ones written there, and `consumed`
-// holds each one a plugin consumed, as Babel last left it.
+// Per worker transform: `babelTransformerPath` the project's, `asWritten` each specifier Babel left -> the ones
+// written, and `consumed` each one a plugin consumed, as Babel last left it.
 export const transformContext = new AsyncLocalStorage()
 
-// The nodes Metro's collectDependencies takes a specifier from: these declarations, and the calls
-// below (`import()`, `require()`, `__prefetchImport()`, `require.<member>()`).
+// The nodes Metro's collectDependencies takes a specifier from.
 const DECLARATIONS = new Set(['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'])
 const REQUIRE_MEMBERS = new Set(['context', 'resolveWeak', 'unstable_importMaybeSync'])
 
-// Whether `node` is one of them.
 function isDependency(node) {
   if (node.type !== 'CallExpression') return DECLARATIONS.has(node.type)
   const { callee } = node
@@ -36,8 +27,7 @@ function isDependency(node) {
     callee.property.type === 'Identifier' && REQUIRE_MEMBERS.has(callee.property.name)
 }
 
-// The string `node` holds as a constant: a literal, a template with no substitutions, or a `+` of
-// such, which Metro's collectDependencies evaluates to the specifier as it does a literal.
+// A literal, a template with no substitutions, or a `+` of such, which collectDependencies evaluates as a literal.
 function constantString(node) {
   if (node?.type === 'StringLiteral') return node.value
   if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) return node.quasis[0].value.cooked ?? undefined
@@ -47,25 +37,19 @@ function constantString(node) {
   return right === undefined ? undefined : left + right
 }
 
-// The specifier a dependency node holds as a constant: an import/export's source, a call's first
-// argument. A plugin rewriting it replaces the literal, never the node holding it.
-function specifierOf(node) {
-  return constantString(node.type === 'CallExpression' ? node.arguments[0] : node.source)
-}
+// A plugin rewriting a specifier replaces the literal, never the node holding it.
+const specifierOf = (node) => constantString(node.type === 'CallExpression' ? node.arguments[0] : node.source)
 
 const TYPE_KINDS = new Set(['type', 'typeof'])
 
-// A declaration of types alone, which Babel may erase, and then it names no module Metro depends on:
-// Flow's `import type`/`import typeof`, TypeScript's `import type`, `export type ... from`, and one
-// whose every specifier is a type (`import { type A }`, which TypeScript's `onlyRemoveTypeImports`
-// keeps as `import {} from`).
+// A declaration of types alone, which Babel may erase: Flow's or TypeScript's `import type`, `export type ... from`,
+// or one whose every specifier is a type (which TypeScript's `onlyRemoveTypeImports` keeps as `import {} from`).
 function typesOnly(node) {
   if (TYPE_KINDS.has(node.importKind ?? node.exportKind)) return true
   const specifiers = node.specifiers ?? []
   return specifiers.length > 0 && specifiers.every((specifier) => TYPE_KINDS.has(specifier.importKind ?? specifier.exportKind))
 }
 
-// The dependency nodes in Babel's output, and the specifiers they hold as constants.
 function dependenciesLeft(t, ast) {
   const nodes = new Set()
   const specifiers = new Set()
@@ -92,8 +76,8 @@ function asWrittenPlugin({ types: t }) {
         if (written !== undefined) slots.push({ node, written, types: node.type !== 'CallExpression' && typesOnly(node) })
         else if (node.type === 'CallExpression' && node.arguments.length > 0) evaluate = true
       })
-      // Metro takes any argument Babel evaluates to a string with confidence, one bound to a constant
-      // too (`const name = './x'; require(name)`), which only a path, and its scope, can evaluate.
+      // Metro also takes an argument Babel evaluates to a string with confidence (`const name = './x'; require(name)`),
+      // which only a path, with its scope, can evaluate.
       if (!evaluate) return
       file.path.traverse({
         CallExpression(path) {
@@ -104,10 +88,8 @@ function asWrittenPlugin({ types: t }) {
       })
     },
     visitor: {
-      // Babel exits a node only if no plugin removed it on the way in, so a declaration of types
-      // alone that Babel erased never exits: flow-strip-types removes it as it enters it, the TS
-      // plugin before the traversal gets there. One it kept (`import {} from` under
-      // `onlyRemoveTypeImports`) exits, still naming its module.
+      // Babel exits a node only if no plugin removed it on the way in, so a types-only declaration it erased never
+      // exits; one it kept (`import {} from`) does, still naming its module.
       'ImportDeclaration|ExportNamedDeclaration|ExportAllDeclaration': {
         exit(path) {
           transformContext.getStore().kept.add(path.node)
@@ -123,12 +105,9 @@ export function transform(args) {
   const slots = []
   const kept = new Set()
   Object.assign(context, { slots, kept })
-  // Once Babel is done: each specifier as it left it, from the node that held it as written, but a
-  // declaration of types alone Babel erased. One a plugin replaced keeps it too: lowered to a require
-  // (the commonjs transform), or split in two (`export * as ns from` into an import and an export,
-  // the export-namespace-from transform), it names the same module, its specifier as rewritten
-  // before (module-resolver rewrites every one as the program enters). One gone from the output,
-  // with no node there naming its module, a plugin consumed in its stead.
+  // Each specifier as Babel left it in the node that held it as written, but an erased types-only declaration's. A
+  // node a plugin replaced (lowered to a require, or split in two) names the same module, its specifier as rewritten
+  // before; one gone from the output with no node there naming its module was consumed.
   const collect = (result) => {
     const left = result?.ast && context.types ? dependenciesLeft(context.types, result.ast) : null
     for (const { node, written, types } of slots) {
@@ -144,7 +123,7 @@ export function transform(args) {
     }
     return result
   }
-  // Sync or async, as the project's transformer is (the RN one is sync).
+  // Sync or async, as the project's transformer is.
   const result = require(context.babelTransformerPath).transform({ ...args, plugins: [...(args.plugins ?? []), asWrittenPlugin] })
   return typeof result?.then === 'function' ? result.then(collect) : collect(result)
 }