@exodus/stasis 1.0.0-beta.1 → 1.0.0-beta.3

package/src/cmd/build.js

@@ -7,41 +7,29 @@ import { spawnSync } from 'node:child_process'
 import { Bundle } from '@exodus/stasis-core/bundle'
 import { State } from '@exodus/stasis-core/state'
 import { StasisEsbuild } from '@exodus/stasis-plugins/esbuild'
+import { HERMES_UNSUPPORTED, createBabelConfigTransform, createHermesTransform } from '../babel.js'
 import { bundleFromLockfile } from '../bundle-from-lockfile.js'
 import { parseFileWithKind } from '../parse.js'
 
-// Re-exported so `@exodus/stasis/cmd/build` keeps surfacing the lockfile->bundle
-// reconstruction alongside the command; the implementation lives in its own module.
 export { bundleFromLockfile }
 
-// JS/TS entry extensions esbuild can build. esbuild handles JSX/TSX natively (loader
-// 'jsx'/'tsx', derived from the extension by the load plugin), and stasis-core already
-// classifies .jsx/.tsx as code (CODE_EXTENSIONS), so a bundle/lockfile captured by the
-// esbuild/webpack plugins can carry them as entries.
 const JS_EXTS = new Set(['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts', '.jsx', '.tsx'])
 
-// Allowlist (NOT a blocklist) of per-file formats `stasis build` accepts in an artifact:
-// the JS/TS/JSON code formats esbuild builds, plus the non-code payload formats
-// (resource/directory) that are inert unless the SELECTED entry imports them. An allowlist
-// so a new language format added to `stasis bundle` later (e.g. a future `go`) is rejected
-// here by default, rather than slipping through to a cryptic esbuild failure in the build.
+// Allowlist (not blocklist) of per-file formats `stasis build` accepts, so a bundle
+// format added later fails closed here rather than in a cryptic esbuild error.
 const BUILDABLE_FORMATS = new Set([
   'module', 'commonjs', 'json', 'module-typescript', 'commonjs-typescript',
-  'resource', 'resource:base64', 'directory',
+  'resource', 'resource:base64', 'directory', 'stat:file', 'stat:directory',
 ])
 
-// esbuild is an OPTIONAL peer dependency: `stasis build` is the only command that
-// needs a bundler, so we don't force every stasis install to pull one in. Resolve it
-// from the local install first (a peer dep hoisted into the project's node_modules, or
-// an npx-provided copy), then fall back to a global install, with an actionable error
-// if neither is present.
+// esbuild is an optional peer dep; resolve it from the local install, else fall back
+// to a global one.
 async function importEsbuild() {
   let mod
   try {
     mod = await import('esbuild')
   } catch (cause) {
-    // Only a genuine "not installed" miss falls through to the global lookup; a
-    // different failure (a corrupt install, a syntax error in esbuild) is surfaced.
+    // Only a genuine "not installed" miss falls through to the global lookup; surface other failures.
     if (cause?.code !== 'ERR_MODULE_NOT_FOUND' && cause?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
       throw cause
     }
@@ -56,14 +44,10 @@ async function importEsbuild() {
     }
     mod = await import(pathToFileURL(globalMain).href)
   }
-  // esbuild ships a CJS module exposing named exports (build, context, ...); Node's
-  // interop surfaces them directly. A globally-imported CJS copy may instead land its
-  // exports on `default` -- accept both shapes.
+  // A globally-imported CJS copy may land its exports on `default` -- accept both shapes.
   return typeof mod.build === 'function' ? mod : mod.default
 }
 
