@exodus/stasis-plugins 1.0.0-beta.8 → 1.0.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/stasis-plugins",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-rc.0",
   "description": "Bundler plugins (webpack, esbuild, Rollup, Metro) for @exodus/stasis-core",
   "type": "module",
   "exports": {
@@ -8,11 +8,14 @@
     "./esbuild": "./src/esbuild.js",
     "./rollup": "./src/rollup.js",
     "./metro": "./src/metro.js",
-    "./metro-transformer": "./src/metro-transformer.js"
+    "./metro-transformer": "./src/metro-transformer.js",
+    "./metro-native": "./src/metro-native.js"
   },
   "files": [
     "src/esbuild.js",
     "src/metro.js",
+    "src/metro-babel-transformer.js",
+    "src/metro-native.js",
     "src/metro-transformer.js",
     "src/plugins.js",
     "src/rollup.js",
@@ -33,6 +36,6 @@
   },
   "homepage": "https://github.com/PreventiveMeasures/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.8"
+    "@exodus/stasis-core": "1.0.0-rc.0"
   }
 }

package/src/esbuild.js

@@ -1,16 +1,56 @@
-import { isUtf8 } from 'node:buffer'
-import { isBuiltin } from 'node:module'
-import { extname, resolve as resolvePath } from 'node:path'
+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 { resolvePluginState } 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 { 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.
+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)
+  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, 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) {
+    const stem = parts.at(-1).replace(/\..*$/su, '')
+    if (stem !== 'index' || parts.length === 1) {
+      parts[parts.length - 1] = stem
+      break
+    }
+    parts.pop()
+  }
+  return parts.join('/')
+}
+
+// The loose keys a directory's package.json `browser` map sends to `false` (esbuild's "disabled").
+async function browserFalseKeys(dir) {
+  let pkg
+  try {
+    pkg = JSON.parse(await realReadFile(join(dir, 'package.json'), 'utf8'))
+  } catch {
+    return new Set()
+  }
+  const browser = pkg?.browser
+  if (browser === null || typeof browser !== 'object' || Array.isArray(browser)) return new Set()
+  return new Set(Object.keys(browser).filter((key) => browser[key] === false).map((key) => looseBrowserKey(key)))
+}
 
 export class StasisEsbuild {
   #seen = new Set()
@@ -18,31 +58,27 @@ export class StasisEsbuild {
   #resources
   #loaders
   #transform
-
-  // Build starts observed by this instance (across rebuilds and separate build()/context() calls);
-  // the second is refused in onStart.
+  #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>
   #captureBuildCount = 0
 
-  constructor(options = {}, { loaders, transform } = {}) {
-    // 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.
+  // 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 } = {}) {
+    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
+    this.#resource = resource
+    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, '')
@@ -52,77 +88,122 @@ export class StasisEsbuild {
     return 'stasis'
   }
 
-  setup = ({ onResolve, onLoad, onStart, onEnd, resolve, initialOptions }) => {
-    if (!this.#state) return  // noop plugin
+  // Every directory from `dir` up whose `browser` map disables something, nearest first: a superset, as esbuild
+  // consults only the nearest map.
+  #browserFalseScopes(dir) {
+    return upsert(this.#browserScopes, dir, () => {
+      const parent = dirname(dir)
+      return Promise.all([browserFalseKeys(dir), parent === dir ? [] : this.#browserFalseScopes(parent)])
+        .then(([keys, above]) => (keys.size > 0 ? [{ dir, keys }, ...above] : above))
+    })
+  }
+
+  // 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)]
+    const dirs = new Set([resolveDir, ...paths.map((p) => dirname(p))])
+    const scopes = (await Promise.all([...dirs].map((dir) => this.#browserFalseScopes(dir)))).flat()
+    return scopes.some((scope) => {
+      const candidates = paths.map((p) => relative(scope.dir, p))
+      if (isPackagePath) candidates.push(specifier, join(relative(scope.dir, resolveDir), specifier))
+      return candidates.some((candidate) => scope.keys.has(looseBrowserKey(candidate)))
+    })
+  }
+
+  // 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 }) {
+    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()
+      return esbuild.build({
+        ...options,
+        stdin: { ...probeSource(specifier, kind), resolveDir },
+        bundle: true,
+        write: false,
+        metafile: true,
+        logLevel: 'silent',
+        plugins: [{ name: 'stasis-probe', setup: (build) => build.onLoad({ filter: /$/ }, () => ({ contents: '', loader: 'empty' })) }],
+      }).then(({ metafile }) => {
+        const found = metafile.inputs['<stdin>']?.imports.find((i) => i.original === specifier)?.path
+        if (!found?.startsWith('(disabled):')) return null
+        return resolvePath(cwd, found.slice('(disabled):'.length))
+      }, () => null)
+    })
+  }
 
-    // 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.
+  // 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
+    if (res.namespace !== 'file' || (build.initialOptions.platform ?? 'browser') !== 'browser') return false
+    if (!(await this.#mayBeDisabled(res.path, specifier, resolveDir))) return false
+    // 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
+    const emptyModuleURL = pathToFileURL(resolvePath(this.#state.root, EMPTY_MODULE_PATH)).toString()
+
+    // 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
-      // Built-ins are never bundled or recorded as edges; hand them back to esbuild (undefined)
-      // so it externalizes under platform:'node', rather than getImport throwing ERR_MODULE_NOT_FOUND.
-      if (isBuiltin(specifier)) 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.
-        try {
-          ;({ url } = this.#state.getImport(parentURL, specifier, { importAttributes: attrs }))
-        } catch (err) {
-          // No attested edge -- at a successful capture that's an EXTERNAL (never recorded as an
-          // edge), so hand it back to esbuild. File BYTES still fail closed at onLoad.
-          // A non-MODULE_NOT_FOUND error is a real fault -- rethrow.
-          if (err?.code === 'ERR_MODULE_NOT_FOUND') return undefined
-          throw err
-        }
+        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 kind = 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' })
-      if (res.errors.length > 0) return res
-      // 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.
+      // 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
+      // 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' })
+          this.#state.addImport(pathToFileURL(args.importer).toString(), specifier, this.#emptyModule, { importAttributes: attrs })
+        }
+        return undefined
+      }
       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.`)
@@ -130,74 +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: `StasisEsbuild: unsupported extension for '${res.path}' -- add its extension or filename to the plugin's resources option or stop importing it`,
-            }],
-          }
-        }
-        // 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())
+        // 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') {
-          // Plugin-provided contents with no `loader` default to `js` (esbuild applies the build's
-          // per-extension loader only on its own load path), so replay the configured loader from
-          // initialOptions.loader. No configured loader fails symmetrically with a capture build.
-          const loader = initialOptions.loader?.[extname(path)]
-          return loader ? { contents: source, loader } : { contents: source }
+          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
+          // 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

@@ -0,0 +1,129 @@
+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 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)
+
+// 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.
+const DECLARATIONS = new Set(['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'])
+const REQUIRE_MEMBERS = new Set(['context', 'resolveWeak', 'unstable_importMaybeSync'])
+
+function isDependency(node) {
+  if (node.type !== 'CallExpression') return DECLARATIONS.has(node.type)
+  const { callee } = node
+  if (callee.type === 'Import') return true
+  if (callee.type === 'Identifier') return callee.name === 'require' || callee.name === '__prefetchImport'
+  return callee.type === 'MemberExpression' && !callee.computed &&
+    callee.object.type === 'Identifier' && callee.object.name === 'require' &&
+    callee.property.type === 'Identifier' && REQUIRE_MEMBERS.has(callee.property.name)
+}
+
+// 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
+  if (node?.type !== 'BinaryExpression' || node.operator !== '+') return undefined
+  const left = constantString(node.left)
+  const right = left === undefined ? undefined : constantString(node.right)
+  return right === undefined ? undefined : left + right
+}
+
+// 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: 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))
+}
+
+function dependenciesLeft(t, ast) {
+  const nodes = new Set()
+  const specifiers = new Set()
+  t.traverseFast(ast, (node) => {
+    if (!isDependency(node)) return
+    nodes.add(node)
+    const specifier = specifierOf(node)
+    if (specifier !== undefined) specifiers.add(specifier)
+  })
+  return { nodes, specifiers }
+}
+
+function asWrittenPlugin({ types: t }) {
+  return {
+    name: 'stasis-as-written',
+    pre(file) {
+      const context = transformContext.getStore()
+      context.types = t
+      const { slots } = context
+      let evaluate = false
+      t.traverseFast(file.ast, (node) => {
+        if (!isDependency(node)) return
+        const written = specifierOf(node)
+        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 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) {
+          if (!isDependency(path.node) || specifierOf(path.node) !== undefined || path.node.arguments.length === 0) return
+          const { confident, value } = path.get('arguments.0').evaluate()
+          if (confident && typeof value === 'string') slots.push({ node: path.node, written: value })
+        },
+      })
+    },
+    visitor: {
+      // 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)
+        },
+      },
+    },
+  }
+}
+
+export function transform(args) {
+  const context = transformContext.getStore()
+  assert.ok(context, 'StasisMetro: the stasis Babel transformer runs only under the stasis metro-transformer')
+  const slots = []
+  const kept = new Set()
+  Object.assign(context, { slots, kept })
+  // 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) {
+      if (types && !kept.has(node)) continue
+      // One evaluated through its scope stays as written: no plugin rewrites what isn't a literal.
+      const specifier = specifierOf(node) ?? written
+      if (left !== null && !left.nodes.has(node) && !left.specifiers.has(specifier)) {
+        context.consumed.add(specifier)
+        continue
+      }
+      if (!context.asWritten.has(specifier)) context.asWritten.set(specifier, new Set())
+      context.asWritten.get(specifier).add(written)
+    }
+    return result
+  }
+  // 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)
+}