-// Locate a globally-installed esbuild via the package managers' "global root" commands.
-// Returns the absolute path to esbuild's entry, or undefined when none is installed.
 function resolveGlobalEsbuild() {
   const probes = [
     ['npm', ['root', '-g']],
@@ -75,7 +59,7 @@ function resolveGlobalEsbuild() {
     try {
       out = spawnSync(cmd, args, { encoding: 'utf8' })
     } catch {
-      continue // package manager not installed
+      continue
     }
     if (!out || out.status !== 0 || !out.stdout) continue
     const base = out.stdout.trim()
@@ -87,61 +71,77 @@ function resolveGlobalEsbuild() {
       try {
         return createRequire(join(nm, 'noop.js')).resolve('esbuild')
       } catch {
-        // keep probing
       }
     }
   }
   return undefined
 }
 
-// Validate that an artifact is something esbuild can build: full scope (node_modules
-// scope omits the entry and workspace code, so it can't be built on its own), at least
-// one entry, all entries JS/TS, and only buildable per-file formats (see BUILDABLE_FORMATS).
-function assertBuildable(artifact, label) {
+// Preconditions independent of which entry we build. Per-entry language checks are deferred
+// to assertBuildableEntry, once selectEntry has picked one.
+function assertBuildableArtifact(artifact, label) {
   if (artifact.config.scope !== 'full') {
     throw new Error(
       `stasis build requires a full-scope artifact; ${label} is scope='${artifact.config.scope}'. ` +
       `node_modules-scope artifacts omit the entry and workspace code, so there is nothing to build.`
     )
   }
-  const entries = [...artifact.entries]
-  if (entries.length === 0) {
+  if (artifact.entries.size === 0) {
     throw new Error(`stasis build: ${label} declares no entries to build`)
   }
-  for (const entry of entries) {
-    if (!JS_EXTS.has(extname(entry))) {
-      throw new Error(`stasis build only builds JavaScript/TypeScript entries (esbuild); got non-JS entry '${entry}' in ${label}`)
+}
+
+// The entry plus its transitive imports in the recorded graph -- the exact set esbuild loads
+// (all conditions buckets; a --metro edge's per-platform targets included).
+function reachableFiles(entry, imports) {
+  const seen = new Set([entry])
+  const stack = [entry]
+  while (stack.length > 0) {
+    const parent = stack.pop()
+    for (const [, byParent] of imports) {
+      const specifiers = byParent.get(parent)
+      if (specifiers === undefined) continue
+      for (const [, target] of specifiers) {
+        // A plain edge is a file string; a --metro edge is a {platform: file} Map.
+        const targets = typeof target === 'string' ? [target] : [...target.values()]
+        for (const file of targets) {
+          if (!seen.has(file)) {
+            seen.add(file)
+            stack.push(file)
+          }
+        }
+      }
     }
   }
-  // artifact.formats is a Map (Bundle) or may be null on a legacy lockfile (an absent map
-  // is fine -- nothing to check). Reject any format outside the allowlist: the non-JS
-  // LANGUAGE bundlers' formats (Solidity/PHP/Bash/Rust) and anything added later.
-  //
-  // NOTE: resource formats are IN the allowlist -- deliberately NOT rejected here. A resource
-  // is recorded as a FILE but never as an import EDGE, so whether a build hits one depends on
-  // the SELECTED entry's own source, not the artifact as a whole -- a code-only entry must
-  // build even when the artifact carries assets for OTHER entries. An entry that does import
-  // an asset fails at build time (esbuild can't resolve the un-graphed resource).
+  return seen
+}
+
+// Language checks scoped to the built entry: it must be JS/TS, and every file reachable from
+// it must be buildable. A non-JS file elsewhere (another entry, or a `stasis add` attachment)
+// isn't reached, so it doesn't block the build. imports/formats are null on a legacy lockfile.
+function assertBuildableEntry(artifact, entry, label) {
+  if (!JS_EXTS.has(extname(entry))) {
+    throw new Error(`stasis build only builds JavaScript/TypeScript entries (esbuild); got non-JS entry '${entry}' in ${label}`)
+  }
+  const reachable = reachableFiles(entry, artifact.imports ?? new Map())
+  // A reachable resource (plugin captures DO record asset edges) stays allowed via BUILDABLE_FORMATS;
+  // an entry that imports an unbuildable asset fails later at esbuild, not here.
   for (const [file, format] of artifact.formats ?? new Map()) {
+    if (!reachable.has(file)) continue
     if (!BUILDABLE_FORMATS.has(format)) {
       throw new Error(`stasis build only supports JavaScript/TypeScript bundles (esbuild); ${label} carries a '${format}' file (${file})`)
     }
   }
 }
 
-// Pick which recorded entry to build. The build produces exactly one entry's bundle;
-// `entryArg` selects it. With a single recorded entry the selector is optional (that
-// entry is used); with several it is required, and an absent or unknown one is rejected
-// with the available list. The selector is matched against the artifact's recorded
-// (project-relative) entries -- only those are attested as graph roots, and the load
-// plugin's assertEntry rejects anything else -- accepting the recorded path verbatim, a
-// leading `./` stripped, or a cwd-relative path normalized into the project root.
+// Pick which recorded entry to build; required only when several are recorded. Matched
+// against the recorded project-relative entries (verbatim, `./`-stripped, or cwd-relative).
 function selectEntry(entryArg, entries, { cwd, root, label }) {
   const recorded = [...entries]
   const list = recorded.map((e) => `  ${e}`).join('\n')
   if (entryArg === undefined) {
     if (recorded.length === 1) return recorded[0]
-    // length === 0 is impossible here (assertBuildable required >= 1 entry).
+    // length === 0 is impossible here (assertBuildableArtifact required >= 1 entry).
     throw new Error(`stasis build: ${label} has ${recorded.length} entry points; pass one as the second argument:\n${list}`)
   }
   const candidates = new Set([
@@ -156,13 +156,8 @@ function selectEntry(entryArg, entries, { cwd, root, label }) {
   return match
 }
 
-// Build a bundle-load State that serves an in-memory Bundle -- the same shape StasisEsbuild's
-// load path reads from (state.sources / state.resources / state.formats / state.imports /
-// state.entries). skipDiscovery anchors the State at `root` and does NO filesystem discovery:
-// no package.json walk, no on-disk config, no stray stasis.code.br read. bundle=load +
-// lock=ignore serve the bundle's own bytes (self-attesting -- the lockfile path already
-// SHA-512-verified them in bundleFromLockfile). We mirror State's on-disk load (split
-// sources/resources by format) and fill the maps from `bundle`.
+// Build a bundle-load State that serves an in-memory Bundle. skipDiscovery does NO
+// filesystem discovery (no package.json walk, no on-disk config, no stray stasis.code.br).
 function loadStateForBundle(root, bundle) {
   const state = new State(root, { bundle: 'load', lock: 'ignore', scope: bundle.config.scope, skipDiscovery: true })
   const sources = new Map()
@@ -176,50 +171,23 @@ function loadStateForBundle(root, bundle) {
   state.formats = bundle.formats
   state.imports = bundle.imports
   state.entries = new Set(bundle.entries)
-  // Not state.modules: the load path (getImport/getFile/getFormat/assertEntry) never reads
-  // it -- it's only written by the capture paths. The State's empty-Map default stands.
+  // Not state.executable either: like state.modules below, the load path never reads it, and every
+  // consumer narrows against state.modules -- which is empty here -- so copying it would be inert.
+  // Not state.modules: the load path never reads it (only the capture paths write it).
   return state
 }
 
-// Run the `stasis build` CLI command end-to-end: take a stasis artifact (a `stasis.code.br`
-// bundle, or a `stasis.lock.json` lockfile whose attested files are read + verified from
-// disk) and an entry point, and run esbuild over that one entry, following the artifact's
-// recorded import graph EXACTLY rather than esbuild's own resolver.
-//
-// `entry` selects which recorded entry to build (see selectEntry): optional when the
-// artifact records one, required when it records several. `output` is required: a path
-// ending in `.js`/`.cjs`/`.mjs` writes a single file, anything else a directory.
-//
-// The build runs entirely in memory off the artifact -- no temp files, and no package.json
-// required. The artifact's relative paths anchor at the artifact's OWN directory: a bundle is
-// self-contained (root is just a keying prefix; nothing is read from disk), and a lockfile
-// records its paths relative to where it sits (its project root), so its sources are read +
-// verified from there. A project stasis.config.json is not consulted -- the build is driven
-// by the artifact, not by `stasis run` config.
-//
-// The recorded graph is forced via the stasis esbuild plugin in bundle-load mode: each import
-// resolves to the edge stasis recorded (a specifier the artifact doesn't record is handed back
-// to esbuild, which externalizes it like a built-in/`external`), and each module's bytes come
-// from the artifact -- so the output reflects what stasis attested, not what's on disk.
-//
-// `format` (esm/cjs/iife, default esm), `platform` (node/browser/neutral, default node),
-// `minify`, `sourcemap`, `define` (an esbuild define map), `external` (an array of esbuild
-// external patterns), and `loader` (an esbuild extension->loader map, e.g. { '.js': 'jsx' }
-// to parse JSX in .js files) are forwarded to esbuild; the import graph is fixed by the artifact.
-//
-// `external` is esbuild's native option: it only steers specifiers esbuild itself would
-// resolve -- i.e. the ones the bundle does NOT record (handed back to esbuild as a miss,
-// typically the externals that existed at capture time). It re-declares those so esbuild
-// leaves them as runtime imports instead of trying (and failing) to resolve them on disk.
-// A specifier the artifact DOES record is still followed from the artifact -- the recorded
-// graph wins, so `external` never silently un-inlines an attested edge.
+// Run `stasis build`: run esbuild over one recorded entry, following the artifact's
+// recorded import graph EXACTLY (not esbuild's resolver). A specifier the artifact records
+// is always followed from the artifact; `external` only steers the specifiers it doesn't.
 export async function buildCommand({
   cwd = process.cwd(),
   artifact,
   entry,
   output,
-  format = 'esm',
+  format,
   platform = 'node',
+  babel = false,
   minify = false,
   sourcemap = false,
   define = {},
@@ -229,36 +197,43 @@ export async function buildCommand({
   if (!artifact) throw new Error('stasis build: an artifact (bundle or lockfile) is required')
   if (!output) throw new Error('stasis build: --output is required (a .js/.cjs/.mjs file, or a directory)')
   if (!Array.isArray(external)) throw new Error('stasis build: external must be an array of esbuild patterns')
+  // --platform=hermes is a stasis-level target, not an esbuild platform (esbuild gets
+  // 'neutral'): every code file is downleveled to Hermes' dialect before the final bundle,
+  // and the bundle itself must avoid ESM -- Hermes has no import/export.
+  const hermes = platform === 'hermes'
+  format ??= hermes ? 'iife' : 'esm'
+  if (hermes && format === 'esm') {
+    throw new Error('stasis build: --platform=hermes cannot emit ESM (Hermes has no import/export); use --format=iife (the hermes default) or cjs')
+  }
   const artifactAbs = resolve(cwd, artifact)
   const { kind, artifact: parsed } = parseFileWithKind(artifactAbs)
-  assertBuildable(parsed, artifact)
+  assertBuildableArtifact(parsed, artifact)
 
-  // Anchor the artifact's relative paths at the artifact's OWN directory. A bundle is
-  // self-contained (root is just a keying prefix; nothing is read from disk), and a lockfile
-  // records its paths relative to where it sits -- its project root -- so its sources are
-  // read + verified from there. No package.json discovery, no project stasis.config.json.
+  // Anchor artifact-relative paths at the artifact's own directory; a lockfile's sources
+  // are read + verified from there.
   const root = dirname(artifactAbs)
   const selectedEntry = selectEntry(entry, parsed.entries, { cwd, root, label: artifact })
+  assertBuildableEntry(parsed, selectedEntry, artifact)
 
-  // The Bundle the load State serves, entirely in memory. A bundle artifact is already a
-  // parsed Bundle; a lockfile is reconstructed into one by reading + SHA-512-verifying its
-  // attested files from disk (bundleFromLockfile). The plugin drives off the in-memory State.
   const bundle = kind === 'lockfile' ? bundleFromLockfile(parsed, { root }) : parsed
   const state = loadStateForBundle(root, bundle)
-  // The selected entry is project-relative in the artifact; make it absolute against the
-  // State's root so esbuild's entry resolution is independent of the process cwd.
+  // Make the entry absolute against the State's root so resolution is independent of process cwd.
   const entryPoint = resolve(state.root, selectedEntry)
 
   const esbuild = await importEsbuild()
+  // Per-file code rewrites the plugin applies before esbuild parses a served file:
+  // --babel runs the project's own babel.config.* over the original source (no esbuild
+  // pre-transform), and otherwise --platform=hermes uses the built-in downlevel pipeline.
+  // Both resolve Babel from the project (cwd), never from stasis's own dependencies.
+  let transform
+  if (babel) transform = createBabelConfigTransform({ projectDir: cwd })
+  else if (hermes) transform = createHermesTransform({ projectDir: cwd, esbuild })
+
   const outAbs = resolve(cwd, output)
-  // A `.js`/`.cjs`/`.mjs` --output names a single output file; anything else is a directory.
   const asFile = /\.[cm]?js$/u.test(output)
-  // Absolute paths the artifact attests -- esbuild must NEVER overwrite one. A stray
-  // `--output=src/x.js` (or `--output=src`/`.` whose computed output basename collides with a
-  // recorded source) would otherwise destroy an attested file: esbuild's own "refusing to
-  // overwrite input file" check fires only AFTER it has written, and for a lockfile that
-  // permanently breaks the file's hash. So we build with write:false and write the outputs
-  // ourselves, refusing -- before touching disk -- to clobber any recorded file.
+  // Never overwrite a file the artifact attests: esbuild's own overwrite check fires only
+  // after writing (corrupting a lockfile's hash), so we build write:false and refuse to
+  // clobber any recorded file before touching disk.
   const attested = new Set([...state.sources.keys(), ...state.resources.keys()].map((f) => resolve(state.root, f)))
 
   let result
@@ -268,24 +243,21 @@ export async function buildCommand({
       absWorkingDir: state.root,
       bundle: true,
       write: false,
-      platform,
+      platform: hermes ? 'neutral' : platform,
       format,
       logLevel: 'silent',
+      ...(hermes ? { supported: HERMES_UNSUPPORTED } : {}),
       ...(minify ? { minify: true } : {}),
       ...(sourcemap ? { sourcemap: true } : {}),
       ...(external.length > 0 ? { external } : {}),
       ...(Object.keys(define).length > 0 ? { define } : {}),
       ...(asFile ? { outfile: outAbs } : { outdir: outAbs }),
-      // Per-extension loader overrides drive the stasis plugin's load-mode loader choice
-      // (the plugin serves and labels every in-bundle file, so esbuild's own `loader`
-      // option never sees them). e.g. { '.js': 'jsx' } to parse JSX in .js files.
-      plugins: [new StasisEsbuild(state, { loaders: new Map(Object.entries(loader)) })],
+      // Loader overrides go through the plugin: it serves every in-bundle file, so esbuild's
+      // own `loader` option never sees them. e.g. { '.js': 'jsx' } to parse JSX in .js files.
+      plugins: [new StasisEsbuild(state, { loaders: new Map(Object.entries(loader)), transform })],
     })
   } catch (err) {
-    // esbuild rejects with a BuildFailure carrying a formatted `.errors` array under
-    // logLevel:'silent'. Surface those (rather than the bare wrapper) so the user sees the
-    // actual resolve/load failure -- including an entry that imports an un-buildable asset
-    // -- then fail the command.
+    // Under logLevel:'silent' esbuild puts the real errors on err.errors; surface them, then fail.
     if (Array.isArray(err?.errors) && err.errors.length > 0) {
       const formatted = await esbuild.formatMessages(err.errors, { kind: 'error', color: false })
       for (const line of formatted) process.stderr.write(line)
@@ -294,9 +266,7 @@ export async function buildCommand({
     throw err
   }
 
-  // The build succeeded. Refuse to clobber an attested source -- checked against esbuild's
-  // ACTUAL output paths (so it covers both `--output` file and directory), BEFORE any write,
-  // so a rejected build leaves every recorded file intact.
+  // Refuse to clobber an attested source, checked against esbuild's actual output paths before any write.
   for (const file of result.outputFiles) {
     if (attested.has(file.path)) {
       throw new Error(